The .claude/ directory appears to be fully protected by permissions. The plan is complete — let me present it directly since I can't write to the pipeline artifacts directory.

---

Replace polling-based PAT authentication with a GitHub App that provides native Checks API integration, webhook-driven issue processing, and first-class PR reviews. The GitHub App authenticates via JWT + installation tokens, receives webhooks instead of polling, and creates check runs with full Shipwright branding.

The system supports both PAT (via gh CLI) and GitHub App authentication. A new sw-github-app.sh module provides the GitHub App auth layer. All existing GitHub API modules gain a thin abstraction to route API calls through either auth path. This avoids a big-bang migration — users adopt the GitHub App incrementally.

Key Decision: We use openssl (available on macOS and Linux) for JWT generation — no external dependencies. The gh CLI remains the primary API transport; for GitHub App auth we set the GH_TOKEN env var with the installation token so all gh api calls "just work."

---

File	Purpose
scripts/sw-github-app.sh	GitHub App auth: JWT generation, installation token management, token refresh
scripts/sw-github-webhook.sh	Webhook HTTP receiver (bash + socat/nc server)
scripts/sw-github-app-test.sh	Unit tests for GitHub App auth module
scripts/sw-github-webhook-test.sh	Unit tests for webhook receiver
templates/github-app-manifest.json	GitHub App manifest for one-click app creation

File	Change
scripts/sw-github-checks.sh	Add app auth detection, enhance check run output
scripts/sw-github-graphql.sh	Add dual auth abstraction
scripts/sw-daemon.sh	Add webhook mode, import app module, token refresh
scripts/sw-pipeline.sh	App-aware PR creation, bot reviews
scripts/sw-doctor.sh	Section 13: validate GitHub App config
scripts/sw	Add app and webhook command routing
.claude/daemon-config.json	Add github_app config section
package.json	Add 2 new test suites
.claude/CLAUDE.md	Document new modules and config

---

• gh_app_configured() — Check credentials (env vars or daemon-config.json)
• gh_app_generate_jwt() — RS256 JWT via openssl, cached ~9 min
• gh_app_get_installation_token() — Exchange JWT for installation token
• gh_app_ensure_token() — Lifecycle management, exports GH_TOKEN
• gh_app_auth_mode() — Returns "app" or "pat"
• CLI: setup (guided config) and status (show auth info)

• HTTP server via socat/nc, configurable port (default 3456)
• HMAC-SHA256 signature verification (mandatory)
• Event handlers: issues, pull_request, check_suite, push
• webhook_start/stop/status lifecycle management
• Rate limiting (10 events/sec)

• Source app module, call gh_app_ensure_token() before API calls
• Add external_id, structured output, action buttons when in app mode

• Source app/webhook modules (~line 48)
• Load github_app.* config in daemon_load_config()
• Webhook mode replaces polling in daemon_poll_loop()
• Token refresh in health loop
• New daemon webhook start/stop/status subcommand

• App-aware PR creation in stage_pr() (bot identity)
• Enhanced PR body with check run links
• App-authenticated reviewer selection

• Validate private key, JWT generation, token retrieval
• Report auth mode, webhook port availability

• Router: app|github-app → sw-github-app.sh, webhook → sw-github-webhook.sh
• Config: github_app.{app_id, installation_id, private_key_file, webhook_mode, webhook_port, webhook_secret}
• App manifest: checks:write, issues:read, pull_requests:write, contents:read, metadata:read

• sw-github-app-test.sh: JWT, tokens, config, setup, status
• sw-github-webhook-test.sh: signatures, routing, lifecycle, rate limiting

• Update CLAUDE.md: modules table, config, runtime state, feature flags

---

• Task 1: Create sw-github-app.sh — JWT generation, token management, setup/status CLI
• Task 2: Create sw-github-webhook.sh — HTTP listener, signature verification, event routing
• Task 3: Modify sw-github-checks.sh — App auth detection, token refresh, enhanced output
• Task 4: Modify sw-daemon.sh — Source modules, webhook mode, token refresh, daemon webhook subcommand
• Task 5: Modify sw-pipeline.sh — App-aware PR creation, bot reviews
• Task 6: Modify sw-doctor.sh — GitHub App validation in section 13
• Task 7: Modify scripts/sw — Add app and webhook commands
• Task 8: Create templates/github-app-manifest.json — Permissions and webhook events
• Task 9: Create sw-github-app-test.sh — Auth module unit tests
• Task 10: Create sw-github-webhook-test.sh — Webhook receiver unit tests
• Task 11: Update package.json — Add 2 test suites to test chain
• Task 12: Update .claude/CLAUDE.md — Document modules, config, runtime state
• Task 13: Run npm test — Verify no regressions, all new tests pass

---

• New suites: Mock openssl, gh api, socat/nc with canned responses per existing harness pattern
• Regression: All 22 existing suites pass (changes guarded behind gh_app_configured())
• Integration: Manual test with real GitHub App on test repo
• NO_GITHUB=true continues to disable all GitHub API calls including app auth

• shipwright app setup and shipwright app status work correctly
• shipwright doctor validates GitHub App config when present
• Check runs appear with app identity in GitHub UI
• shipwright webhook start launches verified HTTP listener
• shipwright daemon start with webhook_mode: true uses webhooks
• PR reviews show [bot] badge
• All 24 test suites pass (22 existing + 2 new)
• Fully backward compatible without GitHub App configured
• No Bash 3.2 compatibility violations
• Documentation updated