cleargate 0.2.0 → 0.3.0

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

@@ -32,7 +32,7 @@
 
 set -u
 
-REPO_ROOT="/Users/ssuladze/Documents/Dev/ClearGate"
+REPO_ROOT="${ORCHESTRATOR_PROJECT_DIR:-${CLAUDE_PROJECT_DIR}}"
 LOG_DIR="${REPO_ROOT}/.cleargate/hook-log"
 mkdir -p "${LOG_DIR}"
 HOOK_LOG="${LOG_DIR}/token-ledger.log"

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

@@ -10,6 +10,17 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pending-task-sentinel.sh"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write",

package/templates/cleargate-planning/.claude/skills/flashcard/SKILL.md

@@ -1,27 +1,37 @@
 ---
 name: flashcard
-description: Append-only project lesson log at .cleargate/FLASHCARD.md. Use BEFORE starting non-trivial work to read past gotchas ("check" mode). Use WHEN you hit a surprise, wasted time, or a non-obvious gotcha to record it for future agents ("record: <one-liner>" mode). One-liners only; tag with #schema/#auth/#test-harness/etc. Also triggers on phrases like "turns out", "unexpected", "gotcha", "wasted time on", "starting work on", "before implementing".
+description: Append-only project lesson log at .cleargate/FLASHCARD.md. Use BEFORE starting non-trivial work to read past gotchas ("check" mode). Use WHEN you (a) hit a surprise, (b) found the winning path after a non-trivial task succeeded, or (c) were corrected by the user — record a one-liner for future agents ("record: <text>" mode). One-liners only; tag with #schema/#auth/#test-harness/etc. Also triggers on phrases: "turns out", "unexpected", "gotcha", "wasted time on", "starting work on", "before implementing", "user pushed back", "prefer X over Y", "winning path", "after several attempts", "the recipe that worked".
 ---
 
 # Flashcard — Project Lesson Log
 
 Append-only one-liner log of non-obvious gotchas that future agents in this project should know. Lives at `.cleargate/FLASHCARD.md` in the project root. Not a general wiki — only things that surprised us and would surprise someone else.
 
-## Two modes
+## Modes
 
 ### `check` — read before work
-Read `.cleargate/FLASHCARD.md`. Scan for tags relevant to your current task (grep by `#schema`, `#auth`, etc.). If a card applies, follow its guidance. If unsure whether a card applies, err on applying it — reading 20 one-liners is cheap.
+Read `.cleargate/FLASHCARD.md`. Apply the Rule 8 filter: skip cards marked `[S]` (stale) or `[R]` (resolved) unless your current task directly matches a tag in a superseded card. Scan active cards for tags relevant to your task (grep by `#schema`, `#auth`, etc.). If unsure whether a card applies, err on applying it — reading 20 one-liners is cheap.
 
-### `record: <one-liner>` — write after surprise
-Append a single line to `.cleargate/FLASHCARD.md`. Format:
+Use `check-all` instead when investigating history or debugging a recurring issue — it includes `[S]` and `[R]` cards.
+
+### `record: <text>` — three trigger classes, same format
+Append a single line to `.cleargate/FLASHCARD.md`. Same 120-char cap regardless of trigger:
+
+1. **Surprise** — something bit us. Lead with the surprise, not the context.
+2. **Recipe** — the winning path after a non-trivial task succeeded (roughly 5+ tool calls, or one clear dead-end recovery). Lead with the *action that worked*, not the failures traversed. Tag `#recipe` alongside the domain tag.
+3. **Correction** — the user pushed back on an approach. Capture the rule, not the exchange. Prefer the shape "prefer X over Y because Z". Tag `#correction` alongside the domain tag.
+
+Format (unchanged):
 
 ```
 YYYY-MM-DD · #tag1 #tag2 · <lesson ≤ 120 chars>
 ```
 
-Example:
+Examples:
 ```
 2026-04-18 · #redis #auth · Invite tokens in Redis-only vanish on eviction — use Postgres invites table as source of truth.
+2026-04-19 · #recipe #wiki · For wiki drift detection, git SHA beats content hash — drops the metadata-lifecycle dependency.
+2026-04-19 · #correction #planning · Prefer two L1/L2 stories over one L3 at epic-decomposition (user: splits are free pre-push).
 ```
 
 ### Tag vocabulary (append new tags freely, but prefer these)
@@ -46,14 +56,21 @@ Example:
 3. **Lead with the surprise, not the context.** Good: "Drizzle 0.45 silently drops `DEFAULT gen_random_uuid()` — use `sql` template." Bad: "When working on schema migrations yesterday we found that sometimes…"
 4. **Lessons, not events.** "Shipped STORY-004-07 today" is NOT a flashcard. "Postgres 18 needs `pgcrypto` extension for gen_random_uuid — not enabled by default in official docker image" IS.
 5. **Ordered newest-first after the header** — new entries go at the TOP of the log section, not bottom. Readers scan the top; old stuff drifts down.
-6. **Never delete.** Edit to add reconfirmations or deprecation notes; keep the original text. History is the point.
+6. **Never delete.** Edit to add reconfirmations, supersede pointers, or status markers (Rule 7); keep the original text. History is the point.
+7. **Status markers for cleanup.** A card may carry a status marker placed *immediately after the second `·`* and before the lesson body:
+   - no marker → active (default; the vast majority of cards).
+   - `[S]` → stale. The symbol the card references no longer exists in the repo.
+   - `[R] → superseded-by <short-ref>` → resolved or replaced by a later card / shipped fix. `<short-ref>` is a date+tag (e.g. `2026-04-19/#hooks-sentinel`) or a STORY/CR ID.
+   Markers are additive — the original lesson text is preserved. The reporter agent flags candidates at sprint end; a human approves the batch before markers are applied (see `.claude/agents/reporter.md` → "Flashcard audit").
+8. **Check-mode filter.** `check` reads active cards only (no marker). Include `[S]` / `[R]` cards only when: (a) their tags directly match the current task area, or (b) the invocation is `check-all` (explicit history read). This keeps `check` signal-dense without losing the historical record.
 
 ## Invocation contract
 
 When an agent invokes this skill:
 
-- **`Skill(flashcard, "check")`** — open `.cleargate/FLASHCARD.md`, summarize any cards with tags relevant to the current task context in one line per card. If none apply, respond "no relevant flashcards" and proceed.
-- **`Skill(flashcard, "record: <text>")`** — parse the text for date + tags + body. If date missing, insert today's UTC date. If tags missing, refuse with "add at least one tag." Grep for duplicates; if dup, reconfirm the existing line instead of appending. Append to the top of the log section in the file.
+- **`Skill(flashcard, "check")`** — open `.cleargate/FLASHCARD.md`, apply the Rule 8 filter, summarize matching active cards in one line per card. If none apply, respond "no relevant flashcards" and proceed.
+- **`Skill(flashcard, "check-all")`** — same as `check` but includes `[S]` / `[R]` cards. Use when investigating history, debugging a recurring issue, or tracing a supersede chain.
+- **`Skill(flashcard, "record: <text>")`** — parse the text for date + tags + body. If date missing, insert today's UTC date. If tags missing, refuse with "add at least one tag." For recipe-class entries include `#recipe`; for correction-class entries include `#correction`. Grep for duplicates; if dup, reconfirm the existing line instead of appending. Append to the top of the log section in the file.
 
 ## File shape
 
@@ -63,11 +80,13 @@ When an agent invokes this skill:
 # ClearGate Flashcards
 
 One-liner gotcha log. Newest first. Grep by tag (e.g. `grep '#schema'`).
-Format: `YYYY-MM-DD · #tags · lesson`
+Active cards have no marker; `[S]` = stale, `[R]` = resolved (see SKILL.md Rule 7).
+Format: `YYYY-MM-DD · #tags · [marker]? lesson`
 
 ---
 
-2026-04-18 · #redis #auth · <newest lesson>
-2026-04-17 · #schema · <older lesson>
+2026-04-19 · #redis #auth · <newest active lesson>
+2026-04-17 · #schema · [S] drizzle-kit v0.42 silently drops indexes — fixed in v0.45 upgrade.
+2026-04-15 · #hooks · [R] → superseded-by 2026-04-19/#hooks-sentinel · SubagentStop fires on orchestrator not subagents.
 ...
 ```

package/templates/cleargate-planning/.cleargate/FLASHCARD.md

@@ -1,6 +1,7 @@
 # ClearGate Flashcards
 
 One-liner gotcha log. Newest first. Grep by tag (e.g. `grep '#schema'`).
-Format: `YYYY-MM-DD · #tags · lesson`
+Active cards have no marker; `[S]` = stale, `[R]` = resolved (see `.claude/skills/flashcard/SKILL.md` Rules 7–8).
+Format: `YYYY-MM-DD · #tags · [marker]? lesson`
 
 ---

package/templates/cleargate-planning/.cleargate/config.example.yml

@@ -0,0 +1,37 @@
+# ClearGate per-repo configuration.
+# Copy to .cleargate/config.yml and edit. All keys optional.
+
+# wiki:
+#   index_token_ceiling: 8000   # chars budget for wiki/index.md (STORY-015-03)
+
+# gates:
+#   precommit: "<command run before every commit — typecheck + tests>"
+#   test: "<command to run the test suite>"
+#   typecheck: "<command to run the type checker>"
+#   lint: "<command to run the linter>"
+
+# Node example:
+# gates:
+#   precommit: "npm run typecheck && npm test"
+#   test: "npm test"
+#   typecheck: "npm run typecheck"
+#   lint: "npm run lint"
+
+# Go example:
+# gates:
+#   precommit: "go vet ./... && go test ./..."
+#   test: "go test ./..."
+#   typecheck: "go build ./..."
+
+# Python example:
+# gates:
+#   precommit: "mypy . && pytest"
+#   test: "pytest"
+#   typecheck: "mypy ."
+
+# Rust example:
+# gates:
+#   precommit: "cargo check && cargo test"
+#   test: "cargo test"
+#   typecheck: "cargo check"
+#   lint: "cargo clippy"

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

@@ -102,6 +102,12 @@ There are three hard stops. You halt at each one and do not proceed until the hu
 4. Once §6 is empty and zero "TBDs" remain in the document, move the status to 🟢.
 5. Only documents at 🟢 may proceed to the Delivery phase.
 
+**v2 enforcement rule:** When the sprint frontmatter has `execution_mode: "v2"`, a 🔴 High-ambiguity Epic BLOCKS bounce start — the orchestrator MUST NOT transition the story to `Bouncing` state until the Epic reaches 🟢. To override: the sprint plan frontmatter MUST contain `human_override: true` AND a `human_override_reason` field captured in §0 Readiness Gate of the sprint plan, with explicit human sign-off recorded. Without both fields, the orchestrator halts and presents the block message: *"Gate 2 blocked: Epic {ID} is 🔴 High ambiguity under execution_mode: v2. Set human_override: true + human_override_reason in sprint §0 to proceed."*
+
+Under `execution_mode: "v1"` this rule is **advisory only** — the orchestrator surfaces the ambiguity level but does not block bounce start.
+
+**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>`.
+
 ### Gate 3 — Push Gate
 
 - **Never call `cleargate_push_item` on a file where `approved: false`.**
@@ -506,3 +512,404 @@ Future `cleargate init` in the same dir detects this marker and offers restore.
 
 ### §13.6 Publishing notes
 `MANIFEST.json` is built at `npm run build` (prebuild step in `cleargate-cli/package.json`) and shipped in the npm tarball (`files[]`). Never computed at install time. `generate-changelog-diff.ts` diffs `MANIFEST.json` between the previous published version and the current one at release time; CHANGELOG.md auto-opens with a "Scaffold files changed" block per release. Content-identical entries (path-moved-only, metadata-changed-only) are collapsed to avoid noise.
+
+---
+
+## 14. Multi-Participant Sync
+
+### §14.1 Sync matrix & authority split
+
+**Rule:** Remote is authoritative for status, assignees, and comments; local is authoritative for work-item body.
+
+When both sides change the same field, the authoritative side wins without prompt (except body+body — see §14.2). This split prevents accidental overwrites of carefully authored local prose while still tracking PM-tool state transitions faithfully. Source: EPIC-010 §4 authority table; `cleargate-cli/src/commands/sync.ts` conflict-detector snapshot shape.
+
+### §14.2 Conflict resolution
+
+**Rule:** content+content → interactive 3-way merge prompt; status+status → remote-wins silently; delete+edit (either direction) → refuse; unrecognized conflict shape → `halt`.
+
+Nine conflict states are recognized (`content-content`, `status-status`, `remote-delete-local-edit`, `local-delete-remote-edit`, `remote-only`, `local-only`, `remote-status-only`, `local-content-only`, `unknown`). Resolution values are `three-way-merge`, `remote-wins`, `local-wins`, `refuse`, `halt`, `remote-only-apply`, `local-only-apply`. The `halt` resolution surfaces an actionable error rather than silently discarding data. Source: `cleargate-cli/src/lib/conflict-detector.ts`; `cleargate-cli/src/commands/sync.ts:307-367`.
+
+### §14.3 Sync ordering invariant
+
+**Rule:** `cleargate sync` MUST execute pull → classify → resolve → push in that order; reversal amplifies conflicts.
+
+Executing a push before all pulls are complete risks overwriting a remote state change that the local resolve step would have otherwise detected. The 6-step driver enforces this order at the code level; a unit test asserts step ordering as a dataflow invariant. Source: `cleargate-cli/src/commands/sync.ts` driver doc comment (steps 1–6); R2 mitigation.
+
+### §14.4 Identity resolution precedence
+
+**Rule:** `.cleargate/.participant.json` → `CLEARGATE_USER` env → `git config user.email` → `host+user` fallback.
+
+Identity is per-repo, not global, so two participants on the same machine with different `.participant.json` files get distinct attribution. The env var override allows CI or scripted sync. Source: `cleargate-cli/src/lib/identity.ts`; R5 mitigation.
+
+### §14.5 Stakeholder-authored proposal flow
+
+**Rule:** Remote items labeled `cleargate:proposal` (configurable via `CLEARGATE_PROPOSAL_LABEL` env) and absent locally land in `pending-sync/PROPOSAL-NNN-remote-<slug>.md` with `source: "remote-authored"` and `approved: false`.
+
+This prevents external stakeholders from bypassing the approval gate: the proposal arrives locally for human review before any push. The label name is configurable so teams can map to their own PM-tool taxonomy. Source: `cleargate-cli/src/lib/intake.ts`; `cleargate-cli/src/commands/sync.ts:167-183`.
+
+### §14.6 Comment policy
+
+**Rule:** Comments pull as read-only snapshots, active items only (current sprint + last 30 days), rendered under `## Remote comments` with literal-string delimiters. Never pushed upstream.
+
+Pulling comments for stale items wastes tokens and clutters archives; the 30-day window keeps recent feedback visible. The `## Remote comments` block uses byte-stable literal delimiters so repeated pulls are idempotent. A 429 rate-limit on any single item causes that item to be skipped silently. Source: `cleargate-cli/src/lib/wiki-comments-render.ts`; `cleargate-cli/src/lib/active-criteria.ts`; R4/R6 mitigations.
+
+### §14.7 Push preconditions
+
+**Rule:** `cleargate_push_item` requires `payload.approved === true` unless the caller passes `skipApprovedGate: true` (reserved for `sync_status` internal callers). `pushed_by` is stamped from `members.email` via JWT `sub` → member lookup, NOT the raw JWT `sub` value.
+
+The `skipApprovedGate` bypass is an internal escape hatch for status-only updates triggered by `cleargate_sync_status`; it is not exposed as a public CLI flag. The email lookup ensures human-readable attribution independent of UUID-based JWT subjects. Source: `mcp/src/tools/push-item.ts`; flashcard `#mcp #jwt #attribution`.
+
+### §14.8 Revert policy
+
+**Rule:** `cleargate push --revert <id>` soft-reverts by calling `cleargate_sync_status` with `new_status: "archived-without-shipping"`; it never deletes the remote item. `--force` is required when local `status: done`.
+
+Soft revert preserves audit history on the PM-tool side. Refusing to revert done items without `--force` prevents accidental archival of shipped work. Source: `cleargate-cli/src/commands/push.ts` revert branch; `cleargate-cli/src/cli.ts:268-273`.
+
+### §14.9 Sync cadence
+
+**Rule:** All sync actions are manual (`cleargate sync` / `cleargate pull <id>` / `cleargate push <file>`). The SessionStart hook SUGGESTS via `cleargate sync --check` — it never auto-pulls or auto-pushes. MCP probes are throttled to at most one per 24 hours per repo.
+
+Auto-push without human review would bypass the approval gate; auto-pull would overwrite in-progress local edits without conflict detection. The 24-hour throttle prevents session-start latency accumulation. Throttle state is stored in `.cleargate/.sync-marker.json` with schema `{ "last_check": "<ISO-8601>" }` (v1; unknown keys are ignored on read for forward compatibility). Source: `.claude/hooks/session-start.sh`; `.cleargate/.sync-marker.json`; R7 mitigation.
+
+---
+
+## 15. Worktree Lifecycle (v2)
+
+**v1/v2 gating:** Under `execution_mode: v1` the rules in this section are **informational** — they document the intended workflow but are not enforced by any script. Under `execution_mode: v2` they are **mandatory**: every story transition that would run a Developer agent MUST follow these procedures before any file edits begin.
+
+### §15.1 Branch hierarchy
+
+The branch hierarchy for a sprint is:
+
+```
+main
+└── sprint/S-XX          ← cut at sprint start; never commit directly
+    └── story/STORY-NNN-NN   ← cut when story transitions Ready → Bouncing
+```
+
+- **Sprint branch** is cut from `main` once at the start of each sprint:
+  ```bash
+  git checkout -b sprint/S-XX main
+  ```
+- **Story branch** is cut from the active sprint branch when the story enters `Bouncing` state:
+  ```bash
+  git checkout sprint/S-XX
+  git checkout -b story/STORY-NNN-NN sprint/S-XX
+  ```
+- Story branches are **never** cut from `main` directly; they always track the sprint branch as parent.
+
+### §15.2 Worktree commands
+
+Per-story working trees live under `.worktrees/` at repo root. Each story gets its own isolated filesystem view.
+
+**Create worktree (story starts bouncing):**
+```bash
+git worktree add .worktrees/STORY-NNN-NN -b story/STORY-NNN-NN sprint/S-XX
+```
+
+**Verify worktree:**
+```bash
+git worktree list
+# .../repo            <sha>  [sprint/S-XX]
+# .../repo/.worktrees/STORY-NNN-NN  <sha>  [story/STORY-NNN-NN]
+```
+
+**Merge story back into sprint branch (story passes QA + Architect):**
+```bash
+git checkout sprint/S-XX
+git merge story/STORY-NNN-NN --no-ff -m "merge(story/STORY-NNN-NN): STORY-NNN-NN <title>"
+```
+
+**Remove worktree and story branch (after successful merge):**
+```bash
+git worktree remove .worktrees/STORY-NNN-NN
+git branch -d story/STORY-NNN-NN
+```
+
+**Prune stale worktree refs:**
+```bash
+git worktree prune
+```
+
+All commands must be run from the **repo root** (not from inside `.worktrees/`), except Developer Agent file edits which happen inside the assigned worktree path.
+
+### §15.3 MCP nested-repo rule
+
+**The `mcp/` directory is a nested independent git repository.** Running `git worktree add` inside `mcp/` would create a worktree scoped to the nested repo, not to the outer ClearGate repo. This is a git footgun: the outer repo cannot track, merge, or remove the inner worktree via its own git commands.
+
+**Rule:** Never run `git worktree add` inside `mcp/`. If a story requires edits to `mcp/`, the Developer Agent must edit `mcp/` from inside the outer worktree (`.worktrees/STORY-NNN-NN/mcp/...`) — the nested repo's files are visible there as a subdirectory, not as a separate git context. MCP-native worktree support is deferred to Q3.
+
+### §15.4 Local state.json is in-flight authority
+
+During a story's execution, `state.json` at `.cleargate/sprint-runs/<sprint-id>/state.json` is the single source of truth for story state. The MCP server is a **post-facto audit** channel: it receives state updates after each transition but is never consulted during execution. If MCP is unavailable, execution continues uninterrupted; state.json records the ground truth that MCP will eventually replicate. (Source: EPIC-013 Q7 resolution.)
+
+### §15.5 Enforcement gates
+
+| `execution_mode` | These rules are |
+|---|---|
+| `v1` | Informational — document intended workflow; not script-enforced |
+| `v2` | Mandatory — `validate_bounce_readiness.mjs` checks worktree isolation before any Developer Agent edit |
+
+Under v2, attempting to run a Developer Agent on a story without a matching `.worktrees/STORY-NNN-NN/` path present causes `validate_bounce_readiness.mjs` to exit non-zero and the orchestrator to halt the story transition.
+
+---
+
+## 16. User Walkthrough on Sprint Branch (v2)
+
+**v1/v2 gating:** Under `execution_mode: v1` this section is **informational**. Under `execution_mode: v2` it is **mandatory**: the sprint branch MUST NOT merge to `main` until the walkthrough is complete and all `UR:bug` items are resolved.
+
+### §16.1 Walkthrough trigger
+
+After all stories in the sprint are merged into `sprint/S-XX` (every story state ∈ `TERMINAL_STATES`) and before `sprint/S-XX` merges to `main`, the orchestrator invites the user to test the running application on the sprint branch.
+
+### §16.2 Feedback classification
+
+User feedback during the walkthrough is classified into exactly two event types:
+
+| Event type | Definition | Bug-Fix Tax effect |
+|---|---|---|
+| `UR:review-feedback` | Enhancement, polish, copy change, or UX preference — does NOT fix broken behavior | Does NOT increment Bug-Fix Tax |
+| `UR:bug` | Defect, crash, wrong output, or behavior broken relative to spec | DOES increment Bug-Fix Tax |
+
+**Classification rule:** when in doubt, ask the user one targeted question — "Is this broken relative to spec, or a preference?" Do not default to `UR:bug`.
+
+### §16.3 Logging
+
+Each piece of walkthrough feedback MUST be logged in the sprint markdown file under `## 4. Execution Log` with the event prefix:
+
+```
+UR:review-feedback 2026-04-21 — copy should say "Sign in" not "Log in" (resolved: STORY-013-09-dev.md commit abc123)
+UR:bug 2026-04-21 — create-project button 500s on submit (resolved: STORY-013-10-dev.md commit def456)
+```
+
+### §16.4 Resolution gate
+
+The sprint branch MUST NOT merge to `main` while any `UR:bug` item is unresolved. `UR:review-feedback` items MAY be deferred to the next sprint with orchestrator + user acknowledgment logged.
+
+---
+
+## 17. Mid-Sprint Change Request Triage (v2)
+
+**v1/v2 gating:** Under `execution_mode: v1` this section is **informational**. Under `execution_mode: v2` it is **mandatory**: every user-injected change during a bounce MUST be classified before routing.
+
+### §17.1 Classification table
+
+When the user injects new input during a QA bounce or active story execution, the orchestrator classifies the input into one of four categories:
+
+| Event type | Definition | Bounce-counter effect | Routing |
+|---|---|---|---|
+| `CR:bug` | Defect introduced by the current story's implementation | Counts toward Bug-Fix Tax; increments `qa_bounces` | Re-open story; Developer fixes; QA re-verifies |
+| `CR:spec-clarification` | Clarification of existing spec — no new scope, removes ambiguity | Does NOT increment any bounce counter | Update story acceptance criteria in place; re-run impacted test |
+| `CR:scope-change` | Net-new requirement or expansion of story scope | Deferred: create a new Story in `pending-sync/`; current story continues unchanged | New Story ID assigned; current bounce counter unaffected |
+| `CR:approach-change` | Switch implementation approach without changing functional spec | Does NOT increment bounce counter; resets Developer context | Re-spawn Developer with updated approach note; same story ID |
+
+### §17.2 Logging
+
+Each mid-sprint CR MUST be logged in the sprint markdown file under `## 4. Execution Log` with the event prefix:
+
+```
+CR:spec-clarification 2026-04-21 — endpoint must return project slug (clarified in STORY-013-05 §1.2; no new scope)
+CR:scope-change 2026-04-21 — user requests audit log table (new STORY-013-11 created in pending-sync/)
+```
+
+### §17.3 Scope-change quarantine
+
+A `CR:scope-change` MUST NOT be folded into the current story's commit. Create a new Story file and handle in a future sprint or as a mid-sprint addition (requires orchestrator + user explicit sign-off to add mid-sprint).
+
+---
+
+## 18. Immediate Flashcard Gate (v2)
+
+**v1/v2 gating:** Under `execution_mode: v1` this section is **informational** — the gate is advisory and the orchestrator may proceed without processing flagged cards (though it is strongly encouraged). Under `execution_mode: v2` it is **mandatory**: the orchestrator MUST NOT create the next story's worktree until all `flashcards_flagged` entries from the prior story's dev + QA reports are processed.
+
+**V-Bounce reference:** `skills/agent-team/SKILL.md` §"Step 5.5: Immediate Flashcard Recording (Hard Gate)" at pinned SHA `2b8477ab65e39e594ee8b6d8cf13a210498eaded`.
+
+### §18.1 Trigger
+
+After story N's commit merges into `sprint/S-XX` and QA approves, the orchestrator collects `flashcards_flagged` from both:
+- `STORY-NNN-NN-dev.md` (Developer Agent output report)
+- `STORY-NNN-NN-qa.md` (QA Agent output report)
+
+The two lists are merged (union, deduplication by exact string match). If the combined list is empty, the gate passes immediately.
+
+### §18.2 Processing rule
+
+For each entry in the merged `flashcards_flagged` list, the orchestrator MUST take exactly one of two actions before creating story N+1's worktree:
+
+| Action | Effect | Record location |
+|---|---|---|
+| **Approve** | Append the one-liner verbatim to `.cleargate/FLASHCARD.md` (newest-first, per SKILL.md format) | The card itself is the record |
+| **Reject** | Discard the entry — do NOT append to `FLASHCARD.md` | Sprint §4 Execution Log: `FLASHCARD-REJECT YYYY-MM-DD — "<card text>" — reason: <one sentence>` |
+
+### §18.3 Worktree creation gate
+
+The orchestrator MUST NOT run `git worktree add .worktrees/STORY-NNN-NN ...` for story N+1 until the §18.2 processing loop is complete (every entry either approved or rejected). This is a blocking serial step, not a background task.
+
+### §18.4 Cards format
+
+Each entry in `flashcards_flagged` MUST conform to the format required by `.claude/skills/flashcard/SKILL.md`:
+
+```
+YYYY-MM-DD · #tag1 #tag2 · lesson ≤120 chars
+```
+
+The orchestrator may reformat an entry that violates the format before appending, but must log the reformat in sprint §4 Execution Log.
+
+### §18.5 v1 dogfood note
+
+SPRINT-09 runs under `execution_mode: v1`. From STORY-013-06 merge onwards, the orchestrator applies the §18.2 processing loop manually as a dogfood check even though the rule is informational. This is recorded in the SPRINT-09 sprint plan (line 121).
+
+### §18.6 PreToolUse hook enforcement (v2)
+
+Under `execution_mode: v2`, the `pending-task-sentinel.sh` PreToolUse hook automatically enforces the flashcard gate before every Task (subagent) dispatch. This is implemented by STORY-014-03.
+
+**Hash-marker convention:**
+
+Each `flashcards_flagged` card is identified by the first 12 hexadecimal characters of its SHA-1 hash (computed with `shasum -a 1`):
+
+```bash
+HASH="$(printf '%s' "<card text>" | shasum -a 1 | cut -c1-12)"
+```
+
+Hash stability: the same card string always produces the same hash. The hash is computed over the exact card string as it appears in the report's `flashcards_flagged` list (after stripping surrounding quotes).
+
+**Processed marker:**
+
+To mark a card as processed (approved or rejected by the orchestrator), touch the marker file:
+
+```bash
+touch .cleargate/sprint-runs/<sprint-id>/.processed-<hash>
+```
+
+The marker files are gitignored via the existing `.cleargate/sprint-runs/` gitignore rule and serve only as local bookkeeping.
+
+**Enforcement logic:**
+
+1. The hook globs `SPRINT_DIR/STORY-*-dev.md` and `SPRINT_DIR/STORY-*-qa.md` (flat layout — no `reports/` subdirectory).
+2. For each report file, it parses the `flashcards_flagged:` YAML list (inline `[]` and block `- "text"` forms both supported).
+3. For each card, it computes the 12-char SHA-1 hash and checks for the `.processed-<hash>` marker in `SPRINT_DIR`.
+4. If any card is unprocessed:
+   - **v2**: exits non-zero (blocks Task spawn) with stderr listing each unprocessed card and the `touch` command hint.
+   - **v1**: prints an advisory warning to stderr and exits 0 (does not block).
+5. If `flashcards_flagged: []` or no report files exist, the gate passes immediately.
+
+**Bypass:**
+
+Set `SKIP_FLASHCARD_GATE=1` in the environment to bypass the gate entirely (both v1 and v2). This bypass is intended for CI and bootstrap scenarios where the hook runs without sprint context. Bypasses should be disabled once M1 is closed; the orchestrator tracks this in the sprint §4 Execution Log.
+
+---
+
+## 19. Execution Mode Routing (v2)
+
+The `execution_mode` field in a Sprint Plan's frontmatter is the single switch that controls whether §§15–18 of this protocol are **enforcing** or **advisory** for that sprint.
+
+### §19.1 Flag semantics
+
+| `execution_mode` value | Effect |
+|---|---|
+| `"v1"` | All §§15–18 rules are **advisory** — document intended workflow; no CLI or script enforcement. New CLI commands (`sprint init|close`, `story start|complete`, `gate qa|arch`, `state update|validate`) print an inert-mode message and exit 0. |
+| `"v2"` | All §§15–18 rules are **mandatory** — CLI wrappers route to `run_script.sh` scripts; worktree isolation, pre-gate scanning, bounce counters, flashcard gate, and sprint-close pipeline are all enforced. |
+
+### §19.2 Sprint-scoped flag
+
+The `execution_mode` flag is **sprint-scoped**, not global. A project may run SPRINT-10 on `v2` while SPRINT-11 planning files default to `v1` until the Architect completes a Sprint Design Review (§15.1). Setting the flag on one sprint has no effect on any other sprint file.
+
+### §19.3 Orchestrator routing rule
+
+Before spawning any Developer, QA, or Reporter agent, the orchestrator MUST:
+
+1. Locate the active sprint file at `.cleargate/delivery/pending-sync/SPRINT-{ID}_*.md` (or the archived equivalent).
+2. Read the `execution_mode` frontmatter field. If absent, treat as `"v1"`.
+3. If `"v1"`: proceed with advisory-only loop. §§15–18 rules are informational.
+4. If `"v2"`: enforce §§15–18 before each agent spawn as mandatory gates.
+
+### §19.4 CLI inert-mode message
+
+When a v2-only CLI command is invoked and the active sprint's `execution_mode` is `"v1"`, the CLI MUST print exactly:
+
+```
+v1 mode active — command inert. Set execution_mode: v2 in sprint frontmatter to enable.
+```
+
+and exit 0. No subprocess is spawned. This preserves backward compatibility for users who have not yet migrated to v2.
+
+### §19.5 Default value
+
+The default value is `"v1"`. All sprint plans generated from the Sprint Plan Template default to `execution_mode: "v1"` until explicitly flipped. The flag should only be set to `"v2"` after all M2 EPIC-013 stories have shipped and the Architect has completed a Sprint Design Review (§15.1).
+
+---
+
+## 20. File-Surface Contract (v2)
+
+Under `execution_mode: v2`, each story's §3.1 "Context & Files" table is the **authoritative file surface** for that story's commit. The pre-commit hook enforces this contract automatically.
+
+### §20.1 Rule
+
+A Developer agent MUST NOT stage and commit any file not declared in the active story's §3.1 table, unless that file matches a whitelist entry in `.cleargate/scripts/surface-whitelist.txt`.
+
+Off-surface edits require one of:
+1. A CR:scope-change item approved before the commit, OR
+2. An updated §3.1 table committed in the same story (self-amending surface — rare, must be explicitly justified in the commit message).
+
+### §20.2 Hook mechanics
+
+The gate runs as `.cleargate/scripts/file_surface_diff.sh` invoked via `.claude/hooks/pre-commit-surface-gate.sh` and dispatched from `.claude/hooks/pre-commit.sh`. The dispatcher is symlinked to `.git/hooks/pre-commit`.
+
+- Under v2: off-surface files cause a non-zero exit — the commit is blocked.
+- Under v1: the hook prints a warning but exits 0 (advisory only).
+- `SKIP_SURFACE_GATE=1` env variable bypasses the gate entirely (use sparingly; log bypass in sprint §4 Execution Log).
+
+### §20.3 §3.1 table contract
+
+The §3.1 table in `story.md` template uses a two-column `| Item | Value |` pipe table. The parser:
+- Scans between the `### 3.1` heading and the next `### ` heading.
+- Only processes rows where the Value cell contains `.` or `/` (path-shaped values).
+- Strips backticks from values.
+- Splits on `, ` to handle multiple paths in one cell.
+- Ignores header and separator rows.
+
+Non-path rows (e.g., "Mirrors", "New Files Needed: Yes/No") are silently skipped.
+
+### §20.4 Whitelist
+
+`.cleargate/scripts/surface-whitelist.txt` declares auto-generated files that are always admitted regardless of story surface. Seed entries include: `cleargate-planning/MANIFEST.json`, `.cleargate/hook-log/*`, `.cleargate/sprint-runs/**/token-ledger.jsonl`, `.cleargate/sprint-runs/**/.pending-task-*.json`, `.cleargate/sprint-runs/**/state.json`.
+
+### §20.5 Install (dogfood)
+
+On `cleargate init`, the scaffold automatically installs the `.git/hooks/pre-commit` symlink. For existing dogfood repositories, install once by hand:
+
+```bash
+ln -sf ../../.claude/hooks/pre-commit.sh .git/hooks/pre-commit
+```
+
+Log this step in the sprint §4 Execution Log.
+
+---
+
+## 21. Status Vocabulary
+
+Raw work-item frontmatter `status:` values must be drawn from this canonical set:
+
+| Status | Meaning |
+|---|---|
+| `Draft` | Newly authored; not yet ambiguity-gated |
+| `Ready` | Ambiguity gate passed; eligible for sprint planning |
+| `Approved` | Epic approved for execution |
+| `Planned` | Sprint planned; not yet started |
+| `Active` | Work in progress |
+| `Completed` | Shipped (sprints, epics) |
+| `Done` | Shipped (stories) — treated as alias of `Completed` for terminal-status checks |
+| `Abandoned` | Work deliberately stopped without shipping. The artifact stays in `archive/` for historical record. Not eligible for the Active index. |
+| `Closed` | Closed without shipping (administrative close) |
+| `Resolved` | Bug or CR confirmed resolved |
+
+### §21.1 Index Token Ceiling
+
+`cleargate wiki lint` enforces a ceiling on `.cleargate/wiki/index.md` size, measured as `bytes ÷ 4` approximate tokens. Default ceiling: `8000`. Override via `.cleargate/config.yml`:
+
+```yaml
+wiki:
+  index_token_ceiling: 8000
+```
+
+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.