cclaw-cli 0.5.15 → 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/stage-schema.js

@@ -1556,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 |

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.15",
+  "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"
   }