cclaw-cli 0.48.0 → 0.48.1

package/dist/artifact-linter.d.ts

@@ -1,4 +1,4 @@
-import { type FlowStage } from "./types.js";
+import { type FlowStage, type FlowTrack } from "./types.js";
 export interface LintFinding {
     section: string;
     required: boolean;
@@ -46,7 +46,7 @@ export interface LearningsParseResult {
     details: string;
 }
 export declare function parseLearningsSection(sectionBody: string): LearningsParseResult;
-export declare function lintArtifact(projectRoot: string, stage: FlowStage): Promise<LintResult>;
+export declare function lintArtifact(projectRoot: string, stage: FlowStage, track?: FlowTrack): Promise<LintResult>;
 export declare function validateReviewArmy(projectRoot: string): Promise<{
     valid: boolean;
     errors: string[];

package/dist/artifact-linter.js

@@ -795,8 +795,8 @@ function validateSectionBody(sectionBody, rule, sectionName) {
         details: "Section heading and content satisfy lint heuristics."
     };
 }
-export async function lintArtifact(projectRoot, stage) {
-    const schema = stageSchema(stage);
+export async function lintArtifact(projectRoot, stage, track = "standard") {
+    const schema = stageSchema(stage, track);
     const { absPath: absFile, relPath: relFile } = await resolveArtifactPath(projectRoot, schema.artifactFile);
     const findings = [];
     if (!(await exists(absFile))) {

package/dist/content/core-agents.d.ts

@@ -24,8 +24,60 @@ export interface AgentDefinition {
 }
 /**
  * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ *
+ * Declared with `satisfies` so the array retains literal `name` types for
+ * downstream type-level consumers (e.g. `AgentName`), while still being
+ * checked against the `AgentDefinition` shape at compile time. Do not add
+ * an explicit `AgentDefinition[]` annotation here — it would widen `name`
+ * to `string` and break the compile-time drift guard.
+ */
+export declare const CCLAW_AGENTS: readonly [{
+    readonly name: "planner";
+    readonly description: "MANDATORY for scope/design/plan and PROACTIVE for high-ambiguity work. MUST BE USED when sequencing, dependency mapping, or risk trade-offs are required before coding.";
+    readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
+    readonly model: "deep";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["brainstorm", "scope", "design", "spec", "plan"];
+    readonly body: string;
+}, {
+    readonly name: "reviewer";
+    readonly description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["spec", "review", "ship"];
+    readonly body: string;
+}, {
+    readonly name: "security-reviewer";
+    readonly description: "MANDATORY during review; PROACTIVE during design/ship for trust-boundary changes. Always produce an explicit no-change attestation when no security-relevant surface moved.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["design", "review", "ship"];
+    readonly body: string;
+}, {
+    readonly name: "test-author";
+    readonly description: "MANDATORY in TDD stage. MUST BE USED for RED -> GREEN -> REFACTOR with evidence-first discipline.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["tdd"];
+    readonly body: string;
+}, {
+    readonly name: "doc-updater";
+    readonly description: "MANDATORY at ship and PROACTIVE when behavior/config/public API changes. Keep docs and runbooks in lockstep with shipped behavior.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob"];
+    readonly model: "fast";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["tdd", "ship"];
+    readonly body: string;
+}];
+/**
+ * Union of known agent names (compile-time). Use this in content that
+ * references agents by name so the TypeScript compiler catches renames
+ * and typos instead of letting them slip into generated artifacts.
  */
-export declare const CCLAW_AGENTS: AgentDefinition[];
+export type AgentName = (typeof CCLAW_AGENTS)[number]["name"];
 /**
  * Render a complete cclaw agent markdown file (YAML frontmatter + body).
  */

package/dist/content/core-agents.js

@@ -15,6 +15,12 @@ function yamlFlowSequence(values) {
 }
 /**
  * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ *
+ * Declared with `satisfies` so the array retains literal `name` types for
+ * downstream type-level consumers (e.g. `AgentName`), while still being
+ * checked against the `AgentDefinition` shape at compile time. Do not add
+ * an explicit `AgentDefinition[]` annotation here — it would widen `name`
+ * to `string` and break the compile-time drift guard.
  */
 export const CCLAW_AGENTS = [
     {

package/dist/content/observe.js

@@ -1094,11 +1094,20 @@ export function claudeHooksJsonWithObservation() {
                         }]
                 }],
             PreToolUse: [{
+                    // `prompt-guard.sh` inspects tool inputs across all tool calls;
+                    // it has to stay on `*` so it sees MCP/Edit/Write/WebSearch
+                    // traffic too. `workflow-guard.sh`, however, only checks TDD
+                    // ordering on write-like operations — it is a no-op for reads.
+                    // Splitting the two matchers cuts Claude's per-read hook
+                    // overhead in half without reducing coverage on write paths.
                     matcher: "*",
                     hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("prompt-guard.sh")
-                        }, {
+                        }]
+                }, {
+                    matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash",
+                    hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("workflow-guard.sh")
                         }]
@@ -1196,6 +1205,18 @@ export function codexHooksJsonWithObservation() {
                     hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("prompt-guard.sh")
+                        }, {
+                            // `workflow-guard.sh` also runs here because Codex's PreToolUse
+                            // only sees Bash; Write/Edit/MCP writes never reach the hook
+                            // surface. Running workflow-guard on UserPromptSubmit catches
+                            // TDD-order violations that originate from the user's prompt
+                            // text (e.g. "edit X.ts to ..."). Payload is a prompt envelope,
+                            // not a tool call, so the script's TOOL extraction falls back
+                            // to "unknown" and advisory mode is a no-op by design — the
+                            // value is that prompt text is scanned for write-shaped intent
+                            // via the existing PAYLOAD_LOWER heuristics.
+                            type: "command",
+                            command: hookDispatcherCommand("workflow-guard.sh")
                         }, {
                             type: "command",
                             command: "bash -lc 'if command -v cclaw >/dev/null 2>&1; then cclaw internal verify-current-state --quiet >/dev/null || true; else npx -y cclaw-cli internal verify-current-state --quiet >/dev/null || true; fi'"

package/dist/content/opencode-plugin.js

@@ -233,11 +233,15 @@ export default function cclawPlugin(ctx) {
         eventType === "session.created" ||
         eventType === "session.resumed" ||
         eventType === "session.compacted" ||
-        eventType === "session.cleared"
+        eventType === "session.cleared" ||
+        eventType === "session.updated"
       ) {
         // Avoid writing directly to stdout in lifecycle hooks because it can
         // interfere with OpenCode TUI rendering. Bootstrap is injected via
         // the system transform hook instead.
+        // session.updated covers config reloads and artifact/rules edits
+        // that happen mid-session; without it the cache would stay stale
+        // until the next compaction or restart.
         refreshBootstrapCache();
       }
       if (eventType === "session.compacted") {

package/dist/content/stage-schema.js

@@ -5,6 +5,7 @@ import { tddStageForTrack } from "./stages/tdd.js";
 const ARTIFACT_STAGE_BY_PATH = {
     ".cclaw/artifacts/01-brainstorm.md": "brainstorm",
     ".cclaw/artifacts/02-scope.md": "scope",
+    ".cclaw/artifacts/02a-research.md": "design",
     ".cclaw/artifacts/03-design.md": "design",
     ".cclaw/artifacts/04-spec.md": "spec",
     ".cclaw/artifacts/05-plan.md": "plan",
@@ -46,6 +47,7 @@ const REQUIRED_GATE_IDS = {
         "tdd_green_full_suite",
         "tdd_refactor_completed",
         "tdd_verified_before_complete",
+        "tdd_docs_drift_check",
         ...(track === "quick" ? [] : ["tdd_traceable_to_plan"])
     ],
     review: (track) => [

package/dist/content/templates.js

@@ -1,10 +1,11 @@
+import { CCLAW_VERSION } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 import { FLOW_STAGES } from "../types.js";
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `---
 stage: brainstorm
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -52,7 +53,7 @@ inputs_hash: sha256:pending
     "02-scope.md": `---
 stage: scope
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -158,7 +159,7 @@ inputs_hash: sha256:pending
     "02a-research.md": `---
 stage: design
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -199,7 +200,7 @@ inputs_hash: sha256:pending
     "03-design.md": `---
 stage: design
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -303,7 +304,7 @@ inputs_hash: sha256:pending
     "04-spec.md": `---
 stage: spec
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -359,7 +360,7 @@ inputs_hash: sha256:pending
     "05-plan.md": `---
 stage: plan
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -438,7 +439,7 @@ Execution rule: complete and verify each batch before starting the next batch.
     "06-tdd.md": `---
 stage: tdd
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -505,7 +506,7 @@ inputs_hash: sha256:pending
     "07-review.md": `---
 stage: review
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -614,7 +615,7 @@ inputs_hash: sha256:pending
     "08-ship.md": `---
 stage: ship
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -669,7 +670,7 @@ inputs_hash: sha256:pending
     "09-retro.md": `---
 stage: retro
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending

package/dist/content/utility-skills.d.ts

@@ -48,4 +48,10 @@ export declare const LANGUAGE_RULE_PACK_GENERATORS: Record<string, () => string>
  */
 export declare const LEGACY_LANGUAGE_RULE_PACK_FOLDERS: readonly ["language-typescript", "language-python", "language-go"];
 export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs", "executing-plans", "verification-before-completion", "finishing-a-development-branch", "context-engineering", "source-driven-development", "frontend-accessibility", "landscape-check", "adversarial-review", "security-audit", "knowledge-curation", "retrospective", "document-review", "receiving-code-review"];
-export declare const UTILITY_SKILL_MAP: Record<string, () => string>;
+export type UtilitySkillFolder = (typeof UTILITY_SKILL_FOLDERS)[number];
+/**
+ * One entry per `UTILITY_SKILL_FOLDERS` slot. Typed via the tuple so that
+ * adding a folder without a generator (or vice versa) is a TypeScript
+ * error — keeps the two sources of truth in lockstep at compile time.
+ */
+export declare const UTILITY_SKILL_MAP: Record<UtilitySkillFolder, () => string>;

package/dist/content/utility-skills.js

@@ -1735,6 +1735,11 @@ export const UTILITY_SKILL_FOLDERS = [
     "document-review",
     "receiving-code-review"
 ];
+/**
+ * One entry per `UTILITY_SKILL_FOLDERS` slot. Typed via the tuple so that
+ * adding a folder without a generator (or vice versa) is a TypeScript
+ * error — keeps the two sources of truth in lockstep at compile time.
+ */
 export const UTILITY_SKILL_MAP = {
     security: securityReviewSkill,
     debugging: debuggingSkill,

package/dist/delegation.d.ts

@@ -66,6 +66,16 @@ export type DelegationLedger = {
     runId: string;
     entries: DelegationEntry[];
 };
+/**
+ * Heuristic: does a changed file path strongly imply a trust-boundary
+ * surface? Used to gate adversarial-reviewer requirements on review.
+ *
+ * Matches authN/Z, credentials, crypto, policy, or explicit sanitization
+ * or injection handling. Intentionally excludes broad terms like `input`
+ * and `validation` because they match innocuous paths such as
+ * `form-input.ts` or `number-validation.ts` and produce false positives.
+ */
+export declare function isTrustBoundaryPath(filePath: string): boolean;
 export declare function readDelegationLedger(projectRoot: string): Promise<DelegationLedger>;
 export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
 /**

package/dist/delegation.js

@@ -53,6 +53,18 @@ async function resolveReviewDiffBase(projectRoot) {
         return null;
     }
 }
+/**
+ * Heuristic: does a changed file path strongly imply a trust-boundary
+ * surface? Used to gate adversarial-reviewer requirements on review.
+ *
+ * Matches authN/Z, credentials, crypto, policy, or explicit sanitization
+ * or injection handling. Intentionally excludes broad terms like `input`
+ * and `validation` because they match innocuous paths such as
+ * `form-input.ts` or `number-validation.ts` and produce false positives.
+ */
+export function isTrustBoundaryPath(filePath) {
+    return /(auth|security|secret|token|credential|permission|acl|policy|oauth|session|encrypt|decrypt|sanitize|untrusted|csrf|xss|injection|taint)/iu.test(filePath);
+}
 async function detectReviewTriggers(projectRoot) {
     const empty = {
         changedFiles: 0,
@@ -81,7 +93,7 @@ async function detectReviewTriggers(projectRoot) {
             .split(/\r?\n/gu)
             .map((line) => line.trim())
             .filter((line) => line.length > 0);
-        const trustBoundaryChanged = changedPaths.some((filePath) => /(auth|security|secret|token|credential|permission|acl|policy|oauth|session|encrypt|decrypt|input|validation)/iu.test(filePath));
+        const trustBoundaryChanged = changedPaths.some((p) => isTrustBoundaryPath(p));
         const requireAdversarialReviewer = changedLines > 100 || changedFiles > 10 || trustBoundaryChanged;
         return {
             changedFiles,

package/dist/doctor.js

@@ -3,7 +3,7 @@ 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";
@@ -547,8 +547,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 +815,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

package/dist/flow-state.d.ts

@@ -94,6 +94,6 @@ export declare function skippedStagesForTrack(track: FlowTrack): FlowStage[];
 export declare function firstStageForTrack(track: FlowTrack): FlowStage;
 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 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

@@ -97,7 +97,21 @@ 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 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));
 }
@@ -54,7 +65,30 @@ 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.js

@@ -212,7 +212,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) {

package/dist/install.js

@@ -44,7 +44,8 @@ import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, harnessShimFileNames, harnessTier, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
 import { validateHookDocument } from "./hook-schema.js";
-import { ensureRunSystem, readFlowState } from "./runs.js";
+import { detectHarnesses } from "./init-detect.js";
+import { CorruptFlowStateError, ensureRunSystem, readFlowState } from "./runs.js";
 import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
@@ -853,7 +854,24 @@ Drop this section if no hard rule applies. Keep it crisp:
 async function ensureSessionStateFiles(projectRoot) {
     const stateDir = runtimePath(projectRoot, "state");
     await ensureDir(stateDir);
-    const flow = await readFlowState(projectRoot);
+    // If flow-state.json is corrupt, `readFlowState` quarantines the bad
+    // file and throws. During install we'd rather continue than abort:
+    // the user just asked to set up cclaw, and the corrupt file is already
+    // preserved next to the original path. Fall back to a fresh initial
+    // state so the rest of install completes and the user can inspect the
+    // `.corrupt-<timestamp>.json` quarantine afterwards.
+    let flow;
+    try {
+        flow = await readFlowState(projectRoot);
+    }
+    catch (err) {
+        if (err instanceof CorruptFlowStateError) {
+            flow = createInitialFlowState();
+        }
+        else {
+            throw err;
+        }
+    }
     const activityPath = path.join(stateDir, "stage-activity.jsonl");
     if (!(await exists(activityPath))) {
         await writeFileSafe(activityPath, "");
@@ -1021,6 +1039,14 @@ async function writeHarnessGapsState(projectRoot, harnesses) {
                 break;
         }
         for (const event of missingHookEvents) {
+            if (harness === "codex" && event === "precompact_digest") {
+                // Codex CLI has no PreCompact event. Generic "schedule the script
+                // manually" copy doesn't help; instead, point the agent at the
+                // in-thread substitute that already exists in cclaw content
+                // (`/cc-ops retro` reads the same digest the hook would emit).
+                remediation.push("hook event precompact_digest → Codex has no PreCompact event; run `/cc-ops retro` in-thread before compaction instead of relying on a hook");
+                continue;
+            }
             remediation.push(`hook event ${event} → schedule the corresponding script manually or accept reduced observability`);
         }
         return {
@@ -1210,9 +1236,19 @@ export async function initCclaw(options) {
 }
 export async function syncCclaw(projectRoot) {
     const configExists = await exists(configPath(projectRoot));
-    const config = await readConfig(projectRoot);
+    let config = await readConfig(projectRoot);
     if (!configExists) {
-        await writeConfig(projectRoot, createDefaultConfig(config.harnesses));
+        // Prefer detected harness markers over the hardcoded default list.
+        // Without this, a user running `cclaw sync` in a `.claude`-only
+        // project ends up with a config that also enables cursor/opencode/
+        // codex, which then fails doctor checks for missing shim folders.
+        // Fall back to the previous default (config.harnesses) if no markers
+        // are found so brand-new projects still bootstrap cleanly.
+        const detected = await detectHarnesses(projectRoot);
+        const harnesses = detected.length > 0 ? detected : config.harnesses;
+        const defaultConfig = createDefaultConfig(harnesses);
+        await writeConfig(projectRoot, defaultConfig);
+        config = defaultConfig;
     }
     await materializeRuntime(projectRoot, config, false);
 }

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/retro-gate.js

@@ -1,14 +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");
 }
-const RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS = 24 * 60 * 60 * 1000;
+// 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;
@@ -58,7 +64,7 @@ export async function evaluateRetroGate(projectRoot, state) {
     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();
@@ -90,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

@@ -24,6 +24,13 @@ function validateFlowTransition(prev, next) {
         // 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.`);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.0",
+  "version": "0.48.1",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {