@isaacriehm/cairn-core 0.4.2 → 0.5.0

package/dist/hooks/post-tool-use/sot-align.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Layer A — live SoT alignment hook (plan §4.1).
+ *
+ * `cairn hook sot-align` runs as a PostToolUse hook on Claude Code's
+ * Write/Edit. For every prose block in the just-written file the
+ * pipeline picks one of:
+ *
+ *   - **Tier 1 (deterministic, no Haiku)** — block is a verbatim/
+ *     near-verbatim duplicate of an existing accepted DEC/INV body
+ *     (Jaccard ≥ 0.85, 3-shingle ≥ 60%, length ratio 0.5-2.0).
+ *     Auto-replace with `// §DEC-<hash>` (or `# §DEC-<hash>` per
+ *     language). Statusline blip `⬡ aligned`.
+ *
+ *   - **Tier 2 — Haiku dedup judge, two-pass.**
+ *       Pass 1 (cheap, snippet + candidate body) → `same | different |
+ *       ambiguous`. `same` → cite. `different` → next candidate.
+ *       `ambiguous` → escalate to Pass 2.
+ *       Pass 2 (full bodies + ±200-char source context + step-by-step
+ *       prompt) → `same | different | augments | ambiguous`. `same`
+ *       cite; `different` next; `augments` triggers two-stage delta:
+ *         - Stage 1 — Haiku extracts the delta prose ("NO_DELTA" → same).
+ *         - Stage 2 — Haiku classifies the delta `constraint | rationale`.
+ *           constraint → fresh INV linked via `derived_from`; rationale
+ *           → fresh DEC linked via `related`. The augmented source
+ *           gains a `// §INV-<new>` / `// §DEC-<new>` cite *alongside*
+ *           the existing one (existing token preserved).
+ *       `ambiguous` (still!) → write to `.cairn/ground/alignment-
+ *       pending/<id>.md` and surface via cairn-attention.
+ *
+ *   - **Tier 3 — Haiku creation judge, two-pass.**
+ *       Pass 1 → `decision | constraint | descriptive | ambiguous`.
+ *       `descriptive` no-op (false-positive DEC creation pollutes
+ *       ground state worse than missed capture). `ambiguous` →
+ *       escalate to Pass 2 (full prose + ±200-char context + step-by-
+ *       step prompt). Pass-2-still-ambiguous → alignment-pending.
+ *
+ * Hard rules:
+ *   - The hook never blocks the Write. Failures degrade to no-op +
+ *     log; the operator's edit always succeeds.
+ *   - Per-Write call caps: max HAIKU_PASS1_CAP Pass-1 calls + max
+ *     HAIKU_PASS2_CAP Pass-2 calls per Write. Excess defers to
+ *     `.cairn/staleness/layer-a-deferred.jsonl` for Layer C drain.
+ *   - Verdict cache at `.cairn/cache/haiku/<scope>/<blockHash>-<key>.json`
+ *     so re-running the same prose hits cache instead of Haiku.
+ *   - Source files outside Claude's repo (cwd) are skipped. Markdown
+ *     (`.md`/`.mdx`) skipped entirely — operator-curated narrative is
+ *     handled by phase 5b's topic-index + the doc-drift sensor.
+ */
+export interface AlignFileArgs {
+    repoRoot: string;
+    /** Repo-relative POSIX path written by Claude Code. */
+    filePath: string;
+    /** Claude Code session id (for statusline blips). */
+    sessionId: string | null;
+    /**
+     * Mock dedup judge — Pass 1. Default uses Haiku via runClaude.
+     */
+    mockDedupJudgePass1?: (args: {
+        blockBody: string;
+        candidate: {
+            id: string;
+            body: string;
+        };
+    }) => Promise<DedupVerdictPass1>;
+    /**
+     * Mock dedup judge — Pass 2 (CoT escalation). Default uses Haiku.
+     */
+    mockDedupJudgePass2?: (args: {
+        blockBody: string;
+        blockContext: string;
+        candidate: {
+            id: string;
+            body: string;
+        };
+    }) => Promise<DedupVerdictPass2>;
+    /**
+     * Mock delta extractor (Stage 1) — extract the prose delta when
+     * Pass 2 returns `augments`. Default uses Haiku.
+     */
+    mockDeltaExtract?: (args: {
+        blockBody: string;
+        candidateBody: string;
+    }) => Promise<string>;
+    /**
+     * Mock delta classifier (Stage 2) — `constraint | rationale`.
+     * Default uses Haiku.
+     */
+    mockDeltaClassify?: (args: {
+        delta: string;
+    }) => Promise<DeltaKind>;
+    /**
+     * Mock creation judge — Pass 1. Default uses Haiku via runClaude.
+     */
+    mockCreationJudgePass1?: (args: {
+        blockBody: string;
+        file: string;
+        line: number;
+    }) => Promise<CreationVerdict>;
+    /**
+     * Mock creation judge — Pass 2 (CoT escalation). Default uses Haiku.
+     */
+    mockCreationJudgePass2?: (args: {
+        blockBody: string;
+        blockContext: string;
+        file: string;
+        line: number;
+    }) => Promise<CreationVerdict>;
+    /**
+     * Override the per-call Pass-1 Haiku cap. Default 5 — appropriate
+     * for live PostToolUse Writes where the cost has to stay tight.
+     * Layer D (`cairn fix align`) sets this much higher (e.g. 200) so a
+     * single-file sweep can fully judge every block.
+     */
+    pass1Cap?: number;
+    /** Override the per-call Pass-2 Haiku cap. Default 2. */
+    pass2Cap?: number;
+    /**
+     * When true, suppress the Tier 3 creation pipeline entirely — Tier 1
+     * + Tier 2 dedup still run. Layer D's `--no-creation` flag sets this
+     * so a sweep only consolidates duplicates without proposing fresh
+     * DECs from prose that doesn't match anything in the ledger yet.
+     */
+    skipCreation?: boolean;
+}
+type DedupVerdictPass1 = "same" | "different" | "ambiguous";
+type DedupVerdictPass2 = "same" | "different" | "augments" | "ambiguous";
+type DeltaKind = "constraint" | "rationale";
+export type CreationVerdict = "decision" | "constraint" | "descriptive" | "ambiguous";
+/** Back-compat alias preserved for external callers. */
+export type DedupVerdict = DedupVerdictPass1;
+export interface AlignFileResult {
+    /** Number of prose blocks discovered in the written file. */
+    blocksConsidered: number;
+    /** Tier 1 deterministic auto-cites. */
+    tier1Aligned: number;
+    /** Tier 2 Haiku-confirmed cites. */
+    tier2Aligned: number;
+    /** Tier 3 fresh DECs emitted. */
+    decsCreated: number;
+    /** Tier 3 fresh INVs emitted. */
+    invsCreated: number;
+    /** Augments-DEC siblings (Pass 2 delta = rationale). */
+    augmentsDecs: number;
+    /** Augments-INV siblings (Pass 2 delta = constraint). */
+    augmentsInvs: number;
+    /** Blocks queued in `.cairn/ground/alignment-pending/`. */
+    pending: number;
+    /** Blocks deferred to staleness (cap exceeded). */
+    deferredToStaleness: number;
+    /** Blocks classified as descriptive (no-op). */
+    descriptive: number;
+    /** Blocks skipped for any reason — already-cited, length floor, etc. */
+    skipped: number;
+    /** Pass-1 Haiku calls made. */
+    haikuPass1Calls: number;
+    /** Pass-2 Haiku calls made. */
+    haikuPass2Calls: number;
+    /** Total Haiku calls (Pass 1 + Pass 2 + augments stages). Back-compat. */
+    haikuCalls: number;
+}
+/**
+ * Run the Layer A pipeline against one repo-relative file.
+ */
+export declare function alignFile(args: AlignFileArgs): Promise<AlignFileResult>;
+export declare function runSotAlign(): Promise<void>;
+export {};