cleargate 0.8.1 → 0.10.0

package/dist/templates/cleargate-planning/.cleargate/templates/CR.md

@@ -8,13 +8,28 @@ Use this template when CHANGING an existing feature. For net-new functionality,
 §4 Verification Protocol: How to confirm new logic works and old logic is fully evicted.
 Output location: .cleargate/delivery/pending-sync/CR-{ID}.md
 
-CRITICAL PHASE GATE: Do NOT invoke cleargate_push_item until all impacted downstream Epics/Stories are identified and reverted to 🔴 High Ambiguity.
+POST-WRITE BRIEF
+After Writing this document, render a Brief in chat with the following sections,
+mechanically extracted from the document's own structure:
+
+  - Summary        ← §1 The Context Override
+  - Open Questions ← §0.5 Open Questions
+  - Edge Cases     ← §2 Blast Radius & Invalidation
+  - Risks          ← §2 Blast Radius (downstream invalidation = risk)
+  - Ambiguity      ← bottom-of-doc ambiguity gate block
+
+Halt for human review. When ambiguity reaches 🟢, proceed to call cleargate_push_item.
+Do NOT ask separately for push confirmation — Brief approval covers it.
+
 Do NOT output these instructions.
 </instructions>
 
 ---
 cr_id: "CR-{ID}"
 parent_ref: "EPIC-{ID} | STORY-{ID}"
+parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
+sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
+carry_over: false  # set true to skip lifecycle reconciliation at sprint close
 status: "Draft | In Review | Approved"
 approved: false
 created_at: "2026-04-17T00:00:00Z"
@@ -33,19 +48,27 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
-# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
-pushed_by: null            # STORY-010-07 writer / STORY-010-04 reader
-pushed_at: null            # STORY-010-07 writer / STORY-010-04 reader
-last_pulled_by: null       # STORY-010-04 writer / STORY-010-03 reader
-last_pulled_at: null       # STORY-010-04 writer / STORY-010-03 reader
-last_remote_update: null   # STORY-010-02 writer (from MCP) / STORY-010-03 reader
-source: "local-authored"   # STORY-010-05 flips to "remote-authored" on intake
-last_synced_status: null   # STORY-010-04 writer; required for conflict-detector rule 6
-last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
+# Sync attribution. Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null            # set by push: which user pushed
+pushed_at: null            # set by push: ISO-8601 timestamp
+last_pulled_by: null       # set by pull: which user pulled
+last_pulled_at: null       # set by pull: ISO-8601 timestamp
+last_remote_update: null   # set by pull: server's last-modified timestamp
+source: "local-authored"   # flips to "remote-authored" on intake
+last_synced_status: null   # required for conflict-detector; status at last sync
+last_synced_body_sha: null # sha256 of body at last sync
 ---
 
 # CR-{ID}: {Change Request Name}
 
+## 0.5 Open Questions
+
+> Populate during drafting. Resolve every entry before flipping ambiguity to 🟢.
+
+- **Question:** {edge case, contradiction, or missing detail}
+- **Recommended:** {agent's proposed answer}
+- **Human decision:** {populated during Brief review}
+
 ## 1. The Context Override (Old vs. New)
 *(AI agents hallucinate when old context conflicts with new requests. Explicitly declare what to evict.)*
 
@@ -62,6 +85,13 @@ last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
 - [ ] Invalidate/Update Epic: [Link]
 - [ ] Database schema impacts? {Yes/No — describe}
 
+## 2.5 Existing Surfaces
+
+> L1 reuse audit. List source-tree implementations this CR extends or modifies. Cite file:line.
+
+- **Surface:** `path/to/file.ext:NN` — {what it does today}
+- **Why this CR extends rather than rebuilds:** {one paragraph — required when the change names a capability that already exists somewhere in the tree}
+
 ## 3. Execution Sandbox
 *(Restrict the agent's scope to prevent unrelated refactoring.)*
 
@@ -84,3 +114,4 @@ Requirements to pass to Green (Ready for Execution):
 - [ ] Execution Sandbox contains exact file paths.
 - [ ] Verification command is provided.
 - [ ] `approved: true` is set in the YAML frontmatter.
+- [ ] §2.5 Existing Surfaces cites at least one source-tree path the CR extends.

package/dist/templates/cleargate-planning/.cleargate/templates/Sprint Plan Template.md

@@ -1,25 +1,51 @@
 <instructions>
-This is a READ artifact. It is written by cleargate_pull_initiative when syncing a Sprint from the remote PM tool.
-Do NOT draft this file manually. Do NOT invoke cleargate_push_item on this file.
-The Vibe Coder may annotate the "Execution Guidelines" section locally — this section is never pushed.
-Output location: .cleargate/plans/SPRINT-{ID}.md
-Do NOT output these instructions.
-
-§1 Lane column placement: "Lane" is inserted between "Title" and "Milestone" in the Consolidated Deliverables
-table (§1). This positions lane as a planning signal adjacent to the story title, which is where the Architect
-most naturally reads it during Sprint Design Review. Values are "standard" (default) or "fast" (see protocol §24).
+This template is actively authored during the Prepare phase.
+
+WHAT TO GATHER
+  - Sprint number — read .cleargate/wiki/active-sprint.md, scan pending-sync/SPRINT-*.md, emit max(N) + 1
+  - Available work items — pending-sync/{EPIC,STORY,CR,BUG,HOTFIX}-*.md filtered ambiguity:🟢 + status:Ready
+  - Human-set priorities — frontmatter `priority` field per item
+  - Cross-item dependencies — `parent_epic_ref:` + shared file-surface analysis
+
+HOW TO GATHER
+  - Read for sprint-runs/, Grep for pending-sync/, scripts/wiki-query for awareness layer
+  - cleargate-cli/src/lib/admin-url.ts for any admin-link references
+
+ANALYSIS REQUIRED
+  - Propose priority reordering for technical reasons (dep chains, shared-surface conflicts, fast-lane bundling). One-line rationale per change.
+  - Flag missing decomposition (epics with no child stories) — must resolve before Gate 2 passes.
+  - Trigger Architect Sprint Design Review (writes §2 Execution Strategy) once scope is locked.
+
+WHERE TO WRITE
+  - .cleargate/delivery/pending-sync/SPRINT-<#>_<name>.md
+
+POST-WRITE BRIEF
+  Render in chat with these sections:
+    - Sprint Goal (1 sentence)
+    - Selected items (table: id / type / lane / milestone / parallel? / bounce-exposure)
+    - Recommended priority changes (with one-line rationale per change)
+    - Open questions for human (with recommended answers)
+    - Risks (with mitigations)
+    - Current ambiguity + Gate 2 readiness checklist (decomposed? all 🟢? SDR §2 written?)
+  Halt for human review. When ambiguity reaches 🟢 AND Gate 2 conditions satisfy, proceed to call cleargate_push_item.
+
+DUAL-AUDIENCE STRUCTURE
+  Top of body: Stakeholder/Sponsor view (Sprint Goal, Business Outcome, Risks/Mitigations, Metrics).
+  Bottom of body: AI-execution view (Phase Plan, Merge Ordering, Lane Audit, ADR-Conflict Flags, Decomposition Status).
 
-§2.4 Lane Audit: The Architect populates one row per fast-lane story during Sprint Design Review. Empty by default.
-Rows are added only for non-`standard` lanes. The subsection is numbered 2.4; the former §2.4 ADR-Conflict Flags
-is renumbered to §2.5.
+Do NOT output these instructions.
 </instructions>
 
 ---
 sprint_id: "SPRINT-{ID}"
+parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
+sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
+carry_over: false  # set true to skip lifecycle reconciliation at sprint close
+lifecycle_init_mode: "warn"  # "warn" | "block" — controls sprint-init lifecycle gate (§10.4); use "block" for SPRINT-16+
 remote_id: "{PM_TOOL_SPRINT_ID}"
 source_tool: "linear | jira"
 status: "Draft | Active | Completed"
-execution_mode: "v1"   # Enum: "v1" | "v2". Default "v1". Under "v2", §§15–18 of cleargate-protocol.md are enforcing (worktree isolation, pre-gate scanning, bounce counters, flashcard gate, sprint-close pipeline). Under "v1", those sections are advisory only and all new CLI commands (sprint init|close, story start|complete, gate qa|arch, state update|validate) print an inert-mode message. Set to "v2" only after all EPIC-013 M2 stories have shipped and the Architect has completed a Sprint Design Review (see §19 of the protocol).
+execution_mode: "v1"   # Enum: "v1" | "v2". Default "v1". Under "v2", §§1–18 of cleargate-enforcement.md are enforcing (worktree isolation, pre-gate scanning, bounce counters, flashcard gate, sprint-close pipeline). Under "v1", those sections are advisory only and all new CLI commands (sprint init|close, story start|complete, gate qa|arch, state update|validate) print an inert-mode message. Set to "v2" only after all EPIC-013 M2 stories have shipped and the Architect has completed a Sprint Design Review (see §5 of the protocol).
 start_date: "{YYYY-MM-DD}"
 end_date: "{YYYY-MM-DD}"
 synced_at: "{ISO-8601 timestamp}"
@@ -42,6 +68,14 @@ cached_gate_result:
 
 # SPRINT-{ID}: {Sprint Number / Name}
 
+## 0. Stakeholder Brief
+*(Sponsor-readable summary. Pushed to PM tool. Pair with §3 Risks below.)*
+
+- **Sprint Goal:** {1 sentence}
+- **Business Outcome:** {what the user / sponsor gets}
+- **Risks (top 3):** {bullet list, see §3 for full table}
+- **Metrics:** {expected impact / KPIs}
+
 ## Sprint Goal
 {One clear sentence describing the primary objective of this sprint, as defined in the PM tool.}
 
@@ -66,7 +100,7 @@ Example:
 
 | Shared File | Stories Touching It | Merge Order | Rationale |
 |---|---|---|---|
-| `.cleargate/knowledge/cleargate-protocol.md` | STORY-NNN-01, STORY-NNN-02 | 01 → 02 | 01 adds §16; 02 amends §16 |
+| `.cleargate/knowledge/cleargate-enforcement.md` | STORY-NNN-01, STORY-NNN-02 | 01 → 02 | 01 adds §2; 02 amends §2 |
 
 ### 2.3 Shared-Surface Warnings
 {Explicit conflict risks. One bullet per risk. Cite file + story pair.}

package/dist/templates/cleargate-planning/.cleargate/templates/epic.md

@@ -1,22 +1,40 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order.
-YAML Frontmatter: Epic ID, Status, Ambiguity, Context Source (MUST link to approved proposal.md), Owner, Target Date.
+YAML Frontmatter: Epic ID, Status, Ambiguity, Context Source, Owner, Target Date.
 §0 Agent Handoff: XML block specifically formulated for AI coding agents to ingest.
 §1 Problem & Value: Why (problem), What (solution), Success Metrics.
 §2 Scope Boundaries: IN-SCOPE checkboxes, OUT-OF-SCOPE list.
 §3 The Reality Check (Context): Constraints table.
-§4 Technical Grounding: Verified files and data changes. Copied strictly from approved proposal.md.
+§4 Technical Grounding: Verified files and data changes.
 §5 Acceptance Criteria: Gherkin scenarios (happy path + error cases).
 §6 AI Interrogation Loop: Explicit questions the Planning AI needs the Human to answer.
 Output location: .cleargate/delivery/pending-sync/EPIC-{NNN}_{epic_name}.md
 
 Codebase research is mandatory. Do NOT guess at affected files.
-You MUST base this strictly on an approved: true proposal document.
+
+POST-WRITE BRIEF
+After Writing this document, render a Brief in chat with the following sections,
+mechanically extracted from the document's own structure:
+
+  - Summary          ← §1 Problem & Value
+  - Open Questions   ← §6 AI Interrogation Loop
+  - Edge Cases       ← §2 OUT-OF-SCOPE list + §5 error scenarios
+  - Risks            ← §3 The Reality Check
+  - Existing Surfaces ← §3.5 Existing Surfaces
+  - Why not simpler? ← §3.6 Why not simpler?
+  - Ambiguity        ← bottom-of-doc ambiguity gate block
+
+Halt for human review. When ambiguity reaches 🟢, proceed to call cleargate_push_item.
+Do NOT ask separately for push confirmation — Brief approval covers it.
+
 Do NOT output these instructions.
 </instructions>
 
 ---
 epic_id: "EPIC-{ID}"
+parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
+sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
+carry_over: false  # set true to skip lifecycle reconciliation at sprint close
 status: "Draft"
 ambiguity: "🔴 High"
 context_source: "PROPOSAL-{ID}.md"
@@ -38,15 +56,15 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
-# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
-pushed_by: null            # STORY-010-07 writer / STORY-010-04 reader
-pushed_at: null            # STORY-010-07 writer / STORY-010-04 reader
-last_pulled_by: null       # STORY-010-04 writer / STORY-010-03 reader
-last_pulled_at: null       # STORY-010-04 writer / STORY-010-03 reader
-last_remote_update: null   # STORY-010-02 writer (from MCP) / STORY-010-03 reader
-source: "local-authored"   # STORY-010-05 flips to "remote-authored" on intake
-last_synced_status: null   # STORY-010-04 writer; required for conflict-detector rule 6
-last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
+# Sync attribution. Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null            # set by push: which user pushed
+pushed_at: null            # set by push: ISO-8601 timestamp
+last_pulled_by: null       # set by pull: which user pulled
+last_pulled_at: null       # set by pull: ISO-8601 timestamp
+last_remote_update: null   # set by pull: server's last-modified timestamp
+source: "local-authored"   # flips to "remote-authored" on intake
+last_synced_status: null   # required for conflict-detector; status at last sync
+last_synced_body_sha: null # sha256 of body at last sync
 ---
 
 # EPIC-{ID}: {Epic Name}
@@ -91,6 +109,20 @@ last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
 | Performance | {e.g., Must complete in < 200ms} |
 | Security | {e.g., No PII in logs} |
 
+## 3.5 Existing Surfaces
+
+> L1 reuse audit. List source-tree implementations the epic could extend. Cite file:line.
+
+- **Surface:** `path/to/file.ext:NN` — {what it does}
+- **Coverage of this epic's scope:** {≥80% extension / partial / none — and why}
+
+## 3.6 Why not simpler?
+
+> L2 / L3 right-size + justify-complexity. Answer both.
+
+- **Smallest existing surface that could carry this epic:** {citation or "none — net-new abstraction required"}
+- **Why isn't extension / parameterization / config sufficient?** {one paragraph}
+
 ## 4. Technical Grounding (The "Shadow Spec")
 *(AI Planning Engine: Populate this strictly from the approved proposal.md)*
 
@@ -127,3 +159,5 @@ Requirements to pass to Green (Ready for Coding Agent):
 - [ ] §4 Technical Grounding contains 100% real, verified file paths.
 - [ ] §6 AI Interrogation Loop is empty (all human answers integrated into the spec).
 - [ ] 0 "TBDs" exist in the document.
+- [ ] §3.5 Existing Surfaces cites at least one source-tree path or explicitly states "none — net-new."
+- [ ] §3.6 Why not simpler? has both sub-bullets answered.

package/dist/templates/cleargate-planning/.cleargate/templates/hotfix.md

@@ -1,5 +1,36 @@
+<instructions>
+USE THIS TEMPLATE FOR EMERGENCY HOTFIXES ONLY — production anomalies requiring immediate fix outside the sprint cycle. Hotfix discipline: ≤2 files, ≤30 LOC net.
+
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 0.5–4.
+YAML Frontmatter: Hotfix ID, severity, originating signal, lane: "hotfix".
+§0.5 Open Questions: Capture any remaining ambiguity before merge.
+§1 Anomaly: Expected vs. Actual behavior.
+§2 Files Touched: ≤2 files (constraint from EPIC-022 §3).
+§3 Verification Steps: Non-empty before merging (blocks merge if empty).
+§4 Rollback: Git revert instructions.
+Output location: .cleargate/delivery/pending-sync/HOTFIX-{ID}-{Slug}.md
+
+POST-WRITE BRIEF
+After Writing this document, render a Brief in chat with the following sections,
+mechanically extracted from the document's own structure:
+
+  - Summary        ← §1 Anomaly (Problem)
+  - Open Questions ← §0.5 Open Questions
+  - Edge Cases     ← §3 Files Affected (risk of adjacent regression)
+  - Risks          ← §4 Verification + risk-of-missing
+  - Ambiguity      ← bottom-of-doc ClearGate Ambiguity Gate block
+
+Halt for human review. When ambiguity reaches 🟢, proceed to call cleargate_push_item.
+Do NOT ask separately for push confirmation — Brief approval covers it.
+
+Do NOT output these instructions.
+</instructions>
+
 ---
 hotfix_id: "{ID}"
+parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
+sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
+carry_over: false  # set true to skip lifecycle reconciliation at sprint close
 status: "Draft"
 severity: "P2"
 originating_signal: "user-report"
@@ -20,7 +51,7 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
-# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
+# Sync attribution. Optional; stamped by `cleargate push` / `cleargate pull`.
 pushed_by: null
 pushed_at: null
 last_pulled_by: null
@@ -33,6 +64,14 @@ last_synced_body_sha: null
 
 # {ID}: {SLUG}
 
+## 0.5 Open Questions
+
+> Populate during drafting. Resolve every entry before flipping ambiguity to 🟢.
+
+- **Question:** {edge case, contradiction, or missing detail}
+- **Recommended:** {agent's proposed answer}
+- **Human decision:** {populated during Brief review}
+
 ## 1. Anomaly
 
 **Expected Behavior:** {What the system should do under normal conditions.}
@@ -56,3 +95,14 @@ Hotfix discipline: ≤2 files, ≤30 LOC net (EPIC-022 §3).
 ## 4. Rollback
 
 If the hotfix introduces a regression, revert by running `git revert <commit-sha>` on the sprint or main branch. The original anomaly will reappear; escalate to a sprint story for a permanent fix. No data migrations are involved unless noted in §2 above.
+
+---
+
+## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
+**Current Status: 🔴 High Ambiguity**
+
+Requirements to pass to Green (Ready for Merge):
+- [ ] Anomaly is deterministically reproducible (§1 filled).
+- [ ] Files Touched list is ≤2 files (§2 filled).
+- [ ] Verification Steps (§3) are non-empty.
+- [ ] `approved: true` is set in the YAML frontmatter.

package/dist/templates/cleargate-planning/.cleargate/templates/initiative.md

@@ -1,21 +1,43 @@
 <instructions>
-This is a READ artifact. It is written by cleargate_pull_initiative when syncing from the remote PM tool.
-Do NOT draft this file from scratch. Do NOT invoke cleargate_push_item on this file — it is already synced from the remote.
-Use this file as context input when drafting a Proposal or Epic.
-Output location: .cleargate/plans/INIT-{ID}.md
-Do NOT output these instructions.
+USE THIS TEMPLATE TO DOCUMENT WHAT AN INITIATIVE LOOKS LIKE — the BA/PM-authored
+stakeholder-input artifact that captures business intent BEFORE AI decomposition.
+
+WHO AUTHORS THIS: a human BA / PM / sponsor — outside the codebase OR in the upstream
+PM tool (Linear / Jira / GitHub Issues). The AI does NOT author Initiatives from
+scratch in the repo. This template is a cheat sheet for the human author.
+
+HOW IT GETS INTO THE REPO (two paths):
+  1. MCP pull (preferred): `cleargate_pull_initiative` fetches from the upstream PM
+     tool → caches at `.cleargate/delivery/pending-sync/INITIATIVE-NNN_*.md`.
+  2. Manual paste: human drops a markdown file matching this shape into
+     `pending-sync/`. AI stamps `source: manual-paste` then triages.
+
+WHAT THE AI DOES WITH IT:
+  - Reads the cached/pasted Initiative.
+  - Asks open questions in chat.
+  - DECOMPOSES into Epic / Story / CR / Bug — NEVER edits the Initiative body.
+  - On triage completion: moves the Initiative to `archive/INITIATIVE-NNN_*.md`
+    with frontmatter stamps `triaged_at: <ISO-8601>` and
+    `spawned_items: [EPIC-NNN, STORY-NNN-NN, ...]`.
+
+OUTPUT LOCATION: `.cleargate/delivery/pending-sync/INITIATIVE-{NNN}_{short_name}.md`
+
+DO NOT output these instructions in the rendered file.
 </instructions>
 
 ---
-initiative_id: "INIT-{ID}"
-remote_id: "{PM_TOOL_ID}"
-source_tool: "linear | jira"
-status: "{PM native status}"
-synced_at: "{ISO-8601 timestamp}"
-created_at: "2026-04-17T00:00:00Z"
-updated_at: "2026-04-17T00:00:00Z"
-created_at_version: "strategy-phase-pre-init"
-updated_at_version: "strategy-phase-pre-init"
+initiative_id: "INIT-{NNN}"
+remote_id: null
+source_tool: "linear | jira | github | manual-paste"
+status: "{PM native status — e.g. Discovery, In Triage, Triaged}"
+synced_at: null
+triaged_at: null
+spawned_items: []
+created_at: "{ISO-8601 timestamp}"
+updated_at: "{ISO-8601 timestamp}"
+created_at_version: "cleargate@{semver}"
+updated_at_version: "cleargate@{semver}"
+server_pushed_at_version: null
 draft_tokens:
   input: null
   output: null
@@ -27,27 +49,74 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
+# Sync attribution. Optional; stamped by `cleargate_pull_initiative`.
+pushed_by: null
+pushed_at: null
+last_pulled_by: null
+last_pulled_at: null
+last_remote_update: null
+source: "remote-pulled"        # or "manual-paste"
+last_synced_status: null
+last_synced_body_sha: null
 ---
 
-# INIT-{ID}: {Initiative Name}
+# INITIATIVE-{NNN}: {Initiative Name}
+
+## 1. User Flow
+
+{End-to-end walkthrough of what the user does — step-by-step, in plain language.
+Capture the happy path first, then named alternative flows. Diagrams welcome
+(see §2). No technical implementation details — that's the AI's job during
+decomposition.}
+
+## 2. Diagrams
 
-## 1. Objective & Business Value
-{High-level summary of what this initiative achieves and the expected outcome for the user or system.}
+{Embedded mermaid / asciiart / linked image. Optional but encouraged for any
+flow with branching, parallel paths, or multiple actors.
 
-## 2. Success Criteria
-- {Concrete metric or functional requirement 1}
-- {Concrete metric or functional requirement 2}
+Placeholder:
+```
+[ User ] → [ Action 1 ] → [ Outcome ]
+              ↓
+          [ Branch ]
+```
+}
 
-## 3. Scope & Constraints
+## 3. End-to-End Verbal Description
 
-**In scope:**
-- {What is included}
+{The "tell me what this does" paragraph. 3-8 sentences. Captures the intent,
+the ask, and the boundary of the work. Skim-readable for a stakeholder; rich
+enough that the AI can ground the first round of decomposition questions in it.}
 
-**Out of scope:**
-- {What is explicitly excluded}
+## 4. Business Outcome
+
+{Why this matters. 1-2 sentences linking the work to a business metric, user
+need, or strategic goal. Answers "if this ships, what changes?"}
+
+## 5. Success Criteria
+
+- {Concrete, measurable criterion 1 — what must be true to call this done.}
+- {Concrete, measurable criterion 2}
+- {Concrete, measurable criterion 3 (optional)}
+
+## 6. Open Questions for AI Triage
+
+{Questions the BA/PM knows are unresolved and wants the AI to surface during
+decomposition. The AI MAY answer in chat then propose decomposition; the AI
+does NOT edit this section in the Initiative body.
+
+- Question 1
+- Question 2
+}
+
+---
 
-**Hard constraints:**
-- {Deadlines, architectural rules, compliance requirements}
+## Stakeholder Authoring Notes (not pushed)
 
-## 4. Target Sprint / Timeline
-{Sprint number or date range as defined in the PM tool.}
+- Initiative is the **stakeholder-input artifact**, not an AI-authored draft.
+  See `.cleargate/knowledge/cleargate-protocol.md` Plan-phase intake (post-CR-025).
+- The AI never invokes `cleargate_push_item` on this file. Push semantics are
+  one-way: Initiative is **pulled**, Epic / Story / CR / Bug / Hotfix are **pushed**.
+- After triage, this file moves to `archive/` with `triaged_at` + `spawned_items`
+  stamped. The PM tool retains source-of-truth for content; the repo retains
+  the audit trail.

package/dist/templates/cleargate-planning/.cleargate/templates/proposal.md

@@ -1,15 +1,28 @@
-<instructions> FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+<instructions>
+USE THIS TEMPLATE FOR INITIATIVE-CLASS SCOPE ONLY — multi-Epic work where a persistent file-based Brief is genuinely useful before decomposition begins. For single Epic / Story / CR / Bug / Hotfix, triage directly into the appropriate template; no Proposal step is needed.
+
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
 YAML Frontmatter: Proposal ID, Status, Author, and the crucial approved boolean.
 §1 Initiative & Context: The "Why" and "What".
 §2 Technical Architecture & Constraints: Architecture constraints, data flow, dependencies.
 §3 Touched Files: Real files that will need modification.
 Output location: .cleargate/delivery/pending-sync/PROPOSAL-{Name}.md
 
-Document Hierarchy Position: LEVEL 0 (Proposal → Epic → Story)
+POST-WRITE BRIEF
+After Writing this document, render a Brief in chat with the following sections,
+mechanically extracted from the document's own structure:
+
+  - Summary        ← §1 Initiative & Context
+  - Open Questions ← (new — add §1.4 Open Questions if multi-Epic scope is ambiguous)
+  - Edge Cases     ← (new — add §3.3 Edge Cases)
+  - Risks          ← §2 Constraints
+  - Ambiguity      ← bottom-of-doc ambiguity gate block
 
-CRITICAL PHASE GATE: Do NOT generate Epics or Stories, and do NOT invoke cleargate_push_item, until the Human has reviewed this document and manually changed approved: false to approved: true in the frontmatter.
+Halt for human review. When ambiguity reaches 🟢, proceed to call cleargate_push_item.
+Do NOT ask separately for push confirmation — Brief approval covers it.
 
-Do NOT output these instructions. </instructions>
+Do NOT output these instructions.
+</instructions>
 
 proposal_id: "PROP-{ID}" status: "Draft / In Review / Approved" author: "{AI Agent / Vibe Coder}" approved: false
 created_at: "2026-04-17T00:00:00Z"
@@ -28,15 +41,15 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
-# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
-pushed_by: null            # STORY-010-07 writer / STORY-010-04 reader
-pushed_at: null            # STORY-010-07 writer / STORY-010-04 reader
-last_pulled_by: null       # STORY-010-04 writer / STORY-010-03 reader
-last_pulled_at: null       # STORY-010-04 writer / STORY-010-03 reader
-last_remote_update: null   # STORY-010-02 writer (from MCP) / STORY-010-03 reader
-source: "local-authored"   # STORY-010-05 flips to "remote-authored" on intake
-last_synced_status: null   # STORY-010-04 writer; required for conflict-detector rule 6
-last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
+# Sync attribution. Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null            # set by push: which user pushed
+pushed_at: null            # set by push: ISO-8601 timestamp
+last_pulled_by: null       # set by pull: which user pulled
+last_pulled_at: null       # set by pull: ISO-8601 timestamp
+last_remote_update: null   # set by pull: server's last-modified timestamp
+source: "local-authored"   # flips to "remote-authored" on intake
+last_synced_status: null   # required for conflict-detector; status at last sync
+last_synced_body_sha: null # sha256 of body at last sync
 PROPOSAL-{ID}: {Initiative Name}
 1. Initiative & Context
 1.1 Objective

package/dist/templates/cleargate-planning/.cleargate/templates/sprint_report.md

@@ -7,7 +7,7 @@ template_version: 2
 ---
 
 <!-- Sprint Report v2 Template — template_version: 2 -->
-<!-- Event-type vocabulary (STORY-013-05 / protocol §§16–17):
+<!-- Event-type vocabulary (STORY-013-05 / protocol §§2–17):
      User-Review: UR:review-feedback | UR:bug
      Change-Request: CR:bug | CR:spec-clarification | CR:scope-change | CR:approach-change
      Circuit-breaker: test-pattern | spec-gap | environment
@@ -103,7 +103,26 @@ template_version: 2
 
 ---
 
-## §4 Lessons
+## §4 Observe Phase Findings
+
+> Populated from sprint plan §4 Execution Log entries dated within the Observe window
+> [last-story-merge-timestamp, sprint-close-timestamp]. Reporter date-filters and groups by event type.
+>
+> SKIP THIS SECTION ENTIRELY (no header, no body) if all three subsections are empty.
+> Output a single line in its place: "Observe phase: no findings."
+
+### 4.1 Bugs Found (UR:bug)
+| Date | Description | Resolution | Commit |
+
+### 4.2 Hotfixes Triggered
+| ID | Trigger | Resolution | Commit |
+
+### 4.3 Review Feedback (UR:review-feedback)
+| Date | Description | Status (folded / deferred) | Deferred to / Rationale |
+
+---
+
+## §5 Lessons
 
 <!-- Flashcards added during this sprint window, grouped by tag.
      Preserve the stale-detection pass from reporter.md §5b — stale-candidate symbols
@@ -132,7 +151,7 @@ If zero candidates: No stale flashcards detected.
 
 ---
 
-## §5 Framework Self-Assessment
+## §6 Framework Self-Assessment
 
 <!-- Rate each dimension: Green (working well) / Yellow (friction) / Red (blocking).
      "Tooling" subsection MUST include token-divergence finding if §3 divergence flag = YES. -->
@@ -196,7 +215,7 @@ intact for sprints with no hotfixes.>
 
 ---
 
-## §6 Change Log
+## §7 Change Log
 
 <!-- Append one line per material revision to this report after initial generation. -->