cclaw-cli 0.32.0 → 0.34.0

package/README.md

@@ -133,7 +133,7 @@ inside `/cc-ops` subcommands.
 | **`/cc <idea>`** | Classify the task, discover origin docs (`docs/prd/**`, ADRs, root `PRD.md`, …), sniff the stack, recommend a track, then start the first stage of that track. `/cc` without arguments resumes the current flow. |
 | **`/cc-next`** | The one progression primitive. Reads `flow-state.json`, checks gates + mandatory subagent delegations, and either resumes the current stage or advances to the next. `/cc-next` in a new session is how you **resume**. |
 | **`/cc-ideate`** | Repository improvement discovery. Scans for TODOs, flaky tests, oversized modules, docs drift, and recurring knowledge-store lessons; returns a ranked backlog before you commit to a specific feature. |
-| **`/cc-view`** | Read-only flow visibility. `/cc-view status` (default), `/cc-view tree`, `/cc-view diff` (baseline delta map). Never mutates state. |
+| **`/cc-view`** | Read-only flow visibility. `/cc-view status` (default) shows stage progress, mandatory delegations with their fulfillment mode (isolated / generic-dispatch / role-switch), the ship closeout substate (retro → compound → archive), and the active harness parity row. `/cc-view tree` renders the same picture as a tree with a closeout sub-branch under ship and a per-harness playbook summary. `/cc-view diff` shows stage/gate/closeout/delegation deltas since the last run. Never mutates state (except diff's snapshot baseline). |
 
 > Power-user surface: `/cc-ops` is an operational router for manual
 > overrides (rewind a stale stage, manage parallel features, re-run a
@@ -277,9 +277,8 @@ The `tdd` stage is not prose guidance. It requires:
 - optional **REFACTOR** pass with coverage preservation
 
 `/cc-next` will not advance past `tdd` until the delegation log shows the
-subagent as `completed` or explicitly `waived` (for harnesses without
-native subagent dispatch, such as Codex — see
-[Harness support](#harness-support)).
+subagent as `completed` (or, on Codex / OpenCode, role-switched with
+`evidenceRefs` — see [Harness support](#harness-support)).
 
 ---
 
@@ -320,21 +319,50 @@ to: `/cc-next` is the only command.
 
 ## Harness support
 
-cclaw is honest about which harnesses give you full automation and which
-need small manual bridges. See
-[`docs/harnesses.md`](./docs/harnesses.md) for the full matrix.
-
-| Harness | Subagent dispatch | Hook surface | Structured ask | Status |
-|---|---|---|---|---|
-| Claude Code | native | full | `AskUserQuestion` | full parity |
-| Cursor | partial | full | `AskQuestion` | parity gap: subagent dispatch |
-| OpenCode | partial | plugin | plain-text | parity gap: plugin hooks |
-| OpenAI Codex | none (waiver) | full | plain-text | parity gap: no subagent |
-
-Capability gaps are captured in `.cclaw/state/harness-gaps.json`. Where
-native dispatch is missing, cclaw emits a **structured waiver** rather
-than pretending the delegation happened. Closing these gaps is an
-ongoing kinetic effort — see the harness tracking doc above.
+cclaw is honest about what each harness can and cannot do, and it
+closes every real gap with a documented fallback — not a silent waiver.
+
+| Harness | Dispatch | Fallback | Hook surface | Structured ask | Playbook |
+|---|---|---|---|---|---|
+| Claude Code | full (named subagents) | `native` | full | `AskUserQuestion` | [`claude-playbook.md`](./src/content/harness-playbooks.ts) |
+| Cursor | generic Task dispatcher | `generic-dispatch` | full | `AskQuestion` | `cursor-playbook.md` |
+| OpenCode | plugin / in-session | `role-switch` | plugin | plain-text | `opencode-playbook.md` |
+| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | full | plain-text | `codex-playbook.md` |
+
+What the fallbacks mean:
+
+- `native` — Claude runs mandatory delegations in isolated subagent
+  workers; cclaw records them with `fulfillmentMode: "isolated"`.
+- `generic-dispatch` — Cursor has a real Task tool with a fixed
+  vocabulary of `subagent_type`s (`explore`, `generalPurpose`, …).
+  cclaw maps each named agent (planner / reviewer / test-author /
+  security-reviewer / doc-updater) onto the generic dispatcher with a
+  structured role prompt. Per-agent mapping lives in the Cursor
+  playbook.
+- `role-switch` — OpenCode and Codex lack an isolated worker primitive.
+  The agent announces the role in-session, performs the work, and
+  records a delegation row with `fulfillmentMode: "role-switch"` and at
+  least one `evidenceRef` pointing at the artifact section that
+  captures the output. Under role-switch, a `completed` row **without**
+  evidenceRefs is classified as `missingEvidence` by `cclaw doctor` and
+  blocks stage completion.
+- `waiver` — reserved. Only fires auto-waivers if every installed
+  harness declares it. Currently unused — v0.33 removed the old
+  Codex-only auto-waiver path.
+
+The full capability matrix lives in
+[`docs/harnesses.md`](./docs/harnesses.md). Per-harness playbooks are
+generated into `.cclaw/references/harnesses/` on every install and
+upgrade; stage skills cite them by path.
+
+Runtime state:
+
+- `.cclaw/state/harness-gaps.json` (schema v2) — per-harness list of
+  missing capabilities, missing hook events, the declared fallback, the
+  playbook path, and a `remediation[]` list you can act on.
+- `cclaw doctor` — asserts every installed harness has its playbook on
+  disk and surfaces the expected fulfillment mode inside the
+  `delegation:mandatory:current_stage` check.
 
 ---
 

package/dist/content/diff-command.js

@@ -7,12 +7,23 @@ function flowStatePath() {
 function snapshotPath() {
     return `${RUNTIME_ROOT}/state/flow-state.snapshot.json`;
 }
+function delegationLogPath() {
+    return `${RUNTIME_ROOT}/state/delegation-log.json`;
+}
+function retroArtifactPath() {
+    return `${RUNTIME_ROOT}/artifacts/09-retro.md`;
+}
 export function diffCommandContract() {
     return `# /cc-view diff
 
 ## Purpose
 
-Show a visual before/after diff map for flow-state progression.
+Show a visual before/after diff map for flow-state progression. Covers the core
+stage/gate transitions plus:
+
+- ship **closeout substate** transitions (\`retro_review\` → \`compound_review\` → \`ready_to_archive\`),
+- delegation **fulfillmentMode** transitions per mandatory agent,
+- appearance or removal of the retro artifact \`09-retro.md\`.
 
 ## HARD-GATE
 
@@ -21,16 +32,27 @@ Show a visual before/after diff map for flow-state progression.
 
 ## Algorithm
 
-1. Read current state from \`${flowStatePath()}\`.
-2. Read baseline from \`${snapshotPath()}\` (if missing -> create baseline from current state and stop).
-3. Compute deltas:
-   - stage transition (\`from -> to\`)
-   - completed stage additions/removals
-   - skipped stage additions/removals
-   - stale stage additions/removals
-   - current-stage gate \`passed\` and \`blocked\` changes
-4. Render a compact diff map (added \`+\`, removed \`-\`, changed \`->\`).
-5. Persist current state back to \`${snapshotPath()}\` as new baseline with \`capturedAt\`.
+1. Read current state from \`${flowStatePath()}\` (including \`closeout\`).
+2. Read current delegation log from \`${delegationLogPath()}\` (if missing treat as empty).
+3. Read baseline from \`${snapshotPath()}\` (if missing -> create baseline from
+   current state **plus** a copy of the current delegation log; report
+   \`flow diff baseline created\` and stop).
+4. Compute deltas:
+   - stage transition (\`from -> to\`),
+   - completed stage additions/removals,
+   - skipped stage additions/removals,
+   - stale stage additions/removals,
+   - current-stage gate \`passed\` and \`blocked\` changes,
+   - \`closeout.shipSubstate\` transition (\`from -> to\`),
+   - \`closeout.retroDraftedAt\` / \`retroAcceptedAt\` / \`retroSkipped\` flips,
+   - \`closeout.compoundPromoted\` / \`compoundSkipped\` flips,
+   - per-agent \`fulfillmentMode\` transitions from the baseline delegation log,
+   - appearance (\`+\`) or disappearance (\`-\`) of \`${retroArtifactPath()}\`.
+5. Render a compact diff map (added \`+\`, removed \`-\`, changed \`->\`).
+6. Persist current state back to \`${snapshotPath()}\` as new baseline with
+   \`capturedAt\` and an embedded \`delegations\` projection
+   (\`{ agent, status, fulfillmentMode }[]\`) so fulfillmentMode transitions are
+   computable on the next run.
 
 ## Diff Map Format
 
@@ -41,8 +63,18 @@ cclaw flow diff
   stale: -design
   gates(spec): +spec_contract_complete  -spec_open_questions_closed
   blocked(spec): +spec_trace_matrix_missing
+  closeout: idle -> retro_review
+  retro: +drafted (09-retro.md appeared)
+  delegations:
+    - reviewer: scheduled -> completed (mode=generic-dispatch)
+    - test-author: mode=? -> role-switch (evidenceRefs=2)
 \`\`\`
 
+- The \`closeout:\` line is omitted when \`shipSubstate\` is unchanged.
+- The \`delegations:\` block is omitted when no agent changed status or mode.
+- The \`retro:\` line is emitted only on artifact appearance/removal or on a
+  \`retroAcceptedAt\` / \`retroSkipped\` flip.
+
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${DIFF_SKILL_FOLDER}/SKILL.md**
@@ -51,7 +83,7 @@ cclaw flow diff
 export function diffCommandSkillMarkdown() {
     return `---
 name: ${DIFF_SKILL_NAME}
-description: "Compare current flow-state against saved snapshot and render gate/stage deltas."
+description: "Compare current flow-state against saved snapshot and render gate/stage/closeout/delegation deltas."
 ---
 
 # /cc-view diff
@@ -63,21 +95,35 @@ Never lose baseline visibility: render deltas before writing a new snapshot.
 ## Protocol
 
 1. Read \`${flowStatePath()}\`.
-2. Read \`${snapshotPath()}\`.
-3. If snapshot missing:
-   - write baseline snapshot from current state,
+2. Read \`${delegationLogPath()}\` (missing → treat as empty list).
+3. Read \`${snapshotPath()}\`.
+4. If snapshot missing:
+   - write baseline snapshot from current state **plus** a
+     \`delegations\` projection (\`{ agent, status, fulfillmentMode }[]\`),
    - print \`flow diff baseline created\`,
    - stop.
-4. Build deltas for stage, completed/skipped/stale sets, and current-stage gate arrays.
-5. Print a compact diff map with explicit \`+\`, \`-\`, and \`->\` markers.
-6. Write updated snapshot with:
-   - \`capturedAt\` (ISO)
-   - \`state\` (full current flow-state object)
+5. Build deltas for:
+   - stage, completed/skipped/stale sets,
+   - current-stage gate arrays (\`passed\`, \`blocked\`),
+   - \`closeout.shipSubstate\` transitions (\`from -> to\`),
+   - \`closeout.retroDraftedAt\` / \`retroAcceptedAt\` / \`retroSkipped\` flips,
+   - \`closeout.compoundPromoted\` / \`compoundSkipped\` / \`compoundCompletedAt\` flips,
+   - per-agent \`fulfillmentMode\` transitions by matching baseline delegations
+     against current delegations on \`agent\` + latest entry,
+   - appearance or removal of \`${retroArtifactPath()}\` on disk.
+6. Print a compact diff map with explicit \`+\`, \`-\`, and \`->\` markers.
+7. Write updated snapshot with:
+   - \`capturedAt\` (ISO),
+   - \`state\` (full current flow-state object),
+   - \`delegations\` projection from the current log.
 
 ## Validation
 
 - Diff output must be deterministic for identical states ("no changes").
 - Snapshot file stays valid JSON after every run.
 - Do not suppress removed values; removals are first-class evidence.
+- Closeout diff lines must use the same \`shipSubstate\` vocabulary as the
+  state machine (\`idle\` / \`retro_review\` / \`compound_review\` /
+  \`ready_to_archive\` / \`archived\`).
 `;
 }

package/dist/content/harness-playbooks.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-harness parity playbooks.
+ *
+ * cclaw's subagent contracts (planner / reviewer / security-reviewer /
+ * test-author / doc-updater) assume Claude-style isolated workers. On
+ * harnesses without that primitive, the agent has to fulfil the role via a
+ * documented fallback (generic Task dispatch, role-switch in-session, …).
+ *
+ * Each playbook is:
+ *   1. short (≤ ~150 lines markdown),
+ *   2. executable — reproducible by an agent without reading the whole repo,
+ *   3. evidence-first — always records a delegation-log entry with
+ *      `fulfillmentMode` and `evidenceRefs` so `cclaw doctor` can tell the
+ *      role was actually performed.
+ *
+ * Playbooks are materialised at
+ * `.cclaw/references/harnesses/<harness>-playbook.md` by install/sync/upgrade.
+ */
+import type { HarnessId } from "../types.js";
+export declare const HARNESS_PLAYBOOKS_DIR = "references/harnesses";
+export declare function harnessPlaybookRelativePath(harness: HarnessId): string;
+export declare function harnessPlaybookFileName(harness: HarnessId): string;
+export declare function harnessPlaybookMarkdown(harness: HarnessId): string;
+export declare function harnessPlaybooksIndexMarkdown(): string;

package/dist/content/harness-playbooks.js

@@ -0,0 +1,292 @@
+/**
+ * Per-harness parity playbooks.
+ *
+ * cclaw's subagent contracts (planner / reviewer / security-reviewer /
+ * test-author / doc-updater) assume Claude-style isolated workers. On
+ * harnesses without that primitive, the agent has to fulfil the role via a
+ * documented fallback (generic Task dispatch, role-switch in-session, …).
+ *
+ * Each playbook is:
+ *   1. short (≤ ~150 lines markdown),
+ *   2. executable — reproducible by an agent without reading the whole repo,
+ *   3. evidence-first — always records a delegation-log entry with
+ *      `fulfillmentMode` and `evidenceRefs` so `cclaw doctor` can tell the
+ *      role was actually performed.
+ *
+ * Playbooks are materialised at
+ * `.cclaw/references/harnesses/<harness>-playbook.md` by install/sync/upgrade.
+ */
+import { HARNESS_ADAPTERS } from "../harness-adapters.js";
+export const HARNESS_PLAYBOOKS_DIR = "references/harnesses";
+export function harnessPlaybookRelativePath(harness) {
+    return `${HARNESS_PLAYBOOKS_DIR}/${harness}-playbook.md`;
+}
+export function harnessPlaybookFileName(harness) {
+    return `${harness}-playbook.md`;
+}
+const CLAUDE_PLAYBOOK = `---
+harness: claude
+fallback: native
+description: "Claude Code has real isolated subagent workers with user-defined named types. No fallback required — this playbook is reference-only."
+---
+
+# Claude Code — Parity Playbook
+
+**Status: native.** Claude Code supports isolated subagent workers via the
+\`Task\` tool with user-defined \`subagent_type\` (\`planner\`, \`reviewer\`,
+\`security-reviewer\`, \`test-author\`, \`doc-updater\`). Each dispatch runs in
+its own context and produces a return message visible only to the parent
+agent.
+
+This playbook exists so the harness matrix has one reference shape; Claude
+itself has no parity gap to close.
+
+## Dispatch pattern
+
+1. Pick the \`subagent_type\` matching the cclaw agent (e.g. \`reviewer\`).
+2. Provide a specific, self-contained \`prompt\` — the subagent cannot see
+   prior assistant turns.
+3. Record a delegation entry before dispatch:
+
+   \`\`\`json
+   {
+     "stage": "review",
+     "agent": "reviewer",
+     "mode": "mandatory",
+     "status": "scheduled",
+     "fulfillmentMode": "isolated",
+     "spanId": "dspan-..."
+   }
+   \`\`\`
+
+4. After the subagent returns, update the entry to \`status: "completed"\`
+   and attach \`evidenceRefs\` pointing at the artifact section that
+   captures the subagent's output.
+
+## Verification
+
+\`cclaw doctor\` will pass the \`delegation:mandatory:current_stage\` check
+when each mandatory agent has a \`completed\` row for the active run.
+`;
+const CURSOR_PLAYBOOK = `---
+harness: cursor
+fallback: generic-dispatch
+description: "Cursor has a generic Task dispatcher with subagent_type (generalPurpose, explore, shell, …) but no user-defined named subagents. cclaw maps planner/reviewer/test-author/… onto generic dispatch with a structured role prompt."
+---
+
+# Cursor — Parity Playbook
+
+**Fallback: generic-dispatch.** Cursor's \`Task\` tool supports
+\`subagent_type\` from a fixed vocabulary (\`generalPurpose\`, \`explore\`,
+\`shell\`, \`browser-use\`, …). Real isolation, but no user-defined agent
+names. cclaw closes the gap by mapping each named cclaw agent onto the
+generic dispatcher with a strict role prompt.
+
+## Named-agent → Cursor subagent_type map
+
+| cclaw agent          | Cursor \`subagent_type\` | Readonly? | Rationale |
+|----------------------|-------------------------|-----------|-----------|
+| \`planner\`          | \`explore\`              | yes       | Pure research, no writes. |
+| \`reviewer\`         | \`explore\`              | yes       | Reads diff + context, emits findings. |
+| \`security-reviewer\`| \`explore\`              | yes       | Reads code, produces report; no fixes. |
+| \`test-author\`      | \`generalPurpose\`       | no        | Writes tests, runs them, iterates. |
+| \`doc-updater\`      | \`generalPurpose\`       | no        | Edits docs, re-runs build. |
+
+## Dispatch pattern
+
+1. Pick the mapped \`subagent_type\` from the table above.
+2. Build the \`prompt\` from the cclaw agent contract in
+   \`.cclaw/agents/<agent>.md\`, prefaced with a single line naming the
+   cclaw role (\`You are the cclaw <agent>. Follow the contract below.\`).
+3. Set \`readonly: true\` when the table says yes — Cursor enforces it.
+4. Before dispatch, append a delegation row:
+
+   \`\`\`json
+   {
+     "stage": "tdd",
+     "agent": "test-author",
+     "mode": "mandatory",
+     "status": "scheduled",
+     "fulfillmentMode": "generic-dispatch",
+     "spanId": "dspan-..."
+   }
+   \`\`\`
+
+5. After dispatch returns, transition the row to \`completed\` with
+   \`evidenceRefs\` citing the artifact anchor where the result landed.
+
+## Why not upgrade Cursor to a full tier-1?
+
+Cursor has dispatch + hooks + \`AskQuestion\`. The missing piece is
+**user-defined named subagents**. Semantically this is the difference
+between Claude's \`test-author\` (a distinct runtime worker registered by
+cclaw) and Cursor's \`generalPurpose\` worker that cclaw *asks* to act as a
+test-author. Good enough for parity; different enough to keep the labels
+honest.
+
+## Verification
+
+\`cclaw doctor\` passes when the delegation row exists with
+\`fulfillmentMode: "generic-dispatch"\` (or \`completed\` rows for the
+mandatory agents in general). No evidenceRef requirement applies here —
+Cursor dispatch is real isolation.
+`;
+const OPENCODE_PLAYBOOK = `---
+harness: opencode
+fallback: role-switch
+description: "OpenCode has plugin-based dispatch hooks but no isolated subagent worker primitive. cclaw uses an in-session role-switch with a delegation-log entry + evidenceRefs."
+---
+
+# OpenCode — Parity Playbook
+
+**Fallback: role-switch.** OpenCode exposes tool/session event hooks via a
+plugin but does not provide an isolated subagent worker. cclaw closes the
+delegation gate by role-switching inside the same session: the agent
+announces the role, performs the work against the contract, and records
+evidence.
+
+## Role-switch protocol
+
+1. Announce the role explicitly in a single message:
+
+   > Acting as cclaw **<agent>** per \`.cclaw/agents/<agent>.md\`. No other
+   > role may be assumed until the delegation row is closed.
+
+2. Execute the role's contract. Do NOT interleave other roles' work.
+3. Write the result into the stage artifact (e.g. TDD work lands in
+   \`.cclaw/artifacts/06-tdd.md\`).
+4. Append a delegation row:
+
+   \`\`\`json
+   {
+     "stage": "tdd",
+     "agent": "test-author",
+     "mode": "mandatory",
+     "status": "completed",
+     "fulfillmentMode": "role-switch",
+     "evidenceRefs": [
+       ".cclaw/artifacts/06-tdd.md#red-run",
+       ".cclaw/artifacts/06-tdd.md#green-run"
+     ],
+     "spanId": "dspan-..."
+   }
+   \`\`\`
+
+5. \`evidenceRefs\` **must** point at concrete artifact anchors — not
+   placeholder text. \`cclaw doctor\` will report \`missingEvidence\` if
+   the array is empty under a role-switch fallback.
+
+## Exception: OpenCode plugin dispatch
+
+If the project configures a plugin-based dispatch path (e.g. a tool that
+spawns a worker process), set \`fulfillmentMode: "generic-dispatch"\`
+instead of \`role-switch\` and omit the role-announce step. evidenceRefs
+remain optional but recommended.
+
+## Verification
+
+\`cclaw doctor\` passes when every mandatory agent for the active stage
+has either a \`completed\` row with evidenceRefs (role-switch) or a
+\`completed\` row under plugin dispatch.
+`;
+const CODEX_PLAYBOOK = `---
+harness: codex
+fallback: role-switch
+description: "OpenAI Codex has no subagent dispatch primitive. cclaw uses role-switch with evidenceRefs; silent auto-waiver is explicitly disabled."
+---
+
+# OpenAI Codex — Parity Playbook
+
+**Fallback: role-switch.** Codex has no subagent dispatch — neither named
+nor generic. cclaw used to silently auto-waive mandatory delegations on
+Codex; v0.33 disables that shortcut. The agent must role-switch in-session
+and record evidence, or the delegation gate blocks stage completion.
+
+## Role-switch protocol
+
+Identical to OpenCode. Key requirements:
+
+1. **Explicit announce.** Before performing the role, emit a single
+   message naming the role and citing \`.cclaw/agents/<agent>.md\`.
+2. **No role interleaving.** Do not mix, for example, reviewer and
+   test-author work into the same turn — close one delegation before
+   opening another.
+3. **EvidenceRefs are mandatory.** Under Codex's role-switch fallback a
+   \`completed\` row without \`evidenceRefs\` is treated as
+   \`missingEvidence\` by \`cclaw doctor\` and blocks the gate.
+
+## Stage-specific role maps
+
+| Stage      | Mandatory roles                  | Artifact to cite in evidenceRefs     |
+|------------|----------------------------------|--------------------------------------|
+| scope      | \`planner\`                      | \`.cclaw/artifacts/02-scope.md\`     |
+| design     | \`planner\`                      | \`.cclaw/artifacts/03-design.md\`    |
+| plan       | \`planner\`                      | \`.cclaw/artifacts/05-plan.md\`      |
+| tdd        | \`test-author\`                  | \`.cclaw/artifacts/06-tdd.md\`       |
+| review     | \`reviewer\`, \`security-reviewer\` | \`.cclaw/artifacts/07-review.md\`  |
+| ship       | \`doc-updater\`                  | \`.cclaw/artifacts/08-ship.md\`      |
+
+## Why no auto-waiver anymore?
+
+Silent auto-waiver on Codex let entire stages complete without any
+reviewer or test-author work. That defeats cclaw's hard gates. v0.33
+replaces it with an explicit role-switch obligation: the agent still gets
+a path forward, but the path is visible in the delegation log.
+
+If a team genuinely wants to skip a delegation on Codex, they must
+manually append a \`status: "waived"\` row with a one-line
+\`waiverReason\` — the same audit trail any Claude/Cursor install would
+need.
+
+## Verification
+
+\`cclaw doctor\` passes when every mandatory agent for the active stage
+has a \`completed\` row with \`fulfillmentMode: "role-switch"\` and at
+least one \`evidenceRef\`.
+`;
+const PLAYBOOK_BY_HARNESS = {
+    claude: CLAUDE_PLAYBOOK,
+    cursor: CURSOR_PLAYBOOK,
+    opencode: OPENCODE_PLAYBOOK,
+    codex: CODEX_PLAYBOOK
+};
+export function harnessPlaybookMarkdown(harness) {
+    const body = PLAYBOOK_BY_HARNESS[harness];
+    if (!body) {
+        throw new Error(`No playbook defined for harness "${harness}".`);
+    }
+    return body;
+}
+export function harnessPlaybooksIndexMarkdown() {
+    const rows = Object.keys(HARNESS_ADAPTERS)
+        .map((h) => {
+        const fallback = HARNESS_ADAPTERS[h].capabilities.subagentFallback;
+        return `| \`${h}\` | ${fallback} | [\`${harnessPlaybookFileName(h)}\`](./${harnessPlaybookFileName(h)}) |`;
+    })
+        .join("\n");
+    return `# Harness parity playbooks
+
+Each playbook describes the concrete pattern cclaw expects when the
+harness does not natively satisfy a mandatory delegation contract.
+
+| Harness | Fallback | Playbook |
+|---|---|---|
+${rows}
+
+## How cclaw uses these files
+
+- \`cclaw doctor\` verifies that every installed harness has its playbook
+  present under \`.cclaw/references/harnesses/\`.
+- Stage skills (TDD, review, ship) cite the active harness's playbook
+  instead of inlining the fallback pattern.
+- The \`delegation:mandatory:current_stage\` check expects
+  \`fulfillmentMode\` to match the harness's declared \`subagentFallback\`
+  (\`isolated\`, \`generic-dispatch\`, or \`role-switch\`).
+
+## When to edit
+
+Playbooks are generated by \`cclaw upgrade\`. Local edits are overwritten.
+To customise the parity pattern for a specific repository, override the
+skill that cites the playbook, not the playbook itself.
+`;
+}

package/dist/content/harnesses-doc.js

@@ -1,5 +1,6 @@
 import { HARNESS_ADAPTERS, harnessTier } from "../harness-adapters.js";
 import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./hook-events.js";
+import { HARNESS_PLAYBOOKS_DIR, harnessPlaybookFileName } from "./harness-playbooks.js";
 function harnessTitle(harness) {
     switch (harness) {
         case "claude":
@@ -25,7 +26,9 @@ export function harnessIntegrationDocMarkdown() {
         .map((harness) => {
         const adapter = HARNESS_ADAPTERS[harness];
         const tier = harnessTier(harness);
-        return `| ${harnessTitle(harness)} | \`${harness}\` | \`${tier}\` (${tierDescription(tier)}) | ${adapter.capabilities.nativeSubagentDispatch} | ${adapter.capabilities.hookSurface} | ${adapter.capabilities.structuredAsk} |`;
+        const caps = adapter.capabilities;
+        const playbook = `\`${HARNESS_PLAYBOOKS_DIR}/${harnessPlaybookFileName(harness)}\``;
+        return `| ${harnessTitle(harness)} | \`${harness}\` | \`${tier}\` (${tierDescription(tier)}) | ${caps.nativeSubagentDispatch} | ${caps.subagentFallback} | ${caps.hookSurface} | ${caps.structuredAsk} | ${playbook} |`;
     })
         .join("\n");
     const hookRows = HOOK_SEMANTIC_EVENTS.map((eventName) => {
@@ -43,10 +46,17 @@ Generated from \`src/harness-adapters.ts\` capabilities and hook event mappings.
 
 ## Capability tiers
 
-| Harness | ID | Tier | Native subagent dispatch | Hook surface | Structured ask |
-|---|---|---|---|---|---|
+| Harness | ID | Tier | Native dispatch | Fallback | Hook surface | Structured ask | Playbook |
+|---|---|---|---|---|---|---|---|
 ${capabilityRows}
 
+Fallback legend:
+
+- \`native\` — first-class named subagent dispatch (Claude).
+- \`generic-dispatch\` — generic Task dispatcher mapped to cclaw roles (Cursor).
+- \`role-switch\` — in-session role announce + delegation-log entry with evidenceRefs (OpenCode, Codex).
+- \`waiver\` — no parity path; reserved for harnesses that cannot role-switch (none shipped).
+
 ## Semantic hook event coverage
 
 | Event | Claude | Cursor | OpenCode | Codex |