cleargate 0.14.0 → 0.15.0

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

@@ -1,213 +0,0 @@
-<instructions>
-FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
-YAML Frontmatter: Story ID, Parent Epic, Status, Ambiguity, Context Source, 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 the approved Epic and verified codebase grounding.
-§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 small** — file a CR or submit the PR directly — if ANY signal trips:
-  • Could this be a config change, a parameter addition, or a one-line edit? If yes, this is not a Story.
-  • The change touches one already-existing function/class and the diff fits in <30 LOC.
-  • The work amounts to renaming, formatting, or moving without behavior change.
-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.
-  • `complexity_label: L3` AND `expected_bounce_exposure: high`. L3+high consistently hits developer-agent wall-time limits (observed in SPRINT-09 on STORY-013-02/03/04, all Sonnet 4.6 stream-timeouts). Split into two L2 stories OR escalate the single L3 to Opus at dispatch — the decomposition default is to split.
-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.
-
-§0.1 v2 Decomposition Signals:
-  `parallel_eligible`: "y" if this story can run concurrently with other stories in the same milestone; "n" if it has a strict predecessor dependency. Default "y". Set by Architect during Sprint Design Review.
-  `expected_bounce_exposure`: "low" | "med" | "high" — predicted re-work risk derived from §2.1 scenario count + §3 file-count + ambiguity level. Default "low". Set by Architect. Used by orchestrator to sequence high-exposure stories before low-exposure ones in a v2 sprint to surface risk early.
-  `lane`: "standard" | "fast" — Architect-set during Sprint Design Review per the seven-check rubric in cleargate-enforcement.md §9. Default "standard". Absent in pre-EPIC-022 stories means standard per the migration default in update_state.mjs.
-  All three fields are v2-only signals. Under v1 sprints they are informational; defaults apply for stories authored before SPRINT-09.
-
-POST-WRITE BRIEF
-After Writing this document, render a Brief in chat with the following sections,
-mechanically extracted from the document's own structure:
-
-  - Prior work    ← cleargate-wiki-query result (cite [[IDs]] or write "none found")
-  - Summary        ← §1.1 User Story
-  - Open Questions ← §1.4 Open Questions
-  - Edge Cases     ← §2.1 Gherkin error scenarios
-  - Risks          ← §1.5 Risks
-  - 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>
-
----
-story_id: "STORY-{EpicID}-{StoryID}-{StoryName}"
-parent_epic_ref: "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"  # lifecycle: Draft → In Review → Completed
-ambiguity: "🔴 High"
-context_source: "approved Epic / verified codebase grounding + recorded direct approval"
-actor: "{Persona Name}"
-complexity_label: "L2"
-parallel_eligible: "y"
-expected_bounce_exposure: "low"
-lane: "standard"
-db_write_set: []  # advisory-v1 (EPIC-033 wave-planner axis 4): list table names this story writes to; default [] = no DB collision contribution; absent treated as [] by architect-synth predicate
-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
-# 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
----
-
-# 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.}
-
-### 1.4 Open Questions
-
-> Resolve every entry before flipping ambiguity to 🟢. Each entry pairs a question with a recommended answer.
-
-- **Question:** {edge case, contradiction, or missing detail surfaced during drafting}
-- **Recommended:** {agent's proposed answer}
-- **Human decision:** {populated during Brief review}
-
-### 1.5 Risks
-
-> Risks specific to this Story (cross-story risks belong in the milestone plan).
-
-- **Risk:** {what could go wrong}
-- **Mitigation:** {agent's proposed mitigation}
-
-## 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
-
-> **v2 gate input:** under v2 execution mode, this table is a pre-commit gate input (cleargate-enforcement.md §6). Every file staged in this story's commit must appear in the Value column, or be covered by `.cleargate/scripts/surface-whitelist.txt`. Non-path rows (e.g. "Mirrors", "New Files Needed: Yes/No") are ignored by the parser.
-
-| 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.
-
-## Existing Surfaces
-
-> L1 reuse audit. List source-tree implementations the request could extend. Cite file:line.
-> Cite paths with at least one '/' separator; root files use './name.ext'. Bare filenames and dotted code references are ignored.
-
-- **Surface:** `path/to/file.ext:NN` — {what it does}
-- **Coverage of this requirement:** {≥80% / partial / none — and why}
-
-## Why not simpler?
-
-> L2 / L3 right-size + justify-complexity. Answer both.
-
-- **Smallest existing surface that could carry this:** {citation or "none — net-new abstraction required"}
-- **Why isn't extension / parameterization / config sufficient?** {one paragraph}
-
----
-
-## ClearGate Ambiguity Gate (🟢 / 🟡 / 🔴)
-**Current Status: 🔴 High Ambiguity**
-
-*Evaluate each criterion against its literal text. If you substituted an interpretation, leave the box unchecked and surface the substitution in the Brief.*
-
-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 Epic and verified codebase grounding.
-- [ ] No "TBDs" exist anywhere in the specification or technical logic.
-- [ ] Existing Surfaces cites at least one source-tree path or explicitly states "none — net-new."
-- [ ] Why not simpler? has both sub-bullets answered (no "TBD" / no "{}").
-

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

@@ -1,66 +0,0 @@
-# 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* (initiatives → epics → stories → sprints) and defines a five-agent loop for execution (Architect, Developer, QA, DevOps, Reporter). 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`. The wiki compiles epics, sprints, proposals, crs, bugs, and initiatives — **stories are excluded by default** (`wiki.ingest_buckets` in `.cleargate/config.yml` omits `stories`; they are too granular for the awareness layer). Stories still sync to ClearGate via `cleargate push`; to see a story, read its raw file under `.cleargate/delivery/**` or pull it from ClearGate. Re-add `stories` to `ingest_buckets` if you want per-story wiki pages.
-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.
-4. `.cleargate/knowledge/cleargate-enforcement.md` — hook-enforced rules (worktree mechanics, file-surface contract, lifecycle reconciler, lane rubric, doctor exit codes, etc.). Read only when a CLI hook surfaces an error or when triaging a v2-mode question.
-
-**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.
-
-**Sprint execution.** When a sprint is active, the orchestration playbook lives at `.claude/skills/sprint-execution/SKILL.md` — load it before dispatching any execution agent (Architect / Developer / QA / DevOps / Reporter). The skill is the canonical sprint-loop spec (Architect → QA-Red → Developer → QA-Verify → Reporter, with DevOps for merge/teardown); the always-on CLAUDE.md keeps only the halt-rules and the load-skill contract.
-
-**Skill auto-load directive.** When the SessionStart banner emits `Load skill: <name>`, invoke the Skill tool to load it before continuing. Claude Code's description-match auto-load is advisory; this rule is the contract.
-
-**Codebase is source of truth.** Wiki, memory, and `context_source` are derived caches. On conflict between cache and code, the code wins; the cache rebuilds. Before stating that a capability exists or doesn't exist, grep the code.
-
-**Duplicate check before drafting.** Before Writing any new file under `.cleargate/delivery/pending-sync/`, dispatch the `cleargate-wiki-query` subagent with the request topic. Record the result (`[[IDs]]` of related prior work, or `none found`) on a `Prior work:` line in the Brief — this is auditable evidence the check ran. Then grep `.cleargate/delivery/archive/` + `.cleargate/FLASHCARD.md` for residual hits the wiki may have missed (raw items not yet ingested). If the request names an integration, feature, or capability, also grep the source tree for existing implementations and cite findings in `## Existing Surfaces`. 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?"*) before drafting.
-
-**Halt at gates.** You halt at Gate 1 (Initiative approval) and Gate 2 (Ambiguity resolution) and wait for explicit human sign-off. You never call `cleargate_push_item` without `approved: true` (hard reject) and explicit human confirmation. Readiness gates (`cached_gate_result.pass`) are advisory by default — the push proceeds and the item body receives an `[advisory: gate_failed — <criteria>]` prefix; opt into hard-reject via `STRICT_PUSH_GATES=true` on the MCP server.
-
-**Ambiguity Gate criteria are evaluated literally.** Each `[ ]` box in a work-item's Ambiguity Gate footer must be evaluated against the literal criterion text, not against your interpretation of its intent. If a criterion is not met but you believe the human's intent is satisfied, leave the box unchecked, say so explicitly in the Brief, and ask. Do not substitute "in spirit" satisfaction for literal satisfaction. The gate exists specifically to catch the case where you are about to declare 🟢 by interpretive leap.
-
-**Brief is the universal pre-push handshake.** Every work-item template's `<instructions>` block tells you to render a Brief in chat after Writing the document — Summary / Open Questions / Edge Cases / Risks / Ambiguity. Halt for human review. When ambiguity reaches 🟢, push via `cleargate_push_item` automatically — the same approval covers Gate 1 and the push.
-
-**Boundary gates (CR-017).** `cleargate sprint init` runs the decomposition gate; `close_sprint.mjs` runs the lifecycle reconciler. Both block in v2.
-
-**Sprint close is Gate-4-class (CR-019).** Run `close_sprint.mjs` with no flags first; surface the prompt verbatim; halt. Never pass `--assume-ack` autonomously. Pre-close enforces Steps 2.7 (no leftover worktrees) + 2.8 (sprint branch merged to main) under v2; failure halts close. Post-close prints a 6-item handoff list (Step 8) summarizing commits, merge state, wiki ingest, flashcards, artifacts, and next-sprint preflight.
-
-**Drafting work items:**
-- Use the templates in `.cleargate/templates/` (`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.
-
-**Initiative Intake.** Stakeholder input arrives via two paths: (1) MCP pull — call `cleargate_pull_initiative` with the remote ID; the tool writes `pending-sync/INITIATIVE-NNN_*.md` automatically; read the result and present a Brief. (2) Manual paste — human pastes the text; triage it, write `pending-sync/INITIATIVE-NNN_*.md` using `templates/initiative.md`, present a Brief. In both cases, after Gate 1 the file moves to `archive/` stamped with `triaged_at:` and `spawned_items:`.
-
-**State-aware surface.** At session start, `cleargate doctor --session-start` (invoked by the SessionStart hook) emits one banner line before any other output: `ClearGate state: pre-member — local planning enabled, sync requires join.` OR `ClearGate state: member (project: <project_id>) — full surface enabled.` In **pre-member** state (no valid join token on disk), only local-planning commands are reachable: `init`, `join`, `whoami`, `wiki *`, `gate *`, `stamp`, `doctor`, `scaffold-lint`, `sprint *`, `story *`, `state *`, `upgrade`, `uninstall`. Commands `push`, `pull`, `sync`, `sync-log`, `conflicts`, and `admin *` (except `admin login`) require membership and exit 2 with a redirect: `Run: cleargate join <invite-url>`. If the SessionStart banner says `pre-member`, do not suggest push/pull/sync to the user — instead ask for an invite URL and direct them to `cleargate join`.
-
-**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. After Writing or Editing any file under `.cleargate/delivery/**`, briefly note the ingest result if the PostToolUse hook surfaced one — one short sentence (`✅ ingested as <bucket>/<id>.md` / `⚠️ gate failed: <criterion>` / `🔴 ingest error — see .cleargate/hook-log/gate-check.log`). Do not narrate when nothing fired (skip-excluded paths). This is conversational confirmation, not retry logic.
-
-**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.
-
-**Cross-project orchestration.** When running an orchestrator from one project's repo against another project's sprint tree, export `ORCHESTRATOR_PROJECT_DIR=/absolute/path/to/target/repo` in the shell before launching the session. Overrides `CLAUDE_PROJECT_DIR`; sentinel + ledger writes route into the target's `.cleargate/sprint-runs/` tree. If the target has no `.cleargate/sprint-runs/.active` sentinel, writes land in the target's `_off-sprint` bucket — not the orchestrator's own repo.
-
-**Codebase / PM-Tool Boundary (EPIC-027).** `cleargate-cli/src/**` and `.claude/**` MUST NOT import any PM-tool SDK (`@linear/sdk`, `jira-client`, `azure-devops`, `@atlassian/`, `linear-sdk`, `node-jira-client`, `jira.js`). PM-tool adapters live exclusively in `mcp/src/adapters/`; PM-tool credentials are held **server-side on the MCP server**, never in `cleargate-cli` or `.claude/` (today a single `LINEAR_API_KEY` env var; per-project credential rows are roadmap). The adapter surface is **pull-only** today (`pullItem`/`listUpdates`/`pullComments`/`detectNewItems`); `cleargate push` lands work items in the MCP server's store and does **not** write out to the PM tool. The type-and-payload contract (open-type validator, KNOWN_TYPES, RESERVED_PAYLOAD_KEYS, `payload.origin`, `cleargate_id` formats, L1 errorCode + L2 warningCode taxonomies) is fully documented in `.cleargate/knowledge/cleargate-protocol.md` §Type & Payload Contract and §Codebase/PM-Tool Boundary. CI enforcement: `npm run check:no-pm-sdk` (exits non-zero on any forbidden import). Target repos that ran `cleargate init` before SPRINT-27 should re-run `cleargate init` to pick up this boundary rule in their local bounded block.
-
-**Single test runner (EPIC-028).** All three packages (mcp/, cleargate-cli/, admin/) use node:test exclusively — vitest is fully eliminated as of 2026-05-18. File naming: `*.node.test.ts`. Run via `tsx --test` (mcp/, cleargate-cli/) or `node --conditions browser --import tsx tests/run-tests.mjs` (admin/). The `--conditions browser` flag is required for admin/ — it enables jsdom-bootstrap via `setup-node-test.mjs`. Adding vitest back is forbidden; `check:no-vitest` pre-commit guard enforces this.
-
-**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 five-agent loop runs. It does not replace your project's build system, CI, test runner, or deployment tooling.
-
-**Guardrails for the conversational agent:**
-- Sprint close requires explicit human ack. Run close_sprint.mjs without flags first; surface the "re-run with --assume-ack" prompt verbatim and halt. Never pass --assume-ack yourself — that flag is reserved for automated tests.
-
-**Doc & metadata refresh on close.** During Gate 4 ack, read `.cleargate/sprint-runs/<id>/.doc-refresh-checklist.md` (generated by `prep_doc_refresh.mjs`) and apply or punt each `- [ ]` item per the canonical list at `.cleargate/knowledge/sprint-closeout-checklist.md`. Items already marked `- [x]` indicate "no changes detected, skip."
-<!-- CLEARGATE:END -->