cclaw-cli 0.47.0 → 0.48.1

package/dist/internal/detect-public-api-changes.js

@@ -0,0 +1,45 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const PUBLIC_SURFACE_PATH_PATTERNS = [
+    /(^|\/)(cli|types?|config)\.[cm]?[jt]s$/iu,
+    /(^|\/)(openapi|swagger|schema)(\/|[-_.])/iu,
+    /(^|\/)(api|commands?|flags?)(\/|[-_.])/iu,
+    /(^|\/)(package|tsconfig)\.json$/iu
+];
+async function resolveDiffBase(projectRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD~1"], {
+            cwd: projectRoot
+        });
+        const base = stdout.trim();
+        return base.length > 0 ? base : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function detectPublicApiChanges(projectRoot) {
+    const base = await resolveDiffBase(projectRoot);
+    if (!base) {
+        return { triggered: false, changedFiles: [] };
+    }
+    try {
+        const range = `${base}..HEAD`;
+        const { stdout } = await execFileAsync("git", ["diff", "--name-only", range], {
+            cwd: projectRoot
+        });
+        const changedFiles = stdout
+            .split(/\r?\n/gu)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .filter((filePath) => PUBLIC_SURFACE_PATH_PATTERNS.some((pattern) => pattern.test(filePath)));
+        return {
+            triggered: changedFiles.length > 0,
+            changedFiles
+        };
+    }
+    catch {
+        return { triggered: false, changedFiles: [] };
+    }
+}

package/dist/knowledge-store.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { withDirectoryLock } from "./fs-utils.js";
+import { stripBom, withDirectoryLock } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 const KNOWLEDGE_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
 const KNOWLEDGE_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
@@ -179,7 +179,7 @@ export function materializeKnowledgeEntry(seed, defaults = {}) {
 async function readExistingKnowledgeKeys(filePath) {
     const keys = new Set();
     try {
-        const raw = await fs.readFile(filePath, "utf8");
+        const raw = stripBom(await fs.readFile(filePath, "utf8"));
         const lines = raw.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0);
         for (const line of lines) {
             try {

package/dist/policy.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { RUNTIME_ROOT } from "./constants.js";
+import { FLOW_STAGES } from "./types.js";
 import { stageSchema, stagePolicyNeedles } from "./content/stage-schema.js";
 import { stageSkillFolder } from "./content/skills.js";
 import { exists } from "./fs-utils.js";
@@ -10,7 +11,7 @@ export async function policyChecks(projectRoot, options = {}) {
     const checks = [];
     const rules = [...POLICY_RULES];
     const activeHarnesses = new Set(options.harnesses && options.harnesses.length > 0 ? options.harnesses : ALL_HARNESSES);
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const folder = stageSkillFolder(stage);
         const schema = stageSchema(stage);
         const commandFile = `${RUNTIME_ROOT}/commands/${stage}.md`;

package/dist/retro-gate.js

@@ -1,13 +1,20 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { exists } from "./fs-utils.js";
+import { exists, stripBom } from "./fs-utils.js";
 function activeArtifactsPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "artifacts");
 }
 function retroArtifactPath(projectRoot) {
     return path.join(activeArtifactsPath(projectRoot), "09-retro.md");
 }
+// Fallback window for compound-entry scanning when `retroDraftedAt` /
+// `retroAcceptedAt` are not set (legacy runs or imports): use the retro
+// artifact's mtime ± 7 days. 24h was too narrow for long-running retros
+// that are edited over several days or runs imported from another
+// machine with slightly different clocks; 7 days is still tight enough
+// that entries from an unrelated future run are excluded.
+const RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
 function parseIsoTimestamp(value) {
     if (!value || value.trim().length === 0)
         return null;
@@ -35,13 +42,29 @@ export async function evaluateRetroGate(projectRoot, state) {
         }
     }
     let compoundEntries = state.retro.compoundEntries;
-    const windowStartMs = parseIsoTimestamp(state.closeout.retroDraftedAt);
-    const windowEndMs = parseIsoTimestamp(state.closeout.retroAcceptedAt) ?? parseIsoTimestamp(state.retro.completedAt);
+    let windowStartMs = parseIsoTimestamp(state.closeout.retroDraftedAt);
+    let windowEndMs = parseIsoTimestamp(state.closeout.retroAcceptedAt) ?? parseIsoTimestamp(state.retro.completedAt);
+    if (compoundEntries <= 0 &&
+        hasRetroArtifact &&
+        windowStartMs === null &&
+        windowEndMs === null) {
+        try {
+            const stats = await fs.stat(artifactFile);
+            const anchor = stats.mtimeMs;
+            if (Number.isFinite(anchor) && anchor > 0) {
+                windowStartMs = anchor - RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS;
+                windowEndMs = anchor + RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS;
+            }
+        }
+        catch {
+            // fallback scan remains disabled when mtime cannot be read
+        }
+    }
     const shouldFallbackScan = compoundEntries <= 0 && (windowStartMs !== null || windowEndMs !== null);
     const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
     if (shouldFallbackScan && (await exists(knowledgeFile))) {
         try {
-            const raw = await fs.readFile(knowledgeFile, "utf8");
+            const raw = stripBom(await fs.readFile(knowledgeFile, "utf8"));
             compoundEntries = 0;
             for (const line of raw.split(/\r?\n/)) {
                 const trimmed = line.trim();
@@ -73,17 +96,20 @@ export async function evaluateRetroGate(projectRoot, state) {
             compoundEntries = 0;
         }
     }
-    // A retro is considered complete when either:
-    //   - at least one compound learning was promoted during the retro window, or
-    //   - the operator explicitly skipped retro or compound (`retroSkipped` /
-    //     `compoundSkipped` recorded in the closeout substate) after reviewing
-    //     the draft. Previously the gate required `compoundEntries > 0`
-    //     unconditionally, which dead-locked ship closeout whenever the retro
-    //     yielded no new patterns worth promoting.
-    const explicitSkip = Boolean(state.closeout.retroSkipped || state.closeout.compoundSkipped);
-    const completed = required
-        ? hasRetroArtifact && (compoundEntries > 0 || explicitSkip)
-        : true;
+    // A retro is considered complete when any of:
+    //   - the retro artifact exists AND (at least one compound learning was
+    //     promoted during the retro window OR compound was explicitly skipped
+    //     after reviewing the draft), or
+    //   - the operator explicitly skipped the retro step itself
+    //     (`retroSkipped === true` with a reason). `retroSkipped` is an
+    //     operator-level override of the artifact requirement, so it must
+    //     bypass `hasRetroArtifact` — otherwise a run that legitimately had
+    //     nothing worth retro-ing dead-locks at closeout waiting for a
+    //     file that will never exist.
+    const retroSkipped = state.closeout.retroSkipped === true;
+    const compoundSkipped = state.closeout.compoundSkipped === true;
+    const artifactPathComplete = hasRetroArtifact && (compoundEntries > 0 || compoundSkipped);
+    const completed = required ? retroSkipped || artifactPathComplete : true;
     return {
         required,
         completed,

package/dist/run-archive.js

@@ -204,40 +204,70 @@ export async function archiveRun(projectRoot, featureName, options = {}) {
         compoundEntries: retroGate.compoundEntries
     };
     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, { allowReset: true });
-    await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
+    // Drop an `.archive-in-progress` sentinel immediately so that a crash
+    // between the artifact rename and the final manifest write leaves a
+    // recoverable marker (doctor surfaces these; re-running archive on an
+    // orphan attempts to complete or roll back). The sentinel is removed
+    // only after the manifest lands successfully.
+    const sentinelPath = path.join(archivePath, ".archive-in-progress");
     const archivedAt = new Date().toISOString();
-    const manifest = {
-        version: 1,
-        archiveId,
-        archivedAt,
-        featureName: feature,
-        activeFeature,
-        sourceRunId: sourceState.activeRunId,
-        sourceCurrentStage: sourceState.currentStage,
-        sourceCompletedStages: sourceState.completedStages,
-        snapshottedStateFiles,
-        retro: retroSummary
-    };
-    await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-    const knowledgeStats = await readKnowledgeStats(projectRoot);
-    await syncActiveFeatureSnapshot(projectRoot);
-    return {
-        archiveId,
-        archivePath,
-        archivedAt,
-        featureName: feature,
-        activeFeature,
-        resetState,
-        snapshottedStateFiles,
-        knowledge: knowledgeStats,
-        retro: retroSummary
-    };
+    await writeFileSafe(sentinelPath, `${JSON.stringify({ archiveId, startedAt: archivedAt, sourceRunId: sourceState.activeRunId }, null, 2)}\n`);
+    let artifactsMoved = false;
+    try {
+        await fs.rename(artifactsDir, archiveArtifactsPath);
+        artifactsMoved = true;
+        await ensureDir(artifactsDir);
+        const archiveStatePath = path.join(archivePath, "state");
+        const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
+        const resetState = createInitialFlowState();
+        await writeFlowState(projectRoot, resetState, { allowReset: true });
+        await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
+        const manifest = {
+            version: 1,
+            archiveId,
+            archivedAt,
+            featureName: feature,
+            activeFeature,
+            sourceRunId: sourceState.activeRunId,
+            sourceCurrentStage: sourceState.currentStage,
+            sourceCompletedStages: sourceState.completedStages,
+            snapshottedStateFiles,
+            retro: retroSummary
+        };
+        await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        // Manifest landed — sentinel is no longer needed.
+        await fs.unlink(sentinelPath).catch(() => undefined);
+        const knowledgeStats = await readKnowledgeStats(projectRoot);
+        await syncActiveFeatureSnapshot(projectRoot);
+        return {
+            archiveId,
+            archivePath,
+            archivedAt,
+            featureName: feature,
+            activeFeature,
+            resetState,
+            snapshottedStateFiles,
+            knowledge: knowledgeStats,
+            retro: retroSummary
+        };
+    }
+    catch (err) {
+        // Best-effort rollback: if artifacts were moved but the subsequent
+        // steps failed, put artifacts back so the user is not left without
+        // a working run. The sentinel is intentionally left behind for
+        // inspection; doctor surfaces it.
+        if (artifactsMoved) {
+            try {
+                await fs.rm(artifactsDir, { recursive: true, force: true });
+                await fs.rename(archiveArtifactsPath, artifactsDir);
+            }
+            catch {
+                // Rollback failed — sentinel + orphaned archive dir will be
+                // surfaced by doctor and can be reconciled manually.
+            }
+        }
+        throw err;
+    }
 }
 const KNOWLEDGE_SOFT_THRESHOLD = 50;
 async function readKnowledgeStats(projectRoot) {

package/dist/run-persistence.js

@@ -1,9 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { RUNTIME_ROOT } from "./constants.js";
 import { canTransition, createInitialCloseoutState, createInitialFlowState, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
 import { ensureFeatureSystem, syncActiveFeatureSnapshot } from "./feature-system.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+import { FLOW_STAGES } from "./types.js";
 export class InvalidStageTransitionError extends Error {
     from;
     to;
@@ -17,12 +18,19 @@ export class InvalidStageTransitionError extends Error {
 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 FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
+const FLOW_STAGE_SET = new Set(FLOW_STAGES);
 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.`);
     }
+    // Track is immutable within a single run: stage schemas, gate sets, and
+    // cross-stage reads all branch on track. Silently flipping the track
+    // mid-run would let completed stages satisfy one gate tier and the
+    // current stage re-read the catalog under a different tier.
+    if (prev.track !== next.track) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change track from "${prev.track}" to "${next.track}" mid-run (activeRunId="${prev.activeRunId}"). Archive the run and start a new one to switch tracks.`);
+    }
     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.`);
@@ -85,7 +93,7 @@ function sanitizeGuardEvidence(value) {
 function sanitizeStageGateCatalog(value, fallback) {
     const uniqueStrings = (items) => [...new Set(items)];
     const next = {};
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const base = fallback[stage];
         next[stage] = {
             required: [...base.required],
@@ -100,7 +108,7 @@ function sanitizeStageGateCatalog(value, fallback) {
         return next;
     }
     const rawCatalog = value;
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const rawStage = rawCatalog[stage];
         if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
             continue;

package/dist/tdd-cycle.js

@@ -1,6 +1,10 @@
 export function parseTddCycleLog(text) {
     const out = [];
-    for (const raw of text.split(/\r?\n/)) {
+    // Strip a leading UTF-8 BOM on the whole blob so the first line parses
+    // cleanly; `trim()` handles BOM on subsequent lines through the same
+    // codepath (empty/whitespace-only lines are skipped).
+    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    for (const raw of normalized.split(/\r?\n/)) {
         const line = raw.trim();
         if (!line)
             continue;
@@ -100,6 +104,7 @@ export function validateTddCycleOrder(entries, options = {}) {
             }
             if (state !== "green_done") {
                 issues.push(`slice ${slice}: refactor logged before green`);
+                continue;
             }
             state = "need_red";
         }

package/dist/types.d.ts

@@ -109,7 +109,7 @@ export interface TddPathConfig {
 export interface CompoundConfig {
     recurrenceThreshold?: number;
 }
-export interface VibyConfig {
+export interface CclawConfig {
     version: string;
     flowVersion: string;
     harnesses: HarnessId[];
@@ -141,6 +141,7 @@ export interface VibyConfig {
     /**
      * Legacy alias for test-side path detection in workflow-guard.
      * Prefer `tdd.testPathPatterns` in new configs.
+     * @deprecated Use `tdd.testPathPatterns` instead.
      */
     tddTestGlobs?: string[];
     /** Path-pattern routing for TDD test/production write classification. */
@@ -173,6 +174,10 @@ export interface VibyConfig {
      */
     sliceReview?: SliceReviewConfig;
 }
+/**
+ * @deprecated Use `CclawConfig` instead.
+ */
+export type VibyConfig = CclawConfig;
 export interface TransitionRule {
     from: FlowStage;
     to: FlowStage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.47.0",
+  "version": "0.48.1",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run",
     "smoke:runtime": "npm run build && node scripts/smoke-init.mjs",
     "lint:hooks": "npm run build && node scripts/lint-generated-hooks.mjs",
     "build:harness-docs": "npm run build && node scripts/build-harness-docs.mjs",
@@ -44,6 +45,8 @@
     "yaml": "^2.8.1"
   },
   "devDependencies": {
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^24.7.2",
     "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.9.3",