cclaw-cli 0.51.30 → 1.0.0

package/dist/cli.d.ts

@@ -2,18 +2,13 @@
 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";
+type CommandName = "init" | "sync" | "upgrade" | "uninstall" | "archive" | "internal";
 interface ParsedArgs {
     command?: CommandName;
     harnesses?: HarnessId[];
     track?: FlowTrack;
     dryRun?: boolean;
     interactive?: boolean;
-    reconcileGates?: boolean;
-    doctorJson?: boolean;
-    doctorExplain?: boolean;
-    doctorQuiet?: boolean;
-    doctorOnly?: string[];
     archiveName?: string;
     archiveSkipRetro?: boolean;
     archiveSkipRetroReason?: string;

package/dist/cli.js

@@ -4,7 +4,6 @@ import path from "node:path";
 import { existsSync, realpathSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-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";
@@ -20,7 +19,6 @@ import { runInternalCommand } from "./internal/advance-stage.js";
 const INSTALLER_COMMANDS = [
     "init",
     "sync",
-    "doctor",
     "upgrade",
     "uninstall",
     "archive",
@@ -42,12 +40,6 @@ Commands:
   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; 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.
@@ -69,10 +61,9 @@ Examples:
   npx cclaw-cli archive --disposition=cancelled --reason="deprioritized"
   npx cclaw-cli upgrade
 
-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.
+Happy-path work happens inside your harness via /cc, /cc-idea,
+and /cc-cancel. Installer/support operations are init/sync/upgrade/uninstall
+plus explicit archive actions.
 
 Docs:   https://github.com/zuevrs/cclaw
 Local:  README.md and generated .cclaw/skills/*.md
@@ -139,7 +130,7 @@ function buildInitSurfacePreview(harnesses) {
         ".cclaw/agents/*.md",
         ".cclaw/hooks/*",
         ".cclaw/rules/**",
-        ".cclaw/runs/**",
+        ".cclaw/archive/**",
         ".cclaw/artifacts/**",
         ".cclaw/knowledge.jsonl",
         ".cclaw/state/*.json|*.jsonl",
@@ -316,98 +307,6 @@ async function resolveSyncInputs(parsed, ctx) {
         }, ctx, "Sync harness reconfiguration")
     };
 }
-function parseDoctorOnly(raw) {
-    return raw
-        .split(",")
-        .map((item) => item.trim().toLowerCase())
-        .filter((item) => item.length > 0);
-}
-function filterDoctorChecks(checks, filters) {
-    if (!filters || filters.length === 0) {
-        return checks;
-    }
-    return checks.filter((check) => {
-        const name = check.name.toLowerCase();
-        return filters.some((filter) => {
-            if (filter === "error" || filter === "warning" || filter === "info") {
-                return check.severity === filter;
-            }
-            return name.includes(filter);
-        });
-    });
-}
-function doctorCountsBySeverity(checks) {
-    const result = {
-        error: { total: 0, failing: 0 },
-        warning: { total: 0, failing: 0 },
-        info: { total: 0, failing: 0 }
-    };
-    for (const check of checks) {
-        const bucket = result[check.severity];
-        bucket.total += 1;
-        if (!check.ok) {
-            bucket.failing += 1;
-        }
-    }
-    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;
-    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}
-`);
-                    }
-                }
-            }
-        }
-    }
-    const counts = doctorCountsBySeverity(checks);
-    const failingErrors = checks.filter((check) => check.severity === "error" && !check.ok).length;
-    ctx.stdout.write(`\nTotals: error ${counts.error.failing}/${counts.error.total} failing, ` +
-        `warning ${counts.warning.failing}/${counts.warning.total} failing, ` +
-        `info ${counts.info.failing}/${counts.info.total} failing\n`);
-    if (failingErrors > 0) {
-        ctx.stdout.write(`Doctor status: BLOCKED (${failingErrors} failing error checks)\n`);
-    }
-    else {
-        ctx.stdout.write("Doctor status: HEALTHY (no failing error checks)\n");
-    }
-}
 function parseArgs(argv) {
     const parsed = {};
     const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
@@ -439,13 +338,6 @@ function parseArgs(argv) {
                 flag === "--no-interactive" ||
                 (parsed.command === "init" && flag === "--dry-run");
         }
-        if (parsed.command === "doctor") {
-            return flag === "--reconcile-gates" ||
-                flag === "--json" ||
-                flag === "--explain" ||
-                flag === "--quiet" ||
-                flag.startsWith("--only=");
-        }
         if (parsed.command === "archive") {
             return flag.startsWith("--name=") ||
                 flag === "--skip-retro" ||
@@ -482,26 +374,6 @@ function parseArgs(argv) {
             parsed.dryRun = true;
             continue;
         }
-        if (flag === "--reconcile-gates") {
-            parsed.reconcileGates = true;
-            continue;
-        }
-        if (flag === "--json") {
-            parsed.doctorJson = true;
-            continue;
-        }
-        if (flag === "--explain") {
-            parsed.doctorExplain = true;
-            continue;
-        }
-        if (flag === "--quiet") {
-            parsed.doctorQuiet = true;
-            continue;
-        }
-        if (flag.startsWith("--only=")) {
-            parsed.doctorOnly = parseDoctorOnly(flag.replace("--only=", ""));
-            continue;
-        }
         if (flag.startsWith("--name=")) {
             parsed.archiveName = flag.replace("--name=", "").trim();
             continue;
@@ -587,33 +459,6 @@ async function runCommand(parsed, ctx) {
         info(ctx, `Synchronized harness shims from current .cclaw config${harnessNote}`);
         return 0;
     }
-    if (command === "doctor") {
-        const checks = await doctorChecks(ctx.cwd, {
-            reconcileCurrentStageGates: parsed.reconcileGates === true
-        });
-        const filteredChecks = filterDoctorChecks(checks, parsed.doctorOnly);
-        const explain = parsed.doctorExplain === true;
-        const quiet = parsed.doctorQuiet === true;
-        if (parsed.doctorJson === true) {
-            const counts = doctorCountsBySeverity(filteredChecks);
-            ctx.stdout.write(`${JSON.stringify({
-                ok: doctorSucceeded(filteredChecks),
-                globalOk: doctorSucceeded(checks),
-                filters: parsed.doctorOnly ?? [],
-                counts,
-                checks: filteredChecks
-            }, null, 2)}\n`);
-        }
-        else {
-            if (filteredChecks.length === 0) {
-                ctx.stdout.write("No checks matched the --only filter.\n");
-            }
-            else {
-                printDoctorText(ctx, filteredChecks, { explain, quiet });
-            }
-        }
-        return doctorSucceeded(filteredChecks) ? 0 : 2;
-    }
     if (command === "upgrade") {
         await upgradeCclaw(ctx.cwd);
         info(ctx, "Upgraded .cclaw runtime and regenerated generated files");

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

@@ -11,7 +11,7 @@
  * ```
  *
  * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
- * cclaw init/sync can prompt the user to flip this flag for them; `cclaw doctor --explain` reports the concrete repair when it is missing;
+ * cclaw init/sync can prompt the user to flip this flag for them; sync/runtime diagnostics report 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 init/sync can prompt the user to flip this flag for them; `cclaw doctor --explain` reports the concrete repair when it is missing;
+ * cclaw init/sync can prompt the user to flip this flag for them; sync/runtime diagnostics report 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.d.ts

@@ -24,9 +24,10 @@ export declare const DEFAULT_TDD_TEST_PATH_PATTERNS: readonly string[];
 export declare const DEFAULT_TDD_TEST_GLOBS: readonly string[];
 export declare const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS: readonly string[];
 export declare const DEFAULT_COMPOUND_RECURRENCE_THRESHOLD = 3;
+export declare const DEFAULT_EARLY_LOOP_MAX_ITERATIONS = 3;
 /**
  * Populated runtime view of config values that downstream callers (install,
- * observe, doctor) consume. Always has the derived guard modes populated,
+ * observe, sync/runtime checks) consume. Always has the derived guard modes populated,
  * regardless of whether the user wrote `strictness`, the legacy keys, both,
  * or neither.
  */
@@ -49,7 +50,7 @@ export declare function readConfig(projectRoot: string, options?: ReadConfigOpti
  * the user set them explicitly. Keeps the default template small and honest:
  * only knobs a new user would meaningfully flip show up.
  */
-type AdvancedConfigKey = "vcs" | "tddTestGlobs" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview" | "ironLaws" | "optInAudits" | "reviewLoop";
+type AdvancedConfigKey = "vcs" | "tddTestGlobs" | "tdd" | "compound" | "earlyLoop" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview" | "ironLaws" | "optInAudits" | "reviewLoop";
 /**
  * Options controlling the serialisation shape of `config.yaml`.
  *

package/dist/config.js

@@ -21,6 +21,8 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "tddTestGlobs",
     "tdd",
     "compound",
+    "earlyLoop",
+    "early_loop",
     "gitHookGuards",
     "defaultTrack",
     "languageRulePacks",
@@ -131,9 +133,10 @@ export const DEFAULT_TDD_TEST_PATH_PATTERNS = [
 export const DEFAULT_TDD_TEST_GLOBS = [...DEFAULT_TDD_TEST_PATH_PATTERNS];
 export const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS = [];
 export const DEFAULT_COMPOUND_RECURRENCE_THRESHOLD = 3;
+export const DEFAULT_EARLY_LOOP_MAX_ITERATIONS = 3;
 /**
  * Populated runtime view of config values that downstream callers (install,
- * observe, doctor) consume. Always has the derived guard modes populated,
+ * observe, sync/runtime checks) consume. Always has the derived guard modes populated,
  * regardless of whether the user wrote `strictness`, the legacy keys, both,
  * or neither.
  */
@@ -155,11 +158,19 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack
         compound: {
             recurrenceThreshold: DEFAULT_COMPOUND_RECURRENCE_THRESHOLD
         },
+        earlyLoop: {
+            enabled: true,
+            maxIterations: DEFAULT_EARLY_LOOP_MAX_ITERATIONS
+        },
         gitHookGuards: false,
         defaultTrack,
         languageRulePacks: [],
         ironLaws: {
             strictLaws: []
+        },
+        optInAudits: {
+            scopePreAudit: false,
+            staleDiagramAudit: true
         }
     };
 }
@@ -327,6 +338,46 @@ export async function readConfig(projectRoot, options = {}) {
             compoundRecurrenceThreshold = compoundRaw.recurrenceThreshold;
         }
     }
+    const hasEarlyLoopField = Object.prototype.hasOwnProperty.call(parsed, "earlyLoop");
+    const hasLegacyEarlyLoopField = Object.prototype.hasOwnProperty.call(parsed, "early_loop");
+    if (hasEarlyLoopField && hasLegacyEarlyLoopField) {
+        emitConfigWarningOnce(warningState, "CCLAW_CONFIG_EARLY_LOOP_ALIAS", `[cclaw] Both "earlyLoop" and legacy "early_loop" are set in ${fullPath}. Using "earlyLoop".`);
+    }
+    const earlyLoopRaw = hasEarlyLoopField
+        ? parsed.earlyLoop
+        : parsed.early_loop;
+    let earlyLoopEnabled = true;
+    let earlyLoopMaxIterations = DEFAULT_EARLY_LOOP_MAX_ITERATIONS;
+    if (hasEarlyLoopField || hasLegacyEarlyLoopField) {
+        if (!isRecord(earlyLoopRaw)) {
+            throw configValidationError(fullPath, `"${hasEarlyLoopField ? "earlyLoop" : "early_loop"}" must be an object`);
+        }
+        const unknownEarlyLoopKeys = Object.keys(earlyLoopRaw).filter((key) => key !== "enabled" && key !== "maxIterations" && key !== "max_iterations");
+        if (unknownEarlyLoopKeys.length > 0) {
+            throw configValidationError(fullPath, `"${hasEarlyLoopField ? "earlyLoop" : "early_loop"}" has unknown key(s): ${unknownEarlyLoopKeys.join(", ")}`);
+        }
+        if (earlyLoopRaw.enabled !== undefined && typeof earlyLoopRaw.enabled !== "boolean") {
+            throw configValidationError(fullPath, `"${hasEarlyLoopField ? "earlyLoop" : "early_loop"}.enabled" must be a boolean`);
+        }
+        if (earlyLoopRaw.maxIterations !== undefined &&
+            earlyLoopRaw.max_iterations !== undefined &&
+            earlyLoopRaw.maxIterations !== earlyLoopRaw.max_iterations) {
+            emitConfigWarningOnce(warningState, "CCLAW_CONFIG_EARLY_LOOP_MAX_ITERATIONS_ALIAS", `[cclaw] Both "${hasEarlyLoopField ? "earlyLoop.maxIterations" : "early_loop.maxIterations"}" and "${hasEarlyLoopField ? "earlyLoop.max_iterations" : "early_loop.max_iterations"}" are set in ${fullPath}. Using "maxIterations".`);
+        }
+        const rawMaxIterations = earlyLoopRaw.maxIterations ?? earlyLoopRaw.max_iterations;
+        if (rawMaxIterations !== undefined &&
+            (typeof rawMaxIterations !== "number" ||
+                !Number.isInteger(rawMaxIterations) ||
+                rawMaxIterations < 1)) {
+            throw configValidationError(fullPath, `"${hasEarlyLoopField ? "earlyLoop" : "early_loop"}.maxIterations" must be a positive integer`);
+        }
+        if (typeof earlyLoopRaw.enabled === "boolean") {
+            earlyLoopEnabled = earlyLoopRaw.enabled;
+        }
+        if (typeof rawMaxIterations === "number") {
+            earlyLoopMaxIterations = rawMaxIterations;
+        }
+    }
     const gitHookGuardsRaw = parsed.gitHookGuards;
     if (Object.prototype.hasOwnProperty.call(parsed, "gitHookGuards") &&
         typeof gitHookGuardsRaw !== "boolean") {
@@ -483,7 +534,13 @@ export async function readConfig(projectRoot, options = {}) {
                 : false,
             staleDiagramAudit: typeof optInAuditsRaw.staleDiagramAudit === "boolean"
                 ? optInAuditsRaw.staleDiagramAudit
-                : false
+                : true
+        };
+    }
+    if (!optInAudits) {
+        optInAudits = {
+            scopePreAudit: false,
+            staleDiagramAudit: true
         };
     }
     const reviewLoopRaw = parsed.reviewLoop;
@@ -544,6 +601,10 @@ export async function readConfig(projectRoot, options = {}) {
         compound: {
             recurrenceThreshold: compoundRecurrenceThreshold
         },
+        earlyLoop: {
+            enabled: earlyLoopEnabled,
+            maxIterations: earlyLoopMaxIterations
+        },
         gitHookGuards,
         defaultTrack,
         languageRulePacks,
@@ -570,6 +631,7 @@ function buildSerializableConfig(config, options = {}) {
         "tddTestGlobs",
         "tdd",
         "compound",
+        "earlyLoop",
         "gitHookGuards",
         "defaultTrack",
         "languageRulePacks",
@@ -626,6 +688,7 @@ export async function detectAdvancedKeys(projectRoot) {
             "tddTestGlobs",
             "tdd",
             "compound",
+            "earlyLoop",
             "defaultTrack",
             "languageRulePacks",
             "trackHeuristics",
@@ -636,7 +699,8 @@ export async function detectAdvancedKeys(projectRoot) {
         ];
         const present = new Set();
         for (const key of advancedCandidates) {
-            if (Object.prototype.hasOwnProperty.call(parsedUnknown, key)) {
+            if (Object.prototype.hasOwnProperty.call(parsedUnknown, key) ||
+                (key === "earlyLoop" && Object.prototype.hasOwnProperty.call(parsedUnknown, "early_loop"))) {
                 present.add(key);
             }
         }

package/dist/constants.d.ts

@@ -10,16 +10,10 @@ export declare const FLOW_VERSION = "1.0.0";
 export declare const SHIP_FINALIZATION_MODES: readonly ["FINALIZE_MERGE_LOCAL", "FINALIZE_OPEN_PR", "FINALIZE_KEEP_BRANCH", "FINALIZE_DISCARD_BRANCH", "FINALIZE_NO_VCS"];
 export type ShipFinalizationMode = (typeof SHIP_FINALIZATION_MODES)[number];
 export declare const DEFAULT_HARNESSES: HarnessId[];
-export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/templates/state-contracts", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/skills/review-prompts"];
+export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/templates/state-contracts", ".cclaw/artifacts", ".cclaw/wave-plans", ".cclaw/archive", ".cclaw/state", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/skills/review-prompts"];
 export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cc/SKILL.md", ".agents/skills/cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 /**
  * Canonical stage -> skill folder mapping.
- *
- * Intentional divergence from stage ids:
- * - stage ids stay short and flow-oriented (`spec`, `tdd`, `ship`)
- * - skill folders stay descriptive and user-facing for `.cclaw/skills/*`.
- *
- * Keep this map as the single source of truth for generated skill paths.
  */
 export declare const STAGE_TO_SKILL_FOLDER: Record<FlowStage, string>;
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];

package/dist/constants.js

@@ -59,8 +59,9 @@ export const REQUIRED_DIRS = [
     `${RUNTIME_ROOT}/templates`,
     `${RUNTIME_ROOT}/templates/state-contracts`,
     `${RUNTIME_ROOT}/artifacts`,
+    `${RUNTIME_ROOT}/wave-plans`,
+    `${RUNTIME_ROOT}/archive`,
     `${RUNTIME_ROOT}/state`,
-    `${RUNTIME_ROOT}/runs`,
     `${RUNTIME_ROOT}/rules`,
     `${RUNTIME_ROOT}/agents`,
     `${RUNTIME_ROOT}/hooks`,
@@ -89,22 +90,16 @@ export const REQUIRED_GITIGNORE_PATTERNS = [
 ];
 /**
  * Canonical stage -> skill folder mapping.
- *
- * Intentional divergence from stage ids:
- * - stage ids stay short and flow-oriented (`spec`, `tdd`, `ship`)
- * - skill folders stay descriptive and user-facing for `.cclaw/skills/*`.
- *
- * Keep this map as the single source of truth for generated skill paths.
  */
 export const STAGE_TO_SKILL_FOLDER = {
-    brainstorm: "brainstorming",
-    scope: "scope-shaping",
-    design: "engineering-design-lock",
-    spec: "specification-authoring",
-    plan: "planning-and-task-breakdown",
-    tdd: "test-driven-development",
-    review: "two-layer-review",
-    ship: "shipping-and-handoff"
+    brainstorm: "brainstorm",
+    scope: "scope",
+    design: "design",
+    spec: "spec",
+    plan: "plan",
+    tdd: "tdd",
+    review: "review",
+    ship: "ship"
 };
 export const SUBAGENT_SKILL_FOLDERS = [
     "subagent-dev",

package/dist/content/cancel-command.js

@@ -6,7 +6,7 @@ Use this command when the user wants to stop the active run without claiming com
 ## 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.
+2. Run \`node .cclaw/hooks/cancel-run.mjs --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.
@@ -20,6 +20,6 @@ description: Cancel or abandon the active cclaw run with a required reason. Use
 
 # 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.
+Load and follow \`.cclaw/commands/cancel.md\`. This is a non-completion path: require a reason, run the generated cancel helper, and archive with cancelled or abandoned disposition.
 `;
 }

package/dist/content/closeout-guidance.d.ts

@@ -4,7 +4,7 @@
  * Keep closeout chain and ship substate language in one place across command
  * contracts, skills, and stage/docs surfaces.
  */
-export declare const CLOSEOUT_CHAIN = "retro -> compound -> archive";
+export declare const CLOSEOUT_CHAIN = "post_ship_review -> archive";
 export declare const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
 export declare function closeoutChainInline(): string;
 export declare function closeoutSubstateInline(): string;

package/dist/content/closeout-guidance.js

@@ -4,7 +4,7 @@
  * Keep closeout chain and ship substate language in one place across command
  * contracts, skills, and stage/docs surfaces.
  */
-export const CLOSEOUT_CHAIN = "retro -> compound -> archive";
+export const CLOSEOUT_CHAIN = "post_ship_review -> archive";
 export const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
 export function closeoutChainInline() {
     return `\`${CLOSEOUT_CHAIN}\``;
@@ -17,26 +17,28 @@ export function closeoutNextCommandGuidance() {
 }
 export function closeoutSubstateProtocolBullets() {
     return `When \`currentStage === "ship"\`, route by **${closeoutSubstateInline()}**:
-  - \`"idle"\` or missing -> set ${closeoutSubstateInline()} = \`"retro_review"\`, then
-    execute the in-stage retro protocol (draft + one structured accept/edit/skip ask).
-  - \`"retro_review"\` -> continue the retro protocol (re-ask the structured
-    question; the draft already exists — do not regenerate it).
-  - \`"compound_review"\` -> execute the in-stage compound closeout scan (not \`ce:compound\`):
+  - \`"idle"\` or missing -> outcome: initialize closeout by setting
+    ${closeoutSubstateInline()} = \`"post_ship_review"\`, then continue \`/cc\`
+    into the in-stage retro protocol (draft + one structured accept/edit/skip ask).
+  - \`"post_ship_review"\` -> outcome: execute the unified post-ship closeout leg
+    (retro acceptance/edit/skip + in-stage compound scan, not \`ce:compound\`)
+    and advance toward archive readiness:
     read \`.cclaw/state/compound-readiness.json\` plus the relevant tail of
     \`.cclaw/knowledge.jsonl\`, assess overlap before adding duplicate knowledge,
     separate bug-track learnings (turn into rules/tests/remediation) from
-    knowledge-track learnings (durable project/process guidance), and use
-    lightweight \`supersedes\` / \`superseded_by\` fields when refreshing stale or
-    partially replaced entries. Optionally ask whether to scan Cursor/Claude/Codex
+    knowledge-track learnings (durable project/process guidance), and refresh stale
+    guidance in place instead of introducing extra lineage metadata. Optionally ask
+    whether to scan Cursor/Claude/Codex
     session transcripts for matching historical learnings; only do it after opt-in.
     Ask **one** structured question (apply / skip) per candidate cluster or a
     single accept-all / skip choice, then advance substate.
-  - \`"ready_to_archive"\` -> run \`npx cclaw-cli archive\` (or \`npx cclaw-cli archive --name=<slug>\`) and reset state.
-  - \`"archived"\` (transient) -> report "run archived" and stop.`;
+  - \`"ready_to_archive"\` -> outcome: continue \`/cc\` so the runtime archive step
+    executes, snapshots, and resets active state.
+  - \`"archived"\` (transient) -> outcome: report "run archived" and stop (flow complete).`;
 }
 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\`; do not route compound closeout through \`ce:compound\`.`;
+    return `The first stage names are the critical path. \`post_ship_review\` 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\` 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. Inside \`post_ship_review\`, assess overlap before appending knowledge: refresh recurring bug-track learnings as actionable rules/tests and keep knowledge-track learnings as durable process/project guidance without extra lineage metadata.`;
 }