cleargate 0.11.4 → 0.12.0

package/dist/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/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

@@ -746,6 +746,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/CLAUDE.md

@@ -53,6 +53,8 @@ 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.
+
 **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.4",
-  "generated_at": "2026-05-05T17:48:13.929Z",
+  "cleargate_version": "0.12.0",
+  "generated_at": "2026-05-15T05:10:35.575Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
-      "sha256": "a2d11d6a7f21bce22730ba9076af9ddde44b258082e33aa99fcd57c14ad75f55",
+      "sha256": "823db34b934d080e648955326dcc3cd31899e90f62ecfa4a9344f5b473237084",
       "tier": "agent",
       "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": "b42018973ec6f02fc5d0ddf2a7d302aa0ee6d127cb5140474a67cb1fb0af6b28",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false

package/dist/{whoami-W4U6DPVG.js → whoami-GQTFZHFQ.js}

@@ -6,7 +6,7 @@ import {
   getMembershipState,
   loadConfig,
   requireMcpUrl
-} from "./chunk-Q3BTSXCK.js";
+} from "./chunk-WFNLCTY5.js";
 import "./chunk-4V4QABOJ.js";
 
 // src/commands/whoami.ts
@@ -73,4 +73,4 @@ async function whoamiHandler(opts) {
 export {
   whoamiHandler
 };
-//# sourceMappingURL=whoami-W4U6DPVG.js.map
+//# sourceMappingURL=whoami-GQTFZHFQ.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleargate",
-  "version": "0.11.4",
+  "version": "0.12.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.",

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/.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/templates/cleargate-planning/.cleargate/scripts/close_sprint.mjs

@@ -746,6 +746,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/templates/cleargate-planning/CLAUDE.md

@@ -53,6 +53,8 @@ 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.
+
 **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.11.4",
-  "generated_at": "2026-05-05T17:48:13.929Z",
+  "cleargate_version": "0.12.0",
+  "generated_at": "2026-05-15T05:10:35.575Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
-      "sha256": "a2d11d6a7f21bce22730ba9076af9ddde44b258082e33aa99fcd57c14ad75f55",
+      "sha256": "823db34b934d080e648955326dcc3cd31899e90f62ecfa4a9344f5b473237084",
       "tier": "agent",
       "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": "b42018973ec6f02fc5d0ddf2a7d302aa0ee6d127cb5140474a67cb1fb0af6b28",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false