cclaw-cli 0.32.0 → 0.33.0

package/README.md

@@ -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/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 |

package/dist/content/subagents.js

@@ -43,14 +43,20 @@ Human input remains mandatory only at explicit approval gates (plan approval, us
 
 ### Harness routing
 
-| Harness | Delegation tool | Structured ask tool | Routing note |
-|---|---|---|---|
-| Claude | Task/delegate | AskUserQuestion | Preferred for rich multi-step delegation + explicit approvals. |
-| Cursor | Task | AskQuestion | Use option-based asks for mode/waiver decisions; keep subagent payloads concise. |
-| Codex | Task (if available) | None native | Use numbered choices in chat for approvals; keep prompts fully self-contained. |
-| OpenCode | Task (if available) | None native | Log delegation outcomes in artifacts/state explicitly; do not assume built-in ask workflows. |
-
-If delegation tooling is unavailable in the active harness, run the same controller protocol in-thread and record a delegation waiver with reason \`harness_limitation\`.
+| Harness | Fallback | Delegation tool | Structured ask | Parity playbook |
+|---|---|---|---|---|
+| Claude | \`native\` | Task (named subagent_type) | AskUserQuestion | \`.cclaw/references/harnesses/claude-playbook.md\` |
+| Cursor | \`generic-dispatch\` | Task (generic subagent_type: explore/generalPurpose/…) | AskQuestion | \`.cclaw/references/harnesses/cursor-playbook.md\` |
+| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | plain-text options | \`.cclaw/references/harnesses/opencode-playbook.md\` |
+| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | plain-text options | \`.cclaw/references/harnesses/codex-playbook.md\` |
+
+**Dispatch rules driven by \`subagentFallback\`:**
+
+- \`native\` — use the harness's own named subagent primitive; delegation entry uses \`fulfillmentMode: "isolated"\`.
+- \`generic-dispatch\` — map each cclaw agent onto the generic dispatcher via the harness playbook; delegation entry uses \`fulfillmentMode: "generic-dispatch"\`.
+- \`role-switch\` — announce the role in-session, perform the work, append a delegation row with \`fulfillmentMode: "role-switch"\` and ≥1 \`evidenceRef\`. Without evidenceRefs the \`delegation:mandatory:current_stage\` check reports \`missingEvidence\` and blocks stage completion.
+
+The only time a \`harness_limitation\` waiver fires automatically is when every installed harness declares \`subagentFallback: "waiver"\`. cclaw 0.33 no longer maps Codex onto auto-waiver — the agent must role-switch with evidence.
 
 ### Model routing
 

package/dist/delegation.d.ts

@@ -1,6 +1,17 @@
+import { type SubagentFallback } from "./harness-adapters.js";
 import type { FlowStage } from "./types.js";
 export type DelegationMode = "mandatory" | "proactive" | "conditional";
 export type DelegationStatus = "scheduled" | "completed" | "failed" | "waived";
+/**
+ * How a delegation was actually fulfilled. Advisory — mirrors the harness
+ * `subagentFallback` that was in effect when the entry was recorded.
+ *
+ * - `isolated`         — Claude-style isolated subagent worker.
+ * - `generic-dispatch` — Cursor-style Task dispatch mapped to a named role.
+ * - `role-switch`      — performed in-session with explicit role announce.
+ * - `harness-waiver`   — auto-waived due to missing dispatch capability.
+ */
+export type DelegationFulfillmentMode = "isolated" | "generic-dispatch" | "role-switch" | "harness-waiver";
 export interface DelegationTokenUsage {
     input: number;
     output: number;
@@ -45,6 +56,12 @@ export type DelegationEntry = {
     retryCount?: number;
     /** Optional references to evidence anchors in artifacts. */
     evidenceRefs?: string[];
+    /**
+     * Fulfillment mode this entry was executed under. Omitted on legacy rows
+     * (treated as `"isolated"` for Claude, otherwise inferred from the active
+     * harness).
+     */
+    fulfillmentMode?: DelegationFulfillmentMode;
     /** Schema version marker for span-compatible delegation logs. */
     schemaVersion?: 1;
 };
@@ -54,10 +71,21 @@ export type DelegationLedger = {
 };
 export declare function readDelegationLedger(projectRoot: string): Promise<DelegationLedger>;
 export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
+/**
+ * Aggregate the fulfillment mode cclaw expects for the active harness set.
+ * Priority native > generic-dispatch > role-switch > waiver — the best
+ * available mode wins so mixed installs (e.g. claude + codex) inherit the
+ * strongest guarantee.
+ */
+export declare function expectedFulfillmentMode(fallbacks: SubagentFallback[]): DelegationFulfillmentMode;
 export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage): Promise<{
     satisfied: boolean;
     missing: string[];
     waived: string[];
     autoWaived: string[];
     staleIgnored: string[];
+    /** Delegation rows missing required evidence under a role-switch fallback. */
+    missingEvidence: string[];
+    /** Expected fulfillment mode for the active harness set. */
+    expectedMode: DelegationFulfillmentMode;
 }>;

package/dist/delegation.js

@@ -54,6 +54,11 @@ function isDelegationEntry(value) {
         (o.taskId === undefined || typeof o.taskId === "string") &&
         (o.waiverReason === undefined || typeof o.waiverReason === "string") &&
         (o.runId === undefined || typeof o.runId === "string") &&
+        (o.fulfillmentMode === undefined ||
+            o.fulfillmentMode === "isolated" ||
+            o.fulfillmentMode === "generic-dispatch" ||
+            o.fulfillmentMode === "role-switch" ||
+            o.fulfillmentMode === "harness-waiver") &&
         (o.conditionTrigger === undefined || typeof o.conditionTrigger === "string") &&
         (o.tokens === undefined || isDelegationTokenUsage(o.tokens)) &&
         retryOk &&
@@ -128,6 +133,23 @@ export async function appendDelegation(projectRoot, entry) {
         await writeFileSafe(filePath, `${JSON.stringify(ledger, null, 2)}\n`);
     });
 }
+/**
+ * Aggregate the fulfillment mode cclaw expects for the active harness set.
+ * Priority native > generic-dispatch > role-switch > waiver — the best
+ * available mode wins so mixed installs (e.g. claude + codex) inherit the
+ * strongest guarantee.
+ */
+export function expectedFulfillmentMode(fallbacks) {
+    if (fallbacks.length === 0)
+        return "isolated";
+    if (fallbacks.some((f) => f === "native"))
+        return "isolated";
+    if (fallbacks.some((f) => f === "generic-dispatch"))
+        return "generic-dispatch";
+    if (fallbacks.some((f) => f === "role-switch"))
+        return "role-switch";
+    return "harness-waiver";
+}
 export async function checkMandatoryDelegations(projectRoot, stage) {
     const mandatory = stageSchema(stage).mandatoryDelegations;
     const { activeRunId } = await readFlowState(projectRoot);
@@ -140,15 +162,21 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
     const missing = [];
     const waived = [];
     const autoWaived = [];
+    const missingEvidence = [];
     const config = await readConfig(projectRoot).catch(() => null);
     const harnesses = config?.harnesses ?? [];
-    const nativeDelegationUnavailable = harnesses.length > 0 &&
-        harnesses.every((harness) => HARNESS_ADAPTERS[harness].capabilities.nativeSubagentDispatch === "none");
+    const fallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
+    const expectedMode = expectedFulfillmentMode(fallbacks);
+    const onlyWaiverFallback = harnesses.length > 0 && fallbacks.every((f) => f === "waiver");
     for (const agent of mandatory) {
         const rows = forRun.filter((e) => e.agent === agent);
-        const ok = rows.some((e) => e.status === "completed" || e.status === "waived");
+        const completedRows = rows.filter((e) => e.status === "completed");
+        const waivedRows = rows.filter((e) => e.status === "waived");
+        const hasCompleted = completedRows.length > 0;
+        const hasWaived = waivedRows.length > 0;
+        const ok = hasCompleted || hasWaived;
         if (!ok) {
-            if (nativeDelegationUnavailable) {
+            if (onlyWaiverFallback) {
                 const existingHarnessWaiver = rows.some((e) => e.status === "waived" && e.waiverReason === "harness_limitation");
                 if (!existingHarnessWaiver) {
                     await appendDelegation(projectRoot, {
@@ -157,6 +185,7 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
                         mode: "mandatory",
                         status: "waived",
                         waiverReason: "harness_limitation",
+                        fulfillmentMode: "harness-waiver",
                         ts: new Date().toISOString(),
                         runId: activeRunId
                     });
@@ -167,16 +196,27 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
             else {
                 missing.push(agent);
             }
+            continue;
         }
-        else if (rows.some((e) => e.status === "waived")) {
+        if (hasWaived) {
             waived.push(agent);
         }
+        // Under role-switch fallback, a `completed` row is only credible if it
+        // carries at least one evidenceRef — otherwise the agent might have
+        // claimed role-switch satisfaction without showing its work.
+        if (hasCompleted &&
+            expectedMode === "role-switch" &&
+            !completedRows.some((e) => Array.isArray(e.evidenceRefs) && e.evidenceRefs.length > 0)) {
+            missingEvidence.push(agent);
+        }
     }
     return {
-        satisfied: missing.length === 0,
+        satisfied: missing.length === 0 && missingEvidence.length === 0,
         missing,
         waived,
         autoWaived,
-        staleIgnored
+        staleIgnored,
+        missingEvidence,
+        expectedMode
     };
 }

package/dist/doctor.js

@@ -23,6 +23,7 @@ import { doctorCheckMetadata } from "./doctor-registry.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS, UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
 import { CONTEXT_MODES, DEFAULT_CONTEXT_MODE } from "./content/contexts.js";
 import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
+import { HARNESS_PLAYBOOKS_DIR, harnessPlaybookFileName } from "./content/harness-playbooks.js";
 import { validateHookDocument } from "./hook-schema.js";
 const execFileAsync = promisify(execFile);
 async function isGitRepo(projectRoot) {
@@ -375,6 +376,12 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "references", "harnesses.md")),
         details: `${RUNTIME_ROOT}/references/harnesses.md`
     });
+    const playbookDir = path.join(projectRoot, RUNTIME_ROOT, ...HARNESS_PLAYBOOKS_DIR.split("/"));
+    checks.push({
+        name: "harness_ref:playbooks_index",
+        ok: await exists(path.join(playbookDir, "README.md")),
+        details: `${RUNTIME_ROOT}/${HARNESS_PLAYBOOKS_DIR}/README.md`
+    });
     const doctorRefDir = path.join(projectRoot, RUNTIME_ROOT, "references", "doctor");
     for (const fileName of Object.keys(DOCTOR_REFERENCE_MARKDOWN)) {
         const refPath = path.join(doctorRefDir, fileName);
@@ -475,6 +482,12 @@ export async function doctorChecks(projectRoot, options = {}) {
                 details: shimPath
             });
         }
+        const playbookFile = path.join(projectRoot, RUNTIME_ROOT, ...HARNESS_PLAYBOOKS_DIR.split("/"), harnessPlaybookFileName(harness));
+        checks.push({
+            name: `harness_ref:playbook:${harness}`,
+            ok: await exists(playbookFile),
+            details: `${RUNTIME_ROOT}/${HARNESS_PLAYBOOKS_DIR}/${harnessPlaybookFileName(harness)}`
+        });
     }
     const agentsFile = path.join(projectRoot, "AGENTS.md");
     let agentsBlockOk = false;
@@ -1298,12 +1311,15 @@ export async function doctorChecks(projectRoot, options = {}) {
         details: `${RUNTIME_ROOT}/runs must exist for archived feature snapshots`
     });
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
+        ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
+        : "";
     checks.push({
         name: "delegation:mandatory:current_stage",
         ok: delegation.satisfied,
         details: delegation.satisfied
-            ? `All mandatory delegations satisfied for stage "${flowState.currentStage}"`
-            : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}`
+            ? `All mandatory delegations satisfied for stage "${flowState.currentStage}" (mode: ${delegation.expectedMode})`
+            : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}`
     });
     checks.push({
         name: "warning:delegation:waived",

package/dist/harness-adapters.d.ts

@@ -1,19 +1,58 @@
 import type { HarnessId } from "./types.js";
 export declare const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export declare const CCLAW_MARKER_END = "<!-- cclaw-end -->";
+export type SubagentFallback = 
+/** Harness has real, isolated subagent dispatch; no fallback needed. */
+"native"
+/**
+ * Harness has generic dispatch (e.g. Cursor's Task tool with
+ * `subagent_type`) but not user-defined named subagents; cclaw maps each
+ * named agent to the generic dispatcher with a structured role prompt.
+ */
+ | "generic-dispatch"
+/**
+ * No isolated dispatch — the agent performs the named subagent's role
+ * in-session with an explicit role announce + delegation-log entry
+ * carrying evidenceRefs. Accepted as `completed` in delegation checks.
+ */
+ | "role-switch"
+/**
+ * No meaningful fallback — mandatory delegations can only be waived
+ * under `waiverReason: "harness_limitation"`.
+ */
+ | "waiver";
 export interface HarnessAdapter {
     id: HarnessId;
     commandDir: string;
     capabilities: {
-        nativeSubagentDispatch: "full" | "partial" | "none";
+        /**
+         * Level of native subagent dispatch:
+         * - `full`    — isolated workers + user-defined named subagents (Claude).
+         * - `generic` — generic dispatcher (Task) without named agents (Cursor).
+         * - `partial` — plugin-based dispatch, not a first-class primitive
+         *   (OpenCode).
+         * - `none`    — no dispatch primitive at all (Codex).
+         */
+        nativeSubagentDispatch: "full" | "generic" | "partial" | "none";
         hookSurface: "full" | "plugin" | "limited" | "none";
         structuredAsk: "AskUserQuestion" | "AskQuestion" | "plain-text";
+        /**
+         * Declared fallback pattern used when the harness cannot satisfy a
+         * mandatory delegation natively. Drives `checkMandatoryDelegations`
+         * and the generated playbook per harness.
+         */
+        subagentFallback: SubagentFallback;
     };
 }
 export declare function harnessShimFileNames(): string[];
 export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
 export type HarnessTier = "tier1" | "tier2" | "tier3";
 export declare function harnessTier(harnessId: HarnessId): HarnessTier;
+/**
+ * Harness IDs ordered from best (tier1) to least-capable. Stable sort — same
+ * tier preserves declaration order.
+ */
+export declare function harnessesByTier(): HarnessId[];
 /** Removes the cclaw AGENTS.md block. */
 export declare function stripCclawBlock(content: string): string;
 export declare function removeCclawFromAgentsMd(projectRoot: string): Promise<void>;

package/dist/harness-adapters.js

@@ -54,16 +54,22 @@ export const HARNESS_ADAPTERS = {
         capabilities: {
             nativeSubagentDispatch: "full",
             hookSurface: "full",
-            structuredAsk: "AskUserQuestion"
+            structuredAsk: "AskUserQuestion",
+            subagentFallback: "native"
         }
     },
     cursor: {
         id: "cursor",
         commandDir: ".cursor/commands",
         capabilities: {
-            nativeSubagentDispatch: "partial",
+            // Cursor has a real Task tool with subagent_type (generalPurpose,
+            // explore, shell, browser-use, …) but no user-defined named
+            // subagents. cclaw maps each named agent (planner/reviewer/…) onto
+            // generic dispatch with a role prompt — see the cursor playbook.
+            nativeSubagentDispatch: "generic",
             hookSurface: "full",
-            structuredAsk: "AskQuestion"
+            structuredAsk: "AskQuestion",
+            subagentFallback: "generic-dispatch"
         }
     },
     opencode: {
@@ -72,7 +78,8 @@ export const HARNESS_ADAPTERS = {
         capabilities: {
             nativeSubagentDispatch: "partial",
             hookSurface: "plugin",
-            structuredAsk: "plain-text"
+            structuredAsk: "plain-text",
+            subagentFallback: "role-switch"
         }
     },
     codex: {
@@ -81,7 +88,8 @@ export const HARNESS_ADAPTERS = {
         capabilities: {
             nativeSubagentDispatch: "none",
             hookSurface: "full",
-            structuredAsk: "plain-text"
+            structuredAsk: "plain-text",
+            subagentFallback: "role-switch"
         }
     }
 };
@@ -94,11 +102,22 @@ export function harnessTier(harnessId) {
     }
     if (capabilities.hookSurface === "full" ||
         capabilities.hookSurface === "plugin" ||
+        capabilities.nativeSubagentDispatch === "generic" ||
         capabilities.nativeSubagentDispatch === "partial") {
         return "tier2";
     }
     return "tier3";
 }
+/**
+ * Harness IDs ordered from best (tier1) to least-capable. Stable sort — same
+ * tier preserves declaration order.
+ */
+export function harnessesByTier() {
+    return Object.keys(HARNESS_ADAPTERS).sort((a, b) => {
+        const tierOrder = { tier1: 0, tier2: 1, tier3: 2 };
+        return tierOrder[harnessTier(a)] - tierOrder[harnessTier(b)];
+    });
+}
 function agentsMdBlock() {
     return `${CCLAW_MARKER_START}
 ## Cclaw — Workflow Adapter

package/dist/install.js

@@ -37,6 +37,7 @@ import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { HARNESS_TOOL_REFS_DIR, HARNESS_TOOL_REFS_INDEX_MD, harnessToolRefMarkdown } from "./content/harness-tool-refs.js";
 import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
 import { harnessIntegrationDocMarkdown } from "./content/harnesses-doc.js";
+import { HARNESS_PLAYBOOKS_DIR, harnessPlaybookFileName, harnessPlaybookMarkdown, harnessPlaybooksIndexMarkdown } from "./content/harness-playbooks.js";
 import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./content/hook-events.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
@@ -293,6 +294,15 @@ async function writeSkills(projectRoot, config) {
         await writeFileSafe(runtimePath(projectRoot, ...doctorRefsDir, fileName), markdown);
     }
     await writeFileSafe(runtimePath(projectRoot, "references", "harnesses.md"), harnessIntegrationDocMarkdown());
+    // Per-harness parity playbooks. Generated for every supported harness
+    // regardless of which harnesses the project installed — the index always
+    // resolves, and doctor only asserts presence of the installed harnesses'
+    // playbooks (see runtime-integrity checks).
+    const playbookDirSegments = HARNESS_PLAYBOOKS_DIR.split("/");
+    await writeFileSafe(runtimePath(projectRoot, ...playbookDirSegments, "README.md"), harnessPlaybooksIndexMarkdown());
+    for (const harness of harnessIds) {
+        await writeFileSafe(runtimePath(projectRoot, ...playbookDirSegments, harnessPlaybookFileName(harness)), harnessPlaybookMarkdown(harness));
+    }
 }
 async function writeUtilityCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "learn.md"), learnCommandContract());
@@ -948,15 +958,40 @@ async function writeHarnessGapsState(projectRoot, harnesses) {
         if (capabilities.structuredAsk === "plain-text") {
             missingCapabilities.push("structuredAsk:none");
         }
+        const remediation = [];
+        switch (capabilities.subagentFallback) {
+            case "native":
+                // nothing to remediate — harness has first-class dispatch
+                break;
+            case "generic-dispatch":
+                remediation.push(`subagent dispatch → map named cclaw agents onto generic Task subagent_type per ${HARNESS_PLAYBOOKS_DIR}/${harness}-playbook.md`);
+                break;
+            case "role-switch":
+                remediation.push(`subagent dispatch → role-switch in-session with evidenceRefs per ${HARNESS_PLAYBOOKS_DIR}/${harness}-playbook.md`);
+                break;
+            case "waiver":
+                remediation.push(`subagent dispatch → record explicit harness_limitation waiver; no parity path available`);
+                break;
+        }
+        if (capabilities.structuredAsk === "plain-text") {
+            remediation.push("structured ask → fall back to a numbered plain-text list; first option is default");
+        }
+        for (const event of missingHookEvents) {
+            remediation.push(`hook event ${event} → schedule the corresponding script manually or accept reduced observability`);
+        }
         return {
             harness,
             tier: harnessTier(harness),
+            subagentFallback: capabilities.subagentFallback,
+            playbookPath: `${RUNTIME_ROOT}/${HARNESS_PLAYBOOKS_DIR}/${harness}-playbook.md`,
             missingCapabilities,
-            missingHookEvents
+            missingHookEvents,
+            remediation
         };
     });
     await writeFileSafe(runtimePath(projectRoot, "state", "harness-gaps.json"), `${JSON.stringify({
         generatedAt: new Date().toISOString(),
+        schemaVersion: 2,
         harnesses: report
     }, null, 2)}\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {