cclaw-cli 1.0.0 → 2.0.0

package/dist/artifact-linter/brainstorm.js

@@ -1,8 +1,22 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { checkCriticPredictionsContract, sectionBodyByName, validateApproachesTaxonomy, headingLineIndex, meaningfulLineCount, parseShortCircuitStatus, validateCalibratedSelfReview, markdownFieldRegex } from "./shared.js";
+import { checkCriticPredictionsContract, sectionBodyByName, validateApproachesTaxonomy, headingLineIndex, meaningfulLineCount, getMarkdownTableRows, parseShortCircuitStatus, validateCalibratedSelfReview, markdownFieldRegex } from "./shared.js";
 export async function lintBrainstormStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
+    const qaLogBody = sectionBodyByName(sections, "Q&A Log");
+    const qaLogRows = qaLogBody ? getMarkdownTableRows(qaLogBody) : [];
+    const qaLogOk = qaLogBody !== null && qaLogRows.length > 0;
+    findings.push({
+        section: "qa_log_missing",
+        required: false,
+        rule: "[P3] qa_log_missing — Q&A Log empty — confirm you actually had a dialogue with the user, not a draft from memory.",
+        found: qaLogOk,
+        details: qaLogOk
+            ? `Q&A Log contains ${qaLogRows.length} data row(s).`
+            : qaLogBody === null
+                ? "Missing `## Q&A Log` section."
+                : "Q&A Log is present but has zero data rows."
+    });
     // Brainstorm Iron Law: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY
     // APPROVED DIRECTION — SILENCE IS NOT APPROVAL." Previously this was
     // prose-only — nothing failed when the Selected Direction section

package/dist/artifact-linter/design.js

@@ -204,6 +204,20 @@ async function runStaleDiagramAudit(projectRoot, artifactPath, artifactRaw, code
 }
 export async function lintDesignStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
+    const qaLogBody = sectionBodyByName(sections, "Q&A Log");
+    const qaLogRows = qaLogBody ? getMarkdownTableRows(qaLogBody) : [];
+    const qaLogOk = qaLogBody !== null && qaLogRows.length > 0;
+    findings.push({
+        section: "qa_log_missing",
+        required: false,
+        rule: "[P3] qa_log_missing — Q&A Log empty — confirm you actually had a dialogue with the user, not a draft from memory.",
+        found: qaLogOk,
+        details: qaLogOk
+            ? `Q&A Log contains ${qaLogRows.length} data row(s).`
+            : qaLogBody === null
+                ? "Missing `## Q&A Log` section."
+                : "Q&A Log is present but has zero data rows."
+    });
     const criticPredictions = checkCriticPredictionsContract(sections);
     if (criticPredictions !== null) {
         findings.push({

package/dist/artifact-linter/scope.js

@@ -12,6 +12,20 @@ export async function lintScopeStage(ctx) {
         sectionBodyByName(sections, "Scope Summary") ?? "",
         lockedDecisionsBody
     ].join("\n");
+    const qaLogBody = sectionBodyByName(sections, "Q&A Log");
+    const qaLogRows = qaLogBody ? getMarkdownTableRows(qaLogBody) : [];
+    const qaLogOk = qaLogBody !== null && qaLogRows.length > 0;
+    findings.push({
+        section: "qa_log_missing",
+        required: false,
+        rule: "[P3] qa_log_missing — Q&A Log empty — confirm you actually had a dialogue with the user, not a draft from memory.",
+        found: qaLogOk,
+        details: qaLogOk
+            ? `Q&A Log contains ${qaLogRows.length} data row(s).`
+            : qaLogBody === null
+                ? "Missing `## Q&A Log` section."
+                : "Q&A Log is present but has zero data rows."
+    });
     const strategistRequired = selectedScopeMode === "SCOPE EXPANSION" || selectedScopeMode === "SELECTIVE EXPANSION";
     if (strategistRequired) {
         const delegationLedger = await readDelegationLedger(projectRoot);

package/dist/artifact-linter/shared.d.ts

@@ -26,6 +26,7 @@ export type H2SectionMap = Map<string, string>;
  *   into multiple passes.
  */
 export declare function extractH2Sections(markdown: string): H2SectionMap;
+export declare function duplicateH2Headings(markdown: string): string[];
 export declare function headingPresent(sections: H2SectionMap, section: string): boolean;
 export declare function sectionBodyByName(sections: H2SectionMap, section: string): string | null;
 export declare function sectionBodyByAnyName(sections: H2SectionMap, sectionNames: string[]): string | null;

package/dist/artifact-linter/shared.js

@@ -57,6 +57,38 @@ export function extractH2Sections(markdown) {
     flush();
     return sections;
 }
+export function duplicateH2Headings(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    let fenced = null;
+    const counts = new Map();
+    const displayHeading = new Map();
+    for (const line of lines) {
+        const fenceMatch = /^(```|~~~)/u.exec(line);
+        if (fenceMatch) {
+            if (fenced === null) {
+                fenced = fenceMatch[1] ?? null;
+            }
+            else if (line.startsWith(fenced)) {
+                fenced = null;
+            }
+            continue;
+        }
+        if (fenced !== null)
+            continue;
+        const match = /^##\s+(.+)$/u.exec(line);
+        if (!match)
+            continue;
+        const heading = normalizeHeadingTitle(match[1] ?? "");
+        const key = heading.toLowerCase();
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+        if (!displayHeading.has(key)) {
+            displayHeading.set(key, heading);
+        }
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([key]) => displayHeading.get(key) ?? key);
+}
 export function headingPresent(sections, section) {
     const want = normalizeHeadingTitle(section).toLowerCase();
     for (const h of sections.keys()) {

package/dist/artifact-linter.js

@@ -3,7 +3,7 @@ import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-path
 import { readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
-import { extractH2Sections, extractLockedDecisionAnchors, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody } from "./artifact-linter/shared.js";
+import { duplicateH2Headings, extractH2Sections, extractLockedDecisionAnchors, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody } from "./artifact-linter/shared.js";
 import { lintBrainstormStage } from "./artifact-linter/brainstorm.js";
 import { lintDesignStage } from "./artifact-linter/design.js";
 import { lintPlanStage } from "./artifact-linter/plan.js";
@@ -48,6 +48,16 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
     }
     const raw = await fs.readFile(absFile, "utf8");
     const sections = extractH2Sections(raw);
+    const duplicateHeadings = duplicateH2Headings(raw);
+    if (duplicateHeadings.length > 0) {
+        findings.push({
+            section: "duplicate_h2_heading",
+            required: false,
+            rule: "[P3] keep each `##` heading unique within an artifact; append updates to the existing section instead of cloning headings.",
+            found: false,
+            details: `Duplicate H2 heading(s): ${duplicateHeadings.join(", ")}. Merge edits into the existing heading to avoid split contracts.`
+        });
+    }
     const projectConfig = await readConfig(projectRoot);
     const parsedFrontmatter = parseFrontmatter(raw);
     const frontmatterMissingKeys = FRONTMATTER_REQUIRED_KEYS.filter((key) => {

package/dist/content/hook-events.js

@@ -11,8 +11,7 @@ const OPENCODE_SEMANTIC_COVERAGE = {
     pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
     pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
     post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
-    stop_handoff: "plugin session.idle -> stop-handoff",
-    precompact_compat: "plugin session.compacted -> pre-compact"
+    stop_handoff: "plugin session.idle -> stop-handoff"
 };
 /**
  * Public semantic coverage map derived from `HOOK_MANIFEST` for

package/dist/content/hook-manifest.d.ts

@@ -21,7 +21,7 @@
  */
 export declare const HOOK_MANIFEST_HARNESSES: readonly ["claude", "cursor", "codex"];
 export type HookManifestHarness = (typeof HOOK_MANIFEST_HARNESSES)[number];
-export declare const HOOK_HANDLERS: readonly ["session-start", "prompt-guard", "workflow-guard", "context-monitor", "stop-handoff", "pre-compact", "verify-current-state"];
+export declare const HOOK_HANDLERS: readonly ["session-start", "prompt-guard", "workflow-guard", "pre-tool-pipeline", "prompt-pipeline", "context-monitor", "stop-handoff", "verify-current-state"];
 export type HookHandlerId = (typeof HOOK_HANDLERS)[number];
 export interface HookBinding {
     /**
@@ -35,8 +35,7 @@ export interface HookBinding {
      * Within a single (harness, event) group, entries are sorted by
      * `priority` ASC, ties broken by manifest-declaration order. Use
      * this to express "this handler must run BEFORE/AFTER that handler
-     * on the same event" (e.g. pre-compact must run before session-start
-     * on cursor `sessionCompact`). Default `0`.
+     * on the same event". Default `0`.
      */
     priority?: number;
 }
@@ -50,7 +49,7 @@ export interface HookHandlerSpec {
     semantic: HookSemanticEvent | null;
     bindings: Partial<Record<HookManifestHarness, HookBinding[]>>;
 }
-export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_handoff", "precompact_compat", "strict_state_verify"];
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_handoff", "strict_state_verify"];
 export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
 export declare const HOOK_MANIFEST: readonly HookHandlerSpec[];
 export interface EventGroup {

package/dist/content/hook-manifest.js

@@ -24,9 +24,10 @@ export const HOOK_HANDLERS = [
     "session-start",
     "prompt-guard",
     "workflow-guard",
+    "pre-tool-pipeline",
+    "prompt-pipeline",
     "context-monitor",
     "stop-handoff",
-    "pre-compact",
     "verify-current-state"
 ];
 export const HOOK_SEMANTIC_EVENTS = [
@@ -35,7 +36,6 @@ export const HOOK_SEMANTIC_EVENTS = [
     "pre_tool_workflow_guard",
     "post_tool_context_monitor",
     "stop_handoff",
-    "precompact_compat",
     "strict_state_verify"
 ];
 export const HOOK_MANIFEST = [
@@ -59,12 +59,7 @@ export const HOOK_MANIFEST = [
         description: "Stage-aware prompt gate (iron-laws + strictness).",
         semantic: "pre_tool_prompt_guard",
         bindings: {
-            claude: [{ event: "PreToolUse", matcher: "*" }],
-            cursor: [{ event: "preToolUse", matcher: "*" }],
-            codex: [
-                { event: "UserPromptSubmit" },
-                { event: "PreToolUse", matcher: "Bash|bash" }
-            ]
+            claude: [{ event: "PreToolUse", matcher: "*" }]
         }
     },
     {
@@ -72,11 +67,26 @@ export const HOOK_MANIFEST = [
         description: "TDD and workflow gate on Write/Edit/Bash style tool invocations.",
         semantic: "pre_tool_workflow_guard",
         bindings: {
-            claude: [{ event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash" }],
+            claude: [{ event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash" }]
+        }
+    },
+    {
+        handler: "pre-tool-pipeline",
+        description: "In-process pre-tool pipeline for harnesses that would otherwise spawn prompt/workflow guards separately.",
+        semantic: null,
+        bindings: {
             cursor: [{ event: "preToolUse", matcher: "*" }],
             codex: [{ event: "PreToolUse", matcher: "Bash|bash" }]
         }
     },
+    {
+        handler: "prompt-pipeline",
+        description: "In-process prompt pipeline for Codex UserPromptSubmit (prompt-guard + verify-current-state).",
+        semantic: "strict_state_verify",
+        bindings: {
+            codex: [{ event: "UserPromptSubmit" }]
+        }
+    },
     {
         handler: "context-monitor",
         description: "Post-tool context usage + stage signal monitor.",
@@ -97,24 +107,11 @@ export const HOOK_MANIFEST = [
             codex: [{ event: "Stop", timeout: 10 }]
         }
     },
-    {
-        handler: "pre-compact",
-        description: "No-op compatibility hook for harness pre-compact events; session-start rehydrates from flow-state, artifacts, and knowledge.",
-        semantic: "precompact_compat",
-        bindings: {
-            claude: [{ event: "PreCompact", matcher: "manual|auto", timeout: 10 }],
-            // Keep this before session-start on cursor `sessionCompact` so the
-            // compatibility handler runs before rehydration.
-            cursor: [{ event: "sessionCompact", priority: -10 }]
-        }
-    },
     {
         handler: "verify-current-state",
-        description: "Supplementary Codex strict-mode guard that runs on UserPromptSubmit to assert the live state matches the flow.",
-        semantic: "strict_state_verify",
-        bindings: {
-            codex: [{ event: "UserPromptSubmit" }]
-        }
+        description: "Supplementary strict-mode guard callable from in-process pipelines to assert live state matches flow.",
+        semantic: null,
+        bindings: {}
     }
 ];
 /** Sanity: every harness in HOOK_MANIFEST_HARNESSES must be a HarnessId. */

package/dist/content/hooks.js

@@ -5,6 +5,15 @@ import { RUNTIME_ROOT } from "../constants.js";
 import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES } from "../delegation.js";
 function resolveCliRuntimeForGeneratedHook() {
     const here = fileURLToPath(import.meta.url);
+    // Vitest runs init/sync from src/ and expects helpers to execute the same
+    // source runtime, even when a stale dist/ exists in the repository.
+    if (process.env.VITEST === "true") {
+        const sourceCli = path.resolve(path.dirname(here), "..", "cli.ts");
+        const viteNode = path.resolve(path.dirname(here), "..", "..", "node_modules", "vite-node", "vite-node.mjs");
+        if (existsSync(sourceCli) && existsSync(viteNode)) {
+            return { entrypoint: viteNode, argsPrefix: ["--script", sourceCli] };
+        }
+    }
     const candidates = [
         path.resolve(path.dirname(here), "..", "cli.js"),
         path.resolve(path.dirname(here), "..", "..", "dist", "cli.js")
@@ -15,15 +24,6 @@ function resolveCliRuntimeForGeneratedHook() {
         if (existsSync(candidate))
             return { entrypoint: candidate, argsPrefix: [] };
     }
-    // Vitest exercises init/sync directly from src/ without a compiled dist/.
-    // Route that dev-only shape through vite-node so hooks still prove a local runtime.
-    if (process.env.VITEST === "true") {
-        const sourceCli = path.resolve(path.dirname(here), "..", "cli.ts");
-        const viteNode = path.resolve(path.dirname(here), "..", "..", "node_modules", "vite-node", "vite-node.mjs");
-        if (existsSync(sourceCli) && existsSync(viteNode)) {
-            return { entrypoint: viteNode, argsPrefix: ["--script", sourceCli] };
-        }
-    }
     return { entrypoint: null, argsPrefix: [] };
 }
 function internalHelperScript(helperName, internalSubcommand, usage, options) {
@@ -42,6 +42,7 @@ const INTERNAL_SUBCOMMAND = ${JSON.stringify(internalSubcommand)};
 const USAGE = ${JSON.stringify(usage)};
 const POSITIONAL_ARG_NAME = ${JSON.stringify(options?.positionalArgName ?? null)};
 const POSITIONAL_ARG_REQUIRED = ${JSON.stringify(options?.positionalArgRequired === true)};
+const DEFAULT_QUIET_ENV_VAR = ${JSON.stringify(options?.defaultQuietEnvVar ?? null)};
 
 async function detectRoot() {
   const candidates = [
@@ -88,6 +89,19 @@ async function main() {
     }
   }
 
+  if (DEFAULT_QUIET_ENV_VAR !== null) {
+    const envRaw = process.env[DEFAULT_QUIET_ENV_VAR];
+    if (typeof envRaw !== "string" || envRaw.trim().length === 0) {
+      process.env[DEFAULT_QUIET_ENV_VAR] = "1";
+    }
+    const quietRaw = (process.env[DEFAULT_QUIET_ENV_VAR] ?? "").trim().toLowerCase();
+    const quietEnabled = !/^(0|false|no|off)$/u.test(quietRaw);
+    const alreadyQuiet = flags.includes("--quiet");
+    if (quietEnabled && !alreadyQuiet) {
+      flags = [...flags, "--quiet"];
+    }
+  }
+
   const root = await detectRoot();
   const runtimePath = path.join(root, RUNTIME_ROOT);
   try {
@@ -171,13 +185,13 @@ void main();
 `;
 }
 export function startFlowScript() {
-    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]");
+    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]", { defaultQuietEnvVar: "CCLAW_START_FLOW_QUIET" });
 }
 export function cancelRunScript() {
     return internalHelperScript("cancel-run", "cancel-run", "Usage: node " + RUNTIME_ROOT + "/hooks/cancel-run.mjs --reason=<text> [--disposition=<cancelled|abandoned>] [--name=<slug>]");
 }
 export function stageCompleteScript() {
-    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=...] [--json]", {
+    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=...] [--skip-questions] [--json]", {
         positionalArgName: "stage",
         positionalArgRequired: true
     });
@@ -280,7 +294,7 @@ function usage() {
   process.stderr.write([
     "Usage:",
     "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--json]",
-    "  node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--completed-ts=<iso>] [--json]",
+    "  node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--json]",
     "",
     "Allowed --dispatch-surface values:",
     "  " + VALID_DISPATCH_SURFACES.join(", "),
@@ -322,6 +336,18 @@ async function pathExists(filePath) {
   }
 }
 
+function normalizeEvidenceRefs(args) {
+  if (Array.isArray(args["evidence-refs"])) {
+    return args["evidence-refs"]
+      .filter((ref) => typeof ref === "string" && ref.trim().length > 0)
+      .map((ref) => ref.trim());
+  }
+  if (typeof args["evidence-ref"] === "string" && args["evidence-ref"].trim().length > 0) {
+    return [args["evidence-ref"].trim()];
+  }
+  return [];
+}
+
 function buildRow(args, status, runId, now) {
   const fulfillmentMode = args["dispatch-surface"] === "role-switch"
     ? "role-switch"
@@ -340,7 +366,7 @@ function buildRow(args, status, runId, now) {
     agentDefinitionPath: args["agent-definition-path"],
     fulfillmentMode,
     waiverReason: args["waiver-reason"],
-    evidenceRefs: args["evidence-ref"] ? [args["evidence-ref"]] : [],
+    evidenceRefs: normalizeEvidenceRefs(args),
     runId,
     startTs: now,
     ts: now,
@@ -420,6 +446,18 @@ async function runRerecord(args, json) {
     emitProblems(["no legacy ledger entry found for --span-id=" + args["span-id"]], json, 1);
     return;
   }
+  const explicitEvidenceRef =
+    typeof args["evidence-ref"] === "string" && args["evidence-ref"].trim().length > 0
+      ? args["evidence-ref"].trim()
+      : "";
+  const legacyEvidenceRefs = Array.isArray(legacyEntry.evidenceRefs)
+    ? legacyEntry.evidenceRefs
+      .filter((ref) => typeof ref === "string" && ref.trim().length > 0)
+      .map((ref) => ref.trim())
+    : [];
+  const mergedEvidenceRefs = explicitEvidenceRef.length > 0
+    ? [explicitEvidenceRef]
+    : legacyEvidenceRefs;
   if (args["dispatch-surface"] !== "role-switch") {
     if (!dispatchSurfaceMatchesPath(args["dispatch-surface"], args["agent-definition-path"])) {
       const allowedPrefixes = SURFACE_PATH_PREFIXES[args["dispatch-surface"]];
@@ -445,7 +483,9 @@ async function runRerecord(args, json) {
     "agent-definition-path": args["agent-definition-path"],
     "ack-ts": args["ack-ts"] || legacyEntry.ackTs || now,
     "completed-ts": args["completed-ts"] || legacyEntry.completedTs || now,
-    "launched-ts": args["launched-ts"] || legacyEntry.launchedTs || now
+    "launched-ts": args["launched-ts"] || legacyEntry.launchedTs || now,
+    "evidence-ref": explicitEvidenceRef.length > 0 ? explicitEvidenceRef : undefined,
+    "evidence-refs": mergedEvidenceRefs
   };
   const status = "completed";
   const clean = Object.fromEntries(Object.entries(buildRow(merged, status, runId, now)).filter(([, value]) => value !== undefined));

package/dist/content/meta-skill.js

@@ -44,9 +44,10 @@ Substantive vs. non-substantive:
 - **Non-substantive** (skill load optional): one-line acknowledgement,
   clarifying a typo, confirming a prior answer, pure conversation.
 
-If the current stage is ambiguous because \`flow-state.json\` is missing
-or corrupt, stop and route through \`/cc\` before any substantive
-response.
+If \`.cclaw/state/flow-state.json\` is missing, treat it as a normal fresh-init
+state and route through \`/cc <idea>\` to start the first tracked run.
+If the file exists but is corrupt/unreadable, stop and route through \`/cc\`
+before any substantive response.
 
 ## Red Flags (stop and re-route)