cclaw-cli 0.32.0 → 0.34.0

package/dist/content/status-command.js

@@ -22,6 +22,12 @@ function stageActivityPath() {
 function snapshotPath() {
     return `${RUNTIME_ROOT}/state/flow-state.snapshot.json`;
 }
+function harnessGapsPath() {
+    return `${RUNTIME_ROOT}/state/harness-gaps.json`;
+}
+function retroArtifactPath() {
+    return `${RUNTIME_ROOT}/artifacts/09-retro.md`;
+}
 /**
  * Command contract for /cc-view status — a read-only snapshot command.
  * Does not mutate state. Always safe to run.
@@ -34,7 +40,8 @@ export function statusCommandContract() {
 ## Purpose
 
 **Read-only visual snapshot of the cclaw run.** Shows progress bar, current stage,
-gate coverage, delegation status, stale markers, and top knowledge highlights.
+gate coverage, delegation status with fulfillmentMode, closeout substate after
+ship, harness parity fallback, stale markers, and top knowledge highlights.
 
 This command **never mutates state**. Use it at session start to orient, or at any
 time to answer "where are we?" without advancing the flow.
@@ -49,9 +56,10 @@ time to answer "where are we?" without advancing the flow.
 ## Algorithm
 
 1. Read **\`${flowPath}\`** — capture \`track\`, \`currentStage\`, \`completedStages\`,
-   \`skippedStages\`, and per-stage gate catalog.
-2. Read **\`${delegationPath}\`** — count delegated / completed / waived / pending entries
-   for the current stage's \`mandatoryDelegations\`.
+   \`skippedStages\`, \`staleStages\`, per-stage gate catalog, and **\`closeout\`**
+   (shipSubstate + retro/compound flags).
+2. Read **\`${delegationPath}\`** — for each mandatory agent of the current stage,
+   capture \`status\`, \`fulfillmentMode\`, and whether \`evidenceRefs\` are present.
 3. Read **\`${contextModePath()}\`** — surface \`activeMode\` (default if missing).
 4. Compute **time in current stage** from the most recent stage-entry signal:
    - Prefer \`${checkpointPath()}\`'s \`timestamp\` when its \`stage\` matches \`currentStage\`.
@@ -60,25 +68,37 @@ time to answer "where are we?" without advancing the flow.
    - If no signal exists, render \`(unknown)\`.
 5. Optionally read **\`${snapshotPath()}\`** to compute gate delta versus prior baseline:
    - If missing or invalid, render \`delta: (baseline unavailable; run /cc-view diff)\`.
-6. Read the top of **\`${knowledgePath}\`** — surface up to 3 most recent entries
+6. Read **\`${harnessGapsPath()}\`** (schemaVersion 2). For every installed harness
+   capture \`tier\`, \`subagentFallback\`, and \`playbookPath\` for the harness row.
+7. Read the top of **\`${knowledgePath()}\`** — surface up to 3 most recent entries
    (by trailing timestamp or source marker).
-7. Emit the visual status block described below. Do **not** load any stage skill.
+8. Detect **closeout artifacts**: check whether \`${retroArtifactPath()}\` exists on
+   disk and annotate the closeout row accordingly.
+9. Emit the visual status block described below. Do **not** load any stage skill.
 
 ## Visual markers
 
 Default UTF markers: \`✓\` passed, \`▶\` current, \`○\` pending, \`⊘\` skipped, \`⏸\` stale, \`✗\` blocked.  
 ASCII fallback (no UTF locale): \`[x]\`, \`[>]\`, \`[ ]\`, \`[-]\`, \`[=]\`, \`[!]\`.
 
+Delegation markers: \`✓\` completed, \`◎\` completed-no-evidence (role-switch
+harness; **blocks stage**), \`○\` scheduled/pending, \`⊘\` waived, \`✗\` failed.
+
 ## Status Block Format
 
 \`\`\`
 cclaw status
-  flow:   <track> · run=<runId> · feature=<feature-id>
-  stage:  <stage> (<N>/<total>) · time <Xd|XhYm|Xm|unknown> · mode <activeMode>
-  bar:    [✓ brainstorm] [✓ scope] [▶ design] [○ spec] [○ plan] [○ tdd] [○ review] [○ ship]
-  gates:  now <passed>/<required> · blocked <count> · delta <summary or baseline-unavailable>
-  delegations: [✓ <role>] [○ <role>] ...
-  stale:  <list or none>
+  flow:    <track> · run=<runId> · feature=<feature-id>
+  stage:   <stage> (<N>/<total>) · time <Xd|XhYm|Xm|unknown> · mode <activeMode>
+  bar:     [✓ brainstorm] [✓ scope] [▶ design] [○ spec] [○ plan] [○ tdd] [○ review] [○ ship]
+  gates:   now <passed>/<required> · blocked <count> · delta <summary or baseline-unavailable>
+  delegations (<expectedMode>):
+    - planner      ✓ completed  mode=<isolated|generic-dispatch|role-switch>
+    - reviewer     ○ pending
+    - test-author  ◎ missing-evidence (role-switch; add evidenceRefs)
+  closeout: <shipSubstate> · retro=<drafted|accepted|skipped|—> · compound=<N promoted|skipped|—>
+  harness: <id>=<tier>/<fallback>, ... · playbooks: <M>/<N>
+  stale:   <list or none>
   knowledge:
     - <latest entry summary>
     - <second entry summary>
@@ -86,12 +106,20 @@ cclaw status
   next: /cc-next · /cc-view tree · /cc-view diff
 \`\`\`
 
+- Omit the \`closeout:\` row when \`currentStage !== "ship"\` and \`shipSubstate === "idle"\`.
+- Omit \`delegations\` line when the current stage has zero mandatory delegations.
+- Omit \`harness\` line only when \`${harnessGapsPath()}\` is missing or invalid
+  (render \`harness: (report unavailable; run cclaw upgrade)\`).
+
 ## Anti-patterns
 
 - Inventing gate status without reading \`${flowPath}\`.
 - Reporting delegations as satisfied when the log says \`pending\`.
+- Treating a \`completed\` role-switch delegation without \`evidenceRefs\` as green
+  — it must surface as \`◎ missing-evidence\`.
 - Advancing the stage from \`/cc-view status\` — progression belongs to \`/cc-next\`.
-- Hiding stale stages; stale markers must be surfaced directly in the status line.
+- Hiding the closeout substate after ship; retro/compound/archive progress must
+  be visible so \`/cc-next\` resumes at the right step.
 
 ## Primary skill
 
@@ -106,7 +134,7 @@ export function statusCommandSkillMarkdown() {
     const delegationPath = delegationLogPath();
     return `---
 name: ${STATUS_SKILL_NAME}
-description: "Read-only visual snapshot of the cclaw flow with progress bar, gate delta, delegations, and stale markers."
+description: "Read-only visual snapshot of the cclaw flow with progress bar, gate delta, delegations (fulfillmentMode + evidence), closeout substate, and harness parity row."
 ---
 
 # /cc-view status — Flow Status Snapshot
@@ -114,7 +142,14 @@ description: "Read-only visual snapshot of the cclaw flow with progress bar, gat
 ## Overview
 
 \`/cc-view status\` is the quickest way to answer "where are we in the flow?" without
-advancing or mutating anything. Safe to run at any point.
+advancing or mutating anything. Safe to run at any point. The snapshot reflects:
+
+- progress across stages with per-stage markers,
+- gate coverage and delta vs. baseline,
+- mandatory delegations with **fulfillmentMode** (isolated / generic-dispatch /
+  role-switch / harness-waiver) and evidence gate,
+- **closeout substate** after ship (retro → compound → archive),
+- **harness parity row** (tier + fallback) for the active harness set.
 
 ## HARD-GATE
 
@@ -133,22 +168,45 @@ a read-only command. Do **not** update \`${snapshotPath()}\` here.
 5. Try reading \`${snapshotPath()}\` for gate delta:
    - If available, compare current stage \`passed\` / \`blocked\` sets against baseline.
    - If unavailable, render \`delta: (baseline unavailable; run /cc-view diff)\`.
-6. Read \`${RUNTIME_ROOT}/knowledge.jsonl\`. If missing or empty → knowledge highlights are \`(none recorded)\`. Parse each line as JSON and surface its \`trigger\`/\`action\`.
-7. For each gate in \`stageGateCatalog[currentStage].required\`:
+6. Read \`${harnessGapsPath()}\`:
+   - If \`schemaVersion === 2\`, for each entry render \`<harness>=<tier>/<subagentFallback>\`.
+   - Count existing \`playbookPath\` files on disk to print \`playbooks: <M>/<N>\`.
+   - If the file is missing or has an older schema, render
+     \`harness: (report unavailable; run cclaw upgrade)\`.
+7. Read \`${RUNTIME_ROOT}/knowledge.jsonl\`. If missing or empty → knowledge highlights are \`(none recorded)\`. Parse each line as JSON and surface its \`trigger\`/\`action\`.
+8. For each gate in \`stageGateCatalog[currentStage].required\`:
    - Satisfied if present in \`passed\` and absent from \`blocked\`.
-8. Build and print the visual status block:
-   - stage header
-   - one-line progress bar with per-stage markers
-   - gate summary + delta
-   - delegation row
-   - stale stage row
-9. Suggest the next action:
-   - If current stage has unmet gates → \`/cc-next\` to resume.
-   - If current stage is complete → \`/cc-next\` to advance (or report "Flow complete" if terminal).
+9. For each mandatory delegation of the current stage, evaluate:
+   - \`✓ completed\` when \`status === "completed"\` and (harness is not role-switch
+     **or** \`evidenceRefs.length >= 1\`).
+   - \`◎ missing-evidence\` when \`status === "completed"\`, harness declares
+     \`role-switch\`, and \`evidenceRefs\` is empty or absent.
+   - \`○ <status>\` for \`scheduled\` / pending.
+   - \`⊘ waived\` when \`status === "waived"\`.
+   - \`✗ failed\` when \`status === "failed"\`.
+10. Compute **closeout row** when \`currentStage === "ship"\` or
+    \`closeout.shipSubstate !== "idle"\`:
+    - \`shipSubstate\` verbatim,
+    - \`retro=drafted|accepted|skipped|—\` derived from \`closeout.retroDraftedAt\`,
+      \`closeout.retroAcceptedAt\`, \`closeout.retroSkipped\`,
+    - \`compound=<N promoted>|skipped|—\` from
+      \`closeout.compoundPromoted\` / \`closeout.compoundSkipped\`.
+11. Build and print the visual status block:
+    - stage header
+    - one-line progress bar with per-stage markers
+    - gate summary + delta
+    - delegation rows (per mandatory agent)
+    - closeout row (when active)
+    - harness row
+    - stale stage row
+12. Suggest the next action:
+    - If current stage has unmet gates → \`/cc-next\` to resume.
+    - If closeout substate is non-idle → \`/cc-next\` to continue the chain.
+    - If current stage is complete → \`/cc-next\` to advance (or report "Flow complete" if terminal).
 
 ## Output Guidelines
 
-- Keep output compact (≤ 30 lines) — status, not narrative.
+- Keep output compact (≤ 40 lines) — status, not narrative.
 - Report counts, not full artifact contents.
 - If any data source is missing or corrupt, say so explicitly rather than guessing.
 - Include \`/cc-view tree\` for deep structure and \`/cc-view diff\` for before/after map in the final line.
@@ -157,6 +215,10 @@ a read-only command. Do **not** update \`${snapshotPath()}\` here.
 
 - Rebuilding trace-matrix or running doctor from \`/cc-view status\` — those belong to dedicated tools.
 - Treating absence of delegation log as "all delegations complete".
+- Collapsing \`◎ missing-evidence\` into \`✓ completed\` — role-switch gaps must stay
+  visible so the stage cannot advance silently.
+- Omitting the closeout row when \`shipSubstate !== "idle"\`; it is the only signal
+  that tells the user why \`/cc-next\` is about to run retro/compound/archive.
 - Mutating state to "clean up" during a status check.
 `;
 }

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/content/tree-command.js

@@ -13,13 +13,17 @@ function artifactsPath() {
 function rewindLogPath() {
     return `${RUNTIME_ROOT}/state/rewind-log.jsonl`;
 }
+function harnessPlaybooksDir() {
+    return `${RUNTIME_ROOT}/references/harnesses`;
+}
 export function treeCommandContract() {
     return `# /cc-view tree
 
 ## Purpose
 
-Render a visual flow tree for quick orientation across stages, gates, delegations,
-stale markers, and artifact presence.
+Render a visual flow tree for quick orientation across stages, gates, delegations
+(with fulfillmentMode), ship closeout substate, stale markers, artifact presence,
+and per-harness playbook availability.
 
 ## HARD-GATE
 
@@ -30,13 +34,21 @@ stale markers, and artifact presence.
 
 1. Read \`${flowStatePath()}\`.
 2. Read \`${delegationLogPath()}\` (if missing, treat current-stage delegations as pending).
-3. Detect artifact files in \`${artifactsPath()}\`.
+3. Detect artifact files in \`${artifactsPath()}\` (\`01-brainstorm.md\` …
+   \`08-ship.md\` plus \`09-retro.md\`).
 4. Read rewind records from \`${rewindLogPath()}\` when present for stale-stage context.
-5. Render the tree using stage order from active track:
+5. Inspect \`${harnessPlaybooksDir()}\` to confirm per-harness playbooks exist
+   for the installed harness set.
+6. Render the tree using stage order from active track:
    - stage node marker: passed/current/pending/skipped/stale
    - gate summary: \`passed/required\`
-   - delegation summary for current stage
+   - delegation summary for current stage (each agent carries its
+     \`fulfillmentMode\` label)
    - artifact marker per stage (exists / stale copy / missing)
+7. When \`currentStage === "ship"\` or \`closeout.shipSubstate !== "idle"\`,
+   append a closeout sub-tree under ship with substate and retro/compound flags.
+8. Append a final \`harnesses\` branch summarising tier + fallback +
+   playbook-present for each installed harness.
 
 ## Tree Format
 
@@ -45,12 +57,31 @@ cclaw flow tree (track=<track>, run=<runId>)
 ├─ [✓] brainstorm  gates 6/6   artifact 01-brainstorm.md
 ├─ [✓] scope       gates 5/5   artifact 02-scope.md
 ├─ [▶] design      gates 2/7   artifact 03-design.md
-│  ├─ delegations: [✓] planner  [○] reviewer
+│  ├─ delegations:
+│  │   ├─ planner   ✓ completed  mode=isolated
+│  │   └─ reviewer  ○ pending
 │  └─ stale: none
 ├─ [○] spec        gates -     artifact missing
 └─ [○] plan        gates -     artifact missing
+
+closeout (shipSubstate=retro_review):
+  ├─ retro:    drafted 09-retro.md · awaiting accept/edit/skip
+  ├─ compound: —
+  └─ archive:  pending
+
+harnesses:
+  ├─ claude    tier=tier1 fallback=native           playbook ✓
+  ├─ cursor    tier=tier2 fallback=generic-dispatch playbook ✓
+  ├─ opencode  tier=tier2 fallback=role-switch      playbook ✓
+  └─ codex     tier=tier2 fallback=role-switch      playbook ✓
 \`\`\`
 
+- Closeout sub-tree is **omitted** when \`currentStage !== "ship"\` and
+  \`shipSubstate === "idle"\`.
+- Delegations sub-branch is omitted when the stage has no mandatory agents.
+- Playbook marker is \`✗ missing\` when the file under
+  \`${harnessPlaybooksDir()}/<harness>-playbook.md\` is absent.
+
 Use UTF markers by default, ASCII fallback when terminal cannot render UTF.
 
 ## Primary skill
@@ -61,7 +92,7 @@ Use UTF markers by default, ASCII fallback when terminal cannot render UTF.
 export function treeCommandSkillMarkdown() {
     return `---
 name: ${TREE_SKILL_NAME}
-description: "Render a visual flow tree for stages, gates, delegations, and artifacts."
+description: "Render a visual flow tree for stages, gates, delegations (fulfillmentMode), ship closeout substate, artifacts, and per-harness playbooks."
 ---
 
 # /cc-view tree
@@ -72,20 +103,39 @@ Do not modify state in this command. It is a pure read/render operation.
 
 ## Protocol
 
-1. Read \`${flowStatePath()}\` as source of truth.
-2. Read \`${delegationLogPath()}\` for current-stage delegation status.
-3. Inspect \`${artifactsPath()}\` for per-stage artifact presence and stale copies.
-4. Render one compact tree:
-   - stage marker: passed/current/pending/skipped/stale
-   - gates summary
-   - artifact summary
-   - delegation branch for current stage
-5. If rewind records exist in \`${rewindLogPath()}\`, include latest rewind note in footer.
+1. Read \`${flowStatePath()}\` as source of truth (including \`closeout\`).
+2. Read \`${delegationLogPath()}\` for current-stage delegation status plus
+   \`fulfillmentMode\` / \`evidenceRefs\`.
+3. Inspect \`${artifactsPath()}\` for per-stage artifact presence and stale copies,
+   and for the retro artifact \`09-retro.md\`.
+4. Inspect \`${harnessPlaybooksDir()}\` for \`<harness>-playbook.md\` files.
+5. Render one compact tree:
+   - stage marker: passed/current/pending/skipped/stale,
+   - gates summary,
+   - artifact summary,
+   - delegation branch for current stage with fulfillmentMode labels,
+6. When \`closeout.shipSubstate !== "idle"\` or \`currentStage === "ship"\`, add
+   a closeout sub-tree:
+   - \`retro:\` line derived from \`closeout.retroDraftedAt\` /
+     \`closeout.retroAcceptedAt\` / \`closeout.retroSkipped\` and artifact presence,
+   - \`compound:\` line derived from \`closeout.compoundPromoted\` /
+     \`closeout.compoundSkipped\` / \`closeout.compoundCompletedAt\`,
+   - \`archive:\` line — \`pending\` until \`shipSubstate === "ready_to_archive"\`,
+     then \`next\`; the transient \`archived\` substate surfaces only if the
+     archive step failed mid-run.
+7. Append a \`harnesses:\` branch. For each installed harness derive the tier
+   from the harness-gaps report and mark \`playbook ✓/✗ missing\` based on
+   \`${harnessPlaybooksDir()}/<harness>-playbook.md\` existence.
+8. If rewind records exist in \`${rewindLogPath()}\`, include latest rewind note in footer.
 
 ## Validation
 
 - Output must mention the active \`track\` and \`currentStage\`.
 - Exactly one stage is marked current.
 - Missing files are reported explicitly; never guessed as complete.
+- Delegation rows always carry a fulfillmentMode label (or \`mode=?\` when the
+  ledger entry is legacy and the mode is inferred).
+- Closeout sub-tree is present iff ship is reached; it cannot be omitted while
+  \`shipSubstate !== "idle"\`.
 `;
 }

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>;