cleargate 0.1.0-alpha.1 → 0.2.1

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

@@ -0,0 +1,82 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-5.
+YAML Frontmatter: Bug ID, Parent Ref, Status, Severity, Reporter, Approved gate.
+§1 The Anomaly: Expected vs. Actual behavior.
+§2 Reproduction Protocol: Deterministic steps to recreate.
+§3 Evidence & Context: Raw logs, stack traces, payloads — no paraphrasing.
+§4 Execution Sandbox: Exact file paths to investigate. Restrict scope to prevent unrelated refactoring.
+§5 Verification Protocol: The failing test that proves the bug exists and proves the fix resolves it.
+Output location: .cleargate/delivery/pending-sync/BUG-{ID}.md
+
+CRITICAL PHASE GATE: Do NOT invoke cleargate_push_item until reproduction steps are 100% deterministic and a failing test is attached.
+Do NOT output these instructions.
+</instructions>
+
+---
+bug_id: "BUG-{ID}"
+parent_ref: "EPIC-{ID} | STORY-{ID}"
+status: "Draft | Triaged | In Fix | Verified"
+severity: "P0-Critical | P1-High | P2-Medium | P3-Low"
+reporter: "{name}"
+approved: false
+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"
+server_pushed_at_version: null
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+---
+
+# BUG-{ID}: {Bug Name}
+
+## 1. The Anomaly (Expected vs. Actual)
+**Expected Behavior:** {What the system should do under normal conditions.}
+
+**Actual Behavior:** {What it is doing right now.}
+
+## 2. Reproduction Protocol
+*(AI agents need strict, deterministic steps. "If it can't be reproduced reliably, it can't be fixed safely.")*
+
+1. Go to...
+2. Click...
+3. Observe...
+
+## 3. Evidence & Context
+*(Provide the raw truth: stack traces, terminal errors, network payloads. Do not paraphrase.)*
+
+```
+[Paste exact logs or error messages here]
+```
+
+## 4. Execution Sandbox (Suspected Blast Radius)
+*(Restrict the agent's focus to prevent unrelated refactoring.)*
+
+**Investigate / Modify:**
+- `src/...`
+
+## 5. Verification Protocol (The Failing Test)
+*(The agent must write or run a specific test that proves the bug exists, then prove the fix resolves it.)*
+
+**Command:** `npm test ...`
+
+---
+
+## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
+**Current Status: 🔴 High Ambiguity**
+
+Requirements to pass to Green (Ready for Fix):
+- [ ] Reproduction steps are 100% deterministic.
+- [ ] Actual vs. Expected behavior is explicitly defined.
+- [ ] Raw error logs/evidence are attached.
+- [ ] Verification command (failing test) is provided.
+- [ ] `approved: true` is set in the YAML frontmatter.

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

@@ -0,0 +1,77 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+YAML Frontmatter: CR ID, Parent Ref (Epic or Story being changed), Status, Approved gate.
+Use this template when CHANGING an existing feature. For net-new functionality, use story.md instead.
+§1 The Context Override: What to remove/forget + the new truth. AI agents hallucinate when old context conflicts with new requests.
+§2 Blast Radius & Invalidation: Which downstream items does this CR break? A CR acts as a "Gate Reset" on affected items.
+§3 Execution Sandbox: Exact file paths to modify.
+§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.
+Do NOT output these instructions.
+</instructions>
+
+---
+cr_id: "CR-{ID}"
+parent_ref: "EPIC-{ID} | STORY-{ID}"
+status: "Draft | In Review | Approved"
+approved: false
+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"
+server_pushed_at_version: null
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+---
+
+# CR-{ID}: {Change Request Name}
+
+## 1. The Context Override (Old vs. New)
+*(AI agents hallucinate when old context conflicts with new requests. Explicitly declare what to evict.)*
+
+**Obsolete Logic (What to Remove / Forget):**
+- {e.g., We no longer use Stripe for this flow.}
+
+**New Logic (The New Truth):**
+- {e.g., Route all payments through PayPal.}
+
+## 2. Blast Radius & Invalidation
+*(A CR acts as a "Gate Reset" — all affected downstream items revert to 🔴 High Ambiguity.)*
+
+- [ ] Invalidate/Update Story: [Link]
+- [ ] Invalidate/Update Epic: [Link]
+- [ ] Database schema impacts? {Yes/No — describe}
+
+## 3. Execution Sandbox
+*(Restrict the agent's scope to prevent unrelated refactoring.)*
+
+**Modify:**
+- `src/...`
+
+## 4. Verification Protocol
+*(How do we confirm new logic works and old logic is completely removed?)*
+
+**Command/Test:** `npm test ...`
+
+---
+
+## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
+**Current Status: 🔴 High Ambiguity**
+
+Requirements to pass to Green (Ready for Execution):
+- [ ] "Obsolete Logic" to be evicted is explicitly declared.
+- [ ] All impacted downstream Epics/Stories are identified and reverted to 🔴 High Ambiguity.
+- [ ] Execution Sandbox contains exact file paths.
+- [ ] Verification command is provided.
+- [ ] `approved: true` is set in the YAML frontmatter.

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

@@ -0,0 +1,63 @@
+<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.
+</instructions>
+
+---
+sprint_id: "SPRINT-{ID}"
+remote_id: "{PM_TOOL_SPRINT_ID}"
+source_tool: "linear | jira"
+status: "Draft | Active | Completed"
+start_date: "{YYYY-MM-DD}"
+end_date: "{YYYY-MM-DD}"
+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"
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+---
+
+# SPRINT-{ID}: {Sprint Number / Name}
+
+## Sprint Goal
+{One clear sentence describing the primary objective of this sprint, as defined in the PM tool.}
+
+## Consolidated Deliverables
+*(Pulled from PM tool. IDs are the remote PM entity IDs.)*
+
+- `{TASK-ID}`: {Title} — {Brief Description}
+- `{TASK-ID}`: {Title} — {Brief Description}
+
+## Risks & Dependencies
+*(As defined in the PM tool.)*
+
+| Risk | Mitigation |
+|---|---|
+| {Description} | {Action} |
+
+## Metrics & Metadata
+- **Expected Impact:** {e.g., performance improvement %, specific user outcome}
+- **Priority Alignment:** {Notes on prioritization from the PM tool}
+
+---
+
+## Execution Guidelines (Local Annotation — Not Pushed)
+*(Vibe Coder: Fill this in locally to direct Claude Code during the Execution Phase. This section never syncs to the PM tool.)*
+
+- **Starting Point:** {Which deliverable to tackle first and why}
+- **Relevant Context:** {Key documentation or codebase areas to reference}
+- **Constraints:** {Specific technical boundaries or "out of scope" rules for this sprint}

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

@@ -0,0 +1,120 @@
+<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.
+§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.
+§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.
+Do NOT output these instructions.
+</instructions>
+
+---
+epic_id: "EPIC-{ID}"
+status: "Draft"
+ambiguity: "🔴 High"
+context_source: "PROPOSAL-{ID}.md"
+owner: "{PM/PO name}"
+target_date: "{YYYY-MM-DD}"
+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"
+server_pushed_at_version: null
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+---
+
+# EPIC-{ID}: {Epic Name}
+
+## 0. AI Coding Agent Handoff
+*(This section is strictly for downstream AI execution agents. It contains zero business fluff.)*
+
+```xml
+<agent_context>
+  <objective>{1 sentence strict technical objective}</objective>
+  <architecture_rules>
+    <rule>Must use existing {Component/Pattern}</rule>
+    <rule>No changes to {Protected Area}</rule>
+  </architecture_rules>
+  <target_files>
+    <file path="src/..." action="modify|create" />
+  </target_files>
+</agent_context>
+```
+
+## 1. Problem & Value
+
+**Why are we doing this?**
+{1-2 sentences explaining the user pain or business value.}
+
+**Success Metrics (North Star):**
+- Metric 1: {Quantifiable outcome}
+
+## 2. Scope Boundaries
+
+**✅ IN-SCOPE (Build This)**
+- [ ] {Technical capability 1}
+- [ ] {Technical capability 2}
+
+**❌ OUT-OF-SCOPE (Do NOT Build This)**
+- {Explicitly excluded capability to prevent scope creep / AI hallucination}
+
+## 3. The Reality Check (Context)
+
+| Constraint Type | Limit / Rule |
+|---|---|
+| Performance | {e.g., Must complete in < 200ms} |
+| Security | {e.g., No PII in logs} |
+
+## 4. Technical Grounding (The "Shadow Spec")
+*(AI Planning Engine: Populate this strictly from the approved proposal.md)*
+
+**Affected Files:**
+- `path/to/file.ext` — {Why it changes}
+
+**Data Changes:**
+- Table/Entity: {New column/field}
+
+## 5. Acceptance Criteria
+
+```gherkin
+Feature: {Epic Name}
+  Scenario: {Scenario Name}
+    Given {precondition}
+    When {action}
+    Then {outcome}
+```
+
+## 6. AI Interrogation Loop (Human Input Required)
+*(AI Planning Engine: List edge cases, contradictions, or missing details found while drafting. The Epic stays 🔴 until the Human answers all of these.)*
+
+- **AI Question:** "{e.g., You mentioned we need to send an email, but src/services/email doesn't support templates yet. Should we build the template engine first, or hardcode this one?}"
+- **Human Answer:** {Waiting for user}
+
+---
+
+## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
+**Current Status: 🔴 High Ambiguity**
+
+Requirements to pass to Green (Ready for Coding Agent):
+- [ ] Proposal document has `approved: true`.
+- [ ] The `<agent_context>` block is complete and validated.
+- [ ] §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.

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

@@ -0,0 +1,53 @@
+<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.
+</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"
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+---
+
+# INIT-{ID}: {Initiative Name}
+
+## 1. Objective & Business Value
+{High-level summary of what this initiative achieves and the expected outcome for the user or system.}
+
+## 2. Success Criteria
+- {Concrete metric or functional requirement 1}
+- {Concrete metric or functional requirement 2}
+
+## 3. Scope & Constraints
+
+**In scope:**
+- {What is included}
+
+**Out of scope:**
+- {What is explicitly excluded}
+
+**Hard constraints:**
+- {Deadlines, architectural rules, compliance requirements}
+
+## 4. Target Sprint / Timeline
+{Sprint number or date range as defined in the PM tool.}

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

@@ -0,0 +1,52 @@
+<instructions> 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)
+
+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.
+
+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"
+updated_at: "2026-04-17T00:00:00Z"
+created_at_version: "strategy-phase-pre-init"
+updated_at_version: "strategy-phase-pre-init"
+server_pushed_at_version: null
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+PROPOSAL-{ID}: {Initiative Name}
+1. Initiative & Context
+1.1 Objective
+{1-2 sentences explaining the high-level goal and business value.}
+
+1.2 The "Why"
+{Reason 1}
+{Reason 2}
+2. Technical Architecture & Constraints
+2.1 Dependencies
+{List required external APIs, packages, or systems}
+2.2 System Constraints
+Constraint	Details
+Architectural Rules	{e.g., Must use purely functional components, etc.}
+Security	{e.g., Data must be encrypted at rest.}
+3. Scope Impact (Touched Files & Data)
+3.1 Known Files
+path/to/existing/file.ext - {Explanation of expected change}
+3.2 Expected New Entities
+path/to/new/file.ext - {Explanation of purpose}
+🔒 Approval Gate
+(Vibe Coder: Review this proposal. If the architecture and context are correct, change approved: false to approved: true in the YAML frontmatter. Only then is the AI authorized to proceed with Epic/Story decomposition.)

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

@@ -0,0 +1,135 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+YAML Frontmatter: Story ID, Parent Epic, Status, Ambiguity, Context Source (MUST link to approved proposal.md), Actor, Complexity Label.
+§1 The Spec: User Story + Detailed Requirements + Out of Scope.
+§2 The Truth: Gherkin acceptance criteria + manual verification steps.
+§3 Implementation Guide: Files to modify, technical logic, API contract. Sourced from approved proposal.md.
+§4 Quality Gates: Minimum test expectations + Definition of Done checklist.
+Output location: .cleargate/delivery/pending-sync/STORY-{EpicID}-{StoryID}-{StoryName}.md
+
+Document Hierarchy Position: LEVEL 2 (Proposal → Epic → Story)
+
+Complexity Labels:
+L1: Trivial — Single file, <1hr, known pattern
+L2: Standard — 2-3 files, known pattern, ~2-4hr (default)
+L3: Complex — Cross-cutting, spike may be needed, ~1-2 days
+L4: Uncertain — Requires probing/spiking, >2 days
+
+Granularity Rubric (run this check BEFORE emitting a story during epic-decomposition):
+A candidate story is too big — emit two stories instead, with consecutive IDs (e.g. STORY-007-03 and STORY-007-04, never 03a/03b) — if ANY signal trips:
+  • §1.2 Detailed Requirements joins unrelated user goals with "and also" / "additionally".
+  • §2.1 Gherkin would need >5 scenarios covering unrelated behaviors.
+  • §3.1 Files-to-touch span unrelated subsystems (e.g. API + UI + migration in one story).
+  • Complexity would land at L4 (>2 days). L4 is a planning smell — split, or carve out a spike as its own story.
+Also split the inverse: two candidate stories that each touch the same 1-2 files with overlapping scenarios should merge into one L1/L2.
+At epic-decomposition time there are no remote IDs yet — splits and merges are free. Prefer two focused L1/L2 stories over one L3. Prefer L3 over L4.
+When the rubric is ambiguous, surface the decision to the human as a one-liner ("candidate covers A+B — split into X and Y?") rather than guessing.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+story_id: "STORY-{EpicID}-{StoryID}-{StoryName}"
+parent_epic_ref: "EPIC-{ID}"
+status: "Draft"
+ambiguity: "🔴 High"
+context_source: "PROPOSAL-{ID}.md"
+actor: "{Persona Name}"
+complexity_label: "L2"
+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"
+server_pushed_at_version: null
+draft_tokens:
+  input: null
+  output: null
+  cache_read: null
+  cache_creation: null
+  model: null
+  sessions: []
+cached_gate_result:
+  pass: null
+  failing_criteria: []
+  last_gate_check: null
+---
+
+# STORY-{EpicID}-{StoryID}: {Story Name}
+**Complexity:** {L1/L2/L3/L4} — {brief description}
+
+## 1. The Spec (The Contract)
+
+### 1.1 User Story
+As a {Persona}, I want to {Action}, so that {Benefit}.
+
+### 1.2 Detailed Requirements
+- Requirement 1: {Specific behavior}
+- Requirement 2: {Specific data or constraint}
+
+### 1.3 Out of Scope
+{What this story explicitly does NOT do.}
+
+## 2. The Truth (Executable Tests)
+
+### 2.1 Acceptance Criteria (Gherkin)
+
+```gherkin
+Feature: {Story Name}
+
+  Scenario: {Happy Path}
+    Given {precondition}
+    When {user action}
+    Then {system response}
+
+  Scenario: {Edge Case / Error}
+    Given {precondition}
+    When {invalid action}
+    Then {error message}
+```
+
+### 2.2 Verification Steps (Manual)
+- [ ] {e.g., "Verify API returns 200 for valid input"}
+- [ ] {e.g., "Verify UI renders correctly on mobile"}
+
+## 3. The Implementation Guide
+
+### 3.1 Context & Files
+
+| Item | Value |
+|---|---|
+| Primary File | `{filepath/to/main/component.ts}` |
+| Related Files | `{filepath/to/api/service.ts}`, `{filepath/to/types.ts}` |
+| New Files Needed | Yes/No — {Name of file} |
+
+### 3.2 Technical Logic
+{Describe the logic flow, e.g., "Use the existing useAuth hook to check permissions."}
+
+### 3.3 API Contract (if applicable)
+
+| Endpoint | Method | Auth | Request Shape | Response Shape |
+|---|---|---|---|---|
+| `/api/resource` | GET/POST | Bearer/None | `{ id: string }` | `{ status: string }` |
+
+## 4. Quality Gates
+
+### 4.1 Minimum Test Expectations
+
+| Test Type | Minimum Count | Notes |
+|---|---|---|
+| Unit tests | {N} | {e.g., "1 per exported function"} |
+| E2E / acceptance tests | {N} | {e.g., "1 per Gherkin scenario in §2.1"} |
+
+### 4.2 Definition of Done (The Gate)
+- [ ] Minimum test expectations (§4.1) met.
+- [ ] All Gherkin scenarios from §2.1 covered.
+- [ ] Peer/Architect Review passed.
+
+---
+
+## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
+**Current Status: 🔴 High Ambiguity**
+
+Requirements to pass to Green (Ready for Execution):
+- [ ] Gherkin scenarios completely cover all detailed requirements in §1.2.
+- [ ] Implementation Guide (§3) maps to specific, verified file paths from the approved proposal.
+- [ ] No "TBDs" exist anywhere in the specification or technical logic.

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

@@ -0,0 +1,42 @@
+# ClearGate — Injected CLAUDE.md Block
+
+This file is the content `cleargate init` injects into a downstream user's `CLAUDE.md` between bounded markers. If the user has no existing `CLAUDE.md`, init writes this as a standalone file wrapped with the markers. If one already exists, init appends the bounded block below without touching the user's existing content. Re-running `cleargate init` updates the block in place.
+
+---
+
+<!-- CLEARGATE:START -->
+## 🔄 ClearGate Planning Framework
+
+This repository uses **ClearGate** — a standalone planning framework for AI coding agents. ClearGate scaffolds *how work is planned* (proposals → epics → stories → sprints) and defines a four-agent loop for execution. ClearGate does not run builds, tests, or deployments; execution tooling remains the target repo's own.
+
+**Session-start orientation (read in this order):**
+1. `.cleargate/wiki/index.md` — compiled awareness layer (~3k tokens). Lists active sprint, in-flight items, recent shipments, open gates, planned work, and topic synthesis pages. **Read this first** to know what exists before grepping raw files. If absent, run `cleargate wiki build`.
+2. `.cleargate/knowledge/cleargate-protocol.md` — delivery protocol (non-negotiable rules).
+3. `.cleargate/FLASHCARD.md` — lessons tagged by topic (`#schema`, `#auth`, etc.). Grep for your area before starting.
+
+**Triage first, draft second.** Every user request gets classified (Epic / Story / CR / Bug / Pull / Push) *before* any drafting. If the type is ambiguous, ask ONE targeted question — do not guess.
+
+**Duplicate check before drafting.** Before drafting a Proposal or work item, grep `.cleargate/delivery/archive/` + `.cleargate/FLASHCARD.md` for similar past work. If you find overlap, surface it as a one-liner (*"This is very close to STORY-003-05 shipped in SPRINT-01 — are you extending it or redoing it?"*) instead of drafting a duplicate.
+
+**Halt at gates.** You halt at Gate 1 (Proposal approval) and Gate 2 (Ambiguity resolution) and wait for explicit human sign-off. You never call `cleargate_push_item` without `approved: true` and explicit human confirmation (Gate 3).
+
+**Drafting work items:**
+- Use the templates in `.cleargate/templates/` (`proposal.md`, `epic.md`, `story.md`, `CR.md`, `Bug.md`, `Sprint Plan Template.md`, `initiative.md`).
+- Save drafts to `.cleargate/delivery/pending-sync/{TYPE}-{ID}-{Name}.md`.
+- After `cleargate_push_item` returns a Remote ID, update the frontmatter AND move the file to `.cleargate/delivery/archive/` — these two happen atomically, never one without the other.
+- **Story granularity.** When decomposing an epic into stories, run the Granularity Rubric at the top of `story.md`. If a candidate story trips any signal (unrelated goals joined, >5 Gherkin scenarios, subsystems span, L4 complexity), emit two stories with consecutive IDs instead. Splits and merges are free at decomposition time — no remote IDs exist yet.
+
+**Four-agent loop (roles in `.claude/agents/`):**
+- `architect.md` — one plan per milestone; no production code.
+- `developer.md` — one Story end-to-end; one commit per Story; runs typecheck + tests before commit.
+- `qa.md` — independent verification gate; re-runs checks; never commits, never edits.
+- `reporter.md` — one sprint retrospective at sprint end; synthesizes token ledger + git log + flashcards into `REPORT.md`.
+
+**Conversational style.** Keep replies terse. Details live in the work-item file and `REPORT.md`, not in chat. State results and next steps; skip narration of your own thought process.
+
+**Support infrastructure.** Flashcard protocol: `.claude/skills/flashcard/SKILL.md`. Token-ledger hook: `.claude/hooks/token-ledger.sh`, wired via `.claude/settings.json` (SubagentStop) — auto-logs agent cost per sprint for the Reporter.
+
+**Project overrides.** Content OUTSIDE this `<!-- CLEARGATE:START -->...<!-- CLEARGATE:END -->` block takes precedence where it conflicts with ClearGate defaults.
+
+**Scope reminder.** ClearGate is a *planning* framework. It scaffolds how work gets planned and how the four-agent loop runs. It does not replace your project's build system, CI, test runner, or deployment tooling.
+<!-- CLEARGATE:END -->