@infinitedusky/indusk-mcp 1.15.1 → 1.16.1

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/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/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,
+    };
+}

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

@@ -0,0 +1,23 @@
+export interface SkipCheck {
+    skipped: boolean;
+    reason: string | null;
+}
+/**
+ * Parse an impl.md body (the full file content including frontmatter) and
+ * return whether the author has explicitly opted out of the falsification
+ * ritual. Opt-out requires both fields in frontmatter:
+ *
+ *   falsification: skipped
+ *   falsification_reason: "a non-empty reason"
+ *
+ * Returns `{ skipped: true, reason }` only if both fields are present and
+ * the reason is non-empty after trimming. Any other state — missing
+ * `falsification`, falsification set to anything other than `skipped`,
+ * missing or empty reason — returns `{ skipped: false, reason: null }`.
+ *
+ * The two-field shape matches the planner skill's precedent (gate_policy
+ * as a single enum value) while keeping the reason unambiguous against
+ * YAML parsers. Colons inside quoted YAML strings are fragile across
+ * parsers; two fields avoid that class of bug entirely.
+ */
+export declare function isFalsificationSkipped(implContent: string): SkipCheck;

package/dist/lib/falsification/skip.js

@@ -0,0 +1,37 @@
+import matter from "gray-matter";
+/**
+ * Parse an impl.md body (the full file content including frontmatter) and
+ * return whether the author has explicitly opted out of the falsification
+ * ritual. Opt-out requires both fields in frontmatter:
+ *
+ *   falsification: skipped
+ *   falsification_reason: "a non-empty reason"
+ *
+ * Returns `{ skipped: true, reason }` only if both fields are present and
+ * the reason is non-empty after trimming. Any other state — missing
+ * `falsification`, falsification set to anything other than `skipped`,
+ * missing or empty reason — returns `{ skipped: false, reason: null }`.
+ *
+ * The two-field shape matches the planner skill's precedent (gate_policy
+ * as a single enum value) while keeping the reason unambiguous against
+ * YAML parsers. Colons inside quoted YAML strings are fragile across
+ * parsers; two fields avoid that class of bug entirely.
+ */
+export function isFalsificationSkipped(implContent) {
+    try {
+        const { data } = matter(implContent);
+        const flag = data.falsification;
+        const reasonRaw = data.falsification_reason;
+        if (flag !== "skipped")
+            return { skipped: false, reason: null };
+        if (typeof reasonRaw !== "string")
+            return { skipped: false, reason: null };
+        const reason = reasonRaw.trim();
+        if (!reason)
+            return { skipped: false, reason: null };
+        return { skipped: true, reason };
+    }
+    catch {
+        return { skipped: false, reason: null };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.15.1",
+	"version": "1.16.1",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/falsify.md

@@ -0,0 +1,87 @@
+---
+name: falsify
+description: Run the falsification ritual against a completed plan. Goal-flip from "prove it works" to "find a failing test" — investigate the code, form a specific hypothesis about what should be broken, write the test that confirms it, run it. Required between /work completion and /retrospective.
+argument-hint: "{plan-name}"
+---
+
+You are about to run the **falsification ritual** against a plan whose `/work` has completed. The plan has an attested state — the goal, the Trajectory rows (all in terminal state), the claims it makes about what is now true. Your job is **not** to confirm those claims. Your job is to **falsify them**.
+
+This is a goal-flip, not a persona switch. Same agent, different question. Instead of "does this work?" — "what specific thing, with what specific inputs, makes this fail?"
+
+## How to hunt
+
+This is bounty hunting, not candidate generation. **Do not write hopeful tests and see what fails.** Each iteration hunts a specific target:
+
+1. **Read the attested state.** Open the plan's `impl.md`. Read the Goal. Read every Trajectory row — what does each claim? Read the ADR if one exists — what invariants does the plan promise?
+2. **Investigate the code.** Read the actual implementation. Compare what the code does against what the attestation claims. Look for gaps.
+3. **Form a specific hypothesis.** Not "what could go wrong?" — "*this specific condition, with these specific inputs, will violate this specific invariant.*" Name the failure before writing any test.
+4. **Write the test that confirms the hypothesis.** If the hypothesis is right, the test fails. If the hypothesis is wrong, the test passes.
+5. **Run the test.**
+
+Prompts to ask yourself while investigating (use these as starting points, not a checklist):
+
+- **What's an edge case not covered by T1–Tn?** List every row. For each: what inputs did the author think of? What inputs did they miss?
+- **What's an implicit invariant the attestation makes that the Trajectory doesn't test?** "Recoverable from crash" implies "recoverable from partial write." Is there a test for partial writes?
+- **What about concurrent, partial, or malformed inputs?** Two callers at once. A half-written file. A valid-shape but semantically-wrong input.
+- **What would a malicious user try?** If this accepts input, what input breaks the parser, or traverses paths, or exhausts memory?
+- **What does the attestation assume about the environment?** Time monotonicity. Disk not full. Network present. Clock skew. Is any assumption documented vs. silently-assumed?
+- **What's the first thing someone would try if they were paid $100 to find one failure here?** Specifically. Concretely.
+- **What invariants are only enforced in one direction?** (E.g., "create calls validate, but update bypasses validation.")
+- **What claim does the Goal make that's not expressed as a Trajectory row?** That's often the unguarded surface.
+
+**Anti-pattern — do NOT do this:** "I'll write several tests and see which ones fail." That's candidate generation. It's cheap and useless. Every candidate you write without a specific hypothesis is noise. Investigate first, hypothesize specifically, write the test that targets *that* hypothesis.
+
+## Three outcomes per failing test
+
+When a test fails (your hypothesis is confirmed), pick one outcome — recommend one, but the user decides:
+
+1. **Fix in scope** — the gap is small and clearly in-scope for the plan's original goal. Add a new phase to the current `impl.md`, flip the impl status back to `in-progress`, return to `/work`. This is "build the plane while flying" — the plan grows during its own closure.
+2. **Spawn a new plan** — the gap is large, touches unrelated areas, or deserves its own planning lifecycle. Create `.indusk/planning/{new-slug}/brief.md` with the failing test as its core motivation. Link via `blocks:` in the current plan's brief.
+3. **Accept as finding** — rare. The gap is small, unambiguously out-of-scope, and the cost of a new plan isn't justified. Record in the falsification log and note in retrospective. Use only when the other two genuinely don't fit.
+
+After choosing the outcome, record the hypothesis via `appendHypothesis(planRoot, { hypothesis, testPath, outcome, note? })` from `apps/indusk-mcp/src/lib/falsification/log.ts`. The log file at `.indusk/planning/{plan}/falsification.md` captures the session's history.
+
+## Loop exit (hybrid)
+
+Continue hunting until you genuinely **cannot form a specific in-scope hypothesis** about what should be broken. Not "I've tried enough tests" — "I have investigated the code and cannot name a concrete attack vector remaining."
+
+When you reach that point, present the user with a summary:
+
+- Hypotheses investigated and their outcomes (confirmed → fix/spawn/accept; wrong → the hypothesis was rejected, note what held up)
+- Regions of code you searched without finding an attack vector
+- Any areas you did NOT investigate and why (e.g., "didn't investigate serialization because no serialization code was changed")
+
+The user confirms termination — or points at an area you didn't investigate. Not "write another test" — they should point at a *region* you missed. If that produces a new hypothesis, the loop continues. If nothing new surfaces, call `markTerminated(planRoot, reason)` to close the log and hand off to `/retrospective`.
+
+## When to skip the ritual entirely
+
+For genuinely trivial plans (two-line typo fix, changelog entry, variable rename with no behavioral change), the ritual's cost may exceed its discipline value. To skip, the plan's `impl.md` frontmatter must contain BOTH:
+
+```yaml
+falsification: skipped
+falsification_reason: "a non-empty reason, quoted as a YAML string"
+```
+
+The retrospective skill's Step 0 gate accepts either a completed falsification log OR the two-field skip frontmatter. Skipping is a confession, not a bypass — use sparingly.
+
+## Output
+
+By the time you hand off to `/retrospective`, one of these must be true:
+
+- `.indusk/planning/{plan}/falsification.md` exists with a terminator entry (log is closed cleanly), OR
+- The plan reopened (`impl` status flipped to `in-progress`) via a "fix in scope" outcome and `/work` is active again (deferring falsification until the fix lands)
+
+The `/retrospective` skill's Step 0 hard-blocks without this. Don't bypass.
+
+## Why this exists
+
+See the [Falsification Ritual guide](apps/indusk-docs/src/guide/falsification-ritual.md) for the full motivation. Short version: the Test Trajectory made universal deferral structurally impossible, but authors only write tests they can think of — and the author is the last person likely to notice the gaps in their own thinking. The ritual is a bullshit detector. Its purpose is rigor through self-examination.
+
+## Important
+
+- Same agent, flipped goal. No persona, no separate session. The same you that built the plan, asked a different question.
+- Bounty hunting, not candidate generation. Investigate first, hypothesize specifically, write the test that targets *that*.
+- Exit criterion is "can't form a specific in-scope hypothesis" — not "ran out of candidates" or "tried N things."
+- The log is append-only. Never edit `falsification.md` by hand. Write via `appendHypothesis` / `markTerminated` from the library.
+- If you find a gap, pick an outcome. Do not log a failing test and then continue looking for more failing tests as if the first didn't matter — each failure demands a decision before moving on.
+- The user's input is: $ARGUMENTS

package/skills/planner.md

@@ -92,7 +92,7 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
    ```
    mcp__graphiti__add_memory({
      name: "adr-{plan-name}",
-     episode_body: "In the context of {use case}, facing {constraint}, we decided for {chosen option} and against {rejected alternatives}, to achieve {desired outcome}, accepting {tradeoff}, because {rationale}.",
+     episode_body: "In context facing: {use case AND constraint}. We decided for: {chosen option}. And against: {rejected alternatives}. To achieve: {desired outcome}. Accepting: {tradeoff}. Because: {rationale}.",
      group_id: "{project-group}",
      source: "text",
      source_description: "ADR acceptance"
@@ -207,13 +207,34 @@ status: proposed | accepted | deprecated | superseded | abandoned
 # {Title}
 
 ## Y-Statement
-In the context of **{use case}**,
-facing **{constraint}**,
-we decided for **{chosen option}**
-and against **{rejected alternatives}**,
-to achieve **{desired outcome}**,
-accepting **{tradeoff}**,
-because **{rationale}**.
+
+**In the context of:**
+{the use case — one paragraph, plain text, not bold}
+
+**Facing:**
+{the constraint or problem the use case presents — one paragraph}
+
+**We decided for:**
+{the chosen option — one paragraph}
+
+**And against:**
+{the rejected alternatives — one paragraph}
+
+**To achieve:**
+{the desired outcome — one paragraph}
+
+**Accepting:**
+{the tradeoff — one paragraph}
+
+**Because:**
+{the rationale — one paragraph}
+
+Format rules (the standard Y-statement format for every ADR in every project going forward):
+- Use all seven canonical clauses: In the context of, Facing, We decided for, And against, To achieve, Accepting, Because. These are the standard Y-statement fields — do not collapse, rename, or omit them.
+- Each clause is its own section. The clause label is bold and ends with a colon.
+- The paragraph body begins on the next line immediately after the bold label — no blank line between the label and the paragraph.
+- The paragraph body is plain text — not bold, no inline label.
+- A blank line separates each clause (between the end of one paragraph and the next bold label).
 
 ## Context
 {Situation and background. Reference research and brief.}

package/skills/retrospective.md

@@ -28,6 +28,34 @@ The retrospective skill replaces the freeform "write a retrospective" step with
 
 Work through these steps in order. Each step is blocking — do not skip ahead.
 
+### Step 0: Falsification Gate
+
+**This gate blocks everything below. Do not proceed to Step 1 until it passes.**
+
+Before writing a single word of the retrospective, confirm that the plan has completed the falsification ritual or has an explicit, recorded skip-reason.
+
+Check the gate by reading two sources:
+
+1. **Completion:** Does `.indusk/planning/{plan-name}/falsification.md` exist with a terminator entry? Use `isFalsificationComplete(planRoot)` from `apps/indusk-mcp/src/lib/falsification/log.js` (invoke via `tsx` or an MCP tool wrapper).
+2. **Skip:** Does the impl's frontmatter contain BOTH `falsification: skipped` AND `falsification_reason: "{non-empty text}"`? Use `isFalsificationSkipped(implContent)` from `apps/indusk-mcp/src/lib/falsification/skip.js`.
+
+The gate passes if either condition holds. If neither holds, refuse to run the retrospective and surface this message to the user:
+
+> **Retrospective blocked: falsification gate not satisfied for `{plan-name}`.**
+>
+> Before closing out a plan, run `/falsify {plan-name}` to exercise the bounty-hunting ritual — investigate the code, form a specific hypothesis about what should be broken, write the test that confirms it. The ritual may surface gaps worth addressing before archival (fix in scope, spawn a new plan, or accept as finding).
+>
+> To skip the ritual intentionally, add these two fields to the impl's frontmatter:
+>
+> ```yaml
+> falsification: skipped
+> falsification_reason: "why skipping is acceptable for this specific plan"
+> ```
+>
+> The skip-reason is recorded in the archive and surfaced in retrospectives. Use sparingly — typically only for trivial typo-fix plans where the ritual cost exceeds the discipline value.
+
+Do not proceed to Step 1 until the gate passes. This is structural enforcement of the discipline documented in the [Falsification Ritual guide](apps/indusk-docs/src/guide/falsification-ritual.md) — happy-path authoring produces happy-path tests, and the ritual is the mechanism for surfacing the gaps the author couldn't think of.
+
 ### Step 1: Write the Retrospective Document
 
 Create `.indusk/planning/{plan-name}/retrospective.md` using the template from the plan skill. This is the reflective writing — what we set out to do, what actually happened, what we learned.

package/skills/work.md

@@ -204,7 +204,8 @@ The hook validates that both `asked:` and `user:` are present with non-empty quo
     - Update impl status to `completed`
     - Summarize what was done
     - If this plan included an ADR, confirm CLAUDE.md's Key Decisions was updated
-    - Let the user know the plan is ready for a retrospective if they want one (`/planner {name}` will pick up at the retrospective stage)
+    - **Run `/falsify {plan}` next, before `/retrospective`.** The falsification ritual is the bridge between "impl done" and "plan archived." It drives the same working agent through a goal-flipped bounty hunt — investigate the code, form a specific hypothesis about what should be broken, write the test that confirms it. The ritual may surface gaps worth addressing, which can reopen the impl (status flips back to `in-progress`) for a fix-in-scope phase, or spawn a new plan, or be recorded as a finding. Only after `/falsify` terminates cleanly — or has been explicitly skipped via `falsification: skipped` + `falsification_reason: "..."` in the impl frontmatter — is the plan ready for `/retrospective`. See the [Falsification Ritual guide](apps/indusk-docs/src/guide/falsification-ritual.md) and `.indusk/planning/archive/falsification-ritual/adr.md`.
+    - Let the user know: "Impl complete. Run `/falsify {plan}` next. If it terminates cleanly, then `/retrospective {plan}` will close out the plan."
 
 ## Teach Mode