cclaw-cli 0.31.0 → 0.33.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.
 
@@ -272,50 +277,92 @@ The `tdd` stage is not prose guidance. It requires:
 - optional **REFACTOR** pass with coverage preservation
 
 `/cc-next` will not advance past `tdd` until the delegation log shows the
-subagent as `completed` or explicitly `waived` (for harnesses without
-native subagent dispatch, such as Codex — see
-[Harness support](#harness-support)).
+subagent as `completed` (or, on Codex / OpenCode, role-switched with
+`evidenceRefs` — see [Harness support](#harness-support)).
 
 ---
 
-## 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.
 
 ---
 
 ## Harness support
 
-cclaw is honest about which harnesses give you full automation and which
-need small manual bridges. See
-[`docs/harnesses.md`](./docs/harnesses.md) for the full matrix.
-
-| Harness | Subagent dispatch | Hook surface | Structured ask | Status |
-|---|---|---|---|---|
-| Claude Code | native | full | `AskUserQuestion` | full parity |
-| Cursor | partial | full | `AskQuestion` | parity gap: subagent dispatch |
-| OpenCode | partial | plugin | plain-text | parity gap: plugin hooks |
-| OpenAI Codex | none (waiver) | full | plain-text | parity gap: no subagent |
-
-Capability gaps are captured in `.cclaw/state/harness-gaps.json`. Where
-native dispatch is missing, cclaw emits a **structured waiver** rather
-than pretending the delegation happened. Closing these gaps is an
-ongoing kinetic effort — see the harness tracking doc above.
+cclaw is honest about what each harness can and cannot do, and it
+closes every real gap with a documented fallback — not a silent waiver.
+
+| Harness | Dispatch | Fallback | Hook surface | Structured ask | Playbook |
+|---|---|---|---|---|---|
+| Claude Code | full (named subagents) | `native` | full | `AskUserQuestion` | [`claude-playbook.md`](./src/content/harness-playbooks.ts) |
+| Cursor | generic Task dispatcher | `generic-dispatch` | full | `AskQuestion` | `cursor-playbook.md` |
+| OpenCode | plugin / in-session | `role-switch` | plugin | plain-text | `opencode-playbook.md` |
+| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | full | plain-text | `codex-playbook.md` |
+
+What the fallbacks mean:
+
+- `native` — Claude runs mandatory delegations in isolated subagent
+  workers; cclaw records them with `fulfillmentMode: "isolated"`.
+- `generic-dispatch` — Cursor has a real Task tool with a fixed
+  vocabulary of `subagent_type`s (`explore`, `generalPurpose`, …).
+  cclaw maps each named agent (planner / reviewer / test-author /
+  security-reviewer / doc-updater) onto the generic dispatcher with a
+  structured role prompt. Per-agent mapping lives in the Cursor
+  playbook.
+- `role-switch` — OpenCode and Codex lack an isolated worker primitive.
+  The agent announces the role in-session, performs the work, and
+  records a delegation row with `fulfillmentMode: "role-switch"` and at
+  least one `evidenceRef` pointing at the artifact section that
+  captures the output. Under role-switch, a `completed` row **without**
+  evidenceRefs is classified as `missingEvidence` by `cclaw doctor` and
+  blocks stage completion.
+- `waiver` — reserved. Only fires auto-waivers if every installed
+  harness declares it. Currently unused — v0.33 removed the old
+  Codex-only auto-waiver path.
+
+The full capability matrix lives in
+[`docs/harnesses.md`](./docs/harnesses.md). Per-harness playbooks are
+generated into `.cclaw/references/harnesses/` on every install and
+upgrade; stage skills cite them by path.
+
+Runtime state:
+
+- `.cclaw/state/harness-gaps.json` (schema v2) — per-harness list of
+  missing capabilities, missing hook events, the declared fallback, the
+  playbook path, and a `remediation[]` list you can act on.
+- `cclaw doctor` — asserts every installed harness has its playbook on
+  disk and surfaces the expected fulfillment mode inside the
+  `delegation:mandatory:current_stage` check.
 
 ---
 

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/harness-playbooks.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type { HarnessId } from "../types.js";
+export declare const HARNESS_PLAYBOOKS_DIR = "references/harnesses";
+export declare function harnessPlaybookRelativePath(harness: HarnessId): string;
+export declare function harnessPlaybookFileName(harness: HarnessId): string;
+export declare function harnessPlaybookMarkdown(harness: HarnessId): string;
+export declare function harnessPlaybooksIndexMarkdown(): string;