cclaw-cli 0.31.0 → 0.33.0

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

@@ -33,7 +33,7 @@ This is the only progression command the user needs to drive the entire flow. St
 
 - **Do not** invent gate completion: use only \`${flowPath}\` plus observable evidence in repo artifacts.
 - **Do not** skip stages: advance only from \`currentStage\` to its configured successor.
-- If the flow reaches terminal ship completion, route closeout in order: **/cc-ops retro -> /cc-ops compound (optional) -> /cc-ops archive**.
+- After ship completes, the closeout chain **retro -> compound -> archive** runs automatically, driven by \`closeout.shipSubstate\`. Do not ask the user to type those commands manually — follow the substate switch in Path B below.
 
 ## Algorithm (mandatory)
 
@@ -55,9 +55,24 @@ This is the only progression command the user needs to drive the entire flow. St
 ### Path B: Current stage IS complete (all gates passed, all delegations satisfied)
 
 → If current stage's \`next\` is **\`done\`**:
-  - if \`currentStage === "ship"\` and \`retro.completedAt\` is missing -> route to \`/cc-ops retro\`,
-  - if \`currentStage === "ship"\` and \`retro.completedAt\` is present -> suggest \`/cc-ops compound\` then route to \`/cc-ops archive\`,
-  - otherwise report **"Flow complete. All stages finished."** and stop.
+
+  When \`currentStage === "ship"\`, route by **\`closeout.shipSubstate\`**:
+  - \`"idle"\` or missing -> set \`closeout.shipSubstate = "retro_review"\`, then
+    load \`${RUNTIME_ROOT}/commands/retro.md\` + \`${RUNTIME_ROOT}/skills/flow-retro/SKILL.md\`
+    and execute the retro protocol (draft + one structured accept/edit/skip ask).
+  - \`"retro_review"\` -> continue the retro protocol (re-ask the structured
+    question; the draft already exists — do not regenerate it).
+  - \`"compound_review"\` -> load \`${RUNTIME_ROOT}/commands/compound.md\` +
+    \`${RUNTIME_ROOT}/skills/flow-compound/SKILL.md\`, execute the compound
+    scan, ask user **one** structured question (apply / skip) per candidate
+    cluster or a single accept-all / skip choice, and advance substate on
+    completion or skip.
+  - \`"ready_to_archive"\` -> load \`${RUNTIME_ROOT}/commands/archive.md\` +
+    \`${RUNTIME_ROOT}/skills/flow-archive/SKILL.md\`, run archive, reset state.
+  - \`"archived"\` (transient) -> report "run archived" and stop.
+
+  Otherwise report **"Flow complete. All stages finished."** and stop.
+
 → Otherwise: load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<nextStage>.md\`** for the successor stage. Execute that stage's protocol.
 
 ### Track-aware successor resolution
@@ -74,6 +89,9 @@ This is the only progression command the user needs to drive the entire flow. St
 \`/cc-next\` in a **new session** = resume from where you left off:
 - Flow-state records \`currentStage\` and which gates have passed.
 - The stage skill reads upstream artifacts and picks up context.
+- \`closeout.shipSubstate\` carries the post-ship substate, so a crashed
+  session during retro/compound/archive resumes at the exact step without
+  regenerating the retro draft.
 - No special resume command needed — \`/cc-next\` IS the resume command.
 
 ## Primary skill
@@ -149,11 +167,25 @@ Execute the stage protocol. The stage skill handles interaction, STOP points, ga
 
 If \`next\` is \`done\`:
 
-- If \`currentStage\` is \`ship\` and \`retro.completedAt\` is missing -> route to \`/cc-ops retro\`.
-- If \`currentStage\` is \`ship\` and \`retro.completedAt\` exists -> suggest \`/cc-ops compound\`, then route to \`/cc-ops archive\`.
-- Otherwise report **"Flow complete. All stages finished."** and stop.
+When \`currentStage\` is \`ship\`, automatically drive the **closeout chain**
+by inspecting \`closeout.shipSubstate\`:
+
+| shipSubstate          | Action                                              |
+|-----------------------|-----------------------------------------------------|
+| \`idle\` / missing      | Flip to \`retro_review\` and start retro protocol     |
+| \`retro_review\`        | Continue retro protocol (re-ask accept/edit/skip)   |
+| \`compound_review\`     | Run compound scan with a single approve/skip ask    |
+| \`ready_to_archive\`    | Run archive skill; reset flow-state on success      |
+| \`archived\`            | Report "run archived"; stop                         |
+
+Each step owns its own state transition. \`/cc-next\` never shells out to
+\`cclaw doctor\` or \`cclaw archive\` automatically — it loads the matching
+skill and command contract and executes the protocol in-session.
+
+Otherwise report **"Flow complete. All stages finished."** and stop.
 
-Otherwise load the next stage's skill and command contract, begin execution.
+Otherwise (non-terminal \`next\`): load the next stage's skill and command
+contract, begin execution.
 
 ## Stage order
 

package/dist/content/protocols.js

@@ -46,20 +46,47 @@ Shared closeout sequence applied by every stage skill.
    - update \`guardEvidence\`.
 3. Persist stage artifact under \`.cclaw/artifacts/\`.
 4. Run \`npx cclaw doctor\` and resolve failures.
-5. Capture reusable learnings from this stage artifact:
-   - append 1-3 strict-schema JSONL entries when the stage produced non-obvious
-     decisions, patterns, or lessons,
-   - use \`type=rule|pattern|lesson\` (\`compound\` stays retro-focused).
+5. **Capture through-flow learnings** — see the policy below. Knowledge
+   accrues continuously across stages, not just at retro.
 6. Notify user with stage completion and next action (\`/cc-next\`).
 7. Stop; do not auto-run the next stage unless user asks.
 
+## Through-flow knowledge capture
+
+Knowledge is recorded **throughout the run**, not saved up for retro.
+Each stage contributes a different kind of insight:
+
+| Stage       | Typical \`type\`  | What to capture                                       |
+|-------------|-----------------|-------------------------------------------------------|
+| brainstorm  | \`lesson\`        | rejected framings and why (only when non-obvious)     |
+| scope       | \`rule\`          | explicit out-of-scope boundaries worth remembering    |
+| design      | \`pattern\`       | architectural trade-offs and their rationale          |
+| spec        | \`rule\`          | non-negotiable acceptance criteria shape              |
+| plan        | \`pattern\`       | effective decomposition / risk-ordering heuristics    |
+| tdd         | \`pattern\`       | red→green→refactor cycle lessons, test-design notes   |
+| review      | \`lesson\`        | recurring defects / blockers caught in this codebase  |
+| ship        | \`lesson\`        | rollback triggers, preflight gotchas                  |
+| retro       | \`compound\`      | process accelerators for the **next** run             |
+
+Rules:
+
+- Append 1–3 strict-schema JSONL lines to \`.cclaw/knowledge.jsonl\` per
+  stage when that stage produced non-obvious decisions, patterns, or
+  lessons. Obvious restatements of the checklist do not count.
+- Use \`type=rule|pattern|lesson\` during stages; reserve \`type=compound\`
+  for the retro step so the retro vs. through-flow signal stays
+  distinguishable.
+- Set \`origin_stage\` to the stage that emitted the entry and
+  \`origin_feature\` to the active feature slug.
+
 ## Automatic learning capture policy
 
 - \`standard\` / \`medium\` tracks: required for \`design\`, \`tdd\`, and \`review\`;
   recommended for other stages.
 - \`quick\` track: recommended only (avoid overhead for tiny fixes).
 - "No learning captured" is acceptable only when explicitly justified (e.g. pure
-  mechanical change, no new trade-offs).
+  mechanical change, no new trade-offs). Record the justification in the
+  stage artifact, not in knowledge.jsonl.
 
 ## Resume protocol
 
@@ -108,9 +135,13 @@ No release shortcuts:
 
 ## 6) Compound, Don't Repeat
 
-When a reusable lesson appears, add one strict-schema JSONL entry via
-\`/cc-learn add\`. Repeated lessons should be lifted into stable rules/skills so
-the same class of mistake gets harder to repeat.
+Knowledge is recorded **throughout** the run, not saved for the retro.
+When a reusable lesson appears in design, plan, tdd, or review, append one
+strict-schema JSONL entry to \`.cclaw/knowledge.jsonl\` using
+\`type=rule|pattern|lesson\`. Reserve \`type=compound\` for post-ship retro.
+Repeated lessons (frequency ≥ 3) are lifted into stable
+rules/protocols/skills during the automatic compound pass so the same
+class of mistake gets harder to repeat.
 
 ## Turn Announce Discipline
 

package/dist/content/retro-command.js

@@ -15,28 +15,62 @@ export function retroCommandContract() {
 
 ## Purpose
 
-Mandatory retrospective gate before archive once ship is complete.
+Auto-triggered retrospective after ship. \`/cc-next\` drafts \`${retroArtifactPath()}\`
+from run artifacts and knowledge, then asks the user exactly ONE structured
+question: **edit / accept / skip**. Default = accept.
+
+This command is normally invoked indirectly by \`/cc-next\` when
+\`closeout.shipSubstate === "retro_review"\`. Invoking it directly is still
+supported for manual re-runs.
 
 ## HARD-GATE
 
-- Do not mark retro complete without writing \`${retroArtifactPath()}\`.
-- Do not finish retro without appending at least one \`type=compound\` entry into \`${knowledgePath()}\`.
+- Do not finalize retro without \`${retroArtifactPath()}\` on disk (or an explicit
+  \`retroSkipped: true\` in closeout with a one-line reason).
+- Do not finalize without appending **at least one** \`type=compound\` entry to
+  \`${knowledgePath()}\` (skipped runs set \`compoundEntries: 0\` instead).
+- Never advance to compound/archive with \`shipSubstate\` still at
+  \`"retro_review"\`.
+
+## Inputs
+
+\`/cc-ops retro\` (no flags). If the user wants to skip, they answer **skip**
+in the structured ask; there is no \`--skip\` flag.
 
 ## Algorithm
 
-1. Read \`${flowStatePath()}\`; confirm ship stage is complete for current run.
-2. Synthesize retrospective artifact \`${retroArtifactPath()}\` with:
-   - what slowed this run
-   - what accelerated this run
-   - concrete repeatable rule for next run
-3. Append >=1 strict-schema JSONL entry to \`${knowledgePath()}\` with:
-   - \`type: "compound"\`
-   - \`stage: "ship"\` or \`"retro"\`
-4. Update flow-state \`retro\` block:
-   - \`required: true\`
-   - \`completedAt: <ISO>\`
-   - \`compoundEntries: <count>\`
-5. Report completion summary and remind user that \`/cc-ops compound\` (optional) can lift repeated learnings before \`/cc-ops archive\`.
+1. Read \`${flowStatePath()}\`; confirm \`completedStages\` contains \`"ship"\`.
+2. If \`closeout.shipSubstate !== "retro_review"\`, and \`retro.completedAt\`
+   is already set, report "retro already complete" and stop.
+3. Draft \`${retroArtifactPath()}\` from available evidence:
+   - scan \`.cclaw/artifacts/01..08-*.md\` for decisions, blockers, rewinds,
+   - scan \`.cclaw/state/delegation-log.json\` for subagent outcomes,
+   - scan \`${knowledgePath()}\` for entries recorded during this run,
+   - structure the draft as: Outcomes / Slowed / Accelerated / Repeatable rule.
+4. Update \`closeout.retroDraftedAt = <ISO>\` in flow-state.
+5. Present **one** structured ask (AskUserQuestion on Claude, AskQuestion on
+   Cursor, plain-text options elsewhere):
+   - \`accept\` (default) — keep the draft as-is,
+   - \`edit\` — user edits \`${retroArtifactPath()}\` in-place, then re-runs \`/cc-next\`,
+   - \`skip\` — record \`retroSkipped: true\` + one-line reason, no compound entry required.
+6. On **accept**:
+   - append >=1 strict-schema JSONL line to \`${knowledgePath()}\` with
+     \`type: "compound"\` and \`stage: "retro"\`,
+   - set \`retro.required = true\`, \`retro.completedAt = <ISO>\`,
+     \`retro.compoundEntries = <count>\`,
+   - set \`closeout.retroAcceptedAt = <ISO>\`,
+   - set \`closeout.shipSubstate = "compound_review"\`.
+7. On **edit**:
+   - leave \`shipSubstate = "retro_review"\`,
+   - tell user to edit \`${retroArtifactPath()}\` and run \`/cc-next\` again.
+8. On **skip**:
+   - require a one-line reason; if empty, re-ask once then escalate,
+   - set \`closeout.retroSkipped = true\`, \`closeout.retroSkipReason = <text>\`,
+     \`closeout.retroAcceptedAt = <ISO>\`,
+   - set \`retro.completedAt = <ISO>\` (marks gate satisfied for archive), and
+     \`retro.compoundEntries = 0\`,
+   - set \`closeout.shipSubstate = "compound_review"\`.
+9. Emit a one-line summary: \`retro: accepted|edited|skipped | next: /cc-next\`.
 
 ## Primary skill
 
@@ -46,33 +80,71 @@ Mandatory retrospective gate before archive once ship is complete.
 export function retroCommandSkillMarkdown() {
     return `---
 name: ${RETRO_SKILL_NAME}
-description: "Run mandatory retrospective and record compound knowledge before archive."
+description: "Auto-drafted retrospective with a single structured accept/edit/skip ask. Triggered from /cc-next when shipSubstate=retro_review."
 ---
 
 # /cc-ops retro
 
 ## HARD-GATE
 
-Archive must remain blocked until retro artifact exists and compound knowledge was appended.
+Archive stays blocked until one of:
+- retro artifact exists **and** one compound knowledge entry was appended, OR
+- retro was explicitly skipped with a one-line reason recorded in closeout.
+
+Do not silently skip. Do not finalize without updating \`flow-state.json\`.
 
 ## Protocol
 
-1. Confirm ship completion from \`${flowStatePath()}\`.
-2. Create/update \`${retroArtifactPath()}\` with concise retrospective sections:
-   - outcomes
-   - bottlenecks
-   - reusable acceleration patterns
-3. Append at least one \`compound\` knowledge entry into \`${knowledgePath()}\`.
-4. Update \`flow-state.json.retro\` with completion timestamp + compound count.
-5. Print explicit completion line:
-   - \`retro gate: complete\`
-   - \`compound entries added: <N>\`
-   - \`next: /cc-ops compound (optional) -> /cc-ops archive\`
+1. Confirm ship completion by reading \`${flowStatePath()}\`.
+2. If retro draft does not yet exist, synthesise \`${retroArtifactPath()}\` using:
+   - all \`.cclaw/artifacts/*-*.md\` from the active run (stages 01–08),
+   - \`.cclaw/state/delegation-log.json\` entries,
+   - \`${knowledgePath()}\` entries written during this run.
+   Draft sections:
+   - **Outcomes** — what was actually shipped.
+   - **Slowed** — concrete friction points (cite artifact line or delegation id).
+   - **Accelerated** — patterns/decisions that worked and are worth keeping.
+   - **Repeatable rule** — one candidate rule/pattern for next run.
+   Record \`closeout.retroDraftedAt\`.
+3. Ask the user **one** structured question via the harness question tool
+   (AskUserQuestion / AskQuestion / plain text fallback):
+
+   > Retro draft ready at \`${retroArtifactPath()}\`. How do you want to
+   > proceed? (default: accept)
+   >
+   > - **accept** — keep the draft and continue.
+   > - **edit** — I'll edit it, then re-run \`/cc-next\`.
+   > - **skip** — no retro this run (requires one-line reason).
+
+4. Apply the state transition for the chosen option:
+   - \`accept\` → append \`{ "type": "compound", "stage": "retro", ... }\` line
+     to \`${knowledgePath()}\`; set \`retro.completedAt\`, \`retro.compoundEntries\`,
+     \`closeout.retroAcceptedAt\`; set \`closeout.shipSubstate = "compound_review"\`.
+   - \`edit\` → leave \`shipSubstate = "retro_review"\`; announce resume path.
+   - \`skip\` → set \`closeout.retroSkipped\`, \`closeout.retroSkipReason\`,
+     \`closeout.retroAcceptedAt\`, \`retro.completedAt\`,
+     \`retro.compoundEntries = 0\`; set \`closeout.shipSubstate = "compound_review"\`.
+
+5. Print one-line completion summary:
+   - \`retro gate: accepted (<N> compound entries)\`
+   - \`retro gate: skipped (reason: <text>)\`
+   - \`retro gate: editing (re-run /cc-next when ready)\`
+
+## Resume semantics
+
+A new session with \`closeout.shipSubstate === "retro_review"\` resumes
+exactly here. If \`closeout.retroDraftedAt\` is present but
+\`retroAcceptedAt\` is missing, re-ask the same structured question without
+regenerating the draft.
 
 ## Validation
 
-- \`${retroArtifactPath()}\` exists and is non-empty.
-- \`${knowledgePath()}\` contains >=1 valid \`compound\` line.
-- \`retro.completedAt\` is set in flow-state.
+- \`${retroArtifactPath()}\` exists and is non-empty, **or**
+  \`closeout.retroSkipped === true\` with a non-empty reason.
+- When accepted: \`${knowledgePath()}\` gained a valid \`compound\` line
+  and \`retro.compoundEntries > 0\`.
+- \`retro.completedAt\` is set.
+- \`closeout.shipSubstate\` is \`"compound_review"\` (or still
+  \`"retro_review"\` when user picked \`edit\`).
 `;
 }