cleargate 0.5.0 → 0.6.1

package/templates/cleargate-planning/.cleargate/scripts/assert_story_files.mjs

@@ -1,19 +1,26 @@
 #!/usr/bin/env node
 /**
- * assert_story_files.mjs — Gate-2 story-file existence assertion
+ * assert_story_files.mjs — Gate-2 work-item file existence + approval assertion
  *
  * Usage: node assert_story_files.mjs <sprint-file-path>
  *
  * Parses the "## 1. Consolidated Deliverables" section of a sprint file for
- * STORY-\d+-\d+ IDs, then checks that each has a corresponding
- * pending-sync/STORY-<id>_*.md file under the repo root.
+ * all six work-item id shapes:
+ *   STORY-\d+-\d+, CR-\d+, BUG-\d+, EPIC-\d+, PROPOSAL-\d+ (PROP-\d+ normalised),
+ *   HOTFIX-\d+
+ * then checks that each has a corresponding pending-sync/<ID>_*.md file under
+ * the repo root, and that each present file is approved + structurally non-empty.
  *
- * Exit 0:  all story files present (prints summary to stdout)
- * Exit 1:  one or more missing (prints JSON {missing,present} to stderr)
+ * Exit 0:  all work-item files present, approved, and non-empty (prints summary to stdout)
+ * Exit 1:  one or more missing / unapproved / stub-empty (prints structured stderr)
  * Exit 2:  usage / parse error
  *
  * Env:
  *   CLEARGATE_REPO_ROOT  override repo root (for test isolation)
+ *   CLEARGATE_EXEC_MODE  override execution_mode ('v1'|'v2') — for test isolation
+ *
+ * Returns (from assertWorkItemFiles):
+ *   { missing: string[], present: string[], unapproved: string[], empty: string[] }
  */
 
 import fs from 'node:fs';
@@ -51,37 +58,103 @@ function extractDeliverablesSection(content) {
 }
 
 /**
- * Extract deduplicated STORY-\d+-\d+ IDs from a text block.
+ * Extract deduplicated work-item IDs from a text block.
+ *
+ * ID shapes (longest-alternative-first to avoid prefix collisions):
+ *   STORY-\d+-\d+         (e.g. STORY-022-07)
+ *   CR-\d+                (e.g. CR-008)
+ *   BUG-\d+               (e.g. BUG-007)
+ *   EPIC-\d+              (e.g. EPIC-013)
+ *   HOTFIX-\d+            (e.g. HOTFIX-001)
+ *   PROPOSAL-\d+          (e.g. PROPOSAL-013)
+ *   PROP-\d+              normalised to PROPOSAL-NNN post-extract (BUG-009 lesson)
+ *
+ * STORY before CR/BUG/EPIC/HOTFIX, PROPOSAL before PROP — BUG-010 longest-first rule.
  */
-function extractStoryIds(text) {
-  const matches = text.match(/STORY-\d+-\d+/g) || [];
-  return [...new Set(matches)];
+function extractWorkItemIds(text) {
+  const re = /(STORY-\d+-\d+|(CR|BUG|EPIC|HOTFIX)-\d+|(PROPOSAL|PROP)-\d+)/g;
+  const raw = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    raw.push(m[0]);
+  }
+  // BUG-009 normalize: PROP-NNN → PROPOSAL-NNN
+  const normalised = raw.map((id) => id.replace(/^PROP-(\d+)$/, 'PROPOSAL-$1'));
+  return [...new Set(normalised)];
 }
 
 /**
- * Check whether pending-sync contains a file matching STORY-<id>_*.md
- * Returns the matching filename or null.
+ * Check whether pending-sync OR archive contains a file matching <ID>_*.md
+ * Returns the matching absolute path or null.
  */
-function findStoryFile(repoRoot, storyId) {
-  const pendingSync = path.join(repoRoot, '.cleargate', 'delivery', 'pending-sync');
-  let entries;
+function findWorkItemFile(repoRoot, workItemId) {
+  const searchDirs = [
+    path.join(repoRoot, '.cleargate', 'delivery', 'pending-sync'),
+    path.join(repoRoot, '.cleargate', 'delivery', 'archive'),
+  ];
+  const prefix = `${workItemId}_`;
+  for (const dir of searchDirs) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    const match = entries.find(
+      (e) => e.startsWith(prefix) && e.endsWith('.md')
+    );
+    if (match) return path.join(dir, match);
+  }
+  return null;
+}
+
+/**
+ * Inline YAML frontmatter extractor.
+ * Returns { approved: boolean, has_heading: boolean }.
+ *
+ * - approved: frontmatter contains `approved: true` (quoted or unquoted).
+ * - has_heading: body after frontmatter contains at least one "## " line.
+ *
+ * Tolerate files with no frontmatter (approved=false, has_heading per body scan).
+ */
+function assertWorkItemApproved(filePath) {
+  let content;
   try {
-    entries = fs.readdirSync(pendingSync);
+    content = fs.readFileSync(filePath, 'utf8');
   } catch {
-    return null;
+    return { approved: false, has_heading: false };
   }
-  const prefix = `${storyId}_`;
-  const match = entries.find(
-    (e) => e.startsWith(prefix) && e.endsWith('.md')
-  );
-  return match ? path.join(pendingSync, match) : null;
+
+  let body = content;
+  let approved = false;
+
+  // Match YAML frontmatter block: starts with --- on first line
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (fmMatch) {
+    const fmBlock = fmMatch[1];
+    body = fmMatch[2] ?? '';
+
+    // Look for `approved: true` (unquoted) or `approved: "true"` (quoted)
+    const approvedMatch = fmBlock.match(/^approved:\s*["']?(true)["']?\s*$/m);
+    approved = approvedMatch !== null;
+  }
+
+  // has_heading: body contains at least one "## " markdown heading
+  const has_heading = /^## /m.test(body);
+
+  return { approved, has_heading };
 }
 
 /**
  * Main assertion logic.
- * Returns { missing: string[], present: string[] }
+ * Returns { missing: string[], present: string[], unapproved: string[], empty: string[] }
+ *
+ * - missing:    id referenced in §1 with no file in pending-sync/ or archive/
+ * - present:    id with a file found
+ * - unapproved: present but approved: false in frontmatter
+ * - empty:      present + approved but body has no ## heading (stub)
  */
-function assertStoryFiles(sprintFilePath, repoRoot) {
+function assertWorkItemFiles(sprintFilePath, repoRoot) {
   let content;
   try {
     content = fs.readFileSync(sprintFilePath, 'utf8');
@@ -98,25 +171,34 @@ function assertStoryFiles(sprintFilePath, repoRoot) {
     process.exit(2);
   }
 
-  const storyIds = extractStoryIds(section);
-  if (storyIds.length === 0) {
-    process.stderr.write('Warning: no STORY-IDs found in §1 Consolidated Deliverables\n');
+  const workItemIds = extractWorkItemIds(section);
+  if (workItemIds.length === 0) {
+    process.stderr.write('Warning: no work-item IDs found in §1 Consolidated Deliverables\n');
     // Return empty — no files to check, nothing is missing
-    return { missing: [], present: [] };
+    return { missing: [], present: [], unapproved: [], empty: [] };
   }
 
   const missing = [];
   const present = [];
-  for (const id of storyIds) {
-    const found = findStoryFile(repoRoot, id);
+  const unapproved = [];
+  const empty = [];
+
+  for (const id of workItemIds) {
+    const found = findWorkItemFile(repoRoot, id);
     if (found) {
       present.push(id);
+      const { approved, has_heading } = assertWorkItemApproved(found);
+      if (!approved) {
+        unapproved.push(id);
+      } else if (!has_heading) {
+        empty.push(id);
+      }
     } else {
       missing.push(id);
     }
   }
 
-  return { missing, present };
+  return { missing, present, unapproved, empty };
 }
 
 function main() {
@@ -125,21 +207,36 @@ function main() {
 
   const sprintFilePath = path.resolve(args[0]);
 
-  const { missing, present } = assertStoryFiles(sprintFilePath, REPO_ROOT);
+  // Allow test-isolation override of execution_mode
+  const execMode = process.env.CLEARGATE_EXEC_MODE ?? 'v2';
+
+  const { missing, present, unapproved, empty } = assertWorkItemFiles(sprintFilePath, REPO_ROOT);
 
-  if (missing.length === 0) {
+  const hasProblems = missing.length > 0 || unapproved.length > 0 || empty.length > 0;
+
+  if (!hasProblems) {
     process.stdout.write(
-      `OK: all ${present.length} story file(s) present in pending-sync/\n`
+      `OK: all ${present.length} work-item file(s) present, approved, and non-empty in pending-sync/ or archive/\n`
     );
     process.exit(0);
-  } else {
-    process.stderr.write(
-      JSON.stringify({ missing, present }, null, 2) + '\n'
-    );
-    process.stderr.write(
-      `MISSING: ${missing.length} story file(s) not found in pending-sync/: ${missing.join(', ')}\n`
-    );
+  }
+
+  // Build structured stderr output
+  if (missing.length > 0) {
+    process.stderr.write(`MISSING (${missing.length}): ${missing.join(', ')}\n`);
+  }
+  if (unapproved.length > 0) {
+    process.stderr.write(`UNAPPROVED (${unapproved.length}): ${unapproved.join(', ')}\n`);
+  }
+  if (empty.length > 0) {
+    process.stderr.write(`STUB-EMPTY (${empty.length}): ${empty.join(', ')}\n`);
+  }
+
+  if (execMode === 'v2') {
     process.exit(1);
+  } else {
+    // v1: warn only, exit 0
+    process.exit(0);
   }
 }
 

package/templates/cleargate-planning/.cleargate/scripts/close_sprint.mjs

@@ -32,6 +32,29 @@ import { execSync } from 'node:child_process';
 import { TERMINAL_STATES } from './constants.mjs';
 import { validateState } from './validate_state.mjs';
 
+/**
+ * Migrate a v1 state.json to v2 by injecting lane fields with defaults.
+ * Inlined from update_state.mjs:migrateV1ToV2 to avoid triggering that
+ * script's CLI main() on import (update_state.mjs has no module guard).
+ * @param {object} state - Parsed v1 state object
+ * @returns {object} - The mutated (now v2) state object
+ */
+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;
+}
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const SCRIPTS_DIR = __dirname;
@@ -129,6 +152,12 @@ function main() {
     process.exit(1);
   }
 
+  // Migrate v1 → v2 if needed before strict validation
+  if (state.schema_version === 1) {
+    state = migrateV1ToV2(state);
+    atomicWrite(stateFile, state);
+  }
+
   const { valid, errors } = validateState(state);
   if (!valid) {
     process.stderr.write('Error: state.json validation failed:\n');
@@ -154,6 +183,70 @@ function main() {
 
   process.stdout.write(`Step 1-2 passed: all ${Object.keys(state.stories || {}).length} stories are terminal.\n`);
 
+  // ── Step 2.5: v2.1 validation — activation-gated ──────────────────────────
+  // Activation gate: schema_version >= 2 AND at least one story has lane: 'fast'
+  const isV2 = (state.schema_version || 1) >= 2;
+  const hasFastLane = isV2 && Object.values(state.stories || {}).some(
+    (s) => /** @type {any} */ (s).lane === 'fast'
+  );
+
+  if (isV2 && hasFastLane) {
+    // Naming convention: sprint dir must match ^SPRINT-\d{2,3}$
+    const sprintDirName = path.basename(sprintDir);
+    if (!/^SPRINT-\d{2,3}$/.test(sprintDirName)) {
+      process.stderr.write(
+        `close_sprint: sprint dir "${sprintDirName}" does not match ^SPRINT-\\d{2,3}$\n` +
+        `  Expected format: SPRINT-NN or SPRINT-NNN (e.g. SPRINT-14)\n` +
+        `  Got: "${sprintDirName}" at path: ${sprintDir}\n`
+      );
+      process.exit(1);
+    }
+
+    // Read REPORT.md
+    const reportFile2 = path.join(sprintDir, 'REPORT.md');
+    if (!fs.existsSync(reportFile2)) {
+      process.stderr.write(
+        `close_sprint: v2.1 validation requires REPORT.md at ${reportFile2}\n` +
+        '  Run the Reporter agent first, then re-run close_sprint.mjs.\n'
+      );
+      process.exit(1);
+    }
+    const report = fs.readFileSync(reportFile2, 'utf8');
+
+    // Check required §3 metric rows
+    const requiredMetricRows = [
+      /Fast-Track Ratio/,
+      /Fast-Track Demotion Rate/,
+      /Hotfix Count/,
+      /Hotfix-to-Story Ratio/,
+      /Hotfix Cap Breaches/,
+      /LD events/,
+    ];
+    const missingMetrics = requiredMetricRows.filter((rx) => !rx.test(report));
+    if (missingMetrics.length > 0) {
+      process.stderr.write(
+        `close_sprint: §3 missing rows: ${missingMetrics.map((rx) => rx.source).join(', ')}\n`
+      );
+      process.exit(1);
+    }
+
+    // Check required §5 sections
+    const requiredSections = [
+      /Lane Audit/,
+      /Hotfix Audit/,
+      /Hotfix Trend/,
+    ];
+    const missingSections = requiredSections.filter((rx) => !rx.test(report));
+    if (missingSections.length > 0) {
+      process.stderr.write(
+        `close_sprint: §5 missing: ${missingSections.map((rx) => rx.source).join(', ')}\n`
+      );
+      process.exit(1);
+    }
+
+    process.stdout.write('Step 2.5 passed: v2.1 validation — all required §3 metrics and §5 sections present.\n');
+  }
+
   // ── Step 3: Invoke prefill_report.mjs ─────────────────────────────────────
   process.stdout.write('Step 3: running prefill_report.mjs...\n');
   try {

package/templates/cleargate-planning/.cleargate/scripts/constants.mjs

@@ -1,10 +1,10 @@
 /**
  * ClearGate Execution Phase v2 — Constants
  *
- * state.json v1 Schema (LOCKED — any future field change must bump schema_version):
+ * state.json v2 Schema (LOCKED — any future field change must bump schema_version):
  *
  * {
- *   "schema_version": 1,          // integer, mandatory
+ *   "schema_version": 2,          // integer, mandatory
  *   "sprint_id": "S-NN",          // string
  *   "execution_mode": "v1"|"v2",  // string
  *   "sprint_status": "Active",    // string
@@ -15,7 +15,11 @@
  *       "arch_bounces": 0,           // integer 0..BOUNCE_CAP
  *       "worktree": null,            // string|null — path to worktree checkout
  *       "updated_at": "<ISO-8601>",  // string
- *       "notes": ""                  // string
+ *       "notes": "",                 // string
+ *       "lane": "standard",          // additive v2; default "standard"
+ *       "lane_assigned_by": "architect" | "human-override" | "migration-default",
+ *       "lane_demoted_at": "<ISO-8601>" | null,
+ *       "lane_demotion_reason": string | null
  *     }
  *   },
  *   "last_action": "<string>",    // human-readable last operation
@@ -23,7 +27,7 @@
  * }
  */
 
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 export const BOUNCE_CAP = 3;
 

package/templates/cleargate-planning/.cleargate/scripts/init_sprint.mjs

@@ -139,8 +139,12 @@ function main() {
       if (executionMode === 'v2') {
         // Hard block: do not create state.json
         process.stderr.write(stderr);
+        // Count categories from structured stderr lines
+        const missingCount = (stderr.match(/^MISSING \((\d+)\):/m) ?? [])[1] ?? '0';
+        const unapprovedCount = (stderr.match(/^UNAPPROVED \((\d+)\):/m) ?? [])[1] ?? '0';
+        const emptyCount = (stderr.match(/^STUB-EMPTY \((\d+)\):/m) ?? [])[1] ?? '0';
         process.stderr.write(
-          `ERROR: v2 sprint init blocked — story files missing. Fix the above, then re-run init.\n`
+          `ERROR: v2 sprint init blocked — ${missingCount} items missing, ${unapprovedCount} unapproved, ${emptyCount} stub-empty. Fix the above, then re-run init.\n`
         );
         process.exit(1);
       } else {
@@ -162,6 +166,10 @@ function main() {
       worktree: null,
       updated_at: now,
       notes: '',
+      lane: 'standard',
+      lane_assigned_by: 'migration-default',
+      lane_demoted_at: null,
+      lane_demotion_reason: null,
     };
   }
 

package/templates/cleargate-planning/.cleargate/scripts/pre_gate_common.sh

@@ -104,6 +104,80 @@ detect_stack() {
   fi
 }
 
+# ---------------------------------------------------------------------------
+# resolve_story_id_from_branch <branch>
+# Extracts story/CR/bug ID from a branch name like story/STORY-022-04.
+# Pattern (per M4 plan §1): (story|cr|bug)/([A-Z-]+-[0-9]+(-[0-9]+)?)
+# Returns the ID (group 2) on stdout, or empty string on no match.
+# Cross-OS: bash 3.2+, POSIX ERE grep -E, quoted expansions, no sed -E extensions.
+# ---------------------------------------------------------------------------
+resolve_story_id_from_branch() {
+  local branch="$1"
+  # Match the full pattern and extract just the ID part after the slash
+  local matched
+  matched="$(printf '%s\n' "${branch}" | grep -oE '(story|cr|bug)/[A-Z][A-Z-]*[A-Z]-[0-9]+(-[0-9]+)?' | head -1 || true)"
+  if [[ -n "${matched}" ]]; then
+    # Strip the (story|cr|bug)/ prefix — everything up to and including first /
+    printf '%s\n' "${matched#*/}"
+  else
+    printf ''
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# resolve_lane <state_json_path> <story_id>
+# Reads the lane field for a story from state.json.
+# Returns "standard" if story absent, lane absent, or jq fails.
+# jq 1.5+ syntax. Cross-OS portable.
+# ---------------------------------------------------------------------------
+resolve_lane() {
+  local state_json="$1"
+  local story_id="$2"
+  if [[ ! -f "${state_json}" ]]; then
+    printf 'standard\n'
+    return
+  fi
+  local lane
+  lane="$(jq -r --arg sid "${story_id}" '.stories[$sid].lane // "standard"' "${state_json}" 2>/dev/null || printf 'standard')"
+  if [[ -z "${lane}" || "${lane}" = "null" ]]; then
+    lane="standard"
+  fi
+  printf '%s\n' "${lane}"
+}
+
+# ---------------------------------------------------------------------------
+# append_ld_event <sprint_md_path> <story_id> <reason>
+# Appends an LD event row to the sprint markdown §4 Events section.
+# If "## 4. Events" heading absent, creates it with table header first.
+# Idempotent by design (orchestrator calls once per demotion).
+# Cross-OS: bash 3.2+, portable date, printf.
+# ---------------------------------------------------------------------------
+append_ld_event() {
+  local sprint_md="$1"
+  local story_id="$2"
+  local reason="$3"
+  local timestamp
+  timestamp="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+  # Truncate reason to 80 chars
+  reason="$(printf '%s' "${reason}" | cut -c1-80)"
+
+  if [[ ! -f "${sprint_md}" ]]; then
+    printf 'append_ld_event: sprint markdown not found: %s\n' "${sprint_md}" >&2
+    return 1
+  fi
+
+  local row
+  row="$(printf '| LD | %s | %s | %s |' "${story_id}" "${timestamp}" "${reason}")"
+
+  if grep -q '^## 4\. Events' "${sprint_md}" 2>/dev/null; then
+    # Section exists: append row only
+    printf '\n%s\n' "${row}" >> "${sprint_md}"
+  else
+    # Section absent: append heading + table header + row
+    printf '\n## 4. Events\n\n| Event | Story | Timestamp | Reason |\n|---|---|---|---|\n%s\n' "${row}" >> "${sprint_md}"
+  fi
+}
+
 # ---------------------------------------------------------------------------
 # diff_package_json <worktree_path> <branch>
 # Prints new runtime deps (non-dev) introduced vs <branch>^.

package/templates/cleargate-planning/.cleargate/scripts/pre_gate_runner.sh

@@ -304,4 +304,68 @@ esac
 
 cat "$REPORT_FILE" >&2
 
-exit $OVERALL_EXIT
+# ---------------------------------------------------------------------------
+# Lane-aware post-scan routing (STORY-022-04)
+# Resolve REPO_ROOT from SCRIPT_DIR (scripts/ lives two levels below repo root)
+# ---------------------------------------------------------------------------
+REPO_ROOT_FOR_LANE="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+ACTIVE_FILE="${REPO_ROOT_FOR_LANE}/.cleargate/sprint-runs/.active"
+
+STORY_ID=""
+if [[ -n "${BRANCH:-}" ]]; then
+  STORY_ID="$(resolve_story_id_from_branch "${BRANCH}")"
+fi
+
+STATE_JSON=""
+SPRINT_ID=""
+SPRINT_MD=""
+if [[ -f "${ACTIVE_FILE}" ]]; then
+  SPRINT_ID="$(cat "${ACTIVE_FILE}" | tr -d '[:space:]')"
+  STATE_JSON="${REPO_ROOT_FOR_LANE}/.cleargate/sprint-runs/${SPRINT_ID}/state.json"
+  # Sprint markdown lives in delivery/pending-sync/
+  SPRINT_MD="$(ls "${REPO_ROOT_FOR_LANE}/.cleargate/delivery/pending-sync/${SPRINT_ID}_"*.md 2>/dev/null | head -1 || true)"
+fi
+
+LANE="standard"
+if [[ -n "${STORY_ID}" && -n "${STATE_JSON}" ]]; then
+  LANE="$(resolve_lane "${STATE_JSON}" "${STORY_ID}")"
+fi
+
+if [[ "${LANE}" = "fast" ]]; then
+  if [[ "${OVERALL_EXIT}" -eq 0 ]]; then
+    # Fast lane + scanner pass: skip QA spawn signal
+    printf 'pre-gate: lane=fast -> skipping QA spawn for %s\n' "${STORY_ID}"
+    if [[ -n "${STATE_JSON}" ]]; then
+      # Positional invocation: node update_state.mjs <STORY-ID> <new-state>
+      CLEARGATE_STATE_FILE="${STATE_JSON}" \
+        node "${SCRIPT_DIR}/update_state.mjs" "${STORY_ID}" "Architect Passed" \
+        > /dev/null 2>&1 || true
+    fi
+    exit 0
+  else
+    # Fast lane + scanner fail: auto-demote + LD event
+    SCANNER_FAIL_REASON="pre-gate scanner failed (exit ${OVERALL_EXIT})"
+    if [[ -n "${STATE_JSON}" ]]; then
+      # Positional invocation: node update_state.mjs <STORY-ID> --lane-demote <reason>
+      # Capture exit independently per FLASHCARD #hooks #bash #exit-capture 2026-04-26
+      _tmp_demote_out="$(mktemp)"
+      CLEARGATE_STATE_FILE="${STATE_JSON}" \
+        node "${SCRIPT_DIR}/update_state.mjs" "${STORY_ID}" --lane-demote \
+        "${SCANNER_FAIL_REASON}" > "${_tmp_demote_out}" 2>&1
+      _demote_exit=$?
+      rm -f "${_tmp_demote_out}"
+      if [[ ${_demote_exit} -ne 0 ]]; then
+        printf 'pre-gate: warn: lane-demote failed (exit %s) for %s\n' \
+          "${_demote_exit}" "${STORY_ID}" >&2
+      fi
+    fi
+    if [[ -n "${SPRINT_MD}" ]]; then
+      append_ld_event "${SPRINT_MD}" "${STORY_ID}" "${SCANNER_FAIL_REASON}"
+    fi
+    # Exit with the original scanner exit code so orchestrator routes to QA
+    exit "${OVERALL_EXIT}"
+  fi
+fi
+
+# lane=standard (or unknown/missing): existing behaviour
+exit "${OVERALL_EXIT}"

package/templates/cleargate-planning/.cleargate/scripts/state.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://cleargate.dev/schemas/state.v1.json",
-  "title": "ClearGate Sprint State v1",
-  "description": "Schema for .cleargate/sprint-runs/<sprint-id>/state.json. schema_version=1 is LOCKED — any field addition or removal must bump schema_version.",
+  "$id": "https://cleargate.dev/schemas/state.v2.json",
+  "title": "ClearGate Sprint State v2",
+  "description": "Schema for .cleargate/sprint-runs/<sprint-id>/state.json. schema_version=2 adds per-story lane fields (lane, lane_assigned_by, lane_demoted_at, lane_demotion_reason). Migrated from v1 on first read by update_state.mjs.",
   "type": "object",
   "required": [
     "schema_version",
@@ -13,12 +13,12 @@
     "last_action",
     "updated_at"
   ],
-  "additionalProperties": false,
+  "additionalProperties": true,
   "properties": {
     "schema_version": {
       "type": "integer",
-      "const": 1,
-      "description": "Schema version. Must be 1 for v1 state files. Bump on any schema change."
+      "const": 2,
+      "description": "Schema version. Must be 2 for v2 state files. Bumped from v1 by migration in update_state.mjs."
     },
     "sprint_id": {
       "type": "string",
@@ -61,9 +61,13 @@
         "arch_bounces",
         "worktree",
         "updated_at",
-        "notes"
+        "notes",
+        "lane",
+        "lane_assigned_by",
+        "lane_demoted_at",
+        "lane_demotion_reason"
       ],
-      "additionalProperties": false,
+      "additionalProperties": true,
       "properties": {
         "state": {
           "type": "string",
@@ -103,6 +107,25 @@
         "notes": {
           "type": "string",
           "description": "Free-form notes for this story (escalation reason, QA comments, etc.)"
+        },
+        "lane": {
+          "type": "string",
+          "enum": ["standard", "fast"],
+          "description": "Execution lane for this story. Default 'standard'. Set by Architect at sprint design or via --lane flag."
+        },
+        "lane_assigned_by": {
+          "type": "string",
+          "enum": ["architect", "human-override", "migration-default"],
+          "description": "Who assigned the lane value. 'migration-default' for stories migrated from v1."
+        },
+        "lane_demoted_at": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "ISO-8601 timestamp when the story was demoted from fast to standard, or null if never demoted."
+        },
+        "lane_demotion_reason": {
+          "type": ["string", "null"],
+          "description": "Human-readable reason for lane demotion, or null if never demoted."
         }
       }
     }