cclaw-cli 0.51.28 → 0.51.30

package/dist/cli.d.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import type { FlowTrack, HarnessId } from "./types.js";
+import type { ArchiveDisposition } from "./runs.js";
+export { parseHarnessSelectionAnswer } from "./harness-selection.js";
 type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive" | "internal";
 interface ParsedArgs {
     command?: CommandName;
@@ -15,6 +17,8 @@ interface ParsedArgs {
     archiveName?: string;
     archiveSkipRetro?: boolean;
     archiveSkipRetroReason?: string;
+    archiveDisposition?: ArchiveDisposition;
+    archiveDispositionReason?: string;
     /** Hidden plumbing command (`cclaw internal ...`) arguments. */
     internalArgs?: string[];
     showHelp?: boolean;
@@ -23,5 +27,6 @@ interface ParsedArgs {
 export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseTrack(raw: string): FlowTrack;
+declare function parseArchiveDisposition(raw: string): ArchiveDisposition;
 declare function parseArgs(argv: string[]): ParsedArgs;
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseArchiveDisposition, parseHarnesses, parseTrack };

package/dist/cli.js

@@ -8,11 +8,13 @@ import { doctorChecks, doctorSucceeded } from "./doctor.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { error, info } from "./logger.js";
 import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
-import { archiveRun } from "./runs.js";
+import { ARCHIVE_DISPOSITIONS, archiveRun } from "./runs.js";
 import { CCLAW_VERSION, RUNTIME_ROOT } from "./constants.js";
-import { createDefaultConfig } from "./config.js";
+import { createDefaultConfig, readConfig } from "./config.js";
 import { detectHarnesses } from "./init-detect.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
+import { promptHarnessSelectionChecklist } from "./harness-selection.js";
+export { parseHarnessSelectionAnswer } from "./harness-selection.js";
 import { classifyCodexHooksFlag, codexConfigPath, patchCodexHooksFlag, readCodexConfig, writeCodexConfig } from "./codex-feature-flag.js";
 import { runInternalCommand } from "./internal/advance-stage.js";
 const INSTALLER_COMMANDS = [
@@ -38,17 +40,21 @@ Commands:
              Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
                     --no-interactive    Skip interactive prompts even on TTY (for CI/scripts).
   sync       Reconcile generated runtime files with the current config.
+             Flags: --harnesses=<list>  Update configured harnesses before syncing.
+                    --interactive      Pick harnesses from a numbered TTY menu.
   doctor     Check install/runtime wiring and print concrete fixes for failures.
              Flags: --explain           Include docs pointers for every check.
                     --json              Emit machine-readable check results.
                     --quiet             Show only failing checks.
                     --only=<filter>     Limit displayed checks (error,warning,hook:,state:,...).
-                    --reconcile-gates   Refresh derived gate status before checking.
+                    --reconcile-gates   Refresh derived gate status before checking; does not repair missing artifacts/tests.
   upgrade    Refresh generated files in .cclaw. Preserves your config.yaml.
   archive    Archive the active run and reset flow state for the next run.
              Flags: --name=<slug>        Override archive folder suffix.
                     --skip-retro         Skip retro gate only when runtime allows it.
                     --retro-reason=<txt> Required rationale with --skip-retro.
+                    --disposition=<completed|cancelled|abandoned>
+                    --reason=<txt>      Required for cancelled/abandoned archives.
   uninstall  Remove .cclaw runtime and the generated harness shim files.
 
 Global flags:
@@ -58,17 +64,18 @@ Global flags:
 Examples:
   npx cclaw-cli
   npx cclaw-cli init --harnesses=claude,cursor --no-interactive
-  npx cclaw-cli sync
+  npx cclaw-cli sync --interactive
   npx cclaw-cli archive --name=my-run
+  npx cclaw-cli archive --disposition=cancelled --reason="deprioritized"
   npx cclaw-cli upgrade
 
-Happy-path work happens inside your harness via /cc, /cc-next,
-/cc-ideate, and /cc-view. Doctor is an operator/support surface:
+Happy-path work happens inside your harness via /cc, /cc-ideate,
+and /cc-cancel. Doctor is an operator/support surface:
 it verifies install/runtime wiring, but a real harness smoke test is
 still needed to prove provider auth and model execution.
 
 Docs:   https://github.com/zuevrs/cclaw
-Local:  docs/config.md and docs/harnesses.md
+Local:  README.md and generated .cclaw/skills/*.md
 Issues: https://github.com/zuevrs/cclaw/issues
 `;
 }
@@ -77,6 +84,9 @@ function parseHarnesses(raw) {
         .split(",")
         .map((item) => item.trim())
         .filter(Boolean);
+    if (requested.length === 0) {
+        throw new Error("Select at least one harness.");
+    }
     const invalid = requested.filter((item) => !HARNESS_IDS.includes(item));
     if (invalid.length > 0) {
         throw new Error(`Unknown harnesses: ${invalid.join(", ")}`);
@@ -90,6 +100,13 @@ function parseTrack(raw) {
     }
     return trimmed;
 }
+function parseArchiveDisposition(raw) {
+    const trimmed = raw.trim();
+    if (!ARCHIVE_DISPOSITIONS.includes(trimmed)) {
+        throw new Error(`Unknown archive disposition: ${trimmed}. Supported: ${ARCHIVE_DISPOSITIONS.join(", ")}`);
+    }
+    return trimmed;
+}
 function isInitPromptAllowed(ctx) {
     return Boolean(process.stdin.isTTY && ctx.stdout.isTTY);
 }
@@ -157,37 +174,8 @@ function buildInitSurfacePreview(harnesses) {
     return lines;
 }
 async function promptInitConfig(defaults, ctx) {
-    const rl = createInterface({
-        input: process.stdin,
-        output: ctx.stdout
-    });
-    const pickHarnesses = async (fallback) => {
-        const fallbackText = fallback.join(",");
-        while (true) {
-            const answer = (await rl.question(`\nHarnesses (comma list from ${HARNESS_IDS.join(", ")}) [${fallbackText}]: `)).trim();
-            if (answer.length === 0) {
-                return fallback;
-            }
-            try {
-                const parsed = parseHarnesses(answer);
-                if (parsed.length === 0) {
-                    ctx.stdout.write("Select at least one harness.\n");
-                    continue;
-                }
-                return parsed;
-            }
-            catch (err) {
-                ctx.stdout.write(`${err instanceof Error ? err.message : "Invalid harness list"}\n`);
-            }
-        }
-    };
-    try {
-        const harnesses = await pickHarnesses(defaults.harnesses);
-        return { harnesses };
-    }
-    finally {
-        rl.close();
-    }
+    const harnesses = await promptHarnessSelectionChecklist(defaults, ctx, "Initial cclaw harnesses");
+    return { harnesses };
 }
 /**
  * When Codex is one of the installed harnesses, check the Codex CLI
@@ -293,13 +281,41 @@ async function resolveInitInputs(parsed, ctx) {
     const defaults = {
         harnesses: autoHarnesses ?? HARNESS_IDS.slice()
     };
-    const prompted = await promptInitConfig(defaults, ctx);
+    const prompted = await promptInitConfig({ ...defaults, detectedHarnesses }, ctx);
     return {
         track: parsed.track,
         harnesses: prompted.harnesses,
         detectedHarnesses
     };
 }
+async function resolveSyncInputs(parsed, ctx) {
+    const explicitHarnesses = parsed.harnesses;
+    if (explicitHarnesses && explicitHarnesses.length > 0) {
+        return { harnesses: explicitHarnesses };
+    }
+    if (parsed.interactive !== true) {
+        return {};
+    }
+    if (!isInitPromptAllowed(ctx)) {
+        throw new Error("Interactive sync requires a TTY. Remove --interactive or run in a terminal.");
+    }
+    let currentHarnesses = [];
+    try {
+        currentHarnesses = (await readConfig(ctx.cwd)).harnesses;
+    }
+    catch {
+        currentHarnesses = [];
+    }
+    const detectedHarnesses = await detectHarnesses(ctx.cwd);
+    const defaults = detectedHarnesses.length > 0 ? detectedHarnesses : currentHarnesses.length > 0 ? currentHarnesses : HARNESS_IDS.slice();
+    return {
+        harnesses: await promptHarnessSelectionChecklist({
+            harnesses: defaults,
+            detectedHarnesses,
+            currentHarnesses
+        }, ctx, "Sync harness reconfiguration")
+    };
+}
 function parseDoctorOnly(raw) {
     return raw
         .split(",")
@@ -335,24 +351,47 @@ function doctorCountsBySeverity(checks) {
     }
     return result;
 }
+const DOCTOR_ACTION_GROUP_LABELS = {
+    sync: "Can fix with cclaw sync",
+    "user-action": "Requires user action",
+    "stage-work": "Requires stage work",
+    informational: "Informational warning"
+};
+function doctorActionGroupOrder(group) {
+    return group === "sync" ? 0 : group === "user-action" ? 1 : group === "stage-work" ? 2 : 3;
+}
 function printDoctorText(ctx, checks, options) {
     const orderedSeverities = ["error", "warning", "info"];
     const view = options.quiet ? checks.filter((check) => !check.ok) : checks;
-    for (const severity of orderedSeverities) {
-        const inBucket = view.filter((check) => check.severity === severity);
-        if (inBucket.length === 0)
-            continue;
-        ctx.stdout.write(`\n[${severity.toUpperCase()}]\n`);
-        for (const check of inBucket) {
-            const status = check.ok ? "PASS" : "FAIL";
-            ctx.stdout.write(`${status} ${check.name} :: ${check.summary}\n`);
-            if (!options.quiet) {
-                ctx.stdout.write(`  details: ${check.details}\n`);
-            }
-            if (!check.ok || options.explain) {
-                ctx.stdout.write(`  fix: ${check.fix}\n`);
-                if (check.docRef) {
-                    ctx.stdout.write(`  docs: ${check.docRef}\n`);
+    const actionGroups = [...new Set(view.map((check) => check.actionGroup))]
+        .sort((left, right) => doctorActionGroupOrder(left) - doctorActionGroupOrder(right));
+    for (const actionGroup of actionGroups) {
+        const groupChecks = view.filter((check) => check.actionGroup === actionGroup);
+        const failingInGroup = groupChecks.filter((check) => !check.ok).length;
+        ctx.stdout.write(`
+[${DOCTOR_ACTION_GROUP_LABELS[actionGroup]}] ${failingInGroup}/${groupChecks.length} failing
+`);
+        for (const severity of orderedSeverities) {
+            const inBucket = groupChecks.filter((check) => check.severity === severity);
+            if (inBucket.length === 0)
+                continue;
+            ctx.stdout.write(`  ${severity.toUpperCase()}
+`);
+            for (const check of inBucket) {
+                const status = check.ok ? "PASS" : "FAIL";
+                ctx.stdout.write(`  ${status} ${check.name} :: ${check.summary}
+`);
+                if (!options.quiet) {
+                    ctx.stdout.write(`    details: ${check.details}
+`);
+                }
+                if (!check.ok || options.explain) {
+                    ctx.stdout.write(`    next action: ${check.fix}
+`);
+                    if (check.docRef) {
+                        ctx.stdout.write(`    reference: ${check.docRef}
+`);
+                    }
                 }
             }
         }
@@ -392,13 +431,13 @@ function parseArgs(argv) {
     }
     const flags = rest;
     const isAllowedForCommand = (flag) => {
-        if (parsed.command === "init") {
+        if (parsed.command === "init" || parsed.command === "sync") {
             return flag.startsWith("--harnesses=") ||
-                flag.startsWith("--track=") ||
-                flag.startsWith("--profile=") ||
+                (parsed.command === "init" && flag.startsWith("--track=")) ||
+                (parsed.command === "init" && flag.startsWith("--profile=")) ||
                 flag === "--interactive" ||
                 flag === "--no-interactive" ||
-                flag === "--dry-run";
+                (parsed.command === "init" && flag === "--dry-run");
         }
         if (parsed.command === "doctor") {
             return flag === "--reconcile-gates" ||
@@ -410,7 +449,9 @@ function parseArgs(argv) {
         if (parsed.command === "archive") {
             return flag.startsWith("--name=") ||
                 flag === "--skip-retro" ||
-                flag.startsWith("--retro-reason=");
+                flag.startsWith("--retro-reason=") ||
+                flag.startsWith("--disposition=") ||
+                flag.startsWith("--reason=");
         }
         return false;
     };
@@ -473,6 +514,14 @@ function parseArgs(argv) {
             parsed.archiveSkipRetroReason = flag.replace("--retro-reason=", "").trim();
             continue;
         }
+        if (flag.startsWith("--disposition=")) {
+            parsed.archiveDisposition = parseArchiveDisposition(flag.replace("--disposition=", ""));
+            continue;
+        }
+        if (flag.startsWith("--reason=")) {
+            parsed.archiveDispositionReason = flag.replace("--reason=", "").trim();
+            continue;
+        }
     }
     return parsed;
 }
@@ -532,8 +581,10 @@ async function runCommand(parsed, ctx) {
         return 0;
     }
     if (command === "sync") {
-        await syncCclaw(ctx.cwd);
-        info(ctx, "Synchronized harness shims from current .cclaw config");
+        const resolved = await resolveSyncInputs(parsed, ctx);
+        await syncCclaw(ctx.cwd, { harnesses: resolved.harnesses });
+        const harnessNote = resolved.harnesses ? ` (${resolved.harnesses.join(", ")})` : "";
+        info(ctx, `Synchronized harness shims from current .cclaw config${harnessNote}`);
         return 0;
     }
     if (command === "doctor") {
@@ -571,12 +622,14 @@ async function runCommand(parsed, ctx) {
     if (command === "archive") {
         const archived = await archiveRun(ctx.cwd, parsed.archiveName, {
             skipRetro: parsed.archiveSkipRetro === true,
-            skipRetroReason: parsed.archiveSkipRetroReason
+            skipRetroReason: parsed.archiveSkipRetroReason,
+            disposition: parsed.archiveDisposition,
+            dispositionReason: parsed.archiveDispositionReason
         });
         const snapshotSummary = archived.snapshottedStateFiles.length > 0
             ? ` Snapshotted ${archived.snapshottedStateFiles.length} state file(s) under ${archived.archivePath}/state and wrote archive-manifest.json.`
             : "";
-        info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.${snapshotSummary}`);
+        info(ctx, `Archived active artifacts to ${archived.archivePath} (${archived.disposition}). Flow state reset to brainstorm.${snapshotSummary}`);
         const k = archived.knowledge;
         if (k.overThreshold) {
             info(ctx, `Knowledge curation recommended: ${k.knowledgePath} now has ${k.activeEntryCount} active entries (soft threshold ${k.softThreshold}). Ask your harness to curate cclaw knowledge and plan a soft-archive of stale/duplicate entries to ${RUNTIME_ROOT}/knowledge.archive.jsonl.`);
@@ -624,4 +677,4 @@ function isDirectExecution() {
 if (isDirectExecution()) {
     void main();
 }
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseArchiveDisposition, parseHarnesses, parseTrack };

package/dist/codex-feature-flag.d.ts

@@ -11,7 +11,7 @@
  * ```
  *
  * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
- * cclaw's `init --codex` prompts the user to flip this flag for them;
+ * cclaw init/sync can prompt the user to flip this flag for them; `cclaw doctor --explain` reports the concrete repair when it is missing;
  * this module owns the detection / mutation code so the prompt logic in
  * `cli.ts` stays small and testable.
  *

package/dist/codex-feature-flag.js

@@ -11,7 +11,7 @@
  * ```
  *
  * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
- * cclaw's `init --codex` prompts the user to flip this flag for them;
+ * cclaw init/sync can prompt the user to flip this flag for them; `cclaw doctor --explain` reports the concrete repair when it is missing;
  * this module owns the detection / mutation code so the prompt logic in
  * `cli.ts` stays small and testable.
  *

package/dist/config.js

@@ -245,6 +245,9 @@ export async function readConfig(projectRoot, options = {}) {
         throw configValidationError(fullPath, `unknown harness id(s): ${formatted}`);
     }
     const validatedHarnesses = configuredHarnesses;
+    if (hasHarnessesField && validatedHarnesses.length === 0) {
+        throw configValidationError(fullPath, `"harnesses" must include at least one harness`);
+    }
     const harnesses = hasHarnessesField
         ? [...new Set(validatedHarnesses)]
         : DEFAULT_HARNESSES;

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

@@ -0,0 +1,2 @@
+export declare function cancelCommandContract(): string;
+export declare function cancelCommandSkillMarkdown(): string;

package/dist/content/cancel-command.js

@@ -0,0 +1,25 @@
+export function cancelCommandContract() {
+    return `# /cc-cancel command contract
+
+Use this command when the user wants to stop the active run without claiming completion.
+
+## Protocol
+
+1. Ask for a concise cancellation reason if the user has not already provided one.
+2. Run \`cclaw archive --disposition=cancelled --reason=<reason>\` from the project root. Use \`--disposition=abandoned\` only when the user explicitly frames the run as abandoned rather than cancelled.
+3. Report the archive path and reset run id. Make clear that the archived run is not a completed ship.
+
+Cancelled and abandoned archives are allowed from any stage, but they require a required reason so future readers know why the run ended.
+`;
+}
+export function cancelCommandSkillMarkdown() {
+    return `---
+name: flow-cancel
+description: Cancel or abandon the active cclaw run with a required reason. Use when the user types /cc-cancel or asks to cancel, abandon, stop, discard, or reset an unfinished run.
+---
+
+# Cancel cclaw Run
+
+Load and follow \`.cclaw/commands/cancel.md\`. This is a non-completion path: require a reason and archive with cancelled or abandoned disposition.
+`;
+}

package/dist/content/closeout-guidance.js

@@ -13,7 +13,7 @@ export function closeoutSubstateInline() {
     return `\`${CLOSEOUT_SUBSTATE_KEY}\``;
 }
 export function closeoutNextCommandGuidance() {
-    return `After ship completes, the closeout chain ${closeoutChainInline()} runs automatically, driven by ${closeoutSubstateInline()}. Continue through \`/cc-next\`; do not branch into \`ce:compound\`, a separate operations router, or a one-off closeout command. Ralph Loop may be mentioned only as tdd carry-forward context when it explains the next \`/cc-next\` move; it is not part of compound/archive routing.`;
+    return `After ship completes, the closeout chain ${closeoutChainInline()} runs automatically, driven by ${closeoutSubstateInline()}. Continue through \`/cc\`; do not branch into \`ce:compound\`, a separate operations router, or a one-off closeout command. Ralph Loop may be mentioned only as tdd carry-forward context when it explains the next \`/cc\` move; it is not part of compound/archive routing.`;
 }
 export function closeoutSubstateProtocolBullets() {
     return `When \`currentStage === "ship"\`, route by **${closeoutSubstateInline()}**:
@@ -35,8 +35,8 @@ export function closeoutSubstateProtocolBullets() {
   - \`"archived"\` (transient) -> report "run archived" and stop.`;
 }
 export function closeoutFlowMapSentence() {
-    return `The first stage names are the critical path. \`retro\`, \`compound\`, and \`archive\` are post-ship closeout substates under ${closeoutSubstateInline()}, not separate stage schemas or commands. Continue them with \`/cc-next\`; do not route compound closeout through \`ce:compound\`.`;
+    return `The first stage names are the critical path. \`retro\`, \`compound\`, and \`archive\` are post-ship closeout substates under ${closeoutSubstateInline()}, not separate stage schemas or commands. Continue them with \`/cc\`; do not route compound closeout through \`ce:compound\`.`;
 }
 export function closeoutProtocolBehaviorSentence() {
-    return `Keep decision, completion, and preamble discipline inline: ask only decision-changing questions, verify gates before advancing, and keep context compact. After \`ship\`, keep using \`/cc-next\` through ${closeoutChainInline()}; do not route normal closeout through \`ce:compound\` or a separate operations command. In compound closeout, assess overlap before appending knowledge: refresh recurring bug-track learnings as actionable rules/tests, keep knowledge-track learnings as durable process/project guidance, and mark outdated entries with lightweight \`supersedes\` / \`superseded_by\` fields instead of building a new doc system.`;
+    return `Keep decision, completion, and preamble discipline inline: ask only decision-changing questions, verify gates before advancing, and keep context compact. After \`ship\`, keep using \`/cc\` through ${closeoutChainInline()}; do not route normal closeout through \`ce:compound\` or a separate operations command. In compound closeout, assess overlap before appending knowledge: refresh recurring bug-track learnings as actionable rules/tests, keep knowledge-track learnings as durable process/project guidance, and mark outdated entries with lightweight \`supersedes\` / \`superseded_by\` fields instead of building a new doc system.`;
 }

package/dist/content/core-agents.js

@@ -498,11 +498,11 @@ export function agentRoutingTable() {
     return `| Stage Entry | Primary Agent(s) | Supporting guidance |
 |---|---|---|
 | Brainstorm (start with \`/cc <idea>\`) | ${brainstormPrimary} | Run in-thread research playbooks: \`research/repo-scan.md\`, \`research/learnings-lookup.md\` |
-| Scope / Design / Plan (via \`/cc-next\`) | ${scopeDesignPlanPrimary} | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
-| Spec (via \`/cc-next\`) | ${specPrimary} | planner (if ambiguity or conflicts remain) |
-| TDD (via \`/cc-next\`) | ${tddPrimary} | doc-updater on public behavior/config changes |
-| Review (via \`/cc-next\`) | ${reviewPrimary} | conditional second reviewer for high blast-radius diffs |
-| Ship (via \`/cc-next\`) | ${shipPrimary} | security-reviewer when release risk is elevated |
+| Scope / Design / Plan (via \`/cc\`) | ${scopeDesignPlanPrimary} | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
+| Spec (via \`/cc\`) | ${specPrimary} | planner (if ambiguity or conflicts remain) |
+| TDD (via \`/cc\`) | ${tddPrimary} | doc-updater on public behavior/config changes |
+| Review (via \`/cc\`) | ${reviewPrimary} | conditional second reviewer for high blast-radius diffs |
+| Ship (via \`/cc\`) | ${shipPrimary} | security-reviewer when release risk is elevated |
 `;
 }
 /**

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 — …
    \`\`\`