cleargate 0.11.5 → 0.13.0

package/dist/templates/cleargate-planning/.cleargate/knowledge/cleargate-protocol.md

@@ -642,3 +642,141 @@ wiki:
 ```
 
 Exceeding the ceiling fails `cleargate wiki lint` (enforcement mode). Under `--suggest`, the usage percentage is reported but the check does not fail. Reference: EPIC-015.
+
+---
+
+## Type & Payload Contract
+
+Every item pushed to the MCP server (`cleargate_push_item`) must conform to the following contract. Adapter authors implementing new PM-tool integrations MUST satisfy all requirements below before the server accepts the payload.
+
+### Open-type validator
+
+`type` is validated as an open vocabulary (new types do not require a server upgrade):
+
+```
+z.string().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/)
+```
+
+Applied after lowercase-normalize. Types that fail this regex are rejected at the MCP transport layer with an L1 `TYPE_INVALID` error.
+
+### KNOWN_TYPES — advisory registry (8 entries)
+
+These 8 types have first-class gate and reporting support. Any type outside this list passes validation but triggers an L2 `TYPE_UNKNOWN` warning in the server log.
+
+| Type | Description |
+|---|---|
+| `initiative` | High-level strategic investment |
+| `epic` | Feature-level work breakdown |
+| `story` | Executable unit of work (one sprint, one commit) |
+| `bug` | Defect report + fix |
+| `cr` | Change request — scope amendment or approach change |
+| `proposal` | Stakeholder-authored item awaiting triage |
+| `sprint` | Sprint plan artifact |
+| `sprint_report` | Sprint closeout report |
+
+### RESERVED_PAYLOAD_KEYS (5 entries)
+
+The following keys are set exclusively by the MCP server or the CLI sync engine. Callers MUST NOT include them in `payload`; the server strips or rejects them on receipt.
+
+| Key | Owner | Reason |
+|---|---|---|
+| `cleargate_id` | CLI stamp engine | Must match the frontmatter `cleargate_id` — server validates; caller cannot override |
+| `pushed_by` | Server | Set from JWT `sub` → member lookup; client-supplied value is ignored |
+| `pushed_at` | Server | Set to server UTC timestamp; client-supplied value is ignored |
+| `last_synced_body_sha` | Sync engine | Conflict-detection cursor; tampering causes spurious diffs |
+| `_version` | Server | Internal optimistic-lock counter; client tampering causes 409 |
+
+### Minimum payload contract
+
+Every push MUST include:
+
+| Key | Level | Note |
+|---|---|---|
+| `cleargate_id` | **Required (L1 error if absent)** | `TYPE-NNN` or 5-digit numeric (see formats below) |
+| `type` | **Required (L1 error if absent)** | Open vocabulary, validated by regex above |
+| `title` | Recommended (L2 warning if absent) | Human-readable item title |
+| `status` | Recommended (L2 warning if absent) | From §21 status vocabulary |
+
+### `payload.origin` convention
+
+`payload.origin` identifies the surface that produced the push. Gates fire or are bypassed based on this value:
+
+| Value pattern | Gate behavior |
+|---|---|
+| `cleargate-cli` | All readiness gates run (standard path) |
+| `adapter:<vendor>` | Gates bypass — adapter is assumed to have already validated externally. Example: `adapter:linear`, `adapter:jira` |
+| `system:<service>` | Gates bypass — system-generated push (e.g. `system:reporter`, `system:wiki-ingest`) |
+| absent / null | Treated as `cleargate-cli`; gates run |
+
+### `cleargate_id` formats (2 valid forms)
+
+| Format | Pattern | Example | Used for |
+|---|---|---|---|
+| Type-prefixed | `TYPE-NNN` (TYPE = uppercase letters, NNN = 1–5 digits) | `STORY-027-05`, `EPIC-003` | All standard work items |
+| 5-digit numeric | Exactly 5 decimal digits | `00042` | Legacy PM-tool remote IDs; internal migration use only |
+
+### L1 errorCode taxonomy (7 codes)
+
+L1 errors cause the MCP tool call to return a structured error payload with shape `{ code, message, hint }` and HTTP 422 (or equivalent MCP error).
+
+| Code | Condition | Hint |
+|---|---|---|
+| `TYPE_INVALID` | `type` fails regex validation | Normalize to lowercase-kebab; max 64 chars |
+| `ID_INVALID` | `cleargate_id` does not match either valid format | Use `TYPE-NNN` or 5-digit numeric |
+| `ID_MISSING` | `cleargate_id` absent from payload | Required field — stamp it before push |
+| `TYPE_MISSING` | `type` absent from payload | Required field |
+| `RESERVED_KEY` | Payload contains a `RESERVED_PAYLOAD_KEYS` member | Remove the key; server owns it |
+| `APPROVED_GATE` | `payload.approved !== true` and `skipApprovedGate` not set | Set `approved: true` after human sign-off |
+| `PROJECT_NOT_FOUND` | JWT `project_id` claim has no matching project row | Re-join with a valid invite URL |
+
+### L2 warningCode taxonomy (3 codes)
+
+L2 warnings are non-blocking. The push succeeds, but the server appends `[advisory: <code>]` to the item body and logs the warning.
+
+| Code | Condition | Field |
+|---|---|---|
+| `TITLE_MISSING` | `title` absent or empty | `title` |
+| `STATUS_MISSING` | `status` absent or not in §21 vocabulary | `status` |
+| `TYPE_UNKNOWN` | `type` is not in `KNOWN_TYPES` advisory registry | `type` |
+
+---
+
+## Codebase / PM-Tool Boundary
+
+**Rule:** `cleargate-cli/src/**` and `.claude/**` MUST NOT import any PM-tool SDK. PM-tool adapters live exclusively in `mcp/src/adapters/`. Credentials and connection config live in admin DB rows, configured via the admin console UI.
+
+### Rationale
+
+ClearGate must remain PM-tool-agnostic at the CLI and agent-definition layer so that:
+1. The CLI can be installed in any repo regardless of which PM tool the team uses.
+2. Agent prompts (`.claude/**`) do not hard-code vendor assumptions.
+3. A new PM-tool adapter can be added by dropping a file in `mcp/src/adapters/` without touching `cleargate-cli/` or `.claude/`.
+
+### Forbidden import patterns
+
+Any `import` or `require` statement in `cleargate-cli/src/**/*.ts` or `.claude/**/*.{ts,sh,md}` that references the following patterns fails CI:
+
+| Pattern | PM tool |
+|---|---|
+| `@linear/sdk` | Linear |
+| `linear-sdk` | Linear (alt package) |
+| `jira-client` | Jira |
+| `node-jira-client` | Jira (alt package) |
+| `jira.js` | Jira (alt package) |
+| `azure-devops` | Azure DevOps |
+| `@atlassian/` | Atlassian family |
+
+### Allowed surface for PM-tool code
+
+`mcp/src/adapters/` is the only surface where PM-tool SDK imports are permitted. Each adapter file is responsible for importing its SDK, mapping ClearGate payload shapes to PM-tool API calls, and surfacing errors as structured MCP errors.
+
+### CI enforcement
+
+`scripts/ci-no-pm-sdk.mjs` scans the two forbidden surfaces and exits non-zero on any match. Run via:
+
+```
+node scripts/ci-no-pm-sdk.mjs
+npm run check:no-pm-sdk
+```
+
+Comments (lines starting with `//`, `#`, `/*`, or `*`) are excluded from the scan. The script prints `✓ no forbidden PM-SDK imports` on a clean tree.

package/dist/templates/cleargate-planning/.cleargate/scripts/close_sprint.mjs

@@ -407,6 +407,79 @@ async function main() {
     process.stdout.write('Step 2.6b skipped: CLEARGATE_SKIP_LIFECYCLE_CHECK=1 set (test seam).\n');
   }
 
+  // ── Step 2.6c: Parent (Epic/Sprint) Rollup (CR-066) ──────────────────────
+  // Runs unconditionally (not gated by CLEARGATE_SKIP_LIFECYCLE_CHECK).
+  // For each active parent in delivery/pending-sync/, checks children coverage:
+  //   auto-flip      → rewrite status: Completed atomically, log one line.
+  //   halt-partial   → collect into haltList; exit 1 after processing all.
+  //   halt-zero-children → collect into haltList; exit 1 after processing all.
+  //   no-op / skip-deferred → silent.
+  // Defensive guard: if walkActiveParents is not a function (stale dist/), skip with warning.
+
+  /**
+   * Atomic in-place status rewrite (raw-bytes regex-replace).
+   * Follows FLASHCARD 2026-04-24 #frontmatter #write-back pattern.
+   * @param {string} filePath
+   * @param {string} newStatus
+   */
+  function setFrontmatterStatusAtomic(filePath, newStatus) {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const fm = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) throw new Error(`No frontmatter in ${filePath}`);
+    const newFm = fm[1].replace(/^status:.*$/m, `status: ${newStatus}`);
+    const newRaw = raw.replace(fm[1], newFm);
+    const tmp = filePath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmp, newRaw, 'utf8');
+    fs.renameSync(tmp, filePath);
+  }
+
+  process.stdout.write('Step 2.6c: rolling up parent statuses...\n');
+  try {
+    // Use __dirname-relative path so the import finds the ACTUAL built dist,
+    // not a fixture tmpdir override (CLEARGATE_REPO_ROOT may point elsewhere in tests).
+    const scriptRepoRoot26c = path.resolve(SCRIPTS_DIR, '..', '..');
+    const reconcilerMod26c = await import(
+      path.join(scriptRepoRoot26c, 'cleargate-cli', 'dist', 'lib', 'lifecycle-reconcile.js')
+    ).catch(() => null);
+
+    if (!reconcilerMod26c || typeof reconcilerMod26c.walkActiveParents !== 'function') {
+      process.stdout.write('Step 2.6c skipped: walkActiveParents not in built CLI — rebuild cleargate-cli/.\n');
+    } else {
+      // Delivery paths come from REPO_ROOT (may be fixture tmpdir in tests)
+      const deliveryRoot26c = path.join(REPO_ROOT, '.cleargate', 'delivery');
+      const archiveRoot26c = path.join(deliveryRoot26c, 'archive');
+      const results26c = await reconcilerMod26c.walkActiveParents({
+        deliveryRoot: deliveryRoot26c,
+        archiveRoot: archiveRoot26c,
+      });
+      const flips26c = results26c.filter((r) => r.verdict === 'auto-flip');
+      const halts26c = results26c.filter(
+        (r) => r.verdict === 'halt-partial' || r.verdict === 'halt-zero-children',
+      );
+
+      for (const f of flips26c) {
+        setFrontmatterStatusAtomic(f.parent_path, 'Completed');
+        process.stdout.write(
+          `Step 2.6c: ${f.parent_id} status ${f.current_status} → Completed` +
+          ` (${f.terminal_children.length}/${f.terminal_children.length} children Completed:` +
+          ` ${f.terminal_children.join(', ')})\n`,
+        );
+      }
+
+      if (halts26c.length > 0) {
+        process.stderr.write(`Step 2.6c HALT: ${halts26c.length} parent(s) require manual ack:\n`);
+        for (const h of halts26c) {
+          process.stderr.write(`  - [${h.verdict}] ${h.halt_reason}\n`);
+        }
+        process.exit(1);
+      }
+
+      process.stdout.write(`Step 2.6c passed: ${flips26c.length} parent(s) auto-flipped; no halts.\n`);
+    }
+  } catch (e26c) {
+    process.stderr.write(`Step 2.6c warning: parent rollup unavailable: ${e26c.message}\n`);
+  }
+
   // ── Step 2.7: Worktree-Closed Check (CR-022 M1) ──────────────────────────
   // Block close if any .worktrees/STORY-* path is present.
   // v2 enforcing (exit 1); v1 advisory (warn + continue).
@@ -746,6 +819,95 @@ async function main() {
     process.stderr.write('Run `cleargate sync work-items` manually to retry.\n');
   }
 
+  // ── Step 7.4: MCP push of sprint plan + report ───────────────────────────────
+  // CR-064: mcp push sprint plan + report
+  // Runs after Step 7 (work-item sync) and BEFORE Step 7.5 (CR-063 wiki ingest).
+  // Per SDR-locked ordering: MCP push first, wiki ingest second (CR-064 §0.5 Q4 accepted).
+  // Non-fatal on failure: sprint stays Completed. MCP push can be retried manually.
+  process.stdout.write('Step 7.4: pushing sprint plan + report to MCP...\n');
+  try {
+    const cliBin74 = path.join(REPO_ROOT, 'cleargate-cli', 'dist', 'cli.js');
+    if (fs.existsSync(cliBin74)) {
+      // Resolve sprint plan path: prefer archive/, fall back to pending-sync/
+      const deliveryBase = path.join(REPO_ROOT, '.cleargate', 'delivery');
+      const archiveDir = path.join(deliveryBase, 'archive');
+      const pendingDir = path.join(deliveryBase, 'pending-sync');
+      let planPath = null;
+      for (const dir of [archiveDir, pendingDir]) {
+        if (!fs.existsSync(dir)) continue;
+        const match = fs.readdirSync(dir).find(
+          (f) => f.startsWith(sprintId + '_') && f.endsWith('.md'),
+        );
+        if (match) { planPath = path.join(dir, match); break; }
+      }
+      if (planPath && fs.existsSync(planPath)) {
+        try {
+          execSync(`node ${JSON.stringify(cliBin74)} push ${JSON.stringify(planPath)}`, {
+            stdio: 'inherit',
+            env: process.env,
+            timeout: 60000,
+          });
+          process.stdout.write('Step 7.4a passed: sprint plan pushed to MCP.\n');
+        } catch (err74a) {
+          process.stderr.write(`Step 7.4a warning: sprint plan push failed: ${/** @type {Error} */ (err74a).message}\n`);
+        }
+      } else {
+        process.stdout.write('Step 7.4a skipped: sprint plan file not found.\n');
+      }
+      // Resolve sprint report path: reuses reportFile resolved via legacy-fallback in Step 4
+      if (reportFile && fs.existsSync(reportFile)) {
+        try {
+          execSync(`node ${JSON.stringify(cliBin74)} push ${JSON.stringify(reportFile)}`, {
+            stdio: 'inherit',
+            env: process.env,
+            timeout: 60000,
+          });
+          process.stdout.write('Step 7.4b passed: sprint report pushed to MCP.\n');
+        } catch (err74b) {
+          process.stderr.write(`Step 7.4b warning: sprint report push failed: ${/** @type {Error} */ (err74b).message}\n`);
+        }
+      } else {
+        process.stdout.write('Step 7.4b skipped: sprint report file not found (legacy sprint or report not yet written).\n');
+      }
+    } else {
+      process.stdout.write('Step 7.4 skipped: CLI binary not found (non-fatal).\n');
+    }
+  } catch (err) {
+    // Non-fatal — sprint stays Completed; MCP push can be retried manually
+    process.stderr.write(`Step 7.4 warning: MCP push failed: ${/** @type {Error} */ (err).message}\n`);
+    process.stderr.write('Run `cleargate push <plan-or-report-path>` manually to retry.\n');
+  }
+
+  // ── Step 7.5: wiki ingest sprint report ──────────────────────────────────
+  // CR-063: wiki ingest sprint report
+  // Runs after Step 7 (MCP sync). Non-fatal: sprint stays Completed on failure.
+  // CR-064 (Wave 3) inserts its MCP-push step at Step 7.4, immediately before this anchor.
+  process.stdout.write('Step 7.5: ingesting sprint report into wiki...\n');
+  try {
+    const cliBin = path.join(REPO_ROOT, 'cleargate-cli', 'dist', 'cli.js');
+    if (fs.existsSync(cliBin)) {
+      // Resolve report path using the same legacy-fallback rule as Step 4
+      // (SPRINT-NN_REPORT.md preferred; fall back to REPORT.md for legacy sprints)
+      const reportPath = reportFile; // reportFile is already resolved via legacy-fallback in Step 4
+      if (fs.existsSync(reportPath)) {
+        execSync(`node ${JSON.stringify(cliBin)} wiki ingest ${JSON.stringify(reportPath)}`, {
+          stdio: 'inherit',
+          env: process.env,
+          timeout: 60000,
+        });
+        process.stdout.write('Step 7.5 passed: sprint report ingested into wiki.\n');
+      } else {
+        process.stdout.write('Step 7.5 skipped: report file not found (legacy sprint or report not yet written).\n');
+      }
+    } else {
+      process.stdout.write('Step 7.5 skipped: CLI binary not found (non-fatal).\n');
+    }
+  } catch (err) {
+    // Non-fatal — sprint stays Completed; ingest can be retried manually
+    process.stderr.write(`Step 7.5 warning: wiki ingest sprint report failed: ${/** @type {Error} */ (err).message}\n`);
+    process.stderr.write('Run `cleargate wiki ingest <report-path>` manually to retry.\n');
+  }
+
   // ── Step 8: Verbose post-close handoff list ───────────────────────────────
   // Prints 6 explicit next-step items to stdout (CR-022 §3 M4).
   {

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

@@ -31,7 +31,7 @@ parent_ref: "EPIC-{ID} | STORY-{ID}"
 parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
 sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
 carry_over: false  # set true to skip lifecycle reconciliation at sprint close
-status: "Draft | Triaged | In Fix | Verified"
+status: "Draft | Triaged | In Fix | Completed"
 severity: "P0-Critical | P1-High | P2-Medium | P3-Low"
 reporter: "{name}"
 approved: false

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

@@ -31,7 +31,7 @@ parent_ref: "EPIC-{ID} | STORY-{ID}"
 parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
 sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
 carry_over: false  # set true to skip lifecycle reconciliation at sprint close
-status: "Draft | In Review | Approved"
+status: "Draft | In Review | Approved | Completed"
 approved: false
 created_at: "2026-04-17T00:00:00Z"
 updated_at: "2026-04-17T00:00:00Z"

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

@@ -36,7 +36,7 @@ epic_id: "EPIC-{ID}"
 parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
 sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
 carry_over: false  # set true to skip lifecycle reconciliation at sprint close
-status: "Draft"
+status: "Draft"  # lifecycle: Draft → Active → Completed
 ambiguity: "🔴 High"
 context_source: "PROPOSAL-{ID}.md"
 owner: "{PM/PO name}"

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

@@ -32,7 +32,7 @@ hotfix_id: "{ID}"
 parent_cleargate_id: null  # canonical cleargate-id of parent work item; null for top-level
 sprint_cleargate_id: null  # canonical cleargate-id of owning sprint; null for off-sprint items
 carry_over: false  # set true to skip lifecycle reconciliation at sprint close
-status: "Draft"
+status: "Draft"  # lifecycle: Draft → In Fix → Completed
 severity: "P2"
 originating_signal: "user-report"
 created_at: "{ISO}"

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

@@ -29,7 +29,7 @@ DO NOT output these instructions in the rendered file.
 initiative_id: "INITIATIVE-{NNN}"
 remote_id: null
 source_tool: "linear | jira | github | manual-paste"
-status: "{PM native status — e.g. Discovery, In Triage, Triaged}"
+status: "{PM native status — e.g. Discovery, In Triage, Triaged, Completed}"
 synced_at: null
 triaged_at: null
 spawned_items: []

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

@@ -46,7 +46,7 @@ template_version: 2
      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
+- **Status:** Completed | Escalated | Parking Lot | Carried Over
 - **Complexity:** L<n>
 - **Commit:** `<sha>`
 - **Bounce count:** qa=N arch=N total=N

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

@@ -59,7 +59,7 @@ 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"
+status: "Draft"  # lifecycle: Draft → In Review → Completed
 ambiguity: "🔴 High"
 context_source: "PROPOSAL-{ID}.md"
 actor: "{Persona Name}"

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

@@ -53,6 +53,10 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 
 **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/`; credentials live in admin DB rows. 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 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.11.5",
-  "generated_at": "2026-05-11T22:02:23.454Z",
+  "cleargate_version": "0.13.0",
+  "generated_at": "2026-05-18T17:11:10.027Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
-      "sha256": "a2d11d6a7f21bce22730ba9076af9ddde44b258082e33aa99fcd57c14ad75f55",
+      "sha256": "823db34b934d080e648955326dcc3cd31899e90f62ecfa4a9344f5b473237084",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -25,7 +25,7 @@
     },
     {
       "path": ".claude/agents/cleargate-wiki-lint.md",
-      "sha256": "42067fd728e64ac1ff1ace5822b8f8c3ddf1ba70fd0fbddf0e8cb19d5d699e77",
+      "sha256": "2a9212d81df9a68e167ec7a18093a73c6da0208f13685c6887d5bd832b56fb3d",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -39,7 +39,7 @@
     },
     {
       "path": ".claude/agents/developer.md",
-      "sha256": "36f75fe9f8dc8412eb22706dfd021f5db5694c81d73e0c938e701a83c0149126",
+      "sha256": "db7963778d68654f2dc96658d60433fa79305a10eec937807f2f0ed0cd05ce89",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -74,7 +74,7 @@
     },
     {
       "path": ".claude/hooks/pre-commit-surface-gate.sh",
-      "sha256": "6741422cd8ca75b45e26bd0e9cb54126ad9e933f763c9094ceba6b84794b761a",
+      "sha256": "8dd817fbe75ee53753e2fe1fc2ccd2b6efdb2b3c0b6ad3191bebd9640afdd6f8",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -165,7 +165,7 @@
     },
     {
       "path": ".cleargate/knowledge/cleargate-protocol.md",
-      "sha256": "50e999717b9c9e1c11638f3f2433f413d177ed8ddf3cffdbb20b50c8807b1fc5",
+      "sha256": "0380e74efa8aa782b77952fa68cc0171de035653e777d5c241d84c6e0414957b",
       "tier": "protocol",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -200,7 +200,7 @@
     },
     {
       "path": ".cleargate/scripts/close_sprint.mjs",
-      "sha256": "1807e5b27f1501476c9dec41cbb350c432d2894cb0727d8da0c860ad3f9181c7",
+      "sha256": "b14b65f15c5ad57a845df89c069b5417195651b7d3aa7f7f5736416d0db0b868",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -396,35 +396,35 @@
     },
     {
       "path": ".cleargate/templates/Bug.md",
-      "sha256": "570112e3a60856c891652837307fc6f296cc39acc20451f8bde62da0fe033026",
+      "sha256": "cebca344b6b820525c603444cf52626e120ebaa1ac28da099dc19c9cff39302c",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/CR.md",
-      "sha256": "ab111792dc79fd5181b44a63c76ac696fa4e456161ac44e2c4d0dc609e8dd904",
+      "sha256": "ea5acf2087808e0d52806a87a6a7f1ced7473b591857f322fab5285adc80d25a",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/epic.md",
-      "sha256": "fd3b54de89befe7c5bcef65e2fa5550fc7f371d55c8f15143ae73d84f3ae6d36",
+      "sha256": "f9cf44db19288f0756b76bc8b13a075d4089990324db6febd072f5cf93d59cd0",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/hotfix.md",
-      "sha256": "b75dd154c156e68a44ae01b85eff7ec16f54050e4fe7eb71f59e17d87c03a298",
+      "sha256": "de788497b4d224500036773f854801c056d73b08c3c0d66fdb641f17a1610bca",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/initiative.md",
-      "sha256": "28680917228e5d9887c8820193cc21bfecc6aad3bc0658e8a59087adf63551fd",
+      "sha256": "1170e595f5813c62f86212d6ca1955d84465f396c81aaf34498b8e2d4595d681",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
@@ -445,14 +445,14 @@
     },
     {
       "path": ".cleargate/templates/sprint_report.md",
-      "sha256": "84e32e956eb1e8a9c97be1c346b695df316a9e47e17402f3d6581e3ffdbc4d2d",
+      "sha256": "5914d54080f6110be5a5e905e3312811f3d0f80978121b1e15707d5be05cc5b1",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false
     },
     {
       "path": ".cleargate/templates/story.md",
-      "sha256": "56d793983614d832e84193d99ee5318c061d2f3ea4f019cefb861c026513cb31",
+      "sha256": "0badf01a080bca552a06fb64becd9b8c88fbf104e30f32667263522c3ff81051",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleargate",
-  "version": "0.11.5",
+  "version": "0.13.0",
   "private": false,
   "type": "module",
   "description": "Planning framework for Claude Code agents — sprint/epic/story protocol, five-role agent team (architect/developer/qa/devops/reporter), Karpathy-style awareness wiki.",
@@ -47,12 +47,11 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --test --test-reporter=spec 'test/**/*.node.test.ts'",
-    "test:file": "tsx --test --test-reporter=spec",
-    "test:vitest": "npm run build && vitest run",
-    "test:vitest:watch": "vitest",
-    "test:node": "tsx --test --test-reporter=spec 'test/**/*.node.test.ts'",
-    "test:node:file": "tsx --test --test-reporter=spec"
+    "test": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec 'test/**/*.node.test.ts' '!test/fixtures/**'",
+    "test:file": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec",
+    "test:node": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec 'test/**/*.node.test.ts' '!test/fixtures/**'",
+    "test:node:file": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec",
+    "check:no-vitest": "node -e \"const r=require('child_process').execSync('grep -rE \\\"\\\\b(vitest|vi\\\\.fn|vi\\\\.mock|vi\\\\.spyOn|vi\\\\.stubGlobal|vi\\\\.useFakeTimers|vi\\\\.useRealTimers|vi\\\\.advanceTimersByTime|vi\\\\.hoisted)\\\\b\\\" --include=\\\"*.ts\\\" --include=\\\"*.js\\\" --include=\\\"*.mjs\\\" --exclude-dir=test/fixtures . 2>/dev/null || true', {encoding:'utf8'}); if(r.trim()){console.error('vitest residue detected:\\\\n'+r); process.exit(1)} console.log('no vitest residue')\""
   },
   "dependencies": {
     "@napi-rs/keyring": "^1.2.0",
@@ -67,9 +66,9 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.11.10",
+    "ts-morph": "28.0.0",
     "tsup": "^8",
     "tsx": "^4.21.0",
-    "typescript": "^5.8.0",
-    "vitest": "^2.1.0"
+    "typescript": "^5.8.0"
   }
 }

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

@@ -77,19 +77,21 @@ Before a v2 sprint plan is confirmed by the human, you MUST write Sprint Plan §
 
 **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:**
+**§2 Execution Strategy — five 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.
+1. **§2.1 Phase Plan** — Group stories into parallel waves vs sequential chains. Before declaring any cross-story dependency, grep the codebase to verify the cited surface exists today vs. is created in-sprint. Story `## Existing Surfaces` bullets are advisory; the codebase is authoritative. 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.
+4. **§2.4 Lane Audit** — Per the seven-check Lane Classification rubric below; emit one row per fast-lane story with a ≤80-char rationale. Empty by default — rows added only for non-`standard` lanes. Full mechanics at "Lane Classification" section in this file.
+
+5. **§2.5 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.
+**Output:** A single markdown block (§§2.1–2.5 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.
 

package/templates/cleargate-planning/.claude/agents/cleargate-wiki-lint.md

@@ -1,6 +1,6 @@
 ---
 name: cleargate-wiki-lint
-description: Use BEFORE Gate 1 (Proposal approval) and Gate 3 (Push) to enforce wiki-vs-raw consistency. Default mode (enforcement) exits non-zero on any drift, naming the offending page; halts gate transitions. `--suggest` mode (advisory) exits 0 and prints candidate cross-refs the ingest pass missed (Karpathy discovery). Performance: O(n), one pass per page plus one index cross-check; no all-pairs comparison.
+description: "Use BEFORE Gate 1 (Proposal approval) and Gate 3 (Push) to enforce wiki-vs-raw consistency. Default mode (enforcement) exits non-zero on any drift, naming the offending page; halts gate transitions. `--suggest` mode (advisory) exits 0 and prints candidate cross-refs the ingest pass missed (Karpathy discovery). Performance: O(n), one pass per page plus one index cross-check; no all-pairs comparison."
 tools: Read, Grep, Glob, Bash
 model: sonnet
 ---

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

@@ -72,13 +72,17 @@ flashcards_flagged:
 
 ## Inner-loop test runner
 
-For inner-loop iteration during a Story, prefer **`node:test` + `node:assert/strict`** when writing **new** test files for any TypeScript package targeting Node 22+. Run them via `node --test --import tsx <file>`. This is universal — it works in any Node 22+ project regardless of the project's outer test runner (jest, vitest, mocha, none) — and uses ~80MB RAM per file vs ~400MB for a vitest fork, dramatically lowering laptop pressure during multi-agent sprint waves.
+All tests use **`node:test` + `node:assert/strict`** — this is the single, mandatory runner across all ClearGate packages (EPIC-028, 2026-05-18). vitest is fully eliminated; adding it back is forbidden and blocked by the `check:no-vitest` pre-commit guard.
 
-**Mocking pattern:** prefer constructor-injected DI seams over module-level mocks (e.g., `vi.mock(...)`, `jest.mock(...)`). Inject the dependency via the constructor or function parameter and pass a fake in tests. For function-level mocks, use `mock.fn()` / `mock.method()` from `node:test`.
+**File naming:** `*.node.test.ts` for all new test files.
 
-**Existing tests stay on the project's existing runner.** Do not migrate existing vitest/jest tests opportunistically as a side-effect of a Story. If your Story modifies an existing test, keep it on the original runner. Batch migrations belong in their own dedicated CR.
+**Run commands per package:**
+- `mcp/` and `cleargate-cli/`: `tsx --test --test-concurrency=1 --experimental-test-module-mocks 'test/**/*.node.test.ts'`
+- `admin/`: `node --conditions browser --import tsx tests/run-tests.mjs` — the `--conditions browser` flag is required; it triggers jsdom-bootstrap via `setup-node-test.mjs` for Svelte component tests.
 
-**Full-suite verification at commit-time.** Use the project's standard test command (`npm test`, etc.) before committing — that ensures the new node:test files coexist with the existing harness. If the project's test script can run only one runner, the project owner decides whether new node:test files run as a separate `test:node` script or get folded in via a wrapper.
+**Mocking pattern:** prefer constructor-injected DI seams over module-level mocks. Inject the dependency via the constructor or function parameter and pass a fake in tests. For function-level mocks, use `mock.fn()` / `mock.method()` from `node:test`. For static-import un-interceptability in admin/ (e.g. toast, clipboard), use the `__overrides__` pattern: a `__mocks__/` stub with a mutable `__overrides__` object that the test sets before each call — see `admin/TESTING.md` for full pattern description.
+
+**Full-suite verification at commit-time.** Use the project's standard test command (`npm test`, etc.) before committing.
 
 ## Script Invocation
 

package/templates/cleargate-planning/.claude/hooks/pre-commit-surface-gate.sh

@@ -23,6 +23,8 @@ else
   echo "[red-gate] BYPASS: SKIP_RED_GATE=1 set — skipping Red-test immutability check. Log bypass in sprint §4." >&2
 fi
 
+if ! npm run check:no-vitest -s --prefix mcp 2>/dev/null || ! npm run check:no-vitest -s --prefix cleargate-cli 2>/dev/null || ! npm run check:no-vitest -s --prefix admin 2>/dev/null; then exit 1; fi
+
 SCRIPT="${REPO_ROOT}/.cleargate/scripts/file_surface_diff.sh"
 if [[ ! -f "${SCRIPT}" ]]; then
   echo "[surface-gate] WARNING: file_surface_diff.sh not found — skipping" >&2