@isaacriehm/cairn-core 0.22.6 → 0.24.0

package/dist/session/seen.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-session dedup store — `.cairn/sessions/<id>/seen.json`.
+ *
+ * The context engine injects scoped ground state as the agent works
+ * (working header, DEC/INV legends, component slices). Without dedup
+ * the injectors re-send unchanged context every turn and *become* the
+ * context-bloat problem they exist to solve. This module is the
+ * single source of "already shown this session":
+ *
+ *   - `fingerprints` — keyed text hashes (e.g. `working-header`). An
+ *     injector re-emits only when the hash changed.
+ *   - `shownIds` — flat set of opaque ids already surfaced once
+ *     (DEC-/INV- ids, component names, `annotate:<file>` debounce keys).
+ *
+ * Pure-FS read/modify/write. A missing or malformed file is treated as
+ * empty — callers run inside hooks that must never throw. The path is
+ * routed through `cairnDir` so `CAIRN_HOME` redirection holds
+ * (smoke-cairn-home).
+ *
+ * GC: the per-session dir (and this file with it) is removed by
+ * `gcStaleSessions` / `cleanupSession` (session/id.ts).
+ */
+/**
+ * Short content fingerprint for change-detection. sha256 hex sliced to
+ * 12 chars — collision-irrelevant for "did this exact text change".
+ */
+export declare function fingerprintText(text: string): string;
+/** Last fingerprint stored under `key`, or null when none. */
+export declare function getSeenFingerprint(repoRoot: string, sessionId: string, key: string): string | null;
+/** Record `fp` as the fingerprint for `key` (overwrites any prior). */
+export declare function setSeenFingerprint(repoRoot: string, sessionId: string, key: string, fp: string): void;
+/** Subset of `ids` not yet marked shown this session (order preserved). */
+export declare function filterUnshownIds(repoRoot: string, sessionId: string, ids: string[]): string[];
+/** Mark each id in `ids` as shown this session (idempotent, deduped). */
+export declare function markShownIds(repoRoot: string, sessionId: string, ids: string[]): void;
+/** True when `id` has already been surfaced this session. */
+export declare function hasShownId(repoRoot: string, sessionId: string, id: string): boolean;

package/dist/session/seen.js

@@ -0,0 +1,110 @@
+/**
+ * Per-session dedup store — `.cairn/sessions/<id>/seen.json`.
+ *
+ * The context engine injects scoped ground state as the agent works
+ * (working header, DEC/INV legends, component slices). Without dedup
+ * the injectors re-send unchanged context every turn and *become* the
+ * context-bloat problem they exist to solve. This module is the
+ * single source of "already shown this session":
+ *
+ *   - `fingerprints` — keyed text hashes (e.g. `working-header`). An
+ *     injector re-emits only when the hash changed.
+ *   - `shownIds` — flat set of opaque ids already surfaced once
+ *     (DEC-/INV- ids, component names, `annotate:<file>` debounce keys).
+ *
+ * Pure-FS read/modify/write. A missing or malformed file is treated as
+ * empty — callers run inside hooks that must never throw. The path is
+ * routed through `cairnDir` so `CAIRN_HOME` redirection holds
+ * (smoke-cairn-home).
+ *
+ * GC: the per-session dir (and this file with it) is removed by
+ * `gcStaleSessions` / `cleanupSession` (session/id.ts).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { bodyContentHash, cairnDir } from "@isaacriehm/cairn-state";
+function seenPath(repoRoot, sessionId) {
+    return cairnDir(repoRoot, "sessions", sessionId, "seen.json");
+}
+function readSeen(repoRoot, sessionId) {
+    const empty = { fingerprints: {}, shownIds: [] };
+    const path = seenPath(repoRoot, sessionId);
+    if (!existsSync(path))
+        return empty;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return empty;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return empty;
+    const p = parsed;
+    const fingerprints = typeof p.fingerprints === "object" && p.fingerprints !== null
+        ? p.fingerprints
+        : {};
+    const shownIds = Array.isArray(p.shownIds)
+        ? p.shownIds.filter((x) => typeof x === "string")
+        : [];
+    return { fingerprints, shownIds };
+}
+function writeSeen(repoRoot, sessionId, data) {
+    const path = seenPath(repoRoot, sessionId);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // best-effort — never throw inside a hook
+    }
+}
+/**
+ * Short content fingerprint for change-detection. sha256 hex sliced to
+ * 12 chars — collision-irrelevant for "did this exact text change".
+ */
+export function fingerprintText(text) {
+    return bodyContentHash(text).slice(0, 12);
+}
+/** Last fingerprint stored under `key`, or null when none. */
+export function getSeenFingerprint(repoRoot, sessionId, key) {
+    const seen = readSeen(repoRoot, sessionId);
+    return seen.fingerprints[key] ?? null;
+}
+/** Record `fp` as the fingerprint for `key` (overwrites any prior). */
+export function setSeenFingerprint(repoRoot, sessionId, key, fp) {
+    const seen = readSeen(repoRoot, sessionId);
+    seen.fingerprints[key] = fp;
+    writeSeen(repoRoot, sessionId, seen);
+}
+/** Subset of `ids` not yet marked shown this session (order preserved). */
+export function filterUnshownIds(repoRoot, sessionId, ids) {
+    const seen = readSeen(repoRoot, sessionId);
+    const shown = new Set(seen.shownIds);
+    const out = [];
+    const local = new Set();
+    for (const id of ids) {
+        if (shown.has(id) || local.has(id))
+            continue;
+        local.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/** Mark each id in `ids` as shown this session (idempotent, deduped). */
+export function markShownIds(repoRoot, sessionId, ids) {
+    if (ids.length === 0)
+        return;
+    const seen = readSeen(repoRoot, sessionId);
+    const set = new Set(seen.shownIds);
+    for (const id of ids)
+        set.add(id);
+    seen.shownIds = [...set];
+    writeSeen(repoRoot, sessionId, seen);
+}
+/** True when `id` has already been surfaced this session. */
+export function hasShownId(repoRoot, sessionId, id) {
+    const seen = readSeen(repoRoot, sessionId);
+    return seen.shownIds.includes(id);
+}
+//# sourceMappingURL=seen.js.map

package/dist/session/seen.js.map

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

package/dist/session/touched.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-session touched-file set — `.cairn/sessions/<id>/touched.json`.
+ *
+ * The PostToolUse(Write|Edit) hook appends every repo-relative path the
+ * agent writes this session (D6). The Stop capture-gate reads the set,
+ * filters to component-dir files missing a `@cairn` header, and surfaces
+ * a fully-specified `cairn_component_annotate` ask. This is the source
+ * for "what did this session touch" — NOT the task journal (which only
+ * carries explicitly-journaled work).
+ *
+ * Pure-FS dedup set. Missing/malformed file → empty. Routed through
+ * `cairnDir` (smoke-cairn-home). GC'd with the per-session dir.
+ */
+/** Repo-relative POSIX paths the agent has written this session. */
+export declare function readTouched(repoRoot: string, sessionId: string): string[];
+/** Add `relPath` (repo-relative POSIX) to the session's touched set. */
+export declare function appendTouched(repoRoot: string, sessionId: string, relPath: string): void;

package/dist/session/touched.js

@@ -0,0 +1,57 @@
+/**
+ * Per-session touched-file set — `.cairn/sessions/<id>/touched.json`.
+ *
+ * The PostToolUse(Write|Edit) hook appends every repo-relative path the
+ * agent writes this session (D6). The Stop capture-gate reads the set,
+ * filters to component-dir files missing a `@cairn` header, and surfaces
+ * a fully-specified `cairn_component_annotate` ask. This is the source
+ * for "what did this session touch" — NOT the task journal (which only
+ * carries explicitly-journaled work).
+ *
+ * Pure-FS dedup set. Missing/malformed file → empty. Routed through
+ * `cairnDir` (smoke-cairn-home). GC'd with the per-session dir.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { cairnDir } from "@isaacriehm/cairn-state";
+function touchedPath(repoRoot, sessionId) {
+    return cairnDir(repoRoot, "sessions", sessionId, "touched.json");
+}
+/** Repo-relative POSIX paths the agent has written this session. */
+export function readTouched(repoRoot, sessionId) {
+    const path = touchedPath(repoRoot, sessionId);
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const p = parsed;
+    return Array.isArray(p.paths)
+        ? p.paths.filter((x) => typeof x === "string")
+        : [];
+}
+/** Add `relPath` (repo-relative POSIX) to the session's touched set. */
+export function appendTouched(repoRoot, sessionId, relPath) {
+    if (relPath.length === 0)
+        return;
+    const norm = relPath.replace(/\\/g, "/");
+    const existing = readTouched(repoRoot, sessionId);
+    if (existing.includes(norm))
+        return;
+    existing.push(norm);
+    const path = touchedPath(repoRoot, sessionId);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify({ paths: existing }, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // best-effort — never throw inside a hook
+    }
+}
+//# sourceMappingURL=touched.js.map

package/dist/session/touched.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"touched.js","sourceRoot":"","sources":["../../src/session/touched.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAMnD,SAAS,WAAW,CAAC,QAAgB,EAAE,SAAiB;IACtD,OAAO,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;AACnE,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,SAAiB;IAC7D,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7D,MAAM,CAAC,GAAG,MAA8B,CAAC;IACzC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QAC3D,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,SAAiB,EACjB,OAAe;IAEf,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAClD,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IACpC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;AACH,CAAC"}

package/dist/tasks/spec-reader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared `spec.tightened.md` frontmatter + `## Goal` reader.
+ *
+ * Factored out of `cairn_resume` (mcp/tools/resume.ts) so both the
+ * resume payload AND the UserPromptSubmit working-header (context
+ * engine, stage 1) read the spec the same way — one parse, no drift.
+ * The parse is verbatim from the original resume.ts implementation.
+ *
+ * Returns null when the task has no `spec.tightened.md` yet (e.g. a
+ * task still in `queued`/`tightening`). Malformed frontmatter degrades
+ * to defaults rather than throwing — callers run inside hooks that must
+ * never crash the agent loop.
+ */
+export interface TaskSpec {
+    title: string;
+    goal: string;
+    inScopeDecisions: string[];
+    inScopeInvariants: string[];
+    targetPathGlobs: string[];
+}
+/**
+ * Read `<taskDir>/spec.tightened.md`'s frontmatter (`title`,
+ * `in_scope_decisions[]`, `in_scope_invariants[]`, `target_path_globs[]`)
+ * and the body's `## Goal` section. `taskDir` is the absolute task
+ * directory (active or done). Returns null when the spec file is absent.
+ */
+export declare function readTaskSpec(taskDir: string): TaskSpec | null;

package/dist/tasks/spec-reader.js

@@ -0,0 +1,60 @@
+/**
+ * Shared `spec.tightened.md` frontmatter + `## Goal` reader.
+ *
+ * Factored out of `cairn_resume` (mcp/tools/resume.ts) so both the
+ * resume payload AND the UserPromptSubmit working-header (context
+ * engine, stage 1) read the spec the same way — one parse, no drift.
+ * The parse is verbatim from the original resume.ts implementation.
+ *
+ * Returns null when the task has no `spec.tightened.md` yet (e.g. a
+ * task still in `queued`/`tightening`). Malformed frontmatter degrades
+ * to defaults rather than throwing — callers run inside hooks that must
+ * never crash the agent loop.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * Read `<taskDir>/spec.tightened.md`'s frontmatter (`title`,
+ * `in_scope_decisions[]`, `in_scope_invariants[]`, `target_path_globs[]`)
+ * and the body's `## Goal` section. `taskDir` is the absolute task
+ * directory (active or done). Returns null when the spec file is absent.
+ */
+export function readTaskSpec(taskDir) {
+    const specPath = join(taskDir, "spec.tightened.md");
+    if (!existsSync(specPath))
+        return null;
+    let title = "";
+    let goal = "";
+    let inScopeDecisions = [];
+    let inScopeInvariants = [];
+    let targetPathGlobs = [];
+    const raw = readFileSync(specPath, "utf8");
+    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\n---\r?\n([\s\S]*)$/);
+    if (fmMatch) {
+        try {
+            const fm = parseYaml(fmMatch[1] ?? "");
+            if (typeof fm.title === "string")
+                title = fm.title;
+            if (Array.isArray(fm.in_scope_decisions)) {
+                inScopeDecisions = fm.in_scope_decisions.filter((x) => typeof x === "string");
+            }
+            if (Array.isArray(fm.in_scope_invariants)) {
+                inScopeInvariants = fm.in_scope_invariants.filter((x) => typeof x === "string");
+            }
+            if (Array.isArray(fm.target_path_globs)) {
+                targetPathGlobs = fm.target_path_globs.filter((x) => typeof x === "string");
+            }
+        }
+        catch {
+            // malformed frontmatter — fall through with defaults
+        }
+        const body = fmMatch[2] ?? "";
+        const goalMatch = body.match(/##\s+Goal\s*\r?\n+([\s\S]*?)(?:\r?\n##\s+|$)/);
+        if (goalMatch && goalMatch[1] !== undefined) {
+            goal = goalMatch[1].trim();
+        }
+    }
+    return { title, goal, inScopeDecisions, inScopeInvariants, targetPathGlobs };
+}
+//# sourceMappingURL=spec-reader.js.map

package/dist/tasks/spec-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-reader.js","sourceRoot":"","sources":["../../src/tasks/spec-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAiB1C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACpD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,gBAAgB,GAAa,EAAE,CAAC;IACpC,IAAI,iBAAiB,GAAa,EAAE,CAAC;IACrC,IAAI,eAAe,GAAa,EAAE,CAAC;IAEnC,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;IACrE,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAoB,CAAC;YAC1D,IAAI,OAAO,EAAE,CAAC,KAAK,KAAK,QAAQ;gBAAE,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;YACnD,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,kBAAkB,CAAC,EAAE,CAAC;gBACzC,gBAAgB,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAC7C,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,CAAC;gBAC1C,iBAAiB,GAAG,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAC/C,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBACxC,eAAe,GAAG,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAC3C,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;QACvD,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC7E,IAAI,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5C,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,CAAC;AAC/E,CAAC"}

package/dist/uninstall/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `cairn uninstall` — remove Cairn from a repo, cleanly.
+ *
+ * The inverse of adoption (`cairn init`) + per-clone bootstrap
+ * (`cairn join`). The install footprint is:
+ *
+ *   - `.cairn/`                       the ground state + config + hooks
+ *   - `.claude/rules/cairn.md`        the plugin-absent onboarding notice
+ *   - an `@.claude/rules/cairn.md`    import block in CLAUDE.md / AGENTS.md
+ *   - `git config core.hooksPath`     pointed at `.cairn/git-hooks`
+ *   - in-source `// §DEC-/§INV-`       citations from sot-align strip-replace
+ *
+ * Uninstall reverses these in dependency order. Cites are expanded FIRST
+ * (while `.cairn/ground/` still exists to resolve them), so removing
+ * `.cairn/` doesn't leave dangling `§` references — the source ends up
+ * self-documenting. `core.hooksPath` is only unset when it is Cairn's own
+ * value (a foreign husky/lefthook path is never clobbered).
+ *
+ * Every step reports a status; nothing throws on a recoverable issue. The
+ * machine-level Claude Code plugin (`/plugin install`) is user-scoped, not
+ * repo-scoped — uninstall can't remove it and says so.
+ */
+export type UninstallStepStatus = "ok" | "skipped" | "warn";
+export interface UninstallStep {
+    step: string;
+    status: UninstallStepStatus;
+    detail: string;
+}
+export interface UninstallOptions {
+    repoRoot: string;
+    /** Expand DEC/INV cites to inline comments first. Default true. */
+    expandCites?: boolean;
+    /** Report what would happen; change nothing. */
+    dryRun?: boolean;
+}
+export interface UninstallResult {
+    repoRoot: string;
+    steps: UninstallStep[];
+    /** True when `.cairn/` was (or would be) removed. */
+    removed: boolean;
+}
+export declare function uninstallCairn(opts: UninstallOptions): UninstallResult;
+/** Remove the marker + import lines, then collapse the blank-line run they left. */
+export declare function stripImportBlock(content: string): string;

package/dist/uninstall/index.js

@@ -0,0 +1,185 @@
+/**
+ * `cairn uninstall` — remove Cairn from a repo, cleanly.
+ *
+ * The inverse of adoption (`cairn init`) + per-clone bootstrap
+ * (`cairn join`). The install footprint is:
+ *
+ *   - `.cairn/`                       the ground state + config + hooks
+ *   - `.claude/rules/cairn.md`        the plugin-absent onboarding notice
+ *   - an `@.claude/rules/cairn.md`    import block in CLAUDE.md / AGENTS.md
+ *   - `git config core.hooksPath`     pointed at `.cairn/git-hooks`
+ *   - in-source `// §DEC-/§INV-`       citations from sot-align strip-replace
+ *
+ * Uninstall reverses these in dependency order. Cites are expanded FIRST
+ * (while `.cairn/ground/` still exists to resolve them), so removing
+ * `.cairn/` doesn't leave dangling `§` references — the source ends up
+ * self-documenting. `core.hooksPath` is only unset when it is Cairn's own
+ * value (a foreign husky/lefthook path is never clobbered).
+ *
+ * Every step reports a status; nothing throws on a recoverable issue. The
+ * machine-level Claude Code plugin (`/plugin install`) is user-scoped, not
+ * repo-scoped — uninstall can't remove it and says so.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { cairnDir, COMMITTED_HOOKS_PATH } from "@isaacriehm/cairn-state";
+import { expandCitesInRepo } from "../cites/expand.js";
+import { CAIRN_RULE_IMPORT, IMPORT_MARKER } from "../init/claude-rule.js";
+export function uninstallCairn(opts) {
+    const root = opts.repoRoot;
+    const dryRun = opts.dryRun ?? false;
+    const doExpand = opts.expandCites ?? true;
+    const steps = [];
+    // 1. Expand cites FIRST — needs `.cairn/ground/` to resolve bodies.
+    if (doExpand) {
+        const r = expandCitesInRepo({ repoRoot: root, dryRun });
+        const bits = [`${r.expanded} citation(s) inlined across ${r.filesChanged} file(s)`];
+        if (r.danglingSkipped > 0)
+            bits.push(`${r.danglingSkipped} dangling left in place`);
+        if (r.inlineSkipped > 0)
+            bits.push(`${r.inlineSkipped} inline left in place`);
+        steps.push({ step: "expand-cites", status: "ok", detail: bits.join("; ") });
+    }
+    else {
+        steps.push({
+            step: "expand-cites",
+            status: "skipped",
+            detail: "--keep-cites: in-source §DEC-/§INV- tokens will dangle after removal",
+        });
+    }
+    // 2. Remove the `@.claude/rules/cairn.md` import block from the memory file.
+    steps.push(unwireRuleImport(root, dryRun));
+    // 3. Remove `.claude/rules/cairn.md` and prune the dirs if they empty out.
+    steps.push(removeRuleFile(root, dryRun));
+    // 4. Unset `core.hooksPath` — only when it is Cairn's own value.
+    steps.push(unsetHooksPath(root, dryRun));
+    // 5. Remove `.cairn/`.
+    const cairnPath = cairnDir(root);
+    let removed = false;
+    if (existsSync(cairnPath)) {
+        removed = true;
+        if (!dryRun)
+            rmSync(cairnPath, { recursive: true, force: true });
+        steps.push({ step: "remove-cairn-dir", status: "ok", detail: `${dryRun ? "would remove" : "removed"} .cairn/` });
+    }
+    else {
+        steps.push({ step: "remove-cairn-dir", status: "skipped", detail: ".cairn/ not present" });
+    }
+    // 6. Advisory — the machine-level plugin is user-scoped.
+    steps.push({
+        step: "plugin",
+        status: "skipped",
+        detail: "Claude Code plugin is machine-scoped — remove with `/plugin uninstall cairn` if no other repo uses it",
+    });
+    return { repoRoot: root, steps, removed };
+}
+/* -------------------------------------------------------------------------- */
+function unwireRuleImport(root, dryRun) {
+    for (const rel of ["CLAUDE.md", "AGENTS.md"]) {
+        const abs = join(root, rel);
+        if (!existsSync(abs))
+            continue;
+        let content;
+        try {
+            content = readFileSync(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!content.includes(CAIRN_RULE_IMPORT))
+            continue;
+        const next = stripImportBlock(content);
+        if (!dryRun)
+            writeFileSync(abs, next, "utf8");
+        return {
+            step: "unwire-import",
+            status: "ok",
+            detail: `${dryRun ? "would remove" : "removed"} the cairn rule import from ${rel}`,
+        };
+    }
+    return { step: "unwire-import", status: "skipped", detail: "no cairn rule import found in CLAUDE.md / AGENTS.md" };
+}
+/** Remove the marker + import lines, then collapse the blank-line run they left. */
+export function stripImportBlock(content) {
+    const lines = content.split(/\r?\n/);
+    const kept = lines.filter((l) => l.trim() !== IMPORT_MARKER && l.trim() !== CAIRN_RULE_IMPORT);
+    // Collapse 3+ consecutive blank lines (the import block was fenced by blanks)
+    // down to a single blank, then normalize the trailing newline.
+    const collapsed = [];
+    let blanks = 0;
+    for (const l of kept) {
+        if (l.trim() === "") {
+            blanks += 1;
+            if (blanks >= 2)
+                continue;
+        }
+        else {
+            blanks = 0;
+        }
+        collapsed.push(l);
+    }
+    return `${collapsed.join("\n").replace(/\s*$/, "")}\n`;
+}
+function removeRuleFile(root, dryRun) {
+    const ruleAbs = join(root, ".claude", "rules", "cairn.md");
+    if (!existsSync(ruleAbs)) {
+        return { step: "remove-rule", status: "skipped", detail: ".claude/rules/cairn.md not present" };
+    }
+    if (!dryRun) {
+        rmSync(ruleAbs, { force: true });
+        pruneIfEmpty(join(root, ".claude", "rules"));
+        pruneIfEmpty(join(root, ".claude"));
+    }
+    return { step: "remove-rule", status: "ok", detail: `${dryRun ? "would remove" : "removed"} .claude/rules/cairn.md` };
+}
+function pruneIfEmpty(dir) {
+    try {
+        if (existsSync(dir) && readdirSync(dir).length === 0)
+            rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function unsetHooksPath(root, dryRun) {
+    if (!existsSync(join(root, ".git"))) {
+        return { step: "unset-hooks", status: "skipped", detail: "not a git repo" };
+    }
+    const current = readGitConfig(root, "core.hooksPath");
+    if (current === null) {
+        return { step: "unset-hooks", status: "skipped", detail: "core.hooksPath not set" };
+    }
+    const ours = current === COMMITTED_HOOKS_PATH || current === cairnDir(root, "git-hooks");
+    if (!ours) {
+        return {
+            step: "unset-hooks",
+            status: "warn",
+            detail: `core.hooksPath is '${current}' (not Cairn's) — left untouched`,
+        };
+    }
+    if (!dryRun) {
+        try {
+            execFileSync("git", ["config", "--unset", "core.hooksPath"], { cwd: root, stdio: "ignore" });
+        }
+        catch {
+            return { step: "unset-hooks", status: "warn", detail: "failed to unset core.hooksPath" };
+        }
+    }
+    return { step: "unset-hooks", status: "ok", detail: `${dryRun ? "would unset" : "unset"} core.hooksPath` };
+}
+function readGitConfig(root, key) {
+    try {
+        const out = execFileSync("git", ["config", "--get", key], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const trimmed = out.trim();
+        return trimmed.length === 0 ? null : trimmed;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/uninstall/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isaacriehm/cairn-core",
-  "version": "0.22.6",
+  "version": "0.24.0",
   "description": "Cairn core — state + context layer. Curated `.cairn/ground/` (decisions, §INV invariants, canonical-map, brand, quality-grades), MCP server, init wizard, hook runners, sensors, GC drift sweep.",
   "author": "Isaac Riehm",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "simple-git": "^3.36.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@isaacriehm/cairn-state": "0.22.6"
+    "@isaacriehm/cairn-state": "0.24.0"
   },
   "devDependencies": {
     "@types/cli-progress": "^3.11.6",

package/templates/.cairn/config/sensors.yaml

@@ -36,16 +36,23 @@ sensors:
       - every_run
     fail_severity: hard
 
-  # ── §INV invariant sensors (auto-registered by backprop) ────────────────
+  # ── §INV invariant sensors ───────────────────────────────────────────────
+  # PLANNED — not yet wired. No runner reads this entry: the pre-commit sweep
+  # executes only stub-pattern-catalog + decision-assertions. Invariants are
+  # curated (§INV pillar) but enforcement (an assertions[] array on each
+  # invariant routed through the assertion evaluator, like decisions) is a
+  # gap, not a live gate. Kept `soft` so it reads as a roadmap item, NOT a
+  # hard gate that silently passes because nothing runs it.
   - id: invariant-suite
     layer: invariants
     kind: invariant_runner
-    description: "Runs every active §INV invariant's linked sensor script. Active invariants accumulate over time; superseded ones are skipped."
+    status: planned
+    description: "PLANNED (not wired): would run every active §INV invariant's linked assertion. Today no runner reads this; invariant enforcement is unimplemented."
     triggers:
       - every_run
     sources:
       - .cairn/ground/invariants/
-    fail_severity: hard
+    fail_severity: soft
 
   # ── Frontmatter freshness (nightly GC pass) ──────────────────────────────
   - id: frontmatter-freshness