cleargate 0.5.0 → 0.6.0

package/dist/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/dist/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/dist/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>)`.

package/dist/templates/cleargate-planning/.claude/hooks/pre-edit-gate.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# pre-edit-gate.sh — CR-008 Phase B: planning-first PreToolUse gate
+#
+# Registered as a PreToolUse hook for Edit|Write tool calls.
+# In warn mode (default), logs would-block decisions but always exits 0.
+# In enforce mode, exits 1 to block the tool call when planning is missing.
+#
+# Mode controlled by CLEARGATE_PLANNING_GATE_MODE (warn|enforce|off). Default: warn.
+# Bypass: CLEARGATE_PLANNING_BYPASS=1 → skip check, log bypass=true, exit 0.
+
+set -u
+
+REPO_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+MODE="${CLEARGATE_PLANNING_GATE_MODE:-warn}"
+LOG_FILE="${REPO_ROOT}/.cleargate/hook-log/pre-edit-gate-warn.log"
+
+# ── 0. Off mode — do nothing ──────────────────────────────────────────────────
+if [ "${MODE}" = "off" ]; then
+  exit 0
+fi
+
+# ── 1. Read file path from stdin (PreToolUse JSON payload) ────────────────────
+# Claude Code sends JSON on stdin: {"tool_name":"Edit","tool_input":{"file_path":"..."}}
+INPUT=$(cat)
+FILE=$(printf '%s' "${INPUT}" | node -e "
+try {
+  var d = require('fs').readFileSync('/dev/stdin','utf8');
+  var o = JSON.parse(d);
+  var fp = (o.tool_input && o.tool_input.file_path) ? o.tool_input.file_path : '';
+  process.stdout.write(fp);
+} catch(e) {
+  process.stdout.write('');
+}
+" 2>/dev/null || true)
+
+TOOL_NAME=$(printf '%s' "${INPUT}" | node -e "
+try {
+  var d = require('fs').readFileSync('/dev/stdin','utf8');
+  var o = JSON.parse(d);
+  process.stdout.write(o.tool_name || '');
+} catch(e) {
+  process.stdout.write('');
+}
+" 2>/dev/null || true)
+
+# ── Guard: if we couldn't parse the file path, fail-open ──────────────────────
+if [ -z "${FILE}" ]; then
+  exit 0
+fi
+
+# ── 2. Bypass env var ─────────────────────────────────────────────────────────
+if [ "${CLEARGATE_PLANNING_BYPASS:-0}" = "1" ]; then
+  ISO_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+  mkdir -p "$(dirname "${LOG_FILE}")"
+  printf '[%s] mode=%s bypass=true file=%s\n' "${ISO_TS}" "${MODE}" "${FILE}" >> "${LOG_FILE}"
+  exit 0
+fi
+
+# ── 3. Whitelist: always allow these paths ────────────────────────────────────
+# Normalise: strip leading REPO_ROOT prefix for matching
+REL_FILE="${FILE}"
+if [[ "${FILE}" == "${REPO_ROOT}/"* ]]; then
+  REL_FILE="${FILE#${REPO_ROOT}/}"
+fi
+
+is_whitelisted() {
+  local f="$1"
+  # Exact or prefix matches for whitelisted directories/files
+  case "${f}" in
+    .cleargate/*|.claude/*|cleargate-planning/*) return 0 ;;
+    CLAUDE.md|MANIFEST.json|README.md|.gitignore|.gitkeep) return 0 ;;
+    package.json|package-lock.json) return 0 ;;
+    .env|.env.*|.npmrc|.editorconfig) return 0 ;;
+    # Also allow absolute paths that fall under the repo's cleargate dirs
+  esac
+  # Check absolute path variants
+  case "${FILE}" in
+    "${REPO_ROOT}/.cleargate/"*|"${REPO_ROOT}/.claude/"*|"${REPO_ROOT}/cleargate-planning/"*) return 0 ;;
+  esac
+  return 1
+}
+
+if is_whitelisted "${REL_FILE}"; then
+  exit 0
+fi
+
+# ── 3.5 Sprint-active sentinel bypass ────────────────────────────────────────
+# If a sprint is actively running, all in-sprint edits bypass the gate.
+if [ -f "${REPO_ROOT}/.cleargate/sprint-runs/.active" ]; then
+  exit 0
+fi
+
+# ── 4. Resolve cleargate CLI (three-branch resolver — CR-009) ────────────────
+if [ -f "${REPO_ROOT}/cleargate-cli/dist/cli.js" ]; then
+  CG=(node "${REPO_ROOT}/cleargate-cli/dist/cli.js")
+elif command -v cleargate >/dev/null 2>&1; then
+  CG=(cleargate)
+else
+  # Read pinned version from stamp-and-gate.sh
+  HOOK_PIN=""
+  HOOK_SH="${REPO_ROOT}/.claude/hooks/stamp-and-gate.sh"
+  if [ -f "${HOOK_SH}" ]; then
+    HOOK_PIN=$(grep -oP '(?<=# cleargate-pin: )[\S]+' "${HOOK_SH}" 2>/dev/null || \
+               grep -oE 'cleargate@[^"]+' "${HOOK_SH}" 2>/dev/null | head -1 | sed 's/.*@//' || true)
+  fi
+  if [ -z "${HOOK_PIN}" ]; then
+    HOOK_PIN="__CLEARGATE_VERSION__"
+  fi
+  CG=(npx -y "cleargate@${HOOK_PIN}")
+fi
+
+# ── 5. Read user prompt snippet for log context (optional; best-effort) ───────
+PROMPT_SNIPPET=$(printf '%s' "${INPUT}" | node -e "
+try {
+  var d = require('fs').readFileSync('/dev/stdin','utf8');
+  var o = JSON.parse(d);
+  var p = (o.user_prompt || '').slice(0, 200);
+  process.stdout.write(p);
+} catch(e) {
+  process.stdout.write('');
+}
+" 2>/dev/null || true)
+
+# ── 6. Ask doctor --can-edit ──────────────────────────────────────────────────
+# Capture both stdout AND exit code without || true swallowing the exit code.
+_DOCTOR_TMPFILE=$(mktemp)
+"${CG[@]}" doctor --can-edit "${FILE}" --cwd "${REPO_ROOT}" > "${_DOCTOR_TMPFILE}" 2>/dev/null
+DOCTOR_EXIT=$?
+DOCTOR_OUT=$(cat "${_DOCTOR_TMPFILE}")
+rm -f "${_DOCTOR_TMPFILE}"
+
+# Parse reason from doctor output
+REASON=$(printf '%s' "${DOCTOR_OUT}" | grep -oP '(?<=blocked: )\S+' 2>/dev/null || \
+         printf '%s' "${DOCTOR_OUT}" | sed -n 's/blocked: //p' 2>/dev/null || \
+         echo "unknown")
+
+# Count approved stories in pending-sync (for log entry)
+PENDING_DIR="${REPO_ROOT}/.cleargate/delivery/pending-sync"
+PENDING_MATCH_COUNT=0
+if [ -d "${PENDING_DIR}" ]; then
+  PENDING_MATCH_COUNT=$(grep -rl 'approved: true' "${PENDING_DIR}" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+fi
+
+# ── 7. Gate decision ──────────────────────────────────────────────────────────
+if [ "${DOCTOR_EXIT}" -ne 0 ]; then
+  # Would block
+  ISO_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+  mkdir -p "$(dirname "${LOG_FILE}")"
+  printf '[%s] mode=%s would_block file=%s reason=%s tool=%s pending_match_count=%d prompt_snippet=%s\n' \
+    "${ISO_TS}" "${MODE}" "${FILE}" "${REASON}" "${TOOL_NAME}" "${PENDING_MATCH_COUNT}" "${PROMPT_SNIPPET}" \
+    >> "${LOG_FILE}"
+
+  if [ "${MODE}" = "enforce" ]; then
+    printf 'ClearGate: planning-first gate — no approved story covers %s (%s). Draft a work item first.\n' \
+      "${FILE}" "${REASON}" >&2
+    exit 1
+  fi
+
+  # warn mode: log written above, exit 0 (do not block)
+fi
+
+exit 0

package/dist/templates/cleargate-planning/.claude/hooks/session-start.sh

@@ -2,17 +2,20 @@
 set -u
 REPO_ROOT="${CLAUDE_PROJECT_DIR}"
 
-# Resolve cleargate CLI: prefer on-PATH binary, fall back to meta-repo-local
-# dist. If neither is present, this hook is a no-op (BUG-006).
-if command -v cleargate >/dev/null 2>&1; then
-  CG=(cleargate)
-elif [ -f "${REPO_ROOT}/cleargate-cli/dist/cli.js" ]; then
+# cleargate-pin: __CLEARGATE_VERSION__
+# Resolve cleargate CLI (three-branch resolver — CR-009):
+#   1. meta-repo dogfood dist (fastest; only present in ClearGate's own repo)
+#   2. on-PATH binary (global install or shim)
+#   3. pinned npx invocation (always works wherever Node is present)
+if [ -f "${REPO_ROOT}/cleargate-cli/dist/cli.js" ]; then
   CG=(node "${REPO_ROOT}/cleargate-cli/dist/cli.js")
+elif command -v cleargate >/dev/null 2>&1; then
+  CG=(cleargate)
 else
-  exit 0
+  CG=(npx -y "cleargate@__CLEARGATE_VERSION__")
 fi
 
-"${CG[@]}" doctor --session-start 2>/dev/null || true
+"${CG[@]}" doctor --session-start || true
 
 # ── §14.9 SessionStart sync nudge (STORY-010-08) ─────────────────────────────
 # Daily-throttled: probe remote for updates at most once per 24h.

package/dist/templates/cleargate-planning/.claude/hooks/stamp-and-gate.sh

@@ -4,16 +4,17 @@ REPO_ROOT="${CLAUDE_PROJECT_DIR}"
 LOG="${REPO_ROOT}/.cleargate/hook-log/gate-check.log"
 mkdir -p "$(dirname "$LOG")"
 
-# Resolve cleargate CLI: prefer on-PATH binary (`npm i -g cleargate` / `npx`),
-# fall back to a meta-repo-local dist (dogfood case). If neither is present,
-# log a remediation message and exit 0 (BUG-006).
-if command -v cleargate >/dev/null 2>&1; then
-  CG=(cleargate)
-elif [ -f "${REPO_ROOT}/cleargate-cli/dist/cli.js" ]; then
+# cleargate-pin: __CLEARGATE_VERSION__
+# Resolve cleargate CLI (three-branch resolver — CR-009):
+#   1. meta-repo dogfood dist (fastest; only present in ClearGate's own repo)
+#   2. on-PATH binary (global install or shim)
+#   3. pinned npx invocation (always works wherever Node is present)
+if [ -f "${REPO_ROOT}/cleargate-cli/dist/cli.js" ]; then
   CG=(node "${REPO_ROOT}/cleargate-cli/dist/cli.js")
+elif command -v cleargate >/dev/null 2>&1; then
+  CG=(cleargate)
 else
-  echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] cleargate CLI not found — install with 'npm i -g cleargate' or run via 'npx cleargate'. Hook skipped." >>"$LOG"
-  exit 0
+  CG=(npx -y "cleargate@__CLEARGATE_VERSION__")
 fi
 
 FILE=$(jq -r '.tool_input.file_path' 2>/dev/null || echo "")

package/dist/templates/cleargate-planning/.claude/hooks/token-ledger.sh

@@ -15,12 +15,21 @@
 #              misrouted SPRINT-04 firings to SPRINT-03 because ledger appends
 #              themselves bumped SPRINT-03's mtime. See REPORT.md SPRINT-04.
 #
-# Work-item ID detection (GENERALIZED 2026-04-19 STORY-008-04):
+# Work-item ID detection (GENERALIZED 2026-04-19 STORY-008-04, SCOPED 2026-04-26 BUG-010):
 #   Primary  : first user message in the transcript — that's the orchestrator's
 #              dispatch prompt, which by agent convention starts with
 #              `STORY=NNN-NN`, `PROPOSAL-NNN`, `EPIC-NNN`, `CR-NNN`, or `BUG-NNN`.
-#   Pattern  : (STORY|PROPOSAL|EPIC|CR|BUG)[-=]?[0-9]+(-[0-9]+)?
-#   Fallback : grep first match anywhere in the transcript.
+#   Scoping  : look ONLY at lines whose FIRST CHARACTER matches the dispatch-marker
+#              pattern (line-anchored). The SessionStart hook emits a "blocked items"
+#              reminder that lists work-item IDs in prose/bullets — those lines start
+#              with "- " or whitespace, never with the marker prefix. Scanning the full
+#              content caused BUG-010: all SPRINT-14 rows tagged BUG-002 (first item in
+#              the reminder list). Fix: join content with \n, split, filter line-starts.
+#   Pattern  : ^(STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=][0-9]...
+#              PROP-NNN is normalised to PROPOSAL-NNN after match (BUG-009, 2026-04-26)
+#   Tie-break: when multiple dispatch-marker lines appear in the first user message,
+#              the FIRST line wins (deterministic; orchestrator puts the marker first).
+#   Fallback : grep first line-start match anywhere in the transcript.
 #   story_id : populated only when the match is a STORY-* (backward compat).
 #   work_item_id: always populated when detection succeeds; equals story_id for STORY items.
 #   (Removed): grep-first-anywhere as PRIMARY — it picked up SPRINT-05 mentions
@@ -107,28 +116,42 @@ ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
   fi
 
   # --- detect work_item_id (PRIMARY: first user message; FALLBACK: anywhere-grep) ---
-  # Orchestrator convention (.claude/agents/developer.md): the first line of the
-  # dispatch prompt is `STORY=NNN-NN`. The first user message in the transcript
-  # is that prompt. Look there first to avoid picking up work-item mentions inside
-  # the subagent's later reads of plans, sprint files, etc.
+  # Orchestrator convention (.claude/agents/developer.md): the FIRST LINE of the
+  # dispatch prompt is `STORY=NNN-NN` (or CR=NNN, BUG=NNN, EPIC=NNN, PROPOSAL=NNN,
+  # PROP=NNN). The SessionStart hook injects a "blocked items" reminder whose lines
+  # start with "- " or whitespace — never with the marker prefix. We therefore
+  # ONLY match lines whose first character is the start of the marker (line-anchored).
+  #
+  # BUG-010 (2026-04-26): joined with " " (space) before — scan() found BUG-002 from
+  # the reminder text. Fix: join with "\n" so line-anchored regex works.
   #
   # Pattern covers: STORY-NNN-NN, PROPOSAL-NNN, EPIC-NNN, CR-NNN, BUG-NNN
   # (and = separator variants like STORY=008-04)
+  # Tie-break: first line matching the anchor wins (orchestrator puts marker first).
   WORK_ITEM_RAW="$(jq -rs '
     [.[] | select(.type == "user")] | .[0].message.content
-    | if type == "array" then map(.text? // "") | join(" ") else (. // "") end
+    | if type == "array" then map(.text? // "") | join("\n") else (. // "") end
     | tostring
-    | scan("(STORY|PROPOSAL|EPIC|CR|BUG)[-=]?([0-9]+(-[0-9]+)?)") | .[0:2] | join("-")
+    | split("\n")
+    | map(select(test("^(STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=][0-9]")))
+    | .[0] // ""
+    | capture("^(?<kind>STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=](?<id>[0-9]+(-[0-9]+)?)")
+    | (.kind + "-" + .id)
   ' "${TRANSCRIPT_PATH}" 2>/dev/null | head -1)"
 
   if [[ -n "${WORK_ITEM_RAW}" && "${WORK_ITEM_RAW}" != "null" && "${WORK_ITEM_RAW}" != "-" ]]; then
     # Normalize: replace any = separator with - in the result
-    WORK_ITEM_ID="$(printf '%s' "${WORK_ITEM_RAW}" | sed 's/=/-/g')"
+    # Then normalize PROP-NNN → PROPOSAL-NNN (canonical form matches wiki/proposals/PROPOSAL-NNN.md filenames)
+    # BUG-009 (2026-04-26): PROP↔PROPOSAL normalization — PRESERVED BY BUG-010.
+    WORK_ITEM_ID="$(printf '%s' "${WORK_ITEM_RAW}" | sed 's/=/-/g' | sed 's/^PROP-/PROPOSAL-/')"
   else
-    # Fallback: grep anywhere in the transcript
-    WORK_ITEM_ID="$(grep -oE '(STORY|PROPOSAL|EPIC|CR|BUG)[-=]?[0-9]+(-[0-9]+)?' "${TRANSCRIPT_PATH}" 2>/dev/null \
+    # Fallback: grep for line-start dispatch markers anywhere in the transcript.
+    # Line-anchored (^) so that "- BUG-002:" reminder bullet lines are not matched —
+    # only lines whose first character starts the marker prefix.
+    # BUG-009 normalization preserved: sed 's/=/-/g' | sed 's/^PROP-/PROPOSAL-/'
+    WORK_ITEM_ID="$(grep -oE '^(STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=][0-9][0-9]*(-[0-9]+)?' "${TRANSCRIPT_PATH}" 2>/dev/null \
       | head -1 \
-      | sed 's/=/-/g')"
+      | sed 's/=/-/g' | sed 's/^PROP-/PROPOSAL-/')"
     if [[ -n "${WORK_ITEM_ID}" ]]; then
       printf '[%s] work_item_id fallback grep: %s\n' "$(date -u +%FT%TZ)" "${WORK_ITEM_ID}" >> "${HOOK_LOG}"
     fi

package/dist/templates/cleargate-planning/.claude/settings.json

@@ -19,6 +19,15 @@
             "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pending-task-sentinel.sh"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-edit-gate.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/dist/templates/cleargate-planning/.cleargate/knowledge/cleargate-protocol.md

@@ -108,6 +108,8 @@ Under `execution_mode: "v1"` this rule is **advisory only** — the orchestrator
 
 **v2 story-file assertion:** Additionally for v2 sprints, `cleargate sprint init` asserts every story in §1 Consolidated Deliverables has a `pending-sync/STORY-*.md` file before writing `state.json`; missing files block init with an enumerated stderr list. Under v1 the assertion runs but only warns (does not block). The assertion is also available standalone: `node .cleargate/scripts/assert_story_files.mjs <sprint-file-path>`.
 
+As of cleargate@0.6.x, sprint-init asserts all six work-item id shapes (STORY/CR/BUG/EPIC/PROPOSAL/HOTFIX). v2 mode hard-blocks on missing OR unapproved OR stub-empty items; v1 warns-only (backwards compat).
+
 ### Gate 3 — Push Gate
 
 - **Never call `cleargate_push_item` on a file where `approved: false`.**
@@ -913,3 +915,56 @@ wiki:
 ```
 
 Exceeding the ceiling fails `cleargate wiki lint` (enforcement mode). Under `--suggest`, the usage percentage is reported but the check does not fail. Reference: EPIC-015.
+
+---
+
+## 22. Advisory Readiness Gates on Push (v2) — CR-010
+
+### §22.1 Two-tier push gate semantics
+
+Push-time gate enforcement uses two distinct tiers:
+
+**Tier 1 — `approved: true` (hard reject, unchanged):**
+`cleargate_push_item` throws `PushNotApprovedError` when `payload.approved !== true`. This is the human go/no-go gate. No advisory mode or env knob overrides it.
+
+**Tier 2 — `cached_gate_result` (advisory by default):**
+When `cached_gate_result.pass === false`, the push proceeds in default advisory mode. The pushed item's body receives a single advisory prefix line placed immediately after the H1 heading (or as the first line if no H1 exists):
+
+```
+[advisory: gate_failed — <comma-separated criterion ids>]
+```
+
+Body content beyond the advisory prefix is byte-identical to the input. The push result includes `gate_status: 'open'` and `failing_criteria: [...]` as response metadata (not persisted to the DB schema).
+
+### §22.2 Strict-mode opt-in and audit log
+
+Set `STRICT_PUSH_GATES=true` on the MCP server to restore pre-CR-010 hard-reject behavior (`PushGateFailedError`, no DB write). Default: `false` (advisory mode).
+
+Advisory pushes (gate_status='open') are recorded in `audit_log` with `result='ok'` — the push succeeded. The `failing_criteria` are surfaced in the push response shape, not in a new audit column. No schema migration is required.
+**Rationale:** PM-tool answer-collection requires items to land before readiness answers arrive; advisory mode enables this. See CR-010 §0 for full evidence.
+
+---
+
+## 23. Doctor Exit-Code Semantics
+
+`cleargate doctor` exits with one of three codes (all modes: default, `--session-start`, `--can-edit`, `--check-scaffold`, `--pricing`). Hooks branch on the integer, not on stdout.
+- `0` — clean. No blockers, no config errors. Stdout MAY include informational lines.
+- `1` — blocked items or advisory issues (gate failures, stamp errors, drifted SHAs, missing ledger rows). Stdout lists each blocker.
+- `2` — ClearGate misconfigured or partially installed (missing `.cleargate/`, missing `MANIFEST.json`, missing `auth.json`, hook resolver failure). Stdout emits a remediation hint. See `cleargate doctor --help`.
+
+---
+
+## 24. Lane Routing
+
+A story is eligible for `lane: fast` only if all seven checks pass (any false → `standard`):
+1. **Size cap.** ≤2 files AND ≤50 LOC net (tests count; generated files do not).
+2. **No forbidden surfaces.** Story does not modify: `mcp/src/db/` / `**/migrations/` (schema); `mcp/src/auth/` / `mcp/src/admin-api/auth-*` (auth); `cleargate.config.json` / `mcp/src/config.ts` (runtime config); `mcp/src/adapters/` (adapter API); `cleargate-planning/MANIFEST.json` (scaffold manifest); security-relevant code (token handling, invite verification, gate enforcement).
+3. **No new dependency.** No new package added to any `package.json`.
+4. **Single acceptance scenario or doc-only.** Exactly one `Scenario:` block (or zero for doc-only). `Scenario Outline:` or multiple scenarios → `standard`.
+5. **Existing tests cover the runtime change.** Named test file exists and includes the affected module, OR story is doc/comment/non-runtime config only.
+6. **`expected_bounce_exposure: low`.** `med` or `high` is auto-`standard`.
+7. **No epic-spanning subsystem touches.** All affected files live under the parent epic's declared scope directories.
+
+**Demotion mechanics.** Demotion is one-way (`fast → standard`). Trigger: pre-gate scanner failure OR post-merge test failure on a fast-lane story. On demotion: set `lane = "standard"`, write `lane_demoted_at` (ISO-8601), `lane_demotion_reason`, reset `qa_bounces = 0` and `arch_bounces = 0` (see STORY-022-02 schema). Architect plan is invoked and QA spawned per standard contract.
+
+Event-type `LD` (Lane Demotion) is recorded in sprint markdown §4 alongside existing `UR` and `CR` events; Reporter aggregates into §3 Execution Metrics > Fast-Track Demotion Rate.

package/dist/templates/cleargate-planning/.cleargate/knowledge/readiness-gates.md

@@ -52,7 +52,7 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
     - id: touched-files-populated
       check: "section(3) has ≥1 listed-item"
     - id: no-tbds
-      check: "body does not contain 'TBD'"
+      check: "body does not contain marker 'TBD'"
 ```
 
 ```yaml
@@ -63,7 +63,7 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
     - id: proposal-approved
       check: "frontmatter(context_source).approved == true"
     - id: no-tbds
-      check: "body does not contain 'TBD'"
+      check: "body does not contain marker 'TBD'"
     - id: scope-in-populated
       check: "section(2) has ≥1 listed-item"
     - id: affected-files-declared
@@ -84,7 +84,7 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
     - id: gherkin-error-path
       check: "body contains 'Error'"
     - id: no-tbds
-      check: "body does not contain 'TBD'"
+      check: "body does not contain marker 'TBD'"
     - id: interrogation-resolved
       check: "body does not contain 'Unresolved'"
 ```
@@ -97,7 +97,7 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
     - id: parent-epic-ref-set
       check: "frontmatter(.).parent_epic_ref != null"
     - id: no-tbds
-      check: "body does not contain 'TBD'"
+      check: "body does not contain marker 'TBD'"
     - id: implementation-files-declared
       check: "section(3) has ≥1 listed-item"
     - id: dod-declared
@@ -112,9 +112,9 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
   severity: enforcing
   criteria:
     - id: blast-radius-populated
-      check: "section(1) has ≥1 listed-item"
+      check: "section(2) has ≥1 listed-item"
     - id: no-tbds
-      check: "body does not contain 'TBD'"
+      check: "body does not contain marker 'TBD'"
     - id: sandbox-paths-declared
       check: "section(2) has ≥1 listed-item"
 ```
@@ -129,5 +129,5 @@ The asymmetry exists because Proposal documents are human-authored strategy arti
     - id: severity-set
       check: "frontmatter(.).severity != null"
     - id: no-tbds
-      check: "body does not contain 'TBD'"
+      check: "body does not contain marker 'TBD'"
 ```