cleargate 0.5.0 → 0.6.0

package/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/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/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/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/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/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/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