cleargate 0.2.0 → 0.3.0

package/dist/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/dist/templates/cleargate-planning/.cleargate/templates/story.md

@@ -15,6 +15,22 @@ 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.
+  • `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>
 
@@ -26,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"
@@ -42,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}
@@ -85,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/dist/templates/cleargate-planning/CLAUDE.md

@@ -24,6 +24,7 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 - 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.
@@ -35,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/dist/templates/cleargate-planning/MANIFEST.json

@@ -1,10 +1,10 @@
 {
-  "cleargate_version": "0.2.0",
-  "generated_at": "2026-04-19T16:46:17.751Z",
+  "cleargate_version": "0.3.0",
+  "generated_at": "2026-04-24T22:02:35.096Z",
   "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": "a83497454969e81015e7d0415e86a3bcf48cafb13741ed7f18b603f9e54cfb80",
+      "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,21 +95,21 @@
     },
     {
       "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
     },
     {
       "path": ".claude/skills/flashcard/SKILL.md",
-      "sha256": "56d6bf3797516ac26ada15876ef2f4cf43842b3af7300abef502a75bd177639e",
+      "sha256": "4c0fe5bb74697e1eb1f37203ff44b8e6a800f024a2f8c3fc8542aa206cd2c777",
       "tier": "skill",
       "overwrite_policy": "always",
       "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": "3e722c51f706177f08c16b56ef984090c7841102f70384bb47d5442846991fe8",
+      "sha256": "266b7e2b0526c4fe37620baf9344521e98ee5e7363661d390ef90068798f9bfe",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false

package/dist/whoami-CX7CXJD5.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import {
+  AcquireError,
+  acquireAccessToken,
+  loadConfig,
+  requireMcpUrl
+} from "./chunk-OM4FAEA7.js";
+import "./chunk-4V4QABOJ.js";
+
+// src/commands/whoami.ts
+import { Buffer } from "buffer";
+function decodeJwtPayload(jwt) {
+  const parts = jwt.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const json = Buffer.from(parts[1], "base64url").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+async function whoamiHandler(opts) {
+  const stdout = opts.stdout ?? ((s) => process.stdout.write(s));
+  const stderr = opts.stderr ?? ((s) => process.stderr.write(s));
+  const exit = opts.exit ?? ((c) => process.exit(c));
+  const cfg = loadConfig({ flags: { profile: opts.profile, mcpUrl: opts.mcpUrlFlag } });
+  let mcpUrl;
+  try {
+    mcpUrl = requireMcpUrl(cfg);
+  } catch (err) {
+    stderr(`cleargate: ${err instanceof Error ? err.message : String(err)}
+`);
+    exit(5);
+    return;
+  }
+  let accessToken;
+  try {
+    accessToken = await acquireAccessToken({
+      mcpUrl,
+      profile: opts.profile,
+      fetch: opts.fetch
+    });
+  } catch (err) {
+    if (err instanceof AcquireError) {
+      stderr(`cleargate: ${err.message}
+`);
+      exit(err.code === "transport" ? 2 : 5);
+      return;
+    }
+    stderr(`cleargate: internal error: ${err instanceof Error ? err.message : String(err)}
+`);
+    exit(99);
+    return;
+  }
+  const claims = decodeJwtPayload(accessToken);
+  if (!claims) {
+    stderr("cleargate: access token received but could not decode payload.\n");
+    exit(7);
+    return;
+  }
+  stdout(
+    [
+      `mcp_url:    ${mcpUrl}`,
+      `profile:    ${opts.profile}`,
+      `member_id:  ${claims.sub ?? "?"}`,
+      `project_id: ${claims.project_id ?? "?"}`,
+      `role:       ${claims.role ?? "?"}`,
+      `expires_at: ${typeof claims.exp === "number" ? new Date(claims.exp * 1e3).toISOString() : "?"}`,
+      ""
+    ].join("\n")
+  );
+}
+export {
+  whoamiHandler
+};
+//# sourceMappingURL=whoami-CX7CXJD5.js.map

package/dist/whoami-CX7CXJD5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/whoami.ts"],"sourcesContent":["/**\n * cleargate whoami — smoke-test command that proves the stored refresh token\n * can be exchanged for a short-lived MCP access token, decodes the JWT payload\n * (no verification — just introspection), and prints identity fields.\n *\n * This is the first command to exercise the acquireAccessToken flow end-to-end;\n * sync/pull/push will be wired in follow-up stories.\n */\nimport { Buffer } from 'node:buffer';\nimport { loadConfig, requireMcpUrl } from '../config.js';\nimport { acquireAccessToken, AcquireError } from '../auth/acquire.js';\n\nexport interface WhoamiOptions {\n  profile: string;\n  mcpUrlFlag?: string;\n  /** Test seam: replaces globalThis.fetch */\n  fetch?: typeof globalThis.fetch;\n  stdout?: (s: string) => void;\n  stderr?: (s: string) => void;\n  exit?: (code: number) => never;\n}\n\nfunction decodeJwtPayload(jwt: string): Record<string, unknown> | null {\n  const parts = jwt.split('.');\n  if (parts.length !== 3) return null;\n  try {\n    const json = Buffer.from(parts[1]!, 'base64url').toString('utf8');\n    return JSON.parse(json);\n  } catch {\n    return null;\n  }\n}\n\nexport async function whoamiHandler(opts: WhoamiOptions): Promise<void> {\n  const stdout = opts.stdout ?? ((s) => process.stdout.write(s));\n  const stderr = opts.stderr ?? ((s) => process.stderr.write(s));\n  const exit = opts.exit ?? ((c: number): never => process.exit(c));\n\n  const cfg = loadConfig({ flags: { profile: opts.profile, mcpUrl: opts.mcpUrlFlag } });\n  let mcpUrl: string;\n  try {\n    mcpUrl = requireMcpUrl(cfg);\n  } catch (err) {\n    stderr(`cleargate: ${err instanceof Error ? err.message : String(err)}\\n`);\n    exit(5);\n    return;\n  }\n\n  let accessToken: string;\n  try {\n    accessToken = await acquireAccessToken({\n      mcpUrl,\n      profile: opts.profile,\n      fetch: opts.fetch,\n    });\n  } catch (err) {\n    if (err instanceof AcquireError) {\n      stderr(`cleargate: ${err.message}\\n`);\n      exit(err.code === 'transport' ? 2 : 5);\n      return;\n    }\n    stderr(`cleargate: internal error: ${err instanceof Error ? err.message : String(err)}\\n`);\n    exit(99);\n    return;\n  }\n\n  const claims = decodeJwtPayload(accessToken);\n  if (!claims) {\n    stderr('cleargate: access token received but could not decode payload.\\n');\n    exit(7);\n    return;\n  }\n\n  stdout(\n    [\n      `mcp_url:    ${mcpUrl}`,\n      `profile:    ${opts.profile}`,\n      `member_id:  ${claims.sub ?? '?'}`,\n      `project_id: ${claims.project_id ?? '?'}`,\n      `role:       ${claims.role ?? '?'}`,\n      `expires_at: ${typeof claims.exp === 'number' ? new Date(claims.exp * 1000).toISOString() : '?'}`,\n      '',\n    ].join('\\n'),\n  );\n}\n"],"mappings":";;;;;;;;;;AAQA,SAAS,cAAc;AAcvB,SAAS,iBAAiB,KAA6C;AACrE,QAAM,QAAQ,IAAI,MAAM,GAAG;AAC3B,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,MAAI;AACF,UAAM,OAAO,OAAO,KAAK,MAAM,CAAC,GAAI,WAAW,EAAE,SAAS,MAAM;AAChE,WAAO,KAAK,MAAM,IAAI;AAAA,EACxB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,eAAsB,cAAc,MAAoC;AACtE,QAAM,SAAS,KAAK,WAAW,CAAC,MAAM,QAAQ,OAAO,MAAM,CAAC;AAC5D,QAAM,SAAS,KAAK,WAAW,CAAC,MAAM,QAAQ,OAAO,MAAM,CAAC;AAC5D,QAAM,OAAO,KAAK,SAAS,CAAC,MAAqB,QAAQ,KAAK,CAAC;AAE/D,QAAM,MAAM,WAAW,EAAE,OAAO,EAAE,SAAS,KAAK,SAAS,QAAQ,KAAK,WAAW,EAAE,CAAC;AACpF,MAAI;AACJ,MAAI;AACF,aAAS,cAAc,GAAG;AAAA,EAC5B,SAAS,KAAK;AACZ,WAAO,cAAc,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,CAAI;AACzE,SAAK,CAAC;AACN;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,kBAAc,MAAM,mBAAmB;AAAA,MACrC;AAAA,MACA,SAAS,KAAK;AAAA,MACd,OAAO,KAAK;AAAA,IACd,CAAC;AAAA,EACH,SAAS,KAAK;AACZ,QAAI,eAAe,cAAc;AAC/B,aAAO,cAAc,IAAI,OAAO;AAAA,CAAI;AACpC,WAAK,IAAI,SAAS,cAAc,IAAI,CAAC;AACrC;AAAA,IACF;AACA,WAAO,8BAA8B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,CAAI;AACzF,SAAK,EAAE;AACP;AAAA,EACF;AAEA,QAAM,SAAS,iBAAiB,WAAW;AAC3C,MAAI,CAAC,QAAQ;AACX,WAAO,kEAAkE;AACzE,SAAK,CAAC;AACN;AAAA,EACF;AAEA;AAAA,IACE;AAAA,MACE,eAAe,MAAM;AAAA,MACrB,eAAe,KAAK,OAAO;AAAA,MAC3B,eAAe,OAAO,OAAO,GAAG;AAAA,MAChC,eAAe,OAAO,cAAc,GAAG;AAAA,MACvC,eAAe,OAAO,QAAQ,GAAG;AAAA,MACjC,eAAe,OAAO,OAAO,QAAQ,WAAW,IAAI,KAAK,OAAO,MAAM,GAAI,EAAE,YAAY,IAAI,GAAG;AAAA,MAC/F;AAAA,IACF,EAAE,KAAK,IAAI;AAAA,EACb;AACF;","names":[]}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "cleargate",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "Planning framework for Claude Code agents — sprint/epic/story protocol, four-agent loop (architect/developer/qa/reporter), Karpathy-style awareness wiki.",
+  "license": "MIT",
   "bin": {
     "cleargate": "dist/cli.js"
   },
@@ -24,7 +25,8 @@
   "files": [
     "dist",
     "templates",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=24.0.0"
@@ -43,12 +45,14 @@
     "commander": "^12",
     "diff": "^5.2.2",
     "js-yaml": "^4.1.0",
+    "pg": "^8.12.0",
     "zod": "^4.3.0"
   },
   "devDependencies": {
     "@types/diff": "^5.2.3",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.0.0",
+    "@types/pg": "^8.11.10",
     "tsup": "^8",
     "tsx": "^4.21.0",
     "typescript": "^5.8.0",

package/templates/cleargate-planning/.claude/agents/architect.md

@@ -43,6 +43,78 @@ Things you will NOT decide — flag them up.
 
 5. **Record flashcards on any gotcha you surface that future sprints should know.** Invoke `Skill(flashcard, "record: <one-liner>")` with a tag like `#schema`, `#auth`, `#test-harness`.
 
+## Adjacent Implementation Check
+
+Before writing the per-story blueprint, grep merged stories in the current sprint (`git log sprint/S-XX --name-only | grep -E '^(cleargate-cli|src|\.cleargate/scripts)/'`) for exports. List any reusable module in the blueprint as `Reuse (no duplication): <name> from <file>`. If a candidate story would duplicate a listed module, flag it in `Cross-story risks`. Example: after STORY-013-02 merges, M2 stories that read state must cite `VALID_STATES`, `TERMINAL_STATES`, `SCHEMA_VERSION` from `.cleargate/scripts/constants.mjs` instead of redefining.
+
+## Blockers Triage
+
+When a Developer Agent writes a Blockers Report (`STORY-NNN-NN-dev-blockers.md` under `.cleargate/sprint-runs/<id>/reports/`), route by the populated section:
+
+| Category | Non-`N/A` section | Routing action |
+|---|---|---|
+| `test-pattern` | `## Test-Pattern` | Re-launch Developer with a fixture hint addressing the pattern. Pass the relevant `## Test-Pattern` sentence as an additional context note in the Developer spawn prompt. |
+| `spec-gap` | `## Spec-Gap` | Return to orchestrator with a user question. Do NOT re-launch Developer until the user clarifies. Escalate: paste the `## Spec-Gap` sentence verbatim in the question. |
+| `environment` | `## Environment` | Trigger a pre-gate re-run: invoke `run_script.sh pre_gate_runner.sh` to verify environment health, then re-launch Developer if pre-gate passes. |
+
+**Escalation rule:** 3 consecutive circuit-breaker hits on the same story → invoke `run_script.sh update_state.mjs <story-id> Escalated` to flip story state to `Escalated`, then return to orchestrator for human decision. Do not attempt a 4th re-launch.
+
+These rules apply under `execution_mode: v2`. Under v1 they are informational.
+
+## Sprint Design Review
+
+Before a v2 sprint plan is confirmed by the human, you MUST write Sprint Plan §2 "Execution Strategy". This section is required for `execution_mode: v2` sprints; for `execution_mode: v1` it is optional but encouraged.
+
+**Trigger:** Orchestrator invokes you with all story files for the sprint milestone AND signals "Design Review requested". You produce §2 content and return it as a markdown block for the orchestrator to insert into the sprint plan file.
+
+**§2 Execution Strategy — four required subsections:**
+
+1. **§2.1 Phase Plan** — Group stories into parallel waves vs sequential chains. Source: `parallel_eligible` field on each story's frontmatter + dependency graph from `## 3. Implementation Guide`. Explicitly state which stories can run concurrently and which must be serialized.
+
+2. **§2.2 Merge Ordering** — Grep each story's "Files to modify" list for overlap. For every file touched by more than one story, determine which story lands first (typically the one that creates the section the other amends). Produce a table: `Shared File | Stories | Order | Rationale`.
+
+3. **§2.3 Shared-Surface Warnings** — For each pair of stories that touch the same file, flag the specific risk: section collision, rename hazard, append-vs-insert conflict. One bullet per risk pair.
+
+4. **§2.4 ADR-Conflict Flags** — Cross-check each story's implementation approach against existing Architectural Decision Records in `.cleargate/knowledge/` and prior sprint decisions captured in flashcards. Flag any story that diverges from a locked decision.
+
+**V-Bounce reference:** `skills/agent-team/SKILL.md` §"Architect Sprint Design Review (Phase 2 → Phase 3 transition)" at pinned SHA `2b8477ab65e39e594ee8b6d8cf13a210498eaded`.
+
+**Output:** A single markdown block (§§2.1–2.4 as shown above) ready for insertion into the sprint plan. Not a separate file. The orchestrator writes it into the plan.
+
+These rules apply under `execution_mode: v2`. Under v1 the Design Review is informational.
+
+## Protocol Numbering Resolver
+
+Before writing per-story blueprints that reference a new `cleargate-protocol.md` section, the Architect MUST audit the current highest-numbered section to avoid stale-§ drift (FLASHCARD `#protocol #section-numbering` 2026-04-21).
+
+**Step 1 — find the current max §:**
+
+```bash
+grep -n "^## [0-9]" .cleargate/knowledge/cleargate-protocol.md | sort -n -k2 | tail -1
+```
+
+This prints the last numbered heading. Extract the section number from the output (e.g. `842:## 20. File-Surface Contract (v2)` → max = **20**).
+
+**Step 2 — emit §(max+1) for any new append:**
+
+The next free section number is always `max + 1`. Never reuse an existing number, even if a section was removed.
+
+**Step 3 — rewrite stale references in story prose:**
+
+For each story in the milestone, grep the story file for `§\d+` references:
+
+```bash
+grep -oE '§[0-9]+' path/to/STORY-NNN-NN.md
+```
+
+If any cited § number is ≤ max AND the section text it describes does not match the actual heading at that number in the protocol, flag it as a stale reference. Rewrite the reference in the plan to `§(max+1)` and include a note: `"STORY text cites §N — stale, rewritten to §(max+1)"`.
+
+**Concrete example (post-SPRINT-10):**
+
+After SPRINT-10 ships, `max = 20`. A story drafted before SPRINT-10 might cite `§10` (meaning "append after §10"). That section is already occupied by `§10 Wiki Awareness Layer`. The plan must use `§21` (next free after `§20`) and note: _"STORY text cites §10 — stale, rewritten to §21"_.
+
+**Rule:** Never let a Developer emit a protocol section number that conflicts with an existing one. Audit first, emit second.
+
 ## Guardrails
 - **No production code.** You write one markdown plan file. Nothing else.
 - **No speculation.** Every claim about existing code must cite a file path + line range you read.