cleargate 0.8.1 → 0.10.0

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

@@ -4,6 +4,35 @@ You are operating in a ClearGate-enabled repository. Read this file in full befo
 
 ---
 
+## Code-Truth Principle
+
+ClearGate's epistemic stack: source code is canonical; wiki, memory, and `context_source` are derived caches. Every triage and draft answers four layers, in order:
+
+- **L0 — Code is source of truth.** On any conflict between cache and code, the code wins; the cache rebuilds. Verify capability claims by grep before stating them.
+- **L1 — Reuse before rebuild.** Before drafting a work item that names an integration, feature, or capability, grep the source tree for existing implementations. Cite findings in `## Existing Surfaces`. If an existing surface covers ≥80% of the requirement, the work item is an extension (CR), not a new build (Story).
+- **L2 — Right-size at triage.** Could this be a config change? a parameter addition? a one-line edit? If yes, it's not a Story — it's a PR or a tiny CR. Smallest viable form first.
+- **L3 — Justify complexity.** Every Epic and Story includes `## Why not simpler?` answering: what's the smallest existing surface; why isn't extension/parameterization/config sufficient.
+
+This is the same epistemic discipline the Knowledge Wiki applies to documents (raw → wiki → schema; source → cache → derived view), extended from planning artifacts to source code.
+
+---
+
+## 0. The Five Phases
+
+ClearGate operates in five named phases. Every work item moves through them in order; every gate fires at a phase boundary.
+
+| Phase | Activity | Gate at exit |
+|---|---|---|
+| **Plan** | Triage user request → draft work item using template → present Brief → resolve open questions → ambiguity 🟢 | **Gate 1 — Brief** (per work item; implicitly grants MCP push) |
+| **Prepare** | Sprint planning. AI auto-picks sprint number, drafts Sprint Plan as Brief, Architect writes §2 Sprint Design Review. | **Gate 2 — Sprint Ready** (plan quality) → **Gate 3 — Sprint Execution** (env health) |
+| **Execute** | Four-agent loop: Architect (per-milestone plan) → Developer → QA → (Reporter at end). One story = one worktree = one commit. | (transitions to Observe when all stories merge to sprint branch) |
+| **Observe** | User walkthrough on sprint branch. Feedback classified `UR:bug` or `UR:review-feedback`. Bugs fixed before merge to main. | (transitions to Close when all `UR:bug` resolved) |
+| **Close** | Lifecycle reconciler → Reporter writes `SPRINT-<#>_REPORT.md` → status flips Completed. | **Gate 4 — Close-Ack** |
+
+Read this section first. Drill into §1–§14 + §21 only as needed for the current task.
+
+---
+
 ## 1. Your Role
 
 You are the **Execution Agent**. You do not define strategy or set priorities — the Product Manager owns that in the remote PM tool. Your responsibilities are:
@@ -47,76 +76,55 @@ If the type is not clear, ask **one targeted question** before proceeding. Do no
 
 Example: *"Is this adding functionality that doesn't exist yet (Story) or changing how an existing feature works (CR)?"*
 
-### Always Start with a Proposal
+### Always Start with a Brief
 
-For Epic, Story, and CR types — before drafting the work item itself, you **must** first draft a Proposal using `templates/proposal.md`. The Proposal is Gate 1 (see §4). You may not skip it.
+Every drafted work item — Epic, Story, CR, Bug, Hotfix — gets a Brief presented to the human in chat after the document is written. The Brief is mechanically extracted from the document's own sections per the template's `<instructions>` block (Summary / Open Questions / Edge Cases / Risks / Ambiguity). Conversation resolves open questions; ambiguity flips 🔴 → 🟢 → **Gate 1 passes**.
 
-Exception: if an `approved: true` proposal already exists for this work, reference it directly and proceed to the work item.
+**Initiative-class scope** uses the `initiative.md` template — multi-Epic work where a persistent file-based Brief is genuinely useful before decomposition begins. For everything else (single Epic / Story / CR / Bug / Hotfix), the agent triages the request directly into the appropriate template and presents the Brief. The legacy Proposal step has been retired (CR-025 SPRINT-19); see §14.5 for the stakeholder-authored intake flow that retains the `cleargate:proposal` external label as backwards-compat.
 
 ---
 
 ## 3. Document Hierarchy
 
-All work follows a strict four-level hierarchy. You cannot skip levels or create orphaned documents.
-
-```
-LEVEL 0 — PROPOSAL
-  (approved: false → human sets approved: true)
-         ↓
-LEVEL 1 — EPIC
-  (🔴 High Ambiguity → human answers §6 → 🟢 Low Ambiguity)
-         ↓
-LEVEL 2 — STORY
-  (🔴 High Ambiguity → human answers §6 → 🟢 Low Ambiguity)
-         ↓
-LEVEL 3 — DELIVERY
-  (cleargate_push_item → remote ID injected → moved to archive/)
-```
-
 ### Hierarchy Rules
 
-- **Proposal before everything.** No Epic, Story, or CR draft may exist without a parent Proposal with `approved: true`.
-- **Epic before Story.** Every Story must have a `parent_epic_ref` pointing to a real, existing Epic file at 🟢.
-- **No orphans.** A Story with no parent Epic is invalid. A Bug or CR must reference the affected Epic or Story.
-- **Cascade ambiguity.** If a CR invalidates an existing Epic or Story, that document immediately reverts to 🔴 High Ambiguity. Do not proceed with execution on reverted items.
+- **No orphans.** Every Story has a `parent_epic_ref:` pointing to a real Epic file. Every Bug or CR references the affected Epic, Story, or knowledge document.
+- **Epic before Story.** A Story file cannot exist without a `parent_epic_ref:` to a 🟢 Epic.
+- **Initiative is optional.** A multi-Epic Initiative MAY exist as a file-persisted Brief in `pending-sync/INITIATIVE-NNN_*.md`. It is not required for any single-Epic-or-smaller work.
+- **Cascade ambiguity.** A CR that invalidates an existing Epic or Story flips that document back to 🔴; downstream items inherit.
 
 ---
 
-## 4. Phase Gates
+## 4. The Four Gates
 
-There are three hard stops. You halt at each one and do not proceed until the human acts.
+### Gate 1 — Brief (per work item, Plan phase)
 
-### Gate 1 — Proposal Approval
+After drafting any work item, the agent presents a Brief in chat:
+- **Summary** (1–2 sentences from §1 / User Story)
+- **Open Questions** (with recommended answers)
+- **Edge Cases** (with recommended handling)
+- **Risks** (with recommended mitigations)
+- **Ambiguity level** (current 🔴 / 🟡 / 🟢)
 
-1. Draft the Proposal using `templates/proposal.md`.
-2. Save to `.cleargate/delivery/pending-sync/PROPOSAL-{Name}.md` with `approved: false`.
-3. Present the document to the user.
-4. **STOP. Do not draft Epics or Stories. Do not call any MCP tool. Wait.**
-5. Proceed only after the human has set `approved: true` in the frontmatter.
+Conversation resolves the open questions. When all are resolved → ambiguity flips 🟢 → Gate 1 passes. **The same approval implicitly grants the MCP push** — agent calls `cleargate_push_item` immediately. No separate "now confirm the push" step.
 
-### Gate 2 — Ambiguity Gate (per Epic and Story)
+**Initiative intake (post-CR-025).** Stakeholder-shaped input (multi-Epic scope, persistent Brief useful) lands in `pending-sync/INITIATIVE-NNN_*.md` via two paths: (1) MCP pull — `cleargate_pull_initiative` with the remote ID writes the file automatically; (2) Manual paste — agent triages the input and writes the file using `templates/initiative.md`. Either path then runs the standard Brief loop above. After Gate 1 passes, the Initiative file moves to `archive/` stamped with `triaged_at: <ISO-8601>` and `spawned_items: ["EPIC-NNN", "EPIC-MMM", ...]` listing the work items it decomposed into.
 
-1. Every drafted Epic or Story starts at 🔴 High Ambiguity.
-2. Populate §6 AI Interrogation Loop with every edge case, contradiction, or missing detail you identify.
-3. **STOP. Present the document. Wait for the human to answer every question in §6.**
-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.
+### Gate 2 — Sprint Ready (per sprint, Prepare phase internal)
 
-**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."*
+Sprint Plan moves Draft → Ready when (a) every referenced item is decomposed + 🟢, (b) the sprint-level Brief is resolved, (c) the Architect Sprint Design Review (§2 of the Sprint Plan) is written under `execution_mode: v2`. Without all three, the sprint cannot transition.
 
-Under `execution_mode: "v1"` this rule is **advisory only** — the orchestrator surfaces the ambiguity level but does not block bounce start.
+### Gate 3 — Sprint Execution (per sprint, Prepare → Execute boundary)
 
-**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>`.
+Before sprint execution begins, `cleargate sprint preflight <sprint-id>` runs **five** checks: previous sprint Completed, no leftover worktrees, sprint branch ref free, `main` clean, and per-item readiness gates pass for every work item in §1 Consolidated Deliverables. Under `execution_mode: v2` a failing per-item gate hard-blocks; under `v1` it warns. See `cleargate-enforcement.md` §<N> for full enforcement spec; specified by CR-021 (env health) + CR-027 (composite per-item gate + Discovery/Risk criteria).
 
-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 4 — Close-Ack (per sprint, Close phase)
 
-### Gate 3 — Push Gate
+`close_sprint.mjs` halts at Step 5 with the prompt "Review the report, then confirm close by re-running with --assume-ack." Orchestrator surfaces the prompt verbatim and halts. Human reads the sprint report, then either re-runs the script with `--assume-ack` themselves or explicitly tells the orchestrator "approved, close it" — at which point the orchestrator may pass the flag.
 
-- **Never call `cleargate_push_item` on a file where `approved: false`.**
-- Never push a document that is 🔴 or 🟡.
-- Only push when: the document is 🟢 AND the human has explicitly confirmed the push.
+`--assume-ack` is reserved for **automated test environments only**. Conversational orchestrators MUST NOT pass it autonomously. Violation is a Gate-4 breach equivalent to an unauthorized push.
 
-> Gate 2 (Ambiguity) is machine-checked via `cleargate gate check`; see §12.
+> Gate check is machine-assisted via `cleargate gate check`; see §12.
 > (See §13 for scaffold lifecycle commands)
 
 ---
@@ -129,14 +137,13 @@ Follow these steps in exact order:
 1. DRAFT   — Fill the appropriate template.
              Save to: .cleargate/delivery/pending-sync/{TYPE}-{ID}-{Name}.md
 
-2. HALT    — Present the draft to the human. Wait for approval (Gate 1 or Gate 2).
+2. BRIEF   — Present the Brief in chat. Halt for human review. Resolve open questions.
 
-3. SYNC    — Human approves. Call cleargate_push_item with the exact file path.
+3. SYNC    — When ambiguity flips 🟢, call cleargate_push_item automatically
+             (Gate 1 covers approval).
 
-4. COMMIT  — Inject the returned remote ID into the file's YAML frontmatter.
-             Example: remote_id: "LIN-102"
-
-5. ARCHIVE — Move the file to: .cleargate/delivery/archive/{ID}-{Name}.md
+4. ARCHIVE — Inject returned remote ID into frontmatter; move file to
+             .cleargate/delivery/archive/.
 ```
 
 **On MCP failure:** Leave the file in `pending-sync/`. Report the exact error to the human. Do not retry in a loop. Do not attempt a workaround.
@@ -147,7 +154,7 @@ Follow these steps in exact order:
 
 ## 6. MCP Tools Reference
 
-Only use the `cleargate_*` MCP tools to communicate with PM tools. Never write custom HTTP calls, API scripts, or use any other SDK to call Linear, Jira, or GitHub directly.
+**MCP is the only sync surface.** From the AI's perspective, MCP *is* the PM tool. The `cleargate_*` MCP tools (`cleargate_pull_initiative`, `cleargate_push_item`, `cleargate_sync_status`, plus the work-item / sync-log surface added in SPRINT-16) are the only interfaces. Whatever upstream systems MCP fans out to (Linear / Jira / GitHub Issues / others) is MCP's concern, not yours. Never write custom HTTP calls, API scripts, or other SDK invocations.
 
 | Tool | When to Call |
 |---|---|
@@ -164,7 +171,7 @@ These rules prevent hallucinated or out-of-scope changes.
 - **Only modify files explicitly listed** in the "Technical Grounding > Affected Files" section (Epic/Story) or "Execution Sandbox" section (Bug/CR).
 - **Do not refactor, optimize, or clean up** code that is not in scope. If you notice an issue outside scope, note it and ask the human whether to create a separate Story or CR.
 - **Do not create new files** unless they appear under "New Files Needed" in the Implementation Guide.
-- **Do not assume file paths.** All affected file paths must originate from an approved Proposal. If a path is missing or unverified, add it to §6 AI Interrogation Loop — do not guess.
+- **Do not assume file paths.** All affected file paths must originate from an approved Initiative. If a path is missing or unverified, add it to §6 AI Interrogation Loop — do not guess.
 
 ---
 
@@ -175,9 +182,9 @@ When the user wants to ingest context from the PM tool before any execution:
 1. Call `cleargate_pull_initiative` with the remote ID provided by the user.
 2. The tool writes the result to `.cleargate/plans/` using the appropriate local format.
 3. Read the pulled file to understand scope, constraints, and sprint context.
-4. Use this as the input context when beginning a Proposal draft.
+4. Use this as the input context when beginning an Initiative draft.
 
-You do not push during the Planning Phase. Planning Phase ends when the user confirms they want to begin drafting a Proposal.
+You do not push during the Planning Phase. Planning Phase ends when the user confirms they want to begin drafting an Initiative.
 
 ---
 
@@ -194,8 +201,8 @@ Is this a PUSH request? ──YES──→ check approved: true → cleargate_pu
       ↓
 Classify: Epic / Story / CR / Bug
       ↓
-Does an approved: true Proposal exist for this work?
-      ├── NO  → Draft Proposal → HALT at Gate 1
+Does an approved: true Initiative exist for this work?
+      ├── NO  → Draft Initiative → HALT at Gate 1
       └── YES → Draft work item (Epic/Story/CR/Bug) → HALT at Gate 2
                       ↓
              Human resolves §6 + sets 🟢
@@ -244,7 +251,7 @@ Invoked automatically at triage (read-only). Searches the wiki index and existin
 
 **lint**
 
-Enforcement run. Checks for drift between wiki pages and their raw source files. Exits non-zero on any violation; a non-zero exit halts Gate 1 (Proposal approval) and Gate 3 (Push). Run with `--suggest` to receive candidate cross-ref patches without blocking (exits 0).
+Enforcement run. Checks for drift between wiki pages and their raw source files. Exits non-zero on any violation; a non-zero exit halts Gate 1 (Initiative approval) and Gate 3 (Push). Run with `--suggest` to receive candidate cross-ref patches without blocking (exits 0).
 
 ---
 
@@ -275,6 +282,7 @@ raw_path: ".cleargate/delivery/archive/STORY-042-01_name.md"
 last_ingest: "2026-04-19T10:00:00Z"
 last_ingest_commit: "a1b2c3d4e5f6..."
 repo: "planning"
+last_contradict_sha: ""  # optional — populated by ingest Phase 4 (§10.10)
 ---
 
 # STORY-042-01: Short title
@@ -292,6 +300,7 @@ Field notes:
 
 - `last_ingest_commit` — the SHA returned by `git log -1 --format=%H -- <raw_path>` at ingest time. Used for idempotency (see §10.7).
 - `repo` — derived from `raw_path` prefix: `cleargate-cli/` → `cli`; `mcp/` → `mcp`; `.cleargate/` or `cleargate-planning/` → `planning`. Never manually set.
+- `last_contradict_sha` (optional) — populated by ingest Phase 4 (§10.10). Pages without this field MUST continue to pass lint. Value is the SHA returned by `git log -1 --format=%H -- <raw_path>` at the moment Phase 4 last ran.
 
 ---
 
@@ -336,7 +345,7 @@ Drift detection is commit-SHA comparison — not content hashing — eliminating
 
 `cleargate wiki lint` exits non-zero and blocks execution at:
 
-- **Gate 1 (Proposal approval):** lint must pass before the agent may proceed past the Proposal halt.
+- **Gate 1 (Initiative approval):** lint must pass before the agent may proceed past the Initiative halt.
 - **Gate 3 (Push):** lint must pass before `cleargate_push_item` is called.
 
 Lint checks performed:
@@ -361,6 +370,24 @@ Ingest reliability follows a three-level fallback:
 
 ---
 
+### §10.10 Wiki Contradiction Detection
+
+After each ingest pass recompiles synthesis pages (Phase 3), the ingest subagent runs an optional Phase 4 contradiction check on any freshly ingested page whose `status` is `Draft` or `In Review`. Phase 4 is synchronous and advisory — it never blocks ingest, never causes a non-zero exit, and never modifies anything other than the wiki page's `last_contradict_sha` field and the append-only `wiki/contradictions.md` log.
+
+Rules:
+
+- **Trigger point.** Phase 4 fires after Phase 3 (synthesis recompile) completes, once per ingested page, only when the page status is `Draft` or `In Review`. All other statuses (`Approved`, `Done`, `Active`, etc.) are skipped silently.
+- **Neighborhood rule.** The neighborhood for a given draft page consists of: (1) all pages explicitly cited via `[[ID]]` in the raw draft body, (2) the draft's parent epic page, and (3) any sibling stories under the same parent epic. The neighborhood is capped at 12 pages; when more than 12 qualify, the closest-cited pages take priority and the finding record sets `truncated: true`.
+- **Idempotency rule.** Phase 4 is skipped when `last_contradict_sha` stored on the wiki page equals `git log -1 --format=%H -- <raw_path>` at the moment Phase 4 would run. A match means the draft has not changed since the last contradiction check; no re-check is needed.
+- **Status filter.** Only `Draft` and `In Review` raw-file statuses trigger Phase 4. The filter reads the raw frontmatter `status` field, not the wiki page's emoji status field.
+- **Advisory exit.** Phase 4 always exits 0. Contradiction findings are written to `wiki/contradictions.md` as an append-only YAML log (see §10.10 schema). No gate is blocked. A future enforcing-mode proposal must clear the calibration precondition (see below) before Phase 4 may exit non-zero.
+- **Subagent contract.** Phase 4 invokes the `cleargate-wiki-contradict` subagent with `{ draft_path, neighborhood: string[] }` inputs. The subagent emits zero or more `contradiction: <draft-id> vs <neighbor-id> · <claim-summary ≤80 chars>` lines plus one paragraph of reasoning per finding, then exits 0.
+- **Log schema.** Each finding appended to `wiki/contradictions.md` has the keys: `draft`, `neighbor`, `claim`, `ingest_sha`, `truncated`, `label`. The `label` field is `null` until a human applies `true-positive`, `false-positive`, or `nitpick`.
+
+**Calibration plan.** Phase 4 enters advisory-only mode unconditionally for an initial 30-day calibration window. A future enforcing-mode proposal may be filed only after the advisory log contains at least 20 human-labeled findings with a true-positive rate of ≥ 80%. Until that precondition is met, any proposal to make Phase 4 exit non-zero is out of scope.
+
+---
+
 ## 11. Document Metadata Lifecycle
 
 Every work item file managed by ClearGate carries timestamp and version fields that track when it was created, last modified, and last pushed to the remote PM tool. This section defines those fields, how they are populated, and when they are frozen.
@@ -440,6 +467,21 @@ Implementation notes:
 
 ---
 
+### §11.7 Hierarchy Keys
+
+Two optional frontmatter keys declare canonical hierarchy for every work item (STORY-015-06):
+
+- `parent_cleargate_id: <string | null>` — the canonical ClearGate ID of the parent work item (e.g. `"EPIC-022"`). Use for items that belong to an epic or parent story. Null for top-level items.
+- `sprint_cleargate_id: <string | null>` — the canonical ClearGate ID of the owning sprint (e.g. `"SPRINT-15"`). Null for off-sprint or speculative items.
+
+**Relationship to legacy keys.** The existing fields `parent_ref`, `parent_epic_ref`, `sprint_id`, and `sprint` remain the **authoritative** source of parent/sprint membership until a future deprecation sprint explicitly retires them. `parent_cleargate_id` and `sprint_cleargate_id` are additive mirrors — consumers must not assume both forms are always present simultaneously. A future deprecation notice will be added to this section when the legacy keys are retired.
+
+**Propagation.** The `cleargate push` command forwards both keys into the `cleargate_push_item` MCP call payload via the existing `payload.*` shallow-clone path. The `cleargate wiki ingest` command copies them verbatim into the compiled wiki page frontmatter. The backfill script `.cleargate/scripts/backfill_hierarchy.mjs` sniffs legacy keys to populate missing values one-time on existing corpus files.
+
+**Idempotency contract.** Both keys default to `null` in templates. The backfill script skips any file where both keys are already non-null. Re-running the backfill is a byte-identical no-op.
+
+---
+
 ## 12. Token Cost Stamping & Readiness Gates
 
 ### §12.1 Overview
@@ -573,321 +615,6 @@ Soft revert preserves audit history on the PM-tool side. Refusing to revert done
 
 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:
@@ -915,56 +642,3 @@ 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.