@isaacriehm/cairn-core 0.1.0

package/dist/mcp/telemetry.d.ts

@@ -0,0 +1,15 @@
+import type { McpContext } from "./context.js";
+/**
+ * Writes one row per tool call to:
+ *   - .cairn/runs/active/<runId>/mcp-calls.jsonl     when ctx.runId set
+ *   - .cairn/staleness/mcp-calls.jsonl               otherwise
+ */
+export interface TelemetryRow {
+    ts: string;
+    tool: string;
+    args: unknown;
+    result_kind: "ok" | "error";
+    result_size: number;
+    duration_ms: number;
+}
+export declare function recordCall(ctx: McpContext, row: TelemetryRow): void;

package/dist/mcp/telemetry.js

@@ -0,0 +1,13 @@
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function recordCall(ctx, row) {
+    const path = ctx.runId !== undefined
+        ? join(ctx.repoRoot, ".cairn", "runs", "active", ctx.runId, "mcp-calls.jsonl")
+        : join(ctx.repoRoot, ".cairn", "staleness", "mcp-calls.jsonl");
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    appendFileSync(path, `${JSON.stringify(row)}\n`, "utf8");
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/mcp/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/mcp/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAiB1C,MAAM,UAAU,UAAU,CAAC,GAAe,EAAE,GAAiB;IAC3D,MAAM,IAAI,GACR,GAAG,CAAC,KAAK,KAAK,SAAS;QACrB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,EAAE,iBAAiB,CAAC;QAC9E,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;IACnE,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC"}

package/dist/mcp/tools/append-run-note.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `cairn_append_run_note` — append a phase-tagged note to a task's notes.md.
+ *
+ * The handoff builder (CONTEXT_CONTINUITY_SPEC §2.2) reads notes.md when it
+ * resumes an in-flight run, so notes survive context compaction by virtue of
+ * being committed to disk. The MCP write surface is append-only and gated
+ * by the path allowlist — see `mcp/path-allowlist.ts`.
+ *
+ * Spec: docs/CONTEXT_CONTINUITY_SPEC.md §2.3.
+ */
+import type { ToolDef } from "./types.js";
+interface Input {
+    run_id: string;
+    phase: string;
+    note: string;
+}
+export declare const appendRunNoteTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/append-run-note.js

@@ -0,0 +1,47 @@
+/**
+ * `cairn_append_run_note` — append a phase-tagged note to a task's notes.md.
+ *
+ * The handoff builder (CONTEXT_CONTINUITY_SPEC §2.2) reads notes.md when it
+ * resumes an in-flight run, so notes survive context compaction by virtue of
+ * being committed to disk. The MCP write surface is append-only and gated
+ * by the path allowlist — see `mcp/path-allowlist.ts`.
+ *
+ * Spec: docs/CONTEXT_CONTINUITY_SPEC.md §2.3.
+ */
+import { appendFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { mcpError } from "../errors.js";
+import { isAppendAllowed, relPosix, safeJoin } from "../path-allowlist.js";
+import { appendRunNoteInput } from "../schemas.js";
+const RUN_ID_RE = /^[A-Za-z0-9_-]+$/;
+async function handler(ctx, input) {
+    if (!RUN_ID_RE.test(input.run_id) || input.run_id.length > 80) {
+        return mcpError("VALIDATION_FAILED", `run_id must match path-safe pattern [A-Za-z0-9_-] (≤80 chars)`);
+    }
+    const rel = `.cairn/tasks/active/${input.run_id}/notes.md`;
+    const abs = safeJoin(ctx.repoRoot, rel);
+    if (typeof abs !== "string")
+        return abs; // error envelope
+    const relCanon = relPosix(ctx.repoRoot, abs);
+    if (!isAppendAllowed(relCanon)) {
+        return mcpError("PATH_NOT_ALLOWED", `Append-write is not allowed for "${relCanon}".`);
+    }
+    const taskDir = join(ctx.repoRoot, ".cairn", "tasks", "active", input.run_id);
+    if (!existsSync(taskDir)) {
+        return mcpError("RUN_NOT_FOUND", `No active task dir at .cairn/tasks/active/${input.run_id}/`);
+    }
+    const entry = `\n## ${new Date().toISOString()} [${input.phase}]\n${input.note}\n`;
+    appendFileSync(abs, entry, "utf8");
+    return {
+        ok: true,
+        path: relCanon,
+        bytes_written: Buffer.byteLength(entry, "utf8"),
+    };
+}
+export const appendRunNoteTool = {
+    name: "cairn_append_run_note",
+    description: "Append a phase-tagged note to .cairn/tasks/active/<run_id>/notes.md. The handoff builder reads notes.md so notes survive across sessions / context compaction. The run_id field must match the active task dir id (path-safe chars only).",
+    inputSchema: appendRunNoteInput,
+    handler,
+};
+//# sourceMappingURL=append-run-note.js.map

package/dist/mcp/tools/append-run-note.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-run-note.js","sourceRoot":"","sources":["../../../src/mcp/tools/append-run-note.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AASnD,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,KAAY;IAClD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAC9D,OAAO,QAAQ,CACb,mBAAmB,EACnB,+DAA+D,CAChE,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,uBAAuB,KAAK,CAAC,MAAM,WAAW,CAAC;IAC3D,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,CAAC,iBAAiB;IAE1D,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7C,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/B,OAAO,QAAQ,CACb,kBAAkB,EAClB,oCAAoC,QAAQ,IAAI,CACjD,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9E,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,OAAO,QAAQ,CACb,eAAe,EACf,6CAA6C,KAAK,CAAC,MAAM,GAAG,CAC7D,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,KAAK,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC;IACnF,cAAc,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,QAAQ;QACd,aAAa,EAAE,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC;KAChD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC/C,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,2OAA2O;IAC7O,WAAW,EAAE,kBAAkB;IAC/B,OAAO;CACR,CAAC"}

package/dist/mcp/tools/append.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDef } from "./types.js";
+interface Input {
+    path: string;
+    content: string;
+    newline_separator?: boolean;
+}
+export declare const appendTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/append.js

@@ -0,0 +1,37 @@
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { requireBootstrap } from "../bootstrap-guard.js";
+import { mcpError } from "../errors.js";
+import { isAppendAllowed, relPosix, safeJoin } from "../path-allowlist.js";
+import { appendInput } from "../schemas.js";
+async function handler(ctx, input) {
+    const block = requireBootstrap(ctx.repoRoot);
+    if (block !== null)
+        return block;
+    const abs = safeJoin(ctx.repoRoot, input.path);
+    if (typeof abs !== "string")
+        return abs; // error envelope
+    const rel = relPosix(ctx.repoRoot, abs);
+    if (!isAppendAllowed(rel)) {
+        return mcpError("PATH_NOT_ALLOWED", `Append-write is not allowed for "${rel}". Allowlist limited to runs/active/<id>/{events,commands}.jsonl, staleness/log.jsonl, and inbox/**.`);
+    }
+    // For runs/active/<id>/* paths, the run id segment must exist as a directory.
+    const runMatch = rel.match(/^\.cairn\/runs\/active\/([^/]+)\//);
+    if (runMatch) {
+        const runDir = `${ctx.repoRoot}/.cairn/runs/active/${runMatch[1]}`;
+        if (!existsSync(runDir)) {
+            return mcpError("RUN_NOT_FOUND", `No active run dir at ${runDir}`);
+        }
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    const sep = input.newline_separator !== false ? "\n" : "";
+    appendFileSync(abs, input.content + sep, "utf8");
+    return { ok: true, path: rel, bytes_written: Buffer.byteLength(input.content + sep, "utf8") };
+}
+export const appendTool = {
+    name: "cairn_append",
+    description: "Append-only write to a path-allowlisted file. No read required. Allowlist: runs/active/<id>/{events,commands}.jsonl, staleness/log.jsonl, inbox/**.",
+    inputSchema: appendInput,
+    handler,
+};
+//# sourceMappingURL=append.js.map

package/dist/mcp/tools/append.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.js","sourceRoot":"","sources":["../../../src/mcp/tools/append.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAS5C,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,KAAY;IAClD,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,CAAC,iBAAiB;IAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,QAAQ,CACb,kBAAkB,EAClB,oCAAoC,GAAG,sGAAsG,CAC9I,CAAC;IACJ,CAAC;IACD,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAChE,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,uBAAuB,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,OAAO,QAAQ,CAAC,eAAe,EAAE,wBAAwB,MAAM,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IACD,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,iBAAiB,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,GAAG,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC;AAChG,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,qJAAqJ;IACvJ,WAAW,EAAE,WAAW;IACxB,OAAO;CACR,CAAC"}

package/dist/mcp/tools/archive.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDef } from "./types.js";
+interface Input {
+    path: string;
+    reason: string;
+    archive_dir?: string;
+}
+export declare const archiveTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/archive.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeInvalidationEvent } from "../../events/index.js";
+import { recordDriftEvent } from "../../ground/index.js";
+import { withWriteLock } from "../../lock.js";
+import { requireBootstrap } from "../bootstrap-guard.js";
+import { mcpError } from "../errors.js";
+import { isArchiveDenied, relPosix, safeJoin } from "../path-allowlist.js";
+import { archiveInput } from "../schemas.js";
+async function handler(ctx, input) {
+    const block = requireBootstrap(ctx.repoRoot);
+    if (block !== null)
+        return block;
+    const abs = safeJoin(ctx.repoRoot, input.path);
+    if (typeof abs !== "string")
+        return abs;
+    const rel = relPosix(ctx.repoRoot, abs);
+    if (isArchiveDenied(rel)) {
+        return mcpError("NOT_ALLOWED", `Path "${rel}" is in the archive-deny list (sacred ground: AGENTS.md, .claude/**, decisions/, brand/).`);
+    }
+    if (rel.startsWith(".archive/")) {
+        return { ok: true, idempotent: true, path: rel, note: "Already in .archive/" };
+    }
+    if (!existsSync(abs)) {
+        return mcpError("FILE_NOT_FOUND", `No file at ${rel}`);
+    }
+    if (!statSync(abs).isFile()) {
+        return mcpError("NOT_ALLOWED", `Path is not a file: ${rel}`);
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    const bucket = input.archive_dir ?? today;
+    const target = join(ctx.repoRoot, ".archive", bucket, rel);
+    return withWriteLock(ctx.repoRoot, () => {
+        mkdirSync(dirname(target), { recursive: true });
+        renameSync(abs, target);
+        recordDriftEvent(ctx.repoRoot, {
+            ts: new Date().toISOString(),
+            kind: "orphan_path",
+            path: rel,
+            detail: `archived: ${input.reason}`,
+            severity: "soft",
+        });
+        try {
+            const refs = [{ kind: "path", id: rel }];
+            const decMatch = rel.match(/^\.cairn\/ground\/decisions\/(?:_inbox\/)?(DEC-\d+)/);
+            if (decMatch)
+                refs.unshift({ kind: "decision", id: decMatch[1] });
+            writeInvalidationEvent(ctx.repoRoot, {
+                kind: "path_archived",
+                refs,
+                path: rel,
+                source: { session_id: ctx.sessionId ?? null, tool: "cairn_archive" },
+            });
+        }
+        catch {
+            // Event emission must never roll back the rename.
+        }
+        return {
+            ok: true,
+            archived_from: rel,
+            archived_to: relPosix(ctx.repoRoot, target),
+            reason: input.reason,
+        };
+    });
+}
+export const archiveTool = {
+    name: "cairn_archive",
+    description: "Move a canonical-zone file to .archive/<archive_dir or today>/<original_path>. Idempotent. Records a staleness/log.jsonl event. Refuses sacred paths (AGENTS.md, .claude/**, decisions/, brand/).",
+    inputSchema: archiveInput,
+    handler,
+};
+//# sourceMappingURL=archive.js.map

package/dist/mcp/tools/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../src/mcp/tools/archive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,sBAAsB,EAA6B,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAS7C,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,KAAY;IAClD,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,QAAQ,CACb,aAAa,EACb,SAAS,GAAG,2FAA2F,CACxG,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;IACjF,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,QAAQ,CAAC,gBAAgB,EAAE,cAAc,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3D,OAAO,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE;QACtC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACxB,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE;YAC7B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,aAAa,KAAK,CAAC,MAAM,EAAE;YACnC,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,IAAI,GAA2B,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;YAClF,IAAI,QAAQ;gBAAE,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;YACnE,sBAAsB,CAAC,GAAG,CAAC,QAAQ,EAAE;gBACnC,IAAI,EAAE,eAAe;gBACrB,IAAI;gBACJ,IAAI,EAAE,GAAG;gBACT,MAAM,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE;aACrE,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;QAED,OAAO;YACL,EAAE,EAAE,IAAI;YACR,aAAa,EAAE,GAAG;YAClB,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC;YAC3C,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,eAAe;IACrB,WAAW,EACT,mMAAmM;IACrM,WAAW,EAAE,YAAY;IACzB,OAAO;CACR,CAAC"}

package/dist/mcp/tools/ask-operator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * cairn_ask_operator — agent-initiated operator dialog mid-run.
+ *
+ * The implementer agent calls this when it hits an ambiguity, needs
+ * permission for a non-recoverable action, gets stuck, or wants to
+ * verify its interpretation. The flow:
+ *
+ *   1. Tool writes a question file under
+ *      `.cairn/runs/active/<run_id>/questions/<question_id>.q.json`.
+ *   2. The orchestrator's question-watcher (chokidar) picks it up,
+ *      fires `adapter.requestDialog()` with the active operator
+ *      pinged (so they see it on mobile push).
+ *   3. Operator answers via Discord button (or free-form follow-up
+ *      if no `options` were provided).
+ *   4. The orchestrator writes the answer to
+ *      `.cairn/runs/active/<run_id>/questions/<question_id>.a.json`.
+ *   5. This tool polls for the answer file and returns its contents to
+ *      the agent.
+ *
+ * The agent run continues with the operator's answer in context. If
+ * `timeout_ms` elapses before the operator answers, the tool returns
+ * `{ timed_out: true }` and the agent decides what to do (default:
+ * abort with a remediation note).
+ */
+import type { ToolDef } from "./types.js";
+interface Input {
+    run_id: string;
+    question: string;
+    options?: string[];
+    category?: "ambiguity" | "permission" | "stuck" | "verify";
+    timeout_ms?: number;
+}
+export declare const askOperatorTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/ask-operator.js

@@ -0,0 +1,97 @@
+/**
+ * cairn_ask_operator — agent-initiated operator dialog mid-run.
+ *
+ * The implementer agent calls this when it hits an ambiguity, needs
+ * permission for a non-recoverable action, gets stuck, or wants to
+ * verify its interpretation. The flow:
+ *
+ *   1. Tool writes a question file under
+ *      `.cairn/runs/active/<run_id>/questions/<question_id>.q.json`.
+ *   2. The orchestrator's question-watcher (chokidar) picks it up,
+ *      fires `adapter.requestDialog()` with the active operator
+ *      pinged (so they see it on mobile push).
+ *   3. Operator answers via Discord button (or free-form follow-up
+ *      if no `options` were provided).
+ *   4. The orchestrator writes the answer to
+ *      `.cairn/runs/active/<run_id>/questions/<question_id>.a.json`.
+ *   5. This tool polls for the answer file and returns its contents to
+ *      the agent.
+ *
+ * The agent run continues with the operator's answer in context. If
+ * `timeout_ms` elapses before the operator answers, the tool returns
+ * `{ timed_out: true }` and the agent decides what to do (default:
+ * abort with a remediation note).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { requireBootstrap } from "../bootstrap-guard.js";
+import { mcpError } from "../errors.js";
+import { askOperatorInput } from "../schemas.js";
+const POLL_INTERVAL_MS = 500;
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+async function handler(ctx, input) {
+    const block = requireBootstrap(ctx.repoRoot);
+    if (block !== null)
+        return block;
+    const runDir = join(ctx.repoRoot, ".cairn", "runs", "active", input.run_id);
+    if (!existsSync(runDir)) {
+        return mcpError("RUN_NOT_FOUND", `No active run dir at ${runDir}. ask_operator must be called from within an in-flight run.`);
+    }
+    const questionsDir = join(runDir, "questions");
+    mkdirSync(questionsDir, { recursive: true });
+    const questionId = `Q-${Date.now().toString(36)}-${randomBytes(2).toString("hex")}`;
+    const qPath = join(questionsDir, `${questionId}.q.json`);
+    const aPath = join(questionsDir, `${questionId}.a.json`);
+    const qPayload = {
+        id: questionId,
+        run_id: input.run_id,
+        asked_at: new Date().toISOString(),
+        question: input.question,
+        ...(input.options !== undefined && input.options.length > 0
+            ? { options: input.options }
+            : {}),
+        ...(input.category !== undefined ? { category: input.category } : {}),
+        timeout_ms: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+    };
+    writeFileSync(qPath, JSON.stringify(qPayload, null, 2), "utf8");
+    // Poll for the answer file. The orchestrator's question-watcher
+    // observes the question, fires the dialog, writes the answer.
+    const deadline = Date.now() + (input.timeout_ms ?? DEFAULT_TIMEOUT_MS);
+    while (Date.now() < deadline) {
+        if (existsSync(aPath)) {
+            try {
+                const raw = readFileSync(aPath, "utf8");
+                const answer = JSON.parse(raw);
+                return {
+                    ok: true,
+                    question_id: questionId,
+                    answer: answer.answer,
+                    ...(answer.choice_id !== undefined ? { choice_id: answer.choice_id } : {}),
+                    ...(answer.free_text === true ? { free_text: true } : {}),
+                    ...(answer.timed_out === true ? { timed_out: true } : {}),
+                };
+            }
+            catch (err) {
+                return mcpError("VALIDATION_FAILED", `Failed to parse answer file ${aPath}: ${String(err)}`);
+            }
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+    return {
+        ok: true,
+        question_id: questionId,
+        answer: "",
+        timed_out: true,
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export const askOperatorTool = {
+    name: "cairn_ask_operator",
+    description: "Stop and ask the operator a question. Use when the spec is genuinely ambiguous, you need permission for a non-recoverable action, you're stuck, or you want the operator to verify your interpretation. Provide 2-4 short option strings if the answer fits a closed set; omit `options` to invite a free-form reply. The tool blocks until the operator answers or `timeout_ms` (default 10 minutes) elapses.",
+    inputSchema: askOperatorInput,
+    handler,
+};
+//# sourceMappingURL=ask-operator.js.map

package/dist/mcp/tools/ask-operator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-operator.js","sourceRoot":"","sources":["../../../src/mcp/tools/ask-operator.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/canonical-for-topic.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDef } from "./types.js";
+interface Input {
+    topic: string;
+}
+export declare const canonicalForTopicTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/canonical-for-topic.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { groundDir, parseFrontmatter } from "../../ground/index.js";
+import { mcpError } from "../errors.js";
+import { canonicalForTopicInput } from "../schemas.js";
+async function handler(ctx, input) {
+    const file = join(groundDir(ctx.repoRoot), "canonical-map", "topics.yaml");
+    if (!existsSync(file)) {
+        return mcpError("TOPIC_NOT_REGISTERED", `No canonical-map registered (topics.yaml not found at ${file})`);
+    }
+    const parsedFile = parseYaml(readFileSync(file, "utf8"));
+    const list = parsedFile?.topics ?? [];
+    const entry = list.find((t) => t.topic === input.topic);
+    if (!entry) {
+        return mcpError("TOPIC_NOT_REGISTERED", `Topic "${input.topic}" is not registered. Curated registry only — do NOT invent topics.`, { available: list.map((t) => t.topic) });
+    }
+    const docPath = join(ctx.repoRoot, entry.canonical_path.split("#")[0] ?? entry.canonical_path);
+    if (!existsSync(docPath) || !statSync(docPath).isFile()) {
+        return mcpError("FILE_NOT_FOUND", `Topic registered, but canonical_path does not exist: ${entry.canonical_path}`);
+    }
+    const buf = readFileSync(docPath);
+    const sha256 = createHash("sha256").update(buf).digest("hex");
+    const fm = parseFrontmatter(buf.toString("utf8")).frontmatter;
+    return {
+        topic: entry.topic,
+        canonical_path: entry.canonical_path,
+        sha256,
+        verified_at: fm?.["verified-at"] ?? null,
+        audience: entry.audience ?? fm?.audience ?? null,
+    };
+}
+export const canonicalForTopicTool = {
+    name: "cairn_canonical_for_topic",
+    description: "Returns the authoritative canonical_path + sha256 + verified-at for a registered topic. Topics are curated; unknown topics return TOPIC_NOT_REGISTERED.",
+    inputSchema: canonicalForTopicInput,
+    handler,
+};
+//# sourceMappingURL=canonical-for-topic.js.map

package/dist/mcp/tools/canonical-for-topic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-for-topic.js","sourceRoot":"","sources":["../../../src/mcp/tools/canonical-for-topic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAkBvD,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,KAAY;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,eAAe,EAAE,aAAa,CAAC,CAAC;IAC3E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,QAAQ,CACb,sBAAsB,EACtB,yDAAyD,IAAI,GAAG,CACjE,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAsB,CAAC;IAC9E,MAAM,IAAI,GAAiB,UAAU,EAAE,MAAM,IAAI,EAAE,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC;IACxD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,QAAQ,CACb,sBAAsB,EACtB,UAAU,KAAK,CAAC,KAAK,oEAAoE,EACzF,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CACxC,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;IAC/F,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACxD,OAAO,QAAQ,CACb,gBAAgB,EAChB,wDAAwD,KAAK,CAAC,cAAc,EAAE,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9D,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;IAC9D,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,MAAM;QACN,WAAW,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,IAAI;QACxC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,QAAQ,IAAI,IAAI;KACjD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAmB;IACnD,IAAI,EAAE,2BAA2B;IACjC,WAAW,EACT,yJAAyJ;IAC3J,WAAW,EAAE,sBAAsB;IACnC,OAAO;CACR,CAAC"}

package/dist/mcp/tools/decision-get.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDef } from "./types.js";
+interface Input {
+    id: string;
+}
+export declare const decisionGetTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/decision-get.js

@@ -0,0 +1,49 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decisionsDir, parseFrontmatter } from "../../ground/index.js";
+import { DecisionFrontmatter } from "../../ground/index.js";
+import { mcpError } from "../errors.js";
+import { decisionGetInput } from "../schemas.js";
+async function handler(ctx, input) {
+    const dir = decisionsDir(ctx.repoRoot);
+    if (!existsSync(dir)) {
+        return mcpError("DECISION_NOT_FOUND", `No decisions directory at ${dir}`);
+    }
+    const files = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+    for (const f of files) {
+        if (!f.isFile() || !f.name.endsWith(".md"))
+            continue;
+        const abs = join(dir, f.name);
+        const parsed = parseFrontmatter(readFileSync(abs, "utf8"));
+        const fm = DecisionFrontmatter.safeParse(parsed.frontmatter);
+        if (!fm.success)
+            continue;
+        if (fm.data.id !== input.id)
+            continue;
+        return {
+            id: fm.data.id,
+            title: fm.data.title,
+            status: fm.data.status,
+            ...(fm.data.scope_globs !== undefined ? { scope_globs: fm.data.scope_globs } : {}),
+            ...(fm.data.supersedes !== undefined ? { supersedes: fm.data.supersedes } : {}),
+            ...(fm.data.superseded_by !== undefined ? { superseded_by: fm.data.superseded_by } : {}),
+            ...(fm.data.decided_at !== undefined ? { decided_at: fm.data.decided_at } : {}),
+            ...(fm.data.assertions !== undefined ? { assertions: fm.data.assertions } : {}),
+            ...(fm.data.human_review_hint !== undefined
+                ? { human_review_hint: fm.data.human_review_hint }
+                : {}),
+            ...(fm.data.related_invariants !== undefined
+                ? { related_invariants: fm.data.related_invariants }
+                : {}),
+            body_markdown: parsed.body,
+        };
+    }
+    return mcpError("DECISION_NOT_FOUND", `No decision with id ${input.id}`);
+}
+export const decisionGetTool = {
+    name: "cairn_decision_get",
+    description: "Returns full ADR + assertions block for a decision id.",
+    inputSchema: decisionGetInput,
+    handler,
+};
+//# sourceMappingURL=decision-get.js.map

package/dist/mcp/tools/decision-get.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-get.js","sourceRoot":"","sources":["../../../src/mcp/tools/decision-get.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/decisions-for-symbol.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDef } from "./types.js";
+interface Input {
+    file: string;
+    symbol: string;
+}
+export declare const decisionsForSymbolTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/decisions-for-symbol.js

@@ -0,0 +1,42 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decisionsDir, matchAnyGlob, parseFrontmatter } from "../../ground/index.js";
+import { DecisionFrontmatter } from "../../ground/index.js";
+import { decisionsForSymbolInput } from "../schemas.js";
+async function handler(ctx, input) {
+    const dir = decisionsDir(ctx.repoRoot);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true, encoding: "utf8" })) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const abs = join(dir, entry.name);
+        const raw = readFileSync(abs, "utf8");
+        const parsed = parseFrontmatter(raw);
+        const fm = DecisionFrontmatter.safeParse(parsed.frontmatter);
+        if (!fm.success)
+            continue;
+        if (fm.data.status !== "accepted")
+            continue;
+        const scope = fm.data.scope_globs ?? [];
+        if (!scope.some((g) => matchAnyGlob(input.file, [g])))
+            continue;
+        if (!parsed.body.includes(input.symbol))
+            continue;
+        out.push({
+            id: fm.data.id,
+            title: fm.data.title,
+            status: fm.data.status,
+            ...(fm.data.scope_globs !== undefined ? { scope_globs: fm.data.scope_globs } : {}),
+        });
+    }
+    return out;
+}
+export const decisionsForSymbolTool = {
+    name: "cairn_decisions_for_symbol",
+    description: "Decisions whose scope_globs cover `file` AND whose body explicitly mentions `symbol`. Smaller result than path-glob alone.",
+    inputSchema: decisionsForSymbolInput,
+    handler,
+};
+//# sourceMappingURL=decisions-for-symbol.js.map

package/dist/mcp/tools/decisions-for-symbol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions-for-symbol.js","sourceRoot":"","sources":["../../../src/mcp/tools/decisions-for-symbol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAQxD,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,KAAY;IAClD,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,GAAG,GAA4E,EAAE,CAAC;IACxF,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAChF,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,EAAE,GAAG,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC7D,IAAI,CAAC,EAAE,CAAC,OAAO;YAAE,SAAS;QAC1B,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,UAAU;YAAE,SAAS;QAC5C,MAAM,KAAK,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QAChE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,SAAS;QAClD,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE;YACd,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK;YACpB,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM;YACtB,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAmB;IACpD,IAAI,EAAE,4BAA4B;IAClC,WAAW,EACT,4HAA4H;IAC9H,WAAW,EAAE,uBAAuB;IACpC,OAAO;CACR,CAAC"}

package/dist/mcp/tools/decisions-in-scope.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDef } from "./types.js";
+interface Input {
+    path_globs: string[];
+    status?: ("draft" | "accepted" | "superseded" | "archived")[];
+}
+export declare const decisionsInScopeTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/decisions-in-scope.js

@@ -0,0 +1,47 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decisionsDir, matchAnyGlob, parseFrontmatter } from "../../ground/index.js";
+import { DecisionFrontmatter } from "../../ground/index.js";
+import { decisionsInScopeInput } from "../schemas.js";
+async function handler(ctx, input) {
+    const wantStatus = new Set(input.status ?? ["accepted"]);
+    const dir = decisionsDir(ctx.repoRoot);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true, encoding: "utf8" })) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const abs = join(dir, entry.name);
+        const parsed = parseFrontmatter(readFileSync(abs, "utf8"));
+        const fm = DecisionFrontmatter.safeParse(parsed.frontmatter);
+        if (!fm.success)
+            continue;
+        if (!wantStatus.has(fm.data.status))
+            continue;
+        const scope = fm.data.scope_globs ?? [];
+        const overlap = scope.length === 0
+            ? false
+            : scope.some((scopeGlob) => input.path_globs.some((req) => matchAnyGlob(scopeGlob, [req]) || matchAnyGlob(req, [scopeGlob])));
+        if (!overlap)
+            continue;
+        out.push({
+            id: fm.data.id,
+            title: fm.data.title,
+            status: fm.data.status,
+            ...(fm.data.scope_globs !== undefined ? { scope_globs: fm.data.scope_globs } : {}),
+            ...(fm.data.supersedes !== undefined ? { supersedes: fm.data.supersedes } : {}),
+            ...(fm.data.superseded_by !== undefined ? { superseded_by: fm.data.superseded_by } : {}),
+            ...(fm.data.decided_at !== undefined ? { decided_at: fm.data.decided_at } : {}),
+        });
+    }
+    out.sort((a, b) => (b.decided_at ?? "").localeCompare(a.decided_at ?? ""));
+    return out;
+}
+export const decisionsInScopeTool = {
+    name: "cairn_decisions_in_scope",
+    description: "List decision summaries whose scope_globs overlap any of the given path_globs.",
+    inputSchema: decisionsInScopeInput,
+    handler,
+};
+//# sourceMappingURL=decisions-in-scope.js.map

package/dist/mcp/tools/decisions-in-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions-in-scope.js","sourceRoot":"","sources":["../../../src/mcp/tools/decisions-in-scope.ts"],"names":[],"mappings":"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"}