cleargate 0.5.0 → 0.6.0

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

@@ -3,9 +3,11 @@
  * update_state.mjs — Atomic state/counter update for a story in state.json
  *
  * Usage:
- *   node update_state.mjs <STORY-ID> <new-state>   — transition to a new state
- *   node update_state.mjs <STORY-ID> --qa-bounce   — increment qa_bounces counter
- *   node update_state.mjs <STORY-ID> --arch-bounce — increment arch_bounces counter
+ *   node update_state.mjs <STORY-ID> <new-state>          — transition to a new state
+ *   node update_state.mjs <STORY-ID> --qa-bounce          — increment qa_bounces counter
+ *   node update_state.mjs <STORY-ID> --arch-bounce        — increment arch_bounces counter
+ *   node update_state.mjs <STORY-ID> --lane <standard|fast> — set lane for a story
+ *   node update_state.mjs <STORY-ID> --lane-demote <reason> — demote story from fast lane
  *
  * Atomic write: write to .tmp.<pid> file, then rename to final path.
  * Idempotent: if new state equals current (for state transitions) and
@@ -13,13 +15,16 @@
  *
  * Auto-escalation: when qa_bounces or arch_bounces reaches BOUNCE_CAP (3),
  *   state is automatically set to "Escalated".
+ *
+ * Migration: reads v1 state.json transparently; upgrades to v2 on first touch
+ *   (injects lane fields with defaults; emits one stderr log line).
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { SCHEMA_VERSION, VALID_STATES, TERMINAL_STATES, BOUNCE_CAP } from './constants.mjs';
-import { validateState } from './validate_state.mjs';
+import { validateState, validateShapeIgnoringVersion } from './validate_state.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -29,11 +34,36 @@ function usage() {
     'Usage:\n' +
     '  node update_state.mjs <STORY-ID> <new-state>\n' +
     '  node update_state.mjs <STORY-ID> --qa-bounce\n' +
-    '  node update_state.mjs <STORY-ID> --arch-bounce\n'
+    '  node update_state.mjs <STORY-ID> --arch-bounce\n' +
+    '  node update_state.mjs <STORY-ID> --lane <standard|fast>\n' +
+    '  node update_state.mjs <STORY-ID> --lane-demote <reason>\n'
   );
   process.exit(2);
 }
 
+/**
+ * Migrate a v1 state.json to v2 by injecting lane fields with defaults.
+ * Mutates the state object in-place and returns it.
+ * Emits a single stderr log line describing the migration.
+ * @param {object} state - Parsed v1 state object
+ * @returns {object} - The mutated (now v2) state object
+ */
+export function migrateV1ToV2(state) {
+  state.schema_version = 2;
+  const storyIds = Object.keys(state.stories || {});
+  for (const id of storyIds) {
+    const story = state.stories[id];
+    if (story.lane == null) story.lane = 'standard';
+    if (story.lane_assigned_by == null) story.lane_assigned_by = 'migration-default';
+    if (story.lane_demoted_at === undefined) story.lane_demoted_at = null;
+    if (story.lane_demotion_reason === undefined) story.lane_demotion_reason = null;
+  }
+  process.stderr.write(
+    `migration: schema_version 1 → 2 for sprint ${state.sprint_id} (${storyIds.length} stories defaulted to lane: standard)\n`
+  );
+  return state;
+}
+
 function resolveStateFile() {
   const envFile = process.env.CLEARGATE_STATE_FILE;
   if (envFile) return path.resolve(envFile);
@@ -71,10 +101,24 @@ function main() {
     process.exit(1);
   }
 
-  // Validate existing state before modifications
+  // Pre-migration: validate shape (ignoring version) before potentially migrating
+  const preCheck = validateShapeIgnoringVersion(state);
+  if (!preCheck.valid) {
+    process.stderr.write(`Error: state.json is invalid:\n`);
+    for (const e of preCheck.errors) process.stderr.write(`  - ${e}\n`);
+    process.exit(1);
+  }
+
+  // Migrate v1 → v2 if needed; write atomically so subsequent reads see v2
+  if (state.schema_version === 1) {
+    state = migrateV1ToV2(state);
+    atomicWrite(stateFile, state);
+  }
+
+  // Post-migration strict validation
   const { valid, errors } = validateState(state);
   if (!valid) {
-    process.stderr.write(`Error: state.json is invalid:\n`);
+    process.stderr.write(`Error: state.json is invalid after migration:\n`);
     for (const e of errors) process.stderr.write(`  - ${e}\n`);
     process.exit(1);
   }
@@ -86,7 +130,48 @@ function main() {
 
   const story = state.stories[storyId];
 
-  if (action === '--qa-bounce') {
+  if (action === '--lane') {
+    const laneValue = args[2];
+    if (!laneValue || !['standard', 'fast'].includes(laneValue)) {
+      process.stderr.write(
+        `Error: --lane requires a value of "standard" or "fast"\n`
+      );
+      process.exit(2);
+    }
+    // TODO(STORY-022-04): cross-read sprint plan to enforce rubric §6 contradiction check
+    // (expected_bounce_exposure: med|high + lane: fast is a contradiction per PROPOSAL-013 §2.3 #6)
+    story.lane = laneValue;
+    story.lane_assigned_by = 'human-override';
+    story.updated_at = new Date().toISOString();
+    state.last_action = `lane-set ${storyId}: lane=${laneValue} (human-override)`;
+    state.updated_at = story.updated_at;
+    atomicWrite(stateFile, state);
+    process.stdout.write(
+      `Updated ${storyId}: lane="${laneValue}", lane_assigned_by="human-override"\n`
+    );
+
+  } else if (action === '--lane-demote') {
+    const reason = args[2];
+    if (!reason) {
+      process.stderr.write(
+        `Error: --lane-demote requires a reason string\n`
+      );
+      process.exit(2);
+    }
+    story.lane = 'standard';
+    story.lane_demoted_at = new Date().toISOString();
+    story.lane_demotion_reason = reason;
+    story.qa_bounces = 0;
+    story.arch_bounces = 0;
+    story.updated_at = story.lane_demoted_at;
+    state.last_action = `lane-demote ${storyId}: "${reason}"`;
+    state.updated_at = story.updated_at;
+    atomicWrite(stateFile, state);
+    process.stdout.write(
+      `Updated ${storyId}: lane="standard", lane_demoted_at="${story.lane_demoted_at}", qa_bounces=0, arch_bounces=0\n`
+    );
+
+  } else if (action === '--qa-bounce') {
     if (story.state === 'Escalated') {
       process.stderr.write(`Error: story ${storyId} is already Escalated\n`);
       process.exit(1);

package/dist/templates/cleargate-planning/.cleargate/templates/Sprint Plan Template.md

@@ -4,6 +4,14 @@ Do NOT draft this file manually. Do NOT invoke cleargate_push_item on this file.
 The Vibe Coder may annotate the "Execution Guidelines" section locally — this section is never pushed.
 Output location: .cleargate/plans/SPRINT-{ID}.md
 Do NOT output these instructions.
+
+§1 Lane column placement: "Lane" is inserted between "Title" and "Milestone" in the Consolidated Deliverables
+table (§1). This positions lane as a planning signal adjacent to the story title, which is where the Architect
+most naturally reads it during Sprint Design Review. Values are "standard" (default) or "fast" (see protocol §24).
+
+§2.4 Lane Audit: The Architect populates one row per fast-lane story during Sprint Design Review. Empty by default.
+Rows are added only for non-`standard` lanes. The subsection is numbered 2.4; the former §2.4 ADR-Conflict Flags
+is renumbered to §2.5.
 </instructions>
 
 ---
@@ -40,9 +48,9 @@ cached_gate_result:
 ## 1. Consolidated Deliverables
 *(Pulled from PM tool. IDs are the remote PM entity IDs.)*
 
-| Story ID | Title | Milestone | Parallel? | Bounce Exposure |
-|---|---|---|---|---|
-| `{STORY-NNN-NN}` | {Title} | M{N} | y / n | low / med / high |
+| Story ID | Title | Lane | Milestone | Parallel? | Bounce Exposure |
+|---|---|---|---|---|---|
+| `{STORY-NNN-NN}` | {Title} | standard / fast | M{N} | y / n | low / med / high |
 
 ## 2. Execution Strategy
 *(Written by Architect during Sprint Design Review. Required before `execution_mode: v2` sprint start. Under v1, this section may be omitted or left as a stub.)*
@@ -64,7 +72,14 @@ Example:
 {Explicit conflict risks. One bullet per risk. Cite file + story pair.}
 - None identified. (Replace with actual warnings if applicable.)
 
-### 2.4 ADR-Conflict Flags
+### 2.4 Lane Audit
+{Architect populates one row per fast-lane story during Sprint Design Review. Empty by default — rows added only for non-`standard` lanes.}
+
+| Story | Lane | Rationale (≤80 chars) |
+|---|---|---|
+| `STORY-NNN-NN` | fast | <one-line rationale> |
+
+### 2.5 ADR-Conflict Flags
 {Any story whose implementation conflicts with an Architectural Decision Record in `.cleargate/knowledge/` or prior sprint decisions. One bullet per flag.}
 - None identified. (Replace with actual flags if applicable.)
 

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

@@ -0,0 +1,58 @@
+---
+hotfix_id: "{ID}"
+status: "Draft"
+severity: "P2"
+originating_signal: "user-report"
+created_at: "{ISO}"
+created_at_version: "cleargate@0.5.0"
+merged_at: null
+commit_sha: null
+verified_by: null
+lane: "hotfix"
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null
+pushed_at: null
+last_pulled_by: null
+last_pulled_at: null
+last_remote_update: null
+source: "local-authored"
+last_synced_status: null
+last_synced_body_sha: null
+---
+
+# {ID}: {SLUG}
+
+## 1. Anomaly
+
+**Expected Behavior:** {What the system should do under normal conditions.}
+
+**Actual Behavior:** {What it is doing now — the observed deviation.}
+
+## 2. Files Touched
+
+Hotfix discipline: ≤2 files, ≤30 LOC net (EPIC-022 §3).
+
+- `{path/to/file.ts}` — {brief description of change}
+
+## 3. Verification Steps
+
+> Rule: §3 must be non-empty before merging. An empty §3 blocks merge at review time.
+
+1. - [ ] {Step 1: describe what to run or observe}
+2. - [ ] {Step 2: confirm the anomaly is resolved}
+3. - [ ] {Step 3: confirm no regression in adjacent behavior}
+
+## 4. Rollback
+
+If the hotfix introduces a regression, revert by running `git revert <commit-sha>` on the sprint or main branch. The original anomaly will reappear; escalate to a sprint story for a permanent fix. No data migrations are involved unless noted in §2 above.

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

@@ -3,14 +3,15 @@ sprint_id: "SPRINT-NN"
 status: "Draft"
 generated_at: "<ISO-8601>"
 generated_by: "Reporter agent"
-template_version: 1
+template_version: 2
 ---
 
-<!-- Sprint Report v2 Template — template_version: 1 -->
+<!-- Sprint Report v2 Template — template_version: 2 -->
 <!-- Event-type vocabulary (STORY-013-05 / protocol §§16–17):
      User-Review: UR:review-feedback | UR:bug
      Change-Request: CR:bug | CR:spec-clarification | CR:scope-change | CR:approach-change
      Circuit-breaker: test-pattern | spec-gap | environment
+     Lane-Demotion: LD
      These tokens appear verbatim in §2 CR Change Log and §3 Execution Metrics tallies. -->
 
 # SPRINT-<NN> Report: <Sprint Title>
@@ -74,6 +75,12 @@ template_version: 1
 | Stories shipped (Done) | N |
 | Stories escalated | N |
 | Stories carried over | N |
+| Fast-Track Ratio | N% |
+| Fast-Track Demotion Rate | N% |
+| Hotfix Count (sprint window) | N |
+| Hotfix-to-Story Ratio | N |
+| Hotfix Cap Breaches | N |
+| LD events | N |
 | Total QA bounces | N |
 | Total Arch bounces | N |
 | CR:bug events | N |
@@ -157,6 +164,29 @@ If zero candidates: No stale flashcards detected.
 | Three-surface landing compliance | Green/Yellow/Red | |
 | Circuit-breaker fires (if any) | Green/Yellow/Red | |
 
+### Lane Audit
+<!-- Filled by Reporter at sprint close. One row per fast-lane story. -->
+
+| Story | Files touched | LOC | Demoted? | In retrospect, was fast correct? (y/n) | Notes |
+|---|---|---|---|---|---|
+| `STORY-NNN-NN` | N | N | y / n | y / n | |
+
+### Hotfix Audit
+<!-- Filled by Reporter at sprint close. One row per hotfix merged during the sprint window. -->
+
+| Hotfix ID | Originating signal | Files touched | LOC | Resolved-by SHA | Could this have been a sprint story? (y/n) | If y — why was it missed at planning? |
+|---|---|---|---|---|---|---|
+| `HOTFIX-NN` | <signal> | N | N | `<sha>` | y / n | |
+
+### Hotfix Trend
+<!-- Filled by Reporter at sprint close. -->
+
+<!-- TBD: Reporter fills at sprint close -->
+
+<Reporter writes a one-paragraph narrative summarising the rolling 4-sprint hotfix count
+and a monotonic-increase flag (yes/no). Empty by default — leave the placeholder text
+intact for sprints with no hotfixes.>
+
 ### Tooling
 | Item | Rating | Notes |
 |---|---|---|

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

@@ -29,7 +29,8 @@ When the rubric is ambiguous, surface the decision to the human as a one-liner (
 §0.1 v2 Decomposition Signals:
   `parallel_eligible`: "y" if this story can run concurrently with other stories in the same milestone; "n" if it has a strict predecessor dependency. Default "y". Set by Architect during Sprint Design Review.
   `expected_bounce_exposure`: "low" | "med" | "high" — predicted re-work risk derived from §2.1 scenario count + §3 file-count + ambiguity level. Default "low". Set by Architect. Used by orchestrator to sequence high-exposure stories before low-exposure ones in a v2 sprint to surface risk early.
-  Both fields are v2-only signals. Under v1 sprints they are informational; defaults apply for stories authored before SPRINT-09.
+  `lane`: "standard" | "fast" — Architect-set during Sprint Design Review per the seven-check rubric in protocol §24. Default "standard". Absent in pre-EPIC-022 stories means standard per the migration default in update_state.mjs.
+  All three fields are v2-only signals. Under v1 sprints they are informational; defaults apply for stories authored before SPRINT-09.
 
 Do NOT output these instructions.
 </instructions>
@@ -44,6 +45,7 @@ actor: "{Persona Name}"
 complexity_label: "L2"
 parallel_eligible: "y"
 expected_bounce_exposure: "low"
+lane: "standard"
 created_at: "2026-04-17T00:00:00Z"
 updated_at: "2026-04-17T00:00:00Z"
 created_at_version: "strategy-phase-pre-init"

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

@@ -18,7 +18,7 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 
 **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.
 
-**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` and explicit human confirmation (Gate 3).
+**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.
 
 **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`).

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

@@ -1,10 +1,10 @@
 {
-  "cleargate_version": "0.5.0",
-  "generated_at": "2026-04-25T21:53:30.430Z",
+  "cleargate_version": "0.6.0",
+  "generated_at": "2026-04-27T06:34:21.351Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
-      "sha256": "c9424894549b270b73c1c95145b7bb8d406cadd2057c47f8e90bf74ce1f3cda7",
+      "sha256": "297020d3344d9122c0ff95e00b436cb83640acbc78377684c04f6af8fb6fbcc4",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -32,7 +32,7 @@
     },
     {
       "path": ".claude/agents/developer.md",
-      "sha256": "ea54db76bcd017526f2b48e05b167cb87251273aa5fd3da6bec3013c207c72fb",
+      "sha256": "602b8ef4ca0f8bc11472a612744535d1a6794533ceaf97587d5d421c4fc49b77",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -46,7 +46,7 @@
     },
     {
       "path": ".claude/agents/reporter.md",
-      "sha256": "5819d6f932ebd25a48e6f91a2e6227726f6d4d15968622728ec22a4ed7caa622",
+      "sha256": "c2f6e9db07c737ada4c2f76497d08e0f881bc8f0fceb073b9479753d33c4ecf4",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -80,29 +80,36 @@
       "preserve_on_uninstall": false
     },
     {
-      "path": ".claude/hooks/session-start.sh",
-      "sha256": "ddaa1a461e6730db0ca7312ee44d66b78379250ba8b30a04125b37dc49350479",
+      "path": ".claude/hooks/pre-edit-gate.sh",
+      "sha256": "a9fae2eae43cf493a5bf79e9d15b909a27750515817a2ed0b45d77892b49ab2c",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
+    {
+      "path": ".claude/hooks/session-start.sh",
+      "sha256": "77c206eeaa5d460f9e751244f25ff09089578ad4d044487cbcff8b3e1d78582f",
+      "tier": "hook",
+      "overwrite_policy": "pin-aware",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".claude/hooks/stamp-and-gate.sh",
-      "sha256": "3f64faff6d142b9ec997480944fc709aed8ed44c3f2adca026804f1e64946059",
+      "sha256": "3488dfea2874e8069453a2fdf40164d2c3fefe9ad7e2453190501391707aee7b",
       "tier": "hook",
-      "overwrite_policy": "always",
+      "overwrite_policy": "pin-aware",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/hooks/token-ledger.sh",
-      "sha256": "be2b2eaa02cc30387601285160d6fe1c90ea76b37ec6cae2b7c9537f66f22783",
+      "sha256": "45113b3c3f3a78e350e112665c1aadf74a246bb4ebfe514ea7230d6bd3fa01c1",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/settings.json",
-      "sha256": "a6d63ac3d01592b7d2ed1af45067606d535349dc27a51740f744c2fd2592a0cb",
+      "sha256": "539345bf59249e645a2b5faeb9cc4f44deb657ac77e9833ef74f7e4a1f4c6e3b",
       "tier": "cli-config",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -123,14 +130,14 @@
     },
     {
       "path": ".cleargate/knowledge/cleargate-protocol.md",
-      "sha256": "4316444ad452e83a2c9387ad6ad96ef4e4511b1face4b30976a912c0f28866f6",
+      "sha256": "a3d02a7e6660403370568f3e412990a6e44394e65040ce21adc5f8e4269946ca",
       "tier": "protocol",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/knowledge/readiness-gates.md",
-      "sha256": "0d5d254bb6c464c5cfa675927b5b358590cfbf8d2b1c7179519ef4780bb8da7f",
+      "sha256": "d7a79a50e3cb5fd42735b017d3d88dff0fa443444951e717013e423770bad87b",
       "tier": "protocol",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -156,6 +163,13 @@
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
+    {
+      "path": ".cleargate/templates/hotfix.md",
+      "sha256": "2a7c745b0d46f4a092c507d6b427c15d64540e332f9544bc572451a313f4e5cc",
+      "tier": "template",
+      "overwrite_policy": "merge-3way",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".cleargate/templates/initiative.md",
       "sha256": "9bf4a5a5ff7af0938ff48d5eaa182f227195d101ba9de4d56123b4fc211b8cac",
@@ -172,7 +186,7 @@
     },
     {
       "path": ".cleargate/templates/Sprint Plan Template.md",
-      "sha256": "9f87539691b910193c55fb9a637975de738dda181baa7e68fc48297993389613",
+      "sha256": "583f71c76c0b3c8cb219183f5881250219cec2719c909abf4d3069beed8cad51",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -186,14 +200,14 @@
     },
     {
       "path": ".cleargate/templates/sprint_report.md",
-      "sha256": "5f3dfdbc7a1dde26758871b358be00d543e9669ab34ca3c7ead765ee6e182bcb",
+      "sha256": "e73126842e219d856d32c4cb72e0a98066ea9ad4993e3f3919f9c8296d73afdf",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/story.md",
-      "sha256": "266b7e2b0526c4fe37620baf9344521e98ee5e7363661d390ef90068798f9bfe",
+      "sha256": "f46364178f09d2514405723e53d5e388ab41bce5e2b318dc1aed8743500f042f",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false

package/package.json

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

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

@@ -115,6 +115,30 @@ After SPRINT-10 ships, `max = 20`. A story drafted before SPRINT-10 might cite `
 
 **Rule:** Never let a Developer emit a protocol section number that conflicts with an existing one. Audit first, emit second.
 
+## Lane Classification
+
+Before emitting a `lane` recommendation per story during Sprint Design Review, run the seven-check rubric. A story is eligible for `lane: fast` **only if all seven checks pass**. Any single false flips it to `standard`.
+
+1. **Size cap.** Implementation diff projected at ≤2 files AND ≤50 LOC net (additions + deletions). Tests count toward the cap; generated files do not.
+2. **No forbidden surfaces.** Story does not modify any of the following file-path prefixes:
+   | Prefix | Category |
+   |---|---|
+   | `mcp/src/db/`, `**/migrations/` | Database schema / migration |
+   | `mcp/src/auth/`, `mcp/src/admin-api/auth-*` | Auth / identity flow |
+   | `cleargate.config.json`, `mcp/src/config.ts` | Runtime config schema |
+   | `mcp/src/adapters/` | MCP adapter API surface |
+   | `cleargate-planning/MANIFEST.json` | Scaffold manifest |
+   | token handling, invite verification, gate enforcement | Security-relevant code |
+3. **No new dependency.** Story does not add a package to any `package.json`. Removals and version pins within an existing major are allowed.
+4. **Single acceptance scenario or doc-only.** Story Gherkin has exactly one `Scenario:` block (or zero, for pure doc/comment changes). Stories with `Scenario Outline:` or multiple scenarios are not fast-eligible.
+5. **Existing tests cover the runtime change.** Either (a) story description names an existing test file the change exercises, or (b) story is doc-only / comment-only / non-runtime config. The pre-gate scanner verifies (a) by checking that at least one referenced test file exists and includes the affected module name as a string match.
+6. **`expected_bounce_exposure: low`.** A story can only be fast if its decomposition signal is already `low`. `med` or `high` is auto-`standard`.
+7. **No epic-spanning subsystem touches.** Story's affected files all live under one of the epic's declared scope directories. A story that touches files outside its parent epic's declared scope is auto-`standard`.
+
+**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`.
+
 ## 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

@@ -71,6 +71,30 @@ 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 §15.3 for full rationale.
 
+## Lane-Aware Execution
+
+These rules apply under `execution_mode: v2`. Under v1 they are informational.
+
+**On spawn:** read `.cleargate/sprint-runs/<sprint-id>/state.json` for the current sprint (locate the active sprint via `.cleargate/sprint-runs/.active`). Look up the story's `lane` field under `state.json.stories[<story-id>].lane`. Default to `"standard"` if the field is absent, the story key is missing, or `state.json` does not exist.
+
+**lane=fast behavior:**
+
+- Skip writing the architect-plan-citation block. No plan exists for fast-lane stories; the orchestrator dispatched without one.
+- The pre-gate scanner (`pre_gate_runner.sh`) is **never skipped** on lane=fast — that routing contract belongs to `pre_gate_runner.sh` (STORY-022-04). The Developer's commit MUST still pass typecheck + tests, and the single-commit rule is fully preserved.
+- All other guardrails (no `--no-verify`, no scope bleed, no mocked DB) remain in force regardless of lane.
+
+**lane=standard behavior (or lane absent / state.json missing):**
+
+- Follow the existing four-agent contract verbatim: read the Architect's plan, cite it in your blueprint section, implement against it.
+
+**Demotion handler:**
+
+If `state.json` lane flips from `"fast"` to `"standard"` mid-sprint (`lane_demoted_at` populated by `pre_gate_runner.sh` after a fast-lane scanner failure), the orchestrator re-dispatches the story with the architect plan attached. The Developer treats the new dispatch as a fresh spawn and follows the lane=standard contract — there is no state machine or continuation logic on the Developer side.
+
+**First-line marker contract preserved:**
+
+The Developer's first response line still emits `STORY=NNN-NN` (or `CR=NNN`, `BUG=NNN`, `EPIC=NNN`, `PROPOSAL=NNN` / `PROP=NNN`) per BUG-010's detector contract. Lane is **NOT** part of the first-line marker.
+
 ## Circuit Breaker
 
 These rules apply under `execution_mode: v2`. Under v1 they are informational.

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

@@ -97,6 +97,80 @@ If SPRINT-09 Reporter regresses post-swap of this reporter.md, rollback path:
 `.cleargate/sprint-runs/S-09/fixtures/sprint-08-shaped/` was used to validate this
 spec before atomic swap.
 
+## Sprint Report v2.1 — Lane + Hotfix Metrics
+
+When `state.json` has `schema_version >= 2` AND at least one story shipped with `lane: fast`,
+the Reporter MUST populate the following additional rows and sections. When the activation
+conditions are not met (v1 state, or all stories `lane: standard`), these rows and sections
+may be omitted or left with placeholder values.
+
+### §3 Execution Metrics — Six New Rows
+
+The Reporter computes and writes these six rows in §3 (after the existing rows):
+
+| Row label | Computation | Source |
+|---|---|---|
+| `Fast-Track Ratio` | `count(stories where lane=fast at sprint close) / total stories × 100` | `state.json` `.stories[*].lane` |
+| `Fast-Track Demotion Rate` | `count(stories with LD event) / count(stories where lane=fast was ever assigned) × 100` | `state.json` `.stories[*].lane_demoted_at` + sprint markdown §4 LD rows |
+| `Hotfix Count (sprint window)` | Count of rows in `wiki/topics/hotfix-ledger.md` where `merged_at` is between sprint `started_at` and `closed_at` | `wiki/topics/hotfix-ledger.md` filtered by sprint window |
+| `Hotfix-to-Story Ratio` | `Hotfix Count / total in-sprint stories` | Derived from above |
+| `Hotfix Cap Breaches` | Count of rolling-7-day windows during the sprint window that had ≥ 3 hotfixes | `wiki/topics/hotfix-ledger.md` `merged_at` column |
+| `LD events` | Count of LD event rows in sprint markdown §4 events list | Sprint plan file `## §4 Events Log` or equivalent |
+
+**Sources detail:**
+
+- `state.json` lane fields per `.cleargate/scripts/state.schema.json` StoryEntry: `lane`, `lane_assigned_by`, `lane_demoted_at`, `lane_demotion_reason`.
+- Sprint markdown §4 LD events written by `pre_gate_runner.sh` `append_ld_event` (STORY-022-04). Each LD row records the story, timestamp, and demotion reason.
+- `wiki/topics/hotfix-ledger.md` — filter rows by `merged_at` between sprint `started_at` and `closed_at`. If the ledger is absent, record `Hotfix Count = 0` and a note explaining the fallback.
+- For historical sprints with `schema_version: 1` (no lane fields), default all lane metrics to `0` or `N/A` and note the fallback in §5 Tooling.
+
+### §5 Process — Lane Audit table
+
+One row per story that was ever assigned `lane: fast` during the sprint (whether it shipped fast
+or was auto-demoted). The Reporter computes the first four columns from `git log` + `state.json`;
+the last two columns are left blank for human fill-in at sprint close.
+
+Template row format (per `sprint_report.md` lines 167-172):
+
+```
+| Story | Files touched | LOC | Demoted? | In retrospect, was fast correct? (y/n) | Notes |
+```
+
+- **Story**: story ID (e.g. `STORY-022-08`).
+- **Files touched**: count via `git diff --name-only <base>..<story-sha>`.
+- **LOC**: `git diff --stat <base>..<story-sha>` insertions+deletions total.
+- **Demoted?**: `y` if `lane_demoted_at` is non-null in `state.json`; `n` otherwise.
+- **In retrospect, was fast correct?**: blank — human fills at close.
+- **Notes**: blank — human fills at close.
+
+### §5 Process — Hotfix Audit table
+
+One row per hotfix merged within the sprint window. Read from `wiki/topics/hotfix-ledger.md`
+filtered by `merged_at` between sprint `started_at` and `closed_at`. Last two columns blank.
+
+Template row format (per `sprint_report.md` lines 174-179):
+
+```
+| Hotfix ID | Originating signal | Files touched | LOC | Resolved-by SHA | Could this have been a sprint story? (y/n) | If y — why was it missed at planning? |
+```
+
+If zero hotfixes in window, write a single row: `| (none) | — | — | — | — | — | — |`
+
+### §5 Process — Hotfix Trend narrative
+
+A one-paragraph narrative summarising the rolling 4-sprint hotfix count and a
+monotonic-increase flag. The Reporter reads the last 4 sprint `REPORT.md` files
+(at `.cleargate/sprint-runs/<id>/REPORT.md`) OR walks `wiki/topics/hotfix-ledger.md`
+by `sprint_id` field to gather per-sprint counts.
+
+Monotonic-increase flag: if the count increased (or stayed ≥ 1) for 3+ consecutive sprints,
+flag it as `trend: INCREASING` and recommend a retrospective action in §5 Tooling.
+
+For historical v1-schema sprints with no lane data, record `0 hotfixes (v1 — no ledger data)`.
+
+Template location: `sprint_report.md` lines 181-188. Leave the placeholder text intact for
+sprints with no hotfixes in the window.
+
 ## Guardrails
 - **Numbers before narrative.** Every claim in §1 must be backed by a ledger row, commit, or flashcard -- cite them.
 - **Do not fabricate cost.** If you cannot find current model rates, state the rate date and mark cost `~$X (rates as of <date>)`.