cclaw-cli 0.51.27 → 0.51.29

package/dist/content/harness-doc.js

@@ -35,7 +35,7 @@ function perHarnessRecipeMarkdown() {
     const examples = recipes
         .map((recipe) => `**${recipe.harnessId}**:\n\n` + recipe.lifecycleCommands.map((cmd) => `    ${cmd}`).join("\n"))
         .join("\n\n");
-    return `\n\n## Per-Harness Lifecycle Recipe\n\n| Harness | Surface | Agent definition path | fulfillmentMode | Lifecycle |\n|---|---|---|---|---|\n${rows}\n\nNeutral placeholder tokens only: \`<agent-name>\`, \`<stage>\`, \`<run-id>\`, \`<span-id>\`, \`<dispatch-id>\`, \`<agent-def-path>\`, \`<iso-ts>\`, \`<artifact-anchor>\`. See \`docs/quality-gates.md\` for stage-by-stage gate mapping.\n\nThe four shipped harnesses (\`claude\`, \`cursor\`, \`opencode\`, \`codex\`) each ship with a canonical primary surface in the table above. The remaining enum values \`generic-task\`, \`role-switch\`, and \`manual\` are documented in the dispatch-surface table below and are available to any harness as fallback paths when the primary surface is unavailable.\n\n${examples}\n\n${dispatchSurfaceTableMarkdown()}\n\n### Legacy ledger upgrade\n\nPre-v3 ledger entries that lack a recorded \`dispatchSurface\` are tagged \`fulfillmentMode: "legacy-inferred"\` on read. Stage-complete blocks completion until those rows are re-recorded with the v3 helper:\n\n    node .cclaw/hooks/delegation-record.mjs \\\n      --rerecord \\\n      --span-id=<span-id> \\\n      --dispatch-id=<dispatch-id> \\\n      --dispatch-surface=<surface> \\\n      --agent-definition-path=<agent-def-path> \\\n      --ack-ts=<iso-ts> \\\n      --completed-ts=<iso-ts> \\\n      --json\n\n\`--dispatch-surface\` must be one of the values listed in the dispatch-surface table above (the enum is generated verbatim from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\`). Surfaces must align with the allowed agent-definition-path prefixes shown alongside each surface; \`role-switch\` and \`manual\` accept any path. The deprecated \`task\` surface is rejected.\n\n`;
+    return `\n\n## Per-Harness Lifecycle Recipe\n\n| Harness | Surface | Agent definition path | fulfillmentMode | Lifecycle |\n|---|---|---|---|---|\n${rows}\n\nNeutral placeholder tokens only: \`<agent-name>\`, \`<stage>\`, \`<run-id>\`, \`<span-id>\`, \`<dispatch-id>\`, \`<agent-def-path>\`, \`<iso-ts>\`, \`<artifact-anchor>\`. See \`docs/quality-gates.md\` for stage-by-stage gate mapping.\n\nThe four shipped harnesses (\`claude\`, \`cursor\`, \`opencode\`, \`codex\`) each ship with a canonical primary surface in the table above. Repair hints: \`cclaw sync\` safely regenerates shims/plugins/agents; Codex also needs \`[features] codex_hooks = true\`; OpenCode needs \`opencode.json(.c)\` plugin registration; role-switch completions require evidenceRefs. The remaining enum values \`generic-task\`, \`role-switch\`, and \`manual\` are documented in the dispatch-surface table below and are available to any harness as fallback paths when the primary surface is unavailable.\n\n${examples}\n\n${dispatchSurfaceTableMarkdown()}\n\n### Legacy ledger upgrade\n\nPre-v3 ledger entries that lack a recorded \`dispatchSurface\` are tagged \`fulfillmentMode: "legacy-inferred"\` on read. Stage-complete blocks completion until those rows are re-recorded with the v3 helper:\n\n    node .cclaw/hooks/delegation-record.mjs \\\n      --rerecord \\\n      --span-id=<span-id> \\\n      --dispatch-id=<dispatch-id> \\\n      --dispatch-surface=<surface> \\\n      --agent-definition-path=<agent-def-path> \\\n      --ack-ts=<iso-ts> \\\n      --completed-ts=<iso-ts> \\\n      --json\n\n\`--dispatch-surface\` must be one of the values listed in the dispatch-surface table above (the enum is generated verbatim from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\`). Surfaces must align with the allowed agent-definition-path prefixes shown alongside each surface; \`role-switch\` and \`manual\` accept any path. The deprecated \`task\` surface is rejected.\n\n`;
 }
 export function harnessIntegrationDocMarkdown() {
     const head = "# Harness Integration Matrix\n\nGenerated from `src/harness-adapters.ts` capabilities and hook event mappings.";

package/dist/content/hooks.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { RUNTIME_ROOT } from "../constants.js";
 import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES } from "../delegation.js";
-function resolveCliEntrypointForGeneratedHook() {
+function resolveCliRuntimeForGeneratedHook() {
     const here = fileURLToPath(import.meta.url);
     const candidates = [
         path.resolve(path.dirname(here), "..", "cli.js"),
@@ -13,12 +13,21 @@ function resolveCliEntrypointForGeneratedHook() {
         // Synchronous probe runs only during cclaw-cli init/sync generation.
         // The generated hook receives a concrete path and does not need a global bin.
         if (existsSync(candidate))
-            return candidate;
+            return { entrypoint: candidate, argsPrefix: [] };
     }
-    return null;
+    // Vitest exercises init/sync directly from src/ without a compiled dist/.
+    // Route that dev-only shape through vite-node so hooks still prove a local runtime.
+    if (process.env.VITEST === "true") {
+        const sourceCli = path.resolve(path.dirname(here), "..", "cli.ts");
+        const viteNode = path.resolve(path.dirname(here), "..", "..", "node_modules", "vite-node", "vite-node.mjs");
+        if (existsSync(sourceCli) && existsSync(viteNode)) {
+            return { entrypoint: viteNode, argsPrefix: ["--script", sourceCli] };
+        }
+    }
+    return { entrypoint: null, argsPrefix: [] };
 }
 function internalHelperScript(helperName, internalSubcommand, usage) {
-    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
+    const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -26,7 +35,8 @@ import process from "node:process";
 import { spawn } from "node:child_process";
 
 const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
-const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
+const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 const HELPER_NAME = ${JSON.stringify(helperName)};
 const INTERNAL_SUBCOMMAND = ${JSON.stringify(internalSubcommand)};
 const USAGE = ${JSON.stringify(usage)};
@@ -77,6 +87,7 @@ async function main() {
   }
 
   const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  const cliArgsPrefix = process.env.CCLAW_CLI_JS ? [] : CCLAW_CLI_ARGS_PREFIX;
   if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
     process.stderr.write(
       "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -88,6 +99,11 @@ async function main() {
   try {
     const stat = await fs.stat(cliEntrypoint);
     if (!stat.isFile()) throw new Error("not-file");
+    for (const argPath of cliArgsPrefix) {
+      if (typeof argPath !== "string" || argPath.startsWith("-")) continue;
+      const argStat = await fs.stat(argPath);
+      if (!argStat.isFile()) throw new Error("arg-not-file");
+    }
   } catch {
     process.stderr.write(
       "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -96,7 +112,7 @@ async function main() {
     return;
   }
 
-  const child = spawn(process.execPath, [cliEntrypoint, "internal", INTERNAL_SUBCOMMAND, ...flags], {
+  const child = spawn(process.execPath, [cliEntrypoint, ...cliArgsPrefix, "internal", INTERNAL_SUBCOMMAND, ...flags], {
     cwd: root,
     env: process.env,
     stdio: "inherit"
@@ -140,7 +156,7 @@ export function startFlowScript() {
     return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]");
 }
 export function stageCompleteScript() {
-    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
+    const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -148,7 +164,8 @@ import process from "node:process";
 import { spawn } from "node:child_process";
 
 const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
-const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
+const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 
 async function detectRoot() {
   const candidates = [
@@ -201,6 +218,7 @@ async function main() {
   }
 
   const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  const cliArgsPrefix = process.env.CCLAW_CLI_JS ? [] : CCLAW_CLI_ARGS_PREFIX;
   if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
     process.stderr.write(
       "[cclaw] stage-complete: local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -212,6 +230,11 @@ async function main() {
   try {
     const stat = await fs.stat(cliEntrypoint);
     if (!stat.isFile()) throw new Error("not-file");
+    for (const argPath of cliArgsPrefix) {
+      if (typeof argPath !== "string" || argPath.startsWith("-")) continue;
+      const argStat = await fs.stat(argPath);
+      if (!argStat.isFile()) throw new Error("arg-not-file");
+    }
   } catch {
     process.stderr.write(
       "[cclaw] stage-complete: local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -222,7 +245,7 @@ async function main() {
 
   const child = spawn(
     process.execPath,
-    [cliEntrypoint, "internal", "advance-stage", stage, ...flags],
+    [cliEntrypoint, ...cliArgsPrefix, "internal", "advance-stage", stage, ...flags],
     {
     cwd: root,
     env: process.env,

package/dist/content/ideate-command.js

@@ -77,7 +77,7 @@ ${frameBullets}
 5. **Adversarial critique pass.** For each candidate, write the strongest
    counter-argument, kill weak ideas, and keep survivors only.
 6. **Produce 5-10 survivors** with impact (High/Medium/Low),
-   effort (S/M/L), confidence (High/Medium/Low), and one evidence path per
+   effort (S/M/L), confidence (High/Medium/Low), **why now**, expected user impact, risk, and one evidence path per
    survivor.
 7. **Rank by impact/effort/confidence** using
    \`(impact points / effort cost) * confidence multiplier\` and recommend
@@ -209,8 +209,11 @@ Only survivors advance to ranking.
    - **Effort** — S / M / L
    - **Confidence** — High / Medium / Low
    - **Evidence** — path(s) or command output, inline if short
+   - **Why now** — timing signal from repo evidence, user friction, repeated knowledge, or blocked flow
+   - **Expected impact** — concrete user-facing benefit if this lands
+   - **Risk** — main implementation/product risk to manage
    - **Counter-argument** — strongest concern that survived
-   - **Proposed handoff** — exact \`/cc <phrase>\`
+   - **Next /cc prompt** — exact \`/cc <phrase>\` that starts the work
 3. Sort by score \`(impact points / effort cost) * confidence multiplier\`
    and break ties with rationale strength.
 4. Compute the artifact filename:
@@ -246,17 +249,19 @@ Only survivors advance to ranking.
 
    ## Ranked survivors
 
-   | ID | Improvement | Impact | Effort | Confidence | Evidence |
-   |---|---|---|---|---|---|
-| I-1 | Simplify a confusing generated prompt surface | High | S | High | <path-to-generated-surface> |
+   | ID | Improvement | Why now | Expected impact | Risk | Impact | Effort | Confidence | Evidence | Next /cc prompt |
+   |---|---|---|---|---|---|---|---|---|---|
+| I-1 | Simplify a confusing generated prompt surface | Repeated blocker in generated UX | Faster operator recovery | Might over-trim context | High | S | High | <path-to-generated-surface> | \`/cc Simplify the confusing generated prompt surface while preserving behavior\` |
    | …   | …                                  | …    | … | …    | …                                     |
 
    ## Candidate detail
 
 ### I-1 — Simplify a confusing generated prompt surface
 - **Evidence:** \`<path>\` contains repeated or stale guidance that a user would see.
-- **Counter-argument:** Trimming too hard can remove useful orientation for new users.
-- **Handoff:** \`/cc Simplify the confusing generated prompt surface while preserving behavior\`
+- **Why now:** The prompt is on the daily /cc path, so confusion compounds quickly.
+- **Expected impact:** Operators get a clearer next action without changing gates.
+- **Risk:** Trimming too hard can remove useful orientation for new users.
+- **Next /cc prompt:** \`/cc Simplify the confusing generated prompt surface while preserving behavior\`
 
    ### I-2 — …
    \`\`\`

package/dist/content/next-command.js

@@ -74,17 +74,17 @@ ${conversationLanguagePolicyMarkdown()}
 
 ## Algorithm (mandatory)
 
-1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
+1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing). Next action: run \`cclaw sync\` to safely regenerate generated runtime files, then \`cclaw doctor --explain\`; do not hand-edit state unless doctor says user repair is required.
 2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, do not advance automatically. Report the stale marker reason/rewindId, re-run the stage artifact work, then clear only the current stage marker with \`cclaw internal rewind --ack <currentStage>\`.
-4. Read **\`${reconciliationNoticesPath}\`** when present. If it contains entries for \`activeRunId + currentStage\` and the listed gate is still blocked in \`stageGateCatalog[currentStage].blocked\`, emit a structured warning before any stage-advance decision.
+3. If \`staleStages[currentStage]\` exists, do not advance automatically. Report \`Blocked by: stale stage\`, the marker reason/rewindId, the stage artifact work to re-run, and clear only the current stage marker with \`cclaw internal rewind --ack <currentStage>\` after rework.
+4. Read **\`${reconciliationNoticesPath}\`** when present. If it contains entries for \`activeRunId + currentStage\` and the listed gate is still blocked in \`stageGateCatalog[currentStage].blocked\`, emit \`Blocked by: reconciliation notice\` with gate id, reason, and next action \`cclaw doctor --reconcile-gates --explain\`. Clarify that reconciliation refreshes derived gate status only; it does not repair missing artifacts or tests.
 5. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
 6. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
 7. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
 8. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
 9. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if each mandatory agent is **completed** or **waived**.
 10. For each satisfied mandatory delegation row, verify \`evidenceRefs\` is a non-empty array (unless status is \`waived\` with rationale). Missing evidenceRefs means delegation is unresolved.
-11. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
+11. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch \`<agent>\` now or waive with rationale. State who must run, why the role is mandatory, whether the gap is ledger status, event-log dispatch proof, or artifact \`evidenceRefs\`, and do not mark gates passed while delegation is unresolved.
 12. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend the managed command \`cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"\`, and do not attempt to advance toward ship. After TDD rework, require \`cclaw internal rewind --ack tdd\` before continuing.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
@@ -109,7 +109,7 @@ ${ralphLoopContractSnippet()}
 
 \`flow-state.json\` carries a \`track\` field (\`"quick"\`, \`"medium"\`, or \`"standard"\`) and a \`skippedStages\` array.
 
-- 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 === "quick"\`, the critical path is **spec → tdd → review → ship**. Quick skips ceremony, not safety: spec approval, RED/GREEN/REFACTOR evidence, review, and ship gates still apply. 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 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.
@@ -190,13 +190,16 @@ Current: <currentStage or closeout.shipSubstate> (<track>)
 Stage: <currentStage>
 Gates: <passed>/<required> passed, <blocked> blocked
 Delegations: <done>/<mandatory> done
-Blocked by: <none | gate/delegation/reconciliation/stale/TDD/review ids>
+Blocked by: <none | gate/delegation/reconciliation/stale/TDD/review/closeout ids>
+Blocker category: <sync-recovery | user-decision | stage-work | delegation-proof | review-rework | closeout>
 Next: <exact next action, usually /cc-next or one named remediation>
 Evidence needed: <artifact/test/review/delegation evidence required to unblock>
 \`\`\`
 
 Only expand beyond this when blocked, when asking a structured question, or when
-the user explicitly requests detail. Do not dump full artifacts in progression output.
+the user explicitly requests detail. When blocked, name the blocker category,
+why it blocks progression, the one next command/action, and the exact proof that
+would unblock it. Do not dump full artifacts in progression output.
 
 **How it works:**
 1. Reads \`flow-state.json\` to find \`currentStage\`
@@ -216,9 +219,9 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 
 1. Open **\`${flowPath}\`**.
 2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, show the marker reason/rewindId, re-run the stage, and clear only the current marker via \`cclaw internal rewind --ack <currentStage>\` before advancing.
-4. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
-5. Read \`${reconciliationNoticesPath}\` when present. For entries matching \`activeRunId + currentStage\` whose gate is still in \`stageGateCatalog[currentStage].blocked\`, show a warning with gate id + reason before proceeding.
+3. If \`staleStages[currentStage]\` exists, show \`Blocked by: stale stage\`, the marker reason/rewindId, re-run the stage, and clear only the current marker via \`cclaw internal rewind --ack <currentStage>\` before advancing.
+4. If the file is missing or invalid JSON → **BLOCKED** (state missing/corrupt). Next action: run \`cclaw sync\` for safe regeneration of generated runtime files, then \`cclaw doctor --explain\`; do not hand-edit flow state unless doctor says user repair is required.
+5. Read \`${reconciliationNoticesPath}\` when present. For entries matching \`activeRunId + currentStage\` whose gate is still in \`stageGateCatalog[currentStage].blocked\`, show \`Blocked by: reconciliation notice\` with gate id + reason before proceeding; \`cclaw doctor --reconcile-gates --explain\` refreshes derived gate-state only; it does not repair missing artifacts or tests.
 
 ### Step 2: Evaluate gates
 
@@ -229,7 +232,8 @@ For each gate id in \`requiredGates\` for \`currentStage\`:
 Check \`mandatoryDelegations\` via **\`${delegationPath}\`** — satisfied only if **completed** or **waived**.
 Also verify each completed mandatory delegation row has non-empty \`evidenceRefs\` (waived rows must include rationale).
 If a mandatory delegation is missing and no waiver exists, **STOP** and ask:
-(A) dispatch now, (B) waive with rationale, (C) cancel stage advance.
+(A) dispatch \`<agent>\` now, (B) waive with rationale, (C) cancel stage advance.
+Explain who must run, why that role is mandatory for this stage, and whether the missing proof is ledger status, event-log dispatch proof, or artifact \`evidenceRefs\`. Waivers must include a user-visible safety reason.
 
 If reconciliation warnings were emitted in Step 1, treat them as a pre-advance stop point: require explicit acknowledgement before continuing Path A or Path B.
 
@@ -246,7 +250,7 @@ ${ralphLoopContractSnippet()}
 
 Special-case for review: if \`review_criticals_resolved\` is in \`blocked\`, route to rework instead of looping review forever - recommend \`cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"\`, then \`cclaw internal rewind --ack tdd\` after TDD rework.
 
-Special-case for TDD blockers: when \`06-tdd.md\` records \`NO_SOURCE_CONTEXT\`, \`NO_TEST_SURFACE\`, \`NO_IMPLEMENTABLE_SLICE\`, \`RED_NOT_EXPRESSIBLE\`, or \`NO_VCS_MODE\`, keep status BLOCKED and print \`Current\`, \`Blocked by\`, \`Next\`, and \`Evidence needed\` instead of retrying speculative RED/GREEN work.
+Special-case for TDD blockers: when \`06-tdd.md\` records \`NO_SOURCE_CONTEXT\`, \`NO_TEST_SURFACE\`, \`NO_IMPLEMENTABLE_SLICE\`, \`RED_NOT_EXPRESSIBLE\`, or \`NO_VCS_MODE\`, keep status BLOCKED and print \`Current\`, \`Blocked by\`, \`Next\`, \`Repair path\`, and \`Evidence needed\` instead of retrying speculative RED/GREEN work. RED blockers need a runnable failing test surface, GREEN blockers need passing full-suite evidence, REFACTOR blockers need behavior-preservation evidence.
 
 **Path B — stage IS complete (all gates met, all delegations done):**
 
@@ -272,7 +276,7 @@ Otherwise (non-terminal \`next\`): load the next stage skill and begin execution
 
 ## Stage order
 
-This table is the track-aware critical path. It must match \`flow-state.json.track\`; do not follow the natural schema edge when the active track skips a stage. After \`ship\`, \`/cc-next\` continues closeout via ${closeoutSubstateInline()}: ${closeoutChainInline()}.
+This table is the track-aware critical path. It must match \`flow-state.json.track\`; do not follow the natural schema edge when the active track skips a stage. Quick skips ceremony, not safety: spec approval, RED/GREEN/REFACTOR evidence, review, and ship gates still apply. After \`ship\`, \`/cc-next\` continues closeout via ${closeoutSubstateInline()}: ${closeoutChainInline()}.
 
 | Stage | Standard next | Medium next | Quick next | Skill path |
 |---|---|---|---|---|

package/dist/content/node-hooks.js

@@ -10,7 +10,7 @@ function normalizePatterns(patterns, fallback) {
         return [...fallback];
     return patterns.map((value) => value.trim()).filter((value) => value.length > 0);
 }
-function resolveCliEntrypointForGeneratedHook() {
+function resolveCliRuntimeForGeneratedHook() {
     const here = fileURLToPath(import.meta.url);
     const candidates = [
         path.resolve(path.dirname(here), "..", "cli.js"),
@@ -19,9 +19,18 @@ function resolveCliEntrypointForGeneratedHook() {
     for (const candidate of candidates) {
         // Synchronous probe runs only during cclaw-cli init/sync generation.
         if (existsSync(candidate))
-            return candidate;
+            return { entrypoint: candidate, argsPrefix: [] };
     }
-    return null;
+    // Vitest exercises init/sync directly from src/ without a compiled dist/.
+    // Route that dev-only shape through vite-node so hooks still prove a local runtime.
+    if (process.env.VITEST === "true") {
+        const sourceCli = path.resolve(path.dirname(here), "..", "cli.ts");
+        const viteNode = path.resolve(path.dirname(here), "..", "..", "node_modules", "vite-node", "vite-node.mjs");
+        if (existsSync(sourceCli) && existsSync(viteNode)) {
+            return { entrypoint: viteNode, argsPrefix: ["--script", sourceCli] };
+        }
+    }
+    return { entrypoint: null, argsPrefix: [] };
 }
 /**
  * Node-only hook runtime (single entrypoint).
@@ -42,7 +51,7 @@ export function nodeHookRuntimeScript(options = {}) {
         options.compoundRecurrenceThreshold >= 1
         ? options.compoundRecurrenceThreshold
         : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
-    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
+    const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -64,7 +73,8 @@ const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS = ${JSON.stringify(tddProductionPathP
 const COMPOUND_RECURRENCE_THRESHOLD = ${JSON.stringify(compoundRecurrenceThreshold)};
 const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD)};
 const SMALL_PROJECT_RECURRENCE_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_RECURRENCE_THRESHOLD)};
-const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
+const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 
 function resolveStrictness() {
   return process.env.CCLAW_STRICTNESS === "strict" ? "strict" : DEFAULT_STRICTNESS;
@@ -313,6 +323,7 @@ async function readStdin() {
 
 async function runCclawInternal(root, args, options = {}) {
   const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  const cliArgsPrefix = process.env.CCLAW_CLI_JS ? [] : CCLAW_CLI_ARGS_PREFIX;
   if (!cliEntrypoint || String(cliEntrypoint).trim().length === 0) {
     return {
       code: 1,
@@ -324,6 +335,11 @@ async function runCclawInternal(root, args, options = {}) {
   try {
     const stat = await fs.stat(cliEntrypoint);
     if (!stat.isFile()) throw new Error("not-file");
+    for (const argPath of cliArgsPrefix) {
+      if (typeof argPath !== "string" || argPath.startsWith("-")) continue;
+      const argStat = await fs.stat(argPath);
+      if (!argStat.isFile()) throw new Error("arg-not-file");
+    }
   } catch {
     return {
       code: 1,
@@ -345,7 +361,7 @@ async function runCclawInternal(root, args, options = {}) {
     };
     let child;
     try {
-      child = spawn(process.execPath, [cliEntrypoint, "internal", ...args], {
+      child = spawn(process.execPath, [cliEntrypoint, ...cliArgsPrefix, "internal", ...args], {
         cwd: root,
         env: process.env,
         stdio: ["ignore", captureStdout ? "pipe" : "ignore", "pipe"]

package/dist/content/opencode-plugin.js

@@ -131,7 +131,7 @@ export default function cclawPlugin(ctx) {
     if (stageSupport.length > 0) parts.push(...stageSupport);
 
     parts.push(
-      "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. Direct JSONL append is only for explicit manual learnings operations."
+      "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. If this plugin does not load, run \`cclaw sync\`, verify opencode.json(.c) includes the cclaw plugin registration, then run \`cclaw doctor --explain\`. Direct JSONL append is only for explicit manual learnings operations."
     );
 
     const meta = (await readFileText(metaSkillPath)).trim();

package/dist/content/stages/review.js

@@ -47,7 +47,7 @@ export const REVIEW = {
             "Classify findings — Critical (blocks ship), Important (should fix), Suggestion (optional improvement).",
             "Victory Detector — before verdict, confirm Layer 1, Layer 2, security sweep, structured findings, trace evidence, and unresolved-critical status are complete; otherwise iterate findings or route back to TDD.",
             "Produce verdict — APPROVED, APPROVED_WITH_CONCERNS, or BLOCKED.",
-            "If verdict is BLOCKED, emit remediation route token `ROUTE_BACK_TO_TDD`, include the managed command `cclaw internal rewind tdd \"review_blocked_by_critical <finding-ids>\"`, and satisfy the special transition guard `review_verdict_blocked` instead of `review_criticals_resolved`. After TDD rework, clear the stale marker with `cclaw internal rewind --ack tdd` before `/cc-next`."
+            "If verdict is BLOCKED, emit remediation route token `ROUTE_BACK_TO_TDD`, include the managed command `cclaw internal rewind tdd \"review_blocked_by_critical <finding-ids>\"`, list the critical finding IDs and required TDD evidence to repair, and satisfy the special transition guard `review_verdict_blocked` instead of `review_criticals_resolved`. After TDD rework, clear the stale marker with `cclaw internal rewind --ack tdd` before `/cc-next`."
         ],
         interactionProtocol: [
             "Run Layer 1 (spec compliance) completely before starting Layer 2.",

package/dist/content/stages/tdd.js

@@ -118,7 +118,7 @@ export const TDD = {
             "full suite not green",
             "behavior changed during refactor",
             "no evidence recorded",
-            "RED/GREEN blocked — classify with the managed taxonomy `NO_SOURCE_CONTEXT`, `NO_TEST_SURFACE`, `NO_IMPLEMENTABLE_SLICE`, `RED_NOT_EXPRESSIBLE`, or `NO_VCS_MODE` and capture blockedBecause, missingInputs, recommendedRoute, nextCommand, and resumeCriteria.",
+            "RED/GREEN blocked — classify with the managed taxonomy `NO_SOURCE_CONTEXT`, `NO_TEST_SURFACE`, `NO_IMPLEMENTABLE_SLICE`, `RED_NOT_EXPRESSIBLE`, or `NO_VCS_MODE` and capture blockedBecause, missingInputs, recommendedRoute, nextCommand, resumeCriteria, and the repair path: RED needs a failing test surface, GREEN needs full-suite pass evidence, REFACTOR needs behavior-preservation evidence.",
             "no-VCS workspace without explicit `vcs: none`, no-vcs reason, content/artifact hash, or `tdd.verificationRef: disabled`"
         ],
         exitCriteria: [

package/dist/content/start-command.js

@@ -74,18 +74,19 @@ ${conversationLanguagePolicyMarkdown()}
 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. **Track heuristic** — classify the idea text and **recommend** a track (the user can override 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** (\`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. Be explicit that this recommendation is advisory until the user accepts and the managed helper writes state; after that, \`/cc-next\` follows the configured track.
+   - 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-next\` follows the configured track.
 8. Present one compact **Start framing** summary: class, recommended track, 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. Present the recommendation as a single decision with explicit options:
    > \`Recommended track: <quick|medium|standard>\` because \`<one-line reason citing matched triggers>\`.
-   > Override? (A) keep \`<recommended>\`  (B) switch track  (C) cancel.
+   > \`Safety retained: <spec/TDD/review/ship gates that still apply>\`.
+   > Override? (A) keep \`<recommended>\`  (B) switch track with reason  (C) cancel.
    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> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
@@ -179,12 +180,12 @@ ${conversationLanguagePolicyMarkdown()}
 
    | 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 |
+   | \`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 |
 
    - 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-next\` follows the selected track.
+   - 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-next\` 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. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP and report the exact command/output; do not manually edit flow state.
 9. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for medium/standard, \`specification-authoring\` for quick) plus its matching command file.
 

package/dist/content/state-contracts.js

@@ -12,7 +12,7 @@ const REQUIRED_TOP_LEVEL_FIELDS = {
 };
 const STAGE_TAXONOMIES = {
     brainstorm: {
-        approachTier: ["Lightweight", "Standard", "Deep"],
+        approachTier: ["Lightweight", "Standard", "Deep", "lite", "standard", "deep"],
         approachRole: ["baseline", "challenger", "wild-card"],
         approachUpside: ["low", "modest", "high", "higher"]
     },

package/dist/content/status-command.js

@@ -28,7 +28,8 @@ export function statusSubcommandMarkdown() {
 ## Overview
 
 \`/cc-view status\` is the quickest way to answer "where are we in the flow?" without
-advancing or mutating anything. Safe to run at any point. The snapshot reflects:
+advancing or mutating anything. Treat it as an operator note, not a JSON dump:
+progress, blockers, risks, next action, and human-readable gate/delegation/closeout labels. Safe to run at any point. The snapshot reflects:
 
 - progress across stages with per-stage markers,
 - gate coverage,
@@ -88,10 +89,10 @@ a read-only command.
 
 - Keep output compact (≤ 40 lines) — status, not narrative.
 - Start with the same operator rows as \`/cc-next\` when possible:
-  \`Current\`, \`Stage\`, \`Gates\`, \`Delegations\`, \`Blocked by\`, \`Next\`, \`Evidence needed\`.
+  \`Current\`, \`Stage\`, \`Progress\`, \`Gates\`, \`Delegations\`, \`Risks\`, \`Blocked by\`, \`Next\`, \`Evidence needed\`. Use labels like \`gate: tdd_green_full_suite\`, \`delegation proof: reviewer evidenceRefs\`, and \`closeout: compound_review\` instead of raw JSON tone.
 - When blocked, include a plain-English action block:
   \`Current: <stage or closeout substate>\`; \`Blocked by: <gate/delegation/blocker code>\`; \`Next: <exact command or managed remediation>\`; \`Evidence needed: <artifact/test/review/delegation evidence>\`.
-- Report counts, not full artifact contents. Include active subagent count from \`${subagentsPath()}\` and proof gaps from \`${delegationEventsPath()}\` when present.
+- Report counts, not full artifact contents. Include active subagent count from \`${subagentsPath()}\` and proof gaps from \`${delegationEventsPath()}\` when present. Convert gate/delegation state into human labels: \`passed\`, \`blocked\`, \`missing proof\`, \`waived with reason\`, \`stale\`, \`ready to advance\`, or the closeout substate label.
 - If any data source is missing or corrupt, say so explicitly rather than guessing.
 - Include \`/cc-view tree\` for deep structure and \`/cc-view diff\` for before/after map in the final line.
 

package/dist/content/track-render-context.d.ts

@@ -5,6 +5,7 @@ export interface TrackRenderContext {
     traceabilitySourceNoun: string;
     traceabilityIdNoun: string;
     traceabilitySliceNoun: string;
+    safetySummary: string;
     upstreamArtifactLabel: string;
     upstreamArtifactPath: string;
 }

package/dist/content/track-render-context.js

@@ -9,6 +9,7 @@ export function trackRenderContext(track) {
             traceabilitySourceNoun: "acceptance criterion",
             traceabilityIdNoun: "acceptance criterion ID",
             traceabilitySliceNoun: "acceptance slice",
+            safetySummary: "quick skips ceremony, not safety: spec approval, TDD, review, and ship gates remain mandatory",
             upstreamArtifactLabel: "spec artifact",
             upstreamArtifactPath: ".cclaw/artifacts/04-spec.md"
         };
@@ -19,6 +20,7 @@ export function trackRenderContext(track) {
         traceabilitySourceNoun: "plan task",
         traceabilityIdNoun: "plan task ID",
         traceabilitySliceNoun: "plan slice",
+        safetySummary: "full upstream planning safety remains in the active track",
         upstreamArtifactLabel: "plan artifact",
         upstreamArtifactPath: ".cclaw/artifacts/05-plan.md"
     };

package/dist/doctor-registry.d.ts

@@ -1,8 +1,10 @@
 export type DoctorSeverity = "error" | "warning" | "info";
+export type DoctorActionGroup = "sync" | "user-action" | "stage-work" | "informational";
 export interface DoctorCheckMetadata {
     severity: DoctorSeverity;
     summary: string;
     fix: string;
+    actionGroup: DoctorActionGroup;
     docRef?: string;
 }
 export declare function doctorCheckMetadata(checkName: string): DoctorCheckMetadata;