cclaw-cli 0.30.0 → 0.32.0

package/README.md

@@ -117,7 +117,8 @@ Plus harness-specific shims:
 
 `.cclaw/config.yaml` holds every tunable key (prompt guard strictness,
 TDD enforcement, git-hook guards, language rule packs, track heuristics).
-Edit it directly — `cclaw-cli upgrade` preserves your changes.
+Edit it directly — `cclaw-cli upgrade` preserves your changes. Full key
+reference: [`docs/config.md`](./docs/config.md).
 
 ---
 
@@ -199,8 +200,9 @@ cclaw has eight stages, but a single prompt rarely needs all of them.
 | **standard** _(default)_ | all 8 stages | `new feature`, `refactor`, `migration`, `platform`, `schema`, `architecture` |
 
 Each stage produces a dated artifact under `.cclaw/artifacts/`:
-`00-idea.md` (seed) and `01-brainstorm.md` through `08-ship.md`
-(plus `09-retro.md` at automatic closeout — see below).
+`00-idea.md` (seed), `01-brainstorm.md` through `08-ship.md`, and
+`09-retro.md` at automatic closeout (see
+[Ship and closeout](#ship-and-closeout--automatic-resumable)).
 
 ### Track heuristics are configurable
 
@@ -253,8 +255,12 @@ it into ceremony:
   in a single place (`.cclaw/contexts/`), so every skill speaks the same
   dialect.
 - **Knowledge capture throughout the flow.** Every stage completion
-  protocol can emit entries to `knowledge.jsonl` — not only retro. Strict
-  JSONL schema keeps it machine-queryable.
+  protocol emits typed entries (`rule` / `pattern` / `lesson`) to
+  `.cclaw/knowledge.jsonl` as the flow progresses — not only at retro.
+  Retro itself adds a `compound` entry, and the automatic compound pass
+  after ship promotes recurring entries (≥ 3) into first-class
+  rules/protocols/skills so the **next** run is easier. Strict JSONL
+  schema keeps the whole thing machine-queryable.
 - **Automatic integrity checks.** Runtime health is verified on every
   stage transition — no command you need to remember to run.
 
@@ -277,24 +283,38 @@ native subagent dispatch, such as Codex — see
 
 ---
 
-## Ship and closeout
-
-Shipping writes `08-ship.md` and then closes out the feature through a
-guided three-step sequence:
-
-1. **Retro** drafts `09-retro.md` from flow artifacts and the delegation
-   log; you review and accept.
-2. **Compound pass** promotes repeated knowledge entries (frequency ≥ 2,
-   maturity = stable) into first-class rules or skills.
-3. **Archive** moves artifacts to `.cclaw/runs/YYYY-MM-DD-<slug>/` and
-   resets `flow-state.json`.
-
-Retro is not optional — archive is gated on retro completion so you can't
-silently lose the learning pass.
-
-> **Coming next:** cclaw will chain these three steps automatically from
-> `ship` (one structured `edit`/`accept`/`skip` ask, resumable if the
-> session ends). Tracked as the v0.32 closeout-automation wave.
+## Ship and closeout — automatic, resumable
+
+Shipping writes `08-ship.md`. `/cc-next` then automatically walks the
+feature through a deterministic three-step closeout without extra
+commands from you:
+
+1. **Retro (`09-retro.md`).** cclaw drafts a retrospective from your
+   stage artifacts, the delegation log, and the knowledge entries
+   recorded during the run. It then asks exactly **one** structured
+   question:
+   - **accept** *(default)* — keep the draft, record one `compound`
+     knowledge entry, advance.
+   - **edit** — you edit `09-retro.md` in place, then `/cc-next` again.
+   - **skip** — record a one-line reason, continue (archive will
+     surface the skip in the run manifest).
+2. **Compound pass.** If the knowledge store has clusters recurring 3+
+   times, cclaw proposes concrete lifts into rules/protocols/skills and
+   asks once: apply-all / apply-selected / skip. An empty pass advances
+   silently.
+3. **Archive.** Moves artifacts into `.cclaw/runs/YYYY-MM-DD-<slug>/`,
+   snapshots `state/`, writes a manifest, and resets `flow-state.json`
+   to the track's initial stage.
+
+The chain is driven by `closeout.shipSubstate` inside `flow-state.json`
+(`retro_review` → `compound_review` → `ready_to_archive` → `archived`).
+If your session dies mid-closeout, a new `/cc-next` resumes at the
+exact step — retro drafts are not regenerated and no structured ask is
+repeated silently.
+
+You can still invoke each step manually (`/cc-ops retro`, `/cc-ops
+compound`, `/cc-ops archive`), but for the default path you do not need
+to: `/cc-next` is the only command.
 
 ---
 
@@ -355,7 +375,8 @@ npx cclaw-cli --version
 For CI or scripted installs, `cclaw-cli init --harnesses=<list>
 --no-interactive` is the non-interactive form. All other tunables
 (prompt-guard strictness, TDD enforcement, language rule packs, track
-heuristics) are set by editing `.cclaw/config.yaml` directly.
+heuristics) are set by editing `.cclaw/config.yaml` directly — see
+[`docs/config.md`](./docs/config.md) for the full key reference.
 
 ---
 

package/dist/cli.d.ts

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
-import type { FlowTrack, HarnessId, InitProfile } from "./types.js";
+import type { FlowTrack, HarnessId } from "./types.js";
 import type { EvalMode } from "./eval/types.js";
 type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive" | "eval";
 interface ParsedArgs {
     command?: CommandName;
     harnesses?: HarnessId[];
     track?: FlowTrack;
-    profile?: InitProfile;
     dryRun?: boolean;
     interactive?: boolean;
     reconcileGates?: boolean;
@@ -40,6 +39,5 @@ interface ParsedArgs {
 export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseTrack(raw: string): FlowTrack;
-declare function parseProfile(raw: string): InitProfile;
 declare function parseArgs(argv: string[]): ParsedArgs;
-export { parseArgs, parseHarnesses, parseTrack, parseProfile };
+export { parseArgs, parseHarnesses, parseTrack };

package/dist/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
-import { createReadStream, realpathSync } from "node:fs";
+import { createReadStream, existsSync, realpathSync } from "node:fs";
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import process from "node:process";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { FLOW_TRACKS, HARNESS_IDS, INIT_PROFILES } from "./types.js";
+import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
 import { doctorChecks, doctorSucceeded } from "./doctor.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { error, info } from "./logger.js";
 import { archiveRun } from "./runs.js";
 import { CCLAW_VERSION, RUNTIME_ROOT } from "./constants.js";
-import { createDefaultConfig, createProfileConfig } from "./config.js";
+import { createDefaultConfig } from "./config.js";
 import { detectHarnesses } from "./init-detect.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { runEval } from "./eval/runner.js";
@@ -21,7 +21,6 @@ import { writeBaselinesFromReport } from "./eval/baseline.js";
 import { writeJsonReport, writeMarkdownReport } from "./eval/report.js";
 import { formatDiffMarkdown, runEvalDiff } from "./eval/diff.js";
 import { ensureRunDir, generateRunId, isRunAlive, listRuns, readRunStatus, resolveRunId, runLogPath, writeRunStatus } from "./eval/runs.js";
-import { EVAL_MODES } from "./eval/types.js";
 import { parseModeInput } from "./eval/mode.js";
 import { FLOW_STAGES } from "./types.js";
 const INSTALLER_COMMANDS = [
@@ -37,82 +36,33 @@ export function usage() {
     return `cclaw - installer-first flow toolkit
 
 Usage:
-  cclaw <command> [flags]
-  cclaw --help | -h
-  cclaw --version | -v
+  npx cclaw-cli                   # launch setup or print "already installed" hint
+  npx cclaw-cli <command> [flags]
+  npx cclaw-cli --help | -h
+  npx cclaw-cli --version | -v
 
 Commands:
   init       Bootstrap .cclaw runtime, state, and harness shims in this project.
-             Flags: --profile=<id>      Pre-fill defaults. One of: minimal | standard | full. Default: standard.
-                    --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex). Overrides the profile default.
-                    --track=<id>        Flow track for new runs (standard | medium | quick). Overrides the profile default.
-                    --interactive       Force interactive prompts (TTY only).
-                    --no-interactive    Skip interactive prompts even on TTY.
-                    --dry-run           Print resolved config + generated surfaces without writing files.
-  sync       Regenerate harness shim files from the current .cclaw config (non-destructive).
-  doctor     Run health checks against the local .cclaw runtime. Exit code 2 when any error-severity check fails.
-             Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
-                    --json              Emit machine-readable JSON output.
-                    --only=<filter>     Comma list of severities/check-name filters (error,warning,info,trace:,hook:...).
-                    --explain           Include fix + doc reference per check in text mode.
-                    --quiet             Print only failing checks (and totals).
-  archive    Move .cclaw/artifacts into .cclaw/runs/<date>-<slug> and reset flow state.
-             Flags: --name=<feature>    Feature slug (default: inferred from 00-idea.md).
-                    --skip-retro       Bypass mandatory retro gate (requires --retro-reason).
-                    --retro-reason=<t> Reason for bypassing retro gate.
-  eval       Run cclaw evals against .cclaw/evals/corpus (Phase 7: structural verifier + baselines).
-             Flags: --stage=<id>         Limit to one flow stage (${FLOW_STAGES.join("|")}) for fixture/agent modes.
-                    --mode=<${EVAL_MODES.join("|")}>
-                                         Evaluation mode:
-                                           fixture  = verify existing artifacts with structural/rule/judge verifiers.
-                                           agent    = LLM drafts one stage's artifact in a sandbox with tools.
-                                           workflow = LLM runs the full multi-stage flow (brainstorm→plan).
-                                         Legacy --tier=A|B|C still works (deprecated).
-                    --schema-only        Run only structural verifiers (default).
-                    --rules              Also run rule-based verifiers (keywords, regex, counts, uniqueness, traceability).
-                    --judge              Run the LLM judge (median-of-N) against each case's rubric. Requires CCLAW_EVAL_API_KEY; fixture mode judges an existing artifact, agent/workflow modes draft first and then judge.
-                    --dry-run            Validate config + corpus, print summary, do not execute.
-                    --json               Emit machine-readable JSON on stdout.
-                    --no-write           Skip writing the report to .cclaw/evals/reports/.
-                    --update-baseline    Overwrite baselines from the current run (requires --confirm).
-                    --confirm            Acknowledge --update-baseline (prevents accidental resets).
-                    --quiet              Silence the stderr progress logger (default: emit one
-                                         line per case / stage to stderr so long runs are visible).
-                    --max-cost-usd=<n>   Abort the run if committed USD spend crosses <n>
-                                         (independent from the daily cap). Also readable from
-                                         CCLAW_EVAL_MAX_COST_USD.
-                    --compare-model=<id> Run the same corpus twice — once with the configured model
-                                         and once with <id> — then diff the summaries. Exit code 1
-                                         when the override model regressed.
-                    --background         Spawn the run as a detached child process, write the
-                                         combined output to .cclaw/evals/runs/<id>/run.log, and
-                                         return immediately. Attach later with
-                                         \`cclaw eval runs tail <id|latest>\`.
-
-             Subcommands:
-                    diff <old> <new>     Compare two reports under .cclaw/evals/reports/.
-                                         Each argument is a cclawVersion (e.g. 0.26.0), a filename,
-                                         or the literal "latest". Exit code 1 when the diff shows a
-                                         regression. Accepts --json to emit machine-readable output.
-                    runs [action] [id]   Inspect background runs under .cclaw/evals/runs/.
-                                         Actions: list (default) | status <id|latest> | tail <id|latest>.
-  upgrade    Refresh generated files in .cclaw without modifying user artifacts.
+             Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
+                    --no-interactive    Skip interactive prompts even on TTY (for CI/scripts).
+  upgrade    Refresh generated files in .cclaw. Preserves your config.yaml.
   uninstall  Remove .cclaw runtime and the generated harness shim files.
+  eval       Run cclaw evals. Maintainer surface — see docs/evals.md.
+             Full flag reference: \`npx cclaw-cli eval --help\` or docs/evals.md.
 
 Global flags:
   -h, --help     Show this help message and exit 0.
   -v, --version  Print the cclaw CLI version and exit 0.
 
 Examples:
-  cclaw init --harnesses=claude,cursor
-  cclaw doctor --reconcile-gates
-  cclaw archive --name=payments-revamp
-  cclaw eval --dry-run
-  cclaw eval --stage=brainstorm --schema-only
-  cclaw eval --judge --mode=fixture --stage=brainstorm
-  cclaw eval --judge --mode=agent --stage=spec
-  cclaw eval --mode=workflow --judge
-  cclaw eval diff 0.26.0 latest
+  npx cclaw-cli
+  npx cclaw-cli init --harnesses=claude,cursor --no-interactive
+  npx cclaw-cli upgrade
+  npx cclaw-cli eval --dry-run
+
+Everything operational (retro, archive, worktrees, doctor, learnings)
+happens inside your harness via slash commands. The CLI is just a
+launcher. See README.md for the four user-facing slash commands.
 
 Docs:   https://github.com/zuevrs/cclaw
 Issues: https://github.com/zuevrs/cclaw/issues
@@ -136,13 +86,6 @@ function parseTrack(raw) {
     }
     return trimmed;
 }
-function parseProfile(raw) {
-    const trimmed = raw.trim();
-    if (!INIT_PROFILES.includes(trimmed)) {
-        throw new Error(`Unknown profile: ${trimmed}. Supported: ${INIT_PROFILES.join(", ")}`);
-    }
-    return trimmed;
-}
 function parseLegacyTier(raw) {
     return parseModeInput(raw.toUpperCase(), {
         source: "cli",
@@ -165,6 +108,26 @@ function parseEvalStage(raw) {
 function isInitPromptAllowed(ctx) {
     return Boolean(process.stdin.isTTY && ctx.stdout.isTTY);
 }
+/**
+ * Print a short, friendly hint when the user runs `cclaw-cli` with no
+ * arguments. Does not read or mutate flow state — only checks whether
+ * `.cclaw/config.yaml` exists to branch between "installed" and
+ * "not-installed" messaging. Keeps exit 0 in both cases: users discover
+ * the tool through this path, not through an error.
+ */
+function printNoArgsHint(ctx) {
+    const installed = existsSync(path.join(ctx.cwd, RUNTIME_ROOT, "config.yaml"));
+    if (installed) {
+        ctx.stdout.write("cclaw is installed in this project. Open your harness (Claude Code, " +
+            "Cursor, OpenCode, or Codex) and type `/cc` to start.\n");
+    }
+    else {
+        ctx.stdout.write("cclaw is not installed in this project yet.\n" +
+            "Run `npx cclaw-cli init` to bootstrap .cclaw and the harness shims.\n" +
+            "For help: `npx cclaw-cli --help`.\n");
+    }
+    return 0;
+}
 function buildInitSurfacePreview(harnesses) {
     const lines = [
         ".cclaw/config.yaml",
@@ -206,39 +169,11 @@ function buildInitSurfacePreview(harnesses) {
     }
     return lines;
 }
-function inferTrackDefault(profile, track) {
-    if (track)
-        return track;
-    if (!profile)
-        return "standard";
-    return createProfileConfig(profile).defaultTrack ?? "standard";
-}
 async function promptInitConfig(defaults, ctx) {
     const rl = createInterface({
         input: process.stdin,
         output: ctx.stdout
     });
-    const pickSingle = async (label, options, fallback) => {
-        while (true) {
-            ctx.stdout.write(`\n${label}\n`);
-            options.forEach((option, index) => {
-                const marker = option === fallback ? " (default)" : "";
-                ctx.stdout.write(`  ${index + 1}) ${option}${marker}\n`);
-            });
-            const answer = (await rl.question("> ")).trim();
-            if (answer.length === 0) {
-                return fallback;
-            }
-            const numeric = Number(answer);
-            if (Number.isInteger(numeric) && numeric >= 1 && numeric <= options.length) {
-                return options[numeric - 1];
-            }
-            if (options.includes(answer)) {
-                return answer;
-            }
-            ctx.stdout.write("Invalid selection. Use option number or value.\n");
-        }
-    };
     const pickHarnesses = async (fallback) => {
         const fallbackText = fallback.join(",");
         while (true) {
@@ -260,11 +195,8 @@ async function promptInitConfig(defaults, ctx) {
         }
     };
     try {
-        const profile = await pickSingle("Select init profile:", INIT_PROFILES, defaults.profile);
-        const trackDefault = inferTrackDefault(profile, defaults.track);
-        const track = await pickSingle("Select default flow track:", FLOW_TRACKS, trackDefault);
         const harnesses = await pickHarnesses(defaults.harnesses);
-        return { profile, track, harnesses };
+        return { harnesses };
     }
     finally {
         rl.close();
@@ -279,13 +211,11 @@ async function resolveInitInputs(parsed, ctx) {
     const promptForbidden = parsed.interactive === false;
     const implicitPrompt = !promptForbidden &&
         isInitPromptAllowed(ctx) &&
-        parsed.profile === undefined &&
         parsed.track === undefined &&
         parsed.harnesses === undefined;
     const shouldPrompt = promptRequested || implicitPrompt;
     if (!shouldPrompt) {
         return {
-            profile: parsed.profile,
             track: parsed.track,
             harnesses: autoHarnesses,
             detectedHarnesses
@@ -295,14 +225,11 @@ async function resolveInitInputs(parsed, ctx) {
         throw new Error("Interactive init requires a TTY. Remove --interactive or run in a terminal.");
     }
     const defaults = {
-        profile: parsed.profile ?? "standard",
-        track: inferTrackDefault(parsed.profile, parsed.track),
         harnesses: autoHarnesses ?? HARNESS_IDS.slice()
     };
     const prompted = await promptInitConfig(defaults, ctx);
     return {
-        profile: prompted.profile,
-        track: prompted.track,
+        track: parsed.track,
         harnesses: prompted.harnesses,
         detectedHarnesses
     };
@@ -447,7 +374,6 @@ function parseArgs(argv) {
             continue;
         }
         if (flag.startsWith("--profile=")) {
-            parsed.profile = parseProfile(flag.replace("--profile=", ""));
             continue;
         }
         if (flag === "--interactive") {
@@ -780,28 +706,20 @@ async function runCommand(parsed, ctx) {
     }
     const command = parsed.command;
     if (!command) {
-        ctx.stderr.write(usage());
-        return 1;
+        return printNoArgsHint(ctx);
     }
     if (command === "init") {
         const resolved = await resolveInitInputs(parsed, ctx);
-        const effectiveProfile = resolved.profile;
         const effectiveTrack = resolved.track;
         const effectiveHarnesses = resolved.harnesses;
         if (parsed.dryRun === true) {
-            const previewConfig = effectiveProfile
-                ? createProfileConfig(effectiveProfile, {
-                    harnesses: effectiveHarnesses,
-                    defaultTrack: effectiveTrack
-                })
-                : createDefaultConfig(effectiveHarnesses, effectiveTrack);
+            const previewConfig = createDefaultConfig(effectiveHarnesses, effectiveTrack);
             const previewSurfaces = buildInitSurfacePreview(previewConfig.harnesses);
             info(ctx, "Dry run: no files were written.");
             if (resolved.detectedHarnesses.length > 0 && parsed.harnesses === undefined) {
                 info(ctx, `Detected harnesses from repo: ${resolved.detectedHarnesses.join(", ")}`);
             }
             ctx.stdout.write(`${JSON.stringify({
-                profile: effectiveProfile ?? "standard(default)",
                 track: previewConfig.defaultTrack ?? "standard",
                 harnesses: previewConfig.harnesses,
                 promptGuardMode: previewConfig.promptGuardMode,
@@ -814,16 +732,13 @@ async function runCommand(parsed, ctx) {
         await initCclaw({
             projectRoot: ctx.cwd,
             harnesses: effectiveHarnesses,
-            track: effectiveTrack,
-            profile: effectiveProfile
+            track: effectiveTrack
         });
         if (resolved.detectedHarnesses.length > 0 && parsed.harnesses === undefined) {
             info(ctx, `Detected harnesses from repo: ${resolved.detectedHarnesses.join(", ")}`);
         }
-        const profileNote = effectiveProfile ? ` profile=${effectiveProfile}` : "";
-        const trackNote = effectiveTrack ? ` track=${effectiveTrack}` : "";
-        const suffix = profileNote || trackNote ? ` (${(profileNote + trackNote).trim()})` : "";
-        info(ctx, `Initialized .cclaw runtime and generated harness shims${suffix}`);
+        const trackNote = effectiveTrack ? ` (track=${effectiveTrack})` : "";
+        info(ctx, `Initialized .cclaw runtime and generated harness shims${trackNote}`);
         return 0;
     }
     if (command === "sync") {
@@ -1043,4 +958,4 @@ function isDirectExecution() {
 if (isDirectExecution()) {
     void main();
 }
-export { parseArgs, parseHarnesses, parseTrack, parseProfile };
+export { parseArgs, parseHarnesses, parseTrack };

package/dist/config.d.ts

@@ -1,15 +1,5 @@
-import type { FlowTrack, HarnessId, InitProfile, LanguageRulePack, VibyConfig } from "./types.js";
+import type { FlowTrack, HarnessId, VibyConfig } from "./types.js";
 export declare function configPath(projectRoot: string): string;
 export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): VibyConfig;
-/**
- * Build a VibyConfig for a named init profile. Profile defaults are applied
- * first, then any explicit overrides (CLI flags) win. This keeps the profile
- * contract deterministic and testable.
- */
-export declare function createProfileConfig(profile: InitProfile, overrides?: {
-    harnesses?: HarnessId[];
-    defaultTrack?: FlowTrack;
-    languageRulePacks?: LanguageRulePack[];
-}): VibyConfig;
 export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
 export declare function writeConfig(projectRoot: string, config: VibyConfig): Promise<void>;

package/dist/config.js

@@ -67,46 +67,6 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack
         languageRulePacks: []
     };
 }
-/**
- * Build a VibyConfig for a named init profile. Profile defaults are applied
- * first, then any explicit overrides (CLI flags) win. This keeps the profile
- * contract deterministic and testable.
- */
-export function createProfileConfig(profile, overrides = {}) {
-    const base = createDefaultConfig();
-    switch (profile) {
-        case "minimal":
-            return {
-                ...base,
-                harnesses: overrides.harnesses ?? ["claude"],
-                promptGuardMode: "advisory",
-                tddEnforcement: "advisory",
-                gitHookGuards: false,
-                defaultTrack: overrides.defaultTrack ?? "medium",
-                languageRulePacks: overrides.languageRulePacks ?? []
-            };
-        case "standard":
-            return {
-                ...base,
-                harnesses: overrides.harnesses ?? DEFAULT_HARNESSES,
-                promptGuardMode: "advisory",
-                tddEnforcement: "advisory",
-                gitHookGuards: false,
-                defaultTrack: overrides.defaultTrack ?? "standard",
-                languageRulePacks: overrides.languageRulePacks ?? []
-            };
-        case "full":
-            return {
-                ...base,
-                harnesses: overrides.harnesses ?? DEFAULT_HARNESSES,
-                promptGuardMode: "strict",
-                tddEnforcement: "strict",
-                gitHookGuards: true,
-                defaultTrack: overrides.defaultTrack ?? "standard",
-                languageRulePacks: overrides.languageRulePacks ?? [...LANGUAGE_RULE_PACKS]
-            };
-    }
-}
 export async function readConfig(projectRoot) {
     const fullPath = configPath(projectRoot);
     if (!(await exists(fullPath))) {

package/dist/content/archive-command.js

@@ -15,35 +15,46 @@ export function archiveCommandContract() {
 
 ## Purpose
 
-Archive the active cclaw run from inside the harness flow (agent-first finish).
+Finalize the active cclaw run: move artifacts to \`${runsPath()}/<archive-id>\`,
+snapshot state, write a manifest, and reset runtime for the next run.
 
-This command removes the user-facing CLI gap: users can stay in \`/cc-*\` flow and
-finish with \`/cc-ops archive\` after ship + retro are complete.
+Auto-triggered by \`/cc-next\` when \`closeout.shipSubstate === "ready_to_archive"\`.
+Direct invocation from a harness command is supported but rarely needed.
 
 ## HARD-GATE
 
-- Do not archive a shipped run when retro is still incomplete.
-- Do not manually move files between \`${activeArtifactsPath()}\` and \`${runsPath()}\`.
-- Use the archive runtime so state snapshots + manifest stay consistent.
+- Do not archive with \`closeout.shipSubstate !== "ready_to_archive"\`.
+- Do not archive a shipped run when \`retro.completedAt\` is missing and
+  \`closeout.retroSkipped !== true\`.
+- Never hand-move files between \`${activeArtifactsPath()}\` and \`${runsPath()}\`.
+  Always run the archive runtime command so the snapshot+manifest stay
+  atomic.
 
 ## Inputs
 
-\`/cc-ops archive [--name=<slug>] [--skip-retro --retro-reason=<text>]\`
+\`/cc-ops archive [--name=<slug>]\`
+
+(Legacy flags \`--skip-retro --retro-reason=<text>\` still exist for CLI
+invocations; in-harness the skip path is driven by \`closeout.retroSkipped\`
+set during retro.)
 
 ## Algorithm
 
 1. Read \`${flowStatePath()}\`.
-2. If ship is complete and \`retro.completedAt\` is absent:
-   - block with explicit instruction: run \`/cc-ops retro\` first.
+2. Verify \`closeout.shipSubstate === "ready_to_archive"\`. If not, report
+   \`closeout not ready (state=<substate>) | run: /cc-next\` and stop.
 3. Build archive command:
-   - base: \`npx cclaw archive\`
-   - optional: \`--name=<slug>\`
-   - optional override: \`--skip-retro --retro-reason=<text>\`
-4. Execute archive command in project root.
-5. Surface result:
+   - base: \`npx cclaw archive\`,
+   - optional: \`--name=<slug>\`,
+   - legacy override: \`--skip-retro --retro-reason=<text>\` (only when user
+     explicitly wants the CLI skip path).
+4. Execute the archive command in project root.
+5. On success, flow-state is reset to the initial stage for the default
+   track; \`closeout.shipSubstate\` returns to \`"idle"\` on reset.
+6. Surface:
    - archive id/path,
-   - reset stage (brainstorm/spec depending on track default),
-   - knowledge curation hint when threshold exceeded.
+   - reset stage,
+   - knowledge curation hint when \`activeEntryCount >= softThreshold\`.
 
 ## Output format
 
@@ -63,36 +74,51 @@ cclaw archive
 export function archiveCommandSkillMarkdown() {
     return `---
 name: ${ARCHIVE_SKILL_NAME}
-description: "Archive the active cclaw run from harness flow and reset runtime safely."
+description: "Finalize the active cclaw run. Auto-triggered by /cc-next when shipSubstate=ready_to_archive."
 ---
 
 # /cc-ops archive
 
 ## HARD-GATE
 
-Never simulate archive by hand-editing runtime files. Always execute the archive
-runtime command so state snapshots and manifest generation stay atomic.
+Never simulate archive by hand-editing runtime files. Always execute the
+archive runtime command so state snapshots and manifest generation stay
+atomic. Never bypass the substate check — if retro/compound haven't
+advanced the substate to \`ready_to_archive\`, stop and surface the
+mismatch.
 
 ## Protocol
 
 1. Read \`${flowStatePath()}\`:
-   - confirm whether ship is completed,
-   - check \`retro.completedAt\` for post-ship runs.
-2. If ship complete and retro incomplete -> stop and direct user to \`/cc-ops retro\`.
-3. Build shell command:
-   - \`npx cclaw archive\`
-   - append \`--name=<slug>\` when provided
-   - append \`--skip-retro --retro-reason=<text>\` only when user explicitly requests skip
-4. Run command from repo root.
-5. Relay key lines from output:
-   - archive destination under \`${runsPath()}\`
-   - flow reset confirmation
-   - knowledge curation recommendation
+   - if \`closeout.shipSubstate !== "ready_to_archive"\`, stop and route
+     the user back to \`/cc-next\` (it will resume at the correct step),
+   - sanity-check: \`completedStages\` must include \`"ship"\`,
+   - sanity-check: \`retro.completedAt\` is set **or**
+     \`closeout.retroSkipped === true\` with a reason.
+2. Build shell command:
+   - \`npx cclaw archive\`,
+   - append \`--name=<slug>\` when provided,
+   - append legacy \`--skip-retro --retro-reason=<text>\` only when the user
+     explicitly requests the CLI skip path (normally not needed — skip is
+     captured in \`closeout\` during retro).
+3. Run command from repo root.
+4. Relay key lines from output:
+   - archive destination under \`${runsPath()}\`,
+   - flow reset confirmation,
+   - knowledge curation recommendation if \`activeEntryCount >= 50\`.
+
+## Resume semantics
+
+Archive is idempotent on a per-run basis. If a previous session ran
+archive successfully, the active artifacts directory is empty and
+\`closeout.shipSubstate\` is \`"idle"\`; \`/cc-next\` will simply report
+"Flow complete" or prompt for a new \`/cc\` input.
 
 ## Validation
 
-- \`${runsPath()}\` contains a new archive folder.
+- \`${runsPath()}\` contains a new archive folder for this run.
 - \`${activeArtifactsPath()}\` is reset for the next run.
 - \`${flowStatePath()}\` is valid JSON and points to the initial stage.
+- \`closeout.shipSubstate === "idle"\` after reset.
 `;
 }