@isaacriehm/cairn-core 0.1.10 → 0.3.0

package/dist/hooks/runners/stop.js

@@ -1,28 +1,44 @@
 /**
  * `Stop` hook runner — fires when the assistant turn ends.
  *
- * Current scope:
- *   • Drain `.cairn/events/` since the per-session marker; stamp the
- *     poll cursor so the next Stop only sees newer events.
- *   • Scan `.cairn/tasks/active/<id>/` for tasks that have a
- *     tightened spec but no `attestation.yaml`; surface a reviewer-
- *     spawn hint in additionalContext so main Claude can spawn the
- *     reviewer subagent on the next assistant turn.
- *   • Patch the per-session status.json `updated_at` (heartbeat).
+ * Per PLUGIN_ARCHITECTURE §10:
+ *   • Drains `.cairn/events/` since the per-session marker.
+ *   • Scans `.cairn/tasks/active/<id>/` for tasks missing attestation.yaml.
+ *   • Compares HEAD's last 5 commits against `.cairn/.attested-commits`;
+ *     surfaces bypass hint for `--no-verify` commits.
+ *   • Patches per-session status.json `updated_at` (heartbeat).
  *
- * Future scope (steps 7–8 per PLUGIN_ARCHITECTURE §10):
- *   • Run sensors on staged + unstaged diff; surface findings inline.
- *   • Compare HEAD's last 5 commits against `.attested-commits` marker;
- *     surface backfill prompt for `--no-verify` bypasses.
+ * When context to surface: emits `{ decision: "block", reason: "..." }` so
+ * Claude reads the hint and invokes cairn-attention on the next turn.
+ * When nothing: emits `{ continue: true }` and Claude stops normally.
  */
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { readActiveTaskSummary } from "../../context/index.js";
 import { eventsSince, } from "../../events/index.js";
 import { renderBypassHint, scanBypassedCommits, } from "../bypass-detection.js";
+import { isDeferActive, readDeferState } from "../defer.js";
 import { resolveRepoRoot } from "../../session-start/index.js";
 import { readEventsMarker, stampEventsPoll, } from "../../session/index.js";
 import { writeStatusJson } from "../../status-line/index.js";
 import { emitShapeB, parseHookPayload, readHookStdin, recordHookTelemetry, } from "./payload.js";
+/** Init in progress means `.cairn/init-state.json` exists at repoRoot. */
+function isInitInProgress(repoRoot) {
+    return existsSync(join(repoRoot, ".cairn", "init-state.json"));
+}
+/**
+ * Cap the reason text that flows back to Claude Code via decision:block.
+ * Both the reviewer hint and the bypass hint can fire on the same Stop
+ * tick; 4 KB is generous for two A/B/C strips but small enough that
+ * overflow is structurally impossible.
+ */
+const MAX_REASON_CHARS = 4_000;
+function clampReason(body) {
+    if (body.length <= MAX_REASON_CHARS)
+        return body;
+    const head = body.slice(0, MAX_REASON_CHARS - 80);
+    return `${head}\n\n…(truncated; resolve via cairn-attention)`;
+}
 export async function runStopHook() {
     const startedAt = Date.now();
     const raw = await readHookStdin();
@@ -34,7 +50,7 @@ export async function runStopHook() {
     let drained = [];
     let pendingReviews = [];
     let bypassed = [];
-    let additionalContext = "";
+    let reason = "";
     if (repoRoot !== null && sessionId !== null && sessionId.length > 0) {
         try {
             const marker = readEventsMarker(repoRoot, sessionId);
@@ -49,42 +65,83 @@ export async function runStopHook() {
         catch (err) {
             warnings.push(`events_poll_failed: ${err instanceof Error ? err.message : String(err)}`);
         }
-        try {
-            pendingReviews = scanPendingReviews(repoRoot);
-            if (pendingReviews.length > 0) {
-                additionalContext = renderReviewerHint(pendingReviews);
-            }
+        const now = new Date();
+        // Suppress reviewer + bypass surfaces while init is mid-flight —
+        // `.cairn/.attested-commits` may not yet be seeded, and the
+        // adoption skill owns the operator's attention until phase 12
+        // returns nextPhase=null. The MCP init-phases tool clears the
+        // state file as soon as the final phase completes, after which
+        // the next Stop tick scans normally.
+        const initInProgress = isInitInProgress(repoRoot);
+        if (initInProgress) {
+            warnings.push("init_in_progress:scans_suppressed");
         }
-        catch (err) {
-            warnings.push(`pending_review_scan_failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        try {
-            const bypassResult = scanBypassedCommits(repoRoot);
-            bypassed = bypassResult.bypassed;
-            if (bypassed.length > 0) {
-                const hint = renderBypassHint(bypassed);
-                additionalContext = additionalContext.length > 0
-                    ? `${additionalContext}\n\n${hint}`
-                    : hint;
+        if (!initInProgress) {
+            try {
+                pendingReviews = scanPendingReviews(repoRoot);
+                if (pendingReviews.length > 0) {
+                    const reviewDefer = readDeferState(repoRoot, "review");
+                    const suppressed = reviewDefer !== null &&
+                        isDeferActive(reviewDefer, now, {
+                            kind: "task_ids",
+                            values: pendingReviews.map((p) => p.task_id),
+                        });
+                    if (suppressed) {
+                        warnings.push(`review_suppressed_until:${reviewDefer.deferred_at}`);
+                    }
+                    else {
+                        reason = renderReviewerHint(pendingReviews);
+                    }
+                }
+            }
+            catch (err) {
+                warnings.push(`pending_review_scan_failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                const bypassResult = scanBypassedCommits(repoRoot);
+                bypassed = bypassResult.bypassed;
+                if (bypassed.length > 0) {
+                    const bypassDefer = readDeferState(repoRoot, "bypass");
+                    const suppressed = bypassDefer !== null &&
+                        isDeferActive(bypassDefer, now, {
+                            kind: "shas",
+                            values: bypassed.map((b) => b.sha),
+                        });
+                    if (suppressed) {
+                        warnings.push(`bypass_suppressed_until:${bypassDefer.deferred_at}`);
+                    }
+                    else {
+                        const hint = renderBypassHint(bypassed);
+                        reason = reason.length > 0 ? `${reason}\n\n${hint}` : hint;
+                    }
+                }
+            }
+            catch (err) {
+                warnings.push(`bypass_scan_failed: ${err instanceof Error ? err.message : String(err)}`);
             }
-        }
-        catch (err) {
-            warnings.push(`bypass_scan_failed: ${err instanceof Error ? err.message : String(err)}`);
         }
         try {
+            const active = readActiveTaskSummary(repoRoot);
             writeStatusJson(repoRoot, sessionId, {
                 updated_at: new Date().toISOString(),
+                task_state: active?.taskState ?? "idle",
+                task_id: active?.taskId ?? null,
+                task_module: active?.taskModule ?? null,
+                bypass_count: bypassed.length,
             });
         }
         catch (err) {
             warnings.push(`status_heartbeat_failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // Claude Code's Stop hook schema rejects hookSpecificOutput. Surface
-    // text via the top-level systemMessage field; empty payload is fine.
-    const out = { continue: true };
-    if (additionalContext.length > 0)
-        out.systemMessage = additionalContext;
+    // Stop hook uses decision:block+reason to inject context into Claude
+    // (Stop does not support hookSpecificOutput.additionalContext — that
+    // field is silently ignored by Claude Code for Stop events). When
+    // reason is non-empty, blocking keeps the session alive so Claude
+    // reads the reason and acts on it (e.g. invokes cairn-attention).
+    const out = reason.length > 0
+        ? { decision: "block", reason: clampReason(reason) }
+        : { continue: true };
     emitShapeB(out);
     recordHookTelemetry({
         hook: "stop",
@@ -97,6 +154,8 @@ export async function runStopHook() {
             events_drained: drained.length,
             pending_reviews: pendingReviews.length,
             bypassed_commits: bypassed.length,
+            decision: reason.length > 0 ? "block" : "continue",
+            ...(reason.length > 0 ? { reason } : {}),
         },
     });
 }
@@ -109,6 +168,30 @@ export async function runStopHook() {
  * Older orphans are stale; the operator deals with them via attention
  * rather than spawning reviewers blindly.
  */
+// Phases a task moves through. The reviewer-attestation prompt only
+// fires for tasks that are explicitly ready for review — a fresh
+// `running` task has work in flight, no reviewer needed yet.
+const REVIEW_READY_PHASES = new Set(["ready_for_review", "awaiting_attestation"]);
+function readTaskPhase(taskDir) {
+    const statusPath = join(taskDir, "status.yaml");
+    if (!existsSync(statusPath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(statusPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    // Cheap line scan — `phase: <value>` at top-level. Avoid a full
+    // YAML parse (this runs on every Stop tick).
+    for (const line of raw.split(/\r?\n/)) {
+        const m = line.match(/^phase:\s*(\S+)/);
+        if (m && m[1] !== undefined)
+            return m[1].replace(/['"]/g, "");
+    }
+    return null;
+}
 function scanPendingReviews(repoRoot) {
     const activeDir = join(repoRoot, ".cairn", "tasks", "active");
     if (!existsSync(activeDir))
@@ -133,6 +216,10 @@ function scanPendingReviews(repoRoot) {
         const attestation = join(taskDir, "attestation.yaml");
         if (existsSync(attestation))
             continue;
+        // Phase gate — `running` / `tightening` / etc. are not review-ready.
+        const phase = readTaskPhase(taskDir);
+        if (phase !== null && !REVIEW_READY_PHASES.has(phase))
+            continue;
         let mtime = 0;
         try {
             mtime = statSync(tightenedSpec).mtimeMs;
@@ -151,13 +238,14 @@ function scanPendingReviews(repoRoot) {
 }
 function renderReviewerHint(pending) {
     const lines = [];
-    lines.push(`## Reviewer pending (${pending.length} task${pending.length === 1 ? "" : "s"})`);
+    const noun = pending.length === 1 ? "task" : "tasks";
+    lines.push(`## Cairn — ${pending.length} ${noun} awaiting review attestation`);
     lines.push("");
     for (const p of pending) {
-        lines.push(`- **${p.task_id}** — ${p.spec_path}`);
+        lines.push(`- \`${p.task_id}\``);
     }
     lines.push("");
-    lines.push("Spawn the `reviewer` subagent (defined at `agents/reviewer.md` in the cairn plugin) via the Task tool to attest each pending task. The subagent reads the diff, collects subagent attestation files, extracts non-obvious DECs, and writes the consolidated `attestation.yaml`. Once written, this hook will stop surfacing the reminder.");
+    lines.push("Invoke the `cairn-attention` skill on the next turn so the operator can pick run review / skip / defer through `AskUserQuestion`.");
     return lines.join("\n");
 }
 //# sourceMappingURL=stop.js.map

package/dist/hooks/runners/stop.js.map

@@ -1 +1 @@
-{"version":3,"file":"stop.js","sourceRoot":"","sources":["../../../src/hooks/runners/stop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stop.js","sourceRoot":"","sources":["../../../src/hooks/runners/stop.ts"],"names":[],"mappings":"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"}

package/dist/hooks/runners/user-prompt-submit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `cairn hook user-prompt-submit` — UserPromptSubmit hook.
+ *
+ * Claude Code's `@<path>` shorthand attaches file content to the
+ * prompt directly, BYPASSING the Read tool — so the
+ * PostToolUse(Read) read-enricher hook never fires for those files.
+ * This hook fills the gap: it parses `@<path>` patterns from the
+ * raw prompt, reads each file, scans for §INV-/§DEC-/TODO(TSK-)
+ * citations, builds the same legend the read-enricher would have,
+ * and emits it as `additionalContext`. Result: the model sees
+ * the resolved citations alongside the attached file content,
+ * matching the documented "bare symbols always resolve on Read"
+ * contract regardless of attachment path.
+ */
+export declare function runUserPromptSubmitHook(): Promise<void>;

package/dist/hooks/runners/user-prompt-submit.js

@@ -0,0 +1,149 @@
+/**
+ * `cairn hook user-prompt-submit` — UserPromptSubmit hook.
+ *
+ * Claude Code's `@<path>` shorthand attaches file content to the
+ * prompt directly, BYPASSING the Read tool — so the
+ * PostToolUse(Read) read-enricher hook never fires for those files.
+ * This hook fills the gap: it parses `@<path>` patterns from the
+ * raw prompt, reads each file, scans for §INV-/§DEC-/TODO(TSK-)
+ * citations, builds the same legend the read-enricher would have,
+ * and emits it as `additionalContext`. Result: the model sees
+ * the resolved citations alongside the attached file content,
+ * matching the documented "bare symbols always resolve on Read"
+ * contract regardless of attachment path.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { resolveRepoRoot } from "../../session-start/index.js";
+import { scanCitations } from "../post-tool-use/citation-scanner.js";
+import { getDecisionsLedger, getInvariantsLedger, getScopeIndexEntry, lookupTask, } from "../post-tool-use/ledger-cache.js";
+import { buildLegend } from "../post-tool-use/legend-builder.js";
+import { readHookStdin } from "./payload.js";
+const MAX_FILE_BYTES = 512_000;
+// Match `@<path>` only when `@` follows whitespace or is at start of
+// prompt — filters out emails, twitter-style mentions, etc. Path
+// chars: word, dot, slash, hyphen.
+const AT_PATH_RE = /(?:^|\s)@([\w./-]+)/g;
+function parsePayload(text) {
+    if (text.trim().length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function emitShapeB(additionalContext) {
+    const out = {
+        continue: true,
+        hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext,
+        },
+    };
+    process.stdout.write(JSON.stringify(out));
+    process.stdout.write("\n");
+}
+function extractAttachedPaths(prompt) {
+    const out = [];
+    for (const m of prompt.matchAll(AT_PATH_RE)) {
+        const p = m[1];
+        if (typeof p === "string" && p.length > 0)
+            out.push(p);
+    }
+    return out;
+}
+function safeRead(absPath) {
+    if (!existsSync(absPath))
+        return null;
+    try {
+        const buf = readFileSync(absPath, "utf8");
+        if (buf.length > MAX_FILE_BYTES)
+            return buf.slice(0, MAX_FILE_BYTES);
+        return buf;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runUserPromptSubmitHook() {
+    try {
+        const raw = await readHookStdin();
+        const payload = parsePayload(raw);
+        const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+        const cwd = typeof payload.cwd === "string" ? payload.cwd : process.cwd();
+        // Fast-path: no `@` token in prompt → no work.
+        if (prompt.length === 0 || !prompt.includes("@")) {
+            emitShapeB("");
+            return;
+        }
+        const repoRoot = resolveRepoRoot(cwd);
+        if (repoRoot === null) {
+            emitShapeB("");
+            return;
+        }
+        const paths = extractAttachedPaths(prompt);
+        if (paths.length === 0) {
+            emitShapeB("");
+            return;
+        }
+        // Aggregate citations across all attached files. Filter to existing
+        // files — non-existent `@`-mentions are typically not file refs.
+        const aggregated = {
+            invariants: [],
+            todos: [],
+            decisions: [],
+        };
+        let firstHitRel = null;
+        for (const p of paths) {
+            const abs = isAbsolute(p) ? p : resolve(repoRoot, p);
+            const content = safeRead(abs);
+            if (content === null)
+                continue;
+            const matches = scanCitations(content);
+            const hit = matches.invariants.length > 0 ||
+                matches.todos.length > 0 ||
+                matches.decisions.length > 0;
+            if (!hit)
+                continue;
+            if (firstHitRel === null) {
+                const rel = relative(repoRoot, abs);
+                if (!rel.startsWith("..") && rel.length > 0) {
+                    firstHitRel = rel.replace(/\\/g, "/");
+                }
+            }
+            aggregated.invariants.push(...matches.invariants);
+            aggregated.todos.push(...matches.todos);
+            aggregated.decisions.push(...matches.decisions);
+        }
+        if (aggregated.invariants.length === 0 &&
+            aggregated.todos.length === 0 &&
+            aggregated.decisions.length === 0) {
+            emitShapeB("");
+            return;
+        }
+        const cachedEntry = firstHitRel !== null ? getScopeIndexEntry(repoRoot, firstHitRel) : null;
+        const scopeHint = cachedEntry !== null
+            ? {
+                decisions: cachedEntry.decisions,
+                invariants: cachedEntry.invariants,
+            }
+            : null;
+        const invariantsLedger = getInvariantsLedger(repoRoot);
+        const decisionsLedger = getDecisionsLedger(repoRoot);
+        const resolveTaskFn = (taskId) => lookupTask(repoRoot, taskId);
+        const legend = buildLegend(aggregated, invariantsLedger, decisionsLedger, scopeHint, resolveTaskFn);
+        emitShapeB(legend ?? "");
+    }
+    catch {
+        try {
+            emitShapeB("");
+        }
+        catch {
+            // last resort
+        }
+    }
+}
+//# sourceMappingURL=user-prompt-submit.js.map

package/dist/hooks/runners/user-prompt-submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-prompt-submit.js","sourceRoot":"","sources":["../../../src/hooks/runners/user-prompt-submit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAyB,MAAM,sCAAsC,CAAC;AAC5F,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GAEX,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAuB,MAAM,oCAAoC,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,cAAc,GAAG,OAAO,CAAC;AAC/B,qEAAqE;AACrE,iEAAiE;AACjE,mCAAmC;AACnC,MAAM,UAAU,GAAG,sBAAsB,CAAC;AAgB1C,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;QAC3D,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,iBAAyB;IAC3C,MAAM,GAAG,GAAiC;QACxC,QAAQ,EAAE,IAAI;QACd,kBAAkB,EAAE;YAClB,aAAa,EAAE,kBAAkB;YACjC,iBAAiB;SAClB;KACF,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,oBAAoB,CAAC,MAAc;IAC1C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,OAAe;IAC/B,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,GAAG,CAAC,MAAM,GAAG,cAAc;YAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QACrE,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,aAAa,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QAE1E,+CAA+C;QAC/C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,UAAU,CAAC,EAAE,CAAC,CAAC;YACf,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,UAAU,CAAC,EAAE,CAAC,CAAC;YACf,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,UAAU,CAAC,EAAE,CAAC,CAAC;YACf,OAAO;QACT,CAAC;QAED,oEAAoE;QACpE,iEAAiE;QACjE,MAAM,UAAU,GAAqB;YACnC,UAAU,EAAE,EAAE;YACd,KAAK,EAAE,EAAE;YACT,SAAS,EAAE,EAAE;SACd,CAAC;QACF,IAAI,WAAW,GAAkB,IAAI,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;YACrD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,OAAO,KAAK,IAAI;gBAAE,SAAS;YAC/B,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;YACvC,MAAM,GAAG,GACP,OAAO,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;gBAC7B,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBACxB,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;gBACzB,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBACpC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC5C,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC;YACD,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;YAClD,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YACxC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAClD,CAAC;QAED,IACE,UAAU,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YAClC,UAAU,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAC7B,UAAU,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EACjC,CAAC;YACD,UAAU,CAAC,EAAE,CAAC,CAAC;YACf,OAAO;QACT,CAAC;QAED,MAAM,WAAW,GACf,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1E,MAAM,SAAS,GACb,WAAW,KAAK,IAAI;YAClB,CAAC,CAAC;gBACE,SAAS,EAAE,WAAW,CAAC,SAAS;gBAChC,UAAU,EAAE,WAAW,CAAC,UAAU;aACnC;YACH,CAAC,CAAC,IAAI,CAAC;QAEX,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACvD,MAAM,eAAe,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QACrD,MAAM,aAAa,GAAG,CAAC,MAAc,EAAoB,EAAE,CACzD,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAE/B,MAAM,MAAM,GAAG,WAAW,CACxB,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,aAAa,CACd,CAAC;QAEF,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YACH,UAAU,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/hooks/seed-attested.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Seed `.cairn/.attested-commits` with every commit reachable from
+ * HEAD at the time of seeding. Bypass detection then grandfathers all
+ * those SHAs as "already attested" — only future bypassed commits
+ * surface as attention.
+ *
+ * Two callers:
+ *   1. Phase 3b-seed (during `cairn init`) — seeds for the adopting
+ *      clone the moment `.cairn/` lands, so the very next Stop hook
+ *      tick doesn't false-positive every pre-adoption commit.
+ *   2. `cairn join` (per-clone bootstrap) — `.attested-commits` is
+ *      gitignored + per-clone, so each new clone needs its own seed
+ *      on first bootstrap.
+ *
+ * Idempotent: if the file already exists with content, we leave it
+ * alone (the post-commit hook owns ongoing appends).
+ */
+export type SeedAttestedStatus = "ok" | "skipped" | "error";
+export interface SeedAttestedResult {
+    status: SeedAttestedStatus;
+    detail: string;
+    /** SHA count seeded — present only when status="ok". */
+    count?: number;
+}
+export declare function seedAttestedCommits(repoRoot: string, dryRun?: boolean): SeedAttestedResult;

package/dist/hooks/seed-attested.js

@@ -0,0 +1,84 @@
+/**
+ * Seed `.cairn/.attested-commits` with every commit reachable from
+ * HEAD at the time of seeding. Bypass detection then grandfathers all
+ * those SHAs as "already attested" — only future bypassed commits
+ * surface as attention.
+ *
+ * Two callers:
+ *   1. Phase 3b-seed (during `cairn init`) — seeds for the adopting
+ *      clone the moment `.cairn/` lands, so the very next Stop hook
+ *      tick doesn't false-positive every pre-adoption commit.
+ *   2. `cairn join` (per-clone bootstrap) — `.attested-commits` is
+ *      gitignored + per-clone, so each new clone needs its own seed
+ *      on first bootstrap.
+ *
+ * Idempotent: if the file already exists with content, we leave it
+ * alone (the post-commit hook owns ongoing appends).
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function seedAttestedCommits(repoRoot, dryRun = false) {
+    const path = join(repoRoot, ".cairn", ".attested-commits");
+    if (existsSync(path)) {
+        return {
+            status: "skipped",
+            detail: ".cairn/.attested-commits already exists — leaving as-is",
+        };
+    }
+    if (!existsSync(join(repoRoot, ".git"))) {
+        return {
+            status: "skipped",
+            detail: "no .git/ — bypass detection is git-only, nothing to seed",
+        };
+    }
+    let shas = [];
+    try {
+        const out = execFileSync("git", ["log", "--format=%H"], {
+            cwd: repoRoot,
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        shas = out.split("\n").filter((s) => s.length > 0);
+    }
+    catch {
+        // git log fails on empty repos (no commits yet) and on edge cases
+        // like detached/corrupted state. In all those cases the right
+        // semantic is "nothing to seed" — never block adoption / bootstrap
+        // on the absence of pre-existing history.
+        return {
+            status: "skipped",
+            detail: "git log returned no commits — nothing to seed",
+        };
+    }
+    if (shas.length === 0) {
+        return {
+            status: "skipped",
+            detail: "git log returned no commits — nothing to seed",
+        };
+    }
+    if (dryRun) {
+        return {
+            status: "ok",
+            detail: `(dry-run) would seed ${shas.length} pre-existing SHA${shas.length === 1 ? "" : "s"}`,
+            count: shas.length,
+        };
+    }
+    try {
+        mkdirSync(join(repoRoot, ".cairn"), { recursive: true });
+        writeFileSync(path, `${shas.join("\n")}\n`, "utf8");
+    }
+    catch (err) {
+        return {
+            status: "error",
+            detail: `write ${path} failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    return {
+        status: "ok",
+        detail: `seeded ${shas.length} pre-existing SHA${shas.length === 1 ? "" : "s"} — bypass detection grandfathers them`,
+        count: shas.length,
+    };
+}
+//# sourceMappingURL=seed-attested.js.map

package/dist/hooks/seed-attested.js.map

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

package/dist/hooks/user-prompt-submit.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Bin entrypoint — `node cairn-core/dist/hooks/user-prompt-submit.js`.
+ * UserPromptSubmit hook; resolves §INV/§DEC/TODO(TSK-) citations in
+ * `@`-attached files (Read-bypass path).
+ */
+export {};

package/dist/hooks/user-prompt-submit.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Bin entrypoint — `node cairn-core/dist/hooks/user-prompt-submit.js`.
+ * UserPromptSubmit hook; resolves §INV/§DEC/TODO(TSK-) citations in
+ * `@`-attached files (Read-bypass path).
+ */
+import { runUserPromptSubmitHook } from "./runners/index.js";
+runUserPromptSubmitHook().catch((err) => {
+    process.stderr.write(`[cairn user-prompt-submit] ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=user-prompt-submit.js.map

package/dist/hooks/user-prompt-submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-prompt-submit.js","sourceRoot":"","sources":["../../src/hooks/user-prompt-submit.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,uBAAuB,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACnF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export * from "./decision-capture/index.js";
 export * from "./doctor/index.js";
 export * from "./gc/index.js";
 export * from "./ground/index.js";
+export { clearDeferState, deferStatePath, isDeferActive, readDeferState, writeDeferState, } from "./hooks/defer.js";
+export type { DeferKind, DeferState } from "./hooks/defer.js";
 export * from "./hooks/post-tool-use/index.js";
 export * from "./init/index.js";
 export * from "./join/index.js";
@@ -25,9 +27,4 @@ export * from "./hooks/runners/index.js";
 export * from "./session/index.js";
 export * from "./session-start/index.js";
 export * from "./status-line/index.js";
-export * from "./tier0/index.js";
-export * from "./tightener/index.js";
-export * from "./frontend-types.js";
-export { writeInboxRow } from "./inbox.js";
-export { loadWorkflowTemplate, renderTemplate } from "./prompt.js";
-export type { TemplateContext } from "./prompt.js";
+export { appendTrace, nowEvent, traceDir, traceFilePath, type TraceEvent, type TraceSource, } from "./trace/index.js";