@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/templates/default/.cursor/rules/commits.mdc

@@ -0,0 +1,88 @@
+---
+alwaysApply: true
+description: "Conventional Commits for consumer apps"
+tags: ["commits", "git", "conventional-commits"]
+globs: ["**/*"]
+---
+
+# Commit Conventions
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) for clarity in review and history. If you wire in a release automation later (Changesets, release-please, semantic-release), it will read these prefixes — but the convention is useful on its own even without one.
+
+## Format
+
+```
+<type>(<scope>): <short description>
+
+<optional body — explain WHY, not WHAT>
+
+<optional footer — BREAKING CHANGE: ..., refs: ...>
+```
+
+## Types
+
+| Type | Use for |
+|---|---|
+| `feat` | new user-facing feature |
+| `fix` | bug fix |
+| `feat!` / `BREAKING CHANGE:` footer | breaking change |
+| `docs` | documentation only |
+| `style` | whitespace, formatting (no behavior change) |
+| `refactor` | code change without behavior change |
+| `perf` | performance fix |
+| `test` | test additions / changes |
+| `build` | build system, deps |
+| `ci` | CI / workflow / pipeline changes |
+| `chore` | tooling, internal cleanup |
+| `revert` | reverting a prior commit |
+
+If you adopt a release automation that reads commit types (e.g. release-please), `feat:` → minor, `fix:`/`perf:` → patch, `feat!:` → major. Otherwise these are descriptive only.
+
+## Scope
+
+Optional. Use the area of the change. Common scopes for ShipAPI apps:
+
+- `(api)` / `(routes)` / `(modules)` — module surface changes
+- `(db)` — schema, migrations, queries
+- `(auth)` — authentication or permissions
+- `(jobs)` — BullMQ jobs / cron
+- `(test)` — when type is `chore` / `refactor` and only tests change
+
+Skip the scope when it's not informative — a one-word commit needs no scope.
+
+## Examples
+
+```
+feat(api): add POST /posts/:id/publish
+
+Endpoint already gates on posts:publish permission and emits a
+post.published outbox event for the notifications worker.
+
+---
+
+fix(auth): refresh token rotation no longer races on logout
+
+The refresh table delete and new-token insert ran in separate
+transactions; concurrent logout + refresh could double-spend a
+token. Wrap both in withTransaction.
+
+---
+
+ci: skip e2e suite on docs-only PRs
+
+paths-ignore was matching .md files but not the docs/ tree.
+
+---
+
+feat!(api): drop /v1/* routes; clients must move to /v2/*
+
+BREAKING CHANGE: Endpoints under /v1/ have been removed. See
+docs/MIGRATION_V1_TO_V2.md for the field-by-field map.
+```
+
+## Don't
+
+- Don't use `git commit --amend` after pushing — it rewrites history and breaks anyone who pulled.
+- Don't `--no-verify`. If a hook fails, fix the underlying issue. Bypassing hooks is how secrets get committed.
+- Don't write multi-paragraph commit bodies for trivial changes. The body should add information the diff doesn't.
+- Don't reference internal ticket IDs in the title — the body is fine, but titles get rendered in CHANGELOG.

package/templates/default/.cursor/rules/security.mdc

@@ -0,0 +1,92 @@
+---
+alwaysApply: true
+description: "Security guidelines for ShipAPI v4 apps"
+tags: ["security", "authentication", "authorization"]
+globs: ["modules/**/*.ts", "src/index.ts", "src/environment.ts"]
+---
+
+# Security Guidelines
+
+## Authentication
+
+ShipAPI v4 uses a pluggable `AuthProvider` interface. The default adapter is `FirebaseAuthProvider`; v4.x will add Better-Auth / Clerk / WorkOS / Auth.js adapters.
+
+### Token verification
+
+- Bearer tokens (Authorization header or session cookie) are verified by the configured `AuthProvider`.
+- The framework's `JwtAuthFlow` issues stateless ES256 JWT cookies (`httpOnly, secure, sameSite=lax`) plus a `refresh_tokens` table for revocation.
+- **Never disable signature verification.** Don't bypass the provider chain "for tests" — use a `MockAuthProvider` adapter instead.
+
+### Middleware
+
+- `requireAuth({ provider })` — rejects with 401 if no valid token. Set `optional: true` only for routes that have a public + authenticated mode.
+- `requirePermission(slug)` — rejects with 403 if the resolved account lacks the slug.
+- **Authorization runs at the route, not the controller.** Always chain `requireAuth → requirePermission` on protected routes. The framework's `ship-reviewer` plugin agent flags missing chains.
+
+### Permission slugs
+
+- Format: `module:resource:action` (e.g., `posts:create`, `accounts:list`, `billing:invoice:read`).
+- Define as constants in `modules/<name>/permissions.ts`. Reference the constant from both `requirePermission(slug)` and any seed-data inserts.
+- Permissions are durable — adding new ones is fine, renaming or removing one needs a migration plan.
+
+### Secrets
+
+- **No hardcoded fallbacks** in `src/environment.ts`. `defineEnv(zodSchema)` fail-fasts at boot — that's the design. A boot failure is preferable to running on an attacker-known default.
+- Never commit `.env` files. The template's `.env.example` is the only env file checked in.
+- Rotate `JWT_SIGNING_KEY` per the framework's documented procedure (add new key to `JWT_VERIFICATION_KEYS` first, cut signing over, wait > max token lifetime, remove old key).
+
+## Input validation
+
+- All request input goes through Zod via `validate("json"|"query"|"param", schema)`. Read with `c.req.valid(...)`.
+- Use `.strict()` on object schemas to reject unknown fields — defense against parameter-injection accidents and forward-compat bugs.
+- Validate at the boundary; don't re-validate inside services.
+
+### Webhooks
+
+- Webhook routes (`POST /webhooks/<provider>`) need raw-body signature verification. Use `parseWebhook(c, { provider, secret })` — handles Stripe, GitHub, Slack, Twilio out of the box; pluggable via the `WebhookVerifier` interface for custom providers.
+- Don't apply `validate("json", ...)` before signature verification — Zod consuming the body breaks the raw-body contract some signatures depend on.
+
+### File uploads
+
+- Use `parseUpload(c, schema)` from the framework — Web Standards FormData with magic-byte MIME validation via `file-type`.
+- Be aware that uploads are buffered in memory up to `bodyLimit` (default 25 MB) before the handler runs. For large files, drop to `c.req.raw.body` and pipe directly to a `StorageService` adapter.
+- Always validate MIME via magic bytes, not the Content-Type header (which clients control).
+
+## CSRF
+
+- **Default**: `httpOnly, secure, sameSite=lax` cookies + automatic Origin / Sec-Fetch-Site checking on mutating requests. Protects against top-level navigation CSRF.
+- **Hardened mode**: `csrf({ doubleSubmit: true })` middleware adds an `X-CSRF-Token` double-submit cookie. Opt in for third-party-iframed apps or multi-subdomain consumers.
+
+## Rate limit
+
+- `rateLimit({ windowMs, max, keyGenerator, scope })` — Redis-backed sliding window. Apply to login / signup / password-reset / any endpoint where unauthenticated retry is cheap.
+- **Default fail-mode is fail-closed** when Redis is unavailable. Override with `onRedisUnavailable: 'allow'` only with a deliberate threat-model decision.
+- Emits RFC-draft `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Policy` headers.
+
+## SQL injection
+
+- Drizzle uses parameterized queries by default — `eq(table.col, userInput)` is safe.
+- Don't drop to raw SQL via `sql\`...\${input}...\`` with user input interpolated. If you need raw SQL, parameterize via `sql.placeholder` or build the string from a constant whitelist.
+
+## Logging
+
+- Sensitive fields are redacted by pino's redaction list: `authorization`, `cookie`, `*.password`, `*.token`, `firebaseCredentials`.
+- **Never `console.log` user PII or secrets.** `console.*` bypasses redaction; use `logger`.
+- Don't log full request bodies on routes that accept secrets (login, password reset, payment intent).
+
+## WebSocket auth
+
+- The framework uses subprotocol-header authentication: client opens `new WebSocket(url, ['ship-api.v1', \`bearer.${token}\`])`. Server reads `Sec-WebSocket-Protocol`, runs the same `AuthProvider` chain as `requireAuth`, rejects the upgrade with 401 if invalid.
+- Don't auth via URL `?token=...` — leaks into access logs. Don't auth via first-message handshake — creates "connected but unauthenticated" footgun.
+
+## Audit
+
+- `audit-ci` runs in CI and hard-fails on `high` / `critical` findings. Don't `--allow-list` a high finding without a tracking issue + remediation date.
+- Run `npm run audit` locally before opening a PR that bumps deps.
+
+## When in doubt
+
+- Default to fail-closed.
+- Default to validating at boundaries.
+- Default to using the framework's middleware factories rather than rolling your own.
+- If a security-relevant change feels surprising, check `docs/V4_LAUNCH.md` and the framework's `.cursor/rules/security.mdc` for the intended pattern.

package/templates/default/.cursor/rules/testing.mdc

@@ -0,0 +1,123 @@
+---
+alwaysApply: true
+description: "Vitest testing patterns for ShipAPI v4 apps"
+tags: ["testing", "vitest"]
+globs: ["src/**/*.test.ts", "tests/**/*.ts"]
+---
+
+# Testing Guidelines
+
+## Framework
+
+[Vitest](https://vitest.dev). The template ships with `vitest` configured; run with `npm test`.
+
+- `npm test` — full run.
+- `npm test -- --watch` — watch mode for active development.
+- `npm test -- --changed` — only re-run tests whose source-of-truth changed since `main`.
+- `npm test -- modules/<name>` — module-scoped run.
+
+## Test file co-location
+
+Co-locate unit tests with the code under test:
+
+```
+modules/posts/
+├── services/PostService.ts
+├── services/PostService.test.ts        # service unit tests
+├── routes.ts
+└── routes.test.ts                      # route integration tests
+```
+
+Integration tests that span modules live under `tests/integration/`.
+
+## Service unit tests (fake DB)
+
+For service-level tests, mock the DB at the lowest level — you're testing service logic, not Drizzle:
+
+```ts
+import { describe, it, expect, vi } from "vitest";
+import { PostService } from "./PostService";
+
+describe("PostService", () => {
+  it("filters out soft-deleted rows by default", async () => {
+    const fakeDb = { query: { posts: { findMany: vi.fn().mockResolvedValue([]) } } };
+    const service = new PostService(fakeDb as any);
+    await service.list({});
+    expect(fakeDb.query.posts.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ where: expect.anything() })
+    );
+  });
+});
+```
+
+For multi-method flows, use `testcontainers` against a real Postgres (see integration tests below).
+
+## Route integration tests (full chain)
+
+Test the full middleware chain (auth → permission → validate → handler → service) via `app.request(...)` against the chained Hono app. The framework's reference modules ship a harness — mirror that shape:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { app } from "../../index"; // your composed app
+
+describe("POST /posts", () => {
+  it("rejects unauthenticated requests", async () => {
+    const res = await app.request("/posts", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ title: "x", body: "y" }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("creates a post for an authenticated user with permission", async () => {
+    const res = await app.request("/posts", {
+      method: "POST",
+      headers: { "content-type": "application/json", cookie: signedAuthCookie() },
+      body: JSON.stringify({ title: "x", body: "y" }),
+    });
+    expect(res.status).toBe(201);
+    const json = await res.json();
+    expect(json).toMatchObject({ id: expect.any(String), title: "x" });
+  });
+});
+```
+
+`signedAuthCookie()` is a test helper you write once that mints a valid session cookie via the framework's `JwtSigner`. Keep helpers in `tests/helpers/`.
+
+## Real-DB integration tests
+
+For tests that exercise queries / migrations / transactions against a real Postgres, use `@testcontainers/postgresql`:
+
+```ts
+import { PostgreSqlContainer } from "@testcontainers/postgresql";
+
+let container: StartedPostgreSqlContainer;
+beforeAll(async () => { container = await new PostgreSqlContainer().start(); });
+afterAll(async () => { await container.stop(); });
+```
+
+Run integration tests under a separate Vitest config (`vitest.integration.config.ts`) so they don't slow the regular suite.
+
+## Mocking
+
+- **Mock at boundaries, not internals.** Mock the framework's `AuthProvider`, `Cache`, `JobQueue` — not your own service methods. If you find yourself mocking your own service heavily, the test is at the wrong level.
+- Use `vi.fn()` over `jest.fn()` (the migration is mechanical; vitest exposes `vi`).
+- Use `vi.spyOn(obj, "method").mockReturnValue(...)` for method spies — don't reassign methods directly.
+
+## What to assert
+
+- **Status codes + response shape**, not exact response bodies. Use `toMatchObject` over `toEqual` so non-deterministic fields (timestamps, IDs) don't make tests brittle.
+- **Side effects**: did the service call the cache? Did it emit an outbox event? Did it log? Spy on those.
+- **Error paths**: assert the exact AppError subclass thrown (`ConflictError`, `NotFoundError`), not just "an error was thrown".
+
+## What NOT to do
+
+- **Don't mock pg/Drizzle directly** in unit tests. Either go fake-DB (a hand-rolled stub object) or testcontainers. Mocking Drizzle leads to tests that pass but don't reflect SQL behavior.
+- **Don't share mutable state across tests.** Each test gets a fresh fixture. If setup is expensive, use `beforeAll` + a reset in `beforeEach`.
+- **Don't test framework internals** — those are tested in `@sixthsummit/ship-api`'s own test suite. You test your code.
+- **Don't add tests just for coverage.** A test that asserts trivia (`expect(x).toBeDefined()`) is worse than no test — it lies about what's verified.
+
+## Coverage
+
+The template ships with no enforced coverage gate; opt in by editing `vitest.config.ts` if you want a floor. The framework itself targets 80% line / 70% branch on `packages/core/src/**` per `docs/V4_STATUS.md` — your app can do whatever fits the team.

package/templates/default/.cursor/rules/typescript.mdc

@@ -0,0 +1,86 @@
+---
+alwaysApply: true
+description: "TypeScript coding standards for ShipAPI v4 apps"
+tags: ["typescript", "type-safety"]
+globs: ["src/**/*.ts", "tests/**/*.ts"]
+---
+
+# TypeScript Coding Standards
+
+## Strictness
+
+- The template runs with `strict: true`. Don't disable individual flags (`strictNullChecks`, `noImplicitAny`, etc.) per-file or per-tsconfig.
+- `tsc --noEmit` runs in `npm run type-check` and CI. Type errors block the pipeline.
+
+## `any`, `unknown`, `never`
+
+- **No `any`.** Use `unknown` and narrow with `instanceof`, type guards, or Zod parsing.
+- Use `unknown` for genuinely-unknown payloads (webhook bodies before signature verification, third-party callbacks). Narrow via Zod before use.
+- Reach for `never` to mark exhaustiveness checks: `const _exhaustive: never = x;` in a `switch` default fails compile if a new case is added.
+
+## Imports
+
+- Import the framework via package-export paths: `@sixthsummit/ship-api`, `@sixthsummit/ship-api/client`, `@sixthsummit/ship-api/observability/logger`, etc.
+- **Never import from `node_modules/@sixthsummit/ship-api/lib/`.** Those are build artifacts; the path is not part of the public API.
+- Within your app, use relative imports for module-internal references and absolute paths (configured in `tsconfig.json` via `paths`) for cross-module references.
+
+## Type-driven schema flow
+
+ShipAPI v4 propagates types end-to-end via:
+
+```
+Drizzle table (schema.ts)
+   ↓ drizzle-zod
+Zod schema (validation/schemas.ts)
+   ↓ validate("json", schema)
+Hono route handler (c.req.valid("json"))
+   ↓ typeof app
+ShipApiClient type (exported from src/index.ts)
+   ↓ hc<ShipApiClient>(BASE_URL)
+Typed RPC client on the consumer
+```
+
+This means: **schema changes propagate through TypeScript types alone, no codegen.** Don't add manual type duplications between layers — let inference flow.
+
+## Null safety
+
+- Prefer `T | undefined` for "not yet known" / "may not be present"; use `T | null` only when the database column is nullable (or another external system distinguishes null from absent).
+- Don't use the non-null assertion `!` to suppress null errors. If TS thinks a value can be null, narrow it with a check or fix the type.
+- Optional chaining (`?.`) and nullish coalescing (`??`) over `&&` / `||` for default-value patterns when you mean "null or undefined", not "any falsy".
+
+## Branded types
+
+For IDs and other opaque scalars where mixing types would be a bug:
+
+```ts
+type AccountId = string & { readonly _brand: "AccountId" };
+type PostId = string & { readonly _brand: "PostId" };
+```
+
+Then `getPost(accountId)` fails to compile. Branded types are zero-cost at runtime.
+
+## Generics
+
+- Default to inference. Explicit generics belong on factory APIs (`createApp<TSchema>`), not on call sites where TS can infer.
+- Constrain generics with `extends` where it documents intent: `function fn<T extends { id: string }>(x: T)`.
+- Avoid `any` as a generic constraint. `unknown` is almost always better.
+
+## Error narrowing
+
+Use `instanceof` against the AppError taxonomy when you need to react to specific errors:
+
+```ts
+try { await service.create(input); }
+catch (err) {
+  if (err instanceof ConflictError) return c.json({ message: "exists" }, 409);
+  throw err;
+}
+```
+
+Otherwise let `registerErrorHandlers(app)` handle it — don't catch errors just to re-throw.
+
+## Conventions
+
+- File names: `PascalCase` for classes / services (`PostService.ts`), `camelCase` for utilities (`buildQuery.ts`), `kebab-case` for route directories.
+- Exported types from a module: name the type after what it represents (`Post`, `CreatePostInput`), not how it's derived (`PostType`, `CreatePostBody`).
+- Prefer `type` over `interface` unless you specifically need declaration merging.

package/templates/default/.env.example

@@ -0,0 +1,79 @@
+# Required ─────────────────────────────────────────────────────────────
+
+# Postgres connection string — used by both runtime + drizzle-kit.
+DATABASE_URL=postgres://ship_api:ship_api@localhost:5432/ship_api
+
+# HMAC-SHA256 secret for OAuth state signing. ≥32 random bytes,
+# rotated separately from JWT keys. Do not commit.
+#
+# Zero-downtime rotation: the framework's `StateSecret` type accepts
+# either a single string OR an ordered array (head signs, tail still
+# verifies). During a rotation window, source two env vars in your
+# environment.ts and pass `[env.OAUTH_STATE_SECRET_NEW, env.OAUTH_STATE_SECRET_OLD]`
+# as `stateSecret` to defineOAuthRoutes; once the rotation window
+# (default 10 min) has fully drained, drop OLD from the array.
+OAUTH_STATE_SECRET=replace-with-32-random-bytes
+
+# JWT signing — ES256 key pair. Rotate via add-new-key →
+# cut-signing → drain-old-key. The signing key is private; the
+# verification keys are a JSON array of JWKS supporting >1 key
+# during rotation windows.
+JWT_SIGNING_KEY=
+JWT_VERIFICATION_KEYS=[]
+
+# Optional ─────────────────────────────────────────────────────────────
+
+PORT=3000
+NODE_ENV=development
+LOG_LEVEL=info
+
+# CORS allowlist (comma-separated). When set, the framework wires
+# `hono/cors` with `credentials: true` against this list. Required if
+# your TypeScript client lives on a different origin from the API.
+#
+# `CORS_ORIGINS=*` is NOT supported with cookie auth — browsers reject
+# the wildcard + credentials combo, and `createApp()` throws at boot
+# rather than letting the misconfig sit silently. Use explicit origins:
+#
+#   CORS_ORIGINS=https://app.example.com,https://admin.example.com
+#
+# Leave unset for a single-origin deployment (same domain for API + web).
+CORS_ORIGINS=
+
+# OpenTelemetry — disable in test, enable + point at a collector
+# in prod. The auto-instrumentations cover HTTP / pg / ioredis /
+# undici / pino with no per-call wiring.
+OTEL_SDK_DISABLED=true
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_SERVICE_NAME=ship-api-app
+ENVIRONMENT_NAME=development
+
+# Prometheus metrics exporter (independent port, off by default).
+METRICS_ENABLED=false
+METRICS_PORT=9464
+
+# Redis — required when using rate limiting / cache / BullMQ.
+REDIS_URL=redis://localhost:6379
+
+# Admin API key for the Bull-Board dashboard (and other admin
+# surfaces). ≥32 random bytes. Required only when you mount the
+# dashboard via `createBullBoardApp({ apiKey: env.ADMIN_API_KEY })`.
+# DO NOT expose the dashboard on a public hostname even with the key
+# set — operators should additionally guard at the network edge
+# (private subnet / VPN / ingress allowlist).
+ADMIN_API_KEY=
+
+# Firebase auth (the v4.0 default AuthProvider). Replace with
+# Better-Auth / Clerk / WorkOS / Auth.js adapter creds when you
+# swap providers.
+FIREBASE_CREDENTIALS=
+
+# OAuth provider credentials. Add only the providers your app
+# supports — the credentials resolver returns null for unconfigured
+# providers and the routes layer 400s with a clear message.
+OAUTH_GOOGLE_CLIENT_ID=
+OAUTH_GOOGLE_CLIENT_SECRET=
+OAUTH_GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/google/callback
+OAUTH_MICROSOFT_CLIENT_ID=
+OAUTH_MICROSOFT_CLIENT_SECRET=
+OAUTH_MICROSOFT_REDIRECT_URI=http://localhost:3000/oauth/microsoft/callback

package/templates/default/.github/workflows/sherpa-brief.yml

@@ -0,0 +1,180 @@
+name: Sherpa QA brief
+
+# Generates a plain-English QA brief for the Sherpa toolkit:
+#   - On PR-to-dev: posts (or updates) a preview brief as a sticky PR comment.
+#   - On push to dev (i.e. merge to dev → deploy to dev site): posts the final
+#     brief to the QA Slack channel + uploads brief.md as a workflow artifact.
+#
+# The brief is produced by the ship-api plugin's `qa-brief` agent running
+# headless via the Claude Code CLI. Engineers do nothing — Cursor and Claude
+# Code users both get the same output through this CI path.
+#
+# Secrets required:
+#   ANTHROPIC_API_KEY    — Claude API key for the headless agent run
+#   SLACK_QA_WEBHOOK_URL — Incoming Webhook for the QA channel (only used on push)
+#   GH_PACKAGES_TOKEN    — read-access to @sixthsummit npm scope (if private deps)
+#
+# Override `STACK_LABEL` per repo if you customize the stack identity.
+
+on:
+  pull_request:
+    branches: [dev]
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [dev]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: sherpa-brief-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: '20'
+  STACK_LABEL: 'ShipAPI (backend)'
+
+jobs:
+  brief:
+    name: Generate QA brief
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft != true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: Resolve diff range and PR context
+        id: refs
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_BRANCH: ${{ github.event.pull_request.head.ref }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          PUSH_BEFORE: ${{ github.event.before }}
+          PUSH_AFTER: ${{ github.sha }}
+          PUSH_BRANCH: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            echo "base=$PR_BASE_SHA" >> "$GITHUB_OUTPUT"
+            echo "head=$PR_HEAD_SHA" >> "$GITHUB_OUTPUT"
+            echo "branch=$PR_BRANCH" >> "$GITHUB_OUTPUT"
+            echo "pr_title=$PR_TITLE" >> "$GITHUB_OUTPUT"
+            echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+            printf '%s' "$PR_BODY" > pr_body.txt
+          else
+            BASE="$PUSH_BEFORE"
+            if [[ -z "$BASE" || "$BASE" == "0000000000000000000000000000000000000000" ]]; then
+              BASE="$(git rev-parse HEAD~1)"
+            fi
+            echo "base=$BASE" >> "$GITHUB_OUTPUT"
+            echo "head=$PUSH_AFTER" >> "$GITHUB_OUTPUT"
+            echo "branch=$PUSH_BRANCH" >> "$GITHUB_OUTPUT"
+            git log -1 --pretty=%s "$PUSH_AFTER" > .commit_subject
+            echo "pr_title=$(cat .commit_subject)" >> "$GITHUB_OUTPUT"
+            echo "pr_number=" >> "$GITHUB_OUTPUT"
+            git log -1 --pretty=%b "$PUSH_AFTER" > pr_body.txt
+          fi
+
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Run qa-brief agent
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          BASE_REF: ${{ steps.refs.outputs.base }}
+          HEAD_REF: ${{ steps.refs.outputs.head }}
+          PR_TITLE: ${{ steps.refs.outputs.pr_title }}
+          PR_NUMBER: ${{ steps.refs.outputs.pr_number }}
+          REPO: ${{ github.repository }}
+          BRANCH: ${{ steps.refs.outputs.branch }}
+          STACK_LABEL: ${{ env.STACK_LABEL }}
+        run: |
+          set -euo pipefail
+          export PR_BODY="$(cat pr_body.txt)"
+          claude -p "Invoke the qa-brief subagent. Use BASE_REF=$BASE_REF and HEAD_REF=$HEAD_REF. Output ONLY the brief markdown — no preamble, no commentary, no fenced code wrapper around the whole thing. The header must use STACK_LABEL=\"$STACK_LABEL\", REPO=\"$REPO\", BRANCH=\"$BRANCH\", and PR=\"$PR_NUMBER\"." > brief.md
+          echo '--- generated brief ---'
+          cat brief.md
+
+      - name: Upload brief artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sherpa-brief-${{ github.run_id }}
+          path: brief.md
+          retention-days: 30
+
+      - name: Post sticky PR comment
+        if: github.event_name == 'pull_request'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: sherpa-brief
+          path: brief.md
+
+      - name: Notify Slack on merge to dev
+        if: github.event_name == 'push'
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_QA_WEBHOOK_URL }}
+          STACK_LABEL: ${{ env.STACK_LABEL }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${SLACK_WEBHOOK_URL:-}" ]]; then
+            echo "::warning::SLACK_QA_WEBHOOK_URL not set; skipping Slack notification."
+            exit 0
+          fi
+          ARTIFACT_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          COMMIT_URL="${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}"
+          TITLE="$(head -1 brief.md | sed 's/^# *//')"
+          # Slack section text caps at ~3000 chars; truncate the inline snippet
+          # and rely on the artifact link for the full brief.
+          PREVIEW="$(head -c 2500 brief.md)"
+          if [[ "$(wc -c < brief.md)" -gt 2500 ]]; then
+            PREVIEW="${PREVIEW}
+
+… (truncated — open the full brief from the link below)"
+          fi
+          jq -n \
+            --arg title "$TITLE" \
+            --arg stack "$STACK_LABEL" \
+            --arg repo "${{ github.repository }}" \
+            --arg branch "${{ steps.refs.outputs.branch }}" \
+            --arg artifact "$ARTIFACT_URL" \
+            --arg commit "$COMMIT_URL" \
+            --arg preview "$PREVIEW" \
+            '{
+              text: ("New QA brief: " + $title),
+              blocks: [
+                { "type": "header",
+                  "text": { "type": "plain_text", "text": $title } },
+                { "type": "section",
+                  "fields": [
+                    { "type": "mrkdwn", "text": ("*Stack:*\n" + $stack) },
+                    { "type": "mrkdwn", "text": ("*Repo:*\n" + $repo) },
+                    { "type": "mrkdwn", "text": ("*Branch:*\n`" + $branch + "`") }
+                  ] },
+                { "type": "section",
+                  "text": { "type": "mrkdwn", "text": $preview } },
+                { "type": "actions",
+                  "elements": [
+                    { "type": "button",
+                      "text": { "type": "plain_text", "text": "Open full brief" },
+                      "url": $artifact },
+                    { "type": "button",
+                      "text": { "type": "plain_text", "text": "View commit" },
+                      "url": $commit }
+                  ] }
+              ]
+            }' > slack-payload.json
+          curl -sS --fail -X POST -H 'Content-Type: application/json' \
+            --data @slack-payload.json "$SLACK_WEBHOOK_URL"