cleargate 0.2.1 → 0.4.0

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

@@ -0,0 +1,175 @@
+---
+sprint_id: "SPRINT-NN"
+status: "Draft"
+generated_at: "<ISO-8601>"
+generated_by: "Reporter agent"
+template_version: 1
+---
+
+<!-- Sprint Report v2 Template — template_version: 1 -->
+<!-- Event-type vocabulary (STORY-013-05 / protocol §§16–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
+     These tokens appear verbatim in §2 CR Change Log and §3 Execution Metrics tallies. -->
+
+# SPRINT-<NN> Report: <Sprint Title>
+
+**Status:** Shipped | Partial | Blocked
+**Window:** YYYY-MM-DD to YYYY-MM-DD (N calendar days)
+**Stories:** N planned / M shipped / K carried over
+
+---
+
+## §1 What Was Delivered
+
+### User-Facing Capabilities
+<!-- One bullet per user-visible outcome, grouped by business goal. Do NOT list stories here. -->
+- <capability>
+
+### Internal / Framework Improvements
+<!-- Infrastructure, tooling, or agent-contract changes not visible to end users. -->
+- <improvement>
+
+### Carried Over
+<!-- Stories that did not reach Done/Escalated/Parking Lot. If none, state "None." -->
+- None
+
+---
+
+## §2 Story Results + CR Change Log
+
+<!-- One block per story. For bounces, list each round-trip as a CR event with the exact token.
+     CR event types: CR:bug | CR:spec-clarification | CR:scope-change | CR:approach-change
+     UR event types: UR:review-feedback | UR:bug
+     Each CR:bug and UR:bug counts toward Bug-Fix Tax (§3). CR:scope-change increments arch_bounces. -->
+
+### STORY-NNN-NN: <Title>
+- **Status:** Done | Escalated | Parking Lot | Carried Over
+- **Complexity:** L<n>
+- **Commit:** `<sha>`
+- **Bounce count:** qa=N arch=N total=N
+- **CR Change Log:**
+  | # | Event type | Description | Counter delta |
+  |---|---|---|---|
+  | 1 | CR:bug | <description> | qa_bounces +1 |
+- **UR Events:**
+  | # | Event type | Feedback | Tax impact |
+  |---|---|---|---|
+  | 1 | UR:review-feedback | <feedback> | none (enhancement) |
+
+---
+
+## §3 Execution Metrics
+
+<!-- Tallies use the locked event-type vocabulary:
+     Bug-Fix Tax = (CR:bug count + UR:bug count) / total story count × 100
+     Enhancement Tax = UR:review-feedback count / total story count × 100
+     First-pass success rate = stories with qa_bounces=0 AND arch_bounces=0 / total stories × 100
+     Token divergence: compare ledger-primary vs task-notification-tertiary; flag if delta >20% -->
+
+| Metric | Value |
+|---|---|
+| Stories planned | N |
+| Stories shipped (Done) | N |
+| Stories escalated | N |
+| Stories carried over | N |
+| Total QA bounces | N |
+| Total Arch bounces | N |
+| CR:bug events | N |
+| CR:spec-clarification events | N |
+| CR:scope-change events | N |
+| CR:approach-change events | N |
+| UR:bug events | N |
+| UR:review-feedback events | N |
+| Circuit-breaker fires: test-pattern | N |
+| Circuit-breaker fires: spec-gap | N |
+| Circuit-breaker fires: environment | N |
+| **Bug-Fix Tax** | N% |
+| **Enhancement Tax** | N% |
+| **First-pass success rate** | N% |
+| Token source: ledger-primary | N tokens |
+| Token source: story-doc-secondary | N tokens |
+| Token source: task-notification-tertiary | N tokens |
+| Token divergence (ledger vs task-notif) | N% |
+| Token divergence flag (>20%) | YES / NO |
+
+---
+
+## §4 Lessons
+
+<!-- Flashcards added during this sprint window, grouped by tag.
+     Preserve the stale-detection pass from reporter.md §5b — stale-candidate symbols
+     from each card are surfaced here for human approval. Do NOT modify FLASHCARD.md. -->
+
+### New Flashcards (Sprint Window)
+
+| Date | Tags | Lesson |
+|---|---|---|
+| YYYY-MM-DD | #tag | <lesson> |
+
+### Flashcard Audit (Stale Candidates)
+<!-- For each active card with no [S]/[R] marker, symbols extracted and grepped.
+     Candidates below have ALL extracted symbols absent from the current repo. -->
+
+| Card (date · lead-tag · lesson head) | Missing symbols | Proposed marker |
+|---|---|---|
+
+If zero candidates: No stale flashcards detected.
+
+### Supersede Candidates
+<!-- Newer cards whose lesson directly contradicts an older card's advice. -->
+
+| Newer card | Older card | Proposed marker for older |
+|---|---|---|
+
+---
+
+## §5 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. -->
+
+### Templates
+| Item | Rating | Notes |
+|---|---|---|
+| Story template completeness | Green/Yellow/Red | |
+| Sprint Plan Template usability | Green/Yellow/Red | |
+| Sprint Report template (this one) | Green/Yellow/Red | |
+
+### Handoffs
+| Item | Rating | Notes |
+|---|---|---|
+| Architect → Developer brief quality | Green/Yellow/Red | |
+| Developer → QA artifact completeness | Green/Yellow/Red | |
+| QA → Orchestrator kickback clarity | Green/Yellow/Red | |
+
+### Skills
+| Item | Rating | Notes |
+|---|---|---|
+| Flashcard gate adherence | Green/Yellow/Red | |
+| Adjacent-implementation reuse rate | Green/Yellow/Red | |
+
+### Process
+| Item | Rating | Notes |
+|---|---|---|
+| Bounce cap respected | Green/Yellow/Red | |
+| Three-surface landing compliance | Green/Yellow/Red | |
+| Circuit-breaker fires (if any) | Green/Yellow/Red | |
+
+### Tooling
+| Item | Rating | Notes |
+|---|---|---|
+| run_script.sh diagnostic coverage | Green/Yellow/Red | |
+| Token ledger completeness | Green/Yellow/Red | |
+| Token divergence finding | Green/Yellow/Red | If §3 divergence >20%: Red — ledger=N task-notif=N delta=N% |
+
+---
+
+## §6 Change Log
+
+<!-- Append one line per material revision to this report after initial generation. -->
+
+| Date | Author | Change |
+|---|---|---|
+| YYYY-MM-DD | Reporter agent | Initial generation |

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

@@ -21,10 +21,16 @@ A candidate story is too big — emit two stories instead, with consecutive IDs
   • §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.
+  Both fields are v2-only signals. Under v1 sprints they are informational; defaults apply for stories authored before SPRINT-09.
+
 Do NOT output these instructions.
 </instructions>
 
@@ -36,6 +42,8 @@ ambiguity: "🔴 High"
 context_source: "PROPOSAL-{ID}.md"
 actor: "{Persona Name}"
 complexity_label: "L2"
+parallel_eligible: "y"
+expected_bounce_exposure: "low"
 created_at: "2026-04-17T00:00:00Z"
 updated_at: "2026-04-17T00:00:00Z"
 created_at_version: "strategy-phase-pre-init"
@@ -52,6 +60,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
 ---
 
 # STORY-{EpicID}-{StoryID}: {Story Name}
@@ -95,6 +112,8 @@ Feature: {Story Name}
 
 ### 3.1 Context & Files
 
+> **v2 gate input:** under v2 execution mode, this table is a pre-commit gate input (protocol §20). 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}` |

package/templates/cleargate-planning/CLAUDE.md

@@ -36,6 +36,8 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 
 **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.
+
 **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.

package/templates/cleargate-planning/MANIFEST.json

@@ -1,10 +1,10 @@
 {
-  "cleargate_version": "0.2.1",
-  "generated_at": "2026-04-19T18:33:06.178Z",
+  "cleargate_version": "0.4.0",
+  "generated_at": "2026-04-25T11:27:01.277Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
-      "sha256": "0e0e545198cfff827ea453195414d884aec5cb5413e07dc1396820aaa2014f97",
+      "sha256": "c9424894549b270b73c1c95145b7bb8d406cadd2057c47f8e90bf74ce1f3cda7",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -32,28 +32,56 @@
     },
     {
       "path": ".claude/agents/developer.md",
-      "sha256": "bd9bcd8ce222effa248ff489939a7e37aa8e151675311fc7b374533c09ef43ee",
+      "sha256": "ea54db76bcd017526f2b48e05b167cb87251273aa5fd3da6bec3013c207c72fb",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/qa.md",
-      "sha256": "9345a4f294cbc327ecc169a51446e2321b53b14917e7880f7e7b374a28ac3751",
+      "sha256": "e753d294d6060ace626878220db02a0595126bc7baa52526e5d1576b163f04d0",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/agents/reporter.md",
-      "sha256": "a9b7e248fd1baaef7fb0c23d4ba92bc94bcd46e9261a6dabbd183477fab96359",
+      "sha256": "5819d6f932ebd25a48e6f91a2e6227726f6d4d15968622728ec22a4ed7caa622",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
+    {
+      "path": ".claude/hooks/pending-task-sentinel.sh",
+      "sha256": "8204286b19287c490cc09014b0c87e2b2686e6bd120393b7165895d215d6b49a",
+      "tier": "hook",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".claude/hooks/pre-commit-surface-gate.sh",
+      "sha256": "a58f3b3c3dbb615a14bf6e2355f5122e80a5cb1e8ef9442648324f3124723ee3",
+      "tier": "hook",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".claude/hooks/pre-commit-test-ratchet.sh",
+      "sha256": "67232d9d94817e512b2d66e020605b59e9795eb4a04005edf7ea75bf9a324848",
+      "tier": "hook",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".claude/hooks/pre-commit.sh",
+      "sha256": "90260116726bfc88191fda353d038445d5838e7cd811db67029b5555f2dbc555",
+      "tier": "hook",
+      "overwrite_policy": "always",
+      "preserve_on_uninstall": false
+    },
     {
       "path": ".claude/hooks/session-start.sh",
-      "sha256": "b851f34c8e40eb10d6dc71c8dbd29282f74afbaad7e823306a3e2a52a15fe21f",
+      "sha256": "a611286330f36e5d0bbdc5642e9409ffbfc569cc3d0b370918e973b545c50741",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -67,14 +95,14 @@
     },
     {
       "path": ".claude/hooks/token-ledger.sh",
-      "sha256": "918ae12960f2c657c7ad1b0b7bc95438a4339d220f75e4abf5259ecabe8a2ca3",
+      "sha256": "be2b2eaa02cc30387601285160d6fe1c90ea76b37ec6cae2b7c9537f66f22783",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
     },
     {
       "path": ".claude/settings.json",
-      "sha256": "1f95f5468db19ffebe75aec1c35489a26aae64eae256d246a6a88cf34581f4bb",
+      "sha256": "a6d63ac3d01592b7d2ed1af45067606d535349dc27a51740f744c2fd2592a0cb",
       "tier": "cli-config",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -95,7 +123,7 @@
     },
     {
       "path": ".cleargate/knowledge/cleargate-protocol.md",
-      "sha256": "fc67af361fbd11137404d3db1034ceb5f876cd8de0e4f90e208ef19ab89072a6",
+      "sha256": "4316444ad452e83a2c9387ad6ad96ef4e4511b1face4b30976a912c0f28866f6",
       "tier": "protocol",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -109,21 +137,21 @@
     },
     {
       "path": ".cleargate/templates/Bug.md",
-      "sha256": "9f32165a709b30bc8794ef96c6a7220ef6484b47c30fb955e1c1c8e892698bcc",
+      "sha256": "3ba6e72bd2bc01cf8d0ea06390f8ea511bef3a421a33c48de033051f844dfa0e",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/CR.md",
-      "sha256": "55ea7a8a25c6b3d37103065dd91eb11378a78a36375d274406d376f4c35af3ef",
+      "sha256": "58ea4badb03991d119f8aa8870992a8239c8df6ad198e0d9ca04a805756e4bac",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/epic.md",
-      "sha256": "1847f1e7cedd631d4ef2aaf7ef67745e88b2ff76389b04bad6fa1f1edf973442",
+      "sha256": "6c85e4c9602af657e6778af9009a67936c27e47331479d0c246cdf1242177c82",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -137,21 +165,35 @@
     },
     {
       "path": ".cleargate/templates/proposal.md",
-      "sha256": "1a0822edf6f29a1f8d34e2fab1180b33a365edd92d84b3fc191f239a751ba373",
+      "sha256": "e8055dac81ecf94d01fe610e8cdaf4fa73a2f8d9953e4db90b91a20a8c81460d",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/Sprint Plan Template.md",
-      "sha256": "6e60b697a136edb89bc19cc40caa1bec51687366b8e1b35a6554d0072736591b",
+      "sha256": "9f87539691b910193c55fb9a637975de738dda181baa7e68fc48297993389613",
+      "tier": "template",
+      "overwrite_policy": "merge-3way",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/templates/sprint_context.md",
+      "sha256": "56c8c401b56d4c654dc41a19bd524f1b8860a8006cc3cd90e784d101c3d7721a",
+      "tier": "template",
+      "overwrite_policy": "merge-3way",
+      "preserve_on_uninstall": false
+    },
+    {
+      "path": ".cleargate/templates/sprint_report.md",
+      "sha256": "5f3dfdbc7a1dde26758871b358be00d543e9669ab34ca3c7ead765ee6e182bcb",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/story.md",
-      "sha256": "6c32fcabc9332cb928ac3b8fbfe618751b0a4cb05cd0f16463c3c4e22f8a67f1",
+      "sha256": "266b7e2b0526c4fe37620baf9344521e98ee5e7363661d390ef90068798f9bfe",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false