cclaw-cli 0.48.0 → 0.48.2

package/dist/doctor.js

@@ -3,18 +3,18 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
-import { REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
+import { REQUIRED_DIRS, RUNTIME_ROOT, UTILITY_COMMANDS } from "./constants.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
 import { detectAdvancedKeys, readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames, harnessShimSkillNames } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
-import { readFlowState } from "./runs.js";
-import { skippedStagesForTrack } from "./flow-state.js";
+import { CorruptFlowStateError, readFlowState } from "./runs.js";
+import { createInitialFlowState, skippedStagesForTrack } from "./flow-state.js";
 import { FLOW_STAGES, TRACK_STAGES } from "./types.js";
 import { checkMandatoryDelegations } from "./delegation.js";
-import { ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
+import { activeFeatureMetaPath, ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
@@ -190,6 +190,25 @@ async function readHookDocument(filePath) {
         return null;
     }
 }
+async function readJsonObjectStatus(filePath) {
+    if (!(await exists(filePath))) {
+        return { exists: false, ok: false, error: "file is missing" };
+    }
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { exists: true, ok: false, error: "JSON root must be an object" };
+        }
+        return { exists: true, ok: true };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
 function normalizeOpenCodePluginEntry(entry) {
     if (typeof entry === "string" && entry.trim().length > 0)
         return entry.trim();
@@ -212,12 +231,16 @@ async function opencodeRegistrationCheck(projectRoot) {
         path.join(projectRoot, ".opencode/opencode.json"),
         path.join(projectRoot, ".opencode/opencode.jsonc")
     ];
+    const mismatches = [];
+    let foundAnyConfig = false;
     for (const configPath of candidates) {
         if (!(await exists(configPath))) {
             continue;
         }
+        foundAnyConfig = true;
         const parsed = await readHookDocument(configPath);
         if (!parsed) {
+            mismatches.push(`${path.relative(projectRoot, configPath)} is unreadable or invalid JSON`);
             continue;
         }
         const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : [];
@@ -225,7 +248,10 @@ async function opencodeRegistrationCheck(projectRoot) {
         if (registered) {
             return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${expected}` };
         }
-        return { ok: false, details: `${path.relative(projectRoot, configPath)} missing plugin ${expected}` };
+        mismatches.push(`${path.relative(projectRoot, configPath)} missing plugin ${expected}`);
+    }
+    if (foundAnyConfig) {
+        return { ok: false, details: mismatches.join(" | ") };
     }
     return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
 }
@@ -244,6 +270,12 @@ async function opencodePluginRuntimeShapeCheck(projectRoot) {
             };
         }
         const plugin = imported.default({ directory: projectRoot });
+        if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) {
+            return {
+                ok: false,
+                details: `${path.relative(projectRoot, pluginPath)} factory must return a plugin object`
+            };
+        }
         const requiredHandlers = [
             "event",
             "tool.execute.before",
@@ -257,7 +289,6 @@ async function opencodePluginRuntimeShapeCheck(projectRoot) {
                 details: `${path.relative(projectRoot, pluginPath)} missing runtime handlers: ${missing.join(", ")}`
             };
         }
-        await plugin.event({ event: { type: "session.updated", data: {} } });
         return {
             ok: true,
             details: `${path.relative(projectRoot, pluginPath)} exports compatible runtime handler shape`
@@ -547,8 +578,8 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: agentsBlockOk,
         details: `${agentsFile} must contain the managed cclaw marker block with routing, verification, and minimal detail pointer`
     });
-    // Utility commands
-    for (const cmd of ["learn", "next", "ideate", "status", "tree", "diff", "feature", "tdd-log", "retro", "compound", "rewind"]) {
+    // Utility commands — keep in sync with UTILITY_COMMANDS (src/constants.ts)
+    for (const cmd of UTILITY_COMMANDS) {
         const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${cmd}.md`);
         checks.push({
             name: `utility_command:${cmd}`,
@@ -815,7 +846,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             });
             checks.push({
                 name: `shim:codex:${skillName}:frontmatter`,
-                ok,
+                ok: frontmatterOk,
                 details: frontmatterOk
                     ? `${skillPath} has \`name: ${skillName}\` frontmatter`
                     : ok
@@ -1289,10 +1320,28 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: modePath
         });
     }
-    await ensureFeatureSystem(projectRoot);
-    const activeFeature = await readActiveFeature(projectRoot);
-    let flowState = await readFlowState(projectRoot);
-    if (options.reconcileCurrentStageGates === true) {
+    await ensureFeatureSystem(projectRoot, { repair: false });
+    const activeFeature = await readActiveFeature(projectRoot, { repair: false });
+    let flowState = createInitialFlowState();
+    let flowStateCorruptError = null;
+    try {
+        flowState = await readFlowState(projectRoot, { repairFeatureSystem: false });
+    }
+    catch (error) {
+        if (error instanceof CorruptFlowStateError) {
+            flowStateCorruptError = error;
+            checks.push({
+                name: "flow_state:readable",
+                ok: false,
+                severity: "error",
+                details: error.message
+            });
+        }
+        else {
+            throw error;
+        }
+    }
+    if (options.reconcileCurrentStageGates === true && !flowStateCorruptError) {
         const reconciliation = await reconcileAndWriteCurrentStageGateCatalog(projectRoot);
         if (reconciliation.wrote) {
             flowState = {
@@ -1311,6 +1360,13 @@ export async function doctorChecks(projectRoot, options = {}) {
                 : `no gate reconciliation changes needed for stage "${reconciliation.stage}"`
         });
     }
+    else if (options.reconcileCurrentStageGates === true && flowStateCorruptError) {
+        checks.push({
+            name: "gates:reconcile:writeback",
+            ok: false,
+            details: "skipped gate reconciliation because flow-state.json is corrupt"
+        });
+    }
     const activeRunId = typeof flowState.activeRunId === "string" ? flowState.activeRunId.trim() : "";
     checks.push({
         name: "flow_state:active_run_id",
@@ -1318,6 +1374,15 @@ export async function doctorChecks(projectRoot, options = {}) {
         details: `${RUNTIME_ROOT}/state/flow-state.json must include activeRunId`
     });
     const reconciliationNotices = await readReconciliationNotices(projectRoot);
+    checks.push({
+        name: "state:reconciliation_notices_parse",
+        ok: reconciliationNotices.parseOk && reconciliationNotices.schemaOk,
+        details: !reconciliationNotices.parseOk
+            ? `unable to parse ${RECONCILIATION_NOTICES_REL_PATH}; reset with \`cclaw sync\` or repair JSON by hand`
+            : !reconciliationNotices.schemaOk
+                ? `${RECONCILIATION_NOTICES_REL_PATH} schemaVersion mismatch; expected ${reconciliationNotices.schemaVersion}`
+                : `${RECONCILIATION_NOTICES_REL_PATH} parsed successfully`
+    });
     const noticeBuckets = classifyReconciliationNotices(flowState, reconciliationNotices.notices);
     const formatNoticeList = (items) => items
         .slice(0, 8)
@@ -1425,22 +1490,38 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no TODO/TBD/FIXME placeholder markers found in active artifacts"
             : `warning: placeholder markers detected in active artifacts (${artifactPlaceholderHits.join(", ")}). Clear before marking completion.`
     });
-    const features = await listFeatures(projectRoot);
-    const worktreeRegistry = await readFeatureWorktreeRegistry(projectRoot);
+    const activeMetaStatus = await readJsonObjectStatus(activeFeatureMetaPath(projectRoot));
+    const worktreeRegistryStatus = await readJsonObjectStatus(worktreeRegistryPath(projectRoot));
+    const features = await listFeatures(projectRoot, { repair: false });
+    const worktreeRegistry = await readFeatureWorktreeRegistry(projectRoot, { repair: false });
     const activeFeatureEntry = worktreeRegistry.entries.find((entry) => entry.featureId === activeFeature);
     const activeFeatureWorkspacePath = activeFeatureEntry
         ? resolveFeatureWorkspacePath(projectRoot, activeFeatureEntry)
         : "";
     checks.push({
         name: "state:active_feature_meta",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "active-feature.json")),
+        ok: activeMetaStatus.exists,
         details: `${RUNTIME_ROOT}/state/active-feature.json must exist`
     });
+    checks.push({
+        name: "state:active_feature_meta_valid_json",
+        ok: activeMetaStatus.ok,
+        details: activeMetaStatus.ok
+            ? `${RUNTIME_ROOT}/state/active-feature.json parsed successfully`
+            : `${RUNTIME_ROOT}/state/active-feature.json is invalid: ${activeMetaStatus.error ?? "unknown error"}`
+    });
     checks.push({
         name: "state:worktree_registry_exists",
-        ok: await exists(worktreeRegistryPath(projectRoot)),
+        ok: worktreeRegistryStatus.exists,
         details: `${RUNTIME_ROOT}/state/worktrees.json must exist and track feature->worktree mapping`
     });
+    checks.push({
+        name: "state:worktree_registry_valid_json",
+        ok: worktreeRegistryStatus.ok,
+        details: worktreeRegistryStatus.ok
+            ? `${RUNTIME_ROOT}/state/worktrees.json parsed successfully`
+            : `${RUNTIME_ROOT}/state/worktrees.json is invalid: ${worktreeRegistryStatus.error ?? "unknown error"}`
+    });
     checks.push({
         name: "state:active_feature_exists",
         ok: features.includes(activeFeature),
@@ -1590,7 +1671,9 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs")),
         details: `${RUNTIME_ROOT}/runs must exist for archived feature snapshots`
     });
-    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
+        repairFeatureSystem: false
+    });
     const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
         ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
         : "";

package/dist/feature-system.d.ts

@@ -19,16 +19,23 @@ export interface CreateFeatureOptions {
     cloneActive?: boolean;
     switchTo?: boolean;
 }
+export interface FeatureSystemAccessOptions {
+    /**
+     * When false, read metadata without auto-repair writes. Useful for pure
+     * diagnostics (doctor) that should not mutate state as a side effect.
+     */
+    repair?: boolean;
+}
 export declare function activeFeatureMetaPath(projectRoot: string): string;
 export declare function worktreeRegistryPath(projectRoot: string): string;
 export declare function featureRootPath(projectRoot: string, featureId: string): string;
 export declare function featureArtifactsPath(projectRoot: string, featureId: string): string;
 export declare function featureStatePath(projectRoot: string, featureId: string): string;
 export declare function resolveFeatureWorkspacePath(projectRoot: string, entry: FeatureWorkspaceEntry): string;
-export declare function ensureFeatureSystem(projectRoot: string): Promise<ActiveFeatureMeta>;
-export declare function readFeatureWorktreeRegistry(projectRoot: string): Promise<FeatureWorktreeRegistry>;
-export declare function readActiveFeature(projectRoot: string): Promise<string>;
-export declare function listFeatures(projectRoot: string): Promise<string[]>;
+export declare function ensureFeatureSystem(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<ActiveFeatureMeta>;
+export declare function readFeatureWorktreeRegistry(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<FeatureWorktreeRegistry>;
+export declare function readActiveFeature(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<string>;
+export declare function listFeatures(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<string[]>;
 export declare function syncActiveFeatureSnapshot(projectRoot: string): Promise<void>;
 export declare function switchActiveFeature(projectRoot: string, featureId: string): Promise<ActiveFeatureMeta>;
 export declare function createFeature(projectRoot: string, rawFeatureId: string, options?: CreateFeatureOptions): Promise<string>;

package/dist/feature-system.js

@@ -278,20 +278,64 @@ async function ensureRegistryState(projectRoot) {
     await writeActiveFeatureMeta(projectRoot, activeMeta);
     return { registry, activeMeta };
 }
-export async function ensureFeatureSystem(projectRoot) {
-    const { activeMeta } = await ensureRegistryState(projectRoot);
+async function readRegistryStateReadonly(projectRoot) {
+    const currentRegistry = await readRegistry(projectRoot);
+    const entries = [...currentRegistry.entries];
+    const gitRepo = await isGitRepository(projectRoot);
+    const source = gitRepo ? "git-worktree" : "workspace";
+    const branch = gitRepo ? await currentBranch(projectRoot) : "workspace/default";
+    if (!entries.some((entry) => entry.featureId === DEFAULT_FEATURE_ID)) {
+        entries.push(buildDefaultEntry(source, branch));
+    }
+    const legacyFeatureIds = await listLegacySnapshotIds(projectRoot);
+    for (const legacyId of legacyFeatureIds) {
+        if (entries.some((entry) => entry.featureId === legacyId)) {
+            continue;
+        }
+        entries.push({
+            featureId: legacyId,
+            branch: `legacy/${legacyId}`,
+            path: `${LEGACY_FEATURES_DIR_REL_PATH}/${legacyId}`,
+            source: "legacy-snapshot",
+            createdAt: new Date().toISOString()
+        });
+    }
+    const registry = {
+        schemaVersion: WORKTREE_REGISTRY_SCHEMA_VERSION,
+        updatedAt: currentRegistry.updatedAt,
+        entries: dedupeEntries(entries)
+    };
+    const active = await readActiveFeatureMetaInternal(projectRoot);
+    return {
+        registry,
+        activeMeta: {
+            activeFeature: registryHasFeature(registry, active.activeFeature)
+                ? active.activeFeature
+                : DEFAULT_FEATURE_ID,
+            updatedAt: active.updatedAt
+        }
+    };
+}
+async function resolveFeatureSystemState(projectRoot, options = {}) {
+    if (options.repair === false) {
+        return readRegistryStateReadonly(projectRoot);
+    }
+    return ensureRegistryState(projectRoot);
+}
+export async function ensureFeatureSystem(projectRoot, options = {}) {
+    const { activeMeta } = await resolveFeatureSystemState(projectRoot, options);
     return activeMeta;
 }
-export async function readFeatureWorktreeRegistry(projectRoot) {
-    const { registry } = await ensureRegistryState(projectRoot);
+export async function readFeatureWorktreeRegistry(projectRoot, options = {}) {
+    const { registry } = await resolveFeatureSystemState(projectRoot, options);
     return registry;
 }
-export async function readActiveFeature(projectRoot) {
-    const meta = await ensureFeatureSystem(projectRoot);
+export async function readActiveFeature(projectRoot, options = {}) {
+    const meta = await ensureFeatureSystem(projectRoot, options);
     return normalizedFeatureId(meta.activeFeature);
 }
-export async function listFeatures(projectRoot) {
-    const registry = await readFeatureWorktreeRegistry(projectRoot);
+export async function listFeatures(projectRoot, options = {}) {
+    const registry = await readFeatureWorktreeRegistry(projectRoot, options);
     return registry.entries.map((entry) => entry.featureId).sort((a, b) => a.localeCompare(b));
 }
 export async function syncActiveFeatureSnapshot(projectRoot) {

package/dist/flow-state.d.ts

@@ -92,8 +92,10 @@ export declare function isFlowTrack(value: unknown): value is FlowTrack;
 export declare function trackStages(track: FlowTrack): FlowStage[];
 export declare function skippedStagesForTrack(track: FlowTrack): FlowStage[];
 export declare function firstStageForTrack(track: FlowTrack): FlowStage;
+export declare function createRunId(date?: Date): string;
 export declare function createInitialFlowState(activeRunIdOrOptions?: string | InitialFlowStateOptions, maybeTrack?: FlowTrack): FlowState;
 export declare function canTransition(from: FlowStage, to: FlowStage): boolean;
-export declare function getTransitionGuards(from: FlowStage, to: FlowStage): string[];
+export declare function getAvailableTransitions(from: FlowStage, track?: FlowTrack): TransitionRule[];
+export declare function getTransitionGuards(from: FlowStage, to: FlowStage, track?: FlowTrack): string[];
 export declare function nextStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;
 export declare function previousStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;

package/dist/flow-state.js

@@ -58,11 +58,14 @@ export function firstStageForTrack(track) {
     const stages = TRACK_STAGES[track];
     return stages[0] ?? "brainstorm";
 }
-export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTrack) {
+export function createRunId(date = new Date()) {
+    return `run-${date.getTime().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function createInitialFlowState(activeRunIdOrOptions = {}, maybeTrack) {
     const options = typeof activeRunIdOrOptions === "string"
         ? { activeRunId: activeRunIdOrOptions, track: maybeTrack }
         : activeRunIdOrOptions;
-    const activeRunId = options.activeRunId ?? "active";
+    const activeRunId = options.activeRunId ?? createRunId();
     const track = options.track ?? "standard";
     const skippedStages = skippedStagesForTrack(track);
     const stageGateCatalog = {};
@@ -97,7 +100,35 @@ export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTra
 export function canTransition(from, to) {
     return TRANSITION_RULES.some((rule) => rule.from === from && rule.to === to);
 }
-export function getTransitionGuards(from, to) {
+export function getAvailableTransitions(from, track = "standard") {
+    const natural = nextStage(from, track);
+    const fromRules = TRANSITION_RULES.filter((rule) => rule.from === from);
+    if (!natural) {
+        return fromRules;
+    }
+    return fromRules.sort((a, b) => {
+        if (a.to === natural && b.to !== natural)
+            return -1;
+        if (b.to === natural && a.to !== natural)
+            return 1;
+        return a.to.localeCompare(b.to);
+    });
+}
+export function getTransitionGuards(from, to, track = "standard") {
+    // Natural forward edge on this track: derive guards fresh from the
+    // track-specific gate schema. `TRANSITION_RULES` collapses shared edges
+    // across tracks (first-registered wins), so reading guards directly
+    // from the track-aware schema avoids silently dropping gates that only
+    // the current track requires (e.g. `tdd_traceable_to_plan` on standard
+    // gets lost if quick was registered first).
+    const ordered = TRACK_STAGES[track];
+    const fromIdx = ordered.indexOf(from);
+    if (fromIdx >= 0 && ordered[fromIdx + 1] === to) {
+        return stageGateIds(from, track);
+    }
+    // Non-neighbour edges (e.g. `review -> tdd` with `review_verdict_blocked`)
+    // carry special guards not derivable from a stage's gate catalog; fall
+    // back to the pre-computed rule table.
     const match = TRANSITION_RULES.find((rule) => rule.from === from && rule.to === to);
     return match ? [...match.guards] : [];
 }

package/dist/fs-utils.d.ts

@@ -1,4 +1,13 @@
 export declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Strip a leading UTF-8 BOM (U+FEFF) if present. Many editors (VS Code on
+ * Windows, Notepad, some CI tools) silently prepend a BOM when saving
+ * UTF-8; when the file is then split on `\n` the first line keeps the
+ * invisible BOM and `JSON.parse` rejects it, which caused the first
+ * knowledge.jsonl entry to be silently dropped on load. Treat BOM as a
+ * no-op at read time so the rest of the pipeline sees clean UTF-8.
+ */
+export declare function stripBom(text: string): string;
 export interface DirectoryLockOptions {
     retries?: number;
     retryDelayMs?: number;

package/dist/fs-utils.js

@@ -3,6 +3,17 @@ import path from "node:path";
 export async function ensureDir(dirPath) {
     await fs.mkdir(dirPath, { recursive: true });
 }
+/**
+ * Strip a leading UTF-8 BOM (U+FEFF) if present. Many editors (VS Code on
+ * Windows, Notepad, some CI tools) silently prepend a BOM when saving
+ * UTF-8; when the file is then split on `\n` the first line keeps the
+ * invisible BOM and `JSON.parse` rejects it, which caused the first
+ * knowledge.jsonl entry to be silently dropped on load. Treat BOM as a
+ * no-op at read time so the rest of the pipeline sees clean UTF-8.
+ */
+export function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -16,6 +27,7 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
     const staleAfterMs = options.staleAfterMs ?? 60_000;
     await ensureDir(path.dirname(lockPath));
     let acquired = false;
+    let lastError = null;
     for (let attempt = 0; attempt < retries; attempt += 1) {
         try {
             await fs.mkdir(lockPath);
@@ -23,6 +35,7 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
             break;
         }
         catch (error) {
+            lastError = error;
             const code = error?.code;
             if (code !== "EEXIST") {
                 throw error;
@@ -41,20 +54,50 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
         }
     }
     if (!acquired) {
-        throw new Error(`Failed to acquire lock: ${lockPath}`);
+        const details = lastError instanceof Error ? lastError.message : String(lastError);
+        throw new Error(`Failed to acquire lock: ${lockPath} (attempts=${retries}, retryDelayMs=${retryDelayMs}, staleAfterMs=${staleAfterMs}, lastError=${details})`);
     }
     try {
         return await fn();
     }
     finally {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+        await fs.rm(lockPath, { recursive: true, force: true }).catch((cleanupError) => {
+            // Lock cleanup failure should not shadow the original operation result,
+            // but keep a diagnostic breadcrumb for flaky FS environments.
+            const details = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+            // eslint-disable-next-line no-console
+            console.warn(`cclaw lock cleanup failed for ${lockPath}: ${details}`);
+        });
     }
 }
 export async function writeFileSafe(filePath, content) {
     await ensureDir(path.dirname(filePath));
     const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
     await fs.writeFile(tempPath, content, "utf8");
-    await fs.rename(tempPath, filePath);
+    try {
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        const code = error?.code;
+        // `rename` fails with EXDEV when the temp file and target live on
+        // different filesystems (container bind mounts, tmpfs + rootfs,
+        // cross-volume setups). Fall back to copy + unlink so atomic writes
+        // still work — copyFile is not fully atomic but is the best we can
+        // do across devices, and we remove the temp even if copy fails.
+        if (code === "EXDEV") {
+            try {
+                await fs.copyFile(tempPath, filePath);
+            }
+            finally {
+                await fs.unlink(tempPath).catch(() => undefined);
+            }
+            return;
+        }
+        // Other errors: try to clean up the temp to avoid littering the
+        // directory with orphaned `.tmp-<pid>-*` files, then rethrow.
+        await fs.unlink(tempPath).catch(() => undefined);
+        throw error;
+    }
 }
 export async function exists(filePath) {
     try {

package/dist/gate-evidence.d.ts

@@ -41,6 +41,8 @@ export interface ReconciliationNotice {
 export interface ReconciliationNoticesPayload {
     schemaVersion: number;
     notices: ReconciliationNotice[];
+    parseOk: boolean;
+    schemaOk: boolean;
 }
 export interface ReconciliationNoticeBuckets {
     activeBlocked: ReconciliationNotice[];

package/dist/gate-evidence.js

@@ -72,7 +72,9 @@ function reconciliationNoticesPath(projectRoot) {
 function defaultReconciliationNoticesPayload() {
     return {
         schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
-        notices: []
+        notices: [],
+        parseOk: true,
+        schemaOk: true
     };
 }
 function sanitizeReconciliationNotice(raw) {
@@ -104,6 +106,7 @@ export async function readReconciliationNotices(projectRoot) {
     }
     try {
         const raw = JSON.parse(await fs.readFile(filePath, "utf8"));
+        const schemaOk = raw.schemaVersion === RECONCILIATION_NOTICES_SCHEMA_VERSION;
         const notices = Array.isArray(raw.notices)
             ? raw.notices
                 .map((value) => sanitizeReconciliationNotice(value))
@@ -111,11 +114,17 @@ export async function readReconciliationNotices(projectRoot) {
             : [];
         return {
             schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
-            notices
+            notices,
+            parseOk: true,
+            schemaOk
         };
     }
     catch {
-        return defaultReconciliationNoticesPayload();
+        return {
+            ...defaultReconciliationNoticesPayload(),
+            parseOk: false,
+            schemaOk: false
+        };
     }
 }
 async function writeReconciliationNotices(projectRoot, payload) {
@@ -212,7 +221,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
     const artifactPresent = await currentStageArtifactExists(projectRoot, stage, flowState.track);
     const shouldValidateArtifact = artifactPresent || catalog.passed.length > 0 || flowState.completedStages.includes(stage);
     if (shouldValidateArtifact) {
-        const lint = await lintArtifact(projectRoot, stage);
+        const lint = await lintArtifact(projectRoot, stage, flowState.track);
         if (!lint.passed) {
             const failedRequired = lint.findings
                 .filter((finding) => finding.required && !finding.found)

package/dist/gitignore.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { REQUIRED_GITIGNORE_PATTERNS } from "./constants.js";
-import { exists } from "./fs-utils.js";
+import { exists, writeFileSafe } from "./fs-utils.js";
 export async function ensureGitignore(projectRoot) {
     const gitignorePath = path.join(projectRoot, ".gitignore");
     const currentContent = (await exists(gitignorePath))
@@ -15,7 +15,10 @@ export async function ensureGitignore(projectRoot) {
     }
     const base = lines.join("\n").replace(/\s+$/u, "");
     const suffix = `${base.length > 0 ? "\n" : ""}${missing.join("\n")}\n`;
-    await fs.writeFile(gitignorePath, `${base}${suffix}`, "utf8");
+    // `writeFileSafe` performs a tmp-file + rename so a crash mid-write
+    // cannot leave `.gitignore` in a half-written state; the previous
+    // direct `fs.writeFile` could truncate the file on SIGKILL.
+    await writeFileSafe(gitignorePath, `${base}${suffix}`);
 }
 export async function removeGitignorePatterns(projectRoot) {
     const gitignorePath = path.join(projectRoot, ".gitignore");
@@ -30,7 +33,7 @@ export async function removeGitignorePatterns(projectRoot) {
         await fs.rm(gitignorePath, { force: true });
     }
     else {
-        await fs.writeFile(gitignorePath, `${result}\n`, "utf8");
+        await writeFileSafe(gitignorePath, `${result}\n`);
     }
 }
 export async function gitignoreHasRequiredPatterns(projectRoot) {

package/dist/harness-adapters.js

@@ -54,7 +54,12 @@ const LEGACY_CODEX_SKILL_NAMES = [
     "cclaw-cc-next",
     "cclaw-cc-view",
     "cclaw-cc-ops",
-    "cclaw-cc-ideate"
+    "cclaw-cc-ideate",
+    // Pre-v0.40 installed `/cc-learn` as a top-level skill before it was
+    // folded into `/cc-ops`. Without this entry the orphan stays behind
+    // after upgrade and Codex lists both the new in-thread workflow and
+    // the legacy slash command.
+    "cclaw-cc-learn"
 ];
 /**
  * Shims that older cclaw versions installed as top-level slash commands but
@@ -417,6 +422,11 @@ what the hook surface does and does not cover.
   are **not** gated by hooks — read
   \`.cclaw/references/harnesses/codex-playbook.md\` for what cclaw
   substitutes with in-turn agent steps for those call classes.
+- Codex's \`SessionStart\` matcher only supports \`startup|resume\`. Claude
+  and Cursor also fire on \`clear\` and \`compact\`, so mid-session
+  context resets there re-inject cclaw's bootstrap automatically. In
+  Codex you must re-announce the active stage yourself after any
+  \`/clear\` or compaction — the skill does not reload implicitly.
 `;
 }
 function codexSkillMarkdown(command, skillName, skillFolder, commandFile) {