cclaw-cli 0.34.0 → 0.35.0

package/README.md

@@ -2,13 +2,15 @@
 
 **Install once, ship every time.** cclaw is an installer-first workflow
 runtime that gives your AI coding agent one inspectable path from idea to
-shipped PR:
+shipped PR — **plus an automatic closeout chain** that turns every ship
+into reusable knowledge:
 
-> **brainstorm → scope → design → spec → plan → tdd → review → ship**
+> **brainstorm → scope → design → spec → plan → tdd → review → ship**  
+> **↳ auto-closeout: retro → compound → archive** *(resumable, never manual)*
 
 Every stage has real gates the agent cannot skip, every decision leaves a
-file-backed audit trail, and the same six slash commands work across
-Claude Code, Cursor, OpenCode, and OpenAI Codex.
+file-backed audit trail, and the same slash commands work across Claude
+Code, Cursor, OpenCode, and OpenAI Codex.
 
 You install cclaw **once** from the terminal, then everything happens
 inside your harness — no hidden control plane, no background daemon, no
@@ -41,15 +43,28 @@ operational knobs to memorise.
       │          │        │       │      │      │      │       │
       ▼          ▼        ▼       ▼      ▼      ▼      ▼       ▼
    01.md      02.md    03.md   04.md  05.md  06.md  07.md   08.md
-      │
-      └──── gates + subagents + knowledge capture happen at every step
+      │                                                      │
+      └──── gates + subagents + knowledge capture             │
+            happen at every step                              │
+                                                              ▼
+                                              ┌─────────────────────────┐
+                                              │  automatic closeout     │
+                                              │  (resumable state       │
+                                              │   machine, never manual)│
+                                              └────────────┬────────────┘
+                                                           ▼
+                                        retro ──► compound ──► archive
+                                        09.md     (knowledge  (runs/
+                                                   promoted)   <slug>/)
 ```
 
 Every stage reads and writes real files under `.cclaw/`. `flow-state.json`
-holds the single source of truth for "where are we"; `knowledge.jsonl`
-accumulates reusable lessons **throughout** the flow, not only at the end;
-stage artifacts live under `.cclaw/artifacts/` until the feature is
-archived.
+holds the single source of truth for "where are we" — including
+`closeout.shipSubstate` so a ship → retro → compound → archive chain
+resumes at the exact step after any interruption. `knowledge.jsonl`
+accumulates reusable lessons **throughout** the flow, not only at the
+end; stage artifacts live under `.cclaw/artifacts/` until archive rolls
+them into `.cclaw/runs/<date-slug>/`.
 
 ```
 You ──► /cc <idea>
@@ -188,21 +203,31 @@ No magic. No ambiguity about where you are.
 
 ---
 
-## The eight stages, and the three tracks
+## The eight stages, the three tracks, and auto-closeout
 
-cclaw has eight stages, but a single prompt rarely needs all of them.
-`/cc` picks a **track** up front so the flow matches the task.
+cclaw has eight **critical-path** stages plus an automatic three-step
+closeout chain (retro → compound → archive). A single prompt rarely needs
+all eight critical-path stages, so `/cc` picks a **track** up front so
+the flow matches the task.
 
-| Track | Path | Typical trigger |
+| Track | Critical path | Typical trigger |
 |---|---|---|
 | **quick** | `spec → tdd → review → ship` | `bug`, `hotfix`, `typo`, `rename`, `bump`, `docs only`, one-liners |
 | **medium** | `brainstorm → spec → plan → tdd → review → ship` | `add endpoint`, `add field`, `extend existing`, `wire integration` |
 | **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), `01-brainstorm.md` through `08-ship.md`, and
-`09-retro.md` at automatic closeout (see
-[Ship and closeout](#ship-and-closeout--automatic-resumable)).
+**Every track ends with the same auto-closeout chain.** Once ship
+completes, `/cc-next` automatically drives
+`retro → compound → archive` — with `closeout.shipSubstate` carrying the
+exact step across sessions, so a crashed or backgrounded run resumes
+without re-drafting retros or re-asking structured questions. See
+[Ship and closeout](#ship-and-closeout--automatic-resumable).
+
+Each critical-path stage produces a dated artifact under
+`.cclaw/artifacts/`: `00-idea.md` (seed), `01-brainstorm.md` through
+`08-ship.md`. Closeout adds `09-retro.md`; archive then rolls the whole
+bundle into `.cclaw/runs/<YYYY-MM-DD-slug>/` and resets the active flow
+for the next feature.
 
 ### Track heuristics are configurable
 

package/dist/content/meta-skill.js

@@ -18,6 +18,27 @@ description: "Routing brain for cclaw. Decide whether to start/resume a stage, a
 
 If the user explicitly overrides a stage rule, record it in the artifact.
 
+## Skill-before-response gate
+
+If \`.cclaw/state/flow-state.json\` exists and \`currentStage\` is set,
+load the matching stage SKILL before producing **substantive** work
+(artifact edits, code, structured clarifying questions). Do not improvise
+from memory. Also load a contextual utility skill when the task clearly
+triggers it (security, performance, debugging, docs, finishing-a-branch,
+verification-before-completion).
+
+Substantive vs. non-substantive:
+
+- **Substantive** (must load skill first): proposing design, editing an
+  artifact, running gates, dispatching subagents, asking a
+  \`Decision Protocol\` question, declaring a stage done.
+- **Non-substantive** (skill load optional): one-line acknowledgement,
+  clarifying a typo, confirming a prior answer, pure conversation.
+
+If the current stage is ambiguous because \`flow-state.json\` is missing
+or corrupt, stop and route through \`/cc\` before any substantive
+response.
+
 ## Routing flow
 
 \`\`\`

package/dist/content/protocols.js

@@ -19,11 +19,62 @@ Shared format for decisions that require user confirmation.
    - OpenCode/Codex: plain text options
 5. Wait for user choice before proceeding.
 
+## Decision skeleton
+
+Every Decision Protocol call — regardless of harness — follows this
+four-part skeleton. Do not skip a part; if a part is trivially empty,
+say so explicitly (e.g. "Re-ground: same branch, same task as prior
+turn").
+
+1. **Re-ground (1-2 sentences).** State the project, the active
+   feature slug, the active stage (from \`flow-state.json\`), and the
+   decision's plain-English context. Pull these values from the source
+   of truth, not from conversation memory.
+2. **Simplify (2-4 sentences).** Explain the choice in plain English a
+   smart 16-year-old could follow. No internal jargon, no raw function
+   names, no implementation trivia. Say what each option DOES and
+   what changes for the user.
+3. **Recommend.** One line of the form
+   \`RECOMMENDATION: Choose [Letter] because [one-line reason]\`.
+   Always prefer the more complete option unless an explicit constraint
+   says otherwise (see Completeness calibration below). Never present
+   options as equivalent when they are not.
+4. **Options.** Lettered options \`A) ... B) ... C) ...\`. Each option
+   includes one-line \`Completeness: X/10\` plus, when effort differs
+   noticeably, a \`(human: ~Xh / agent: ~Ym)\` estimate.
+
+## Completeness calibration
+
+Use the same 1-10 scale for every option so comparisons stay honest:
+
+- **10** = complete implementation: all stated edges handled,
+  traceable to spec, no known deferred work.
+- **7** = covers the happy path; one or two non-critical edges
+  deferred with an explicit follow-up.
+- **5** = partial; either drops edge cases silently or hands off
+  required work to a future run.
+- **3** = shortcut; skips spec criteria, violates an Iron Law, or
+  defers significant work without tracking.
+- **1** = acknowledged placeholder (\`TBD\`, \`TODO\`, "static for now").
+
+Calibration rules:
+
+- Mark any option at \`Completeness: ≤5\` and require the user to
+  acknowledge the gap before picking it.
+- If two options are both \`≥8\`, recommend the higher one.
+- "Static for now" / "we will add later" phrasing always scores \`≤3\`
+  and must be surfaced in Simplify, not buried in an option label.
+
 ## Ask format
 
 - One question per call.
-- Option labels are short and unambiguous.
-- If tool schema fails once, fall back to plain text immediately.
+- Option labels are short and unambiguous; the full reasoning lives in
+  Simplify + per-option Completeness.
+- If tool schema fails once, fall back to plain text immediately but
+  keep the skeleton (Re-ground / Simplify / RECOMMENDATION / lettered
+  Options with Completeness scores).
+- Log the chosen letter into the stage artifact's decision log with
+  the Completeness score; do not rely on chat history.
 
 ## Retry and escalation
 

package/dist/content/stages/spec.js

@@ -31,6 +31,7 @@ export const SPEC = {
         "Express each requirement in observable terms.",
         "Resolve ambiguity before moving to plan. Challenge vague language.",
         "Capture assumptions explicitly, not implicitly.",
+        "**Chunk acceptance criteria for review.** When presenting the spec to the user for sign-off, deliver acceptance criteria in batches of 3-5 and **pause for explicit ACK** (via Decision Protocol) before sending the next batch. Do not dump the full criteria wall in one message — small batches surface objections earlier and keep the sign-off meaningful. Full spec writeup still lands in `04-spec.md`, but the conversation itself must be digestible.",
         "Require user confirmation on the written spec. **STOP.** Do NOT proceed to plan until user approves.",
         "For each criterion, ask: how would you test this? If the answer is unclear, rewrite.",
         "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity."
@@ -40,6 +41,7 @@ export const SPEC = {
         "Capture constraints, assumptions, and edge cases.",
         "Build testability map: criterion -> test description.",
         "Confirm testability for each criterion.",
+        "Present acceptance criteria to the user in 3-5-item batches, pausing for explicit ACK between batches (see Interaction Protocol).",
         "Write spec artifact and request approval."
     ],
     requiredGates: [

package/package.json

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