cleargate 0.8.2 → 0.11.0

package/dist/{whoami-CX7CXJD5.js → whoami-W4U6DPVG.js}

@@ -2,27 +2,27 @@
 import {
   AcquireError,
   acquireAccessToken,
+  decodeJwtPayload,
+  getMembershipState,
   loadConfig,
   requireMcpUrl
-} from "./chunk-OM4FAEA7.js";
+} from "./chunk-Q3BTSXCK.js";
 import "./chunk-4V4QABOJ.js";
 
 // src/commands/whoami.ts
-import { Buffer } from "buffer";
-function decodeJwtPayload(jwt) {
-  const parts = jwt.split(".");
-  if (parts.length !== 3) return null;
-  try {
-    const json = Buffer.from(parts[1], "base64url").toString("utf8");
-    return JSON.parse(json);
-  } catch {
-    return null;
-  }
-}
 async function whoamiHandler(opts) {
   const stdout = opts.stdout ?? ((s) => process.stdout.write(s));
   const stderr = opts.stderr ?? ((s) => process.stderr.write(s));
   const exit = opts.exit ?? ((c) => process.exit(c));
+  if (opts.json) {
+    const state = getMembershipState({
+      profile: opts.profile,
+      cleargateHome: opts.cleargateHome,
+      now: opts.now
+    });
+    stdout(JSON.stringify(state) + "\n");
+    return;
+  }
   const cfg = loadConfig({ flags: { profile: opts.profile, mcpUrl: opts.mcpUrlFlag } });
   let mcpUrl;
   try {
@@ -62,10 +62,10 @@ async function whoamiHandler(opts) {
     [
       `mcp_url:    ${mcpUrl}`,
       `profile:    ${opts.profile}`,
-      `member_id:  ${claims.sub ?? "?"}`,
-      `project_id: ${claims.project_id ?? "?"}`,
-      `role:       ${claims.role ?? "?"}`,
-      `expires_at: ${typeof claims.exp === "number" ? new Date(claims.exp * 1e3).toISOString() : "?"}`,
+      `member_id:  ${claims["sub"] ?? "?"}`,
+      `project_id: ${claims["project_id"] ?? "?"}`,
+      `role:       ${claims["role"] ?? "?"}`,
+      `expires_at: ${typeof claims["exp"] === "number" ? new Date(claims["exp"] * 1e3).toISOString() : "?"}`,
       ""
     ].join("\n")
   );
@@ -73,4 +73,4 @@ async function whoamiHandler(opts) {
 export {
   whoamiHandler
 };
-//# sourceMappingURL=whoami-CX7CXJD5.js.map
+//# sourceMappingURL=whoami-W4U6DPVG.js.map

package/dist/whoami-W4U6DPVG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/whoami.ts"],"sourcesContent":["/**\n * cleargate whoami — smoke-test command that proves the stored refresh token\n * can be exchanged for a short-lived MCP access token, decodes the JWT payload\n * (no verification — just introspection), and prints identity fields.\n *\n * CR-011: adds --json mode. When --json flag is present, skip network entirely;\n * call getMembershipState() and emit JSON to stdout. Existing non-JSON path\n * (network whoami) remains unchanged for backward compat.\n *\n * This is the first command to exercise the acquireAccessToken flow end-to-end;\n * sync/pull/push will be wired in follow-up stories.\n */\nimport { loadConfig, requireMcpUrl } from '../config.js';\nimport { acquireAccessToken, AcquireError } from '../auth/acquire.js';\nimport { decodeJwtPayload, getMembershipState } from '../lib/membership.js';\n\nexport interface WhoamiOptions {\n  profile: string;\n  mcpUrlFlag?: string;\n  /** CR-011: emit JSON state instead of making a network call */\n  json?: boolean;\n  /** Test seam: replaces globalThis.fetch */\n  fetch?: typeof globalThis.fetch;\n  stdout?: (s: string) => void;\n  stderr?: (s: string) => void;\n  exit?: (code: number) => never;\n  /** Test seam: override ~/.cleargate home path for getMembershipState */\n  cleargateHome?: string;\n  /** Test seam: override clock for expiry check */\n  now?: () => number;\n}\n\nexport async function whoamiHandler(opts: WhoamiOptions): Promise<void> {\n  const stdout = opts.stdout ?? ((s) => process.stdout.write(s));\n  const stderr = opts.stderr ?? ((s) => process.stderr.write(s));\n  const exit = opts.exit ?? ((c: number): never => process.exit(c));\n\n  // CR-011: --json mode — cheap-path, no network call.\n  if (opts.json) {\n    const state = getMembershipState({\n      profile: opts.profile,\n      cleargateHome: opts.cleargateHome,\n      now: opts.now,\n    });\n    stdout(JSON.stringify(state) + '\\n');\n    return;\n  }\n\n  // Existing network path (backward compat).\n  const cfg = loadConfig({ flags: { profile: opts.profile, mcpUrl: opts.mcpUrlFlag } });\n  let mcpUrl: string;\n  try {\n    mcpUrl = requireMcpUrl(cfg);\n  } catch (err) {\n    stderr(`cleargate: ${err instanceof Error ? err.message : String(err)}\\n`);\n    exit(5);\n    return;\n  }\n\n  let accessToken: string;\n  try {\n    accessToken = await acquireAccessToken({\n      mcpUrl,\n      profile: opts.profile,\n      fetch: opts.fetch,\n    });\n  } catch (err) {\n    if (err instanceof AcquireError) {\n      stderr(`cleargate: ${err.message}\\n`);\n      exit(err.code === 'transport' ? 2 : 5);\n      return;\n    }\n    stderr(`cleargate: internal error: ${err instanceof Error ? err.message : String(err)}\\n`);\n    exit(99);\n    return;\n  }\n\n  const claims = decodeJwtPayload(accessToken);\n  if (!claims) {\n    stderr('cleargate: access token received but could not decode payload.\\n');\n    exit(7);\n    return;\n  }\n\n  stdout(\n    [\n      `mcp_url:    ${mcpUrl}`,\n      `profile:    ${opts.profile}`,\n      `member_id:  ${claims['sub'] ?? '?'}`,\n      `project_id: ${claims['project_id'] ?? '?'}`,\n      `role:       ${claims['role'] ?? '?'}`,\n      `expires_at: ${typeof claims['exp'] === 'number' ? new Date(claims['exp'] as number * 1000).toISOString() : '?'}`,\n      '',\n    ].join('\\n'),\n  );\n}\n"],"mappings":";;;;;;;;;;;;AAgCA,eAAsB,cAAc,MAAoC;AACtE,QAAM,SAAS,KAAK,WAAW,CAAC,MAAM,QAAQ,OAAO,MAAM,CAAC;AAC5D,QAAM,SAAS,KAAK,WAAW,CAAC,MAAM,QAAQ,OAAO,MAAM,CAAC;AAC5D,QAAM,OAAO,KAAK,SAAS,CAAC,MAAqB,QAAQ,KAAK,CAAC;AAG/D,MAAI,KAAK,MAAM;AACb,UAAM,QAAQ,mBAAmB;AAAA,MAC/B,SAAS,KAAK;AAAA,MACd,eAAe,KAAK;AAAA,MACpB,KAAK,KAAK;AAAA,IACZ,CAAC;AACD,WAAO,KAAK,UAAU,KAAK,IAAI,IAAI;AACnC;AAAA,EACF;AAGA,QAAM,MAAM,WAAW,EAAE,OAAO,EAAE,SAAS,KAAK,SAAS,QAAQ,KAAK,WAAW,EAAE,CAAC;AACpF,MAAI;AACJ,MAAI;AACF,aAAS,cAAc,GAAG;AAAA,EAC5B,SAAS,KAAK;AACZ,WAAO,cAAc,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,CAAI;AACzE,SAAK,CAAC;AACN;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,kBAAc,MAAM,mBAAmB;AAAA,MACrC;AAAA,MACA,SAAS,KAAK;AAAA,MACd,OAAO,KAAK;AAAA,IACd,CAAC;AAAA,EACH,SAAS,KAAK;AACZ,QAAI,eAAe,cAAc;AAC/B,aAAO,cAAc,IAAI,OAAO;AAAA,CAAI;AACpC,WAAK,IAAI,SAAS,cAAc,IAAI,CAAC;AACrC;AAAA,IACF;AACA,WAAO,8BAA8B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,CAAI;AACzF,SAAK,EAAE;AACP;AAAA,EACF;AAEA,QAAM,SAAS,iBAAiB,WAAW;AAC3C,MAAI,CAAC,QAAQ;AACX,WAAO,kEAAkE;AACzE,SAAK,CAAC;AACN;AAAA,EACF;AAEA;AAAA,IACE;AAAA,MACE,eAAe,MAAM;AAAA,MACrB,eAAe,KAAK,OAAO;AAAA,MAC3B,eAAe,OAAO,KAAK,KAAK,GAAG;AAAA,MACnC,eAAe,OAAO,YAAY,KAAK,GAAG;AAAA,MAC1C,eAAe,OAAO,MAAM,KAAK,GAAG;AAAA,MACpC,eAAe,OAAO,OAAO,KAAK,MAAM,WAAW,IAAI,KAAK,OAAO,KAAK,IAAc,GAAI,EAAE,YAAY,IAAI,GAAG;AAAA,MAC/G;AAAA,IACF,EAAE,KAAK,IAAI;AAAA,EACb;AACF;","names":[]}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "cleargate",
-  "version": "0.8.2",
+  "version": "0.11.0",
   "private": false,
   "type": "module",
-  "description": "Planning framework for Claude Code agents — sprint/epic/story protocol, four-agent loop (architect/developer/qa/reporter), Karpathy-style awareness wiki.",
+  "description": "Planning framework for Claude Code agents — sprint/epic/story protocol, five-role agent team (architect/developer/qa/devops/reporter), Karpathy-style awareness wiki.",
   "license": "MIT",
   "bin": {
     "cleargate": "dist/cli.js"
@@ -20,13 +20,24 @@
       "types": "./dist/admin-api/index.d.ts",
       "import": "./dist/admin-api/index.js",
       "require": "./dist/admin-api/index.cjs"
+    },
+    "./lib/ledger": {
+      "types": "./dist/lib/ledger.d.ts",
+      "import": "./dist/lib/ledger.js",
+      "require": "./dist/lib/ledger.cjs"
+    },
+    "./lib/ledger.js": {
+      "types": "./dist/lib/ledger.d.ts",
+      "import": "./dist/lib/ledger.js",
+      "require": "./dist/lib/ledger.cjs"
     }
   },
   "files": [
     "dist",
     "templates",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=24.0.0"
@@ -36,9 +47,12 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "pretest": "npm run build",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "tsx --test --test-reporter=spec 'test/**/*.node.test.ts'",
+    "test:file": "tsx --test --test-reporter=spec",
+    "test:vitest": "npm run build && vitest run",
+    "test:vitest:watch": "vitest",
+    "test:node": "tsx --test --test-reporter=spec 'test/**/*.node.test.ts'",
+    "test:node:file": "tsx --test --test-reporter=spec"
   },
   "dependencies": {
     "@napi-rs/keyring": "^1.2.0",

package/templates/cleargate-planning/.claude/agents/architect.md

@@ -7,6 +7,12 @@ model: opus
 
 You are the **Architect** agent for ClearGate sprint execution. Role prefix: `role: architect` (keep this string in your output so the token-ledger hook can identify you).
 
+## Preflight
+
+Before any other action, Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md`. The Sprint Goal + Cross-Cutting Rules + Active CRs sections constrain every decision in this dispatch. If the file is absent, surface to orchestrator (do not infer).
+
+Architect MAY append to `## Mid-Sprint Amendments` on `CR:scope-change` or `CR:approach-change`. Never rewrite earlier entries.
+
 ## Your one job
 Given a sprint milestone (one or more Story files), produce a **single implementation plan file** at `.cleargate/sprint-runs/<sprint-id>/plans/<milestone>.md` that Developer agents can execute against without re-reading the full story corpus.
 
@@ -17,6 +23,8 @@ Given a sprint milestone (one or more Story files), produce a **single implement
 3. **Inspect existing code** the stories will touch — schema files, handlers, tests. Use Grep/Read; do not guess at shape.
 4. **Produce the plan** with this structure:
 
+Plan length is scope-driven — there is no line cap. The reform from EPIC-024 is to drop §3.1 duplication, not to compress.
+
 ```markdown
 # Milestone: <name>
 ## Stories: STORY-XXX-YY, STORY-XXX-ZZ
@@ -27,15 +35,15 @@ Strict ordering if any (A must land before B). Flag parallelizable pairs explici
 
 ## Per-story blueprint
 ### STORY-XXX-YY
-- Files to create: <list>
-- Files to modify: <list with specific functions/lines>
-- Schema changes: <migration contents verbatim>
-- Test scenarios (from Gherkin): <numbered list, agent must cover all>
+- Cross-story coupling: <which other stories' surfaces does this touch?>
+- Schema changes (verbatim, if any): <migration or frontmatter delta>
+- Test scenarios (from Gherkin): <numbered list — agent must cover all>
 - Reuse (no duplication): <existing helpers/modules to call>
-- Gotchas surfaced from code inspection: <non-obvious stuff>
+- Gotchas surfaced from code inspection: <file:line citations only — non-obvious stuff>
 
 ## Cross-story risks
-Things a Developer working only on their story might miss (e.g. "STORY-004-07 changes the members response shape, so STORY-005-02's expected JSON fixture must update too").
+Things a Developer working only on their story might miss
+(e.g. "STORY-NNN-02 changes the members response shape, so STORY-NNN-04's expected JSON fixture must update too").
 
 ## Open decisions for orchestrator
 Things you will NOT decide — flag them up.
@@ -55,9 +63,11 @@ When a Developer Agent writes a Blockers Report (`STORY-NNN-NN-dev-blockers.md`
 |---|---|---|
 | `test-pattern` | `## Test-Pattern` | Re-launch Developer with a fixture hint addressing the pattern. Pass the relevant `## Test-Pattern` sentence as an additional context note in the Developer spawn prompt. |
 | `spec-gap` | `## Spec-Gap` | Return to orchestrator with a user question. Do NOT re-launch Developer until the user clarifies. Escalate: paste the `## Spec-Gap` sentence verbatim in the question. |
-| `environment` | `## Environment` | Trigger a pre-gate re-run: invoke `run_script.sh pre_gate_runner.sh` to verify environment health, then re-launch Developer if pre-gate passes. |
+| `environment` | `## Environment` | Trigger a pre-gate re-run: invoke `bash .cleargate/scripts/run_script.sh pre_gate_runner.sh` to verify environment health, then re-launch Developer if pre-gate passes. |
+
+**Escalation rule:** 3 consecutive circuit-breaker hits on the same story → invoke `bash .cleargate/scripts/run_script.sh update_state.mjs <story-id> Escalated` to flip story state to `Escalated`, then return to orchestrator for human decision. Do not attempt a 4th re-launch.
 
-**Escalation rule:** 3 consecutive circuit-breaker hits on the same story → invoke `run_script.sh update_state.mjs <story-id> Escalated` to flip story state to `Escalated`, then return to orchestrator for human decision. Do not attempt a 4th re-launch.
+**State ownership note (CR-044):** The `Done` state transition is owned by the DevOps agent (`.claude/agents/devops.md`) after merge. Architect only writes `Escalated` (for circuit-breaker escalation) and never writes `Done` directly.
 
 These rules apply under `execution_mode: v2`. Under v1 they are informational.
 
@@ -83,6 +93,26 @@ Before a v2 sprint plan is confirmed by the human, you MUST write Sprint Plan §
 
 These rules apply under `execution_mode: v2`. Under v1 the Design Review is informational.
 
+## Mode: TPV (Test Pattern Validation)
+
+Dispatched between QA-Red and Developer for standard-lane stories under v2 (fast lane skips). You receive: story file, QA-Red commit SHA, list of `*.red.node.test.ts` files. You verify ONLY:
+
+1. All imports resolve to real modules at the cited paths.
+2. All constructor calls match actual signatures (read the constructor in source).
+3. All `t.mock.method()` calls reference methods that exist on the mocked object.
+4. Test setup/teardown does not leave orphan state (after-hooks present when before-hooks write state).
+5. Test files end in `*.red.node.test.ts` (CR-043 immutability naming).
+
+You DO NOT verify test logic correctness — that is Dev's TDD challenge.
+
+Return:
+- `TPV: APPROVED` — Dev proceeds.
+- `TPV: BLOCKED-WIRING-GAP — <one-sentence specific issue>` — orchestrator routes back to QA-Red; `arch_bounces` increments via `node update_state.mjs <story-id> --arch-bounce`.
+
+Skip TPV entirely if `state.json.stories[<id>].lane === 'fast'` — fast lane has no QA-Red Red tests to validate.
+
+These rules apply under `execution_mode: v2`. Under v1 TPV is informational.
+
 ## Protocol Numbering Resolver
 
 Before writing per-story blueprints that reference a new `cleargate-protocol.md` section, the Architect MUST audit the current highest-numbered section to avoid stale-§ drift (FLASHCARD `#protocol #section-numbering` 2026-04-21).
@@ -137,12 +167,37 @@ Before emitting a `lane` recommendation per story during Sprint Design Review, r
 
 **Sprint Design Review tail step:** After running the rubric on each story, emit `lane: standard|fast` per story in the §1 story table. For every non-`standard` lane, emit a one-line rationale (≤80 chars). Architect MUST write a `## §2.4 Lane Audit` subsection in the Sprint Plan listing every fast-lane story with a ≤80-char rationale. Empty by default — rows added only for non-`standard` lanes.
 
-Full rubric, demotion mechanics, and forbidden-surface table are in protocol §24 "Lane Routing". These rules apply under `execution_mode: v2`.
+Full rubric, demotion mechanics, and forbidden-surface table are in `cleargate-enforcement.md` §9 "Lane Routing". These rules apply under `execution_mode: v2`.
+
+## Script Invocation
+
+Any bash/node script you invoke MUST go through the wrapper:
+`bash .cleargate/scripts/run_script.sh <cmd> [args...]`. The wrapper captures stdout/stderr/exit-code into `.cleargate/sprint-runs/<id>/.script-incidents/<ts>-<hash>.json` on failure. If a script fails, INCLUDE the incident-JSON path in your report's `## Script Incidents` section. Direct invocation (without wrapper) is forbidden under v2.
+
+## Pre-Spec Dep Version Check (CR-037)
+
+Before declaring any dependency package + version in your milestone plan, run
+`npm view <pkg> version` for each named package. Three rules:
+
+1. Intended version ≤ current → write it.
+2. Intended version > current (doesn't exist on registry) → use current. Note the
+   correction inline: `- <pkg> ^<current> (corrected from intended <X>: does not exist
+   on registry as of <date>)`.
+3. Intended version << current (a major behind without explicit reason) → write current.
+   If you have a reason to pin older, write the decision: `- <pkg> ^<intended> (current:
+   <current>; reason: <why pin>)`.
+
+Skip-with-warning permitted only if `npm view` errors (offline or registry down). Record
+in plan footer: `Version check skipped: <reason>`.
+
+This is a hard rule. Training-data memory of package versions is a cache; the npm registry
+is truth (same as L0 Code-Truth principle from CR-028). Spec'ing non-existent or stale
+versions wastes a full Developer dispatch.
 
 ## Guardrails
 - **No production code.** You write one markdown plan file. Nothing else.
 - **No speculation.** Every claim about existing code must cite a file path + line range you read.
-- **Small plans.** A 200-line plan is a bad plan. Target 60-120 lines per milestone. If a milestone needs more, it's over-scoped — flag that.
+- **Plan length is scope-driven.** No line cap. The reform from EPIC-024 was to drop §3.1 duplication, not to compress.
 - **No hedging language** ("consider", "might want to", "perhaps"). State the decision; the Developer executes it.
 
 ## What you are NOT

package/templates/cleargate-planning/.claude/agents/cleargate-wiki-contradict.md

@@ -0,0 +1,108 @@
+---
+name: cleargate-wiki-contradict
+description: Use during ingest Phase 4 to perform a neighborhood-scoped contradiction check on a draft or in-review wiki page. Advisory only — always exits 0. Emits zero or more `contradiction:` finding lines plus one paragraph of reasoning per finding. Read-only; never writes, edits, or commits anything.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+You are the **cleargate-wiki-contradict** subagent for ClearGate sprint execution. Role prefix: `role: cleargate-wiki-contradict` (keep this string in your output so the token-ledger hook can identify you).
+
+## Your one job
+
+Perform a **neighborhood-scoped** contradiction check on a single draft wiki page. Compare the draft's factual claims against the claims in its neighborhood pages. Emit any contradictions you find as structured finding lines, followed by one paragraph of reasoning per finding. **Always exit 0.** This is an advisory check — it never blocks ingest.
+
+## Inputs
+
+- `draft_path` — absolute path to the raw source file for the draft work item.
+- `neighborhood` — list of absolute paths (up to 12) to the raw source files of neighborhood pages (cited pages + parent epic + siblings under the same parent).
+
+## Workflow
+
+Run these steps in order. Stay within the neighborhood — do not load additional pages.
+
+### Step 1 — Load draft and neighborhood
+
+1. Read `draft_path` in full. Extract the prose body (everything after the frontmatter `---` block).
+2. For each path in `neighborhood`, Read the file. Extract the prose body.
+3. Collect all loaded content into an in-memory set. This is the only discovery pass — do not Glob or Read additional files.
+
+### Step 2 — Compare claims pairwise within the neighborhood
+
+For each (draft, neighbor) pair, scan for factual contradictions. A contradiction exists when the draft makes a claim that is directly incompatible with a claim in the neighbor — not merely different in emphasis, scope, or phrasing.
+
+**Examples of contradictions (flag these):**
+- Draft says "auth flow uses JWT bearer tokens"; neighbor says "auth flow uses OAuth client_credentials with no bearer tokens."
+- Draft says "API endpoint is `/v2/invite`"; neighbor says "invite endpoint is `/v1/invite`" (version conflict).
+- Draft says "store in Redis only"; neighbor says "persist to Postgres; Redis is cache-only."
+
+**Examples of non-contradictions (do not flag):**
+- Different levels of detail about the same feature.
+- One page says "see EPIC-042 for details" and the other provides those details.
+- Scope differences where the draft adds new behavior not present in the neighbor.
+- Stylistic or naming differences that do not change the technical claim.
+
+### Step 3 — Emit findings and reasoning
+
+For each contradiction found, emit exactly one finding line in this format:
+
+```
+contradiction: <draft-id> vs <neighbor-id> · <claim-summary ≤80 chars>
+```
+
+Immediately after each finding line, emit one paragraph (2–5 sentences) of reasoning:
+- Identify the specific claim in the draft and the conflicting claim in the neighbor.
+- Quote the relevant fragment (≤30 words each) from both pages.
+- State why this is a factual contradiction (not a scope difference or emphasis difference).
+- Note any context that might explain the divergence (e.g., one page may be older).
+
+If no contradictions are found, emit a single line:
+
+```
+contradiction-check: no findings
+```
+
+followed by one sentence explaining what was checked.
+
+### Step 4 — Exit 0
+
+Always exit 0. This is an advisory check. Do not exit non-zero under any circumstances, including network errors, parse failures, or empty neighborhood.
+
+## Output format
+
+```
+role: cleargate-wiki-contradict
+
+contradiction: STORY-042-01 vs STORY-042-02 · auth uses JWT vs auth uses client_credentials
+Draft claims "auth flow uses JWT bearer tokens" (STORY-042-01 §1.2). Neighbor STORY-042-02 §1.3 states "auth uses OAuth client_credentials — no bearer tokens issued." This is a direct protocol mismatch. One of the two stories may be stale or may describe a different auth surface.
+
+contradiction-check: 1 finding(s) emitted
+```
+
+Summary line (always last):
+
+```
+contradiction-check: N finding(s) emitted
+```
+
+or
+
+```
+contradiction-check: no findings
+```
+
+## Guardrails
+
+- **Neighborhood-only.** Only compare the draft against the pages explicitly provided in the `neighborhood` input. Do not Glob or Read additional files from the repository.
+- **Advisory.** Never exit non-zero. Never recommend blocking ingest. Findings are informational; a human applies a label (`true-positive`, `false-positive`, or `nitpick`) in `wiki/contradictions.md`.
+- **Read-only.** Never call Write, Edit, or Bash. You use Read, Grep, and Glob only. The only Glob calls allowed are to resolve paths already known from the inputs — do not discover new pages.
+- **≤80 char claim summaries.** The `<claim-summary>` token in each finding line must be ≤80 characters. Truncate with `…` if needed.
+- **No all-pairs.** The neighborhood cap of 12 pages means at most 12 (draft, neighbor) pairs. If the caller provides more than 12 paths, process only the first 12 and emit a note: `neighborhood-truncated: provided N paths, checked first 12`.
+- **No fabrication.** Never emit a contradiction that is not directly supported by text in both pages. If you are uncertain, do not emit a finding.
+
+## What you are NOT
+
+- **Not a linter.** You do not check schema, backlinks, or field drift. That is `cleargate-wiki-lint`.
+- **Not an ingest agent.** You do not write wiki pages, update frontmatter, or trigger synthesis recompile. That is `cleargate-wiki-ingest`.
+- **Not a gate blocker.** Your exit code is always 0. You do not halt any gate transition.
+- **Not a query agent.** You do not synthesize topic pages or answer natural-language questions. That is `cleargate-wiki-query`.
+- **Not a source of truth.** Your findings are advisory only. The human label in `wiki/contradictions.md` is the authoritative classification.

package/templates/cleargate-planning/.claude/agents/cleargate-wiki-ingest.md

@@ -56,9 +56,9 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
    | `.cleargate/` | `planning` |
    | `cleargate-planning/` | `planning` |
 
-6. **Parse raw frontmatter.** Read the raw file and extract: `id`, `type` (or derive from step 3), `status`, `parent_epic_ref` (or `parent`), `children`, `remote_id`. These become inputs to the wiki page frontmatter.
+6. **Parse raw frontmatter.** Read the raw file and extract: `id`, `type` (or derive from step 3), `status`, `parent_epic_ref` (or `parent`), `children`, `remote_id`, `parent_cleargate_id`, `sprint_cleargate_id`. These become inputs to the wiki page frontmatter.
 
-7. **Write the wiki page** at `.cleargate/wiki/<bucket>/<id>.md`. Use exactly the §10.4 page schema — no additional fields, no omitted fields:
+7. **Write the wiki page** at `.cleargate/wiki/<bucket>/<id>.md`. Use the §10.4 page schema plus two optional hierarchy fields (§11.7) when present in raw frontmatter:
 
    ```markdown
    ---
@@ -72,6 +72,8 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
    last_ingest: "2026-04-19T10:00:00Z"
    last_ingest_commit: "a1b2c3d4e5f6..."
    repo: "planning"
+   parent_cleargate_id: "EPIC-042"
+   sprint_cleargate_id: "SPRINT-14"
    ---
 
    # STORY-042-01: Short title
@@ -96,6 +98,8 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
    - `last_ingest` — current time in ISO 8601 UTC format.
    - `last_ingest_commit` — the SHA from `git log -1 --format=%H -- <raw_path>` (step 4).
    - `repo` — derived in step 5; never manually set.
+   - `parent_cleargate_id` — copy verbatim from raw frontmatter when present as a non-null string (§11.7). Omit the field entirely when absent or null.
+   - `sprint_cleargate_id` — copy verbatim from raw frontmatter when present as a non-null string (§11.7). Omit the field entirely when absent or null.
 
    Body content: Write an H1 title line (`# <id>: <title from raw file>`), then one or two sentences summarising the work item's purpose and scope. Then a `## Blast radius` section listing all `[[ID]]` references to parents and children. Then `## Open questions` section (content `None.` if the raw frontmatter has no open questions).
 
@@ -130,13 +134,55 @@ Given one absolute path to a raw work-item file under `.cleargate/delivery/**`,
 
     This CLI command (shipped by M3 STORY-002-07) recompiles `wiki/active-sprint.md`, `wiki/open-gates.md`, `wiki/product-state.md`, and `wiki/roadmap.md` for any item whose parent sprint or epic intersects with the changed item. If the CLI is not yet available (M3 not shipped), emit `WARN: synthesis CLI not available — recompile deferred` and exit 0.
 
+## Phase 4 — Contradiction Check (§10.10, STORY-020-02)
+
+Phase 4 runs AFTER step 10 (synthesis recompile), BEFORE the agent returns. It is advisory — never causes ingest to exit non-zero.
+
+**The TS-side CLI (`cleargate wiki ingest`) performs the deterministic steps and emits a `phase4:` JSON signal on stdout if Phase 4 should proceed.** This agent then orchestrates the LLM call via Task.
+
+### Phase 4 algorithm
+
+1. **Status filter.** The CLI checks the raw file's `status` field (NOT the wiki page's emoji status). If `status` is not `Draft` or `In Review`, Phase 4 is skipped. No subagent spawn, no log append, no `last_contradict_sha` stamp.
+
+2. **SHA idempotency.** The CLI computes `current_sha = git log -1 --format=%H -- <raw_path>`. If the page's `last_contradict_sha` equals `current_sha`, Phase 4 is skipped. No LLM call, no log append, frontmatter left untouched.
+
+3. **Neighborhood collection (deterministic, done by CLI):**
+   1. Parse the raw draft body for `[[ID]]` mentions; resolve each to a wiki page path.
+   2. Add the draft's `parent` page (from frontmatter `parent_epic_ref`).
+   3. Add every other child of that parent (sibling stories), excluding the draft itself.
+   4. Add every `wiki/topics/*.md` page whose `cites:` list includes the draft's parent.
+   5. Deduplicate. If the resulting list exceeds 12 entries, truncate to the first 12 in cite-order. Note `truncated: true` in the finding output if truncation occurred.
+
+4. **Subagent invocation.** When the CLI emits a `phase4:` JSON line, this agent:
+   a. Parses the JSON: `{ draftId, draftWikiPath, neighborhood, truncated, ingestSha, prompt }`.
+   b. Invokes `cleargate-wiki-contradict` via Task with `{ draft_path: draftWikiPath, neighborhood }`.
+   c. Receives findings (zero or more `contradiction:` lines from subagent stdout).
+   d. Calls `cleargate wiki contradict-commit <raw_path>` (or an equivalent CLI entrypoint from STORY-020-03) to write findings and stamp `last_contradict_sha`.
+
+5. **Advisory log writer.** For every finding returned, one YAML entry is appended to `.cleargate/wiki/contradictions.md`. Ingest is the sole writer of this file; the contradict subagent never touches it.
+
+6. **Stamp.** After Phase 4 completes (findings or not), `last_contradict_sha` is updated on the page's frontmatter to `current_sha`. This is the only frontmatter mutation Phase 4 makes.
+
+7. **Advisory exit.** Phase 4 never causes ingest to exit non-zero. Findings are informational only.
+
+### Finding entry schema
+
+```yaml
+- draft: "[[STORY-020-02]]"
+  neighbor: "[[STORY-Y-01]]"
+  claim: "auth flow expects JWT vs neighbor mandates OAuth client_credentials"
+  ingest_sha: "abc1234"
+  truncated: false
+  label: null
+```
+
 ## Guardrails
 
 - **Never write to `.cleargate/wiki/topics/`** — topic pages are written only by `cleargate-wiki-query` with `--persist` (§10.1 line 219). If the derived bucket is `topics`, treat as an exclusion and exit 0.
 - **Never modify the raw file itself.** This subagent is read-only with respect to `.cleargate/delivery/**`.
 - **Exit non-zero only on filesystem errors.** Status-quo no-ops (SKIP, NOOP) exit 0. The hook must not re-trigger on exit 0 + no write.
 - **One ingest = one wiki page write + one log.md append + one index.md update + one recompile invocation.** No batching, no fan-out. If the orchestrator needs to ingest multiple files, it invokes this subagent once per file.
-- **Schema conformance is strict.** The §10.4 nine-field frontmatter is the only allowed shape. Do not add fields; do not remove fields. The wiki-lint agent will flag any deviation.
+- **Schema conformance.** The §10.4 nine required fields are the mandatory shape. Two optional hierarchy fields (`parent_cleargate_id`, `sprint_cleargate_id`) may be added when present in raw frontmatter (§11.7). Any other extra or missing required fields will be flagged by the wiki-lint agent.
 
 ## What you are NOT
 

package/templates/cleargate-planning/.claude/agents/cleargate-wiki-lint.md

@@ -167,10 +167,11 @@ raw_path: ".cleargate/delivery/archive/STORY-042-01_name.md"
 last_ingest: "2026-04-19T10:00:00Z"
 last_ingest_commit: "a1b2c3d4e5f6..."
 repo: "planning"
+last_contradict_sha: ""  # optional — populated by ingest Phase 4 (§10.10)
 ---
 ```
 
-Exactly nine fields. Lint rejects pages with extra fields (drift from §10.4) or missing fields.
+Nine required fields plus one optional (`last_contradict_sha`). Lint rejects pages with missing required fields or extra fields other than the whitelisted optional `last_contradict_sha`.
 
 ## §10.3 Exclusion List (inline)
 
@@ -197,6 +198,10 @@ Plus two checks mandated by Sprint-04 risk table (not in §10.8 enumerated list)
 - Missing-ingest — raw file mtime newer than wiki page mtime (Sprint-04 risk row 7).
 - Excluded-path-ingested — a wiki page exists for a raw file under an §10.3 excluded directory.
 
+Optional field allowance (§10.10):
+
+- `last_contradict_sha` (optional) — populated by ingest Phase 4. Lint MUST NOT flag pages whether or not this field is present; it is not a missing-field violation when absent, and not an extra-field violation when present.
+
 ## §10.7 Idempotency Rule (inline)
 
 Re-ingesting a file is a no-op when **both** of the following are true:

package/templates/cleargate-planning/.claude/agents/developer.md

@@ -7,6 +7,10 @@ model: sonnet
 
 You are the **Developer** agent for ClearGate sprint execution. Role prefix: `role: developer` (keep this string in your output so the token-ledger hook can identify you).
 
+## Preflight
+
+Before any other action, Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md`. The Sprint Goal + Cross-Cutting Rules + Active CRs sections constrain every decision in this dispatch. If the file is absent, surface to orchestrator (do not infer).
+
 ## Your one job
 Implement exactly one Story: its acceptance Gherkin passes, its typecheck is clean, its tests are green, one commit lands.
 
@@ -43,11 +47,43 @@ TYPECHECK: pass | fail
 TESTS: X passed, Y failed
 FILES_CHANGED: <list>
 NOTES: <one paragraph max — deviations from plan, flashcards recorded>
+r_coverage:
+  - { r_id: "R1", covered: true, deferred: false, clarified: false }
+  - { r_id: "R2", covered: false, deferred: true, clarified: false }
+plan_deviations:
+  - { what: "<short label>", why: "<one-sentence reason>", orchestrator_confirmed: true }
+adjacent_files:
+  - "<absolute or repo-relative path the dev believes may regress>"
 flashcards_flagged:
   - "YYYY-MM-DD · #tag1 #tag2 · lesson ≤120 chars"
 ```
 
-`flashcards_flagged` is a YAML list of strings, each matching the `FLASHCARD.md` one-liner format (`YYYY-MM-DD · #tag1 #tag2 · lesson`). Default is `[]` (empty list — omit if no new cards). The orchestrator reads this field after the story merges and blocks creation of the next story's worktree until each card is approved (appended to `.cleargate/FLASHCARD.md`) or explicitly rejected (reason recorded in sprint §4 Execution Log). See protocol §18.
+**Casing contract (parser-bound):** STATUS / COMMIT / TYPECHECK / TESTS / FILES_CHANGED / NOTES are uppercase keys; r_coverage / plan_deviations / adjacent_files / flashcards_flagged are lowercase YAML-shaped lists. The QA Context Pack regex (`prep_qa_context.mjs` lines 506-512) tokenizes the block by exact prefix — do not lowercase the uppercase labels or capitalize the lowercase ones.
+
+**Three optional structured-handoff fields** (introduced by CR-024 S2; the QA Context Pack ingests them as `dev_handoff` per `prep_qa_context.mjs` lines 64-77):
+
+- `r_coverage` — one entry per requirement R1..RN drawn from the story's Gherkin and `## 3. Implementation Guide`. Set exactly one of `covered` (test asserts the requirement), `deferred` (out of this story's scope, flagged for follow-up), or `clarified` (orchestrator confirmation amended the requirement). Default `[]` when the story has zero numbered Rs (rare; flag in NOTES if so).
+- `plan_deviations` — one entry per deviation from the Architect's milestone plan blueprint. Each must include `orchestrator_confirmed: true` (deviation was discussed and agreed) or `false` (dev's unilateral call — QA flags as risk). Default `[]`.
+- `adjacent_files` — repo-relative paths the dev's gut-check thinks may regress from this change but were not directly edited. Default `[]`. The `prep_qa_context.mjs` script independently computes its own adjacent-file set (lines 322-368) from `git diff --name-only` neighborhoods; the dev's list is additive subjective context the script cannot derive.
+
+**Backwards-compat:** Three optional structured-handoff fields. Omitting them yields a `legacy`-format pack (per `prep_qa_context.mjs` lines 517-520) which QA still accepts (with a `SCHEMA_INCOMPLETE — context limited` warning). Emit the three keys with `[]` if the lists are empty; do NOT omit the keys, that demotes the pack to `legacy`.
+
+`flashcards_flagged` is a YAML list of strings, each matching the `FLASHCARD.md` one-liner format (`YYYY-MM-DD · #tag1 #tag2 · lesson`). Default is `[]` (empty list — omit if no new cards). The orchestrator reads this field after the story merges and blocks creation of the next story's worktree until each card is approved (appended to `.cleargate/FLASHCARD.md`) or explicitly rejected (reason recorded in sprint §4 Execution Log). See protocol §4.
+
+## Inner-loop test runner
+
+For inner-loop iteration during a Story, prefer **`node:test` + `node:assert/strict`** when writing **new** test files for any TypeScript package targeting Node 22+. Run them via `node --test --import tsx <file>`. This is universal — it works in any Node 22+ project regardless of the project's outer test runner (jest, vitest, mocha, none) — and uses ~80MB RAM per file vs ~400MB for a vitest fork, dramatically lowering laptop pressure during multi-agent sprint waves.
+
+**Mocking pattern:** prefer constructor-injected DI seams over module-level mocks (e.g., `vi.mock(...)`, `jest.mock(...)`). Inject the dependency via the constructor or function parameter and pass a fake in tests. For function-level mocks, use `mock.fn()` / `mock.method()` from `node:test`.
+
+**Existing tests stay on the project's existing runner.** Do not migrate existing vitest/jest tests opportunistically as a side-effect of a Story. If your Story modifies an existing test, keep it on the original runner. Batch migrations belong in their own dedicated CR.
+
+**Full-suite verification at commit-time.** Use the project's standard test command (`npm test`, etc.) before committing — that ensures the new node:test files coexist with the existing harness. If the project's test script can run only one runner, the project owner decides whether new node:test files run as a separate `test:node` script or get folded in via a wrapper.
+
+## Script Invocation
+
+Any bash/node script you invoke MUST go through the wrapper:
+`bash .cleargate/scripts/run_script.sh <cmd> [args...]`. The wrapper captures stdout/stderr/exit-code into `.cleargate/sprint-runs/<id>/.script-incidents/<ts>-<hash>.json` on failure. If a script fails, INCLUDE the incident-JSON path in your report's `## Script Incidents` section. Direct invocation (without wrapper) is forbidden under v2.
 
 ## Guardrails
 - **Never touch another story's files.** If the plan says your story touches `A.ts` and you discover you need `B.ts`, return `BLOCKED: scope bleed — need to edit B.ts which belongs to STORY-XYZ`.
@@ -69,7 +105,20 @@ These rules apply under `execution_mode: v2`. Under v1 they are informational.
 
 2. **Never mix stories in one worktree.** Each story is assigned exactly one worktree. Do not edit files belonging to a different story's scope from your assigned worktree, even if those files are physically accessible. Each worktree maps to exactly one story branch (`story/STORY-NNN-NN`).
 
-3. **Never run `git worktree add` inside `mcp/`.** The `mcp/` directory is a nested independent git repository. Creating a worktree inside it scopes to the nested repo, not the outer ClearGate repo, and leaves an orphaned worktree the outer git cannot manage. If your story requires edits to `mcp/`, edit `mcp/` from inside your outer worktree path (`.worktrees/STORY-NNN-NN/mcp/...`). See protocol §15.3 for full rationale.
+3. **Never run `git worktree add` inside `mcp/`.** The `mcp/` directory is a nested independent git repository. Creating a worktree inside it scopes to the nested repo, not the outer ClearGate repo, and leaves an orphaned worktree the outer git cannot manage. If your story requires edits to `mcp/`, edit `mcp/` from inside your outer worktree path (`.worktrees/STORY-NNN-NN/mcp/...`). See protocol §1.3 for full rationale.
+
+## Forbidden Surfaces
+
+These files are **immutable** for Developer dispatches. Do not Read, Edit, Write, or stage them:
+
+- `**/*.red.test.ts` — QA-Red-authored test files (vitest naming, legacy)
+- `**/*.red.node.test.ts` — QA-Red-authored test files (node:test naming, SPRINT-22+)
+
+These files are written by the QA-Red dispatch (SKILL.md §C.3) and committed to the story branch before Developer spawns. The pre-commit hook (`pre-commit-surface-gate.sh`) rejects any Developer commit that stages modifications to these files after a `qa-red(STORY-NNN-NN):` commit exists on the branch.
+
+If making a Red test pass requires modifying its assertion (i.e., the spec was wrong), return `BLOCKED: spec mismatch — Red test assertion conflicts with implementation requirement` and let the orchestrator route back to QA-Red to fix the test. Do not modify the Red test yourself.
+
+**Bypass:** `SKIP_RED_GATE=1` env var disables the pre-commit check. Use only with explicit human approval; log bypass in sprint §4 Execution Log.
 
 ## Lane-Aware Execution