cleargate 0.8.2 → 0.10.0

package/dist/templates/cleargate-planning/CLAUDE.md

@@ -7,32 +7,45 @@ This file is the content `cleargate init` injects into a downstream user's `CLAU
 <!-- CLEARGATE:START -->
 ## 🔄 ClearGate Planning Framework
 
-This repository uses **ClearGate** — a standalone planning framework for AI coding agents. ClearGate scaffolds *how work is planned* (proposals → epics → stories → sprints) and defines a four-agent loop for execution. ClearGate does not run builds, tests, or deployments; execution tooling remains the target repo's own.
+This repository uses **ClearGate** — a standalone planning framework for AI coding agents. ClearGate scaffolds *how work is planned* (initiatives → epics → stories → sprints) and defines a four-agent loop for execution. ClearGate does not run builds, tests, or deployments; execution tooling remains the target repo's own.
 
 **Session-start orientation (read in this order):**
 1. `.cleargate/wiki/index.md` — compiled awareness layer (~3k tokens). Lists active sprint, in-flight items, recent shipments, open gates, planned work, and topic synthesis pages. **Read this first** to know what exists before grepping raw files. If absent, run `cleargate wiki build`.
 2. `.cleargate/knowledge/cleargate-protocol.md` — delivery protocol (non-negotiable rules).
 3. `.cleargate/FLASHCARD.md` — lessons tagged by topic (`#schema`, `#auth`, etc.). Grep for your area before starting.
+4. `.cleargate/knowledge/cleargate-enforcement.md` — hook-enforced rules (worktree mechanics, file-surface contract, lifecycle reconciler, lane rubric, doctor exit codes, etc.). Read only when a CLI hook surfaces an error or when triaging a v2-mode question.
 
 **Triage first, draft second.** Every user request gets classified (Epic / Story / CR / Bug / Pull / Push) *before* any drafting. If the type is ambiguous, ask ONE targeted question — do not guess.
 
-**Duplicate check before drafting.** Before drafting a Proposal or work item, grep `.cleargate/delivery/archive/` + `.cleargate/FLASHCARD.md` for similar past work. If you find overlap, surface it as a one-liner (*"This is very close to STORY-003-05 shipped in SPRINT-01 — are you extending it or redoing it?"*) instead of drafting a duplicate.
+**Sprint execution.** When a sprint is active, the orchestration playbook lives at `.claude/skills/sprint-execution/SKILL.md` — load it before dispatching any execution agent (Architect / Developer / QA / Reporter). The skill is the canonical four-agent-loop spec; the always-on CLAUDE.md keeps only the halt-rules and the load-skill contract.
 
-**Halt at gates.** You halt at Gate 1 (Proposal approval) and Gate 2 (Ambiguity resolution) and wait for explicit human sign-off. You never call `cleargate_push_item` without `approved: true` (hard reject) and explicit human confirmation. Readiness gates (`cached_gate_result.pass`) are advisory by default — the push proceeds and the item body receives an `[advisory: gate_failed — <criteria>]` prefix; opt into hard-reject via `STRICT_PUSH_GATES=true` on the MCP server.
+**Skill auto-load directive.** When the SessionStart banner emits `Load skill: <name>`, invoke the Skill tool to load it before continuing. Claude Code's description-match auto-load is advisory; this rule is the contract.
+
+**Codebase is source of truth.** Wiki, memory, and `context_source` are derived caches. On conflict between cache and code, the code wins; the cache rebuilds. Before stating that a capability exists or doesn't exist, grep the code.
+
+**Duplicate check before drafting.** Before drafting an Initiative or work item, grep `.cleargate/delivery/archive/` + `.cleargate/FLASHCARD.md` for similar past work. If you find overlap, surface it as a one-liner (*"This is very close to STORY-003-05 shipped in SPRINT-01 — are you extending it or redoing it?"*) instead of drafting a duplicate. If the request names an integration, feature, or capability, also grep the source tree for existing implementations and cite findings in `## Existing Surfaces`.
+
+**Halt at gates.** You halt at Gate 1 (Initiative approval) and Gate 2 (Ambiguity resolution) and wait for explicit human sign-off. You never call `cleargate_push_item` without `approved: true` (hard reject) and explicit human confirmation. Readiness gates (`cached_gate_result.pass`) are advisory by default — the push proceeds and the item body receives an `[advisory: gate_failed — <criteria>]` prefix; opt into hard-reject via `STRICT_PUSH_GATES=true` on the MCP server.
+
+**Sprint mode.** Read `execution_mode:` in the active sprint's frontmatter before spawning Developer/QA. `v1` = advisory; `v2` = enforce the rules in `cleargate-enforcement.md`. Default `v1`.
+
+**Brief is the universal pre-push handshake.** Every work-item template's `<instructions>` block tells you to render a Brief in chat after Writing the document — Summary / Open Questions / Edge Cases / Risks / Ambiguity. Halt for human review. When ambiguity reaches 🟢, push via `cleargate_push_item` automatically — the same approval covers Gate 1 and the push.
+
+**Boundary gates (CR-017).** `cleargate sprint init` runs the decomposition gate; `close_sprint.mjs` runs the lifecycle reconciler. Both block in v2.
+
+**Sprint close is Gate-4-class (CR-019).** Run `close_sprint.mjs` with no flags first; surface the prompt verbatim; halt. Never pass `--assume-ack` autonomously. Pre-close enforces Steps 2.7 (no leftover worktrees) + 2.8 (sprint branch merged to main) under v2; failure halts close. Post-close prints a 6-item handoff list (Step 8) summarizing commits, merge state, wiki ingest, flashcards, artifacts, and next-sprint preflight.
 
 **Drafting work items:**
-- Use the templates in `.cleargate/templates/` (`proposal.md`, `epic.md`, `story.md`, `CR.md`, `Bug.md`, `Sprint Plan Template.md`, `initiative.md`).
+- Use the templates in `.cleargate/templates/` (`epic.md`, `story.md`, `CR.md`, `Bug.md`, `Sprint Plan Template.md`, `initiative.md`).
 - Save drafts to `.cleargate/delivery/pending-sync/{TYPE}-{ID}-{Name}.md`.
 - After `cleargate_push_item` returns a Remote ID, update the frontmatter AND move the file to `.cleargate/delivery/archive/` — these two happen atomically, never one without the other.
 - **Story granularity.** When decomposing an epic into stories, run the Granularity Rubric at the top of `story.md`. If a candidate story trips any signal (unrelated goals joined, >5 Gherkin scenarios, subsystems span, L4 complexity), emit two stories with consecutive IDs instead. Splits and merges are free at decomposition time — no remote IDs exist yet.
 
-**Four-agent loop (roles in `.claude/agents/`):**
-- `architect.md` — one plan per milestone; no production code.
-- `developer.md` — one Story end-to-end; one commit per Story; runs typecheck + tests before commit.
-- `qa.md` — independent verification gate; re-runs checks; never commits, never edits.
-- `reporter.md` — one sprint retrospective at sprint end; synthesizes token ledger + git log + flashcards into `REPORT.md`.
+**Initiative Intake.** Stakeholder input arrives via two paths: (1) MCP pull — call `cleargate_pull_initiative` with the remote ID; the tool writes `pending-sync/INITIATIVE-NNN_*.md` automatically; read the result and present a Brief. (2) Manual paste — human pastes the text; triage it, write `pending-sync/INITIATIVE-NNN_*.md` using `templates/initiative.md`, present a Brief. In both cases, after Gate 1 the file moves to `archive/` stamped with `triaged_at:` and `spawned_items:`.
+
+**State-aware surface.** At session start, `cleargate doctor --session-start` (invoked by the SessionStart hook) emits one banner line before any other output: `ClearGate state: pre-member — local planning enabled, sync requires join.` OR `ClearGate state: member (project: <project_id>) — full surface enabled.` In **pre-member** state (no valid join token on disk), only local-planning commands are reachable: `init`, `join`, `whoami`, `wiki *`, `gate *`, `stamp`, `doctor`, `scaffold-lint`, `sprint *`, `story *`, `state *`, `upgrade`, `uninstall`. Commands `push`, `pull`, `sync`, `sync-log`, `conflicts`, and `admin *` (except `admin login`) require membership and exit 2 with a redirect: `Run: cleargate join <invite-url>`. If the SessionStart banner says `pre-member`, do not suggest push/pull/sync to the user — instead ask for an invite URL and direct them to `cleargate join`.
 
-**Conversational style.** Keep replies terse. Details live in the work-item file and `REPORT.md`, not in chat. State results and next steps; skip narration of your own thought process.
+**Conversational style.** Keep replies terse. Details live in the work-item file and `REPORT.md`, not in chat. State results and next steps; skip narration of your own thought process. After Writing or Editing any file under `.cleargate/delivery/**`, briefly note the ingest result if the PostToolUse hook surfaced one — one short sentence (`✅ ingested as <bucket>/<id>.md` / `⚠️ gate failed: <criterion>` / `🔴 ingest error — see .cleargate/hook-log/gate-check.log`). Do not narrate when nothing fired (skip-excluded paths). This is conversational confirmation, not retry logic.
 
 **Support infrastructure.** Flashcard protocol: `.claude/skills/flashcard/SKILL.md`. Token-ledger hook: `.claude/hooks/token-ledger.sh`, wired via `.claude/settings.json` (SubagentStop) — auto-logs agent cost per sprint for the Reporter.
 
@@ -41,4 +54,9 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 **Project overrides.** Content OUTSIDE this `<!-- CLEARGATE:START -->...<!-- CLEARGATE:END -->` block takes precedence where it conflicts with ClearGate defaults.
 
 **Scope reminder.** ClearGate is a *planning* framework. It scaffolds how work gets planned and how the four-agent loop runs. It does not replace your project's build system, CI, test runner, or deployment tooling.
+
+**Guardrails for the conversational agent:**
+- Sprint close requires explicit human ack. Run close_sprint.mjs without flags first; surface the "re-run with --assume-ack" prompt verbatim and halt. Never pass --assume-ack yourself — that flag is reserved for automated tests.
+
+**Doc & metadata refresh on close.** During Gate 4 ack, read `.cleargate/sprint-runs/<id>/.doc-refresh-checklist.md` (generated by `prep_doc_refresh.mjs`) and apply or punt each `- [ ]` item per the canonical list at `.cleargate/knowledge/sprint-closeout-checklist.md`. Items already marked `- [x]` indicate "no changes detected, skip."
 <!-- CLEARGATE:END -->

package/dist/templates/cleargate-planning/MANIFEST.json

@@ -1,24 +1,31 @@
 {
-  "cleargate_version": "0.8.2",
-  "generated_at": "2026-04-27T09:39:12.477Z",
+  "cleargate_version": "0.10.0",
+  "generated_at": "2026-05-02T19:21:41.996Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
-      "sha256": "297020d3344d9122c0ff95e00b436cb83640acbc78377684c04f6af8fb6fbcc4",
+      "sha256": "5aa58a549f74ecc73be1630428ef1903faae5c3779b7b5371307c5cb63621026",
+      "tier": "agent",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".claude/agents/cleargate-wiki-contradict.md",
+      "sha256": "1b7ca28889dfa1ab704e05b90179547bee1ae683b68722c99a1daec990e8572b",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/cleargate-wiki-ingest.md",
-      "sha256": "6dcd13bb9c8daeac083e2e2f34eebc56dbd3a9f3e6e0025bc3db558937fcff36",
+      "sha256": "4b14aed168d30807a1325de8c065bb57e2bc66271a0cffc71a21481c227b453b",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/cleargate-wiki-lint.md",
-      "sha256": "97d930aa906e350ce7975bc0cf17cd6870aea2b636ef482b33ffc638cdba931a",
+      "sha256": "42067fd728e64ac1ff1ace5822b8f8c3ddf1ba70fd0fbddf0e8cb19d5d699e77",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -32,21 +39,21 @@
     },
     {
       "path": ".claude/agents/developer.md",
-      "sha256": "602b8ef4ca0f8bc11472a612744535d1a6794533ceaf97587d5d421c4fc49b77",
+      "sha256": "55790014320187e500f6b904756bbc8bda4806274805e883d62492bf75a34f12",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/qa.md",
-      "sha256": "e753d294d6060ace626878220db02a0595126bc7baa52526e5d1576b163f04d0",
+      "sha256": "b6ac9d814e1bbd1fb9a062ce7775e34da1d1e5e6fc35140b977f30b2632654fa",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/reporter.md",
-      "sha256": "c2f6e9db07c737ada4c2f76497d08e0f881bc8f0fceb073b9479753d33c4ecf4",
+      "sha256": "d8e11e0a5eeb7bf298df2e79ce0f6b8b4d87e3a2d6666f458ae143ef8e593ea1",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -86,9 +93,16 @@
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
+    {
+      "path": ".claude/hooks/pre-tool-use-task.sh",
+      "sha256": "79fdd30e3f301cb89757aa2279a5fb8cc3a91493b62d5c801517853500368e7f",
+      "tier": "hook",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".claude/hooks/session-start.sh",
-      "sha256": "77c206eeaa5d460f9e751244f25ff09089578ad4d044487cbcff8b3e1d78582f",
+      "sha256": "b266a5567cc84c02d041e570569962c003daaa69b6aee244173e740dedbf4ee2",
       "tier": "hook",
       "overwrite_policy": "pin-aware",
       "preserve_on_uninstall": false
@@ -102,14 +116,14 @@
     },
     {
       "path": ".claude/hooks/token-ledger.sh",
-      "sha256": "45113b3c3f3a78e350e112665c1aadf74a246bb4ebfe514ea7230d6bd3fa01c1",
+      "sha256": "b766f18e005dea89d63c2dae9c436e3e52ef0e4828ea895ce94abfecc68f0ce2",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/settings.json",
-      "sha256": "539345bf59249e645a2b5faeb9cc4f44deb657ac77e9833ef74f7e4a1f4c6e3b",
+      "sha256": "8c3c8fe2bd2a2c23e3faa56fad94352c66a11646d12a4ca79ff95d578e589ec0",
       "tier": "cli-config",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -121,6 +135,13 @@
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
+    {
+      "path": ".claude/skills/sprint-execution/SKILL.md",
+      "sha256": "f403bb55f4cdce4b82ce3fdd59b03dd55d8f3f64bdc0e1d1c2abf9b2121efa3d",
+      "tier": "skill",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".cleargate/FLASHCARD.md",
       "sha256": null,
@@ -128,65 +149,275 @@
       "overwrite_policy": "skip",
       "preserve_on_uninstall": true
     },
+    {
+      "path": ".cleargate/knowledge/cleargate-enforcement.md",
+      "sha256": "11ff8004145d627ce3885976304797465e07ea80f2e37001304afa9087852e7f",
+      "tier": "protocol",
+      "overwrite_policy": "merge-3way",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".cleargate/knowledge/cleargate-protocol.md",
-      "sha256": "a3d02a7e6660403370568f3e412990a6e44394e65040ce21adc5f8e4269946ca",
+      "sha256": "50e999717b9c9e1c11638f3f2433f413d177ed8ddf3cffdbb20b50c8807b1fc5",
       "tier": "protocol",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/knowledge/readiness-gates.md",
-      "sha256": "d7a79a50e3cb5fd42735b017d3d88dff0fa443444951e717013e423770bad87b",
+      "sha256": "6125b57bfdcdd5d4fabe886770d9b062d76df9a232f4997dbedf3322aefdf1b5",
       "tier": "protocol",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
+    {
+      "path": ".cleargate/knowledge/sprint-closeout-checklist.md",
+      "sha256": "d44f57445188bdefb18b39c6c121a1f52d32d9ca6122df91e54855e87fc2233e",
+      "tier": "protocol",
+      "overwrite_policy": "merge-3way",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/assert_story_files.mjs",
+      "sha256": "74db9e12008492e40c77cc9bffac4c689621ac5eededf9b342a87e45f918f003",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/close_sprint.mjs",
+      "sha256": "d02be1cb8e0290782197a8b775c52b8f3064aaf661f5466c218dadb62179690a",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/constants.mjs",
+      "sha256": "6f3fd11046bfd3d7f6b90b9ca70e02612a5db05ca21f2f2db3dce4473e720ce4",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/dedupe_frontmatter.mjs",
+      "sha256": "6bf2816399cad2ab6f8f770de5eb920c3547b6fad9295c81f08aa6a4f894ef21",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/file_surface_diff.sh",
+      "sha256": "a1c250ba35face9124183273fb04d45fdd4f8e43f405be4a765aeb58582753e9",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/gate-checks.json",
+      "sha256": "188ef9995ce14e609ecf042563bab44d461df5315a4fd698e3eebfaf84db3b6a",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/init_gate_config.sh",
+      "sha256": "47f4a9c6609d22d66acc9ccbceb1a144ad590d5ed17159ae5fb9811002a087e8",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/init_sprint.mjs",
+      "sha256": "1d0f41df4325ea32981256aec15ed43eef09aba2a16ab4ba6d310cd61685556e",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/lib/report-filename.mjs",
+      "sha256": "c26e2c0557f5e33d84058fc34db5c3258e5050093eabeb09fb22d067e458a8e2",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/pre_gate_common.sh",
+      "sha256": "fd9af416b6db636901354fca64e60adcce9d4ce71dac96f2d718562a4bdb27e0",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/pre_gate_runner.sh",
+      "sha256": "7f221089a353391f6e917c03a6813a26b6650a8b4e7e1c6a2bd845fa4ae081ca",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/prefill_report.mjs",
+      "sha256": "bee417d96150410f78262a7fb4f485bf2f2e4191b8818085bdf60a664ebf7d62",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/prep_doc_refresh.mjs",
+      "sha256": "822f887fc6c2754d2314f72b8ae62e1f20707b350b04c9867f9fd65068b21d79",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/prep_qa_context.mjs",
+      "sha256": "68d69678f72fd6aa64bcf359fbd74f9c5b6b4fe598374f13c1261148b9907cab",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/run_script.sh",
+      "sha256": "63ff100bb56361b06825d20dc601975e6df32bb688fe112b0d705dc45129ca20",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/sprint_trends.mjs",
+      "sha256": "58732d158dcffca71fdc935200bbf9f8f14058cec7e05590345c335151dfa156",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/state.schema.json",
+      "sha256": "d4e1c076764e5dc0573805502b3164d3b7d4977871cb67f5eca8a5035aeee37d",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/suggest_improvements.mjs",
+      "sha256": "7d5853bf477447ae9090485648c3ba9426419504c6d36626c32454bf578c74a6",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/surface-whitelist.txt",
+      "sha256": "c1c14349265d741570dc4b0e61501c2a9e898a25cefad93911ef1298cf4d74c7",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/test_ratchet.mjs",
+      "sha256": "429f6034ad6946f906c9068e9604d5348898687af0cf56badcae673b04369c5b",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/test/test_assert_story_files.sh",
+      "sha256": "6aace15a0de4d07b4b9e7454d2b38e266b7a80e265281135a050bd9f6be83aab",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/test/test_file_surface.sh",
+      "sha256": "ada0e9583717a38bd912c0af16bb0e11c0b719a96df6dd511c879f0cf367788d",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/test/test_flashcard_gate.sh",
+      "sha256": "0e05a7fbaa86aeb9401e7df09696b9c547896512c41aa738a7c812d69d135916",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/test/test_prep_qa_context.sh",
+      "sha256": "fd198bbc5d1faeaebd18ac72e5bcc2d84f931f035175bd51048ee04dcbd7ae0d",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/test/test_test_ratchet.sh",
+      "sha256": "bfa13cb347824a525b636538d330a3ee3765f7908707f94149f2ffe69439729b",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/update_state.mjs",
+      "sha256": "19eb2a3f7b0cc027a2805a49ba14029bcb70dbc8e98299375a375a6fe4adf2c5",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/validate_bounce_readiness.mjs",
+      "sha256": "e4c6bead578a75a4f62fddbc1bccd40e92cc64f6136b3f893bb7cf50bacbd6ff",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/validate_state.mjs",
+      "sha256": "a1ad7e5f0525d3302759f9a04514e7205141c124abeb42fcda1f9d6042eca926",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/scripts/write_dispatch.sh",
+      "sha256": "4af4035555f4c6852ffd8f4635734931cfa2baef706f27f001bf0b2c64f7a0be",
+      "tier": "script",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".cleargate/templates/Bug.md",
-      "sha256": "54660457a8b7f5c9f1a286993e2d83d46fef880a3d65086421d8db815a9c01ec",
+      "sha256": "d58c3d5d19387e7749c62570931a829fd1fc31bda83b6edba2b0854dafd6936d",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/CR.md",
-      "sha256": "e4cff0314217d649177a3dd1603c510d2f5246c1cf297baaa91d5941c1eedc91",
+      "sha256": "434ac96bfd9aa8732a89d18ceb546101737b2b6fdc1b3858b5ea0153837bc6ee",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/epic.md",
-      "sha256": "fa0e5bf85b50bee11d38646b2606652999ac2ff7c649810408c35ff25d7a025c",
+      "sha256": "bbb250b5ca905ed6f48b55b0c982296899d04a492f9427195960cee3e3632594",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/hotfix.md",
-      "sha256": "93c6690a23bcfca98697048b7f1c2c5c76ee16c2d295a53ced8471e8c4eb78d3",
+      "sha256": "2d4fe14f12dbdae75cd8298bc547f39da89ecc9aaf917d32b3298a9b4936aaa2",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/initiative.md",
-      "sha256": "9bf4a5a5ff7af0938ff48d5eaa182f227195d101ba9de4d56123b4fc211b8cac",
-      "tier": "template",
-      "overwrite_policy": "merge-3way",
-      "preserve_on_uninstall": false
-    },
-    {
-      "path": ".cleargate/templates/proposal.md",
-      "sha256": "227907f5de028453168c487e9c4ec4d4acd578298d13d658f7a7b63ef76dc23d",
+      "sha256": "08730306824f184a7d972346640493f100a5d1b44f0efe0ed855e1acedfd65d6",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/Sprint Plan Template.md",
-      "sha256": "583f71c76c0b3c8cb219183f5881250219cec2719c909abf4d3069beed8cad51",
+      "sha256": "8c359d0d7d06706cbae4c7c28777229ca3f8c4e1cc819795b4d39b349acbe9c1",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -200,14 +431,14 @@
     },
     {
       "path": ".cleargate/templates/sprint_report.md",
-      "sha256": "e73126842e219d856d32c4cb72e0a98066ea9ad4993e3f3919f9c8296d73afdf",
+      "sha256": "84e32e956eb1e8a9c97be1c346b695df316a9e47e17402f3d6581e3ffdbc4d2d",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/story.md",
-      "sha256": "0817454195b1c3ddb7a2559a0295273082fb621cdfd7a77594414876da28c620",
+      "sha256": "a1413c4af5d854163741e92575fb913b93bdac1c1b7cfc59be8c3e0c8780eac0",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false

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,6 +1,6 @@
 {
   "name": "cleargate",
-  "version": "0.8.2",
+  "version": "0.10.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.",
@@ -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"

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

@@ -17,6 +17,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 +29,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.
@@ -137,12 +139,12 @@ 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`.
 
 ## 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