@isaacriehm/cairn-core 0.1.0

package/dist/hooks/post-tool-use/copy-scanner.js

@@ -0,0 +1,192 @@
+/**
+ * Copy-safety scanner for the PostToolUse Write/Edit guardian.
+ *
+ * Given a file path and its (post-Write/Edit) content, locate strings
+ * that look like internal-only copy leaking into a user-facing surface
+ * (TODO/FIXME comments inside JSX text, cairn citations, snake_case
+ * identifiers in display strings, internal repo paths, etc.).
+ *
+ * Implementation is intentionally regex-only — NOT a full AST. For
+ * `.tsx`/`.jsx` we extract the contents of string/template literals and
+ * the text between `>` and `<`/`{` in JSX. For `.json` we walk values
+ * (skipping keys). For `.html`/`.vue`/`.svelte` and any other extension
+ * we scan the entire content.
+ *
+ * Spec: docs/READ_ENRICHER_SPEC.md "Write Guardian" section.
+ */
+const PATTERNS = [
+    { regex: /\b(TODO|FIXME|HACK|XXX|TEMP|WIP)\b/g, label: "comment-marker" },
+    { regex: /§V\d+/g, label: "cairn-citation-§V" },
+    { regex: /\bTSK-[a-z0-9-]+\b/g, label: "cairn-citation-TSK" },
+    { regex: /\[(PLACEHOLDER|TODO|DRAFT)\]/g, label: "draft-marker" },
+    {
+        regex: /\b[a-z][a-z0-9]*(?:_[a-z0-9]+){2,}\b/g,
+        label: "multi-underscore-identifier",
+    },
+    // Internal path: matches a leading separator (start, whitespace, quote, or
+    // backtick) followed by `src/` | `packages/` | `.cairn/`. The whole
+    // match is recorded verbatim (including the leading char) so allowlist
+    // authoring is consistent — see scanForCopyLeakage callers.
+    {
+        regex: /(?:^|[\s"'`])(src\/|packages\/|\.cairn\/)/g,
+        label: "internal-path",
+    },
+];
+/**
+ * Compute 1-indexed line number of an absolute character index within `content`.
+ */
+function lineForIndex(content, absIndex) {
+    let line = 1;
+    const cap = Math.min(absIndex, content.length);
+    for (let i = 0; i < cap; i++) {
+        if (content.charCodeAt(i) === 0x0a)
+            line++;
+    }
+    return line;
+}
+function getExt(filePath) {
+    const lastSlash = filePath.lastIndexOf("/");
+    const tail = lastSlash >= 0 ? filePath.slice(lastSlash + 1) : filePath;
+    const dot = tail.lastIndexOf(".");
+    if (dot < 0)
+        return "";
+    return tail.slice(dot).toLowerCase();
+}
+/**
+ * For .tsx/.jsx: extract regions worth scanning — the inside of every
+ * single-quote, double-quote, and backtick literal, plus JSX text
+ * positions. Strict correctness vs. a real parser is not the goal; we
+ * accept some false positives (e.g. matches inside non-display strings)
+ * — the allowlist is the escape valve.
+ */
+function jsxRegions(content) {
+    const regions = [];
+    // Capture string and template literal contents.
+    const literalRe = /(['"`])((?:\\.|(?!\1)[\s\S])*)\1/g;
+    for (const m of content.matchAll(literalRe)) {
+        const inner = m[2];
+        if (typeof inner !== "string" || inner.length === 0)
+            continue;
+        if (m.index === undefined)
+            continue;
+        // +1 to skip past the opening quote/backtick to where `inner` starts.
+        regions.push({ text: inner, baseOffset: m.index + 1 });
+    }
+    // Capture JSX text positions — `>...<` and `>...{` runs.
+    const jsxTextRe = />([^<{]+)</g;
+    for (const m of content.matchAll(jsxTextRe)) {
+        const inner = m[1];
+        if (typeof inner !== "string" || inner.length === 0)
+            continue;
+        if (m.index === undefined)
+            continue;
+        regions.push({ text: inner, baseOffset: m.index + 1 });
+    }
+    return regions;
+}
+/**
+ * For .json: walk parsed values (NOT keys). On parse failure, fall back
+ * to a regex over `: "..."` value-position strings.
+ */
+function jsonRegions(content) {
+    const regions = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed !== undefined) {
+        const stringValues = [];
+        const visit = (node) => {
+            if (typeof node === "string") {
+                stringValues.push(node);
+                return;
+            }
+            if (Array.isArray(node)) {
+                for (const v of node)
+                    visit(v);
+                return;
+            }
+            if (node !== null && typeof node === "object") {
+                for (const v of Object.values(node))
+                    visit(v);
+            }
+        };
+        visit(parsed);
+        // For each string value, locate its first occurrence as a JSON
+        // value-position substring (`"<value>"`) for accurate line numbers.
+        for (const sv of stringValues) {
+            if (sv.length === 0)
+                continue;
+            // Best-effort: search for the literal value enclosed in quotes.
+            // Simple identity match — JSON-escape sequences may shift, but
+            // the line number derived will still point at the right block in
+            // practice. False positives here just produce slightly wrong
+            // lines, never wrong matches.
+            const escaped = JSON.stringify(sv);
+            const idx = content.indexOf(escaped);
+            if (idx < 0)
+                continue;
+            regions.push({ text: sv, baseOffset: idx + 1 });
+        }
+        return regions;
+    }
+    // Fallback: regex over value-position strings.
+    const valueRe = /:\s*"((?:\\.|[^"\\])*)"/g;
+    for (const m of content.matchAll(valueRe)) {
+        const inner = m[1];
+        if (typeof inner !== "string" || inner.length === 0)
+            continue;
+        if (m.index === undefined)
+            continue;
+        // Locate the offset of the captured value's opening quote.
+        const matchText = m[0];
+        const quoteIdx = matchText.indexOf('"');
+        if (quoteIdx < 0)
+            continue;
+        regions.push({ text: inner, baseOffset: m.index + quoteIdx + 1 });
+    }
+    return regions;
+}
+function scanRegion(region, content, out) {
+    for (const { regex, label } of PATTERNS) {
+        // Each pattern uses /g; reset lastIndex via fresh matchAll on the slice.
+        for (const m of region.text.matchAll(regex)) {
+            if (m.index === undefined)
+                continue;
+            const matchText = m[0];
+            if (matchText.length === 0)
+                continue;
+            const absIndex = region.baseOffset + m.index;
+            out.push({
+                line: lineForIndex(content, absIndex),
+                match: matchText,
+                pattern: label,
+            });
+        }
+    }
+}
+export function scanForCopyLeakage(content, filePath) {
+    if (content.length === 0)
+        return [];
+    const ext = getExt(filePath);
+    const issues = [];
+    let regions;
+    if (ext === ".tsx" || ext === ".jsx") {
+        regions = jsxRegions(content);
+    }
+    else if (ext === ".json") {
+        regions = jsonRegions(content);
+    }
+    else {
+        // .html, .vue, .svelte, and default fallback — scan everything.
+        regions = [{ text: content, baseOffset: 0 }];
+    }
+    for (const region of regions) {
+        scanRegion(region, content, issues);
+    }
+    return issues;
+}
+//# sourceMappingURL=copy-scanner.js.map

package/dist/hooks/post-tool-use/copy-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-scanner.js","sourceRoot":"","sources":["../../../src/hooks/post-tool-use/copy-scanner.ts"],"names":[],"mappings":"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"}

package/dist/hooks/post-tool-use/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PostToolUse hook handlers.
+ *
+ * Exposes the Read enricher (`runReadEnricher`), the Write guardian
+ * (`runWriteGuardian`), and their shared helpers.
+ * Spec: docs/READ_ENRICHER_SPEC.md.
+ */
+export { runReadEnricher } from "./read-enricher.js";
+export { scanCitations } from "./citation-scanner.js";
+export type { ScannedCitations, CitationMatch } from "./citation-scanner.js";
+export { getInvariantsLedger, getScopeIndexEntry, lookupTask, } from "./ledger-cache.js";
+export type { LedgerSnapshot, ScopeIndexEntry, TaskLookupResult, } from "./ledger-cache.js";
+export { buildLegend } from "./legend-builder.js";
+export type { ScopeIndexHint } from "./legend-builder.js";
+export { runWriteGuardian } from "./write-guardian.js";
+export { scanForCopyLeakage } from "./copy-scanner.js";
+export type { CopyIssue } from "./copy-scanner.js";
+export { readCopySafetyConfig } from "./allowlist-reader.js";
+export type { CopySafetyConfig } from "./allowlist-reader.js";

package/dist/hooks/post-tool-use/index.js

@@ -0,0 +1,15 @@
+/**
+ * PostToolUse hook handlers.
+ *
+ * Exposes the Read enricher (`runReadEnricher`), the Write guardian
+ * (`runWriteGuardian`), and their shared helpers.
+ * Spec: docs/READ_ENRICHER_SPEC.md.
+ */
+export { runReadEnricher } from "./read-enricher.js";
+export { scanCitations } from "./citation-scanner.js";
+export { getInvariantsLedger, getScopeIndexEntry, lookupTask, } from "./ledger-cache.js";
+export { buildLegend } from "./legend-builder.js";
+export { runWriteGuardian } from "./write-guardian.js";
+export { scanForCopyLeakage } from "./copy-scanner.js";
+export { readCopySafetyConfig } from "./allowlist-reader.js";
+//# sourceMappingURL=index.js.map

package/dist/hooks/post-tool-use/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/post-tool-use/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/hooks/post-tool-use/ledger-cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-process LRU cache (max 1 entry) for the invariants ledger and
+ * task-status lookups consumed by the read-enricher hook. All disk
+ * reads here are best-effort: any failure returns null/not_found so
+ * the hook stays a no-op.
+ */
+import { type ScopeIndexEntry } from "../../ground/scope-index.js";
+export type { ScopeIndexEntry } from "../../ground/scope-index.js";
+export interface LedgerSnapshot {
+    invariantsByid: Map<string, {
+        title: string;
+        status: string;
+        superseded_by?: string;
+    }>;
+}
+export interface TaskLookupResult {
+    found: "active" | "done" | "not_found";
+    title?: string;
+}
+export declare function getInvariantsLedger(repoRoot: string): LedgerSnapshot | null;
+export declare function lookupTask(repoRoot: string, taskId: string): TaskLookupResult;
+/**
+ * Cached scope-index reader. Content-keyed (sha256 of first 512 bytes) so
+ * back-to-back hook invocations in the same process don't re-parse the file
+ * AND so daemon writes that happen within the same mtime tick are not
+ * silently masked by a stale cache hit (Gap 6 in BUILD_REPORT).
+ *
+ * Returns null when the file is missing, when no entry matches the path,
+ * when the entry is explicitly `unscoped: true`, or when the entry has no
+ * decisions/invariants — i.e., when there is nothing useful to surface.
+ */
+export declare function getScopeIndexEntry(repoRoot: string, repoRelativePath: string): ScopeIndexEntry | null;

package/dist/hooks/post-tool-use/ledger-cache.js

@@ -0,0 +1,236 @@
+/**
+ * Per-process LRU cache (max 1 entry) for the invariants ledger and
+ * task-status lookups consumed by the read-enricher hook. All disk
+ * reads here are best-effort: any failure returns null/not_found so
+ * the hook stays a no-op.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, openSync, readFileSync, readSync, closeSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { lookupScope, readScopeIndex, scopeIndexPath, } from "../../ground/scope-index.js";
+const SCOPE_INDEX_HASH_BYTES = 512;
+/**
+ * Hash the first N bytes of a file. Returns null when the file can't be read.
+ * Used as the cache key for scope-index — mtime is unreliable under clock skew
+ * (daemon writes can land with the same mtime as the previous read).
+ */
+function hashFilePrefix(path, bytes) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const buf = Buffer.alloc(bytes);
+        const read = readSync(fd, buf, 0, bytes, 0);
+        return createHash("sha256")
+            .update(buf.subarray(0, read))
+            .digest("hex");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // ignore — best-effort
+        }
+    }
+}
+let invariantsCache = null;
+let activeTasksCache = null;
+let doneTasksCache = null;
+let scopeIndexCache = null;
+function invariantsLedgerFile(repoRoot) {
+    return join(repoRoot, ".cairn", "ground", "invariants", "invariants.ledger.yaml");
+}
+export function getInvariantsLedger(repoRoot) {
+    const path = invariantsLedgerFile(repoRoot);
+    if (!existsSync(path))
+        return null;
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+    if (invariantsCache !== null &&
+        invariantsCache.repoRoot === repoRoot &&
+        invariantsCache.mtimeMs === mtimeMs) {
+        return invariantsCache.snapshot;
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed))
+        return null;
+    const map = new Map();
+    for (const raw of parsed) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const r = raw;
+        const id = typeof r["id"] === "string" ? r["id"] : null;
+        const title = typeof r["title"] === "string" ? r["title"] : "";
+        const status = typeof r["status"] === "string" ? r["status"] : "active";
+        const supersededByRaw = r["superseded_by"];
+        const supersededBy = typeof supersededByRaw === "string" && supersededByRaw.length > 0
+            ? supersededByRaw
+            : undefined;
+        if (id === null)
+            continue;
+        map.set(id, {
+            title,
+            status,
+            ...(supersededBy !== undefined ? { superseded_by: supersededBy } : {}),
+        });
+    }
+    const snapshot = { invariantsByid: map };
+    invariantsCache = { repoRoot, mtimeMs, snapshot };
+    return snapshot;
+}
+function tasksScopeDir(repoRoot, scope) {
+    return join(repoRoot, ".cairn", "tasks", scope);
+}
+function readDirMtime(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+function extractTitle(taskDir) {
+    const candidates = [
+        join(taskDir, "spec.tightened.md"),
+        join(taskDir, "spec.md"),
+    ];
+    for (const c of candidates) {
+        if (!existsSync(c))
+            continue;
+        try {
+            const text = readFileSync(c, "utf8");
+            const m = text.match(/^#\s+(.+)$/m);
+            if (m && typeof m[1] === "string")
+                return m[1].trim();
+        }
+        catch {
+            // ignore — try next candidate
+        }
+    }
+    return "";
+}
+function resolveCacheForScope(repoRoot, scope) {
+    const dir = tasksScopeDir(repoRoot, scope);
+    const mtimeMs = readDirMtime(dir);
+    if (mtimeMs === null)
+        return null;
+    const cache = scope === "active" ? activeTasksCache : doneTasksCache;
+    if (cache !== null &&
+        cache.repoRoot === repoRoot &&
+        cache.scope === scope &&
+        cache.mtimeMs === mtimeMs) {
+        return cache;
+    }
+    // Lazy: don't pre-walk all task dirs. We populate `titles` on demand
+    // in `lookupTask`. Empty map keyed to current dir mtime is fine.
+    const fresh = {
+        repoRoot,
+        scope,
+        mtimeMs,
+        titles: new Map(),
+    };
+    if (scope === "active")
+        activeTasksCache = fresh;
+    else
+        doneTasksCache = fresh;
+    return fresh;
+}
+export function lookupTask(repoRoot, taskId) {
+    // Active first.
+    const activeDir = tasksScopeDir(repoRoot, "active");
+    const activeTaskDir = join(activeDir, taskId);
+    if (existsSync(activeTaskDir)) {
+        const cache = resolveCacheForScope(repoRoot, "active");
+        if (cache !== null) {
+            let title = cache.titles.get(taskId);
+            if (title === undefined) {
+                title = extractTitle(activeTaskDir);
+                cache.titles.set(taskId, title);
+            }
+            return title.length > 0
+                ? { found: "active", title }
+                : { found: "active" };
+        }
+        // Couldn't cache, but the dir is present.
+        const title = extractTitle(activeTaskDir);
+        return title.length > 0 ? { found: "active", title } : { found: "active" };
+    }
+    const doneDir = tasksScopeDir(repoRoot, "done");
+    const doneTaskDir = join(doneDir, taskId);
+    if (existsSync(doneTaskDir)) {
+        const cache = resolveCacheForScope(repoRoot, "done");
+        if (cache !== null) {
+            let title = cache.titles.get(taskId);
+            if (title === undefined) {
+                title = extractTitle(doneTaskDir);
+                cache.titles.set(taskId, title);
+            }
+            return title.length > 0 ? { found: "done", title } : { found: "done" };
+        }
+        const title = extractTitle(doneTaskDir);
+        return title.length > 0 ? { found: "done", title } : { found: "done" };
+    }
+    return { found: "not_found" };
+}
+/**
+ * Cached scope-index reader. Content-keyed (sha256 of first 512 bytes) so
+ * back-to-back hook invocations in the same process don't re-parse the file
+ * AND so daemon writes that happen within the same mtime tick are not
+ * silently masked by a stale cache hit (Gap 6 in BUILD_REPORT).
+ *
+ * Returns null when the file is missing, when no entry matches the path,
+ * when the entry is explicitly `unscoped: true`, or when the entry has no
+ * decisions/invariants — i.e., when there is nothing useful to surface.
+ */
+export function getScopeIndexEntry(repoRoot, repoRelativePath) {
+    const path = scopeIndexPath(repoRoot);
+    if (!existsSync(path))
+        return null;
+    const contentHash = hashFilePrefix(path, SCOPE_INDEX_HASH_BYTES);
+    if (contentHash === null)
+        return null;
+    let index;
+    if (scopeIndexCache !== null &&
+        scopeIndexCache.repoRoot === repoRoot &&
+        scopeIndexCache.contentHash === contentHash) {
+        index = scopeIndexCache.index;
+    }
+    else {
+        const fresh = readScopeIndex(repoRoot);
+        if (fresh === null)
+            return null;
+        scopeIndexCache = { repoRoot, contentHash, index: fresh };
+        index = fresh;
+    }
+    const entry = lookupScope(index, repoRelativePath);
+    if (entry === null)
+        return null;
+    if (entry.unscoped === true)
+        return null;
+    if (entry.decisions.length === 0 && entry.invariants.length === 0)
+        return null;
+    return entry;
+}
+//# sourceMappingURL=ledger-cache.js.map

package/dist/hooks/post-tool-use/ledger-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-cache.js","sourceRoot":"","sources":["../../../src/hooks/post-tool-use/ledger-cache.ts"],"names":[],"mappings":"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"}

package/dist/hooks/post-tool-use/legend-builder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Renders the boxed citation legend that the read-enricher prepends to
+ * the agent's view via Shape-B `additionalContext`. Per
+ * READ_ENRICHER_SPEC §6.1 the legend includes a scope-index header
+ * (decisions/invariants in scope) when one was found for the file.
+ */
+import type { ScannedCitations } from "./citation-scanner.js";
+import type { LedgerSnapshot, TaskLookupResult } from "./ledger-cache.js";
+export interface ScopeIndexHint {
+    /** DEC-IDs in scope for the file. */
+    decisions: string[];
+    /** Invariant IDs in scope (e.g. "V0041"). */
+    invariants: string[];
+}
+export declare function buildLegend(matches: ScannedCitations, ledger: LedgerSnapshot | null, scopeHint: ScopeIndexHint | null, resolveTask: (taskId: string) => TaskLookupResult): string | null;

package/dist/hooks/post-tool-use/legend-builder.js

@@ -0,0 +1,84 @@
+/**
+ * Renders the boxed citation legend that the read-enricher prepends to
+ * the agent's view via Shape-B `additionalContext`. Per
+ * READ_ENRICHER_SPEC §6.1 the legend includes a scope-index header
+ * (decisions/invariants in scope) when one was found for the file.
+ */
+const TOP_BORDER = "┌─ cairn citations ────────────────────────────┐";
+const BOTTOM_BORDER = "└───────────────────────────────────────────┘";
+const SIDE = "│";
+function row(content) {
+    return `${SIDE} ${content}`;
+}
+export function buildLegend(matches, ledger, scopeHint, resolveTask) {
+    const hasScopeHint = scopeHint !== null &&
+        (scopeHint.decisions.length > 0 || scopeHint.invariants.length > 0);
+    const hasCitations = matches.invariants.length > 0 ||
+        matches.todos.length > 0 ||
+        matches.decIds.length > 0;
+    if (!hasScopeHint && !hasCitations)
+        return null;
+    const lines = [];
+    lines.push(TOP_BORDER);
+    if (scopeHint !== null &&
+        Array.isArray(scopeHint.decisions) &&
+        scopeHint.decisions.length > 0) {
+        lines.push(row(`Decisions in scope: ${scopeHint.decisions.join(", ")}`));
+    }
+    if (scopeHint !== null &&
+        Array.isArray(scopeHint.invariants) &&
+        scopeHint.invariants.length > 0) {
+        const formatted = scopeHint.invariants
+            .map((v) => (v.startsWith("§") ? v : `§${v}`))
+            .join(", ");
+        lines.push(row(`Invariants in scope: ${formatted}`));
+    }
+    for (const inv of matches.invariants) {
+        lines.push(row(renderInvariant(inv.id, ledger)));
+    }
+    for (const todo of matches.todos) {
+        lines.push(row(renderTodo(todo.id, resolveTask(todo.id))));
+    }
+    for (const dec of matches.decIds) {
+        lines.push(row(`${dec.id} → [POLICY VIOLATION — DEC-id comments banned]`));
+    }
+    lines.push(BOTTOM_BORDER);
+    return lines.join("\n");
+}
+function renderInvariant(id, ledger) {
+    // id arrives as "V0023" — display with the §-prefix.
+    const label = `§${id}`;
+    if (ledger === null) {
+        return `${label} → [NOT FOUND — orphaned citation, GC will flag]`;
+    }
+    const entry = ledger.invariantsByid.get(id);
+    if (!entry) {
+        return `${label} → [NOT FOUND — orphaned citation, GC will flag]`;
+    }
+    if (entry.superseded_by !== undefined && entry.superseded_by.length > 0) {
+        const sup = entry.superseded_by.startsWith("V")
+            ? `§${entry.superseded_by}`
+            : entry.superseded_by;
+        return `${label} → [SUPERSEDED by ${sup} — update this citation]`;
+    }
+    if (entry.status === "superseded") {
+        return `${label} → [SUPERSEDED — update this citation]`;
+    }
+    const title = entry.title.length > 0 ? entry.title : "(no title)";
+    return `${label} → ${title}  [active]`;
+}
+function renderTodo(id, result) {
+    // id arrives as "TSK-<id>" — display in the TODO(...) form.
+    const label = `TODO(${id})`;
+    if (result.found === "not_found") {
+        return `${label} → [NOT FOUND]`;
+    }
+    const title = result.title !== undefined && result.title.length > 0
+        ? result.title
+        : id;
+    if (result.found === "done") {
+        return `${label} → ${title}  [DONE — this TODO can be removed]`;
+    }
+    return `${label} → ${title}  [active]`;
+}
+//# sourceMappingURL=legend-builder.js.map

package/dist/hooks/post-tool-use/legend-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend-builder.js","sourceRoot":"","sources":["../../../src/hooks/post-tool-use/legend-builder.ts"],"names":[],"mappings":"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"}

package/dist/hooks/post-tool-use/read-enricher.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `cairn hook read-enrich` — PostToolUse hook on the Read tool.
+ *
+ * Scans the file content the agent just read for cairn citation
+ * patterns (`§V<N>`, `TODO(TSK-<id>)`, banned `DEC-<N>`) and prepends a
+ * legend block via Claude Code's documented Shape-B `additionalContext`
+ * field so the agent sees authoritative resolutions inline with the
+ * file content. No MCP round-trip; all sources read directly from
+ * `.cairn/` on disk.
+ *
+ * Spec: docs/READ_ENRICHER_SPEC.md
+ */
+export declare function runReadEnricher(): Promise<void>;