@infinitedusky/indusk-mcp 1.16.0 → 1.17.0

package/dist/bin/cli.js

@@ -3,8 +3,31 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
+import { resolveProjectRoot } from "../lib/config.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
+/**
+ * Resolve the InDusk project root for commands that operate on an existing
+ * project. Walks up from cwd looking for `.indusk/config.json`. If not
+ * found, errors out — prevents accidental writes to the wrong `.claude/`
+ * when invoked from a sub-directory like `apps/indusk-mcp/`.
+ *
+ * Commands that CREATE the project root (currently only `init`) use
+ * `process.cwd()` directly — init is responsible for creating the marker.
+ */
+function rootOrExit() {
+    const cwd = process.cwd();
+    const root = resolveProjectRoot(cwd);
+    if (root === null) {
+        console.error(`Not inside an InDusk project (no .indusk/config.json found walking up from ${cwd}).\n` +
+            "Run 'indusk init' here to initialize a new project, or cd to an existing one.");
+        process.exit(1);
+    }
+    if (root !== cwd) {
+        console.info(`[indusk] Using project root: ${root}\n`);
+    }
+    return root;
+}
 const program = new Command();
 program
     .name("dev-system")
@@ -29,7 +52,7 @@ program
     .description("Update skills from package without touching project content")
     .action(async () => {
     const { update } = await import("./commands/update.js");
-    await update(process.cwd());
+    await update(rootOrExit());
 });
 const ext = program
     .command("extensions")
@@ -39,28 +62,28 @@ ext
     .description("Show all available extensions")
     .action(async () => {
     const { extensionsList } = await import("./commands/extensions.js");
-    await extensionsList(process.cwd());
+    await extensionsList(rootOrExit());
 });
 ext
     .command("status")
     .description("Show enabled extensions with health")
     .action(async () => {
     const { extensionsStatus } = await import("./commands/extensions.js");
-    await extensionsStatus(process.cwd());
+    await extensionsStatus(rootOrExit());
 });
 ext
     .command("enable <names...>")
     .description("Enable extensions")
     .action(async (names) => {
     const { extensionsEnable } = await import("./commands/extensions.js");
-    await extensionsEnable(process.cwd(), names);
+    await extensionsEnable(rootOrExit(), names);
 });
 ext
     .command("disable <names...>")
     .description("Disable extensions")
     .action(async (names) => {
     const { extensionsDisable } = await import("./commands/extensions.js");
-    await extensionsDisable(process.cwd(), names);
+    await extensionsDisable(rootOrExit(), names);
 });
 ext
     .command("add <name>")
@@ -68,35 +91,35 @@ ext
     .requiredOption("--from <source>", "Source: npm:pkg, github:user/repo, URL, or local path")
     .action(async (name, opts) => {
     const { extensionsAdd } = await import("./commands/extensions.js");
-    await extensionsAdd(process.cwd(), name, opts.from);
+    await extensionsAdd(rootOrExit(), name, opts.from);
 });
 ext
     .command("remove <names...>")
     .description("Remove extensions")
     .action(async (names) => {
     const { extensionsRemove } = await import("./commands/extensions.js");
-    await extensionsRemove(process.cwd(), names);
+    await extensionsRemove(rootOrExit(), names);
 });
 ext
     .command("update [names...]")
     .description("Update third-party extensions from their original source")
     .action(async (names) => {
     const { extensionsUpdate } = await import("./commands/extensions.js");
-    await extensionsUpdate(process.cwd(), names);
+    await extensionsUpdate(rootOrExit(), names);
 });
 ext
     .command("suggest")
     .description("Recommend extensions based on project contents")
     .action(async () => {
     const { extensionsSuggest } = await import("./commands/extensions.js");
-    await extensionsSuggest(process.cwd());
+    await extensionsSuggest(rootOrExit());
 });
 program
     .command("init-docs")
     .description("Scaffold a VitePress documentation site with Mermaid, llms.txt, and FullscreenDiagram")
     .action(async () => {
     const { initDocs } = await import("./commands/init-docs.js");
-    await initDocs(process.cwd());
+    await initDocs(rootOrExit());
 });
 program
     .command("check-gates")
@@ -105,7 +128,7 @@ program
     .option("--phase <number>", "Check a specific phase number", Number.parseInt)
     .action(async (opts) => {
     const { checkGates } = await import("./commands/check-gates.js");
-    await checkGates(process.cwd(), { file: opts.file, phase: opts.phase });
+    await checkGates(rootOrExit(), { file: opts.file, phase: opts.phase });
 });
 const infra = program
     .command("infra")
@@ -144,7 +167,7 @@ graph
     const { getLogPath } = await import("../lib/semantic-graph/paths.js");
     const { SemanticGraphClient } = await import("../lib/semantic-graph/runtime-client.js");
     const { runSync } = await import("../lib/semantic-graph/sync-engine.js");
-    const projectRoot = process.cwd();
+    const projectRoot = rootOrExit();
     const projectName = basename(projectRoot);
     const adapter = new CgcAdapter();
     const logWriter = new LogWriter(getLogPath(projectRoot));
@@ -164,7 +187,7 @@ graph
     const { getLogPath } = await import("../lib/semantic-graph/paths.js");
     const { replay } = await import("../lib/semantic-graph/replay.js");
     const { SemanticGraphClient } = await import("../lib/semantic-graph/runtime-client.js");
-    const projectRoot = process.cwd();
+    const projectRoot = rootOrExit();
     const projectName = basename(projectRoot);
     const logPath = getLogPath(projectRoot);
     const client = new SemanticGraphClient(projectName);
@@ -188,7 +211,7 @@ graph
     const { getLogPath } = await import("../lib/semantic-graph/paths.js");
     const { readAllEvents } = await import("../lib/semantic-graph/log-reader.js");
     const { SemanticGraphClient } = await import("../lib/semantic-graph/runtime-client.js");
-    const projectRoot = process.cwd();
+    const projectRoot = rootOrExit();
     const projectName = basename(projectRoot);
     const logPath = getLogPath(projectRoot);
     console.info(`Project: ${projectName}`);
@@ -223,7 +246,7 @@ program
     .description("Strip InDusk settings overlay before a PR")
     .action(async () => {
     const { stripOverlay } = await import("../lib/settings-overlay.js");
-    stripOverlay(process.cwd());
+    stripOverlay(rootOrExit());
     console.info("Stripped InDusk overlay from .claude/settings.json");
 });
 program
@@ -231,7 +254,7 @@ program
     .description("Re-apply InDusk settings overlay after a PR")
     .action(async () => {
     const { applyOverlay } = await import("../lib/settings-overlay.js");
-    applyOverlay(process.cwd());
+    applyOverlay(rootOrExit());
     console.info("Re-applied InDusk overlay to .claude/settings.json");
 });
 program
@@ -239,13 +262,14 @@ program
     .description("Install extensions (shorthand for extensions enable / add)")
     .option("--from <source>", "Source for third-party extension (npm:pkg, github:user/repo, URL, or path)")
     .action(async (names, opts) => {
+    const root = rootOrExit();
     if (opts.from) {
         const { extensionsAdd } = await import("./commands/extensions.js");
-        await extensionsAdd(process.cwd(), names[0], opts.from);
+        await extensionsAdd(root, names[0], opts.from);
     }
     else {
         const { extensionsEnable } = await import("./commands/extensions.js");
-        await extensionsEnable(process.cwd(), names);
+        await extensionsEnable(root, names);
     }
 });
 const eval_ = program.command("eval").description("Context evaluation and quality scoring");
@@ -257,7 +281,7 @@ eval_
     .option("--json", "Output as JSON")
     .action(async (opts) => {
     const { evalSummary } = await import("./commands/eval.js");
-    await evalSummary(process.cwd(), opts);
+    await evalSummary(rootOrExit(), opts);
 });
 eval_
     .command("findings")
@@ -265,21 +289,21 @@ eval_
     .option("--all", "Show all findings including fixed/ignored")
     .action(async (opts) => {
     const { evalFindings } = await import("./commands/eval.js");
-    await evalFindings(process.cwd(), opts);
+    await evalFindings(rootOrExit(), opts);
 });
 eval_
     .command("fix <key>")
     .description("Mark an eval finding as fixed")
     .action(async (key) => {
     const { evalMark } = await import("./commands/eval.js");
-    await evalMark(process.cwd(), key, "fixed");
+    await evalMark(rootOrExit(), key, "fixed");
 });
 eval_
     .command("ignore <key>")
     .description("Mark an eval finding as ignored")
     .action(async (key) => {
     const { evalMark } = await import("./commands/eval.js");
-    await evalMark(process.cwd(), key, "ignored");
+    await evalMark(rootOrExit(), key, "ignored");
 });
 eval_
     .command("baseline")
@@ -288,7 +312,7 @@ eval_
     .option("--keep", "Keep baseline worktree after eval")
     .action(async (opts) => {
     const { evalBaseline } = await import("./commands/eval.js");
-    await evalBaseline(process.cwd(), opts);
+    await evalBaseline(rootOrExit(), opts);
 });
 program
     .command("beam <file>")
@@ -299,7 +323,7 @@ program
     const { runBeam } = await import("../lib/beam/runner.js");
     const { formatBeamMarkdown, formatBeamTrace } = await import("../lib/beam/format.js");
     const result = await runBeam({
-        projectRoot: process.cwd(),
+        projectRoot: rootOrExit(),
         targetPath: file,
         trace: opts.trace ?? false,
     });

package/dist/bin/commands/extensions.js

@@ -374,7 +374,7 @@ export async function extensionsUpdate(projectRoot, names) {
             continue;
         try {
             if (!ext.manifest._source) {
-                if (names && names.includes(name)) {
+                if (names?.includes(name)) {
                     console.info(`  ${name}: built-in extension — updated via package update, not extensions update`);
                 }
                 continue;
@@ -633,7 +633,10 @@ function printMcpInstructions(name, manifest) {
     const needsAuth = server.headers && Object.keys(server.headers).length > 0;
     // Remove first, then add — ensures clean state
     try {
-        execSync(`claude mcp remove -s project ${name}`, { timeout: 10000, stdio: ["ignore", "pipe", "pipe"] });
+        execSync(`claude mcp remove -s project ${name}`, {
+            timeout: 10000,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
     }
     catch {
         // not registered yet, fine

package/dist/bin/commands/init-docs.js

@@ -24,7 +24,7 @@ export async function initDocs(projectRoot) {
         mkdirSync(join(docsDir, dir), { recursive: true });
     }
     // package.json
-    writeFileSync(join(docsDir, "package.json"), JSON.stringify({
+    writeFileSync(join(docsDir, "package.json"), `${JSON.stringify({
         name: `${projectName}-docs`,
         version: "0.1.0",
         private: true,
@@ -42,7 +42,7 @@ export async function initDocs(projectRoot) {
             "vitepress-plugin-mermaid": "^2.0.10",
             vue: "^3.4.15",
         },
-    }, null, "\t") + "\n");
+    }, null, "\t")}\n`);
     // .vitepress/config.ts
     writeFileSync(join(docsDir, "src/.vitepress/config.ts"), `import { defineConfig } from "vitepress";
 import llmstxt from "vitepress-plugin-llms";

package/dist/lib/config.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Resolve the InDusk project root by walking up from the given directory
+ * until `.indusk/config.json` is found. Returns the directory containing
+ * `.indusk/config.json`, or `null` if none is found up to the filesystem
+ * root.
+ *
+ * `.indusk/config.json` is the authoritative "this is an InDusk project"
+ * marker — created by `indusk init`, never by sub-apps that happen to
+ * have their own `.claude/` scaffolding. Walking up to find it prevents
+ * bugs like `indusk update` syncing to the wrong `.claude/` when the user
+ * runs it from a sub-directory (e.g. `apps/indusk-mcp/`).
+ *
+ * For `indusk init` itself, use the raw cwd — init creates the marker, so
+ * walk-up would either find nothing or (worse) match an ancestor project
+ * the user doesn't intend to re-init.
+ */
+export declare function resolveProjectRoot(startDir: string): string | null;
 export interface VerifyToolConfig {
     tool: string;
     config: string;

package/dist/lib/config.js

@@ -1,5 +1,33 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
+/**
+ * Resolve the InDusk project root by walking up from the given directory
+ * until `.indusk/config.json` is found. Returns the directory containing
+ * `.indusk/config.json`, or `null` if none is found up to the filesystem
+ * root.
+ *
+ * `.indusk/config.json` is the authoritative "this is an InDusk project"
+ * marker — created by `indusk init`, never by sub-apps that happen to
+ * have their own `.claude/` scaffolding. Walking up to find it prevents
+ * bugs like `indusk update` syncing to the wrong `.claude/` when the user
+ * runs it from a sub-directory (e.g. `apps/indusk-mcp/`).
+ *
+ * For `indusk init` itself, use the raw cwd — init creates the marker, so
+ * walk-up would either find nothing or (worse) match an ancestor project
+ * the user doesn't intend to re-init.
+ */
+export function resolveProjectRoot(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 20; i++) {
+        if (existsSync(join(dir, ".indusk/config.json")))
+            return dir;
+        const parent = resolve(dir, "..");
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
 const CONFIG_PATH = ".indusk/config.json";
 export function getConfigPath(projectRoot) {
     return join(projectRoot, CONFIG_PATH);

package/dist/lib/eval/prompt-builder.js

@@ -12,9 +12,32 @@ export function buildJudgePrompt(opts) {
     const questionsBlock = opts.rubric
         .map((q, i) => `${i + 1}. **${q.id}**: ${q.question}\n   Guidance: ${q.guidance}`)
         .join("\n\n");
+    const highlightsInstructions = opts.mode === "eval"
+        ? `### Step 4: Process unprocessed highlights
+
+Before answering the rubric, process the working agent's highlights queue. Highlights are the working agent's flagged moments — brief acceptances, ADR acceptances, corrections, retrospective lessons — and the eval agent is responsible for materializing them into structured Graphiti episodes.
+
+Call \`mcp__indusk__highlights_unprocessed\` to get the list. For each highlight, the level drives effort and Graphiti edge weight:
+
+- **critical** (architectural decision, accepted ADR, accepted brief): extract full context from the transcript and the changed files, write a structured Graphiti episode with weight **1.0**.
+- **important** (correction, retro lesson, confirmed pattern): extract context, write a Graphiti episode with weight **0.6**.
+- **note** (observation, partially-formed thought): consider it. Write a low-weight (**0.3**) episode if it adds signal; skip if it's already captured in an existing episode.
+
+Write each episode using \`mcp__indusk__graph_capture\` so it attaches to the relevant file anchor in the semantic graph — not raw \`mcp__graphiti__add_memory\`. Pick the group sensibly: \`${opts.projectGroup}\` for project-specific facts, \`shared\` for cross-project conventions (e.g., "always use pnpm ce"). Use the level to set the edge weight in the body's metadata section so downstream context-beam queries can rank by importance.
+
+After processing each highlight (whether you wrote an episode or decided to skip), call \`mcp__indusk__highlight_mark_processed\` with the highlight ID and the action:
+- \`action: "wrote-episode"\`, \`detail: "{episode name}"\` — if you wrote an episode.
+- \`action: "skipped"\`, \`detail: "{brief reason}"\` — if you decided not to (e.g., already captured, or not meaningful enough).
+
+**Highlights are additive context, not a constraint.** Continue reading the full transcript and inferring knowledge independently — highlights ensure important moments aren't missed, but they don't bound your analysis. The transcript may contain insights the working agent didn't flag.
+
+If \`mcp__indusk__highlights_unprocessed\` is unavailable, skip this step silently and continue.`
+        : `### Step 4: Highlights (baseline mode)
+
+Baseline mode — do NOT process highlights or write to Graphiti. Skip to Step 5.`;
     const graphitiInstructions = opts.mode === "eval"
         ? `
-## Step 5: Write findings to the knowledge graph
+### Step 6: Write findings to the knowledge graph
 
 For each finding with severity "warning" or "critical", write it using \`mcp__indusk__graph_capture\`. This dual-writes to both Graphiti AND the semantic graph, connecting the finding to the existing file anchor — so the context beam can find it later.
 
@@ -33,10 +56,10 @@ mcp__indusk__graph_capture({
 \`\`\`
 
 Only write facts that would have changed the outcome. Be selective — quality over quantity.
-Count how many graph_capture calls you made for the scorecard.
+Count how many graph_capture calls you made for the scorecard (this count includes any highlight episodes written in Step 4).
 If the tool is unavailable, skip silently and set graphitiWrites to 0.`
         : `
-## Step 5: Graphiti writes
+### Step 6: Graphiti writes
 
 Baseline mode — do NOT write to Graphiti. Set graphitiWrites to 0.`;
     return `You are the InDusk evaluation judge. Your job is to evaluate the quality of work done by an AI agent on a software project.
@@ -65,7 +88,9 @@ Run \`jj diff -r ${opts.changeId}\` to see what was committed. This is the work
 
 Then read the specific files that were changed to understand the full context — not just the diff lines, but the surrounding code.
 
-### Step 4: Answer the evaluation questions
+${highlightsInstructions}
+
+### Step 5: Answer the evaluation questions
 
 For each question, investigate thoroughly using MCP tools — search the codebase, query the code graph, check Graphiti for relevant facts. Then answer with this exact JSON shape per question:
 
@@ -88,7 +113,7 @@ Questions:
 ${questionsBlock}
 ${graphitiInstructions}
 
-## Step 6: Output the scorecard
+### Step 7: Output the scorecard
 
 After completing all steps, output ONLY the following JSON object. No markdown wrapping, no commentary before or after — just the JSON:
 
@@ -99,7 +124,7 @@ After completing all steps, output ONLY the following JSON object. No markdown w
   "mode": "${opts.mode}",
   "changeId": "${opts.changeId}",
   "projectGroup": "${opts.projectGroup}",
-  "questions": [/* your answers from Step 4 */],
+  "questions": [/* your answers from Step 5 */],
   "summary": "{one paragraph overall assessment}",
   "graphitiWrites": {number of Graphiti writes made},
   "telemetryPosted": false

package/dist/lib/falsification/log.d.ts

@@ -0,0 +1,51 @@
+export type HypothesisOutcome = "fix-in-scope" | "spawn-plan" | "accept-finding";
+export interface HypothesisEntry {
+    kind: "hypothesis";
+    hypothesis: string;
+    testPath: string | null;
+    outcome: HypothesisOutcome;
+    note?: string;
+    timestamp: string;
+}
+export interface TerminatorEntry {
+    kind: "terminator";
+    reason: string;
+    timestamp: string;
+}
+export type LogEntry = HypothesisEntry | TerminatorEntry;
+export interface MalformedLine {
+    lineNumber: number;
+    content: string;
+    reason: string;
+}
+/**
+ * Append a confirmed-hypothesis entry to the plan's falsification log.
+ * Creates the log file with a header if it doesn't yet exist. Throws if
+ * the log is already terminated (a new hypothesis after a terminator is a
+ * sign the ritual was restarted incorrectly — see `isFalsificationComplete`
+ * and start a new plan or explicitly un-terminate first).
+ */
+export declare function appendHypothesis(planRoot: string, entry: Omit<HypothesisEntry, "kind" | "timestamp">): HypothesisEntry;
+/**
+ * Append a terminator entry marking the falsification ritual complete for
+ * this plan. No further hypotheses can be appended after this. The reason
+ * is the user-confirmed rationale for termination (e.g., "investigated
+ * concurrency, race conditions, partial-write paths, and type-narrowing
+ * gaps; no in-scope failure remained").
+ */
+export declare function markTerminated(planRoot: string, reason: string): TerminatorEntry;
+/**
+ * Read the falsification log for a plan. Returns an empty array if the log
+ * file does not exist. Malformed entries are skipped (not thrown) and
+ * surfaced via the optional `onMalformed` callback, matching the semantic
+ * graph event log's resilience pattern.
+ */
+export declare function readFalsificationLog(planRoot: string, opts?: {
+    onMalformed?: (malformed: MalformedLine) => void;
+}): LogEntry[];
+/**
+ * True iff the plan's falsification log exists AND its last entry is a
+ * terminator. False for a missing log, a log with only hypotheses (ritual
+ * started but not terminated), or an empty log file.
+ */
+export declare function isFalsificationComplete(planRoot: string): boolean;

package/dist/lib/falsification/log.js

@@ -0,0 +1,207 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+const VALID_OUTCOMES = new Set([
+    "fix-in-scope",
+    "spawn-plan",
+    "accept-finding",
+]);
+/**
+ * Reject multiline content at the library boundary. The log's on-disk
+ * format is markdown sections with bold-labeled single-line fields; any
+ * line-separator character in hypothesis / note / reason silently
+ * truncates during parse (the regex uses /m mode, where $ matches before
+ * LF, CR, LS, and PS). Throwing here forces callers to sanitize — either
+ * collapse to a single line or split across multiple entries.
+ *
+ * Line separators rejected: LF (\n), CR (\r), LS (U+2028), PS (U+2029).
+ */
+const LINE_SEPARATOR_RE = /[\n\r\u2028\u2029]/;
+function assertSingleLine(field, value) {
+    if (LINE_SEPARATOR_RE.test(value)) {
+        throw new Error(`Falsification log ${field} must be single-line (got a value containing a line separator). Either collapse to one line (replace '\\n' with '; '), or split the content across multiple entries. The log's parser is line-oriented; any line-separator (LF, CR, LS, PS) would silently truncate.`);
+    }
+}
+function logPath(planRoot) {
+    return join(planRoot, "falsification.md");
+}
+function headerFor(planRoot) {
+    return `# Falsification Log — ${basename(planRoot)}\n\nAppend-only record of the /falsify bounty hunt for this plan. Never edit in place; entries are appended via \`appendHypothesis\` and \`markTerminated\` from \`apps/indusk-mcp/src/lib/falsification/log.ts\`.\n\n`;
+}
+/**
+ * Append a confirmed-hypothesis entry to the plan's falsification log.
+ * Creates the log file with a header if it doesn't yet exist. Throws if
+ * the log is already terminated (a new hypothesis after a terminator is a
+ * sign the ritual was restarted incorrectly — see `isFalsificationComplete`
+ * and start a new plan or explicitly un-terminate first).
+ */
+export function appendHypothesis(planRoot, entry) {
+    assertSingleLine("hypothesis", entry.hypothesis);
+    if (entry.note !== undefined)
+        assertSingleLine("note", entry.note);
+    const path = logPath(planRoot);
+    const existing = existsSync(path) ? readFalsificationLog(planRoot) : [];
+    if (existing.length > 0 && existing[existing.length - 1].kind === "terminator") {
+        throw new Error(`Falsification log at ${path} is already terminated. Start a new plan or remove the terminator before appending.`);
+    }
+    if (!existsSync(path)) {
+        writeFileSync(path, headerFor(planRoot), "utf-8");
+    }
+    const stored = {
+        kind: "hypothesis",
+        hypothesis: entry.hypothesis,
+        testPath: entry.testPath,
+        outcome: entry.outcome,
+        note: entry.note,
+        timestamp: new Date().toISOString(),
+    };
+    appendFileSync(path, renderHypothesis(stored), "utf-8");
+    return stored;
+}
+/**
+ * Append a terminator entry marking the falsification ritual complete for
+ * this plan. No further hypotheses can be appended after this. The reason
+ * is the user-confirmed rationale for termination (e.g., "investigated
+ * concurrency, race conditions, partial-write paths, and type-narrowing
+ * gaps; no in-scope failure remained").
+ */
+export function markTerminated(planRoot, reason) {
+    if (!reason.trim()) {
+        throw new Error("markTerminated requires a non-empty reason.");
+    }
+    assertSingleLine("reason", reason);
+    const path = logPath(planRoot);
+    const existing = existsSync(path) ? readFalsificationLog(planRoot) : [];
+    if (existing.length > 0 && existing[existing.length - 1].kind === "terminator") {
+        throw new Error(`Falsification log at ${path} is already terminated.`);
+    }
+    if (!existsSync(path)) {
+        writeFileSync(path, headerFor(planRoot), "utf-8");
+    }
+    const stored = {
+        kind: "terminator",
+        reason: reason.trim(),
+        timestamp: new Date().toISOString(),
+    };
+    appendFileSync(path, renderTerminator(stored), "utf-8");
+    return stored;
+}
+/**
+ * Read the falsification log for a plan. Returns an empty array if the log
+ * file does not exist. Malformed entries are skipped (not thrown) and
+ * surfaced via the optional `onMalformed` callback, matching the semantic
+ * graph event log's resilience pattern.
+ */
+export function readFalsificationLog(planRoot, opts) {
+    const path = logPath(planRoot);
+    if (!existsSync(path))
+        return [];
+    const content = readFileSync(path, "utf-8");
+    const entries = [];
+    const sectionRegex = /^##\s+(Hypothesis|Terminated)\s+(.+?)\s*$/gm;
+    const matches = [...content.matchAll(sectionRegex)];
+    for (let i = 0; i < matches.length; i++) {
+        const match = matches[i];
+        const [, kind, timestamp] = match;
+        const start = (match.index ?? 0) + match[0].length;
+        const end = i + 1 < matches.length ? (matches[i + 1].index ?? content.length) : content.length;
+        const body = content.slice(start, end).trim();
+        if (kind === "Hypothesis") {
+            const entry = parseHypothesisBody(body, timestamp);
+            if ("lineNumber" in entry) {
+                opts?.onMalformed?.(entry);
+            }
+            else {
+                entries.push(entry);
+            }
+        }
+        else if (kind === "Terminated") {
+            const entry = parseTerminatorBody(body, timestamp);
+            if ("lineNumber" in entry) {
+                opts?.onMalformed?.(entry);
+            }
+            else {
+                entries.push(entry);
+            }
+        }
+    }
+    return entries;
+}
+/**
+ * True iff the plan's falsification log exists AND its last entry is a
+ * terminator. False for a missing log, a log with only hypotheses (ritual
+ * started but not terminated), or an empty log file.
+ */
+export function isFalsificationComplete(planRoot) {
+    const entries = readFalsificationLog(planRoot);
+    if (entries.length === 0)
+        return false;
+    return entries[entries.length - 1].kind === "terminator";
+}
+// ---------------------------------------------------------------
+// Rendering (writing entries to markdown)
+// ---------------------------------------------------------------
+function renderHypothesis(entry) {
+    const lines = [
+        `## Hypothesis ${entry.timestamp}`,
+        "",
+        `**Hypothesis:** ${entry.hypothesis}`,
+        `**Test:** ${entry.testPath ?? "(not written)"}`,
+        `**Outcome:** ${entry.outcome}`,
+    ];
+    if (entry.note) {
+        lines.push(`**Note:** ${entry.note}`);
+    }
+    lines.push("", "");
+    return lines.join("\n");
+}
+function renderTerminator(entry) {
+    return [`## Terminated ${entry.timestamp}`, "", `**Reason:** ${entry.reason}`, "", ""].join("\n");
+}
+// ---------------------------------------------------------------
+// Parsing (reading entries from markdown)
+// ---------------------------------------------------------------
+function parseHypothesisBody(body, timestamp) {
+    const hypothesisMatch = body.match(/^\*\*Hypothesis:\*\*\s+(.+)$/m);
+    const testMatch = body.match(/^\*\*Test:\*\*\s+(.+)$/m);
+    const outcomeMatch = body.match(/^\*\*Outcome:\*\*\s+([a-z-]+)$/m);
+    const noteMatch = body.match(/^\*\*Note:\*\*\s+(.+)$/m);
+    if (!hypothesisMatch || !outcomeMatch) {
+        return {
+            lineNumber: 0,
+            content: body,
+            reason: "Hypothesis entry missing required fields (hypothesis or outcome)",
+        };
+    }
+    const outcome = outcomeMatch[1];
+    if (!VALID_OUTCOMES.has(outcome)) {
+        return {
+            lineNumber: 0,
+            content: body,
+            reason: `Invalid outcome "${outcome}"; must be one of ${[...VALID_OUTCOMES].join(", ")}`,
+        };
+    }
+    const testRaw = testMatch?.[1]?.trim() ?? "(not written)";
+    return {
+        kind: "hypothesis",
+        hypothesis: hypothesisMatch[1].trim(),
+        testPath: testRaw === "(not written)" ? null : testRaw,
+        outcome,
+        note: noteMatch?.[1]?.trim(),
+        timestamp,
+    };
+}
+function parseTerminatorBody(body, timestamp) {
+    const reasonMatch = body.match(/^\*\*Reason:\*\*\s+(.+)$/m);
+    if (!reasonMatch) {
+        return {
+            lineNumber: 0,
+            content: body,
+            reason: "Terminator entry missing required Reason field",
+        };
+    }
+    return {
+        kind: "terminator",
+        reason: reasonMatch[1].trim(),
+        timestamp,
+    };
+}