cclaw-cli 0.51.21 → 0.51.23

package/README.md

@@ -344,8 +344,9 @@ 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, on Codex / OpenCode, role-switched with
-`evidenceRefs` — see [Harness support](#harness-support)).
+subagent as `completed`. Codex and OpenCode use generated native subagents
+by default; a role-switch row is only a degraded fallback and must include
+`evidenceRefs` — see [Harness support](#harness-support).
 
 ---
 
@@ -391,25 +392,25 @@ closes every real gap with a documented fallback — not a silent waiver.
 |---|---|---|---|---|
 | Claude Code | full (named subagents) | `native` | full | `AskUserQuestion` |
 | Cursor | generic Task dispatcher | `generic-dispatch` | full | `AskQuestion` |
-| OpenCode | plugin / in-session | `role-switch` | plugin | `question` (permission-gated; `permission.question: "allow"`) |
-| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | limited (Bash-only `PreToolUse`/`PostToolUse`; requires `codex_hooks` feature flag) | `request_user_input` (experimental; Plan / Collaboration mode) |
+| OpenCode | native subagents (`.opencode/agents`) | `native` | plugin | `question` (permission-gated; `permission.question: "allow"`) |
+| OpenAI Codex | native parallel subagents (`.codex/agents`) | `native` | limited (Bash-only `PreToolUse`/`PostToolUse`; requires `codex_hooks` feature flag) | `request_user_input` (experimental; Plan / Collaboration mode) |
 
 What the fallbacks mean:
 
-- `native` — Claude runs mandatory delegations in isolated subagent
-  workers; cclaw records them with `fulfillmentMode: "isolated"`.
+- `native` — Claude, OpenCode, and Codex run 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.
-- `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.
+- `role-switch` — degraded fallback only when the active runtime cannot
+  expose its declared dispatch surface. The agent announces
+  `## cclaw role-switch: <stage>/<agent> (<mode>)`, loads
+  `.cclaw/agents/<agent>.md`, writes outputs to the stage artifact, and
+  records a delegation row with `fulfillmentMode: "role-switch"` plus at
+  least one `evidenceRef`. A role-switch `completed` row without
+  evidenceRefs is classified as `missingEvidence` by `cclaw doctor`.
 - `waiver` — reserved. Only fires auto-waivers if every installed
   harness declares it. Currently unused — v0.33 removed the old
   Codex-only auto-waiver path.

package/dist/config.d.ts

@@ -1,4 +1,11 @@
 import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack } from "./types.js";
+export interface ConfigWarningState {
+    emitted: Set<string>;
+}
+export interface ReadConfigOptions {
+    warningState?: ConfigWarningState;
+}
+export declare function createConfigWarningState(): ConfigWarningState;
 export declare class InvalidConfigError extends Error {
     constructor(message: string);
 }
@@ -34,7 +41,7 @@ export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrac
  * never surprise a user who intentionally cleared the list.
  */
 export declare function detectLanguageRulePacks(projectRoot: string): Promise<LanguageRulePack[]>;
-export declare function readConfig(projectRoot: string): Promise<CclawConfig>;
+export declare function readConfig(projectRoot: string, options?: ReadConfigOptions): Promise<CclawConfig>;
 /**
  * Fields that live on the populated runtime `CclawConfig` but are considered
  * "advanced" — we keep them in the in-memory object so downstream callers

package/dist/config.js

@@ -56,13 +56,15 @@ const MINIMAL_CONFIG_KEYS = [
 ];
 const DEFAULT_SLICE_REVIEW_THRESHOLD = 5;
 const DEFAULT_SLICE_REVIEW_TRACKS = ["standard"];
-const emittedConfigWarnings = new Set();
-function emitConfigWarningOnce(code, message) {
+export function createConfigWarningState() {
+    return { emitted: new Set() };
+}
+function emitConfigWarningOnce(warningState, code, message) {
     const key = `${code}:${message}`;
-    if (emittedConfigWarnings.has(key)) {
+    if (warningState.emitted.has(key)) {
         return;
     }
-    emittedConfigWarnings.add(key);
+    warningState.emitted.add(key);
     process.emitWarning(message, { code });
 }
 function sameStringArray(a, b) {
@@ -196,7 +198,8 @@ export async function detectLanguageRulePacks(projectRoot) {
     }
     return [...new Set(detected)];
 }
-export async function readConfig(projectRoot) {
+export async function readConfig(projectRoot, options = {}) {
+    const warningState = options.warningState ?? createConfigWarningState();
     const fullPath = configPath(projectRoot);
     if (!(await exists(fullPath))) {
         return createDefaultConfig();
@@ -269,7 +272,7 @@ export async function readConfig(projectRoot) {
     if (tddTestGlobsRaw !== undefined &&
         explicitTddTestPathPatterns !== undefined &&
         !sameStringArray(tddTestGlobs, explicitTddTestPathPatterns)) {
-        emitConfigWarningOnce("CCLAW_CONFIG_DEPRECATED_TDD_TEST_GLOBS", `[cclaw] Both "tddTestGlobs" (deprecated) and "tdd.testPathPatterns" are set in ${fullPath}. ` +
+        emitConfigWarningOnce(warningState, "CCLAW_CONFIG_DEPRECATED_TDD_TEST_GLOBS", `[cclaw] Both "tddTestGlobs" (deprecated) and "tdd.testPathPatterns" are set in ${fullPath}. ` +
             `Using "tdd.testPathPatterns".`);
     }
     const resolvedTddTestPathPatterns = [

package/dist/content/examples.js

@@ -726,8 +726,8 @@ const DOMAIN_LABELS = {
 export const RESEARCH_FLEET_USAGE_EXAMPLE = [
     "Before drafting `03-design.md`, run `research/research-fleet.md` once and",
     "capture all four lenses in `.cclaw/artifacts/02a-research.md`.",
-    "Dispatch semantics by harness: Claude/Cursor = parallel subagents in one turn;",
-    "OpenCode/Codex = sequential role-switch with explicit announcements.",
+    "Dispatch semantics by harness: Claude/OpenCode/Codex = native subagents;",
+    "Cursor = generic-dispatch Task mapping; role-switch only as degraded fallback.",
     "Design must include a `Research Fleet Synthesis` section that maps each",
     "lens to concrete architecture decisions and risks."
 ].join(" ");

package/dist/content/hook-manifest.d.ts

@@ -45,14 +45,12 @@ export interface HookHandlerSpec {
     description: string;
     /**
      * Semantic event id used by `HOOK_EVENTS_BY_HARNESS` / docs.
-     * `null` means this handler contributes no semantic coverage row
-     * (e.g. `verify-current-state` on codex is a supplementary guard,
-     * not a top-level semantic event).
+     * `null` means this handler contributes no semantic coverage row.
      */
     semantic: HookSemanticEvent | null;
     bindings: Partial<Record<HookManifestHarness, HookBinding[]>>;
 }
-export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_handoff", "precompact_compat"];
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_handoff", "precompact_compat", "strict_state_verify"];
 export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
 export declare const HOOK_MANIFEST: readonly HookHandlerSpec[];
 export interface EventGroup {

package/dist/content/hook-manifest.js

@@ -35,7 +35,8 @@ export const HOOK_SEMANTIC_EVENTS = [
     "pre_tool_workflow_guard",
     "post_tool_context_monitor",
     "stop_handoff",
-    "precompact_compat"
+    "precompact_compat",
+    "strict_state_verify"
 ];
 export const HOOK_MANIFEST = [
     {
@@ -73,10 +74,7 @@ export const HOOK_MANIFEST = [
         bindings: {
             claude: [{ event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash" }],
             cursor: [{ event: "preToolUse", matcher: "*" }],
-            codex: [
-                { event: "UserPromptSubmit" },
-                { event: "PreToolUse", matcher: "Bash|bash" }
-            ]
+            codex: [{ event: "PreToolUse", matcher: "Bash|bash" }]
         }
     },
     {
@@ -112,8 +110,8 @@ export const HOOK_MANIFEST = [
     },
     {
         handler: "verify-current-state",
-        description: "Supplementary codex guard that runs on UserPromptSubmit to assert the live state matches the flow.",
-        semantic: null,
+        description: "Supplementary Codex strict-mode guard that runs on UserPromptSubmit to assert the live state matches the flow.",
+        semantic: "strict_state_verify",
         bindings: {
             codex: [{ event: "UserPromptSubmit" }]
         }

package/dist/content/learnings.js

@@ -78,7 +78,7 @@ Do not invent alternate stores (no markdown mirror, no SQLite, no per-stage file
 
 Exactly one JSON object per line. Required fields must appear in the order:
 \`type, trigger, action, confidence, domain, stage, origin_stage, origin_run, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`.
-Optional fields \`source\` and \`severity\` may be appended after \`project\`.
+Optional fields \`source\`, \`severity\`, \`supersedes\`, and \`superseded_by\` may be appended after \`project\`.
 
 \`\`\`json
 {"type":"pattern","trigger":"when reviewing external payloads","action":"parse through zod before touching service layer","confidence":"high","domain":"api","stage":"review","origin_stage":"review","origin_run":"payload-hardening","frequency":1,"universality":"project","maturity":"raw","created":"2026-04-14T12:00:00Z","first_seen_ts":"2026-04-14T12:00:00Z","last_seen_ts":"2026-04-14T12:00:00Z","project":"cclaw"}
@@ -103,12 +103,15 @@ Optional fields \`source\` and \`severity\` may be appended after \`project\`.
 | \`project\` | string \\| null | yes | Repo or scope name. Use \`null\` when the entry crosses projects. |
 | \`source\` | \`"stage" \\| "retro" \\| "compound" \\| "ideate" \\| "manual" \\| null\` | no | Origin channel for the entry when known. |
 | \`severity\` | \`"critical" \\| "important" \\| "suggestion"\` | no | Priority signal for compound lifts; \`critical\` enables single-hit override in compound readiness analysis. |
+| \`supersedes\` | string[] | no | Non-empty IDs/slugs of older entries this entry refreshes. Use only for clear replacements discovered during compound closeout or curation. |
+| \`superseded_by\` | string | no | Non-empty ID/slug of the newer entry that refreshes this one. Use only when marking stale guidance as replaced. |
 
 Rules:
 - No other fields beyond the table above. Extra keys are forbidden and MUST be rejected by any writer.
 - Every required-null field must be emitted explicitly as \`null\` (not omitted). This keeps the file grep-friendly.
 - Append-only: never rewrite or delete a historical line. Corrections are new
-  entries whose \`trigger\` clearly supersedes the earlier one.
+  entries whose \`trigger\` clearly supersedes the earlier one; add \`supersedes\` /
+  \`superseded_by\` only when the replacement relationship is clear.
 - Keep each entry one line. No pretty-printing. No trailing commas.
 
 ## Curation policy (target: ≤ 50 active entries)

package/dist/content/meta-skill.d.ts

@@ -1,2 +1,3 @@
 export declare const META_SKILL_NAME = "using-cclaw";
+export declare const META_SKILL_GENERATED_HELPER_SKILLS: readonly ["subagent-dev", "parallel-dispatch", "session", "iron-laws"];
 export declare function usingCclawSkillMarkdown(): string;

package/dist/content/meta-skill.js

@@ -1,6 +1,15 @@
 import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 import { CLOSEOUT_CHAIN, closeoutChainInline, closeoutFlowMapSentence, closeoutProtocolBehaviorSentence } from "./closeout-guidance.js";
 export const META_SKILL_NAME = "using-cclaw";
+export const META_SKILL_GENERATED_HELPER_SKILLS = [
+    "subagent-dev",
+    "parallel-dispatch",
+    "session",
+    "iron-laws"
+];
+function generatedHelperSkillList() {
+    return META_SKILL_GENERATED_HELPER_SKILLS.map((name) => `\`${name}\``).join(", ");
+}
 export function usingCclawSkillMarkdown() {
     return `---
 name: using-cclaw
@@ -14,7 +23,7 @@ description: "Routing brain for cclaw. Decide whether to start/resume a stage, a
 1. User message in current turn.
 2. Active stage skill and command contract.
 3. This routing file.
-4. Contextual utility skills.
+4. Generated cclaw helper skills, research playbooks, and enabled rule packs.
 5. Default model behavior.
 
 If the user explicitly overrides a stage rule, record it in the artifact.
@@ -25,9 +34,7 @@ ${conversationLanguagePolicyMarkdown()}
 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).
+from memory. Load only generated helper surfaces that actually exist in this install: ${generatedHelperSkillList()}, research playbooks, review prompts, or enabled language rule packs under \`.cclaw/rules/lang/\`. Do not invent helper-skill names beyond those generated surfaces.
 
 Substantive vs. non-substantive:
 
@@ -70,7 +77,7 @@ Task arrives
 | Class | Route |
 |---|---|
 | non-trivial software work | \`/cc <idea>\` |
-| trivial software fix | \`/cc <idea>\` (quick/medium track as recommended) |
+| trivial software fix | \`/cc <idea>\` (quick track) |
 | bugfix with clear repro | \`/cc <idea>\` and enforce RED-first in tdd |
 | pure question / conversation | answer directly |
 | non-software work | answer directly |
@@ -115,10 +122,10 @@ Use the current stage skill plus \`.cclaw/state/flow-state.json\` for orientatio
 
 Use built-in judgment only when triggered by the current task:
 
-- security, performance, debugging, docs, and CI/CD review lenses
-- verification discipline before completion claims
-- branch-finishing discipline during ship/finalization
-- iron-laws as policy arbitration when instructions conflict
+- generated subagent context skills for mandatory review/delegation contracts
+- research playbooks and review prompts when a stage explicitly calls for them
+- inline verification and ship/finalization sections in the active stage skill
+- \`iron-laws\` as policy arbitration when instructions conflict
 - language rule packs from \`.cclaw/config.yaml\` when enabled
 
 ## Protocol Behavior

package/dist/content/next-command.js

@@ -112,7 +112,7 @@ ${ralphLoopContractSnippet()}
 - If \`track === "quick"\`, the critical path is **spec → tdd → review → ship**. When advancing, skip any stage listed in \`skippedStages\` — i.e. after the current stage completes, pick the next stage that is NOT in \`skippedStages\`.
 - If \`track === "medium"\`, the critical path is **brainstorm → spec → plan → tdd → review → ship**. Scope and design are intentionally skipped unless the run is reclassified to standard.
 - If \`track === "standard"\`, advance through all 8 stages in their natural order.
-- Never reintroduce a skipped stage mid-run. If the user wants upstream scoping work, they must archive the run and start a new one with \`track: "standard"\`.
+- Never manually reintroduce a skipped stage mid-run. If evidence shows the track was wrong, stop and use the managed start-flow helper with \`--reclassify\`; only that managed reclassification may add upstream stages back into the active track.
 
 ## Resume Semantics
 
@@ -130,7 +130,7 @@ When orchestrated by another skill/subagent, emit exactly one JSON envelope and
 no narrative text:
 
 \`\`\`json
-{"version":"1","kind":"gate-result","stage":"review","payload":{"command":"/cc-next","decision":"resume_or_advance","nextStage":"ship"},"emittedAt":"<ISO-8601>"}
+{"version":"1","kind":"gate-result","stage":"<currentStage>","payload":{"command":"/cc-next","decision":"resume_or_advance","nextStage":"<nextStage>"},"emittedAt":"<ISO-8601>"}
 \`\`\`
 
 Validate envelopes with:

package/dist/content/node-hooks.js

@@ -1117,12 +1117,21 @@ async function handleStopHandoff(runtime) {
     return 1;
   }
 
+  const closeoutObj = toObject(state.raw.closeout) || {};
+  const shipSubstate = typeof closeoutObj.shipSubstate === "string" ? closeoutObj.shipSubstate : "idle";
+  const closeoutContext =
+    state.currentStage === "ship" || shipSubstate !== "idle"
+      ? " closeout.shipSubstate=" + shipSubstate + "; closeout chain=retro -> compound -> archive; continue closeout with /cc-next."
+      : "";
+
   const message =
     "Cclaw: session ending (stage=" +
     state.currentStage +
     ", run=" +
     state.activeRunId +
-    "). Active artifacts stay in " +
+    ")." +
+    closeoutContext +
+    " Active artifacts stay in " +
     RUNTIME_ROOT +
     "/artifacts until archive. Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match current intent, (3) if you discovered a non-obvious rule/pattern during stage work, add it to the current artifact ## Learnings section so stage-complete can harvest it, (4) commit or revert pending changes.";
 
@@ -1627,7 +1636,7 @@ async function handleVerifyCurrentState(runtime) {
     process.stderr.write(result.stderr.trim().length > 0
       ? result.stderr
       : "[cclaw] hook: local Node runtime entrypoint is required for verify-current-state\\n");
-    return 1;
+    return mode === "strict" ? 1 : 0;
   }
   if (mode === "strict") {
     if (result.code !== 0) {
@@ -1650,9 +1659,10 @@ async function handleVerifyCurrentState(runtime) {
 function normalizeHookName(rawName) {
   const value = normalizeText(rawName).toLowerCase();
   if (value === "session-start") return "session-start";
-  if (value === "stop-handoff") return "stop-handoff";
+  if (value === "stop-handoff" || value === "stop") return "stop-handoff";
   if (value === "stop-checkpoint") return "stop-handoff";
-  if (value === "pre-compact") return "pre-compact";
+  if (value === "pre-compact" || value === "precompact") return "pre-compact";
+  if (value === "session-rehydrate") return "session-start";
   if (value === "prompt-guard") return "prompt-guard";
   if (value === "workflow-guard") return "workflow-guard";
   if (value === "context-monitor") return "context-monitor";

package/dist/content/review-loop.js

@@ -456,6 +456,9 @@ export function buildReviewLoopEnvelope(args) {
 function formatScore(value) {
     return clampScore(value).toFixed(3);
 }
+function reviewLoopHeading(stage) {
+    return stage === "scope" ? "Scope Outside Voice Loop" : "Design Outside Voice Loop";
+}
 function finalEnvelopeScore(envelope) {
     if (envelope.iterations.length === 0)
         return 0;
@@ -486,7 +489,8 @@ export function renderReviewLoopSummarySection(envelope) {
         })
             .join("\n")
         : "| 0 | 0.000 | 0 |";
-    return `## Spec Review Loop
+    const heading = reviewLoopHeading(envelope.stage);
+    return `## ${heading}
 | Iteration | Quality Score | Findings |
 |---|---|---|
 ${rows}
@@ -498,9 +502,14 @@ ${rows}
 export function upsertReviewLoopSummary(markdown, envelope) {
     const withHeader = upsertReviewLoopHeader(markdown, envelope);
     const section = renderReviewLoopSummarySection(envelope);
-    const headingRe = /^##\s+Spec Review Loop\s*$/m;
-    const match = headingRe.exec(withHeader);
-    if (!match || match.index < 0) {
+    const headingCandidates = [reviewLoopHeading(envelope.stage), "Spec Review Loop"];
+    const match = headingCandidates
+        .map((heading) => {
+        const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+        return new RegExp(`^##\\s+${escapedHeading}\\s*$`, "m").exec(withHeader);
+    })
+        .find((candidate) => candidate !== null && candidate.index >= 0);
+    if (!match) {
         const needsBreak = withHeader.endsWith("\n") ? "" : "\n";
         return `${withHeader}${needsBreak}\n${section}\n`;
     }
@@ -613,7 +622,8 @@ function parseHeaderMeta(markdown) {
     };
 }
 export function extractReviewLoopEnvelopeFromArtifact(markdown, stage, artifactPath) {
-    const sectionBody = extractH2Section(markdown, "Spec Review Loop");
+    const sectionBody = extractH2Section(markdown, reviewLoopHeading(stage))
+        ?? extractH2Section(markdown, "Spec Review Loop");
     if (!sectionBody)
         return null;
     const iterations = parseIterationsTable(sectionBody);

package/dist/content/review-prompts.js

@@ -57,7 +57,7 @@ value. Do not nitpick wording.
 
 ## Output
 
-Record in \`## Outside Voice Findings\` or \`## Spec Review Loop\`:
+Record in \`## Outside Voice Findings\` or the stage-specific outside voice loop section:
 
 \`\`\`markdown
 | ID | Dimension | Finding | Disposition | Rationale |

package/dist/content/skills.js

@@ -61,23 +61,24 @@ function autoSubagentDispatchBlock(stage, track) {
     const rules = stageAutoSubagentDispatch(stage);
     if (rules.length === 0)
         return "";
+    const schema = stageSchema(stage, track);
     const rows = rules
         .map((rule) => {
         const userGate = rule.requiresUserGate ? "required" : "not required";
-        return `| ${rule.agent} | ${rule.mode} | ${userGate} | ${rule.when} |`;
+        return `| ${rule.agent} | ${rule.mode} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
     })
         .join("\n");
-    const mandatory = stageSchema(stage, track).mandatoryDelegations;
+    const mandatory = schema.mandatoryDelegations;
     const mandatoryList = mandatory.length > 0 ? mandatory.map((a) => `\`${a}\``).join(", ") : "none";
     const delegationLogRel = `${RUNTIME_ROOT}/state/delegation-log.json`;
+    const artifactRef = `${RUNTIME_ROOT}/artifacts/${schema.artifactRules.artifactFile}`;
     return `## Automatic Subagent Dispatch
-
-| Agent | Mode | User Gate | Trigger |
-|---|---|---|---|
+| Agent | Mode | User Gate | Trigger | Purpose |
+|---|---|---|---|---|
 ${rows}
-
-Mandatory delegations for this stage: ${mandatoryList}.
-Record completion/waiver in \`${delegationLogRel}\` before stage completion.
+Mandatory: ${mandatoryList}. Record completion/waiver in \`${delegationLogRel}\` before completion.
+### Harness Dispatch Contract
+Use true harness dispatch: Claude native Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\`, Codex \`.codex/agents/<agent>.toml\`. Run independent read-only/review agents in parallel where safe, write evidence into \`${artifactRef}\`, then append \`${delegationLogRel}\` rows with matching \`fulfillmentMode: "isolated"\` or \`"generic-dispatch"\`. Do not collapse OpenCode or Codex to role-switch by default; role-switch is degraded fallback and must carry non-empty \`evidenceRefs\`. Missing evidence blocks completion.
 `;
 }
 function researchPlaybooksBlock(playbooks) {
@@ -160,15 +161,18 @@ function batchExecutionModeBlock(stage, track) {
     const schema = stageSchema(stage, track);
     if (!schema.batchExecutionAllowed)
         return "";
+    const orderingGuidance = track === "quick"
+        ? "Use spec acceptance items / bug reproduction slices for ordering."
+        : "Use plan slices for ordering.";
     return `## Batch Execution Mode
 
 Execute the current dependency batch task-by-task (RED -> GREEN -> REFACTOR).
 Stop on BLOCKED status or when user input is required.
-Apply concise turn announces: one announce per batch boundary (or when risk/plan
+Apply concise turn announces: one announce per batch boundary (or when risk/source
 changes materially), then execute tasks without repetitive boilerplate.
 
 Detailed walkthrough:
-Use the current plan artifact for batch order and keep RED -> GREEN -> REFACTOR evidence in the TDD artifact.
+${orderingGuidance} Keep RED -> GREEN -> REFACTOR evidence in the TDD artifact.
 `;
 }
 function crossStageTraceBlock(trace) {
@@ -386,6 +390,7 @@ ${philosophy.purpose}
 
 ## Complexity Tier
 - Active tier: \`${schema.complexityTier}\`
+- Scale-to-complexity rule: execute required gates and artifact sections, but keep optional/deep sections compact unless risk, novelty, or configuration triggers them. Do not mechanically expand lightweight work into a strategy workshop.
 - Mandatory delegations at this tier: ${mandatoryDelegationSummary}
 - Track render context: \`${trackContext.track}\` (${trackContext.usesPlanTerminology ? "plan-first wording" : "acceptance-first wording"})
 
@@ -452,7 +457,7 @@ ${reviewLens.outputs.map((item) => `- ${item}`).join("\n")}
 ${reviewSectionsBlock(reviewLens.reviewSections)}
 
 ## Shared Stage Guidance
-- Follow the handoff menu: advance, revise, pause, rewind, or archive only when the user explicitly chooses it.
+- At STOP/closeout points, offer the shared handoff choices only when a user decision is needed.
 - Carry upstream decisions forward explicitly; record drift instead of silently changing direction.
 - Before closeout, fill \`## Learnings\` with \`- None this stage.\` or 1-3 strict JSON bullets.
 - Keep decisions explicit: context, options, chosen option, rationale, risk, and rollback.

package/dist/content/stage-command.d.ts

@@ -0,0 +1,2 @@
+import type { FlowStage } from "../types.js";
+export declare function stageCommandShimMarkdown(stage: FlowStage): string;

package/dist/content/stage-command.js

@@ -0,0 +1,17 @@
+import { RUNTIME_ROOT } from "../constants.js";
+import { stageSkillFolder } from "./skills.js";
+export function stageCommandShimMarkdown(stage) {
+    const skillPath = `${RUNTIME_ROOT}/skills/${stageSkillFolder(stage)}/SKILL.md`;
+    return `# /cc-${stage}
+
+This is a thin compatibility shim for the \`${stage}\` flow stage.
+
+Load and follow the authoritative stage skill:
+
+- \`${skillPath}\`
+
+Normal stage resume and advancement uses \`/cc-next\`. Use \`/cc-next\` to read
+\`.cclaw/state/flow-state.json\`, select the active stage, and advance only after
+that stage's gates pass. Do not duplicate the stage protocol here.
+`;
+}

package/dist/content/stage-schema.js

@@ -227,6 +227,7 @@ const REQUIRED_GATE_IDS = {
     review: (track) => [
         "review_layer1_spec_compliance",
         "review_layer2_security",
+        "review_layer_coverage_complete",
         "review_criticals_resolved",
         "review_army_json_valid",
         ...(track === "quick" ? [] : ["review_trace_matrix_clean"])

package/dist/content/stages/brainstorm.js

@@ -40,10 +40,10 @@ export const BRAINSTORM = {
             "**Classify depth and scope** — pick Lightweight / Standard / Deep; decompose independent subsystems before deeper work.",
             "**Premise check (one pass)** — answer the three gstack-style questions in the artifact body: *Right problem? Direct path? What if we do nothing?* Take a position; do not hedge.",
             "**Reframe with How Might We** — write a single `How Might We …?` line that names the user, the desired outcome, and the constraint. This is the altitude check before approaches.",
-            "**Sharpening questions (3-5)** — capture decision-changing question/answer pairs in the `Sharpening Questions` table with the actual decision impact; if a question would not change architecture/scope/UX, state the assumption and skip it.",
+            "**Sharpening questions (3-5)** — capture decision-changing question/answer pairs in the `Sharpening Questions` table with the actual decision impact; only non-critical preference/default assumptions may continue. STOP and ask on scope, architecture, security, data loss, public API, migration, auth/pricing, or user-approval uncertainty.",
             "**Use compact discovery for simple apps** — for concrete low-risk asks (todo app, landing page, local widget), do one context pass, compare one baseline and one challenger, then ask for one explicit approval; do not drag the user through a full workshop.",
             "**Short-circuit concrete asks** — for unambiguous implementation-only requests, write a compact brainstorm stub (context, problem, approved intent, constraints, assumptions) and ask for one explicit approval.",
-            "**Ask only decision-changing questions** — one at a time; if answers would not change approach, state the assumption and continue.",
+            "**Ask only decision-changing questions** — one at a time; if answers would not change approach and are non-critical preference/default assumptions, state the assumption and continue; STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval uncertainty.",
             "**Compare 2-3 distinct approaches with stable Role/Upside columns** — Role values are `baseline` | `challenger` | `wild-card`; Upside is `low` | `modest` | `high` | `higher`; include real trade-offs and reuse notes; include exactly one challenger with explicit `high` or `higher` upside.",
             "**Collect reaction before recommending** — ask which option feels closest and what concern remains, then recommend based on that reaction.",
             "**Write the `Not Doing` list** — name 3-5 things this brainstorm explicitly is not committing to (vs. deferred). This protects scope from silent enlargement and the next stage from rework.",
@@ -55,7 +55,7 @@ export const BRAINSTORM = {
             "Start from observed project context; if the idea is vague, first narrow the project type with **one** structured question, then keep going.",
             "Lead with the premise check (right problem / direct path / what if nothing) and the `How Might We` reframing before approaches; both go in the artifact, not just the chat.",
             "Ask at most one question per turn, only when decision-changing; if using a structured question tool, send exactly one question object, not a multi-question form.",
-            "If likely answers do not change architecture or scope boundaries, choose the default and state the assumption inline.",
+            "Only non-critical preference/default assumptions may continue inline. STOP and ask when uncertainty affects scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval.",
             "For simple greenfield web apps, present a compact A/B choice with one recommended path and one higher-upside challenger; keep the artifact concise but structurally complete (Context, Premise, How Might We, Sharpening Questions, Approaches, Reaction, Selected Direction, Not Doing).",
             "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",
             "Self-review before approval: re-read the artifact, fix contradictions/placeholders/weak trade-offs, then ask for approval. Do not ask for approval on a draft you have not re-read.",