cleargate 0.10.0 → 0.11.0

package/dist/templates/cleargate-planning/.cleargate/scripts/validate_state.mjs

@@ -19,11 +19,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
 /**
- * Validate a parsed state object.
+ * Validate a parsed state object, ignoring schema_version check.
+ * Used PRE-MIGRATION so that v1 files pass shape validation before being upgraded.
  * @param {object} state - Parsed state.json content
  * @returns {{ valid: boolean, errors: string[] }}
  */
-export function validateState(state) {
+export function validateShapeIgnoringVersion(state) {
   const errors = [];
 
   if (typeof state !== 'object' || state === null) {
@@ -31,12 +32,6 @@ export function validateState(state) {
     return { valid: false, errors };
   }
 
-  if (state.schema_version !== SCHEMA_VERSION) {
-    errors.push(
-      `schema_version mismatch: expected ${SCHEMA_VERSION}, got ${state.schema_version}`
-    );
-  }
-
   if (!state.sprint_id) {
     errors.push('missing required field: sprint_id');
   }
@@ -98,6 +93,35 @@ export function validateState(state) {
   return { valid: errors.length === 0, errors };
 }
 
+/**
+ * Validate a parsed state object (strict — includes schema_version check).
+ * Call this AFTER migration to assert the file is fully v2-compliant.
+ * @param {object} state - Parsed state.json content
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateState(state) {
+  const errors = [];
+
+  if (typeof state !== 'object' || state === null) {
+    errors.push('state is not an object');
+    return { valid: false, errors };
+  }
+
+  if (state.schema_version !== SCHEMA_VERSION) {
+    errors.push(
+      `schema_version mismatch: expected ${SCHEMA_VERSION}, got ${state.schema_version}`
+    );
+  }
+
+  // Delegate shape validation (everything except version check)
+  const shapeResult = validateShapeIgnoringVersion(state);
+  for (const e of shapeResult.errors) {
+    errors.push(e);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
 // CLI mode
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const args = process.argv.slice(2);

package/dist/templates/cleargate-planning/.cleargate/scripts/write_dispatch.sh

@@ -17,7 +17,7 @@
 #
 # Args:
 #   $1  work_item_id  — e.g. STORY-020-02, CR-016, BUG-021
-#   $2  agent_type    — one of: developer|architect|qa|reporter|cleargate-wiki-contradict
+#   $2  agent_type    — one of: developer|architect|qa|reporter|devops|cleargate-wiki-contradict
 #
 # Env (optional):
 #   CLAUDE_SESSION_ID         — session UUID of the orchestrator session
@@ -49,6 +49,17 @@ fi
 WORK_ITEM_ID="${1}"
 AGENT_TYPE="${2}"
 
+# ─── Validate agent_type ────────────────────────────────────────────────────
+case "${AGENT_TYPE}" in
+  developer|architect|qa|reporter|devops|cleargate-wiki-contradict)
+    ;;
+  *)
+    printf '[%s] error: invalid agent_type: %s\n' "$(date -u +%FT%TZ)" "${AGENT_TYPE}" >> "${LOG}"
+    printf 'error: invalid agent_type: %s (expected developer|architect|qa|reporter|devops|cleargate-wiki-contradict)\n' "${AGENT_TYPE}" >&2
+    exit 3
+    ;;
+esac
+
 # ─── Resolve active sprint ──────────────────────────────────────────────────
 ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
 if [[ ! -f "${ACTIVE_SENTINEL}" ]]; then

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

@@ -12,6 +12,7 @@ POST-WRITE BRIEF
 After Writing this document, render a Brief in chat with the following sections,
 mechanically extracted from the document's own structure:
 
+  - Prior work    ← cleargate-wiki-query result (cite [[IDs]] or write "none found")
   - Summary        ← §1 The Anomaly (repro)
   - Open Questions ← §0.5 Open Questions
   - Edge Cases     ← §2 Impact (edge conditions)
@@ -106,6 +107,8 @@ last_synced_body_sha: null # sha256 of body at last sync
 ## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
 **Current Status: 🔴 High Ambiguity**
 
+*Evaluate each criterion against its literal text. If you substituted an interpretation, leave the box unchecked and surface the substitution in the Brief.*
+
 Requirements to pass to Green (Ready for Fix):
 - [ ] Reproduction steps are 100% deterministic.
 - [ ] Actual vs. Expected behavior is explicitly defined.

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

@@ -12,6 +12,7 @@ POST-WRITE BRIEF
 After Writing this document, render a Brief in chat with the following sections,
 mechanically extracted from the document's own structure:
 
+  - Prior work    ← cleargate-wiki-query result (cite [[IDs]] or write "none found")
   - Summary        ← §1 The Context Override
   - Open Questions ← §0.5 Open Questions
   - Edge Cases     ← §2 Blast Radius & Invalidation
@@ -108,6 +109,8 @@ last_synced_body_sha: null # sha256 of body at last sync
 ## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
 **Current Status: 🔴 High Ambiguity**
 
+*Evaluate each criterion against its literal text. If you substituted an interpretation, leave the box unchecked and surface the substitution in the Brief.*
+
 Requirements to pass to Green (Ready for Execution):
 - [ ] "Obsolete Logic" to be evicted is explicitly declared.
 - [ ] All impacted downstream Epics/Stories are identified and reverted to 🔴 High Ambiguity.

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

@@ -16,6 +16,7 @@ POST-WRITE BRIEF
 After Writing this document, render a Brief in chat with the following sections,
 mechanically extracted from the document's own structure:
 
+  - Prior work       ← cleargate-wiki-query result (cite [[IDs]] or write "none found")
   - Summary          ← §1 Problem & Value
   - Open Questions   ← §6 AI Interrogation Loop
   - Edge Cases       ← §2 OUT-OF-SCOPE list + §5 error scenarios
@@ -153,6 +154,8 @@ Feature: {Epic Name}
 ## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
 **Current Status: 🔴 High Ambiguity**
 
+*Evaluate each criterion against its literal text. If you substituted an interpretation, leave the box unchecked and surface the substitution in the Brief.*
+
 Requirements to pass to Green (Ready for Coding Agent):
 - [ ] Proposal document has `approved: true`.
 - [ ] The `<agent_context>` block is complete and validated.

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

@@ -14,6 +14,7 @@ POST-WRITE BRIEF
 After Writing this document, render a Brief in chat with the following sections,
 mechanically extracted from the document's own structure:
 
+  - Prior work    ← cleargate-wiki-query result (cite [[IDs]] or write "none found")
   - Summary        ← §1 Anomaly (Problem)
   - Open Questions ← §0.5 Open Questions
   - Edge Cases     ← §3 Files Affected (risk of adjacent regression)
@@ -101,6 +102,8 @@ If the hotfix introduces a regression, revert by running `git revert <commit-sha
 ## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
 **Current Status: 🔴 High Ambiguity**
 
+*Evaluate each criterion against its literal text. If you substituted an interpretation, leave the box unchecked and surface the substitution in the Brief.*
+
 Requirements to pass to Green (Ready for Merge):
 - [ ] Anomaly is deterministically reproducible (§1 filled).
 - [ ] Files Touched list is ≤2 files (§2 filled).

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

@@ -26,7 +26,7 @@ DO NOT output these instructions in the rendered file.
 </instructions>
 
 ---
-initiative_id: "INIT-{NNN}"
+initiative_id: "INITIATIVE-{NNN}"
 remote_id: null
 source_tool: "linear | jira | github | manual-paste"
 status: "{PM native status — e.g. Discovery, In Triage, Triaged}"

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

@@ -8,6 +8,10 @@ last_updated: "YYYY-MM-DDTHH:MM:SSZ"
 
 Per-sprint audit artefact. Populated at sprint init (M1 planning) and re-touched after each story merges. Referenced from every Developer/QA/Architect task brief so all agents start from the same baseline.
 
+## Sprint Goal
+
+_(populated by orchestrator from sprint plan §0 at kickoff)_
+
 ## Locked Versions
 
 Frozen dependency versions for this sprint. Orchestrator populates from `package.json` snapshots at sprint init; Developers must not upgrade these mid-sprint without an explicit CR.
@@ -40,3 +44,7 @@ Exported helpers and modules from already-merged stories in this sprint. The Arc
 | Story | Module / Export | Path |
 |-------|----------------|------|
 | (populated as stories merge) | | |
+
+## Mid-Sprint Amendments
+
+_(populated by Architect on CR:scope-change or CR:approach-change; never rewrite, only append. Format: '<ISO-ts> · <ID> · <one-line note>')_

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

@@ -40,6 +40,7 @@ POST-WRITE BRIEF
 After Writing this document, render a Brief in chat with the following sections,
 mechanically extracted from the document's own structure:
 
+  - Prior work    ← cleargate-wiki-query result (cite [[IDs]] or write "none found")
   - Summary        ← §1.1 User Story
   - Open Questions ← §1.4 Open Questions
   - Edge Cases     ← §2.1 Gherkin error scenarios
@@ -199,6 +200,8 @@ Feature: {Story Name}
 ## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
 **Current Status: 🔴 High Ambiguity**
 
+*Evaluate each criterion against its literal text. If you substituted an interpretation, leave the box unchecked and surface the substitution in the Brief.*
+
 Requirements to pass to Green (Ready for Execution):
 - [ ] Gherkin scenarios completely cover all detailed requirements in §1.2.
 - [ ] Implementation Guide (§3) maps to specific, verified file paths from the approved proposal.

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

@@ -23,12 +23,14 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 
 **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`.
+**Duplicate check before drafting.** Before Writing any new file under `.cleargate/delivery/pending-sync/`, dispatch the `cleargate-wiki-query` subagent with the request topic. Record the result (`[[IDs]]` of related prior work, or `none found`) on a `Prior work:` line in the Brief — this is auditable evidence the check ran. Then grep `.cleargate/delivery/archive/` + `.cleargate/FLASHCARD.md` for residual hits the wiki may have missed (raw items not yet ingested). If the request names an integration, feature, or capability, also grep the source tree for existing implementations and cite findings in `## Existing Surfaces`. 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?"*) before drafting.
 
 **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`.
 
+**Ambiguity Gate criteria are evaluated literally.** Each `[ ]` box in a work-item's Ambiguity Gate footer must be evaluated against the literal criterion text, not against your interpretation of its intent. If a criterion is not met but you believe the human's intent is satisfied, leave the box unchecked, say so explicitly in the Brief, and ask. Do not substitute "in spirit" satisfaction for literal satisfaction. The gate exists specifically to catch the case where you are about to declare 🟢 by interpretive leap.
+
 **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.

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

@@ -1,10 +1,10 @@
 {
-  "cleargate_version": "0.10.0",
-  "generated_at": "2026-05-02T19:21:41.996Z",
+  "cleargate_version": "0.11.0",
+  "generated_at": "2026-05-04T21:55:12.920Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
-      "sha256": "5aa58a549f74ecc73be1630428ef1903faae5c3779b7b5371307c5cb63621026",
+      "sha256": "a2d11d6a7f21bce22730ba9076af9ddde44b258082e33aa99fcd57c14ad75f55",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -39,21 +39,28 @@
     },
     {
       "path": ".claude/agents/developer.md",
-      "sha256": "55790014320187e500f6b904756bbc8bda4806274805e883d62492bf75a34f12",
+      "sha256": "36f75fe9f8dc8412eb22706dfd021f5db5694c81d73e0c938e701a83c0149126",
+      "tier": "agent",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".claude/agents/devops.md",
+      "sha256": "65e84275b7a6480be2144250cc00573e8c26840abed98768ce4c168d594c7f8e",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/qa.md",
-      "sha256": "b6ac9d814e1bbd1fb9a062ce7775e34da1d1e5e6fc35140b977f30b2632654fa",
+      "sha256": "c6fab6b64acc717a6bb5618531e6568010b3aeb10a98e33ba10b8dde45f5becb",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/reporter.md",
-      "sha256": "d8e11e0a5eeb7bf298df2e79ce0f6b8b4d87e3a2d6666f458ae143ef8e593ea1",
+      "sha256": "36558f7f90e2e52192df88f243631735a880b7d371e6df17025933151a825c56",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -67,7 +74,7 @@
     },
     {
       "path": ".claude/hooks/pre-commit-surface-gate.sh",
-      "sha256": "a58f3b3c3dbb615a14bf6e2355f5122e80a5cb1e8ef9442648324f3124723ee3",
+      "sha256": "6741422cd8ca75b45e26bd0e9cb54126ad9e933f763c9094ceba6b84794b761a",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -109,14 +116,14 @@
     },
     {
       "path": ".claude/hooks/stamp-and-gate.sh",
-      "sha256": "3488dfea2874e8069453a2fdf40164d2c3fefe9ad7e2453190501391707aee7b",
+      "sha256": "2c654dc3a6707d394f782f68d7318410d4acbbcb70c0a9d0d674d966241fc310",
       "tier": "hook",
       "overwrite_policy": "pin-aware",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/hooks/token-ledger.sh",
-      "sha256": "b766f18e005dea89d63c2dae9c436e3e52ef0e4828ea895ce94abfecc68f0ce2",
+      "sha256": "6678f814520c379b3ab055f3a1b98c92f631fd415ae24752d45aa8bee058c29c",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -137,7 +144,7 @@
     },
     {
       "path": ".claude/skills/sprint-execution/SKILL.md",
-      "sha256": "f403bb55f4cdce4b82ce3fdd59b03dd55d8f3f64bdc0e1d1c2abf9b2121efa3d",
+      "sha256": "877fabf8fcc682d9ba55421e6ba8c2a4ccf2b84a83d66e77dedc418b5aa47a3a",
       "tier": "skill",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -163,9 +170,16 @@
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
+    {
+      "path": ".cleargate/knowledge/mid-sprint-triage-rubric.md",
+      "sha256": "170f762b427074a84c183a91fb65d1d6408650b7746de3bbc460d21194bda30a",
+      "tier": "protocol",
+      "overwrite_policy": "merge-3way",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".cleargate/knowledge/readiness-gates.md",
-      "sha256": "6125b57bfdcdd5d4fabe886770d9b062d76df9a232f4997dbedf3322aefdf1b5",
+      "sha256": "10cb46cdaf264f8aa7c3841d12101bfad422a45f36c758be5327b0e4009a46a0",
       "tier": "protocol",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -186,7 +200,7 @@
     },
     {
       "path": ".cleargate/scripts/close_sprint.mjs",
-      "sha256": "d02be1cb8e0290782197a8b775c52b8f3064aaf661f5466c218dadb62179690a",
+      "sha256": "1807e5b27f1501476c9dec41cbb350c432d2894cb0727d8da0c860ad3f9181c7",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -214,7 +228,7 @@
     },
     {
       "path": ".cleargate/scripts/gate-checks.json",
-      "sha256": "188ef9995ce14e609ecf042563bab44d461df5315a4fd698e3eebfaf84db3b6a",
+      "sha256": "9c520e63ac582289b6905a1c5704326590923eeef90d1e02801d1a57b4262877",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -228,7 +242,7 @@
     },
     {
       "path": ".cleargate/scripts/init_sprint.mjs",
-      "sha256": "1d0f41df4325ea32981256aec15ed43eef09aba2a16ab4ba6d310cd61685556e",
+      "sha256": "80d532754b0b27bb274aca4e30a0e9a208f2528d079c24d4e319de2e429cd268",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -277,7 +291,7 @@
     },
     {
       "path": ".cleargate/scripts/run_script.sh",
-      "sha256": "63ff100bb56361b06825d20dc601975e6df32bb688fe112b0d705dc45129ca20",
+      "sha256": "f2bd931d3b7bb4d30f5da9c116714345480163e9afb4c244c1a1c074410c15d0",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -298,7 +312,7 @@
     },
     {
       "path": ".cleargate/scripts/suggest_improvements.mjs",
-      "sha256": "7d5853bf477447ae9090485648c3ba9426419504c6d36626c32454bf578c74a6",
+      "sha256": "62e71e7bf43abb6f015290f6ff3e06f15fb097682ddb95dbdf9532922d27925a",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -333,7 +347,7 @@
     },
     {
       "path": ".cleargate/scripts/test/test_flashcard_gate.sh",
-      "sha256": "0e05a7fbaa86aeb9401e7df09696b9c547896512c41aa738a7c812d69d135916",
+      "sha256": "40fb023b0db1556295b92858b303ba90745ef89c3131bc760232e5cd8ebe7815",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -368,49 +382,49 @@
     },
     {
       "path": ".cleargate/scripts/validate_state.mjs",
-      "sha256": "a1ad7e5f0525d3302759f9a04514e7205141c124abeb42fcda1f9d6042eca926",
+      "sha256": "ee3e8c0aeadb9a4e182d2a061cd992b6751e5bf067e0729b88da58582c67dbf1",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/scripts/write_dispatch.sh",
-      "sha256": "4af4035555f4c6852ffd8f4635734931cfa2baef706f27f001bf0b2c64f7a0be",
+      "sha256": "abdcaf09b09251f3ab42cb7ec8bdedc5806fd0eb337578f55043bffb158d8128",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/Bug.md",
-      "sha256": "d58c3d5d19387e7749c62570931a829fd1fc31bda83b6edba2b0854dafd6936d",
+      "sha256": "570112e3a60856c891652837307fc6f296cc39acc20451f8bde62da0fe033026",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/CR.md",
-      "sha256": "434ac96bfd9aa8732a89d18ceb546101737b2b6fdc1b3858b5ea0153837bc6ee",
+      "sha256": "ab111792dc79fd5181b44a63c76ac696fa4e456161ac44e2c4d0dc609e8dd904",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/epic.md",
-      "sha256": "bbb250b5ca905ed6f48b55b0c982296899d04a492f9427195960cee3e3632594",
+      "sha256": "fd3b54de89befe7c5bcef65e2fa5550fc7f371d55c8f15143ae73d84f3ae6d36",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/hotfix.md",
-      "sha256": "2d4fe14f12dbdae75cd8298bc547f39da89ecc9aaf917d32b3298a9b4936aaa2",
+      "sha256": "b75dd154c156e68a44ae01b85eff7ec16f54050e4fe7eb71f59e17d87c03a298",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/initiative.md",
-      "sha256": "08730306824f184a7d972346640493f100a5d1b44f0efe0ed855e1acedfd65d6",
+      "sha256": "28680917228e5d9887c8820193cc21bfecc6aad3bc0658e8a59087adf63551fd",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -424,7 +438,7 @@
     },
     {
       "path": ".cleargate/templates/sprint_context.md",
-      "sha256": "56c8c401b56d4c654dc41a19bd524f1b8860a8006cc3cd90e784d101c3d7721a",
+      "sha256": "82a95b8e5e9a5842a9dcad68bc3ed7405819a616d13d616cdb80083c32cc1fc3",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -438,7 +452,7 @@
     },
     {
       "path": ".cleargate/templates/story.md",
-      "sha256": "a1413c4af5d854163741e92575fb913b93bdac1c1b7cfc59be8c3e0c8780eac0",
+      "sha256": "56d793983614d832e84193d99ee5318c061d2f3ea4f019cefb861c026513cb31",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "cleargate",
-  "version": "0.10.0",
+  "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"
@@ -47,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.
 
@@ -57,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 `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 `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.
+
+**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.
 
@@ -85,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).
@@ -141,6 +169,31 @@ Before emitting a `lane` recommendation per story during Sprint Design Review, r
 
 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.

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.
 
@@ -76,6 +80,11 @@ For inner-loop iteration during a Story, prefer **`node:test` + `node:assert/str
 
 **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`.
 - **Never mock the database.** Integration tests against real Postgres + Redis (SPRINT-01 flashcard).
@@ -98,6 +107,19 @@ These rules apply under `execution_mode: v2`. Under v1 they are informational.
 
 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
 
 These rules apply under `execution_mode: v2`. Under v1 they are informational.