cclaw-cli 0.31.0 → 0.33.0

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/flow-state.d.ts

@@ -28,6 +28,35 @@ export interface RetroState {
     completedAt?: string;
     compoundEntries: number;
 }
+/**
+ * Ship closeout substate machine.
+ *
+ * After ship completes, cclaw auto-chains retro → compound → archive.
+ * Each step is interruptible: `/cc-next` reads `shipSubstate` and resumes
+ * from the correct step even across sessions.
+ *
+ * - `idle` — ship not complete, or closeout not yet started.
+ * - `retro_review` — 09-retro.md draft exists; awaiting user edit/accept/skip.
+ * - `compound_review` — retro accepted; compound pass awaiting execution
+ *   (or user skip).
+ * - `ready_to_archive` — retro + compound done; archive is the next
+ *   automatic step.
+ * - `archived` — archive completed in this session (transient — archive
+ *   resets flow-state so this value does not persist between runs).
+ */
+export declare const SHIP_SUBSTATES: readonly ["idle", "retro_review", "compound_review", "ready_to_archive", "archived"];
+export type ShipSubstate = (typeof SHIP_SUBSTATES)[number];
+export interface CloseoutState {
+    shipSubstate: ShipSubstate;
+    retroDraftedAt?: string;
+    retroAcceptedAt?: string;
+    retroSkipped?: boolean;
+    retroSkipReason?: string;
+    compoundCompletedAt?: string;
+    compoundSkipped?: boolean;
+    compoundPromoted: number;
+}
+export declare function createInitialCloseoutState(): CloseoutState;
 export interface FlowState {
     activeRunId: string;
     currentStage: FlowStage;
@@ -44,6 +73,8 @@ export interface FlowState {
     rewinds: RewindRecord[];
     /** Mandatory retrospective gate status before archive. */
     retro: RetroState;
+    /** Ship → retro → compound → archive substate for resumable closeout. */
+    closeout: CloseoutState;
 }
 export interface InitialFlowStateOptions {
     activeRunId?: string;

package/dist/flow-state.js

@@ -2,6 +2,41 @@ import { COMMAND_FILE_ORDER } from "./constants.js";
 import { buildTransitionRules, orderedStageSchemas, stageConditionalGateIds, stageGateIds, stageRecommendedGateIds } from "./content/stage-schema.js";
 import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
+/**
+ * Ship closeout substate machine.
+ *
+ * After ship completes, cclaw auto-chains retro → compound → archive.
+ * Each step is interruptible: `/cc-next` reads `shipSubstate` and resumes
+ * from the correct step even across sessions.
+ *
+ * - `idle` — ship not complete, or closeout not yet started.
+ * - `retro_review` — 09-retro.md draft exists; awaiting user edit/accept/skip.
+ * - `compound_review` — retro accepted; compound pass awaiting execution
+ *   (or user skip).
+ * - `ready_to_archive` — retro + compound done; archive is the next
+ *   automatic step.
+ * - `archived` — archive completed in this session (transient — archive
+ *   resets flow-state so this value does not persist between runs).
+ */
+export const SHIP_SUBSTATES = [
+    "idle",
+    "retro_review",
+    "compound_review",
+    "ready_to_archive",
+    "archived"
+];
+export function createInitialCloseoutState() {
+    return {
+        shipSubstate: "idle",
+        retroDraftedAt: undefined,
+        retroAcceptedAt: undefined,
+        retroSkipped: undefined,
+        retroSkipReason: undefined,
+        compoundCompletedAt: undefined,
+        compoundSkipped: undefined,
+        compoundPromoted: 0
+    };
+}
 export function isFlowTrack(value) {
     return typeof value === "string" && FLOW_TRACKS.includes(value);
 }
@@ -48,7 +83,8 @@ export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTra
             required: false,
             completedAt: undefined,
             compoundEntries: 0
-        }
+        },
+        closeout: createInitialCloseoutState()
     };
 }
 export function canTransition(from, to) {

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/dist/runs.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
-import { canTransition, createInitialFlowState, isFlowTrack, skippedStagesForTrack } from "./flow-state.js";
+import { canTransition, createInitialCloseoutState, createInitialFlowState, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
 import { ensureFeatureSystem, readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 export class InvalidStageTransitionError extends Error {
@@ -272,6 +272,37 @@ function sanitizeRetroState(value) {
         compoundEntries
     };
 }
+function isShipSubstate(value) {
+    return typeof value === "string" && SHIP_SUBSTATES.includes(value);
+}
+function sanitizeCloseoutState(value) {
+    const fallback = createInitialCloseoutState();
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return fallback;
+    }
+    const typed = value;
+    const shipSubstate = isShipSubstate(typed.shipSubstate) ? typed.shipSubstate : fallback.shipSubstate;
+    const retroDraftedAt = typeof typed.retroDraftedAt === "string" ? typed.retroDraftedAt : undefined;
+    const retroAcceptedAt = typeof typed.retroAcceptedAt === "string" ? typed.retroAcceptedAt : undefined;
+    const retroSkipped = typeof typed.retroSkipped === "boolean" ? typed.retroSkipped : undefined;
+    const retroSkipReason = typeof typed.retroSkipReason === "string" ? typed.retroSkipReason : undefined;
+    const compoundCompletedAt = typeof typed.compoundCompletedAt === "string" ? typed.compoundCompletedAt : undefined;
+    const compoundSkipped = typeof typed.compoundSkipped === "boolean" ? typed.compoundSkipped : undefined;
+    const promotedRaw = typed.compoundPromoted;
+    const compoundPromoted = typeof promotedRaw === "number" && Number.isFinite(promotedRaw) && promotedRaw >= 0
+        ? Math.floor(promotedRaw)
+        : 0;
+    return {
+        shipSubstate,
+        retroDraftedAt,
+        retroAcceptedAt,
+        retroSkipped,
+        retroSkipReason,
+        compoundCompletedAt,
+        compoundSkipped,
+        compoundPromoted
+    };
+}
 function coerceFlowState(parsed) {
     const track = coerceTrack(parsed.track);
     const next = createInitialFlowState("active", track);
@@ -289,7 +320,8 @@ function coerceFlowState(parsed) {
         skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
         staleStages: sanitizeStaleStages(parsed.staleStages),
         rewinds: sanitizeRewinds(parsed.rewinds),
-        retro: sanitizeRetroState(parsed.retro)
+        retro: sanitizeRetroState(parsed.retro),
+        closeout: sanitizeCloseoutState(parsed.closeout)
     };
 }
 function toArchiveDate(date = new Date()) {
@@ -536,9 +568,12 @@ export async function archiveRun(projectRoot, featureName, options = {}) {
     if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
         throw new Error("archive --skip-retro requires --retro-reason=<text>.");
     }
-    if (retroGate.required && !retroGate.completed && !skipRetro) {
+    const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
+        typeof sourceState.closeout.retroSkipReason === "string" &&
+        sourceState.closeout.retroSkipReason.trim().length > 0;
+    if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
         throw new Error("Archive blocked: retro gate is required after ship completion. " +
-            "Run /cc-ops retro and append at least one compound knowledge entry, or re-run /cc-ops archive with --skip-retro and --retro-reason.");
+            "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
     }
     if (retroGate.completed) {
         const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();

package/package.json

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