cclaw-cli 0.5.15 → 0.5.17

package/dist/doctor.js

@@ -13,7 +13,7 @@ import { policyChecks } from "./policy.js";
 import { readFlowState } from "./runs.js";
 import { checkMandatoryDelegations } from "./delegation.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
-import { reconcileAndWriteCurrentStageGateCatalog, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
+import { reconcileAndWriteCurrentStageGateCatalog, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { stageSkillFolder } from "./content/skills.js";
 import { UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
 import { CONTEXT_MODES, DEFAULT_CONTEXT_MODE } from "./content/contexts.js";
@@ -768,11 +768,37 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? `warning: waived mandatory delegations for stage "${flowState.currentStage}": ${delegation.waived.join(", ")}`
             : "no waived mandatory delegations for current stage"
     });
+    checks.push({
+        name: "warning:delegation:stale_runs",
+        ok: true,
+        details: delegation.staleIgnored.length > 0
+            ? `warning: ${delegation.staleIgnored.length} delegation entries from other runs were ignored: ${delegation.staleIgnored.join(", ")}`
+            : "no stale delegation entries from prior runs"
+    });
     const trace = await buildTraceMatrix(projectRoot);
+    const artifactsDir = path.join(projectRoot, RUNTIME_ROOT, "artifacts");
+    const specExists = await exists(path.join(artifactsDir, "04-spec.md"));
+    const planExists = await exists(path.join(artifactsDir, "05-plan.md"));
+    const tddExists = await exists(path.join(artifactsDir, "06-tdd.md"));
     const traceHasSignal = trace.entries.length > 0 ||
         trace.orphanedCriteria.length > 0 ||
         trace.orphanedTasks.length > 0 ||
         trace.orphanedTests.length > 0;
+    const artifactsPresent = specExists || planExists || tddExists;
+    const emptyMatrixWithArtifacts = !traceHasSignal && artifactsPresent;
+    checks.push({
+        name: "trace:matrix_populated",
+        ok: !emptyMatrixWithArtifacts,
+        details: emptyMatrixWithArtifacts
+            ? `trace matrix is empty but artifacts exist (${[
+                specExists ? "04-spec.md" : null,
+                planExists ? "05-plan.md" : null,
+                tddExists ? "06-tdd.md" : null
+            ].filter(Boolean).join(", ")}). The extractors found no criterion/task/slice IDs — check heading conventions and ID formats.`
+            : artifactsPresent
+                ? `trace matrix parsed ${trace.entries.length} criterion(s) from present artifacts`
+                : "no downstream artifacts to trace yet"
+    });
     checks.push({
         name: "trace:criteria_coverage",
         ok: !traceHasSignal || trace.orphanedCriteria.length === 0,
@@ -802,6 +828,16 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? `stage "${gateEvidence.stage}" gate evidence is consistent (required=${gateEvidence.requiredCount}, passed=${gateEvidence.passedCount}, blocked=${gateEvidence.blockedCount})`
             : gateEvidence.issues.join(" ")
     });
+    const completedClosure = verifyCompletedStagesGateClosure(flowState);
+    checks.push({
+        name: "gates:closure:completed_stages",
+        ok: completedClosure.ok,
+        details: completedClosure.ok
+            ? flowState.completedStages.length === 0
+                ? "no completed stages yet"
+                : `all ${flowState.completedStages.length} completed stages have every required gate passed`
+            : completedClosure.issues.join(" ")
+    });
     // Self-improvement block in stage skills
     for (const stage of COMMAND_FILE_ORDER) {
         const skillPath = path.join(projectRoot, RUNTIME_ROOT, "skills", stageSkillFolder(stage), "SKILL.md");

package/dist/gate-evidence.d.ts

@@ -7,8 +7,22 @@ export interface GateEvidenceCheckResult {
     requiredCount: number;
     passedCount: number;
     blockedCount: number;
+    /** True only when every required gate for the stage is in `passed` and none are `blocked`. */
+    complete: boolean;
+    /** Required gate ids that are neither passed nor blocked. */
+    missingRequired: string[];
+}
+export interface CompletedStagesClosureResult {
+    ok: boolean;
+    issues: string[];
+    openStages: Array<{
+        stage: FlowStage;
+        missingRequired: string[];
+        blocked: string[];
+    }>;
 }
 export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState): Promise<GateEvidenceCheckResult>;
+export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
 export interface GateReconciliationResult {
     stage: FlowStage;
     changed: boolean;

package/dist/gate-evidence.js

@@ -1,6 +1,29 @@
-import { lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { checkReviewVerdictConsistency, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
+import { exists } from "./fs-utils.js";
 import { readFlowState, writeFlowState } from "./runs.js";
+async function currentStageArtifactExists(projectRoot, stage) {
+    const artifactFile = stageSchema(stage).artifactFile;
+    const candidates = [
+        path.join(projectRoot, RUNTIME_ROOT, "artifacts", artifactFile),
+        path.join(projectRoot, artifactFile)
+    ];
+    for (const candidate of candidates) {
+        if (await exists(candidate))
+            return true;
+    }
+    // Artifact-linter also accepts the file under current working directory fallback; stat once more.
+    try {
+        await fs.access(path.join(projectRoot, artifactFile));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function unique(values) {
     return [...new Set(values)];
 }
@@ -44,7 +67,8 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             issues.push(`blocked gate "${gateId}" is not defined for stage "${stage}".`);
         }
     }
-    const shouldValidateArtifact = catalog.passed.length > 0 || flowState.completedStages.includes(stage);
+    const artifactPresent = await currentStageArtifactExists(projectRoot, stage);
+    const shouldValidateArtifact = artifactPresent || catalog.passed.length > 0 || flowState.completedStages.includes(stage);
     if (shouldValidateArtifact) {
         const lint = await lintArtifact(projectRoot, stage);
         if (!lint.passed) {
@@ -60,6 +84,21 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             if (!reviewArmy.valid) {
                 issues.push(`review-army validation failed: ${reviewArmy.errors.join("; ")}`);
             }
+            const verdictConsistency = await checkReviewVerdictConsistency(projectRoot);
+            if (!verdictConsistency.ok) {
+                issues.push(`review verdict inconsistency: ${verdictConsistency.errors.join("; ")}`);
+            }
+        }
+    }
+    const passedSet = new Set(catalog.passed);
+    const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
+    const complete = missingRequired.length === 0 && catalog.blocked.length === 0;
+    if (flowState.completedStages.includes(stage) && !complete) {
+        if (missingRequired.length > 0) {
+            issues.push(`stage "${stage}" is marked completed but required gates are not passed: ${missingRequired.join(", ")}.`);
+        }
+        if (catalog.blocked.length > 0) {
+            issues.push(`stage "${stage}" is marked completed but has blocked gates: ${catalog.blocked.join(", ")}.`);
         }
     }
     return {
@@ -68,9 +107,32 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         issues,
         requiredCount: required.length,
         passedCount: catalog.passed.length,
-        blockedCount: catalog.blocked.length
+        blockedCount: catalog.blocked.length,
+        complete,
+        missingRequired
     };
 }
+export function verifyCompletedStagesGateClosure(flowState) {
+    const issues = [];
+    const openStages = [];
+    for (const stage of flowState.completedStages) {
+        const schema = stageSchema(stage);
+        const catalog = flowState.stageGateCatalog[stage];
+        const required = schema.requiredGates.map((gate) => gate.id);
+        const passedSet = new Set(catalog.passed);
+        const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
+        if (missingRequired.length > 0 || catalog.blocked.length > 0) {
+            openStages.push({ stage, missingRequired, blocked: [...catalog.blocked] });
+            if (missingRequired.length > 0) {
+                issues.push(`completed stage "${stage}" has unpassed required gates: ${missingRequired.join(", ")}.`);
+            }
+            if (catalog.blocked.length > 0) {
+                issues.push(`completed stage "${stage}" still has blocked gates: ${catalog.blocked.join(", ")}.`);
+            }
+        }
+    }
+    return { ok: openStages.length === 0, issues, openStages };
+}
 export function reconcileCurrentStageGateCatalog(flowState) {
     const stage = flowState.currentStage;
     const required = stageSchema(stage).requiredGates.map((gate) => gate.id);

package/dist/runs.d.ts

@@ -1,4 +1,17 @@
 import { type FlowState } from "./flow-state.js";
+import type { FlowStage } from "./types.js";
+export declare class InvalidStageTransitionError extends Error {
+    readonly from: FlowStage;
+    readonly to: FlowStage;
+    constructor(from: FlowStage, to: FlowStage, message: string);
+}
+export interface WriteFlowStateOptions {
+    /**
+     * When true, skip prior-state validation. Used for run archival, initial
+     * bootstrap, or explicit recovery; never set from normal stage handlers.
+     */
+    allowReset?: boolean;
+}
 export interface CclawRunMeta {
     id: string;
     title: string;
@@ -10,12 +23,28 @@ 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 writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
 export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
 export declare function archiveRun(projectRoot: string, featureName?: string): Promise<ArchiveRunResult>;

package/dist/runs.js

@@ -1,12 +1,45 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
-import { createInitialFlowState } from "./flow-state.js";
+import { canTransition, createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+export class InvalidStageTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to, message) {
+        super(message);
+        this.from = from;
+        this.to = to;
+        this.name = "InvalidStageTransitionError";
+    }
+}
+function validateFlowTransition(prev, next) {
+    if (prev.activeRunId !== next.activeRunId) {
+        // New run — only reset paths may change the runId, but those set allowReset.
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change activeRunId from "${prev.activeRunId}" to "${next.activeRunId}" without allowReset.`);
+    }
+    for (const completed of prev.completedStages) {
+        if (!next.completedStages.includes(completed)) {
+            throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage "${completed}" was previously completed but is missing from the new state.`);
+        }
+    }
+    if (prev.currentStage === next.currentStage) {
+        return;
+    }
+    if (!canTransition(prev.currentStage, next.currentStage)) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `no transition rule allows "${prev.currentStage}" -> "${next.currentStage}". Use /cc-next to advance stages or archive the run to reset.`);
+    }
+}
 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 +52,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,23 +217,89 @@ 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) {
+export async function writeFlowState(projectRoot, state, options = {}) {
     await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
+        const statePath = flowStatePath(projectRoot);
+        if (!options.allowReset && (await exists(statePath))) {
+            try {
+                const raw = await fs.readFile(statePath, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    const prev = coerceFlowState(parsed);
+                    validateFlowTransition(prev, state);
+                }
+            }
+            catch (err) {
+                if (err instanceof InvalidStageTransitionError) {
+                    throw err;
+                }
+                // A corrupt prior file is surfaced by readFlowState elsewhere; don't
+                // block a legitimate write attempt on parse errors here.
+            }
+        }
         const safe = coerceFlowState({ ...state });
-        await writeFileSafe(flowStatePath(projectRoot), `${JSON.stringify(safe, null, 2)}\n`);
+        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`);
     });
 }
 export async function ensureRunSystem(projectRoot, _options = {}) {
@@ -169,7 +308,7 @@ export async function ensureRunSystem(projectRoot, _options = {}) {
     const statePath = flowStatePath(projectRoot);
     const state = await readFlowState(projectRoot);
     if (!(await exists(statePath))) {
-        await writeFlowState(projectRoot, state);
+        await writeFlowState(projectRoot, state, { allowReset: true });
     }
     return state;
 }
@@ -214,17 +353,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);
+    await writeFlowState(projectRoot, resetState, { allowReset: true });
     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.17",
   "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"
   }