cclaw-cli 0.47.0 → 0.48.1

package/dist/doctor.js

@@ -3,16 +3,16 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
-import { COMMAND_FILE_ORDER, 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 { readConfig } from "./config.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 { TRACK_STAGES } from "./types.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 { buildTraceMatrix } from "./trace-matrix.js";
@@ -280,7 +280,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: fullPath
         });
     }
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const commandPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${stage}.md`);
         checks.push({
             name: `command:${stage}`,
@@ -377,7 +377,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     // skill's Examples section points here; the file MUST exist or the pointer
     // is a dangling link.
     const stageRefDir = path.join(projectRoot, RUNTIME_ROOT, "references", "stages");
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const refPath = path.join(stageRefDir, `${stage}-examples.md`);
         checks.push({
             name: `stage_examples_ref:${stage}`,
@@ -430,6 +430,18 @@ export async function doctorChecks(projectRoot, options = {}) {
         });
     }
     if (parsedConfig) {
+        const advancedKeys = await detectAdvancedKeys(projectRoot).catch(() => new Set());
+        const hasLegacyTddTestGlobs = advancedKeys.has("tddTestGlobs");
+        const hasModernTddConfig = advancedKeys.has("tdd");
+        checks.push({
+            name: "warning:config:deprecated_tdd_test_globs",
+            ok: !hasLegacyTddTestGlobs,
+            details: hasLegacyTddTestGlobs
+                ? hasModernTddConfig
+                    ? `warning: ${RUNTIME_ROOT}/config.yaml sets deprecated "tddTestGlobs" alongside "tdd.*"; "tdd.testPathPatterns" takes precedence. Remove legacy key.`
+                    : `warning: ${RUNTIME_ROOT}/config.yaml uses deprecated "tddTestGlobs". Migrate to "tdd.testPathPatterns".`
+                : `no deprecated "tddTestGlobs" key detected in ${RUNTIME_ROOT}/config.yaml`
+        });
         const expectedMode = parsedConfig.promptGuardMode === "strict" ? "strict" : "advisory";
         const promptGuardPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", "prompt-guard.sh");
         let promptGuardModeOk = false;
@@ -535,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}`,
@@ -803,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
@@ -1191,6 +1203,62 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "harness-gaps.json")),
         details: `${RUNTIME_ROOT}/state/harness-gaps.json must exist for tiered harness capability tracking`
     });
+    const adapterManifestPath = path.join(projectRoot, RUNTIME_ROOT, "adapters", "manifest.json");
+    const adapterManifestExists = await exists(adapterManifestPath);
+    checks.push({
+        name: "state:adapter_manifest_exists",
+        ok: adapterManifestExists,
+        details: `${RUNTIME_ROOT}/adapters/manifest.json must exist for harness adapter provenance`
+    });
+    if (adapterManifestExists) {
+        let harnessesOk = false;
+        let harnessesDetails = "";
+        let sourcesOk = false;
+        let sourcesDetails = "";
+        try {
+            const parsed = JSON.parse(await fs.readFile(adapterManifestPath, "utf8"));
+            const manifestHarnesses = Array.isArray(parsed.harnesses)
+                ? parsed.harnesses.filter((entry) => typeof entry === "string")
+                : [];
+            const expectedHarnesses = configuredHarnesses.length > 0
+                ? [...new Set(configuredHarnesses)].sort()
+                : null;
+            const actualHarnesses = [...new Set(manifestHarnesses)].sort();
+            harnessesOk = expectedHarnesses
+                ? actualHarnesses.length === expectedHarnesses.length &&
+                    actualHarnesses.every((harness, index) => harness === expectedHarnesses[index])
+                : actualHarnesses.length > 0;
+            harnessesDetails = expectedHarnesses
+                ? harnessesOk
+                    ? `adapter manifest harnesses match config.yaml: ${actualHarnesses.join(", ")}`
+                    : `adapter manifest harnesses [${actualHarnesses.join(", ")}] do not match config.yaml [${expectedHarnesses.join(", ")}]`
+                : harnessesOk
+                    ? `adapter manifest declares harnesses: ${actualHarnesses.join(", ")}`
+                    : "adapter manifest must declare at least one harness";
+            const commandSource = typeof parsed.commandSource === "string" ? parsed.commandSource.trim() : "";
+            const skillSource = typeof parsed.skillSource === "string" ? parsed.skillSource.trim() : "";
+            sourcesOk = commandSource.length > 0 && skillSource.length > 0;
+            sourcesDetails = sourcesOk
+                ? `adapter manifest source globs are set (commandSource=${commandSource}; skillSource=${skillSource})`
+                : "adapter manifest must include non-empty commandSource and skillSource";
+        }
+        catch {
+            harnessesOk = false;
+            harnessesDetails = "adapter manifest must be valid JSON with a harnesses array";
+            sourcesOk = false;
+            sourcesDetails = "adapter manifest must be valid JSON with source globs";
+        }
+        checks.push({
+            name: "state:adapter_manifest_harnesses",
+            ok: harnessesOk,
+            details: harnessesDetails
+        });
+        checks.push({
+            name: "state:adapter_manifest_sources",
+            ok: sourcesOk,
+            details: sourcesDetails
+        });
+    }
     const contextModeStatePath = path.join(projectRoot, RUNTIME_ROOT, "state", "context-mode.json");
     checks.push({
         name: "state:context_mode_exists",
@@ -1276,7 +1344,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         name: "flow_state:track",
         ok: skippedConsistent,
         details: skippedConsistent
-            ? `active track "${activeTrack}" (${trackStageList.length}/${COMMAND_FILE_ORDER.length} stages: ${trackStageList.join(" → ")})${expectedSkipped.length > 0 ? `; skippedStages=${expectedSkipped.join(", ")}` : ""}`
+            ? `active track "${activeTrack}" (${trackStageList.length}/${FLOW_STAGES.length} stages: ${trackStageList.join(" → ")})${expectedSkipped.length > 0 ? `; skippedStages=${expectedSkipped.join(", ")}` : ""}`
             : `track "${activeTrack}" expects skippedStages=[${expectedSkipped.join(", ")}] but flow-state has [${skippedFromState.join(", ")}] — run \`cclaw sync\` to repair`
     });
     if (parsedConfig?.trackHeuristics) {
@@ -1441,7 +1509,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no legacy .cclaw/features snapshot entries remain"
             : `legacy snapshot entries still present (read-only): ${legacyWorkspaceEntries.join(", ")}`
     });
-    const staleStages = Object.keys(flowState.staleStages).filter((value) => COMMAND_FILE_ORDER.includes(value));
+    const staleStages = Object.keys(flowState.staleStages).filter((value) => FLOW_STAGES.includes(value));
     checks.push({
         name: "state:stale_stages_resolved",
         ok: staleStages.length === 0,
@@ -1667,10 +1735,10 @@ export async function doctorChecks(projectRoot, options = {}) {
             const stageOrder = parsed.stage_order;
             const stageGates = parsed.stage_gates;
             const hasStageOrder = Array.isArray(stageOrder) &&
-                COMMAND_FILE_ORDER.every((stage) => stageOrder.includes(stage));
+                FLOW_STAGES.every((stage) => stageOrder.includes(stage));
             const hasStageGates = typeof stageGates === "object" &&
                 stageGates !== null &&
-                COMMAND_FILE_ORDER.every((stage) => Array.isArray(stageGates[stage]));
+                FLOW_STAGES.every((stage) => Array.isArray(stageGates[stage]));
             hasRules = hasCoreLists && hasStageOrder && hasStageGates;
         }
         catch {

package/dist/flow-state.d.ts

@@ -43,6 +43,14 @@ export interface RetroState {
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
  *   resets flow-state so this value does not persist between runs).
+ *
+ * Layer separation (intentional):
+ * - `next: "done"` in stage schema means "the flow stage chain ended".
+ * - `shipSubstate: "archived"` is closeout-machine progress after ship.
+ * - `shipSubstate: "idle"` is the default closeout value before ship.
+ *
+ * These are not duplicates: `done` lives in stage transitions; `archived` /
+ * `idle` live in closeout lifecycle state.
  */
 export declare const SHIP_SUBSTATES: readonly ["idle", "retro_review", "compound_review", "ready_to_archive", "archived"];
 export type ShipSubstate = (typeof SHIP_SUBSTATES)[number];
@@ -86,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

@@ -1,4 +1,3 @@
-import { COMMAND_FILE_ORDER } from "./constants.js";
 import { buildTransitionRules, orderedStageSchemas, stageGateIds, stageRecommendedGateIds } from "./content/stage-schema.js";
 import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
@@ -17,6 +16,14 @@ export const TRANSITION_RULES = buildTransitionRules();
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
  *   resets flow-state so this value does not persist between runs).
+ *
+ * Layer separation (intentional):
+ * - `next: "done"` in stage schema means "the flow stage chain ended".
+ * - `shipSubstate: "archived"` is closeout-machine progress after ship.
+ * - `shipSubstate: "idle"` is the default closeout value before ship.
+ *
+ * These are not duplicates: `done` lives in stage transitions; `archived` /
+ * `idle` live in closeout lifecycle state.
  */
 export const SHIP_SUBSTATES = [
     "idle",
@@ -90,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] : [];
 }
@@ -98,11 +119,7 @@ export function nextStage(stage, track = "standard") {
     const ordered = TRACK_STAGES[track];
     const index = ordered.indexOf(stage);
     if (index < 0) {
-        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
-        if (fallback < 0 || fallback === COMMAND_FILE_ORDER.length - 1) {
-            return null;
-        }
-        return COMMAND_FILE_ORDER[fallback + 1];
+        return null;
     }
     if (index === ordered.length - 1) {
         return null;
@@ -116,11 +133,11 @@ export function previousStage(stage, track = "standard") {
         return null;
     }
     if (index < 0) {
-        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
+        const fallback = FLOW_STAGES.indexOf(stage);
         if (fallback <= 0) {
             return null;
         }
-        return COMMAND_FILE_ORDER[fallback - 1];
+        return FLOW_STAGES[fallback - 1];
     }
     return ordered[index - 1];
 }

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

@@ -1,9 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { checkReviewSecurityNoChangeAttestation, checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
+import { readDelegationLedger } from "./delegation.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
 import { readFlowState, writeFlowState } from "./runs.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { FLOW_STAGES } from "./types.js";
@@ -210,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)
@@ -228,6 +230,10 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             if (!verdictConsistency.ok) {
                 issues.push(`review verdict inconsistency: ${verdictConsistency.errors.join("; ")}`);
             }
+            const securityAttestation = await checkReviewSecurityNoChangeAttestation(projectRoot);
+            if (!securityAttestation.ok) {
+                issues.push(`review security attestation failed: ${securityAttestation.errors.join("; ")}`);
+            }
             const traceGateRequired = schema.requiredGates.some((gate) => gate.id === "review_trace_matrix_clean" && gate.tier === "required");
             if (traceGateRequired) {
                 const trace = await buildTraceMatrix(projectRoot);
@@ -282,6 +288,19 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                 }
             }
         }
+        if (stage === "tdd") {
+            const docsDriftDetection = await detectPublicApiChanges(projectRoot);
+            if (docsDriftDetection.triggered) {
+                const ledger = await readDelegationLedger(projectRoot);
+                const hasDocUpdaterCompletion = ledger.entries.some((entry) => entry.runId === flowState.activeRunId &&
+                    entry.stage === "tdd" &&
+                    entry.agent === "doc-updater" &&
+                    entry.status === "completed");
+                if (!hasDocUpdaterCompletion) {
+                    issues.push(`tdd docs drift gate blocked (tdd_docs_drift_check): public surface changes detected (${docsDriftDetection.changedFiles.join(", ")}) but no completed doc-updater delegation exists for the active run.`);
+                }
+            }
+        }
     }
     const passedSet = new Set(catalog.passed);
     const missingRequired = required.filter((gateId) => !passedSet.has(gateId));

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.d.ts

@@ -17,8 +17,8 @@ export type SubagentFallback =
  */
  | "role-switch"
 /**
- * No meaningful fallback — mandatory delegations can only be waived
- * under `waiverReason: "harness_limitation"`.
+ * Reserved escape hatch for future harnesses with no parity path.
+ * Current shipped harnesses do not use this fallback.
  */
  | "waiver";
 /**

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
@@ -222,7 +227,7 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 |---|---|
 | \`/cc\` | **Entry point.** No args = resume current stage. With prompt = classify task and start the right flow. |
 | \`/cc-next\` | **Progression.** Advances to the next stage when current is complete. |
-| \`/cc-ideate\` | **Discovery mode.** Generates a ranked repo-improvement backlog before implementation. |
+| \`/cc-ideate\` | **Ideate mode.** Generates a ranked repo-improvement backlog before implementation. |
 | \`/cc-view\` | **Read-only router.** Unified entry for status/tree/diff views. |
 | \`/cc-ops\` | **Operations router.** Unified entry for feature/tdd-log/retro/compound/archive/rewind actions. |
 
@@ -356,7 +361,7 @@ function codexSkillDescription(command) {
         case "next":
             return `Advance the cclaw flow to the next stage. Use when the user types \`/cc-next\` or asks to "move to the next stage", "continue the flow", "advance cclaw", "progress the workflow", or when the current stage skill reports completion and gates have passed.`;
         case "ideate":
-            return `Read-only repo-improvement discovery for cclaw. Use when the user types \`/cc-ideate\` or asks to "ideate", "brainstorm improvements", "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\`.`;
+            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 "view":
             return `Read-only router for cclaw flow views. Use when the user types \`/cc-view\`, \`/cc-view status\`, \`/cc-view tree\`, \`/cc-view diff\`, or asks to "show cclaw status", "show the flow tree", "diff flow state", or wants a snapshot without mutation.`;
         case "ops":
@@ -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

@@ -2,9 +2,9 @@ import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
-import { CCLAW_VERSION, COMMAND_FILE_ORDER, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
+import { CCLAW_VERSION, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { writeConfig, createDefaultConfig, readConfig, configPath, detectLanguageRulePacks, detectAdvancedKeys } from "./config.js";
-import { commandContract } from "./content/contracts.js";
+import { stageCommandContract } from "./content/contracts.js";
 import { contextModeFiles, createInitialContextModeState } from "./content/contexts.js";
 import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js";
 import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
@@ -36,7 +36,7 @@ import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LANGUAGE_RULE_PACK_GE
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { HARNESS_TOOL_REFS_DIR, HARNESS_TOOL_REFS_INDEX_MD, harnessToolRefMarkdown } from "./content/harness-tool-refs.js";
 import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
-import { harnessDocsOverviewMarkdown, harnessIntegrationDocMarkdown } from "./content/harnesses-doc.js";
+import { harnessDocsOverviewMarkdown, harnessIntegrationDocMarkdown } from "./content/harness-doc.js";
 import { HARNESS_PLAYBOOKS_DIR, harnessPlaybookFileName, harnessPlaybookMarkdown, harnessPlaybooksIndexMarkdown } from "./content/harness-playbooks.js";
 import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./content/hook-events.js";
 import { createInitialFlowState } from "./flow-state.js";
@@ -44,7 +44,9 @@ 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";
 const GIT_HOOK_MANAGED_MARKER = "cclaw-managed-git-hook";
@@ -177,8 +179,8 @@ async function ensureStructure(projectRoot) {
     }
 }
 async function writeCommandContracts(projectRoot) {
-    for (const stage of COMMAND_FILE_ORDER) {
-        await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), commandContract(stage));
+    for (const stage of FLOW_STAGES) {
+        await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), stageCommandContract(stage));
     }
 }
 async function writeArtifactTemplates(projectRoot) {
@@ -214,7 +216,7 @@ async function writeEvalScaffold(projectRoot) {
 }
 async function writeSkills(projectRoot, config) {
     const skillTrack = config?.defaultTrack ?? "standard";
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const folder = stageSkillFolder(stage);
         await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), stageSkillMarkdown(stage, skillTrack));
         // Progressive disclosure (A.2#8): materialize the full example artifact as
@@ -852,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, "");
@@ -1020,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 {
@@ -1114,6 +1141,27 @@ async function cleanLegacyArtifacts(projectRoot) {
             // best-effort cleanup
         }
     }
+    // D-4 terminology migration: rename historical ideation artifacts to the
+    // canonical ideate-* naming without deleting user-authored content.
+    const artifactsDir = runtimePath(projectRoot, "artifacts");
+    try {
+        const entries = await fs.readdir(artifactsDir);
+        for (const entry of entries) {
+            const match = /^ideation-(.+\.md)$/u.exec(entry);
+            if (!match)
+                continue;
+            const nextName = `ideate-${match[1]}`;
+            const from = path.join(artifactsDir, entry);
+            const to = path.join(artifactsDir, nextName);
+            if (await exists(to)) {
+                continue;
+            }
+            await fs.rename(from, to);
+        }
+    }
+    catch {
+        // no artifacts directory yet (fresh init) or read-only FS
+    }
 }
 async function cleanStaleFiles(projectRoot) {
     const expectedShimFiles = new Set(harnessShimFileNames());
@@ -1188,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/internal/detect-public-api-changes.d.ts

@@ -0,0 +1,5 @@
+export interface PublicApiChangeDetection {
+    triggered: boolean;
+    changedFiles: string[];
+}
+export declare function detectPublicApiChanges(projectRoot: string): Promise<PublicApiChangeDetection>;