cclaw-cli 0.5.14 → 0.5.16

package/README.md

@@ -120,6 +120,12 @@ Required repository secret:
 └── runs/                     # archived feature snapshots (YYYY-MM-DD-feature-name)
 ```
 
+## Harness Integration
+
+Supported harnesses: `claude`, `cursor`, `opencode`, `codex`. The full
+per-harness install surface, feature matrix, and lifecycle details live in
+[docs/harnesses.md](./docs/harnesses.md).
+
 ## License
 
 [MIT](./LICENSE)

package/dist/cli.d.ts

@@ -6,7 +6,10 @@ interface ParsedArgs {
     harnesses?: HarnessId[];
     reconcileGates?: boolean;
     archiveName?: string;
+    showHelp?: boolean;
+    showVersion?: boolean;
 }
+export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseArgs(argv: string[]): ParsedArgs;
 export { parseArgs, parseHarnesses };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import process from "node:process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,18 +9,63 @@ import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js
 import { error, info } from "./logger.js";
 import { archiveRun } from "./runs.js";
 const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall", "archive"];
-function usage() {
+export function usage() {
     return `cclaw - installer-first flow toolkit
 
 Usage:
-  cclaw init [--harnesses=claude,cursor,opencode,codex]
-  cclaw sync
-  cclaw doctor [--reconcile-gates]
-  cclaw archive [--name=feature-name]
-  cclaw upgrade
-  cclaw uninstall
+  cclaw <command> [flags]
+  cclaw --help | -h
+  cclaw --version | -v
+
+Commands:
+  init       Bootstrap .cclaw runtime, state, and harness shims in this project.
+             Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
+  sync       Regenerate harness shim files from the current .cclaw config (non-destructive).
+  doctor     Run health checks against the local .cclaw runtime. Exit code 2 on failure.
+             Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
+  archive    Move .cclaw/artifacts into .cclaw/runs/<date>-<slug> and reset flow state.
+             Flags: --name=<feature>    Feature slug (default: inferred from 00-idea.md).
+  upgrade    Refresh generated files in .cclaw without modifying user artifacts.
+  uninstall  Remove .cclaw runtime and the generated harness shim files.
+
+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
+
+Docs:   https://github.com/zuevrs/cclaw
+Issues: https://github.com/zuevrs/cclaw/issues
 `;
 }
+function cliPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            path.resolve(here, "../package.json"),
+            path.resolve(here, "../../package.json")
+        ];
+        for (const candidate of candidates) {
+            try {
+                const raw = readFileSync(candidate, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed.name === "cclaw-cli" && typeof parsed.version === "string") {
+                    return parsed.version;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "unknown";
+}
 function parseHarnesses(raw) {
     const requested = raw
         .split(",")
@@ -33,11 +78,19 @@ function parseHarnesses(raw) {
     return requested;
 }
 function parseArgs(argv) {
-    const [commandRaw, ...flags] = argv;
-    const command = INSTALLER_COMMANDS.includes(commandRaw)
+    const parsed = {};
+    const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
+    if (helpFlag) {
+        parsed.showHelp = true;
+    }
+    const versionFlag = argv.find((arg) => arg === "--version" || arg === "-v");
+    if (versionFlag) {
+        parsed.showVersion = true;
+    }
+    const [commandRaw, ...flags] = argv.filter((arg) => arg !== "--help" && arg !== "-h" && arg !== "--version" && arg !== "-v");
+    parsed.command = INSTALLER_COMMANDS.includes(commandRaw)
         ? commandRaw
         : undefined;
-    const parsed = { command };
     for (const flag of flags) {
         if (flag.startsWith("--harnesses=")) {
             parsed.harnesses = parseHarnesses(flag.replace("--harnesses=", ""));
@@ -54,6 +107,14 @@ function parseArgs(argv) {
     return parsed;
 }
 async function runCommand(parsed, ctx) {
+    if (parsed.showHelp) {
+        ctx.stdout.write(usage());
+        return 0;
+    }
+    if (parsed.showVersion) {
+        ctx.stdout.write(`cclaw ${cliPackageVersion()}\n`);
+        return 0;
+    }
     const command = parsed.command;
     if (!command) {
         ctx.stderr.write(usage());
@@ -88,7 +149,10 @@ async function runCommand(parsed, ctx) {
     }
     if (command === "archive") {
         const archived = await archiveRun(ctx.cwd, parsed.archiveName);
-        info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.`);
+        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}`);
         return 0;
     }
     await uninstallCclaw(ctx.cwd);

package/dist/content/agents.js

@@ -216,7 +216,7 @@ export function agentRoutingTable() {
 | Brainstorm (start with \`/cc <idea>\`) | planner | — |
 | Scope / Design / Spec / Plan (advance via \`/cc-next\`) | planner | security-reviewer on design, spec-reviewer on spec |
 | TDD (via \`/cc-next\`) | test-author | doc-updater |
-| Review (via \`/cc-next\`) | spec-reviewer, code-reviewer | security-reviewer |
+| Review (via \`/cc-next\`) | spec-reviewer, code-reviewer, security-reviewer | — |
 | Ship (via \`/cc-next\`) | — | doc-updater |
 `;
 }
@@ -231,8 +231,8 @@ Cclaw provides specialist agents under \`.cclaw/agents/\` for targeted delegatio
 ${agentRoutingTable()}
 
 **Activation modes:**
-- **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer during review)
-- **Proactive:** Should be used automatically when context matches (planner for complex features, security-reviewer for auth code)
+- **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer, and security-reviewer during review; planner during scope and design; test-author during tdd; doc-updater during ship). Even if a change has no trust-boundary impact, security-reviewer produces an explicit no-change attestation.
+- **Proactive:** Should be used automatically when context matches (planner for complex features, security-reviewer escalations outside review, doc-updater on behavior changes)
 - **On-demand:** Invoked only when explicitly requested
 
 **Agent files:** \`.cclaw/agents/{name}.md\` — each contains YAML frontmatter with tools and model tier.

package/dist/content/contracts.js

@@ -11,6 +11,12 @@ export function commandContract(stage) {
     const gateIds = schema.requiredGates
         .map((g) => `\`${g.id}\``)
         .join(", ");
+    const writes = schema.crossStageTrace.writesTo;
+    const writesLine = writes.map((w) => `\`${w}\``).join(", ");
+    const primaryArtifact = `.cclaw/artifacts/${schema.artifactFile}`;
+    const writeStepPaths = writes.length > 1
+        ? writes.map((w) => `\`${w}\``).join(" and ")
+        : `\`${primaryArtifact}\``;
     return `# /cc-${stage}
 
 Load and follow **${skillPath}** — it contains the full checklist, examples, interaction protocol, and verification discipline.
@@ -20,7 +26,7 @@ ${schema.hardGate}
 
 ## In / Out
 - **Reads:** ${readsLine}
-- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\`
+- **Writes:** ${writesLine}
 - **Next:** \`/cc-next\` (updates flow-state and loads the next stage)
 
 ## Context Hydration (mandatory before stage work)
@@ -29,7 +35,7 @@ ${schema.hardGate}
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
 4. Load \`.cclaw/knowledge.md\` and apply relevant entries.
-5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\`.
+5. Write stage output to ${writeStepPaths}.
 6. Do NOT copy artifacts into \`.cclaw/runs/\`; archival is handled only by \`cclaw archive\`.
 
 ## Gates

package/dist/content/examples.js

@@ -398,33 +398,39 @@ Execution rule: complete and verify each wave before starting the next wave.
 ### Final Verdict
 
 - BLOCKED`,
-    ship: `### Preflight checklist (sample)
+    ship: `### Preflight Results
 
-- tests ✅ (\`pnpm test\` green on main)
-- build ✅ (\`pnpm build\` succeeds)
-- lint ✅ (\`pnpm lint\` clean)
-- type-check ✅ (\`pnpm typecheck\` clean)
+- Review verdict: APPROVED_WITH_CONCERNS (R-1 resolved, R-2 accepted as known debt)
+- Build: pass (\`pnpm build\` succeeds)
+- Tests: pass (\`pnpm vitest run && pnpm playwright test\` — 47 passed, 0 failed)
+- Lint: pass (\`pnpm lint\` clean)
+- Type-check: pass (\`pnpm typecheck\` clean)
+- Working tree clean: yes (\`git status\` shows no uncommitted changes)
 
-### Release notes (sample)
+### Release Notes
 
-- **Added:** In-app notification feed with SSE updates and REST fallback snapshotting.
-- **Changed:** Notification payloads now include a stable dedupe key for idempotent rendering.
+- **Added:** In-app notification feed with SSE updates and REST fallback snapshotting (AC-1, AC-3).
+- **Changed:** Notification payloads now include a stable dedupe key for idempotent rendering (AC-2).
 - **Fixed:** Panel no longer drops the newest item when reconnecting after sleep/resume.
+- **Breaking changes:** None.
 
-### Rollback plan (sample)
+### Rollback Plan
 
-1. Revert release tag \`v1.14.0\` to \`v1.13.2\` and redeploy the previous container image from the registry.
-2. If database migrations shipped, run the documented down migration \`2026_04_12_notifications_cursor_down.sql\` before serving traffic again.
+- Trigger conditions: error rate on \`/notifications/stream\` exceeds 5% for >5 minutes, or p95 publish-to-visible lag exceeds 10s.
+- Rollback steps: \`git revert <merge-sha> && git push origin main\` then redeploy; if DB migrations shipped, run \`2026_04_12_notifications_cursor_down.sql\` before traffic.
+- Verification steps: confirm error rate returns to pre-release baseline within 10 minutes; smoke-test feed panel manually.
 
-### Post-release monitoring (sample)
+### Monitoring
 
-- Watch error rate on \`/notifications/stream\` and snapshot endpoint separately for 24 hours.
-- Track p95 “publish → visible” lag via existing metrics dashboard; alert if SLO regresses.
+- Metrics/logs to watch: error rate on \`/notifications/stream\` and snapshot endpoint for 24h; p95 publish-to-visible lag via metrics dashboard.
+- Risk note (if no monitoring): N/A — monitoring is in place.
 
-### Communications (sample)
+### Finalization
 
-- Post a short internal changelog entry linking to release notes and rollback doc location.
-- If user-visible behavior changes, prepare a one-paragraph support macro explaining the new feed + fallback behavior.`,
+- Selected enum: FINALIZE_OPEN_PR
+- Selected label: B
+- Execution result: PR #42 created via \`gh pr create\`; CI passed; squash-merged to main.
+- PR URL: https://github.com/example/repo/pull/42`,
 };
 export function stageExamples(stage) {
     const examples = STAGE_EXAMPLES[stage];

package/dist/content/stage-schema.js

@@ -1350,7 +1350,8 @@ const SHIP = {
         { id: "ship_release_notes_written", description: "Release notes are complete and accurate." },
         { id: "ship_rollback_plan_ready", description: "Rollback trigger, steps, and verification are documented." },
         { id: "ship_finalization_mode_selected", description: "Exactly one finalization action is selected." },
-        { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." }
+        { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." },
+        { id: "ship_post_merge_tests", description: "Full test suite re-run on the merged result (not just the branch). Post-merge failures caught before release." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/08-ship.md`.",
@@ -1383,7 +1384,10 @@ const SHIP = {
     rationalizations: [
         { claim: "Rollback details can be written after release.", reality: "Rollback is part of release readiness, not post-release cleanup." },
         { claim: "Finalization choice is obvious from context.", reality: "Explicit branch action prevents accidental release state." },
-        { claim: "Urgent fixes can skip preflight.", reality: "Urgency increases risk; preflight discipline matters more, not less." }
+        { claim: "Urgent fixes can skip preflight.", reality: "Urgency increases risk; preflight discipline matters more, not less." },
+        { claim: "Monitoring can be set up after deploy.", reality: "If you cannot observe the release, you cannot detect failure. Monitoring is a ship prerequisite, not a follow-up task." },
+        { claim: "A small merge does not need post-merge testing.", reality: "Small merges on diverged bases cause silent conflicts. Post-merge suite runs catch what branch-only CI misses." },
+        { claim: "Release notes are internal documentation, not a ship gate.", reality: "Release notes are the rollback decision input. Without them, the team cannot assess what changed or why a rollback is needed." }
     ],
     redFlags: [
         "No rollback trigger/steps",
@@ -1408,7 +1412,8 @@ const SHIP = {
         { name: "Rollback-First Thinking", description: "Before shipping, answer: what tells me this is broken? How do I undo it? How do I verify the undo worked? If you cannot answer all three, you are not ready." },
         { name: "Explicit Over Implicit Finalization", description: "Merge, PR, keep, discard — each has different consequences. Pick one. Say it out loud. Write it down. Never let finalization be 'whatever the default is.'" },
         { name: "Post-Merge Paranoia", description: "The merge itself can introduce failures even when both branches pass independently. Always run the full suite AFTER merge, not just before." },
-        { name: "Observability Before Ship", description: "If you cannot monitor the change in production, you cannot know if it is broken. Monitoring/logging is a ship prerequisite, not a follow-up." }
+        { name: "Observability Before Ship", description: "If you cannot monitor the change in production, you cannot know if it is broken. Monitoring/logging is a ship prerequisite, not a follow-up." },
+        { name: "Release Blast Radius", description: "Before shipping, map the blast radius: how many users are affected if this breaks? Is it one endpoint or the entire app? Scale rollback urgency and monitoring to the blast radius, not the diff size. A 3-line auth change can have infinite blast radius." }
     ],
     reviewSections: [
         {
@@ -1435,17 +1440,22 @@ const SHIP = {
     ],
     completionStatus: ["SHIPPED", "SHIPPED_WITH_EXCEPTIONS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md"],
+        readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
         writesTo: [".cclaw/artifacts/08-ship.md"],
-        traceabilityRule: "Ship artifact must reference review verdict and resolution status. Rollback plan must reference specific changes that could fail."
+        traceabilityRule: "Ship artifact must reference review verdict and resolution status. Release notes must reference spec criteria. Rollback plan must reference specific changes that could fail."
     },
     artifactValidation: [
         { section: "Preflight Results", required: true, validationRule: "Build, test, lint, type-check results captured with fresh output. Exceptions documented if any." },
         { section: "Release Notes", required: true, validationRule: "What changed, why, impact. References spec criteria. Breaking changes flagged." },
         { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
         { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
-        { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected. Execution result documented. Worktree cleaned if applicable." }
-    ]
+        { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected. Execution result documented. Worktree cleaned if applicable." },
+        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." }
+    ],
+    namedAntiPattern: {
+        title: "Green CI Means Safe to Merge",
+        description: "CI passing on a feature branch does not prove the merged result is safe. Post-merge test failures are common when the base branch has diverged. Re-run the full suite on the merge result, not just the branch. A green branch badge is a necessary condition, not a sufficient one."
+    }
 };
 // ---------------------------------------------------------------------------
 // Stage map and accessors
@@ -1546,9 +1556,9 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         },
         {
             agent: "security-reviewer",
-            mode: "proactive",
-            when: "When auth, input validation, secrets, parser, or privileged actions changed.",
-            purpose: "Raise exploitable findings before release.",
+            mode: "mandatory",
+            when: "Always in review stage. Even when no trust boundaries changed, produce an explicit 'no-change' security attestation.",
+            purpose: "Guarantee a dedicated security pass on every diff: auth, input validation, secrets, injection, privilege, and blast-radius review are never opt-in.",
             requiresUserGate: false
         }
     ],

package/dist/content/subagents.js

@@ -35,7 +35,7 @@ For cclaw flow stages, machine-only specialist work should auto-dispatch without
 
 - **design/plan:** planner
 - **tdd:** test-author
-- **review:** spec-reviewer + code-reviewer (security-reviewer when trust boundaries moved)
+- **review:** spec-reviewer + code-reviewer + security-reviewer (security-reviewer is always mandatory; produce an explicit no-change attestation when no trust boundaries moved)
 - **ship:** doc-updater
 
 Human input remains mandatory only at explicit approval gates (plan approval, user challenge resolution, release finalization mode).

package/dist/content/templates.js

@@ -137,9 +137,9 @@ export const ARTIFACT_TEMPLATES = {
 
 ## Architecture Diagram
 
-\\\`\\\`\\\`
+\`\`\`
 (ASCII, Mermaid, or tool-generated diagram showing component boundaries and data flow direction)
-\\\`\\\`\\\`
+\`\`\`
 
 ## What Already Exists
 | Sub-problem | Existing code/library | Layer | Reuse decision |
@@ -422,6 +422,10 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Selected label (A/B/C/D):
 - Execution result:
 - PR URL / merge commit / kept branch / discard confirmation:
+
+## Completion Status
+- SHIPPED | SHIPPED_WITH_EXCEPTIONS | BLOCKED
+- Exceptions (if any):
 `
 };
 export const RULEBOOK_MARKDOWN = `# Cclaw Rulebook

package/dist/runs.d.ts

@@ -1,4 +1,5 @@
 import { type FlowState } from "./flow-state.js";
+import type { FlowStage } from "./types.js";
 export interface CclawRunMeta {
     id: string;
     title: string;
@@ -10,10 +11,26 @@ export interface ArchiveRunResult {
     archivedAt: string;
     featureName: string;
     resetState: FlowState;
+    snapshottedStateFiles: string[];
+}
+export interface ArchiveManifest {
+    version: 1;
+    archiveId: string;
+    archivedAt: string;
+    featureName: string;
+    sourceRunId: string;
+    sourceCurrentStage: FlowStage;
+    sourceCompletedStages: FlowStage[];
+    snapshottedStateFiles: string[];
 }
 interface EnsureRunSystemOptions {
     createIfMissing?: boolean;
 }
+export declare class CorruptFlowStateError extends Error {
+    readonly statePath: string;
+    readonly quarantinedPath: string;
+    constructor(statePath: string, quarantinedPath: string, cause: unknown);
+}
 export declare function readFlowState(projectRoot: string): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState): Promise<void>;
 export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;

package/dist/runs.js

@@ -6,7 +6,13 @@ import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.
 const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
+const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
 const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
+/** State filenames explicitly excluded from the archive snapshot. */
+const STATE_SNAPSHOT_EXCLUDE = new Set([
+    ".flow-state.lock",
+    ".delegation.lock"
+]);
 function flowStatePath(projectRoot) {
     return path.join(projectRoot, FLOW_STATE_REL_PATH);
 }
@@ -19,6 +25,46 @@ function runsRoot(projectRoot) {
 function activeArtifactsPath(projectRoot) {
     return path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH);
 }
+function stateDirPath(projectRoot) {
+    return path.join(projectRoot, STATE_DIR_REL_PATH);
+}
+async function snapshotStateDirectory(projectRoot, destinationRoot) {
+    const sourceDir = stateDirPath(projectRoot);
+    if (!(await exists(sourceDir))) {
+        return [];
+    }
+    await ensureDir(destinationRoot);
+    const copied = [];
+    let entries;
+    try {
+        entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (STATE_SNAPSHOT_EXCLUDE.has(entry.name))
+            continue;
+        if (entry.name.startsWith(".") && !entry.name.endsWith(".json"))
+            continue;
+        const from = path.join(sourceDir, entry.name);
+        const to = path.join(destinationRoot, entry.name);
+        try {
+            if (entry.isDirectory()) {
+                await fs.cp(from, to, { recursive: true });
+                copied.push(`${entry.name}/`);
+            }
+            else if (entry.isFile()) {
+                await fs.copyFile(from, to);
+                copied.push(entry.name);
+            }
+        }
+        catch {
+            // best-effort snapshot; continue on individual failures
+        }
+    }
+    return copied.sort((a, b) => a.localeCompare(b));
+}
 function isFlowStage(value) {
     return typeof value === "string" && FLOW_STAGE_SET.has(value);
 }
@@ -144,18 +190,66 @@ async function uniqueArchiveId(projectRoot, baseId) {
     }
     return candidate;
 }
+export class CorruptFlowStateError extends Error {
+    statePath;
+    quarantinedPath;
+    constructor(statePath, quarantinedPath, cause) {
+        super(`Corrupt flow-state.json detected at ${statePath}. ` +
+            `Quarantined to ${quarantinedPath}. ` +
+            `Inspect the quarantined file, reconcile by hand, then re-run your command ` +
+            `or delete ${statePath} to start over. ` +
+            `Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "CorruptFlowStateError";
+        this.statePath = statePath;
+        this.quarantinedPath = quarantinedPath;
+        if (cause instanceof Error) {
+            this.cause = cause;
+        }
+    }
+}
+function quarantineTimestamp(date = new Date()) {
+    return date.toISOString().replace(/[:.]/gu, "-");
+}
+async function quarantineCorruptState(statePath, cause) {
+    const quarantinedPath = `${statePath}.corrupt-${quarantineTimestamp()}.json`;
+    try {
+        await fs.rename(statePath, quarantinedPath);
+    }
+    catch (renameErr) {
+        try {
+            const raw = await fs.readFile(statePath, "utf8");
+            await fs.writeFile(quarantinedPath, raw, "utf8");
+            await fs.unlink(statePath).catch(() => undefined);
+        }
+        catch {
+            throw new CorruptFlowStateError(statePath, quarantinedPath, renameErr);
+        }
+    }
+    throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
+}
 export async function readFlowState(projectRoot) {
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
         return createInitialFlowState();
     }
+    let raw;
     try {
-        const parsed = JSON.parse(await fs.readFile(statePath, "utf8"));
-        return coerceFlowState(parsed);
+        raw = await fs.readFile(statePath, "utf8");
     }
-    catch {
-        return createInitialFlowState();
+    catch (readErr) {
+        throw new CorruptFlowStateError(statePath, statePath, readErr);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (parseErr) {
+        await quarantineCorruptState(statePath, parseErr);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        await quarantineCorruptState(statePath, new Error("flow-state.json did not deserialize to a JSON object"));
     }
+    return coerceFlowState(parsed);
 }
 export async function writeFlowState(projectRoot, state) {
     await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
@@ -214,17 +308,32 @@ export async function archiveRun(projectRoot, featureName) {
     const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
     const archivePath = path.join(runsDir, archiveId);
     const archiveArtifactsPath = path.join(archivePath, "artifacts");
+    const sourceState = await readFlowState(projectRoot);
     await ensureDir(archivePath);
     await fs.rename(artifactsDir, archiveArtifactsPath);
     await ensureDir(artifactsDir);
+    const archiveStatePath = path.join(archivePath, "state");
+    const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
     const resetState = createInitialFlowState();
     await writeFlowState(projectRoot, resetState);
     const archivedAt = new Date().toISOString();
+    const manifest = {
+        version: 1,
+        archiveId,
+        archivedAt,
+        featureName: feature,
+        sourceRunId: sourceState.activeRunId,
+        sourceCurrentStage: sourceState.currentStage,
+        sourceCompletedStages: sourceState.completedStages,
+        snapshottedStateFiles
+    };
+    await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
     return {
         archiveId,
         archivePath,
         archivedAt,
         featureName: feature,
-        resetState
+        resetState,
+        snapshottedStateFiles
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "build": "npm run clean:dist && tsc -p tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "smoke:runtime": "npm run build && node scripts/smoke-init.mjs",
     "lint:hooks": "npm run build && node scripts/lint-generated-hooks.mjs",
     "build:plugin-manifests": "npm run build && node scripts/build-plugin-manifests.mjs",
@@ -42,6 +43,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.7.2",
+    "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }