cclaw-cli 7.7.0 → 8.1.0

package/dist/content/start-command.js

@@ -1,236 +1,250 @@
-import { RUNTIME_ROOT } from "../constants.js";
-import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
-const START_SKILL_FOLDER = "flow-start";
-const START_SKILL_NAME = "flow-start";
-function flowStatePath() {
-    return `${RUNTIME_ROOT}/state/flow-state.json`;
-}
-/**
- * Command contract for /cc — the unified entry point.
- * No args → reads existing flow state and progresses it when a tracked flow
- * already exists; missing state/fresh placeholder state blocks with
- * init/start guidance. With prompt → classifies the idea, asks for one discovery mode,
- * resolves the internal track, and starts the first stage of that track (brainstorm for medium/standard, spec for quick).
- */
-export function startCommandContract() {
-    const flowPath = flowStatePath();
-    return `# /cc
-
-## Purpose
-
-**The unified entry point for the cclaw flow.**
-
-- \`/cc\` (no arguments) → reads existing flow state and resumes/progresses the active flow. If flow state is missing or still a fresh init placeholder, stop and guide the user to run \`/cc <prompt>\` or \`npx cclaw-cli init\`; do not silently create a brainstorm run.
-- \`/cc <prompt>\` (with an idea/description) → saves the prompt as idea context, asks for one discovery mode, and starts the first stage of the resolved internal track.
-
-This is the **recommended way to start, resume, and continue** working with cclaw.
-
-## HARD-GATE
-
-${conversationLanguagePolicyMarkdown()}
-- **Do not** skip reading \`${flowPath}\` — always check current state before acting.
-- **Do not** start implementation stages directly from \`/cc <prompt>\` — always begin at the first stage of the resolved track (brainstorm for medium/standard, spec for quick).
-- **Do not** start a stage pipeline for a task that is not a software change (pure question, non-software task, conversation).
-
-## Algorithm
-
-### With prompt (\`/cc <text>\`)
-
-1. **Phase 0 — Task classification.** Before any stage routing, classify the prompt:
-
-   | Class | Signals | Action |
-   |---|---|---|
-   | **non-software** | legal text / docs / marketing copy / meeting notes / therapy-style conversation | Respond directly, do NOT open a stage, do NOT mutate flow state. |
-   | **pure-question** | "how does X work?", "explain Y", "what are the trade-offs of Z?" | Answer directly, do NOT open a stage. |
-   | **trivial** | typo, one-liner, rename, config tweak, copy change, version bump with zero behavior change | Fast-path: set track to \`quick\`, seed \`00-idea.md\`, and enter \`spec\`. Runtime quick never starts at design. |
-   | **software — bug fix with repro** | regression / hotfix / named symptom + repro steps | Fast-path: set track to \`quick\`, enter \`spec\`, and capture a reproduction contract first. TDD later writes the RED reproduction test from that contract. |
-   | **software — medium** | additive feature following existing architecture | medium track (\`brainstorm → spec → plan → tdd → review → ship\`). |
-   | **software — standard** | feature, refactor, migration, integration, architecture change | Full 8-stage flow starting at \`brainstorm\`. |
-
-   Record the chosen class in \`.cclaw/artifacts/00-idea.md\` on the \`Class:\` line. Do NOT silently treat a non-software task as software.
-
-2. **Phase 0.5 — Seed shelf recall.** Before routing, scan \`${RUNTIME_ROOT}/seeds/SEED-*.md\` and match each seed's \`trigger_when\` tokens against the prompt text (substring match is enough). If any match:
-   - Surface up to 3 matches (file + title + one-line action) as \`Seed recalls\`.
-   - Ask whether to apply now, keep as reference, or ignore for this run.
-   - If applied/reference, append selected seeds to \`00-idea.md\` under \`Discovered context\` so downstream stages keep the trace.
-
-3. **Phase 1 — Origin-document discovery.** Before asking the user for context, scan for existing requirements/plan artifacts and merge them into initial context:
-   - \`.cclaw/artifacts/00-idea.md\` if it already exists (resumed flow).
-   - Common origin locations: \`docs/prd/**\`, \`docs/rfcs/**\`, \`docs/adr/**\`, \`docs/design/**\`, \`specs/**\`, \`prd/**\`, \`rfc/**\`, \`design/**\`, root-level \`PRD.md\` / \`SPEC.md\` / \`DESIGN.md\` / \`REQUIREMENTS.md\` / \`ROADMAP.md\`.
-   - Summarize each discovered doc in \`00-idea.md\` under a \`Discovered context\` section with path + 1-line summary.
-   - If an origin doc contradicts the prompt, surface the conflict to the user before routing.
-
-4. **Phase 2 — Tech-stack + version detection.** Sniff the repo for stack + language versions and record under \`Stack:\`:
-   - Node: \`package.json\` \`engines\` / \`volta\` / \`packageManager\` / \`devDependencies\`.
-   - Python: \`pyproject.toml\` / \`requirements*.txt\` / \`.python-version\`.
-   - Go: \`go.mod\` (module + Go version).
-   - Rust: \`Cargo.toml\` (\`[package]\` + \`rust-version\`).
-   - Java/Kotlin: \`pom.xml\` / \`build.gradle*\` + toolchain version.
-   - Containers: \`Dockerfile\`, \`docker-compose*.yml\`.
-   - CI: \`.github/workflows\`, \`.gitlab-ci.yml\`.
-   Skip detection quietly if no markers are found — do NOT invent a stack.
-
-5. Read \`${flowPath}\`.
-6. If flow already has completed stages, warn the user that starting a new tracked flow will reset progress. Ask for confirmation before proceeding. A fresh init placeholder state with \`completedStages: []\`, no passed gates, and no \`00-idea.md\` is **not** an active flow; do not ask the user to resume it.
-7. **Internal track heuristic** — classify the idea text and compute an internal track recommendation before any state mutation:
-   - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of the built-in defaults. Evaluation order is always \`standard -> medium -> quick\` (narrow-to-broad).
-   - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known. Quick skips ceremony, not safety: spec approval, TDD evidence, review, and ship gates remain mandatory.
-     Triggers (case-insensitive substring or close variant): \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`copy change\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`config tweak\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`.
-   - **medium** (\`brainstorm → spec → plan → tdd → review → ship\`) — additive work that fits existing architecture and still needs product framing.
-     Triggers: \`add endpoint\`, \`add field\`, \`extend existing\`, \`wire integration\`, \`small migration\`, \`new screen following existing patterns\`.
-   - **standard** (full 8 stages — default fallback) — anything that introduces a new capability with architecture uncertainty, touches many modules, or has unclear scope.
-     Triggers: \`new feature\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`integrate\`, \`workflow\`, \`onboarding\`, or any prompt that does not match quick/medium confidently.
-   - When triggers conflict, prefer **standard** over **medium**, and **medium** over **quick**.
-   - Report **track selection confidence** as high/medium/low with the matched trigger or fallback reason, plus one sentence explaining what the selected track skips and what safety gates remain. Be explicit that this recommendation is advisory until the user accepts and the managed helper writes state; after that, \`/cc\` follows the configured track.
-8. Present one compact **Start framing** summary: class, internal track recommendation, track selection confidence, stack, origin docs, seed recalls, and the recommended next action. Ask a single confirmation question only when there is a destructive reset, a real contradiction, or ambiguous software/non-software classification.
-9. Ask one explicit **discovery mode** question and make it the only normal start-of-run user choice:
-   > \`Choose discovery mode: Lean / Guided / Deep\`.
-   > \`Lean\` = compact shaping, \`Guided\` = recommended default with enough questions and key specialists before drafting, \`Deep\` = stronger probing and broader specialist/research passes.
-   > Mention the internal track recommendation only as context, not as the primary decision. Offer track override only when reset, contradiction, or reclassification evidence makes the internal recommendation suspect.
-   Normalize the user's answer before calling the start helper: \`trim\`, lower-case, map UI labels to \`lean\` / \`guided\` / \`deep\` only; if the answer is not one of those three, re-ask the same question once with the compact definitions. In \`flow-state.json\`, persist only the canonical lowercase token (never \`Deep\`/\`Guided\` casing).
-   If the user prompt is one short line (at most 12 words) and the workspace matches an empty-repo signal set — either \`flow-state.repoSignals\` from the last successful \`start-flow\` shows \`fileCount < 5\` with \`hasReadme\` and \`hasPackageManifest\` both false, OR (before any \`start-flow\` yet) a shallow scan finds no root \`README.md\`, no root \`package.json\`/\`pyproject.toml\`/\`Cargo.toml\`, and fewer than five relevant files excluding \`node_modules\`/\`.git\` — recommend \`guided\` and ask for explicit confirmation before defaulting to \`deep\`.
-   If the harness's native ask tool is available (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`), send exactly ONE question; on schema error, fall back to a plain-text lettered list.
-10. Start the tracked flow only through the managed helper:
-   \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --discovery-mode=<lean|guided|deep> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
-   If this helper fails, STOP. Report one human-readable failure line from the JSON \`error\` field, include the helper JSON payload in a fenced \`json\` block, and never echo the invoking command line. Do **not** manually edit \`${flowPath}\`.
-11. The helper persists \`${flowPath}\`, computes \`skippedStages\`, sets the first stage for the track, resets the gate catalog, and writes \`.cclaw/artifacts/00-idea.md\`.
-12. Load the **first-stage skill for the chosen track** and its command file:
-    - quick → \`.cclaw/skills/spec/SKILL.md\`
-    - medium/standard → \`.cclaw/skills/brainstorm/SKILL.md\`
-    - trivial fast-path → quick track spec skill per Phase 0 decision.
-13. Execute that stage with the prompt + Phase 1/Phase 2 + seed context as initial input.
-
-### Reclassification on discovery
-
-If during any stage the agent discovers evidence that contradicts the initial Phase 0 / track decision (e.g. a supposedly \`trivial\` change turns out to require schema migration, a \`quick\` bug fix turns out to need design discussion, an origin doc reveals scope 3× larger than the prompt), STOP and re-classify:
-
-1. Surface the new evidence in plain text.
-2. Propose the updated \`Class\`, internal \`Track\`, and (when discovery posture should change) \`Discovery mode\` with a one-line reason.
-3. Use the Decision Protocol to let the user accept, override, or cancel.
-4. On acceptance: run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --discovery-mode=<lean|guided|deep> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report one human-readable line plus the helper JSON payload in a fenced \`json\` block; never echo the invoking command line. Do NOT manually edit \`flow-state.json\`.
-
-### Without prompt (\`/cc\`)
-
-1. Read \`${flowPath}\`.
-2. If flow state is missing → guide the user to run \`npx cclaw-cli init\` and stop.
-3. If flow state is only a fresh init placeholder (\`completedStages: []\`, all \`passed\` arrays empty, and no \`00-idea.md\`) → stop and ask for \`/cc <prompt>\` to start a tracked run. Do not create a brainstorm state implicitly.
-4. Otherwise check current stage gates, resume if incomplete, and advance if complete.
-5. **TDD wave dispatch:** When \`currentStage\` is \`tdd\`, run \`node .cclaw/cli.mjs internal wave-status --json\` first, then read the managed **Parallel Execution Plan** block inside \`${RUNTIME_ROOT}/artifacts/05-plan.md\` plus \`${RUNTIME_ROOT}/artifacts/wave-plans/\` for detail. Resume partial waves on remaining members only.
-
-   **The controller preserves TDD evidence.** When \`topology: parallel-builders\` and \`pathConflicts: []\`, fan out the ready independent units in a SINGLE controller message: one harness \`Task(subagent_type=…, description="slice-builder S-<id>", prompt=<full slice context>)\` call per routed builder, **side by side in the same tool batch**. Each \`slice-builder\` span owns the full RED → GREEN → REFACTOR → DOC cycle for its feature-atomic unit and emits its own \`delegation-record --phase=red|green|refactor|refactor-deferred|doc\` rows. RED-before-GREEN is enforced per-slice by the linter.
-
-   When \`mode: blocked\` with \`pathConflicts\`, surface exactly one AskQuestion that lets the user resolve the overlap (drop / split / serialize). When \`topology: single-builder\`, dispatch one \`Task\` for the next ready unit. When \`topology: inline\`, execute inline only if the same RED/GREEN/REFACTOR evidence and path/commit gates can be satisfied.
-
-6. **Auto-advance after stage-complete:** when \`stage-complete\` returns \`ok\` with a new \`currentStage\`, immediately load the next stage skill and continue without waiting for the user to retype \`/cc\`. Announce \`Stage <prev> complete → entering <next>. Continuing.\` and proceed.
-
-## Headless mode (CI/automation only)
-
-Headless envelopes are a machine-mode exception for CI/automation orchestration.
-In normal interactive runs, respond in natural language instead of emitting an envelope.
-When called by another skill or subagent in machine mode, emit exactly one JSON envelope (no prose) and stop:
+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 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 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
+---
+\`\`\``;
+export const START_COMMAND_BODY = `# /cc — cclaw orchestrator
 
-\`\`\`json
-{"version":"1","kind":"stage-output","stage":"<currentStage>","payload":{"command":"/cc","track":"<track>","action":"start_or_resume"},"emittedAt":"<ISO-8601>"}
-\`\`\`
+You are the cclaw orchestrator. The user's request is: ${"`{{TASK}}`"}.
 
-Validate envelopes with:
-\`npx cclaw-cli internal envelope-validate --stdin\`
+This document is your operating manual. Follow it in order. Skipping a step usually surfaces later as a failed gate.
 
-## Primary skill
+## Step 0 — Sanity check
 
-**${RUNTIME_ROOT}/skills/${START_SKILL_FOLDER}/SKILL.md**
+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:
 
-## Surface reference
+> "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."
 
-Use the start skill plus \`.cclaw/state/flow-state.json\` for orientation before \`/cc <prompt>\` runs.
-`;
-}
-/**
- * Skill body for /cc — the unified entry point.
- */
-export function startCommandSkillMarkdown() {
-    const flowPath = flowStatePath();
-    return `---
-name: ${START_SKILL_NAME}
-description: "Unified entry point for the cclaw flow. No args = resume/next. With prompt = classify, pick track, start its first stage."
----
+Do not auto-migrate. Do not delete state on the user's behalf.
+
+## Step 1 — Existing-plan detection
+
+Glob \`.cclaw/flows/*/plan.md\` (skip \`shipped/\` and \`cancelled/\`) and \`.cclaw/flows/shipped/*/plan.md\`. For each match:
+
+- 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\`.
+
+Then ask the user one of:
+
+- **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.
+
+Refinement always lives inside \`/cc\`. There is no \`/cc-amend\`. There is no auto-merge with the prior plan; the user picks.
+
+## Step 2 — Phase 0 calibration
+
+Ask the user **once**:
+
+> "Targeted change in one place, or a feature spanning multiple components?"
+
+Combine the answer with these heuristics to pick a routing class:
+
+| 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 answer disagrees with the heuristic, prefer the **larger** class — agents underestimate scope more often than they overestimate.
+
+## Step 3 — Specialist routing (large / risky only)
+
+Ask the user once which specialists to invoke. Default proposal:
+
+> "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."
+
+After the choice, run the selected specialists **sequentially with a checkpoint between each**:
+
+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.
+
+The user can stop after any checkpoint and proceed with what is already in \`plan.md\`.
+
+Available specialists (with modes):
+
+${SPECIALIST_LIST}
+
+\`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.
 
-# /cc — Flow Entry Point
+## Step 4 — Plan template
 
-## Overview
+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.
 
-\`/cc\` is the **starting command** for cclaw. It intelligently routes:
+${PLAN_FRONTMATTER_EXAMPLE}
 
-- **No arguments** → resumes or progresses an existing tracked flow; missing/fresh placeholder state blocks with start guidance
-- **With a prompt** → classifies the task, asks for one discovery mode (lean/guided/deep), resolves an internal track (quick/medium/standard), and starts the **first stage of that track** (not always brainstorm — e.g. the \`quick\` track starts at \`spec\`)
+For a refinement, set \`refines\` to the parent slug:
 
-## HARD-GATE
+${REFINEMENT_EXAMPLE}
 
-Do **not** silently discard an existing flow when the user provides a prompt. If completed stages exist, inform and confirm before resetting. A freshly initialized placeholder state with \`completedStages: []\`, no passed gates, and no \`${RUNTIME_ROOT}/artifacts/00-idea.md\` is not an active flow; classify the prompt and start normally.
+## Step 5 — Build (TDD cycle)
 
-${conversationLanguagePolicyMarkdown()}
-## Protocol
+**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).
 
-### Path A: \`/cc <prompt>\`
+For each AC:
 
-1. **Task classification (Phase 0).** Decide whether the prompt is \`software-standard\`, \`software-trivial\`, \`software-bugfix\`, \`pure-question\`, or \`non-software\`. Non-software and pure-question exit immediately — answer directly, do not open a stage. Bugfixes with a clear repro still start on quick \`spec\`: capture the reproduction contract first, then TDD writes the RED reproduction test from that contract.
-2. **Seed shelf recall (Phase 0.5).** Scan \`${RUNTIME_ROOT}/seeds/SEED-*.md\` and match \`trigger_when\` tokens against the prompt text. Surface up to 3 matching seeds with file/title/action and ask whether to apply or ignore. When applied, add them to \`00-idea.md\` under \`Discovered context\`.
-3. **Origin-document discovery (Phase 1).** Scan for \`docs/prd/**\`, \`docs/rfcs/**\`, \`docs/adr/**\`, \`docs/design/**\`, \`specs/**\`, root-level \`PRD.md\` / \`SPEC.md\` / \`DESIGN.md\` / \`REQUIREMENTS.md\`. Summarize any hits in \`00-idea.md\` under \`Discovered context\`. Surface conflicts with the prompt before routing.
-4. **Stack detection (Phase 2).** Inspect \`package.json\` engines, \`pyproject.toml\`, \`go.mod\`, \`Cargo.toml\`, \`pom.xml\`, \`build.gradle*\`, \`Dockerfile\`, \`docker-compose*.yml\`, and CI configs. Record stack + versions on the \`Stack:\` line. Do not invent stack details.
-5. Read \`${flowPath}\`.
-6. If \`completedStages\` is non-empty:
-   - Inform: "You have an active flow at stage **{currentStage}** with {N} completed stages. Starting a new tracked flow will reset progress."
-   - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
-   - If (B) → switch to Path B behavior.
-   If \`completedStages\` is empty, all gate \`passed\` arrays are empty, and \`${RUNTIME_ROOT}/artifacts/00-idea.md\` is missing, treat it as a fresh init placeholder — do **not** ask whether to continue the current flow.
-7. **Classify the idea** using the heuristic below and present one compact Start framing summary (class, internal track recommendation, stack, origin docs, seed recalls, next action). Wait for explicit confirmation or override before mutating any state only when reset/conflict/ambiguity makes it necessary.
-   - If \`${RUNTIME_ROOT}/config.yaml\` defines \`trackHeuristics\`, apply those vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of built-in defaults. Evaluation order is fixed: \`standard -> medium -> quick\`. (Honest note: this is advisory prose; the LLM applies it, not a Node-level router.)
+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:
 
-   **Track heuristic** (lowercase substring match against the user prompt):
+${COMMIT_HELPER_EXAMPLE}
 
-   | Track | Triggers | Use when |
-   |---|---|---|
-   | \`quick\` | \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`, \`copy change\` | Single-purpose, spec is essentially known, low blast radius; skips ceremony, not safety |
-   | \`medium\` | \`add endpoint\`, \`add field\`, \`extend existing\`, \`wire integration\`, \`small migration\`, \`new screen following existing pattern\` | Additive work with existing architecture |
-   | \`standard\` | \`new feature\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`integrate\`, \`workflow\`, \`onboarding\` (or no confident quick/medium match) | New or uncertain multi-module work |
+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.
 
-   - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
-   - Always state the recommendation as a one-line reason citing matched triggers and a high/medium/low track selection confidence. Clarify that the heuristic is advisory until the managed helper writes state; after that, \`/cc\` follows the selected track. Include override guidance: switch to standard when architecture, schema, migration, security, or unclear scope appears; switch to medium when product framing is needed but architecture is known.
-8. Ask for the single explicit start choice: \`Lean / Guided / Deep\`. Use \`Guided\` as the recommended default unless the user clearly wants compact shaping or unusually deep probing. Keep track internal unless contradiction/reset/reclassification requires surfacing an override.
-   Normalize the answer (\`trim\`, lower-case) to exactly \`lean\` / \`guided\` / \`deep\` before invoking the start helper; re-ask once if the reply is not one of those. Pass only canonical lowercase tokens to \`--discovery-mode\`.
-   If the prompt is one short line (at most 12 words) and the workspace matches an empty-repo signal set — either persisted \`repoSignals\` has \`fileCount < 5\` with \`hasReadme\` and \`hasPackageManifest\` false, OR a shallow scan before the first \`start-flow\` shows the same — recommend \`guided\` and confirm before defaulting to \`deep\`.
-9. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --discovery-mode=<lean|guided|deep> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, including \`discoveryMode\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP, report one human-readable failure line from the JSON \`error\` field, and include the helper JSON payload in a fenced \`json\` block; do not echo the invoking command line, and do not manually edit flow state.
-10. Load and execute the **first stage skill of the chosen track** (\`brainstorm\` for medium/standard, \`spec\` for quick) plus its matching command file.
+\`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.
 
-### Reclassification on discovery
+> **Iron Law:** NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. The RED failure is the spec.
+
+Never call \`git commit\` directly. The hook is the only path that keeps AC ↔ commit traceability and the TDD cycle intact.
+
+### Step 5a — Parallel-build dispatch (when planner declared it)
+
+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.
+
+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\`).
+
+For each slice:
+
+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.
+
+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.
+
+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.
+
+### When to use sub-agents (and when not to)
+
+Use sub-agents for:
+
+- **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.
+
+Do **not** use sub-agents for:
+
+- 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.
+
+## Step 6 — Review
+
+Run \`reviewer\` (and \`security-reviewer\` when relevant). Five Failure Modes are mandatory:
+
+${failureModesChecklist()}
+
+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.
+
+Block-level findings → \`slice-builder\` runs in \`fix-only\` mode against the cited file:path:line list, then re-review.
+
+## Step 7 — Ship
+
+Write \`ships/<slug>.md\` from \`.cclaw/lib/templates/ship.md\` with release notes, the AC ↔ commit map, and push/PR refs.
+
+**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.
+
+If the user approves \`git push\`, do that one action and stop. Do not proactively open a PR after pushing unless the user asked.
+
+## Step 8 — Compound (automatic)
+
+After ship, automatically check the compound quality gate. Capture \`learnings/<slug>.md\` only if at least one signal is present:
+
+- 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:
+
+1. Write \`learnings/<slug>.md\` from \`.cclaw/lib/templates/learnings.md\`.
+2. Append one line to \`.cclaw/knowledge.jsonl\`:
+
+\`\`\`json
+{"slug":"approval-page","ship_commit":"abc1234","shipped_at":"2026-05-07T18:30:00Z","signals":{"hasArchitectDecision":true,"reviewIterations":2,"securityFlag":false,"userRequestedCapture":false}}
+\`\`\`
 
-If mid-stage evidence contradicts the initial Class/Track/Discovery decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --discovery-mode=<lean|guided|deep> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. If it fails, report one human-readable line plus the helper JSON payload in a fenced \`json\` block, never echo the invoking command line, and do not rewrite prior artifacts or manually edit flow-state.
+## Step 9 — Active → shipped move
 
-### Path B: \`/cc\` (no arguments)
+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=[]\`.
 
-Progress the tracked flow only when one exists:
+## Always-ask rules
 
-1. Read \`${flowPath}\`.
-2. If missing, guide the user to run \`npx cclaw-cli init\` and stop.
-3. If it is only a fresh init placeholder (\`completedStages: []\`, no passed gates, and no \`${RUNTIME_ROOT}/artifacts/00-idea.md\`), stop and ask for \`/cc <prompt>\` to start a tracked run. Do not silently create a brainstorm run.
-4. Check gates for \`currentStage\`.
-5. **TDD:** When \`currentStage\` is \`tdd\`, run \`wave-status --json\`, then reconcile the managed **Parallel Execution Plan** in \`05-plan.md\` with \`wave-plans/wave-NN.md\`. Route by \`nextDispatch.topology\`: \`parallel-builders\` fans out independent units in one controller message, \`single-builder\` dispatches one builder, \`inline\` executes directly only with equivalent evidence, and \`strict-micro\` preserves tiny-slice sequencing. If \`mode: blocked\`, resolve overlaps first. Each delegated \`slice-builder\` span owns its full RED → GREEN → REFACTOR → DOC cycle. Mirror plan \`dependsOn\` ordering between waves.
-6. **Wave resume:** Parallelize unfinished members; never restart completed lanes. Integration-overseer follows \`integrationCheckRequired\`; when skipped, emit \`cclaw_integration_overseer_skipped\` per the hook contract.
-7. If incomplete → load current stage skill and execute.
-8. If complete → advance to next stage and execute. **Auto-advance:** when \`stage-complete\` returns \`ok\`, immediately load the next stage skill and continue without waiting for the user to retype \`/cc\`.
-9. If flow is done → report completion.
+- 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.
 
-## Public flow habit
+## Skills attached
 
-Use \`/cc\` for the happy path:
+The following skills auto-trigger during this flow. Do not re-explain them; obey them.
 
-| Scenario | Command |
-|---|---|
-| Starting work for the first time | \`/cc\` or \`/cc <idea>\` |
-| Resuming in a new session | \`/cc\` |
-| Progressing after completing a stage | \`/cc\` |
-| Starting with a specific idea | \`/cc <idea>\` |
+- **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.
+- **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.
+- **refinement** — when an existing plan match is detected.
+- **parallel-build** — when planner topology is \`parallel-build\`; enforces the 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.
 
-\`/cc <prompt>\` resolves class + internal track, asks for one discovery mode, and starts the selected track's first stage; \`/cc\` without a prompt follows the current \`flow-state.json\`.
+${ironLawsMarkdown()}
 `;
+export function renderStartCommand() {
+    return START_COMMAND_BODY;
 }