cclaw-cli 0.30.0 → 0.32.0

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/doctor.js

@@ -484,7 +484,6 @@ export async function doctorChecks(projectRoot, options = {}) {
         const hasCcCommand = content.includes("/cc");
         const hasCcNext = content.includes("/cc-next");
         const hasCcIdeate = content.includes("/cc-ideate");
-        const hasCcLearn = content.includes("/cc-learn");
         const hasCcView = content.includes("/cc-view");
         const hasCcOps = content.includes("/cc-ops");
         const hasVerification = content.includes("Verification Discipline");
@@ -494,7 +493,6 @@ export async function doctorChecks(projectRoot, options = {}) {
             && hasCcCommand
             && hasCcNext
             && hasCcIdeate
-            && hasCcLearn
             && hasCcView
             && hasCcOps
             && hasVerification

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.js

@@ -30,12 +30,6 @@ const UTILITY_SHIMS = [
         skillFolder: "flow-view",
         commandFile: "view.md"
     },
-    {
-        fileName: "cc-learn.md",
-        command: "learn",
-        skillFolder: "learnings",
-        commandFile: "learn.md"
-    },
     {
         fileName: "cc-ops.md",
         command: "ops",
@@ -43,6 +37,13 @@ const UTILITY_SHIMS = [
         commandFile: "ops.md"
     }
 ];
+/**
+ * Shims that older cclaw versions installed as top-level slash commands but
+ * which we now treat as internal (skill-only, invoked by the agent, never
+ * typed by users). On sync/upgrade we proactively delete any stale file from
+ * harness command directories so `/cc-learn` etc. do not linger.
+ */
+const LEGACY_HARNESS_SHIMS = ["cc-learn.md"];
 export function harnessShimFileNames() {
     return ["cc.md", ...UTILITY_SHIMS.map((shim) => shim.fileName)];
 }
@@ -150,9 +151,11 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 | \`/cc-next\` | **Progression.** Advances to the next stage when current is complete. |
 | \`/cc-ideate\` | **Discovery mode.** Generates a ranked repo-improvement backlog before implementation. |
 | \`/cc-view\` | **Read-only router.** Unified entry for status/tree/diff views. |
-| \`/cc-learn\` | **Cross-cutting.** Capture or review project knowledge (append-only JSONL). |
 | \`/cc-ops\` | **Operations router.** Unified entry for feature/tdd-log/retro/compound/archive/rewind actions. |
 
+Knowledge capture and curation run automatically as part of stage completion
+protocols via the internal \`learnings\` skill — no user-facing command.
+
 **Stage order:** brainstorm > scope > design > spec > plan > tdd > review > ship.
 \`/cc-next\` loads the right stage skill automatically. Gates must pass before handoff.
 
@@ -263,6 +266,15 @@ export async function syncHarnessShims(projectRoot, harnesses) {
         for (const shim of UTILITY_SHIMS) {
             await writeFileSafe(path.join(commandDir, shim.fileName), utilityShimContent(harness, shim.command, shim.skillFolder, shim.commandFile));
         }
+        for (const legacy of LEGACY_HARNESS_SHIMS) {
+            const legacyPath = path.join(commandDir, legacy);
+            try {
+                await fs.unlink(legacyPath);
+            }
+            catch {
+                // fine — file may not exist (fresh install) or may be on read-only FS
+            }
+        }
     }
     await syncAgentFiles(projectRoot);
     await syncAgentsMd(projectRoot, harnesses);

package/dist/install.d.ts

@@ -1,10 +1,8 @@
-import type { FlowTrack, HarnessId, InitProfile } from "./types.js";
+import type { FlowTrack, HarnessId } from "./types.js";
 export interface InitOptions {
     projectRoot: string;
     harnesses?: HarnessId[];
     track?: FlowTrack;
-    /** When set, pre-fills config defaults from the named profile before applying flag overrides. */
-    profile?: InitProfile;
 }
 export declare function initCclaw(options: InitOptions): Promise<void>;
 export declare function syncCclaw(projectRoot: string): Promise<void>;
@@ -15,8 +13,8 @@ export declare function syncCclaw(projectRoot: string): Promise<void>;
  * `promptGuardMode`, `tddEnforcement`, `gitHookGuards`, `languageRulePacks`,
  * and `trackHeuristics` are preserved verbatim from the existing config.
  *
- * For an explicit reset to the default profile the user should reinstall via
- * `cclaw init --profile=<id>` (after optionally archiving the current run).
+ * For an explicit reset, run `cclaw-cli uninstall && cclaw-cli init`
+ * (after optionally archiving the current run via `/cc-ops archive`).
  */
 export declare function upgradeCclaw(projectRoot: string): Promise<void>;
 export declare function uninstallCclaw(projectRoot: string): Promise<void>;