@davesheffer/hunch 1.31.1 → 1.32.1

package/dist/core/escalations.js

@@ -1,5 +1,40 @@
 import { topicCollisions } from "./topics.js";
+import { liveRewrites, deadRewrites, commitRepairReviewHash, firstFor } from "./commitrepair.js";
 import { importedAdrReviewHash, importedAdrSourceHash, pendingImportedAdrReviews } from "./importReview.js";
+/** Escalations gating surfaces (CI exit codes, "needs your call" counts/lists)
+ *  should act on: everything except an entry explicitly marked
+ *  actionable:false (#61). The full list — including non-actionable
+ *  entries — still belongs in any transparency-facing output (e.g. --json). */
+export function actionableEscalations(items) {
+    return items.filter((e) => e.actionable !== false);
+}
+/** One computation for every "N need your call (+M shown for context)"
+ *  consumer (CLI `escalations`, SessionStart, the `hunch_now`/`hunch_escalations`
+ *  MCP tools) — introduced alongside `actionable` (#61) specifically so a
+ *  future consumer of Escalation[] can't repeat the mistake of hand-rolling
+ *  the filter and forgetting it (the VS Code panel did, before this existed). */
+export function summarizeEscalations(items) {
+    const actionable = actionableEscalations(items);
+    return { actionable, context: items.length - actionable.length };
+}
+/** The ONE "N need your call (+M shown for context)" headline, shared by the
+ *  CLI `escalations` command and the `hunch_escalations` MCP tool (#61) —
+ *  including its own "nothing actionable, but N item(s) queued for context"
+ *  fallback, so that unreachable-today prose exists in exactly one place
+ *  instead of being hand-copied per consumer (the copy-paste is how the VS
+ *  Code panel missed the filter entirely before `actionable` existed).
+ *  Callers are expected to have already special-cased `items.length === 0`
+ *  (a plainer "nothing needs your decision" message, no tally at all). */
+export function escalationHeadline(items, audience) {
+    const { actionable, context } = summarizeEscalations(items);
+    if (actionable.length) {
+        const call = audience === "cli" ? "your call — asked here, never decided for you" : "the human's call — ask each inline, don't decide it for them";
+        const note = audience === "cli" ? "not gating" : "not a decision";
+        return `${actionable.length} decision(s) need ${call}${context ? ` (+${context} shown below for context only, ${note})` : ""}:`;
+    }
+    const whose = audience === "cli" ? "your decision" : "the human's call";
+    return `Nothing needs ${whose} right now — ${items.length} entr${items.length === 1 ? "y" : "ies"} shown below for context only (resolving another entry will clear them):`;
+}
 /** The decisions a human must make NOW, to be asked INLINE. Empty in a healthy graph. */
 export function pendingEscalations(decisions) {
     const out = [];
@@ -35,6 +70,136 @@ export function pendingEscalations(decisions) {
     }
     return out;
 }
+/** A commit-provenance repair the post-merge hook detected and queued
+ *  (src/core/repairqueue.ts) but never applied — the match signal (related_files
+ *  overlap) isn't strong enough to write unattended, so it's a question for the
+ *  human, exactly like every other entry here, never a silent write.
+ *
+ *  `decisions` is the caller's VISIBLE scope (supplies the title only) —
+ *  MCP/SessionStart pass store.advisoryRecs(), which is public-only in
+ *  private mode. `live` is the scope liveRewrites checks the repair against;
+ *  it defaults to `decisions` but callers on an advisory scope must pass the
+ *  FULL store (store.recs()) here, since repair-provenance itself reads the
+ *  full store — an overlay decision's repair is fully answerable even where
+ *  its title isn't visible, and must not go silent just because the title is
+ *  private.
+ *
+ *  `withheld` (from repairqueue.ts's withheldRewrites — a git-facing check
+ *  this module deliberately stays free of, so the caller runs it and passes
+ *  the result in) names entries whose proposed `to` doesn't resolve to a
+ *  real commit here. `--apply --only <id>` can never resolve one of these —
+ *  advertising it as the answer would be advice guaranteed to no-op
+ *  forever, which is worse than not asking at all. Such an entry still
+ *  needs a human (only `--drop` can retire it), so it still escalates, just
+ *  with wording that doesn't promise `--apply` will help.
+ *
+ *  Keyed by OBJECT, not by id, matching withheldForUnresolvableTo's own
+ *  contract: a corrupted queue file can carry two entries sharing an id
+ *  (one resolvable, one not) — an id-keyed set couldn't tell them apart and
+ *  would wrongly tag the resolvable sibling as unresolvable too. Every
+ *  caller of this function already passes the SAME `queued` array to both
+ *  this function and withheldRewrites, so identity holds. */
+export function commitRepairEscalations(queued, decisions, live = decisions, withheld = new Set()) {
+    const reviewHash = commitRepairReviewHash(queued, withheld);
+    const byId = new Map(decisions.map((d) => [d.id, d]));
+    // Mirrors two of the three queue transformations --apply/--drop actually see
+    // (src/cli/index.ts): dead entries (deadRewrites) are pruned via `save()`
+    // before either command ever reads `queue`, so a duplicate-id check against
+    // the RAW `queued` array can name an entry that's already gone by the time a
+    // human acts (#59). Deliberately does NOT model the fresh-detection merge
+    // (mergeRewrites) that also runs before either command: a fresh match can
+    // silently evict firstFor(queue, id) with no tombstone. That gap predates
+    // this fix (see #56) and isn't new here — it just means a queue whose first
+    // entry is about to be evicted by a fresh match still reads as the ordinary,
+    // ask-normally case rather than something rarer.
+    // deadRewrites (below) and liveRewrites (in the return) are BOTH called with
+    // this same `live` array, so for any one id they agree on the same single
+    // decision (or the same absence) governing it. That decision's `commit`/
+    // `status` are fixed for the whole id-group — only each entry's OWN `from`
+    // varies — so liveRewrites' and deadRewrites' predicates are exact
+    // complements entry-by-entry (never uniform across the group: two entries
+    // sharing an id can freely land on opposite sides, see the "dead first
+    // sibling" test, #59). `survivors` (queued minus dead) restricted to one id
+    // is therefore exactly that id's live entries, in the same queue order.
+    // Consequence relied on below (#61): the FIRST live entry per id is always
+    // `dropTarget(id)`, so it always stays actionable — no id-group's
+    // escalations can ever be entirely actionable:false.
+    const deadSet = new Set(deadRewrites(queued, live));
+    const survivors = queued.filter((q) => !deadSet.has(q));
+    // What `--drop <id>` targets (src/cli/index.ts: `firstFor(queue, opts.drop)`
+    // on the post-prune queue) — --drop doesn't care whether an entry's `to`
+    // resolves, so a withheld entry can still be the drop target.
+    const dropTarget = (id) => firstFor(survivors, id);
+    // What `--apply --only <id>` targets: its plan is built from
+    // withheldForUnresolvableTo's `applicable` half (src/cli/index.ts:
+    // `plan.rewrites = applicable`), which excludes withheld entries entirely —
+    // so the apply-target can differ from the drop-target when an earlier
+    // survivor for the same id is withheld. Routed through the shared `firstFor`
+    // rather than hand-rolled, so this can't independently drift from
+    // commitrepair.ts's own first-match rule (already drifted three times
+    // across call sites there — #51/#53/#56 — before firstFor consolidated it).
+    const applyTarget = (id) => firstFor(survivors.filter((q) => !withheld.has(q)), id);
+    return liveRewrites(queued, live)
+        .map((r) => {
+        const title = byId.get(r.id)?.title;
+        const named = `${r.id}${title ? ` ("${title}")` : ""}`;
+        const base = { kind: "commit-repair-pending", topic: r.id, decisionIds: [r.id], detail: `${r.from} → ${r.to}` };
+        const applyQuestion = `${named}'s commit is no longer reachable from HEAD (likely squash-merged away), and one newly-merged commit touches all its related files — apply the proposed replacement?`;
+        const isDropTarget = dropTarget(r.id) === r;
+        const isApplyTarget = applyTarget(r.id) === r;
+        if (!isDropTarget && !isApplyTarget) {
+            // A duplicate-id queue (corrupted file, hand edit, or a bug upstream —
+            // #53/#55/#56/#58): an earlier survivor for this id is what BOTH
+            // commands would act on, never this entry (#59). If this entry is
+            // itself withheld, say so too — that fact doesn't disappear just
+            // because it's also unreachable by id right now, and it stays
+            // drop-only even once it's next in line (never permanently: a fresh
+            // detection run can still supersede it with a resolvable match, same
+            // as the ordinary withheld branch below).
+            const alsoWithheld = withheld.has(r)
+                ? " — and its own proposed replacement doesn't resolve here either, so even once it's next in line it stays drop-only unless a fresh detection run supersedes it with a resolvable match"
+                : "";
+            return {
+                ...base,
+                actionable: false,
+                question: `${named} has a further queued replacement candidate (${r.from} → ${r.to}) sitting behind another entry for the same decision — leave it queued for now?`,
+                // Dropping the entry ahead brings this one back into play on the next
+                // run (deadRewrites can no longer see a reason to prune it). Applying
+                // it does the OPPOSITE for this entry: repairDecisionCommit moves the
+                // decision's `commit` past the `from` both entries share, so the next
+                // run's deadRewrites prunes THIS entry as stale — it is never
+                // reconsidered, not "resolved the normal way".
+                resolution: `not directly actionable by id right now: \`hunch repair-provenance --apply --only ${r.id} --expect ${reviewHash}\`/\`hunch repair-provenance --drop ${r.id} --expect ${reviewHash}\` both act on an entry queued ahead of it, never this one${alsoWithheld}. Dropping that entry brings this one back into consideration on the next run; applying it instead retires this one as stale, since the decision moves past the \`from\` both entries share.`,
+            };
+        }
+        if (!isDropTarget) {
+            // isApplyTarget is true here: this entry IS what --apply --only would
+            // apply, but an earlier, WITHHELD sibling for the same id sits ahead
+            // of it, so --drop <id> would tombstone that sibling instead (#59).
+            return {
+                ...base,
+                question: applyQuestion,
+                resolution: `hunch repair-provenance --apply --only ${r.id} --expect ${reviewHash} to accept just this one — but \`--drop ${r.id}\` won't reject THIS entry: an earlier queued sibling for the same id (whose own replacement doesn't resolve here) sits ahead of it and would be tombstoned instead.`,
+            };
+        }
+        if (!isApplyTarget) {
+            // isDropTarget is true here, so this can only mean withheld.has(r):
+            // a non-withheld first survivor is always its own apply-target too
+            // (nothing withheld can precede it if it isn't withheld itself), so
+            // isDropTarget && !isApplyTarget and "withheld" are the same fact.
+            return {
+                ...base,
+                question: `${named}'s commit is no longer reachable from HEAD (likely squash-merged away), and the queued replacement commit doesn't resolve in this repository (corrupted queue entry, or the commit has since been garbage-collected) — reject it?`,
+                resolution: `this entry can never be applied as-is — \`hunch repair-provenance --apply\` will leave it queued every run; \`hunch repair-provenance --drop ${r.id} --expect ${reviewHash}\` to reject it, or wait for a fresh match to supersede it`,
+            };
+        }
+        return {
+            ...base,
+            question: applyQuestion,
+            resolution: `hunch repair-provenance --apply --only ${r.id} --expect ${reviewHash} to accept just this one, hunch repair-provenance --drop ${r.id} --expect ${reviewHash} to reject it (tombstoned durably — this same match won't resurface, though a genuinely different candidate still can), or leave it queued to decide later`,
+        };
+    });
+}
 /** The Constitution's genuine human moments (§59.5.3), framed as inline questions:
  *  a candidate awaiting review, and a proposed policy whose next step (prove, or
  *  accept/reject) is a human call. Machine conclusions never appear here as

package/dist/core/events.d.ts

@@ -0,0 +1,29 @@
+import type { HunchPaths } from "./paths.js";
+/** One enforcement event. `kind` is open-ended so the conformance/drift gates can
+ *  append their own shapes later; `subject`/`object`/`assert` stay OPTIONAL and
+ *  are populated ONLY by a gate that genuinely has them (never a plain block). */
+export interface HunchEvent {
+    /** ISO instant the gate fired. */
+    at: string;
+    kind: "constraint" | "veto" | "conformance" | "drift";
+    /** Repo-relative file the blocked edit targeted. */
+    file: string;
+    /** Decision the block enforces (veto/conformance carry this; a bare constraint may not). */
+    decision?: string;
+    /** Constraint id, when the block came from a blocking invariant. */
+    constraint?: string;
+    /** Human-readable rule text, for receipts. */
+    statement?: string;
+    /** Conformance-only predicate shape — never set by a constraint/veto block. */
+    subject?: string;
+    object?: string;
+    assert?: string;
+}
+export declare function eventsLogPath(paths: HunchPaths): string;
+/** Append one event as a JSONL line. Best-effort and never throws: the primary
+ *  call site is the edit hook, which MUST NEVER break an agent on failure
+ *  (con_03a0b94b2e). A dropped catch-log line is an acceptable loss. */
+export declare function appendEvent(paths: HunchPaths, event: HunchEvent): void;
+/** Read + parse the catch-log. Malformed lines are skipped, not fatal (the log is
+ *  derived; one bad line never poisons the aggregation). Missing log → []. */
+export declare function readEvents(paths: HunchPaths): HunchEvent[];

package/dist/core/evidenceMap.d.ts

@@ -0,0 +1,164 @@
+import { z } from "zod";
+export declare const EvidenceOutcomeSchema: z.ZodEnum<{
+    error: "error";
+    red: "red";
+    green: "green";
+    "not-run": "not-run";
+}>;
+export declare const EvidenceOwnerSchema: z.ZodString;
+export declare const EvidenceProbeSchema: z.ZodObject<{
+    target_before: z.ZodEnum<{
+        error: "error";
+        red: "red";
+        green: "green";
+        "not-run": "not-run";
+    }>;
+    control_before: z.ZodEnum<{
+        error: "error";
+        red: "red";
+        green: "green";
+        "not-run": "not-run";
+    }>;
+    target_after: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        red: "red";
+        green: "green";
+        "not-run": "not-run";
+    }>>;
+    control_after: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        red: "red";
+        green: "green";
+        "not-run": "not-run";
+    }>>;
+}, z.core.$strict>;
+export declare const EvidenceExecutionSchema: z.ZodObject<{
+    owner: z.ZodString;
+    target_count: z.ZodNumber;
+    control_count: z.ZodNumber;
+}, z.core.$strict>;
+export declare const EvidenceInterventionSchema: z.ZodObject<{
+    owner: z.ZodString;
+    mutation_id: z.ZodOptional<z.ZodString>;
+    target_after: z.ZodEnum<{
+        error: "error";
+        red: "red";
+        green: "green";
+        "not-run": "not-run";
+    }>;
+    control_after: z.ZodEnum<{
+        error: "error";
+        red: "red";
+        green: "green";
+        "not-run": "not-run";
+    }>;
+}, z.core.$strict>;
+export declare const VerifiedEvidenceReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    claim: z.ZodString;
+    probe: z.ZodObject<{
+        target_before: z.ZodEnum<{
+            error: "error";
+            red: "red";
+            green: "green";
+            "not-run": "not-run";
+        }>;
+        control_before: z.ZodEnum<{
+            error: "error";
+            red: "red";
+            green: "green";
+            "not-run": "not-run";
+        }>;
+        target_after: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            red: "red";
+            green: "green";
+            "not-run": "not-run";
+        }>>;
+        control_after: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            red: "red";
+            green: "green";
+            "not-run": "not-run";
+        }>>;
+    }, z.core.$strict>;
+    execution: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        target_count: z.ZodNumber;
+        control_count: z.ZodNumber;
+    }, z.core.$strict>>>;
+    interventions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        mutation_id: z.ZodOptional<z.ZodString>;
+        target_after: z.ZodEnum<{
+            error: "error";
+            red: "red";
+            green: "green";
+            "not-run": "not-run";
+        }>;
+        control_after: z.ZodEnum<{
+            error: "error";
+            red: "red";
+            green: "green";
+            "not-run": "not-run";
+        }>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type EvidenceOutcome = z.infer<typeof EvidenceOutcomeSchema>;
+export type VerifiedEvidenceReceipt = z.infer<typeof VerifiedEvidenceReceiptSchema>;
+export interface EvidenceFile {
+    path: string;
+    target_execution_owners: string[];
+    target_only_owners: string[];
+    shared_execution_owners: string[];
+    strong_differential_owners: string[];
+    strong_differential_support: number;
+    behavior_sensitive_owners: string[];
+    evidence: Array<"target-execution" | "target-only-execution" | "shared-execution" | "strong-differential-execution" | "behavior-sensitive">;
+}
+export interface VerifiedEvidenceMap {
+    version: 1;
+    claim: string;
+    level: "unverified" | "probe-authenticated" | "execution-verified" | "behavior-sensitive";
+    verification: {
+        authenticated: boolean;
+        target_before: EvidenceOutcome;
+        control_before: EvidenceOutcome;
+        reason: string;
+    };
+    closure: {
+        status: "unverified" | "open" | "still-red" | "closed" | "control-unchecked" | "control-regressed" | "probe-error";
+        target_after: EvidenceOutcome | null;
+        control_after: EvidenceOutcome | null;
+    };
+    execution_slice: {
+        target_observed_owners: string[];
+        target_only_owners: string[];
+        shared_owners: string[];
+        strong_differential_owners: string[];
+        strong_differential_files: string[];
+        strong_differential: Array<{
+            owner: string;
+            target_count: number;
+            control_count: number;
+            ratio: number;
+        }>;
+    };
+    intervention_slice: {
+        admitted_receipts: number;
+        behavior_sensitive_owners: string[];
+        behavior_sensitive_files: string[];
+    };
+    files: EvidenceFile[];
+    owner_claim: {
+        enabled: false;
+        owner: null;
+        reason: string;
+    };
+    limitations: string[];
+}
+/** Compile externally observed receipts into a bounded evidence map. This is
+ * deliberately pure: it runs no probe, edits no source, and never turns causal
+ * influence into a correction-owner claim. */
+export declare function compileVerifiedEvidenceMap(value: unknown): VerifiedEvidenceMap;
+export declare function formatVerifiedEvidenceMap(map: VerifiedEvidenceMap): string;

package/dist/core/externalImports.d.ts

@@ -0,0 +1,8 @@
+/** Canonical package identity for a static module specifier. Relative, absolute,
+ * package-import-map (#), and URL-like specifiers are repository/runtime-local
+ * and deliberately outside the external-dependency evaluator. */
+export declare function externalPackage(specifier: string): string | null;
+/** Virtual graph target for an external package. It is intentionally not a
+ * Component record: package facts stay a bounded evaluator layer and do not
+ * inflate the human-curated component graph. */
+export declare function externalImportNodeId(specifier: string): string | null;

package/dist/core/format.d.ts

@@ -0,0 +1,13 @@
+/** Render an AssembledContext as a compact, agent-ready brief: invariants first
+ *  (what must not break), then the why, blast radius, and bug history — each with
+ *  provenance so the agent can weight it. Shared by the CLI and the MCP tool. */
+import type { AssembledContext, SearchHit, StructureView } from "../store/hunchStore.js";
+import { type DeliveryOptions } from "./delivery.js";
+export declare function formatContext(ctx: AssembledContext, options?: DeliveryOptions): string;
+/** One search hit as `hunch query` / hunch_query print it (headline + indented detail line).
+ *  Graph records keep their `[kind] id — title` shape; a nuryel.state/1 hit renders through
+ *  renderStateLine (`[commitment/in_force] customer:Site:7 — "send report" due … (owner …)`)
+ *  with the record id on the detail line, so both readers say the same thing. */
+export declare function formatSearchHit(hit: SearchHit, record: unknown): string;
+/** Render a StructureView as a compact orientation brief (hunch_structure). */
+export declare function formatStructure(v: StructureView): string;

package/dist/core/glob.d.ts

@@ -0,0 +1,9 @@
+/** Minimal, segment-aware glob matching for constraint `scope` / component
+ *  `paths` (e.g. "src/auth/**"). Supports **, *, and ? with correct path-segment
+ *  semantics (`**` spans separators; `*`/`?` stay within one segment). No dep. */
+/** Does a concrete path match a glob? Also returns true when the glob is a bare
+ *  directory prefix of the path (so "src/auth" matches "src/auth/x.ts"). */
+export declare function pathMatchesGlob(path: string, glob: string): boolean;
+/** Do two concrete repo paths identify the same path at different prefix depth?
+ * Segment-anchored: `x/scenario.ts` relates to `scenario.ts`, never `io.ts`. */
+export declare function pathsRelated(left: string, right: string): boolean;

package/dist/core/groundingLag.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Grounding-block freshness classification (fnd_c402046ac7).
+ *
+ * The committed grounding docs (CLAUDE.md, AGENTS.md, copilot-instructions,
+ * hunch.mdc, hunch.md) carry a managed block whose first sentence states the
+ * public store's RECORD COUNTS. Those counts are a pure function of .hunch/*.json,
+ * so two branches that each capture one decision both regenerate the very same
+ * "N+1 decisions" line. Git merges identical lines silently, the merged store holds
+ * N+2, and the committed doc is one behind — with no conflict, no hook (the merge
+ * happened on the forge) and no human error. Every release-gate red of that class
+ * (PR #128, #135, v1.26.2's first run) was this lag.
+ *
+ * The lag is transient and self-healing: the next capture commit folds the
+ * regenerated docs in (refreshCommittableGrounding), and the release gate's
+ * repository-index stage regenerates them in the worktree and already treats the
+ * dirt as memory churn. What must STILL fail is a doc that is genuinely wrong:
+ *
+ *   - prose in the block differs (a hand edit, a stale renderer, a template change);
+ *   - an append-only count is AHEAD of the store: the doc counted a record the
+ *     repository does not carry — the never-committed Video component of
+ *     fnd_6391b4242f, the only defect the counts ever caught.
+ *
+ * So the rule is direction-aware and deterministic: decisions, bugs, constraints,
+ * components and policies only accrue, so a doc may lag behind them (merge) but never
+ * run ahead (missing record). Open findings move both ways (a finding resolved on one
+ * branch, a finding recorded on another), so a differing findings count alone is lag.
+ */
+export interface GroundingCounts {
+    decisions: number;
+    bugs: number;
+    constraints: number;
+    components: number;
+    policies: number;
+    findings: number;
+}
+/** Record kinds whose committed count may only ever lag behind the store. */
+export declare const APPEND_ONLY_COUNT_KINDS: readonly ["decisions", "bugs", "constraints", "components", "policies"];
+/** Render the counts sentence's bold `**N decisions, ...**` segment — the
+ *  exact text parseGroundingCounts looks for. The single source of truth for
+ *  the format, shared by the doc generator (claudemd.ts) and the grounding
+ *  merge driver (groundingMerge.ts) so they can never drift out of sync. */
+export declare function renderCountsMatch(counts: GroundingCounts): string;
+/** Replace a counts-sentence match with a neutral placeholder, so the rest of
+ *  two texts can be compared for equality regardless of their counts. Shared
+ *  by classifyGroundingBlock (committed doc vs computed) and the grounding
+ *  merge driver (ours vs theirs) — both ask "do these two texts differ ONLY
+ *  in the counts sentence?" */
+export declare function stripCountsMatch(text: string, match: string): string;
+export declare function parseGroundingCounts(block: string): {
+    counts: GroundingCounts;
+    match: string;
+} | null;
+export type GroundingFreshness = 
+/** Byte-identical managed block. */
+{
+    kind: "fresh";
+}
+/** Only the counts sentence differs and no append-only count is ahead of the
+ *  store: records merged in behind the doc. Heals on the next capture or
+ *  `hunch grounding --refresh`; never a release blocker. */
+ | {
+    kind: "lagging";
+    committed: GroundingCounts;
+    generated: GroundingCounts;
+    behind: string[];
+}
+/** An append-only count in the committed doc exceeds the store: the doc knows a
+ *  record the repository does not carry (never committed, or pruned by hand). */
+ | {
+    kind: "ahead";
+    committed: GroundingCounts;
+    generated: GroundingCounts;
+    ahead: string[];
+}
+/** The block differs outside the counts sentence (or a counts sentence is missing). */
+ | {
+    kind: "diverged";
+    reason: string;
+};
+/** Classify a committed managed block against the one the graph generates NOW.
+ *  Both inputs are block CONTENT (markers stripped, trimmed). */
+export declare function classifyGroundingBlock(committed: string, generated: string): GroundingFreshness;
+/** One human line per verdict — shared by the freshness test and `hunch grounding`. */
+export declare function describeGroundingFreshness(doc: string, verdict: GroundingFreshness): string;

package/dist/core/groundingLag.js

@@ -28,6 +28,21 @@
 const COUNTS_RE = /\*\*(\d+) decisions?, (\d+) bugs?, (\d+) constraints?, (\d+) components?, (\d+) polic(?:y|ies)(?:, (\d+) open findings?)?\*\*/;
 /** Record kinds whose committed count may only ever lag behind the store. */
 export const APPEND_ONLY_COUNT_KINDS = ["decisions", "bugs", "constraints", "components", "policies"];
+/** Render the counts sentence's bold `**N decisions, ...**` segment — the
+ *  exact text parseGroundingCounts looks for. The single source of truth for
+ *  the format, shared by the doc generator (claudemd.ts) and the grounding
+ *  merge driver (groundingMerge.ts) so they can never drift out of sync. */
+export function renderCountsMatch(counts) {
+    return `**${counts.decisions} decisions, ${counts.bugs} bugs, ${counts.constraints} constraints, ${counts.components} components, ${counts.policies} policies${counts.findings ? `, ${counts.findings} open findings` : ""}**`;
+}
+/** Replace a counts-sentence match with a neutral placeholder, so the rest of
+ *  two texts can be compared for equality regardless of their counts. Shared
+ *  by classifyGroundingBlock (committed doc vs computed) and the grounding
+ *  merge driver (ours vs theirs) — both ask "do these two texts differ ONLY
+ *  in the counts sentence?" */
+export function stripCountsMatch(text, match) {
+    return text.replace(match, "<counts>");
+}
 export function parseGroundingCounts(block) {
     const m = COUNTS_RE.exec(block);
     if (!m)
@@ -55,8 +70,7 @@ export function classifyGroundingBlock(committed, generated) {
         return { kind: "diverged", reason: "the committed block carries no record-counts sentence" };
     if (!g)
         return { kind: "diverged", reason: "the generated block carries no record-counts sentence" };
-    const withoutCounts = (text, match) => text.replace(match, "<counts>");
-    if (withoutCounts(committed, c.match) !== withoutCounts(generated, g.match)) {
+    if (stripCountsMatch(committed, c.match) !== stripCountsMatch(generated, g.match)) {
         return { kind: "diverged", reason: "the block differs outside the record-counts sentence" };
     }
     const ahead = APPEND_ONLY_COUNT_KINDS.filter((k) => c.counts[k] > g.counts[k]);

package/dist/core/groundingMerge.d.ts

@@ -0,0 +1,15 @@
+/** Given `git merge-file --diff3 -L ours -L base -L theirs` output for a
+ *  generated grounding doc, auto-resolve it if every conflicting hunk is
+ *  confined to the counts sentence; otherwise return it untouched. */
+export declare function resolveGroundingConflicts(diff3Text: string): {
+    conflict: boolean;
+    text: string;
+};
+/** Run `git merge-file --diff3` on real files and resolve the result.
+ *  `write: null` means git itself errored (e.g. one side is binary) — never
+ *  guess content in that case; leave the file exactly as git already
+ *  populated it before invoking this driver. */
+export declare function mergeGroundingFile(basePath: string, oursPath: string, theirsPath: string): {
+    conflict: boolean;
+    write: string | null;
+};

package/dist/core/groundingMerge.js

@@ -0,0 +1,95 @@
+/**
+ * Merge driver for the generated grounding block's record-counts sentence
+ * (dec_ba5b0dfa22, superseding dec_91da20a46b's "drop the counts sentence"):
+ * resolves a HARD git conflict when it is confined to that one line by
+ * taking the ELEMENT-WISE MAX of ours's and theirs's counts, per field, as a
+ * placeholder. Picking `ours` unconditionally would discard whichever side
+ * carried the HIGHER count — and a higher count can itself be the
+ * ahead-of-store signal fnd_6391b4242f depends on (a branch whose doc claims
+ * a record its own committed store never received). Taking the max instead:
+ * when neither side already carries that defect, the merged store's counts
+ * can only be >= max(ours, theirs) (decisions/bugs/constraints/components/
+ * policies are append-only, and the merged store is the union of both
+ * sides' committed records), so the doc reads as "lagging" — self-healed by
+ * the post-merge hook's `hunch grounding --refresh` — never falsely "ahead".
+ * But when one side DOES already carry the defect, its inflated count
+ * survives into the resolution and correctly still reads as "ahead" against
+ * the true merged store, instead of being silently discarded. Any conflict
+ * outside the counts sentence, anywhere in the file, is left untouched with
+ * standard diff3 markers for a human to resolve.
+ */
+import { execFileSync } from "node:child_process";
+import { parseGroundingCounts, stripCountsMatch, renderCountsMatch } from "./groundingLag.js";
+// `\r?\n` (not a bare `\n`) throughout: on a CRLF worktree every diff3 marker
+// line is itself `\r\n`-terminated, and a bare `\n` fails to match ANY of
+// them. `^...$` with /m anchor each marker at its own line start rather than
+// requiring a specific preceding/following literal newline, so a hunk whose
+// ours or theirs side is EMPTY (one side deleted the line, the other edited
+// it) still matches — with a literal `\n` requirement there, git's real
+// output for that shape has no such newline to match, so the whole hunk
+// silently fails to match at all.
+const CONFLICT_RE = /^<<<<<<< ours\r?\n([\s\S]*?)^\|\|\|\|\|\|\| base\r?\n[\s\S]*?^=======\r?\n([\s\S]*?)^>>>>>>> theirs[^\n]*\r?\n?/gm;
+/** `null` when the hunk isn't confined to the counts sentence; otherwise the
+ *  resolved sentence text, with each field taken as max(ours, theirs). */
+function resolveCountsOnlyHunk(ours, theirs) {
+    const o = parseGroundingCounts(ours);
+    const t = parseGroundingCounts(theirs);
+    if (!o || !t)
+        return null;
+    if (stripCountsMatch(ours, o.match) !== stripCountsMatch(theirs, t.match))
+        return null;
+    const keys = Object.keys(o.counts);
+    if (keys.every((k) => o.counts[k] >= t.counts[k]))
+        return ours; // ours already dominates every field verbatim
+    const combined = { ...o.counts };
+    for (const k of keys)
+        combined[k] = Math.max(o.counts[k], t.counts[k]);
+    return ours.replace(o.match, renderCountsMatch(combined));
+}
+/** Given `git merge-file --diff3 -L ours -L base -L theirs` output for a
+ *  generated grounding doc, auto-resolve it if every conflicting hunk is
+ *  confined to the counts sentence; otherwise return it untouched. */
+export function resolveGroundingConflicts(diff3Text) {
+    if (!diff3Text.includes("<<<<<<< ours"))
+        return { conflict: false, text: diff3Text };
+    let allResolved = true;
+    const resolved = diff3Text.replace(CONFLICT_RE, (whole, ours, theirs) => {
+        const merged = resolveCountsOnlyHunk(ours, theirs);
+        if (merged === null) {
+            allResolved = false;
+            return whole;
+        }
+        return merged;
+    });
+    // Defense in depth: a hunk shape CONFLICT_RE fails to recognize must never
+    // read as resolved just because the callback never ran on it — if any
+    // marker survives, this is a real conflict, full stop.
+    if (!allResolved || resolved.includes("<<<<<<< ours"))
+        return { conflict: true, text: diff3Text };
+    return { conflict: false, text: resolved };
+}
+/** Run `git merge-file --diff3` on real files and resolve the result.
+ *  `write: null` means git itself errored (e.g. one side is binary) — never
+ *  guess content in that case; leave the file exactly as git already
+ *  populated it before invoking this driver. */
+export function mergeGroundingFile(basePath, oursPath, theirsPath) {
+    try {
+        const merged = execFileSync("git", ["merge-file", "-p", "--diff3", "-L", "ours", "-L", "base", "-L", "theirs", oursPath, basePath, theirsPath], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        return { conflict: false, write: merged };
+    }
+    catch (e) {
+        const err = e;
+        const status = typeof err.status === "number" ? err.status : -1;
+        // `git merge-file`'s exit status is the number of conflicting hunks
+        // (1-127) on a genuine 3-way merge attempt. Anything else (a negative
+        // status, or >127) means git itself errored — e.g. "Cannot merge binary
+        // files" exits 255 with EMPTY stdout — and treating that as diff3 output
+        // silently truncates the file to nothing.
+        if (status < 1 || status > 127)
+            return { conflict: true, write: null };
+        const out = typeof err.stdout === "string" ? err.stdout : (err.stdout?.toString() ?? "");
+        const res = resolveGroundingConflicts(out);
+        return { conflict: res.conflict, write: res.text };
+    }
+}
+//# sourceMappingURL=groundingMerge.js.map

package/dist/core/hookObservations.d.ts

@@ -0,0 +1,9 @@
+export interface HookObservation {
+    provider: string;
+    event: string;
+    at: string;
+    version: string;
+}
+/** Never throws (con_03a0b94b2e): a missing ledger costs evidence, not the edit. */
+export declare function recordHookObservation(root: string, provider: string, event: string): void;
+export declare function readHookObservations(root: string): HookObservation[];