cclaw-cli 0.51.30 → 0.55.2

package/dist/harness-adapters.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { conversationLanguagePolicyMarkdown } from "./content/language-policy.js";
 import { CCLAW_AGENTS, agentMarkdown } from "./content/core-agents.js";
-import { ironLawsAgentsMdBlock } from "./content/iron-laws.js";
+import { IRON_LAWS } from "./content/iron-laws.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 export const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export const CCLAW_MARKER_END = "<!-- cclaw-end -->";
@@ -15,11 +15,11 @@ const RUNTIME_AGENTS_BLOCK_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "u"
 const RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "gu");
 const UTILITY_SHIMS = [
     {
-        fileName: "cc-ideate.md",
-        skillName: "cc-ideate",
-        command: "ideate",
-        skillFolder: "flow-ideate",
-        commandFile: "ideate.md"
+        fileName: "cc-idea.md",
+        skillName: "cc-idea",
+        command: "idea",
+        skillFolder: "flow-idea",
+        commandFile: "idea.md"
     },
     {
         fileName: "cc-cancel.md",
@@ -163,9 +163,9 @@ export function harnessDispatchSurface(harnessId) {
         case "cursor":
             return "Use Cursor Subagent/Task with a generic subagent_type (explore for read-only mapping, generalPurpose for broader work, shell/browser-use when specifically needed) and paste the cclaw role prompt; record fulfillmentMode: \"generic-dispatch\" with evidenceRefs.";
         case "opencode":
-            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>; if agents or plugin registration are missing, run `cclaw sync` and check opencode.json(.c) plugin registration with `cclaw doctor --explain`; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
+            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>; if agents or plugin registration are missing, run `cclaw sync` and check opencode.json(.c) plugin registration with `npx cclaw-cli sync`; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
         case "codex":
-            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name; if hooks are inert, set `[features] codex_hooks = true` in ~/.codex/config.toml or rerun init/sync repair, then `cclaw doctor --explain`; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
+            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name; if hooks are inert, set `[features] codex_hooks = true` in ~/.codex/config.toml or rerun init/sync repair, then `npx cclaw-cli sync`; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
     }
 }
 /**
@@ -292,6 +292,35 @@ export function harnessesByTier() {
         return tierOrder[harnessTier(a)] - tierOrder[harnessTier(b)];
     });
 }
+function ironLawsAgentsMdBlock() {
+    const enforcedLawIds = new Set([
+        "stop-clean-or-handoff",
+        "review-coverage-complete-before-ship"
+    ]);
+    const enforcedRows = IRON_LAWS
+        .filter((law) => enforcedLawIds.has(law.id))
+        .map((law) => `| \`${law.id}\` | ${law.rule} | ${law.enforcement} |`)
+        .join("\n");
+    const advisoryRows = IRON_LAWS
+        .filter((law) => !enforcedLawIds.has(law.id))
+        .map((law) => {
+        const appliesTo = law.appliesTo === "all" ? "all stages" : law.appliesTo.join(", ");
+        return `- \`${law.id}\` (applies to: ${appliesTo})`;
+    })
+        .join("\n");
+    return `### Iron Laws
+
+These rules are always-on. The hook-enforced runtime laws are:
+
+| ID | Rule | Enforced by |
+|---|---|---|
+${enforcedRows}
+
+Advisory laws are stage-owned through each stage's HARD-GATE block:
+
+${advisoryRows}
+`;
+}
 function agentsMdBlock() {
     return `${CCLAW_MARKER_START}
 ## Cclaw — Workflow Adapter
@@ -343,7 +372,7 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 | Command | Purpose |
 |---|---|
 | \`/cc\` | **Entry point.** No args = resume or progress current flow. With prompt = classify task and start the right flow. |
-| \`/cc-ideate\` | **Ideate mode.** Generates a ranked repo-improvement backlog before implementation. |
+| \`/cc-idea\` | **Idea mode.** Generates a ranked repo-improvement backlog before implementation. |
 | \`/cc-cancel\` | **Non-completion closeout.** Archives a cancelled/abandoned run with a required reason. |
 
 Knowledge capture and curation run automatically as part of stage completion
@@ -372,11 +401,11 @@ If the same approach fails three times in a row (same command, same finding, sam
 ### Codex users
 
 OpenAI Codex CLI has **no native \`/cc\` slash command** (custom prompts
-were deprecated in v0.89, Jan 2026). The \`/cc\`, \`/cc-ideate\`, and
+were deprecated in v0.89, Jan 2026). The \`/cc\`, \`/cc-idea\`, and
 \`/cc-cancel\` tokens above describe intent — in Codex they map onto skills cclaw installs at
 \`.agents/skills/cc*/SKILL.md\`. Activate one of two ways:
 
-- Type \`/use cc\` (or \`cc-ideate\` / \`cc-cancel\`) at Codex's prompt.
+- Type \`/use cc\` (or \`cc-idea\` / \`cc-cancel\`) at Codex's prompt.
 - Type \`/cc …\` as plain text — Codex matches the skill \`description\`
   frontmatter (which spells out the token verbatim) and loads the right
   skill body automatically.
@@ -385,9 +414,9 @@ Codex CLI v0.114+ (Mar 2026) **does** expose lifecycle hooks via
 \`.codex/hooks.json\`, gated by the \`[features] codex_hooks = true\` flag
 in \`~/.codex/config.toml\`. cclaw generates \`.codex/hooks.json\` on
 sync; if the feature flag is off, hooks are inert and cclaw's
-session-start rehydration simply does not fire. Run \`cclaw doctor\` to
+session-start rehydration simply does not fire. Run \`npx cclaw-cli sync\` to
 see if the flag is missing. \`.codex/commands/*\` is still unused by
-Codex CLI and is removed on every sync. Run \`cclaw doctor --explain\` for
+Codex CLI and is removed on every sync. Run \`npx cclaw-cli sync\` for
 hook coverage details (Bash-only \`PreToolUse\`/\`PostToolUse\`; other events are full).
 ${CCLAW_MARKER_END}`;
 }
@@ -449,7 +478,7 @@ function utilityShimBehavior(command) {
     switch (command) {
         case "cc":
             return "This is the entry command, not a flow stage. It may initialize or resume flow state after confirmation.";
-        case "ideate":
+        case "idea":
             return "This is an ideation command, not a flow stage. It may write ideation artifacts/seeds but does not advance flow state.";
         case "cancel":
             return "This is a non-completion closeout utility, not a flow stage. It requires a reason and archives cancelled or abandoned work without presenting it as completed.";
@@ -484,8 +513,8 @@ function codexSkillDescription(command) {
     switch (command) {
         case "cc":
             return `Entry point for the cclaw track-aware workflow ending in ship plus auto-closeout (retro → compound → archive). Use whenever the user types \`/cc\`, \`/cclaw\`, or asks to "start the flow", "begin cclaw", "kick off the workflow", "classify this task", or wants to start/resume a non-trivial software change. No args = resume the active stage from \`.cclaw/state/flow-state.json\`. With a prompt = classify and pick a track (quick/medium/standard).`;
-        case "ideate":
-            return `Read-only repo-improvement ideate mode for cclaw. Use when the user types \`/cc-ideate\` or asks to "ideate", "scan the repo for TODOs/tech debt", "generate a backlog", or wants a ranked list of candidate ideas before committing to a single flow. Does not mutate \`.cclaw/state/flow-state.json\`.`;
+        case "idea":
+            return `Read-only repo-improvement idea mode for cclaw. Use when the user types \`/cc-idea\` or asks to "scan the repo for TODOs/tech debt", "generate a backlog", "brainstorm improvement ideas", or wants a ranked list of candidate ideas before committing to a single flow. Does not mutate \`.cclaw/state/flow-state.json\`.`;
         case "cancel":
             return `Cancel or abandon the active cclaw run. Use when the user types \`/cc-cancel\` or asks to cancel, abandon, stop, discard, or reset an unfinished run. Requires a reason and archives with cancelled/abandoned disposition.`;
         default:
@@ -518,7 +547,7 @@ under \`.agents/skills/${skillSlug}/\` so the user can either:
 
 Lifecycle hooks **are** available in Codex CLI v0.114+ (behind the
 \`[features] codex_hooks = true\` flag in \`~/.codex/config.toml\`) and
-cclaw installs a matching \`.codex/hooks.json\`; run \`cclaw doctor --explain\`
+cclaw installs a matching \`.codex/hooks.json\`; run \`npx cclaw-cli sync\`
 for the current hook surface and limitations.
 
 ## Protocol
@@ -542,7 +571,7 @@ for the current hook surface and limitations.
   unavailable or disabled, and then include non-empty \`evidenceRefs\`.
 - Codex's \`PreToolUse\` / \`PostToolUse\` hooks currently only intercept
   the \`Bash\` tool. \`Write\`, \`Edit\`, \`WebSearch\`, and MCP tool calls
-  are **not** gated by hooks — use \`cclaw doctor --explain\` for what cclaw
+  are **not** gated by hooks — use \`npx cclaw-cli sync\` 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

package/dist/install.js

@@ -5,16 +5,15 @@ import { promisify } from "node:util";
 import { CCLAW_VERSION, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { writeConfig, createDefaultConfig, readConfig, configPath, detectLanguageRulePacks, detectAdvancedKeys } from "./config.js";
 import { learnSkillMarkdown } from "./content/learnings.js";
-import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
 import { stageCommandShimMarkdown } from "./content/stage-command.js";
-import { ideateCommandContract, ideateCommandSkillMarkdown } from "./content/ideate-command.js";
+import { ideaCommandContract, ideaCommandSkillMarkdown } from "./content/idea-command.js";
 import { startCommandContract, startCommandSkillMarkdown } from "./content/start-command.js";
 import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-command.js";
 import { cancelCommandContract, cancelCommandSkillMarkdown } from "./content/cancel-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, startFlowScript, runHookCmdScript, delegationRecordScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, startFlowScript, cancelRunScript, runHookCmdScript, delegationRecordScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
@@ -29,10 +28,11 @@ import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ManagedResourceSession, setActiveManagedResourceSession } from "./managed-resources.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
-import { HARNESS_ADAPTERS, harnessShimFileNames, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
+import { HARNESS_ADAPTERS, harnessShimFileNames, harnessShimSkillNames, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
 import { validateHookDocument } from "./hook-schema.js";
 import { detectHarnesses } from "./init-detect.js";
-import { ensureRunSystem } from "./runs.js";
+import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
+import { CorruptFlowStateError, ensureRunSystem } 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";
@@ -49,6 +49,23 @@ async function writeInitSentinel(projectRoot, operation) {
     await writeFileSafe(sentinelPath, `${JSON.stringify({ operation, startedAt: new Date().toISOString() }, null, 2)}\n`);
     return sentinelPath;
 }
+async function warnStaleInitSentinel(projectRoot, operation) {
+    const sentinelPath = runtimePath(projectRoot, "state", INIT_SENTINEL_FILE);
+    if (!(await exists(sentinelPath)))
+        return;
+    let startedAt = "unknown time";
+    try {
+        const raw = await fs.readFile(sentinelPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.startedAt === "string" && parsed.startedAt.trim().length > 0) {
+            startedAt = parsed.startedAt;
+        }
+    }
+    catch {
+        // best-effort parse of stale sentinel metadata
+    }
+    process.stderr.write(`[${operation}] Detected stale .init-in-progress sentinel from ${startedAt}; previous run may have crashed. Continuing.\n`);
+}
 async function removeBestEffort(targetPath, recursive = false) {
     try {
         await fs.rm(targetPath, { recursive, force: true });
@@ -89,6 +106,16 @@ const DEPRECATED_UTILITY_SKILL_FOLDERS = [
     "flow-tree",
     "flow-diff"
 ];
+const DEPRECATED_STAGE_SKILL_FOLDERS = [
+    "brainstorming",
+    "scope-shaping",
+    "engineering-design-lock",
+    "specification-authoring",
+    "planning-and-task-breakdown",
+    "test-driven-development",
+    "two-layer-review",
+    "shipping-and-handoff"
+];
 const DEPRECATED_AGENT_FILES = [
     "securityer.md",
     "spec-reviewer.md",
@@ -451,8 +478,7 @@ async function writeSkills(projectRoot, config) {
     }
     // Utility skills (not flow stages)
     await writeFileSafe(runtimePath(projectRoot, "skills", "learnings", "SKILL.md"), learnSkillMarkdown());
-    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-next-step", "SKILL.md"), nextCommandSkillMarkdown());
-    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-ideate", "SKILL.md"), ideateCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-idea", "SKILL.md"), ideaCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-start", "SKILL.md"), startCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-view", "SKILL.md"), viewCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-cancel", "SKILL.md"), cancelCommandSkillMarkdown());
@@ -516,8 +542,7 @@ async function writeSkills(projectRoot, config) {
 }
 async function writeEntryCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "start.md"), startCommandContract());
-    await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
-    await writeFileSafe(runtimePath(projectRoot, "commands", "ideate.md"), ideateCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "idea.md"), ideaCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "view.md"), viewCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "cancel.md"), cancelCommandContract());
     for (const stage of FLOW_STAGES) {
@@ -858,14 +883,16 @@ async function writeMergedHookJson(projectRoot, hookFilePath, generatedJson) {
     if (harness) {
         const generatedSchema = validateHookDocument(harness, generatedDoc);
         if (!generatedSchema.ok) {
-            throw new Error(`Generated ${harness} hook document failed schema validation: ${generatedSchema.errors.join("; ")}`);
+            throw new Error(`[sync fail-fast] Hook document drift detected for ${harness}: generated hook document is invalid (${generatedSchema.errors.join("; ")}). ` +
+                "Run `npx cclaw-cli sync` to regenerate managed hooks or repair the generated hook shape manually.");
         }
     }
     const mergedDoc = mergeHookDocuments(existingDoc, generatedDoc);
     if (harness) {
         const mergedSchema = validateHookDocument(harness, mergedDoc);
         if (!mergedSchema.ok) {
-            throw new Error(`Merged ${harness} hook document failed schema validation: ${mergedSchema.errors.join("; ")}`);
+            throw new Error(`[sync fail-fast] Hook document drift detected for ${harness}: merged hook document is invalid (${mergedSchema.errors.join("; ")}). ` +
+                "Run `npx cclaw-cli sync` after fixing the custom hook entry or remove the malformed user-authored hook block.");
         }
     }
     await writeFileSafe(hookFilePath, `${JSON.stringify(mergedDoc, null, 2)}\n`);
@@ -883,11 +910,14 @@ async function writeHooks(projectRoot, config) {
     }), null, 2)}\n`);
     await writeFileSafe(path.join(hooksDir, "stage-complete.mjs"), stageCompleteScript());
     await writeFileSafe(path.join(hooksDir, "start-flow.mjs"), startFlowScript());
+    await writeFileSafe(path.join(hooksDir, "cancel-run.mjs"), cancelRunScript());
     await writeFileSafe(path.join(hooksDir, "run-hook.mjs"), nodeHookRuntimeScript({
         strictness: effectiveStrictness,
         tddTestPathPatterns: config.tdd?.testPathPatterns ?? config.tddTestGlobs,
         tddProductionPathPatterns: config.tdd?.productionPathPatterns,
-        compoundRecurrenceThreshold: config.compound?.recurrenceThreshold
+        compoundRecurrenceThreshold: config.compound?.recurrenceThreshold,
+        earlyLoopEnabled: config.earlyLoop?.enabled,
+        earlyLoopMaxIterations: config.earlyLoop?.maxIterations
     }));
     await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookCmdScript());
     await writeFileSafe(path.join(hooksDir, "delegation-record.mjs"), delegationRecordScript());
@@ -900,7 +930,8 @@ async function writeHooks(projectRoot, config) {
             "run-hook.mjs",
             "run-hook.cmd",
             "delegation-record.mjs",
-            "opencode-plugin.mjs"
+            "opencode-plugin.mjs",
+            "cancel-run.mjs"
         ]) {
             await fs.chmod(path.join(hooksDir, script), 0o755);
         }
@@ -938,8 +969,8 @@ async function writeHooks(projectRoot, config) {
             // flag in `~/.codex/config.toml`. cclaw always writes the file so
             // the moment the flag flips on, the cclaw hooks start firing. See
             // `codexHooksJsonWithObservation` for the Bash-only caveat on
-            // PreToolUse/PostToolUse. `cclaw doctor` warns if the feature flag
-            // is not set.
+            // PreToolUse/PostToolUse. If the feature flag is off, hooks remain
+            // inert until the user enables codex_hooks in ~/.codex/config.toml.
             const codexDir = path.join(projectRoot, ".codex");
             await ensureDir(codexDir);
             await writeMergedHookJson(projectRoot, path.join(codexDir, "hooks.json"), codexHooksJson());
@@ -989,7 +1020,7 @@ async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
     for (const entry of managedHookFiles) {
         if (enabled.has(entry.harness))
             continue;
-        await removeManagedHookEntries(entry.hookPath);
+        await removeManagedHookEntries(entry.hookPath, { failOnParseError: true });
     }
     if (!enabled.has("opencode")) {
         try {
@@ -998,8 +1029,22 @@ async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
         catch {
             // best-effort cleanup
         }
+        try {
+            await fs.rm(path.join(projectRoot, ".opencode/agents"), { recursive: true, force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
         await removeManagedOpenCodePluginConfig(projectRoot, OPENCODE_PLUGIN_REL_PATH);
     }
+    if (!enabled.has("codex")) {
+        try {
+            await fs.rm(path.join(projectRoot, ".codex/agents"), { recursive: true, force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
 }
 async function writeState(projectRoot, config, forceReset = false) {
     const statePath = runtimePath(projectRoot, "state", "flow-state.json");
@@ -1013,6 +1058,9 @@ async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyFolder of DEPRECATED_UTILITY_SKILL_FOLDERS) {
         await removeBestEffort(runtimePath(projectRoot, "skills", legacyFolder), true);
     }
+    for (const legacyFolder of DEPRECATED_STAGE_SKILL_FOLDERS) {
+        await removeBestEffort(runtimePath(projectRoot, "skills", legacyFolder), true);
+    }
     for (const legacyAgentFile of DEPRECATED_AGENT_FILES) {
         await removeBestEffort(runtimePath(projectRoot, "agents", legacyAgentFile));
     }
@@ -1037,16 +1085,30 @@ async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyRuntimeDir of DEPRECATED_RUNTIME_DIRS) {
         await removeBestEffort(runtimePath(projectRoot, legacyRuntimeDir), true);
     }
-    // D-4 terminology migration: rename historical ideation artifacts to the
-    // canonical ideate-* naming without deleting user-authored content.
+    // Archive storage migration: `.cclaw/runs` is legacy and no longer a valid
+    // archive root. Remove only when empty; otherwise keep it so users can
+    // manually migrate or inspect old data.
+    const legacyRunsDir = runtimePath(projectRoot, "runs");
+    try {
+        const entries = await fs.readdir(legacyRunsDir);
+        if (entries.length === 0) {
+            await fs.rm(legacyRunsDir, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // missing or unreadable legacy dir; keep best-effort behavior
+    }
+    // D-4 terminology migration: rename historical ideation artifact prefixes to
+    // the canonical idea-* naming without deleting user-authored content.
+    const legacyIdeaArtifactPattern = /^ideation-(.+\.md)$/u;
     const artifactsDir = runtimePath(projectRoot, "artifacts");
     try {
         const entries = await fs.readdir(artifactsDir);
         for (const entry of entries) {
-            const match = /^ideation-(.+\.md)$/u.exec(entry);
+            const match = legacyIdeaArtifactPattern.exec(entry);
             if (!match)
                 continue;
-            const nextName = `ideate-${match[1]}`;
+            const nextName = `idea-${match[1]}`;
             const from = path.join(artifactsDir, entry);
             const to = path.join(artifactsDir, nextName);
             if (await exists(to)) {
@@ -1094,7 +1156,34 @@ async function cleanStaleFiles(projectRoot) {
     // Keep user-owned custom assets under .cclaw/agents and .cclaw/skills.
     // Legacy managed removals happen in cleanLegacyArtifacts() with explicit paths.
 }
+async function assertExpectedHarnessShims(projectRoot, harnesses) {
+    const expectedFiles = harnessShimFileNames();
+    const expectedSkillFolders = harnessShimSkillNames();
+    for (const harness of harnesses) {
+        const adapter = HARNESS_ADAPTERS[harness];
+        const base = path.join(projectRoot, adapter.commandDir);
+        for (const fileName of expectedFiles) {
+            const target = adapter.shimKind === "skill"
+                ? path.join(base, fileName.replace(/\.md$/u, ""), "SKILL.md")
+                : path.join(base, fileName);
+            if (!(await exists(target))) {
+                throw new Error(`[sync fail-fast] Harness shim drift detected for ${harness}: missing ${target}. ` +
+                    `Run \`npx cclaw-cli sync\` again; if the file is still missing, inspect harness permissions/paths.`);
+            }
+        }
+        if (adapter.shimKind === "skill") {
+            for (const folder of expectedSkillFolders) {
+                const skillPath = path.join(base, folder, "SKILL.md");
+                if (!(await exists(skillPath))) {
+                    throw new Error(`[sync fail-fast] Harness skill shim drift detected for ${harness}: missing ${skillPath}. ` +
+                        `Run \`npx cclaw-cli sync\` again; if the issue persists, inspect generated .agents/skills surfaces.`);
+                }
+            }
+        }
+    }
+}
 async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
+    await warnStaleInitSentinel(projectRoot, operation);
     const sentinelPath = await writeInitSentinel(projectRoot, operation);
     const managedSession = await ManagedResourceSession.create({ projectRoot, operation });
     setActiveManagedResourceSession(managedSession);
@@ -1110,25 +1199,51 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
             writeRulebook(projectRoot)
         ]);
         await writeState(projectRoot, config, forceStateReset);
-        await ensureRunSystem(projectRoot, { createIfMissing: false });
+        try {
+            await ensureRunSystem(projectRoot, { createIfMissing: false });
+        }
+        catch (error) {
+            if (error instanceof CorruptFlowStateError) {
+                throw new Error(`[sync fail-fast] Corrupt flow state detected: ${error.message} ` +
+                    `Resolve the quarantined flow-state file and re-run \`npx cclaw-cli sync\`.`);
+            }
+            throw error;
+        }
         await ensureKnowledgeStore(projectRoot);
         await writeHooks(projectRoot, config);
         await syncDisabledHarnessArtifacts(projectRoot, harnesses);
         await syncManagedGitHooks(projectRoot, config);
         await syncHarnessShims(projectRoot, harnesses);
+        await assertExpectedHarnessShims(projectRoot, harnesses);
         await writeCursorWorkflowRule(projectRoot, harnesses);
         await ensureGitignore(projectRoot);
         await managedSession.commit();
         await fs.unlink(sentinelPath).catch(() => undefined);
     }
     catch (error) {
-        // Leave the sentinel in place so doctor can surface the interrupted run.
+        // Leave the sentinel in place so the interrupted run is visible.
         throw error;
     }
     finally {
         setActiveManagedResourceSession(null);
     }
 }
+async function warnCodexHooksFeatureFlagIfDisabled(harnesses) {
+    if (!harnesses.includes("codex"))
+        return;
+    const codexTomlPath = codexConfigPath();
+    let existing;
+    try {
+        existing = await readCodexConfig(codexTomlPath);
+    }
+    catch (error) {
+        process.stderr.write(`cclaw: could not read ${codexTomlPath} to validate codex_hooks flag: ${error instanceof Error ? error.message : String(error)}\n`);
+        return;
+    }
+    if (classifyCodexHooksFlag(existing) === "enabled")
+        return;
+    process.stderr.write(`cclaw: Codex hooks file written, but [features] codex_hooks is not true in ${codexTomlPath} — hooks are inert until you enable it.\n`);
+}
 export async function initCclaw(options) {
     if (options.harnesses !== undefined && options.harnesses.length === 0) {
         throw new Error("Select at least one harness.");
@@ -1157,7 +1272,7 @@ export async function syncCclaw(projectRoot, options = {}) {
         // 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.
+        // codex, which then creates invalid harness expectations.
         // 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);
@@ -1177,6 +1292,7 @@ export async function syncCclaw(projectRoot, options = {}) {
         });
     }
     await materializeRuntime(projectRoot, config, false, "sync");
+    await warnCodexHooksFeatureFlagIfDisabled(config.harnesses);
 }
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
@@ -1274,20 +1390,28 @@ function isManagedRuntimeHookCommand(command) {
     // Codex UserPromptSubmit non-blocking state nudge.
     return /internal verify-current-state(?:\s|$)/u.test(normalized);
 }
-async function removeManagedHookEntries(hookFilePath) {
+async function removeManagedHookEntries(hookFilePath, options = {}) {
     if (!(await exists(hookFilePath)))
         return;
     let parsed = null;
     try {
         const raw = await fs.readFile(hookFilePath, "utf8");
         const recovered = tryParseHookDocument(raw);
-        parsed = recovered?.parsed ?? null;
+        if (recovered === null) {
+            if (options.failOnParseError === true) {
+                throw new Error(`[sync fail-fast] Cannot strip managed hook entries from ${hookFilePath} — JSON is unparseable. ` +
+                    `Run \`rm ${hookFilePath}\` and rerun \`npx cclaw-cli sync\`.`);
+            }
+            return;
+        }
+        parsed = recovered.parsed;
     }
-    catch {
+    catch (error) {
+        if (options.failOnParseError === true) {
+            throw new Error(`[sync fail-fast] Cannot strip managed hook entries from ${hookFilePath} — ${error instanceof Error ? error.message : String(error)}. Run \`rm ${hookFilePath}\` and rerun \`npx cclaw-cli sync\`.`);
+        }
         return;
     }
-    if (parsed === null)
-        return;
     const { updated, changed } = stripManagedHookCommands(parsed);
     if (!changed)
         return;
@@ -1369,7 +1493,7 @@ export async function uninstallCclaw(projectRoot) {
     try {
         const entries = await fs.readdir(codexSkillsRoot);
         for (const entry of entries) {
-            if (/^(?:cclaw-)?cc(?:-(?:next|view|finish|cancel|ops|ideate|brainstorm|scope|design|spec|plan|tdd|review|ship))?$/u.test(entry)) {
+            if (/^(?:cclaw-)?cc(?:-(?:next|view|finish|cancel|ops|idea|brainstorm|scope|design|spec|plan|tdd|review|ship))?$/u.test(entry)) {
                 await fs.rm(path.join(codexSkillsRoot, entry), { recursive: true, force: true });
             }
         }

package/dist/internal/advance-stage/advance.d.ts

@@ -0,0 +1,50 @@
+import { type FlowState } from "../../flow-state.js";
+import { type FlowStage } from "../../types.js";
+import type { AdvanceStageArgs } from "./parsers.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+interface InternalValidationReport {
+    ok: boolean;
+    stage: FlowStage;
+    delegation: {
+        satisfied: boolean;
+        missing: string[];
+        waived: string[];
+        missingEvidence: string[];
+        missingDispatchProof: string[];
+        legacyInferredCompletions: string[];
+        corruptEventLines: number[];
+        staleWorkers: string[];
+        expectedMode: string;
+    };
+    gates: {
+        ok: boolean;
+        complete: boolean;
+        issues: string[];
+        missingRequired: string[];
+        missingTriggeredConditional: string[];
+    };
+    completedStages: {
+        ok: boolean;
+        issues: string[];
+    };
+}
+export declare function hydrateReviewLoopEvidenceFromArtifact(projectRoot: string, stage: FlowStage, track: FlowState["track"], selectedGateIds: string[], evidenceByGate: Record<string, string>): Promise<void>;
+export declare function buildValidationReport(projectRoot: string, flowState: FlowState, options?: {
+    allowBlockedReviewRoute?: boolean;
+}): Promise<InternalValidationReport>;
+interface HarvestLearningsResult {
+    ok: boolean;
+    markerWritten: boolean;
+    parsedEntries: number;
+    appendedEntries: number;
+    skippedDuplicates: number;
+    details: string;
+}
+export declare function withLearningsHarvestMarker(artifactMarkdown: string, appendedEntries: number, skippedDuplicates: number): string;
+export declare function harvestStageLearnings(projectRoot: string, stage: FlowStage, track: FlowState["track"]): Promise<HarvestLearningsResult>;
+export declare function runAdvanceStage(projectRoot: string, args: AdvanceStageArgs, io: InternalIo): Promise<number>;
+export {};