@davesheffer/hunch 1.45.2 → 1.47.0

package/dist/core/escalations.d.ts

@@ -33,76 +33,34 @@ export interface Escalation {
     detail: string;
     /** the concrete resolution the human's answer maps to. */
     resolution: string;
-    /** false ONLY for an entry whose own resolution requires acting on a
-     *  DIFFERENT entry first (a duplicate-id queue's non-drop, non-apply
-     *  follower) — it still surfaces, for transparency, but gating surfaces
-     *  (CI exit code, "needs your call" tallies) must not count it: resolving
-     *  the actionable entry ahead of it is what clears it, not anything a
-     *  human can do to this row directly (#61). Omitted (undefined) means
-     *  true — every other escalation kind is always directly actionable. */
+    /** `false` marks an entry whose resolution depends on first acting on a DIFFERENT
+     *  entry: the non-drop, non-apply follower in a duplicate-id commit-repair queue.
+     *  It still surfaces for transparency, but gating surfaces (the CI exit code and
+     *  "needs your call" tallies) must not count it. Omitted/undefined = actionable. */
     actionable?: boolean;
 }
-/** 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). */
+/** The entries a human can act on right now (order preserved). */
 export declare function actionableEscalations(items: readonly Escalation[]): Escalation[];
 export interface EscalationSummary {
-    /** the subset a gating surface should count/exit/ask on. */
+    /** the gating subset. */
     actionable: Escalation[];
-    /** how many entries were filtered out — informational-only, shown for
-     *  transparency but not itself a decision to raise. */
+    /** how many entries were filtered out as context-only. */
     context: number;
 }
-/** 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 declare function summarizeEscalations(items: readonly Escalation[]): EscalationSummary;
-/** "you" (the CLI, talking directly to the operator) vs "mcp" (an assistant
- *  relaying a question to the human, third person). */
+/** "cli" speaks to the operator (second person); "mcp" is an assistant relaying to the human (third person). */
 export type EscalationAudience = "cli" | "mcp";
-/** 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). */
+/** One-line heading for a non-empty escalation list. Callers handle the empty list themselves. */
 export declare function escalationHeadline(items: readonly Escalation[], audience: EscalationAudience): string;
 /** The decisions a human must make NOW, to be asked INLINE. Empty in a healthy graph. */
 export declare function pendingEscalations(decisions: readonly Decision[]): Escalation[];
-/** 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. */
+/** A commit-provenance repair the post-merge hook queued but never applied is a human
+ *  question, never a silent write. `decisions` is the caller's VISIBLE scope and supplies
+ *  titles only. `live` is the scope liveness is checked against: callers on an advisory
+ *  scope pass the full store so an overlay decision's repair isn't silenced just because
+ *  its title is private. `withheld` holds entries whose proposed `to` doesn't resolve to a
+ *  real commit; membership is by object identity, not id, so two corrupted entries
+ *  sharing an id stay distinguishable. */
 export declare function commitRepairEscalations(queued: readonly CommitRewrite[], decisions: readonly Decision[], live?: readonly Decision[], withheld?: ReadonlySet<CommitRewrite>): Escalation[];
 /** The minimal policy shape the escalation scan needs — a structural subset of
  *  constitution PolicySpec, so this module stays dependency-free of the

package/dist/core/escalations.js

@@ -2,39 +2,26 @@ import { topicCollisions } from "./topics.js";
 import { liveRewrites, deadRewrites, commitRepairReviewHash, firstFor } from "./commitrepair.js";
 import { importedAdrReviewHash, importedAdrSourceHash, pendingImportedAdrReviews } from "./importReview.js";
 import { pathMatchesGlob } from "./glob.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). */
+/** The entries a human can act on right now (order preserved). */
 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). */
+/** One-line heading for a non-empty escalation list. Callers handle the empty list themselves. */
 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 mcp = audience === "mcp";
+    if (actionable.length === 0) {
+        const t = items.length;
+        return `Nothing needs ${mcp ? "the human's call" : "your decision"} right now — ${t} ${t === 1 ? "entry" : "entries"} shown below for context only (resolving another entry will clear them):`;
     }
-    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):`;
+    const note = context > 0 ? ` (+${context} shown below for context only, not ${mcp ? "a decision" : "gating"})` : "";
+    return mcp
+        ? `${actionable.length} decision(s) need the human's call — ask each inline, don't decide it for them${note}:`
+        : `${actionable.length} decision(s) need your call — asked here, never decided for you${note}:`;
 }
 /** The decisions a human must make NOW, to be asked INLINE. Empty in a healthy graph. */
 export function pendingEscalations(decisions) {
@@ -71,123 +58,54 @@ 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. */
+/** A commit-provenance repair the post-merge hook queued but never applied is a human
+ *  question, never a silent write. `decisions` is the caller's VISIBLE scope and supplies
+ *  titles only. `live` is the scope liveness is checked against: callers on an advisory
+ *  scope pass the full store so an overlay decision's repair isn't silenced just because
+ *  its title is private. `withheld` holds entries whose proposed `to` doesn't resolve to a
+ *  real commit; membership is by object identity, not id, so two corrupted entries
+ *  sharing an id stay distinguishable. */
 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 visible = new Map(decisions.map((d) => [d.id, d]));
+    // Mirror the CLI: dead entries are pruned before --apply/--drop read the queue.
+    const dead = new Set(deadRewrites(queued, live));
+    const survivors = queued.filter((r) => !dead.has(r));
     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 applyTarget = (id) => firstFor(survivors.filter((r) => !withheld.has(r)), id);
+    return liveRewrites(queued, live).map((r) => {
+        const title = visible.get(r.id)?.title;
+        const named = title ? `${r.id} ("${title}")` : r.id;
+        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 isDrop = dropTarget(r.id) === r;
+        const isApply = applyTarget(r.id) === r;
+        if (!isDrop && !isApply) {
             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"
+                ? ` — and this entry's own proposed replacement doesn't resolve here either, so even once it is 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).
+        if (isApply && !isDrop) {
+            // An earlier withheld sibling sits ahead: --drop would tombstone that one instead.
             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.
+        if (isDrop && !isApply) {
+            // Equivalent to `r` being withheld.
             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?`,

package/dist/core/glob.d.ts

@@ -7,18 +7,18 @@ 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;
-/** True when `target` is a path Hunch's index already knows about: an indexed
- *  symbol's exact file, or a path an indexed component's `paths` glob(s) cover.
- *  The latter catches a symbol-less-but-indexed file (README.md, package.json,
- *  Dockerfile, ...) that has zero tree-sitter symbols but is still a real,
- *  known file. Derived entirely from already-loaded graph data — never the
- *  filesystem — so the answer doesn't depend on untracked working-tree state
+/** True when `target` is a path the index already knows: an indexed symbol's
+ *  exact file, or a path covered by an indexed component's `paths` globs (which
+ *  catches symbol-less but indexed files such as README, package manifests,
+ *  Dockerfiles). Derived only from already-loaded graph data, never the
+ *  filesystem, so the answer cannot depend on untracked working-tree state
  *  (a deleted-but-still-indexed path stays "real"; issue #299). It is therefore
  *  only HALF the "is this a real path" question: a real file with no symbols and
  *  no covering component is invisible here, so callers OR in `isRepoFile` as a
  *  last resort (issue #334) — `HunchStore.isKnownPath` is that composition. */
 export declare function isIndexedPath(target: string, symbolFiles: Iterable<string>, componentPaths: Iterable<readonly string[]>): boolean;
-/** Resolve symbols matching `target`, tiered: exact id > exact name > exact file >
+/** Resolve the symbols a `target` names, strictly tiered, first non-empty tier
+ *  wins: exact id, then exact name, then exact file, then — conditionally —
  *  (only when `target` is NOT a path already known to be real) segment-anchored
  *  suffix. A real file with zero symbols must return [] rather than fall through
  *  to the suffix tier, which would leak an unrelated same-basename file's records

package/dist/core/glob.js

@@ -66,12 +66,11 @@ export function pathsRelated(left, right) {
     const b = norm(right);
     return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
 }
-/** True when `target` is a path Hunch's index already knows about: an indexed
- *  symbol's exact file, or a path an indexed component's `paths` glob(s) cover.
- *  The latter catches a symbol-less-but-indexed file (README.md, package.json,
- *  Dockerfile, ...) that has zero tree-sitter symbols but is still a real,
- *  known file. Derived entirely from already-loaded graph data — never the
- *  filesystem — so the answer doesn't depend on untracked working-tree state
+/** True when `target` is a path the index already knows: an indexed symbol's
+ *  exact file, or a path covered by an indexed component's `paths` globs (which
+ *  catches symbol-less but indexed files such as README, package manifests,
+ *  Dockerfiles). Derived only from already-loaded graph data, never the
+ *  filesystem, so the answer cannot depend on untracked working-tree state
  *  (a deleted-but-still-indexed path stays "real"; issue #299). It is therefore
  *  only HALF the "is this a real path" question: a real file with no symbols and
  *  no covering component is invisible here, so callers OR in `isRepoFile` as a
@@ -80,13 +79,15 @@ export function isIndexedPath(target, symbolFiles, componentPaths) {
     for (const f of symbolFiles)
         if (f === target)
             return true;
-    for (const globs of componentPaths)
+    for (const globs of componentPaths) {
         for (const g of globs)
             if (pathMatchesGlob(target, g))
                 return true;
+    }
     return false;
 }
-/** Resolve symbols matching `target`, tiered: exact id > exact name > exact file >
+/** Resolve the symbols a `target` names, strictly tiered, first non-empty tier
+ *  wins: exact id, then exact name, then exact file, then — conditionally —
  *  (only when `target` is NOT a path already known to be real) segment-anchored
  *  suffix. A real file with zero symbols must return [] rather than fall through
  *  to the suffix tier, which would leak an unrelated same-basename file's records
@@ -102,9 +103,9 @@ export function matchSymbolsTiered(target, symbols, indexed) {
     const byName = symbols.filter((s) => s.name === target);
     if (byName.length)
         return byName;
-    const exact = symbols.filter((s) => s.file === target);
-    if (exact.length)
-        return exact;
+    const byFile = symbols.filter((s) => s.file === target);
+    if (byFile.length)
+        return byFile;
     if (indexed)
         return [];
     return symbols.filter((s) => pathsRelated(s.file, target));

package/dist/core/groundingLag.d.ts

@@ -38,16 +38,9 @@ export interface GroundingCounts {
 }
 /** 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. */
+/** Render the bold counts segment `parseGroundingCounts` reads. Shared by claudemd.ts and the merge driver. */
 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?" */
+/** `text` with its counts segment swapped for a neutral token, so two texts compare equal regardless of counts. */
 export declare function stripCountsMatch(text: string, match: string): string;
 export declare function parseGroundingCounts(block: string): {
     counts: GroundingCounts;

package/dist/core/groundingLag.js

@@ -35,20 +35,14 @@ export function groundingTemplate(block) {
 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. */
+/** Render the bold counts segment `parseGroundingCounts` reads. Shared by claudemd.ts and the merge driver. */
 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` : ""}**`;
+    const tail = counts.findings ? `, ${counts.findings} open findings` : "";
+    return `**${counts.decisions} decisions, ${counts.bugs} bugs, ${counts.constraints} constraints, ${counts.components} components, ${counts.policies} policies${tail}**`;
 }
-/** 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?" */
+/** `text` with its counts segment swapped for a neutral token, so two texts compare equal regardless of counts. */
 export function stripCountsMatch(text, match) {
-    return text.replace(match, "<counts>");
+    return text.replace(match, () => "<counts>");
 }
 export function parseGroundingCounts(block) {
     const m = COUNTS_RE.exec(block);

package/dist/core/groundingMerge.d.ts

@@ -1,14 +1,9 @@
-/** 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. */
+/** Input is `git merge-file --diff3 -L ours -L base -L theirs` output. */
 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. */
+/** Three-way merge of a grounding doc; the CLI writes `write` to the ours path and exits 1 on conflict. */
 export declare function mergeGroundingFile(basePath: string, oursPath: string, theirsPath: string): {
     conflict: boolean;
     write: string | null;

package/dist/core/groundingMerge.js

@@ -1,37 +1,31 @@
 /**
- * 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.
+ * Merge driver for the generated grounding block's record-counts sentence.
+ *
+ * When two branches each regenerate the block, git reports a hard conflict on
+ * that one line. This driver resolves a conflict confined to it by taking the
+ * element-wise maximum of the two sides' counts.
+ *
+ * "Take ours" would be simpler but could discard a higher count, and a higher
+ * count may be the ahead-of-store signal that freshness classification relies
+ * on. The maximum is safe: append-only kinds only grow and the merged store is
+ * the union of both sides, so the result reads as "lagging" (self-healed by the
+ * post-merge `hunch grounding --refresh`), never falsely "ahead". An inflated
+ * count from a side that genuinely carries the defect survives and still reads
+ * "ahead".
+ *
+ * A conflict anywhere else is left untouched, with standard diff3 markers.
  */
 import { execFileSync } from "node:child_process";
 import { parseGroundingCounts, stripCountsMatch, renderCountsMatch } from "./groundingLag.js";
 import { normalizeEol } from "./eol.js";
 // The entry point normalizes EOL before matching. `^...$` with /m anchors
 // 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.
+// demanding a literal newline before or after a marker: a hunk with an empty
+// side (one side deleted the line, the other edited it) has no such newline in
+// git's real output, so a pattern requiring one would silently miss it.
 const CONFLICT_RE = /^<<<<<<< ours\n([\s\S]*?)^\|\|\|\|\|\|\| base\n[\s\S]*?^=======\n([\s\S]*?)^>>>>>>> theirs[^\n]*\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) {
+/** Resolve one hunk's ours/theirs text, or null when it is not confined to the counts sentence. */
+function resolveHunk(ours, theirs) {
     const o = parseGroundingCounts(ours);
     const t = parseGroundingCounts(theirs);
     if (!o || !t)
@@ -40,15 +34,13 @@ function resolveCountsOnlyHunk(ours, theirs) {
         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
+        return ours;
     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));
+    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. */
+/** Input is `git merge-file --diff3 -L ours -L base -L theirs` output. */
 export function resolveGroundingConflicts(diff3Text) {
     if (!diff3Text.includes("<<<<<<< ours"))
         return { conflict: false, text: diff3Text };
@@ -56,42 +48,31 @@ export function resolveGroundingConflicts(diff3Text) {
     const normalized = normalizeEol(diff3Text);
     let allResolved = true;
     const resolved = normalized.replace(CONFLICT_RE, (whole, ours, theirs) => {
-        const merged = resolveCountsOnlyHunk(ours, theirs);
-        if (merged === null) {
+        const out = resolveHunk(ours, theirs);
+        if (out === null) {
             allResolved = false;
             return whole;
         }
-        return merged;
+        return out;
     });
-    // 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: eol === "\n" ? resolved : resolved.replace(/\n/g, eol) };
 }
-/** 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. */
+/** Three-way merge of a grounding doc; the CLI writes `write` to the ours path and exits 1 on conflict. */
 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 };
+        const out = 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: out };
     }
     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 };
+        const status = err.status;
+        if (typeof status === "number" && status >= 1 && status <= 127) {
+            const res = resolveGroundingConflicts(err.stdout == null ? "" : String(err.stdout));
+            return { conflict: res.conflict, write: res.text };
+        }
+        return { conflict: true, write: null };
     }
 }
 //# sourceMappingURL=groundingMerge.js.map

package/dist/core/migrate.d.ts

@@ -10,6 +10,9 @@ export interface Migration {
     /** The version this migration PRODUCES (i.e. it upgrades version-1 → `version`). */
     version: number;
     description: string;
+    /** The kinds `up` changes. Omitted = it may touch any kind (conservative: a
+     *  failed record of any kind then holds the manifest version). */
+    kinds?: EntityKind[];
     /** Transform one raw record (untrusted JSON) of `kind` to the next shape. */
     up(kind: EntityKind, raw: Record<string, unknown>): Record<string, unknown>;
 }
@@ -24,5 +27,11 @@ export declare function readManifest(paths: HunchPaths): Manifest;
 /** Write `.hunch/manifest.json` at `version` (default: the current SCHEMA_VERSION). */
 export declare function writeManifest(paths: HunchPaths, version?: number): void;
 /** Apply every migration in (fromVersion, toVersion] to a single raw record. Skips
- *  non-object input untouched (the loader's Zod pass will reject it). */
+ *  non-object input untouched (the loader's Zod pass will reject it). All-or-nothing:
+ *  the steps run on a deep copy, so `raw` is never mutated and a caller that rejects
+ *  the result (or a step that throws) keeps the original record intact — never a
+ *  half-migrated one. */
 export declare function migrateRaw(kind: EntityKind, raw: unknown, fromVersion: number, migrations?: Migration[], toVersion?: number): unknown;
+/** Whether some migration in (fromVersion, toVersion] may change a record of
+ *  `kind` — i.e. whether re-running migrations could ever fix a failed one. */
+export declare function hasPendingMigration(kind: EntityKind, fromVersion: number, migrations?: Migration[], toVersion?: number): boolean;