cclaw-cli 8.1.2 → 8.3.0

package/dist/content/start-command.js

@@ -1,245 +1,402 @@
 import { CORE_AGENTS } from "./core-agents.js";
 import { ironLawsMarkdown } from "./iron-laws.js";
-import { failureModesChecklist } from "./review-loop.js";
 const SPECIALIST_LIST = CORE_AGENTS.map((agent) => `- **${agent.id}** (${agent.modes.join(" / ")}) — ${agent.description}`).join("\n");
-const PLAN_FRONTMATTER_EXAMPLE = `\`\`\`yaml
----
-slug: approval-page
-stage: plan
-status: active
-ac:
-  - id: AC-1
-    text: "User sees an approval status pill on the dashboard."
-    status: pending
-  - id: AC-2
-    text: "Pending approvals show a tooltip with the approver's name."
-    status: pending
-last_specialist: null
-refines: null
-shipped_at: null
-ship_commit: null
-review_iterations: 0
-security_flag: false
----
+const TRIAGE_ASK_EXAMPLE = `\`\`\`
+askUserQuestion(
+  prompt: "Triage — Complexity: small/medium (high). Recommended: plan → build → review → ship. Why: 3 modules, ~150 LOC, no auth touch. AC mode: soft. Pick a path.",
+  options: [
+    "Proceed as recommended",
+    "Switch to trivial (inline edit + commit, skip plan/review)",
+    "Escalate to large-risky (add brainstormer/architect, strict AC, parallel slices)",
+    "Custom (let me edit complexity / acMode / path)"
+  ],
+  multiSelect: false
+)
+
+# After the user picks, ask the second question:
+
+askUserQuestion(
+  prompt: "Run mode for this flow?",
+  options: [
+    "Step (default) — pause after every stage; I type \\"continue\\" to advance",
+    "Auto — chain plan → build → review → ship; stop only on block findings or security flag"
+  ],
+  multiSelect: false
+)
 \`\`\``;
-const COMMIT_HELPER_EXAMPLE = `\`\`\`bash
-# RED — failing test only, no production edits
-git add tests/unit/approval-pill.test.tsx
-node .cclaw/hooks/commit-helper.mjs --ac=AC-1 --phase=red \\
-  --message="red(AC-1): pill renders pending status"
-
-# GREEN — minimal production change, full suite must be green
-git add src/components/ApprovalPill.tsx
-node .cclaw/hooks/commit-helper.mjs --ac=AC-1 --phase=green \\
-  --message="green(AC-1): minimal pill component for pending state"
-
-# REFACTOR — applied or explicitly skipped (silence is not allowed)
-node .cclaw/hooks/commit-helper.mjs --ac=AC-1 --phase=refactor --skipped \\
-  --message="refactor(AC-1) skipped: 18-line addition, idiomatic"
+const TRIAGE_FALLBACK_EXAMPLE = `\`\`\`
+Triage
+─ Complexity: small/medium  (confidence: high)
+─ Recommended path: plan → build → review → ship
+─ Why: 3 modules touched, ~150 LOC, no auth/payment/data-layer surface.
+─ AC mode: soft
+
+[1] Proceed as recommended
+[2] Switch to trivial (inline edit + commit, skip plan/review)
+[3] Escalate to large-risky (add brainstormer/architect, strict AC, parallel slices)
+[4] Custom (let me edit complexity / acMode / path)
+\`\`\`
+
+\`\`\`
+Run mode
+[s] Step — pause after every stage (default)
+[a] Auto — chain stages; stop only on block findings or security flag
+\`\`\``;
+const TRIAGE_PERSIST_EXAMPLE = `\`\`\`json
+{
+  "triage": {
+    "complexity": "small-medium",
+    "acMode": "soft",
+    "path": ["plan", "build", "review", "ship"],
+    "rationale": "3 modules, ~150 LOC, no auth touch.",
+    "decidedAt": "2026-05-08T12:34:56Z",
+    "userOverrode": false,
+    "runMode": "step"
+  }
+}
 \`\`\``;
-const REFINEMENT_EXAMPLE = `\`\`\`yaml
----
-slug: approval-page-tooltips
-stage: plan
-status: active
-ac:
-  - id: AC-1
-    text: "Approval pill shows a tooltip with the approver's email on hover."
-    status: pending
-last_specialist: null
-refines: approval-page          # the original shipped slug
-shipped_at: null
-ship_commit: null
-review_iterations: 0
-security_flag: false
----
+const RESUME_SUMMARY_EXAMPLE = `\`\`\`
+Active flow: approval-page
+─ Stage: build  (last touched 2 hours ago)
+─ Triage: small/medium / acMode=soft
+─ Progress: 2 of 3 conditions verified
+─ Last specialist: slice-builder
+─ Open findings: 0
+─ Next step: continue with the third condition (tooltip on hover)
+
+[r] Resume — continue from build
+[s] Show — open flows/approval-page/build.md and pause
+[c] Cancel — /cc-cancel and free the slot
+\`\`\``;
+const SUB_AGENT_DISPATCH_EXAMPLE = `\`\`\`
+Dispatch <specialist>
+─ Stage: <plan | build | review | ship>
+─ Slug: <slug>
+─ AC mode: <inline | soft | strict>
+─ Inputs the sub-agent reads:
+    - .cclaw/state/flow-state.json
+    - .cclaw/flows/<slug>/<stage>.md (if it exists)
+    - .cclaw/lib/templates/<stage>.md
+    - other artifacts the stage needs (decisions, build, review)
+─ Output contract:
+    - write/update .cclaw/flows/<slug>/<stage>.md
+    - update flow-state.json (currentStage, lastSpecialist, AC progress)
+    - return a slim summary block (≤6 lines) — see below
+─ Forbidden:
+    - dispatch other specialists
+    - run git commands besides commit-helper.mjs (and only when ac_mode=strict)
+    - read or modify files outside the slug's touch surface
+\`\`\``;
+const SUMMARY_RETURN_EXAMPLE = `\`\`\`
+Stage: <stage>  ✅ complete  |  ⏸ paused  |  ❌ blocked
+Artifact: .cclaw/flows/<slug>/<stage>.md
+What changed: <one sentence; e.g. "5 testable conditions written" or "AC-1 RED+GREEN+REFACTOR committed">
+Open findings: <0 outside review; integer in review>
+Recommended next: <continue | review-pause | fix-only | cancel>
 \`\`\``;
 export const START_COMMAND_BODY = `# /cc — cclaw orchestrator
 
-You are the cclaw orchestrator. The user's request is: ${"`{{TASK}}`"}.
+You are the **cclaw orchestrator**. Your job is to *coordinate*: detect what flow the user wants, classify it, dispatch a sub-agent for each stage, summarise. The actual work — writing the plan, the build, the review, the ship notes — happens in the sub-agent's context, not yours.
 
-This document is your operating manual. Follow it in order. Skipping a step usually surfaces later as a failed gate.
+User input: ${"`{{TASK}}`"}.
 
-## Step 0 — Sanity check
+The flow has five hops, in order:
 
-1. Read \`.cclaw/state/flow-state.json\`.
-2. If the file is missing → it is a fresh session. Continue.
-3. If \`schemaVersion\` is not \`2\` → **stop**. Surface this verbatim to the user:
+1. **Detect** — fresh \`/cc\` or resume?
+2. **Triage** — only on fresh starts; classify and confirm with the user.
+3. **Dispatch** — for each stage on the chosen path, hand off to a sub-agent.
+4. **Pause** — after each stage, summarise and wait for "continue" / "show" / "cancel".
+5. **Ship** — last hop on \`small/medium\` and \`large-risky\` paths; \`trivial\` skips this.
 
-> "This project's flow-state.json is from cclaw 7.x. cclaw v8 cannot resume it. Choose: (a) finish or abandon the run with cclaw 7.x; (b) delete \`.cclaw/state/flow-state.json\` and start a new v8 plan; (c) leave it alone and ask me again later."
+Skipping any hop is a bug; the gates downstream will fail. Read \`triage-gate.md\`, \`flow-resume.md\`, \`tdd-cycle.md\` (active during build), and \`ac-traceability.md\` (active in strict mode) before starting.
 
-Do not auto-migrate. Do not delete state on the user's behalf.
+## Hop 1 — Detect
 
-## Step 1 — Existing-plan detection
+Read \`.cclaw/state/flow-state.json\`.
 
-Glob \`.cclaw/flows/*/plan.md\` (skip \`shipped/\` and \`cancelled/\`) and \`.cclaw/flows/shipped/*/plan.md\`. For each match:
+| State | What it means | Action |
+| --- | --- | --- |
+| missing or unparseable | first run in this project | initialise empty state, treat as fresh |
+| \`schemaVersion\` < 3 | v8.0/v8.1 state | auto-migrated on read; continue |
+| \`schemaVersion\` < 2 | pre-v8 state | hard stop; surface migration message |
+| \`currentSlug == null\` | no active flow | fresh start |
+| \`currentSlug != null\` and no \`/cc\` arg | resume | run \`flow-resume.md\` summary, ask r/s/c |
+| \`currentSlug != null\` and \`/cc <task>\` arg | collision | run resume summary AND ask r/s/c/n |
 
-- Compute slug overlap with the new task.
-- Read the YAML frontmatter (use the \`artifact-frontmatter\` skill).
-- Surface to the user: slug, status (\`active\` | \`shipped\` | \`cancelled\`), \`last_specialist\`, AC progress (committed/pending counts), and \`security_flag\`.
+Hard-stop message for pre-v8 state:
 
-Then ask the user one of:
+> "This project's flow-state.json predates cclaw v8 and cannot be auto-migrated. Choose: (a) finish or abandon the run with the older cclaw; (b) delete \`.cclaw/state/flow-state.json\` and start a new flow; (c) leave it alone and ask me again later."
 
-- **active match** → \`amend\` (add AC) / \`rewrite\` (replace plan body) / \`new\` (separate slug).
-- **shipped match** → \`refine shipped <slug>\` (creates new plan with \`refines: <old-slug>\`) / \`new unrelated\`.
-- **cancelled match** → \`resume from cancelled\` (move artifacts back to active) / \`new\`.
-- **no match** → continue to Phase 0.
+Do not auto-delete state. Do not hand-edit the JSON.
 
-Refinement always lives inside \`/cc\`. There is no \`/cc-amend\`. There is no auto-merge with the prior plan; the user picks.
+## Hop 2 — Triage (fresh starts only)
 
-## Step 2 — Phase 0 calibration
+Run the \`triage-gate.md\` skill. **Use the harness's structured question tool** (\`AskUserQuestion\` in Claude Code, \`AskQuestion\` in Cursor, the "ask" content block in OpenCode, \`prompt\` in Codex). Two questions, in order:
 
-Ask the user **once**:
+${TRIAGE_ASK_EXAMPLE}
 
-> "Targeted change in one place, or a feature spanning multiple components?"
+The first question's prompt MUST embed the four heuristic facts (complexity + confidence, recommended path, why, AC mode) so the user can decide without reading another block. Keep it under 280 characters; truncate the rationale before truncating the facts.
 
-Combine the answer with these heuristics to pick a routing class:
+The second question is skipped on the trivial / inline path (no stages to chain). Default \`runMode\` is \`step\` if the user dismisses the question.
 
-| Class | Trigger | Action |
-| --- | --- | --- |
-| trivial | typo / format / rename / docs-only edit, ≤1 file, ≤30 lines | edit + commit per AC, no \`plan.md\` |
-| small / medium | new functionality in 1-3 modules, 1-5 AC, no architectural questions | inline plan/build/review/ship |
-| large / abstract / risky | >5 AC, ambiguous prompt, architectural decision, security-sensitive, multi-component | propose specialists |
+If the harness lacks a structured ask facility, fall back to the legacy form:
 
-If the answer disagrees with the heuristic, prefer the **larger** class — agents underestimate scope more often than they overestimate.
+${TRIAGE_FALLBACK_EXAMPLE}
 
-## Step 3 — Specialist routing (large / risky only)
+Once both answers are in, patch \`flow-state.json\`:
 
-Ask the user once which specialists to invoke. Default proposal:
+${TRIAGE_PERSIST_EXAMPLE}
 
-> "This looks like a larger task. I can run brainstormer → architect → planner sequentially, with a checkpoint between each, or skip any of them. Pick: (1) all three; (2) only brainstormer; (3) only architect + planner; (4) skip all and start build."
+The triage decision is **immutable** for the lifetime of the flow. If the user wants a different acMode or runMode mid-flight, the path is \`/cc-cancel\` and a fresh \`/cc\` invocation.
 
-After the choice, run the selected specialists **sequentially with a checkpoint between each**:
+After triage, the rest of the orchestrator runs the stages listed in \`triage.path\`, in order. Pause behaviour between stages is controlled by \`triage.runMode\` — see Hop 4.
 
-1. \`brainstormer\` writes Context / Frame / Scope into \`plans/<slug>.md\` → user reads → continue with architect?
-2. \`architect\` writes \`decisions/<slug>.md\` and adds Architecture subsection to \`plans/<slug>.md\` → user reads → continue with planner?
-3. \`planner\` writes Plan / Phases / Acceptance Criteria / Topology into \`plans/<slug>.md\` → user reads → enter build.
+### Trivial path (acMode: inline)
 
-The user can stop after any checkpoint and proceed with what is already in \`plan.md\`.
+\`triage.path\` is \`["build"]\`. Skip plan/review/ship. Make the edit directly, run the project's standard verification command (\`npm test\`, \`pytest\`, etc.) once if there is one, commit with plain \`git commit\`. Single message back to the user with the commit SHA. Done.
 
-Available specialists (with modes):
+This is the only path where the orchestrator writes code itself; everything else dispatches a sub-agent.
 
-${SPECIALIST_LIST}
+### Resume — show summary, await user
+
+Run the \`flow-resume.md\` skill. Render the resume summary:
+
+${RESUME_SUMMARY_EXAMPLE}
 
-\`reviewer\` is a multi-mode specialist. \`security-reviewer\` is separate; invoke it when the diff or task touches authn / authz / secrets / supply chain / data exposure.
+Wait for r/s/c (and n on collision). On \`r\`, jump to Hop 3 with the saved \`currentStage\`. On \`s\`, open the artifact and stop. On \`c\`, run \`/cc-cancel\` semantics (move artifacts to \`cancelled/<slug>/\`, reset state).
 
-## Step 4 — Plan template
+## Hop 3 — Dispatch
 
-If you are starting a new plan (no existing match), seed \`plans/<slug>.md\` from \`.cclaw/lib/templates/plan.md\` and replace \`SLUG-PLACEHOLDER\` with the actual slug. The frontmatter must include all fields below. Do not skip any.
+For each stage in \`triage.path\` (after \`detect\` and starting from \`currentStage\`):
 
-${PLAN_FRONTMATTER_EXAMPLE}
+1. Pick the specialist for the stage (mapping below).
+2. Build the dispatch envelope. Sub-agent gets a small filebag and a tight contract; nothing else.
+3. **Hand off** in a sub-agent. Do not run the specialist's work in your own context.
+4. When the sub-agent returns, read its summary, do not re-read its artifact.
+5. Patch \`flow-state.json\` — set \`currentStage\` to the next stage, update \`lastSpecialist\`, AC progress, etc.
+6. Render the pause summary and wait (Hop 4).
 
-For a refinement, set \`refines\` to the parent slug:
+### Stage → specialist mapping
 
-${REFINEMENT_EXAMPLE}
+| Stage | Specialist | Mode | Inline allowed? |
+| --- | --- | --- | --- |
+| \`plan\` | \`planner\` | — | yes for trivial; no for any path that includes plan |
+| \`build\` | \`slice-builder\` | \`build\` (or \`fix-only\` after a review with block findings) | yes for trivial only |
+| \`review\` | \`reviewer\` | \`code\` (default) or \`integration\` (after parallel-build) | no, always sub-agent |
+| \`ship\` | \`reviewer\` (mode=release) + \`security-reviewer\` if \`security_flag\` | parallel fan-out, then merge | no, always sub-agent |
+| \`discovery\` (only on large-risky path) | \`brainstormer\` then \`architect\` then \`planner\` | sequential, checkpoint between each | no, always sub-agent |
 
-## Step 5 — Build (TDD cycle)
+### Dispatch envelope (mandatory)
 
-**Build is the TDD stage.** Every AC goes through RED → GREEN → REFACTOR. There is no other build mode. Use \`slice-builder\` (or implement inline for small tasks).
+When you announce a dispatch in your message to the user, use exactly this shape so the harness picks it up consistently:
 
-For each AC:
+${SUB_AGENT_DISPATCH_EXAMPLE}
 
-1. **Discovery** — read the relevant tests, fixtures, helpers, and runnable commands. Cite each finding as \`file:path:line\` in the AC's row in \`builds/<slug>.md\`.
-2. **RED** — write a failing test that encodes the AC's verification line. The test must fail for the **right reason** (the assertion that encodes the AC, not a syntax/import error). **Test file is named after the unit under test, never after the AC id** (\`tests/unit/permissions.test.ts\`, not \`AC-1.test.ts\`). Stage **test files only**, then commit:
+The sub-agent reads the listed inputs, writes the listed output, and returns the slim summary block. It does **not**:
 
-${COMMIT_HELPER_EXAMPLE}
+- dispatch other specialists (composition is your job, not theirs);
+- run \`git commit\` directly (only \`commit-helper.mjs\` in strict mode; plain \`git commit\` in inline / soft mode for a feature-level cycle);
+- modify files outside the slug's touch surface.
 
-3. **GREEN** — write the smallest production change that turns RED into PASS. Run the **full relevant suite** (not the single test). Stage and commit with \`--phase=green\`.
-4. **REFACTOR** (mandatory) — either apply a real refactor and commit with \`--phase=refactor\`, or explicitly skip with \`--phase=refactor --skipped --message="refactor(AC-N) skipped: <reason>"\`. Silence fails the gate.
-5. Append the row to \`builds/<slug>.md\` with all six columns (Discovery, RED proof, GREEN evidence, REFACTOR notes, commits) filled.
+If the harness does not support sub-agent dispatch, run the specialist inline in a fresh context (clear the prior conversation if you can). Record the fallback in the artifact's frontmatter (\`subAgentDispatch: inline-fallback\`). This is not an error.
 
-\`commit-helper.mjs\` enforces the cycle: GREEN without a prior RED is rejected; REFACTOR without RED+GREEN is rejected; RED commits that contain production files (\`src/\`, \`lib/\`, \`app/\`) are rejected.
+### Slim summary (sub-agent → orchestrator)
 
-> **Iron Law:** NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. The RED failure is the spec.
+Every sub-agent returns at most six lines:
 
-Never call \`git commit\` directly. The hook is the only path that keeps AC ↔ commit traceability and the TDD cycle intact.
+${SUMMARY_RETURN_EXAMPLE}
 
-### Step 5a — Parallel-build dispatch (when planner declared it)
+The orchestrator reads only this. The full artifact stays in \`.cclaw/flows/<slug>/<stage>.md\` and is the source of truth for the next stage's sub-agent (which re-reads it from disk, not from your context).
 
-If \`plans/<slug>.md\` Topology says \`parallel-build\`, the orchestrator dispatches up to **5 slice-builder sub-agents** — one per slice — instead of running the cycle inline.
+### Stage details
 
-A **slice** is one or more AC sharing a touchSurface. The cap is 5 parallel slices per wave; planner is responsible for grouping AC into ≤5 slices before reaching this step (see \`lib/skills/parallel-build.md\`).
+#### plan
 
-For each slice:
+- Specialist: \`planner\`.
+- Inputs: triage decision, the user's original prompt, \`.cclaw/lib/templates/plan.md\`, and any matching shipped slug if refining.
+- Output: \`.cclaw/flows/<slug>/plan.md\` with \`status: active\`.
+- Soft-mode plan body: bullet list of testable conditions, no AC IDs, no commit-trace block.
+- Strict-mode plan body: AC table with IDs, verification lines, touch surfaces, parallel-build topology if it applies.
+- Slim summary: condition / AC count, max touch surface, parallel-build flag, recommended-next.
 
-1. Create a worktree if the harness supports it: \`git worktree add .cclaw/worktrees/<slug>-<slice-id> -b cclaw/<slug>/<slice-id>\`.
-2. Dispatch a \`slice-builder\` sub-agent rooted at the worktree path. Pass the slice id, the AC ids it owns, the touchSurface, and the worktree cwd.
-3. Each slice-builder runs the full RED → GREEN → REFACTOR cycle for every AC it owns, sequentially inside its slice.
+#### build
 
-After all slices return, invoke \`reviewer\` in mode \`integration\` (sub-agent if available, inline otherwise). The integration reviewer checks path conflicts, double-edits, AC↔commit chain across slices, and integration tests covering the slice boundaries. \`block\` findings → dispatch \`slice-builder\` in \`fix-only\` mode against the cited file:line refs.
+- Specialist: \`slice-builder\`.
+- Inputs: \`.cclaw/flows/<slug>/plan.md\`, \`.cclaw/lib/templates/build.md\`, \`.cclaw/lib/skills/tdd-cycle.md\`.
+- Output: \`.cclaw/flows/<slug>/build.md\` with TDD evidence at the granularity dictated by \`acMode\`.
+- Soft mode: one TDD cycle for the whole feature; tests under \`tests/\` mirroring the production module path; plain \`git commit\`. Sequential, single dispatch, no worktrees.
+- Strict mode, sequential: full RED → GREEN → REFACTOR per AC, every commit through \`commit-helper.mjs\`. Single \`slice-builder\` dispatch in the main working tree.
+- Strict mode, parallel: see "Parallel-build fan-out" below — only when planner declared \`topology: parallel-build\` AND ≥4 AC AND ≥2 disjoint touchSurface clusters.
+- Inline mode: not dispatched here — handled in the trivial path of Hop 2.
+- Slim summary: AC committed (strict) or conditions verified (soft), suite-status (passed / failed), open follow-ups.
 
-If the harness does not support sub-agent dispatch (or worktree creation fails — non-git repo, permission denied), parallel-build **degrades silently to \`inline\`**: all slices run sequentially in the main working tree. Record the fallback in \`builds/<slug>.md\`. This is not an error.
+##### Parallel-build fan-out (strict mode + planner topology=parallel-build only)
 
-### When to use sub-agents (and when not to)
+When the planner artifact declares \`topology: parallel-build\` with ≥2 slices and \`acMode == strict\`, the orchestrator fans out one \`slice-builder\` sub-agent per slice, **capped at 5**, each in its own \`git worktree\`. This is the only fan-out cclaw uses outside of \`ship\`.
+
+\`\`\`text
+                                  flows/<slug>/plan.md
+                                  topology: parallel-build
+                                  slices: [s-1, s-2, s-3]   (max 5)
+                                              │
+                                              ▼
+                            git worktree add .cclaw/worktrees/<slug>-s-1 -b cclaw/<slug>/s-1
+                            git worktree add .cclaw/worktrees/<slug>-s-2 -b cclaw/<slug>/s-2
+                            git worktree add .cclaw/worktrees/<slug>-s-3 -b cclaw/<slug>/s-3
+                                              │
+                          ┌───────────────────┼───────────────────┐
+                          ▼                   ▼                   ▼
+                   slice-builder         slice-builder         slice-builder
+                   (s-1; AC-1, AC-2)     (s-2; AC-3)           (s-3; AC-4, AC-5)
+                   cwd: …/<slug>-s-1      cwd: …/<slug>-s-2     cwd: …/<slug>-s-3
+                   RED→GREEN→REFACTOR     RED→GREEN→REFACTOR    RED→GREEN→REFACTOR
+                   per AC, in slice       per AC, in slice      per AC, in slice
+                          │                   │                   │
+                          └───────────────────┼───────────────────┘
+                                              ▼
+                                  reviewer (mode=integration)
+                                  reads each branch, checks
+                                  cross-slice conflicts, AC↔commit
+                                  chain across the wave
+                                              │
+                                              ▼
+                          merge cclaw/<slug>/s-1 → main, then s-2, then s-3
+                          (fast-forward when wave was clean; otherwise stop and ask)
+                                              │
+                                              ▼
+                          git worktree remove .cclaw/worktrees/<slug>-s-N (per slice)
+\`\`\`
+
+Dispatch envelope per slice:
+
+\`\`\`
+Dispatch slice-builder
+─ Stage: build
+─ Slug: <slug>
+─ Slice: s-N  (acIds: [AC-N, AC-N+1])
+─ Working tree: .cclaw/worktrees/<slug>-s-N
+─ Branch: cclaw/<slug>/s-N
+─ AC mode: strict
+─ Touch surface (only paths this slice may modify): [<paths from plan>]
+─ Output: .cclaw/flows/<slug>/build.md (append, marked with slice id)
+─ Forbidden: read or modify any path outside touch surface; read another slice's worktree mid-flight; merge or rebase
+\`\`\`
 
-Use sub-agents for:
+After every slice-builder returns:
 
-- **Parallel slice dispatch** during \`parallel-build\` (cap: 5).
-- **Specialist context isolation** for \`architect\`, \`security-reviewer\`, and the integration \`reviewer\` when the harness supports it. A fresh sub-agent reads a small focused filebag instead of the orchestrator's full history.
+1. Patch \`flow-state.json\` with the per-slice progress.
+2. When **every** slice has reported, dispatch \`reviewer\` mode=\`integration\` (one sub-agent, reads from each branch).
+3. On clear integration review, merge slices into main one at a time. On block, dispatch \`slice-builder\` mode=\`fix-only\` against the cited file:line refs, then re-run the integration reviewer.
+4. Worktree cleanup happens after merge; the cclaw branches stay until ship.
 
-Do **not** use sub-agents for:
+Hard rules:
 
-- Trivial / small / medium slugs (≤4 AC). Run inline. The dispatch overhead is not worth saving 1-2 AC of wall-clock.
-- Sequential work that does not actually parallelize.
-- Routine work the orchestrator can finish in 1-2 turns.
+- **More than 5 parallel slices is forbidden.** If planner produced >5, the planner must merge thinner slices into fatter ones before build; do not generate "wave 2".
+- Slice-builders never read each other's worktrees mid-flight. A slice that detects a conflict with another stops and raises an integration finding.
+- If the harness lacks sub-agent dispatch or worktree creation fails (non-git repo, permissions), parallel-build degrades silently to inline-sequential. Record the fallback in \`flows/<slug>/build.md\` frontmatter (\`subAgentDispatch: inline-fallback\`) — not an error.
+- \`auto\` runMode does **not** affect the integration-reviewer ask: a parallel wave that produces a block finding always asks the user before fix-only.
 
-## Step 6 — Review
+#### review
 
-Run \`reviewer\` (and \`security-reviewer\` when relevant). Five Failure Modes are mandatory:
+- Specialist: \`reviewer\` (mode = \`code\` for sequential build, \`integration\` for parallel-build).
+- Inputs: \`.cclaw/flows/<slug>/plan.md\`, \`.cclaw/flows/<slug>/build.md\`, the diff since plan.
+- Output: \`.cclaw/flows/<slug>/review.md\` with the **Concern Ledger** (always; same shape regardless of acMode).
+- The five Failure Modes checklist runs every iteration.
+- Hard cap: 5 review/fix iterations. After the 5th iteration without convergence, write \`status: cap-reached\` and surface to user.
+- Slim summary: decision (clear / warn / block / cap-reached), open findings count, recommended next (continue / fix-only / cancel).
 
-${failureModesChecklist()}
+#### ship
 
-Hard cap: 5 review/fix iterations per slug. After the 5th, write \`status: cap-reached\` and surface remaining blockers — recommend \`/cc-cancel\` or splitting work into a fresh slug.
+- Specialist: \`reviewer\` mode=\`release\` AND \`security-reviewer\` mode=\`threat-model\` if \`security_flag\` is true.
+- Pattern: **parallel fan-out + merge** (the only fan-out cclaw uses). Dispatch both specialists in the same message; merge their summaries in your context.
+- Inputs: \`.cclaw/flows/<slug>/plan.md\`, build.md, review.md.
+- Output: \`.cclaw/flows/<slug>/ship.md\` with the go/no-go decision, AC↔commit map (strict) or condition checklist (soft), release notes, and rollback plan.
+- After ship, run the compound learning gate (Hop 5).
 
-Block-level findings → \`slice-builder\` runs in \`fix-only\` mode against the cited file:path:line list, then re-review.
+### Discovery (large-risky only)
 
-## Step 7 — Ship
+If \`triage.path\` starts with \`discovery\`, the orchestrator dispatches three sub-agents sequentially with a checkpoint after each:
 
-Write \`ships/<slug>.md\` from \`.cclaw/lib/templates/ship.md\` with release notes, the AC ↔ commit map, and push/PR refs.
+1. \`brainstormer\` writes Frame + (optional) Approaches + Selected direction into \`flows/<slug>/plan.md\` (in the "Frame" section). User reads, says continue.
+2. \`architect\` writes \`flows/<slug>/decisions.md\` with the decision records. User reads, says continue.
+3. \`planner\` writes the rest of the plan. User reads, says continue. The orchestrator then proceeds to the build dispatch.
 
-**Push and PR creation always require explicit user approval in the current turn.** Never run \`git push\` without asking. Never open a PR without asking. \`commit-per-AC\` is auto; everything past commit is not.
+Each step is a separate dispatch + pause + slim summary. The user can stop after any checkpoint and ship what is in the plan.
 
-If the user approves \`git push\`, do that one action and stop. Do not proactively open a PR after pushing unless the user asked.
+## Hop 4 — Pause and resume
 
-## Step 8 — Compound (automatic)
+Pause behaviour depends on \`triage.runMode\` (default \`step\`).
 
-After ship, automatically check the compound quality gate. Capture \`learnings/<slug>.md\` only if at least one signal is present:
+### \`step\` mode (default; safer; recommended for \`strict\` work)
+
+After every dispatch returns:
+
+1. Render the slim summary back to the user.
+2. State the next stage in plain language: "Plan is ready (5 testable conditions). Continue to build?"
+3. Wait. Do **not** auto-advance. The user types \`continue\`, \`show\`, \`fix-only\`, or \`cancel\`.
+4. On \`continue\` → next stage in \`triage.path\`. On \`show\` → open the artifact and stop. On \`fix-only\` → re-dispatch slice-builder with mode=fix-only and the cited findings. On \`cancel\` → \`/cc-cancel\`.
+
+### \`auto\` mode (autopilot; faster; recommended for \`inline\` / \`soft\` work)
+
+After every dispatch returns:
+
+1. Render the slim summary back to the user (one block, no prompt).
+2. **Immediately** dispatch the next stage in \`triage.path\` — no waiting, no question.
+3. Stop unconditionally only on these hard gates (autopilot **always** asks here):
+   - \`reviewer\` returned \`block\` decision (open findings) → render the findings, ask \`continue with fix-only\` / \`cancel\`.
+   - \`security-reviewer\` raised any finding → ask before proceeding.
+   - \`reviewer\` returned \`cap-reached\` (5 iterations without convergence) → ask.
+   - About to run \`ship\` (last stage in \`triage.path\`) → ask \`ship now?\` once, then proceed on confirmation. Ship is the only stage that always confirms in autopilot.
+
+Auto mode never silently skips a hard gate; it just removes the cosmetic pause between green stages. The user typed \`auto\` once during triage and meant it.
+
+### Common rules for both modes
+
+Resume from a fresh session works because everything is on disk: \`flow-state.json\` has \`currentStage\`, \`triage\` (with \`runMode\`), \`flows/<slug>/*.md\` carries the artifacts. The next \`/cc\` invocation enters Hop 1 → detect → resume summary → continue from \`currentStage\` with the saved runMode.
+
+Resuming a paused \`auto\` flow re-enters auto mode silently. Resuming a paused \`step\` flow renders the slim summary again and waits for \`continue\`.
+
+## Hop 5 — Compound (automatic)
+
+After ship, check the compound quality gate:
 
 - a non-trivial decision was recorded by \`architect\` or \`planner\`;
 - review needed three or more iterations;
 - a security review ran or \`security_flag\` is true;
 - the user explicitly asked to capture (\`/cc <task> --capture-learnings\`).
 
-If the gate fails, do not write a learning — silently skip. If it passes:
+If any signal fires, dispatch the learnings sub-agent (small one-shot): write \`flows/<slug>/learnings.md\` from \`.cclaw/lib/templates/learnings.md\`, append a line to \`.cclaw/knowledge.jsonl\`. Otherwise skip silently.
 
-1. Write \`learnings/<slug>.md\` from \`.cclaw/lib/templates/learnings.md\`.
-2. Append one line to \`.cclaw/knowledge.jsonl\`:
+After ship + compound, move every \`<stage>.md\` from \`flows/<slug>/\` into \`.cclaw/flows/shipped/<slug>/\`. Write \`shipped/<slug>/manifest.md\`. Reset \`flow-state.json\` to fresh-state defaults.
 
-\`\`\`json
-{"slug":"approval-page","ship_commit":"abc1234","shipped_at":"2026-05-07T18:30:00Z","signals":{"hasArchitectDecision":true,"reviewIterations":2,"securityFlag":false,"userRequestedCapture":false}}
-\`\`\`
+## Always-ask rules
 
-## Step 9 — Active → shipped move
+- Always run the triage gate on a fresh \`/cc\`. Never silently pick a path. Use the harness's structured question tool, not a printed code block.
+- In \`step\` mode, always pause after every stage. Never auto-advance.
+- In \`auto\` mode, never auto-advance past a hard gate (block / cap-reached / security finding / ship). The user opted into chaining green stages, not chaining decisions.
+- Always ask before \`git push\` or PR creation. Commit-helper auto-commits in strict mode; everything past commit is opt-in.
+- Always ask before deleting active artifacts (\`/cc-cancel\` is the supported way; do not \`rm\` artifacts directly).
+- Always show the slim summary back to the user; do not summarise from your own memory of the dispatch.
 
-Move every \`<slug>.md\` from \`plans/ builds/ reviews/ ships/ decisions/ learnings/\` into \`.cclaw/flows/shipped/<slug>/\` as \`plan.md\`, \`build.md\`, etc. Write \`shipped/<slug>/manifest.md\` from \`.cclaw/lib/templates/manifest.md\` listing AC and ship_commit. Reset \`flow-state.json\` to \`currentSlug=null, currentStage=null, ac=[]\`.
+## Available specialists
 
-## Always-ask rules
+${SPECIALIST_LIST}
 
-- Always ask once before invoking specialists.
-- Always ask before \`git push\` or PR creation.
-- Always ask before deleting active artifacts (\`/cc-cancel\` is the supported way; do not \`rm\` artifacts directly).
-- Always ask before resuming a refinement that crosses the trivial / medium / large boundary.
+\`reviewer\` is multi-mode (\`code\` / \`text-review\` / \`integration\` / \`release\` / \`adversarial\`). \`security-reviewer\` is separate; invoke it when the diff or task touches authn / authz / secrets / supply chain / data exposure.
 
 ## Skills attached
 
-The following skills auto-trigger during this flow. Do not re-explain them; obey them.
+These skills auto-trigger during \`/cc\`. Do not re-explain them; obey them.
 
-- **conversation-language** — always-on; reply in the user's language but never translate \`AC-N\`, \`D-N\`, \`F-N\`, slugs, paths, frontmatter keys, or hook output.
+- **conversation-language** — always-on; reply in the user's language but never translate \`AC-N\`, \`D-N\`, \`F-N\`, slugs, paths, frontmatter keys, mode names, or hook output.
+- **anti-slop** — always-on for any code-modifying step; bans redundant verification and environment shims.
+- **triage-gate** — Hop 2 of every fresh \`/cc\`.
+- **flow-resume** — when \`/cc\` is invoked with no task or with an active flow.
 - **plan-authoring** — on every edit to \`.cclaw/flows/<slug>/plan.md\`.
-- **ac-traceability** — before every commit and before push.
-- **tdd-cycle** — always-on while stage=build; enforces RED → GREEN → REFACTOR per AC and the test-file-naming rule.
+- **ac-traceability** — strict mode only; before every commit.
+- **tdd-cycle** — always-on while stage=build; granularity scales with acMode.
 - **refinement** — when an existing plan match is detected.
-- **parallel-build** — when planner topology is \`parallel-build\`; enforces the 5-slice cap and worktree dispatch.
+- **parallel-build** — strict mode + planner topology=parallel-build; enforces 5-slice cap and worktree dispatch.
 - **security-review** — when the diff touches sensitive surfaces.
 - **review-loop** — wraps every reviewer / security-reviewer invocation; runs the Concern Ledger + convergence detector.