cclaw-cli 0.31.0 → 0.32.0

package/README.md

@@ -200,8 +200,9 @@ cclaw has eight stages, but a single prompt rarely needs all of them.
 | **standard** _(default)_ | all 8 stages | `new feature`, `refactor`, `migration`, `platform`, `schema`, `architecture` |
 
 Each stage produces a dated artifact under `.cclaw/artifacts/`:
-`00-idea.md` (seed) and `01-brainstorm.md` through `08-ship.md`
-(plus `09-retro.md` at automatic closeout — see below).
+`00-idea.md` (seed), `01-brainstorm.md` through `08-ship.md`, and
+`09-retro.md` at automatic closeout (see
+[Ship and closeout](#ship-and-closeout--automatic-resumable)).
 
 ### Track heuristics are configurable
 
@@ -254,8 +255,12 @@ it into ceremony:
   in a single place (`.cclaw/contexts/`), so every skill speaks the same
   dialect.
 - **Knowledge capture throughout the flow.** Every stage completion
-  protocol can emit entries to `knowledge.jsonl` — not only retro. Strict
-  JSONL schema keeps it machine-queryable.
+  protocol emits typed entries (`rule` / `pattern` / `lesson`) to
+  `.cclaw/knowledge.jsonl` as the flow progresses — not only at retro.
+  Retro itself adds a `compound` entry, and the automatic compound pass
+  after ship promotes recurring entries (≥ 3) into first-class
+  rules/protocols/skills so the **next** run is easier. Strict JSONL
+  schema keeps the whole thing machine-queryable.
 - **Automatic integrity checks.** Runtime health is verified on every
   stage transition — no command you need to remember to run.
 
@@ -278,24 +283,38 @@ native subagent dispatch, such as Codex — see
 
 ---
 
-## Ship and closeout
-
-Shipping writes `08-ship.md` and then closes out the feature through a
-guided three-step sequence:
-
-1. **Retro** drafts `09-retro.md` from flow artifacts and the delegation
-   log; you review and accept.
-2. **Compound pass** promotes repeated knowledge entries (frequency ≥ 2,
-   maturity = stable) into first-class rules or skills.
-3. **Archive** moves artifacts to `.cclaw/runs/YYYY-MM-DD-<slug>/` and
-   resets `flow-state.json`.
-
-Retro is not optional — archive is gated on retro completion so you can't
-silently lose the learning pass.
-
-> **Coming next:** cclaw will chain these three steps automatically from
-> `ship` (one structured `edit`/`accept`/`skip` ask, resumable if the
-> session ends). Tracked as the v0.32 closeout-automation wave.
+## Ship and closeout — automatic, resumable
+
+Shipping writes `08-ship.md`. `/cc-next` then automatically walks the
+feature through a deterministic three-step closeout without extra
+commands from you:
+
+1. **Retro (`09-retro.md`).** cclaw drafts a retrospective from your
+   stage artifacts, the delegation log, and the knowledge entries
+   recorded during the run. It then asks exactly **one** structured
+   question:
+   - **accept** *(default)* — keep the draft, record one `compound`
+     knowledge entry, advance.
+   - **edit** — you edit `09-retro.md` in place, then `/cc-next` again.
+   - **skip** — record a one-line reason, continue (archive will
+     surface the skip in the run manifest).
+2. **Compound pass.** If the knowledge store has clusters recurring 3+
+   times, cclaw proposes concrete lifts into rules/protocols/skills and
+   asks once: apply-all / apply-selected / skip. An empty pass advances
+   silently.
+3. **Archive.** Moves artifacts into `.cclaw/runs/YYYY-MM-DD-<slug>/`,
+   snapshots `state/`, writes a manifest, and resets `flow-state.json`
+   to the track's initial stage.
+
+The chain is driven by `closeout.shipSubstate` inside `flow-state.json`
+(`retro_review` → `compound_review` → `ready_to_archive` → `archived`).
+If your session dies mid-closeout, a new `/cc-next` resumes at the
+exact step — retro drafts are not regenerated and no structured ask is
+repeated silently.
+
+You can still invoke each step manually (`/cc-ops retro`, `/cc-ops
+compound`, `/cc-ops archive`), but for the default path you do not need
+to: `/cc-next` is the only command.
 
 ---
 

package/dist/content/archive-command.js

@@ -15,35 +15,46 @@ export function archiveCommandContract() {
 
 ## Purpose
 
-Archive the active cclaw run from inside the harness flow (agent-first finish).
+Finalize the active cclaw run: move artifacts to \`${runsPath()}/<archive-id>\`,
+snapshot state, write a manifest, and reset runtime for the next run.
 
-This command removes the user-facing CLI gap: users can stay in \`/cc-*\` flow and
-finish with \`/cc-ops archive\` after ship + retro are complete.
+Auto-triggered by \`/cc-next\` when \`closeout.shipSubstate === "ready_to_archive"\`.
+Direct invocation from a harness command is supported but rarely needed.
 
 ## HARD-GATE
 
-- Do not archive a shipped run when retro is still incomplete.
-- Do not manually move files between \`${activeArtifactsPath()}\` and \`${runsPath()}\`.
-- Use the archive runtime so state snapshots + manifest stay consistent.
+- Do not archive with \`closeout.shipSubstate !== "ready_to_archive"\`.
+- Do not archive a shipped run when \`retro.completedAt\` is missing and
+  \`closeout.retroSkipped !== true\`.
+- Never hand-move files between \`${activeArtifactsPath()}\` and \`${runsPath()}\`.
+  Always run the archive runtime command so the snapshot+manifest stay
+  atomic.
 
 ## Inputs
 
-\`/cc-ops archive [--name=<slug>] [--skip-retro --retro-reason=<text>]\`
+\`/cc-ops archive [--name=<slug>]\`
+
+(Legacy flags \`--skip-retro --retro-reason=<text>\` still exist for CLI
+invocations; in-harness the skip path is driven by \`closeout.retroSkipped\`
+set during retro.)
 
 ## Algorithm
 
 1. Read \`${flowStatePath()}\`.
-2. If ship is complete and \`retro.completedAt\` is absent:
-   - block with explicit instruction: run \`/cc-ops retro\` first.
+2. Verify \`closeout.shipSubstate === "ready_to_archive"\`. If not, report
+   \`closeout not ready (state=<substate>) | run: /cc-next\` and stop.
 3. Build archive command:
-   - base: \`npx cclaw archive\`
-   - optional: \`--name=<slug>\`
-   - optional override: \`--skip-retro --retro-reason=<text>\`
-4. Execute archive command in project root.
-5. Surface result:
+   - base: \`npx cclaw archive\`,
+   - optional: \`--name=<slug>\`,
+   - legacy override: \`--skip-retro --retro-reason=<text>\` (only when user
+     explicitly wants the CLI skip path).
+4. Execute the archive command in project root.
+5. On success, flow-state is reset to the initial stage for the default
+   track; \`closeout.shipSubstate\` returns to \`"idle"\` on reset.
+6. Surface:
    - archive id/path,
-   - reset stage (brainstorm/spec depending on track default),
-   - knowledge curation hint when threshold exceeded.
+   - reset stage,
+   - knowledge curation hint when \`activeEntryCount >= softThreshold\`.
 
 ## Output format
 
@@ -63,36 +74,51 @@ cclaw archive
 export function archiveCommandSkillMarkdown() {
     return `---
 name: ${ARCHIVE_SKILL_NAME}
-description: "Archive the active cclaw run from harness flow and reset runtime safely."
+description: "Finalize the active cclaw run. Auto-triggered by /cc-next when shipSubstate=ready_to_archive."
 ---
 
 # /cc-ops archive
 
 ## HARD-GATE
 
-Never simulate archive by hand-editing runtime files. Always execute the archive
-runtime command so state snapshots and manifest generation stay atomic.
+Never simulate archive by hand-editing runtime files. Always execute the
+archive runtime command so state snapshots and manifest generation stay
+atomic. Never bypass the substate check — if retro/compound haven't
+advanced the substate to \`ready_to_archive\`, stop and surface the
+mismatch.
 
 ## Protocol
 
 1. Read \`${flowStatePath()}\`:
-   - confirm whether ship is completed,
-   - check \`retro.completedAt\` for post-ship runs.
-2. If ship complete and retro incomplete -> stop and direct user to \`/cc-ops retro\`.
-3. Build shell command:
-   - \`npx cclaw archive\`
-   - append \`--name=<slug>\` when provided
-   - append \`--skip-retro --retro-reason=<text>\` only when user explicitly requests skip
-4. Run command from repo root.
-5. Relay key lines from output:
-   - archive destination under \`${runsPath()}\`
-   - flow reset confirmation
-   - knowledge curation recommendation
+   - if \`closeout.shipSubstate !== "ready_to_archive"\`, stop and route
+     the user back to \`/cc-next\` (it will resume at the correct step),
+   - sanity-check: \`completedStages\` must include \`"ship"\`,
+   - sanity-check: \`retro.completedAt\` is set **or**
+     \`closeout.retroSkipped === true\` with a reason.
+2. Build shell command:
+   - \`npx cclaw archive\`,
+   - append \`--name=<slug>\` when provided,
+   - append legacy \`--skip-retro --retro-reason=<text>\` only when the user
+     explicitly requests the CLI skip path (normally not needed — skip is
+     captured in \`closeout\` during retro).
+3. Run command from repo root.
+4. Relay key lines from output:
+   - archive destination under \`${runsPath()}\`,
+   - flow reset confirmation,
+   - knowledge curation recommendation if \`activeEntryCount >= 50\`.
+
+## Resume semantics
+
+Archive is idempotent on a per-run basis. If a previous session ran
+archive successfully, the active artifacts directory is empty and
+\`closeout.shipSubstate\` is \`"idle"\`; \`/cc-next\` will simply report
+"Flow complete" or prompt for a new \`/cc\` input.
 
 ## Validation
 
-- \`${runsPath()}\` contains a new archive folder.
+- \`${runsPath()}\` contains a new archive folder for this run.
 - \`${activeArtifactsPath()}\` is reset for the next run.
 - \`${flowStatePath()}\` is valid JSON and points to the initial stage.
+- \`closeout.shipSubstate === "idle"\` after reset.
 `;
 }

package/dist/content/compound-command.js

@@ -6,29 +6,49 @@ export function compoundCommandContract() {
 
 ## Purpose
 
-Lift repeated lessons into durable project assets (rules, protocols, skills)
-so the next run is easier and safer.
+Lift repeated lessons from \`${RUNTIME_ROOT}/knowledge.jsonl\` into durable
+project assets (rules, protocols, skills) so the next run is easier and safer.
+
+Auto-triggered by \`/cc-next\` when \`closeout.shipSubstate === "compound_review"\`.
+Direct invocation is supported but rarely needed.
 
 ## HARD-GATE
 
-- Do not mutate rules/skills without explicit user approval.
-- Every proposal must cite concrete knowledge evidence (line references or IDs).
+- Do not mutate rules/skills/protocols without explicit user approval.
+- Every proposal must cite concrete knowledge evidence (line refs or IDs).
 - Keep scope focused: one compound change set per run.
+- Do not block the archive step if no clusters qualify — record an empty
+  compound pass and advance.
+
+## Inputs
+
+\`/cc-ops compound\` (no flags). The structured ask presents candidates;
+the user can approve individual lifts, accept-all, or skip.
 
 ## Algorithm
 
-1. Read \`${RUNTIME_ROOT}/knowledge.jsonl\`.
-2. Cluster repeated trigger/action pairs.
-3. For clusters with frequency >= 3, propose one lift action:
-   - rule update
-   - protocol update
-   - utility skill update
-4. For each proposal include:
-   - why now
-   - target file(s)
-   - expected risk reduction
-5. Ask user approval for each proposal before writing.
-6. Apply approved lifts and record completion in retro artifact.
+1. Read \`${RUNTIME_ROOT}/knowledge.jsonl\` (strict JSONL, one entry per line).
+2. Cluster entries by \`trigger\` + \`action\` similarity.
+3. Filter candidates whose recurrence count >= 3.
+4. If **no candidates** exist:
+   - set \`closeout.compoundCompletedAt = <ISO>\`,
+   - set \`closeout.compoundPromoted = 0\`,
+   - set \`closeout.shipSubstate = "ready_to_archive"\`,
+   - emit \`compound: no candidates | next: /cc-next\` and stop.
+5. Otherwise, present **one** structured ask (AskUserQuestion / AskQuestion /
+   plain text) summarising all candidates at once:
+   - \`apply-all\` (default) — apply every listed lift,
+   - \`apply-selected\` — prompt per-candidate,
+   - \`skip\` — record a skip reason and advance without changes.
+6. Apply approved lifts to the target file(s). Each lift also appends a
+   \`type: "compound"\` entry back to \`${RUNTIME_ROOT}/knowledge.jsonl\`
+   summarising what was lifted.
+7. Update flow-state:
+   - \`closeout.compoundCompletedAt = <ISO>\`,
+   - \`closeout.compoundPromoted = <count>\`,
+   - \`closeout.compoundSkipped = true\` if user picked skip,
+   - \`closeout.shipSubstate = "ready_to_archive"\`.
+8. Emit one-line summary: \`compound: promoted=<N> skipped=<bool> | next: /cc-next\`.
 
 ## Primary skill
 
@@ -38,7 +58,7 @@ so the next run is easier and safer.
 export function compoundCommandSkillMarkdown() {
     return `---
 name: ${COMPOUND_SKILL_NAME}
-description: "Compound mode: convert repeated learnings into durable rules/protocols/skills."
+description: "Lift repeated learnings into durable rules/protocols/skills. Auto-triggered after retro accept."
 ---
 
 # /cc-ops compound
@@ -49,13 +69,21 @@ description: "Compound mode: convert repeated learnings into durable rules/proto
 
 ## HARD-GATE
 
-No silent codification. Every lift requires explicit user approval.
+No silent codification. Every lift requires explicit user approval. An
+empty pass is allowed and must advance \`closeout.shipSubstate\` to
+\`"ready_to_archive"\`.
 
 ## Protocol
 
-1. Parse \`.cclaw/knowledge.jsonl\` and group repeated lessons.
-2. Keep only candidates with clear recurrence and actionable lift path.
-3. Propose each candidate using this template:
+1. Parse \`.cclaw/knowledge.jsonl\` and group repeated lessons by
+   trigger+action similarity.
+2. Keep only candidates with recurrence >= 3 and an actionable lift path.
+3. If none qualify, record an empty pass:
+   - \`closeout.compoundCompletedAt = <ISO>\`,
+   - \`closeout.compoundPromoted = 0\`,
+   - \`closeout.shipSubstate = "ready_to_archive"\`,
+   - announce \`compound: no candidates\` and stop.
+4. Otherwise, render each candidate as:
 
 \`\`\`
 Candidate: <short title>
@@ -65,8 +93,35 @@ Change type: <add/update/remove>
 Expected benefit: <what regressions this prevents>
 \`\`\`
 
-4. Ask user to approve/reject per candidate.
-5. Apply only approved candidates.
-6. Append a \`compound\` learning entry summarizing what was lifted.
+5. Present **one** structured question with three options:
+   - \`apply-all\` (default) — apply every candidate,
+   - \`apply-selected\` — prompt per-candidate approval next,
+   - \`skip\` — record a skip reason and advance.
+
+6. For approved candidates:
+   - edit the target file(s) with the lift,
+   - append a \`type: "compound"\` entry to \`.cclaw/knowledge.jsonl\`
+     describing what was promoted.
+
+7. Update flow-state \`closeout\`:
+   - \`compoundCompletedAt\`,
+   - \`compoundPromoted\` (count),
+   - \`compoundSkipped\` (boolean) + \`compoundSkipReason\` when applicable,
+   - \`shipSubstate = "ready_to_archive"\`.
+
+## Resume semantics
+
+A new session with \`shipSubstate === "compound_review"\` re-runs the scan
+and re-asks the structured question. If the user already applied lifts in
+a previous session but the state file was not updated, they should pick
+\`skip\` with reason \`already-applied\` — compound is idempotent from the
+closeout chain's perspective.
+
+## Validation
+
+- \`closeout.compoundCompletedAt\` is set.
+- \`closeout.shipSubstate === "ready_to_archive"\`.
+- If lifts were applied, the target files show the edit and at least one
+  new \`compound\` line exists in \`.cclaw/knowledge.jsonl\`.
 `;
 }

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\`).
 `;
 }

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/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.32.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {