@davesheffer/hunch 1.10.4 → 1.10.6

package/dist/cli/index.js

@@ -3781,7 +3781,12 @@ program
             // travel further than a terminal. Union view: `hunch now --private`.
             const s = new HunchStore(paths);
             try {
-                const decisions = s.json.loadAll("decisions");
+                // Mode-aware: in unified ("shared") mode the public `.hunch/` is only a routing
+                // shell, so loading it alone makes session-start orientation — recent work,
+                // roadmap, escalations — report an empty graph for a repo whose memory is all
+                // in the overlay. Private mode stays public-only: session transcripts travel
+                // further than a terminal.
+                const decisions = s.advisoryRecs("decisions");
                 const { recent, roadmap, pendingReview } = nowData(decisions, 3);
                 if (!decisions.length) {
                     // Fresh graph: nothing to orient on, but the operating loop still ships.
@@ -3912,7 +3917,10 @@ program
         }
         // Decision-grounding (§3): for topic-anchored decisions governing this file, state
         // the current decision assertively (graph over any stale doc) + what it rejected.
-        const grounding = renderGrounding(ctx.decisions);
+        // The FULL decision set is passed alongside the file slice so a topic contested
+        // somewhere else in the graph is reported as unresolved instead of being asserted
+        // as settled — the collision's two sides often live in different files.
+        const grounding = renderGrounding(ctx.decisions, store.recs("decisions"));
         if (grounding)
             text += `\n\n${grounding}`;
         if (docGround)

package/dist/constitution/g2BehaviorCandidates.js

@@ -567,22 +567,27 @@ function runLeg(root, session, hooks, env, candidate, commit, expected, source,
         const testFile = join(checkout, candidate.test.file);
         mkdirSync(dirname(testFile), { recursive: true });
         writeFileSync(testFile, source);
-        const exactEvidence = candidate.grounding === "human_decision_plus_added_test";
+        // ONE scoring mode, always reporter-based. The exit code of a `node --test` run is a
+        // property of the whole FILE, not of the selected test: a failure in an unrelated
+        // sibling flips it, so a proxy-grounded candidate could record behavior_confirmed (or
+        // its negation) from evidence that has nothing to do with the candidate. The reporter
+        // path already existed and is the unconditional standard in every other evidence
+        // surface here (behaviorEvaluator, g2Drills, g3Conformance) — this was the one holdout.
+        //
+        // The pattern is also derived from the candidate rather than trusting runner.argv:
+        // argv could carry a pattern selecting a DIFFERENT test than the one being attested,
+        // and an un-escaped raw name is a regex that can match siblings.
         const reporter = join(run, "reporter.mjs");
-        const patternArg = candidate.runner.argv.find((arg) => arg.startsWith("--test-name-pattern="))
-            ?? `--test-name-pattern=${candidate.test.name}`;
-        if (exactEvidence)
-            writeFileSync(reporter, NODE_TEST_REPORTER_SOURCE);
-        const testArgs = exactEvidence
-            ? [
-                "--test",
-                nodeTestIsolationFlag(),
-                patternArg,
-                `--test-reporter=${pathToFileURL(reporter).href}`,
-                "--test-reporter-destination=stdout",
-                candidate.test.file,
-            ]
-            : ["--test", patternArg, candidate.test.file];
+        const patternArg = `--test-name-pattern=${exactNodeTestPattern(candidate.test.name)}`;
+        writeFileSync(reporter, NODE_TEST_REPORTER_SOURCE);
+        const testArgs = [
+            "--test",
+            nodeTestIsolationFlag(),
+            patternArg,
+            `--test-reporter=${pathToFileURL(reporter).href}`,
+            "--test-reporter-destination=stdout",
+            candidate.test.file,
+        ];
         let args;
         if (candidate.runner.kind === "node-test") {
             args = testArgs;
@@ -614,36 +619,22 @@ function runLeg(root, session, hooks, env, candidate, commit, expected, source,
             else {
                 const exitCode = result.status ?? null;
                 const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
-                if (exactEvidence) {
-                    const matches = nodeTestReporterEvents(result.stdout ?? "")
-                        .filter((event) => event.name === candidate.test.name && !event.skip && !event.todo);
-                    if (matches.length === 0) {
-                        leg = errorLeg(commit, expected, nodeTestInfrastructureError(output) ?? "selected-test-not-executed", dependencySnapshotId);
-                    }
-                    else if (matches.length > 1) {
-                        leg = errorLeg(commit, expected, "selected-test-ambiguous", dependencySnapshotId);
-                    }
-                    else if (matches[0].type === "test:pass" && exitCode === 0) {
-                        leg = { commit, expected, result: "passed", exit_code: exitCode, ...(dependencySnapshotId ? { dependency_snapshot_id: dependencySnapshotId } : {}) };
-                    }
-                    else if (matches[0].type === "test:fail" && exitCode !== 0) {
-                        leg = { commit, expected, result: "failed", exit_code: exitCode, ...(dependencySnapshotId ? { dependency_snapshot_id: dependencySnapshotId } : {}) };
-                    }
-                    else {
-                        leg = errorLeg(commit, expected, "runner-outcome-inconsistent", dependencySnapshotId);
-                    }
+                const matches = nodeTestReporterEvents(result.stdout ?? "")
+                    .filter((event) => event.name === candidate.test.name && !event.skip && !event.todo);
+                if (matches.length === 0) {
+                    leg = errorLeg(commit, expected, nodeTestInfrastructureError(output) ?? "selected-test-not-executed", dependencySnapshotId);
+                }
+                else if (matches.length > 1) {
+                    leg = errorLeg(commit, expected, "selected-test-ambiguous", dependencySnapshotId);
+                }
+                else if (matches[0].type === "test:pass") {
+                    leg = { commit, expected, result: "passed", exit_code: exitCode, ...(dependencySnapshotId ? { dependency_snapshot_id: dependencySnapshotId } : {}) };
+                }
+                else if (matches[0].type === "test:fail") {
+                    leg = { commit, expected, result: "failed", exit_code: exitCode, ...(dependencySnapshotId ? { dependency_snapshot_id: dependencySnapshotId } : {}) };
                 }
                 else {
-                    const infrastructureError = exitCode === 0 ? null : nodeTestInfrastructureError(output);
-                    leg = infrastructureError
-                        ? errorLeg(commit, expected, infrastructureError, dependencySnapshotId)
-                        : {
-                            commit,
-                            expected,
-                            result: exitCode === 0 ? "passed" : "failed",
-                            exit_code: exitCode,
-                            ...(dependencySnapshotId ? { dependency_snapshot_id: dependencySnapshotId } : {}),
-                        };
+                    leg = errorLeg(commit, expected, "runner-outcome-inconsistent", dependencySnapshotId);
                 }
             }
         }

package/dist/constitution/service.js

@@ -97,6 +97,19 @@ export function shadowCommitEligible(root, policy, commit) {
         return false;
     throw new Error(`cannot compare shadow commit ${commit} with policy introduction ${sourceCommit}: ${(check.stderr ?? "").trim() || `git exited ${check.status}`}`);
 }
+/** The commit a shadow receipt's ancestry check must be anchored to.
+ *
+ *  A WORKSPACE receipt retains a content-addressed PSEUDO-head for dedupe — it is not a
+ *  real git rev. Handing it to `git merge-base --is-ancestor` makes git exit with
+ *  neither 0 nor 1, which shadowCommitEligible turns into a THROW, so the surface
+ *  hard-fails instead of reporting. Ancestry is always the real base commit.
+ *
+ *  Shared because that rule was previously written out at one call site (with this
+ *  explanation attached) and silently omitted at another — the same one-side-only drift
+ *  as OVERLAY_IGNORE. One definition, both callers. */
+export function shadowAncestryCommit(record) {
+    return record.evaluation.repository.base ?? record.evaluation.repository.head;
+}
 export class ConstitutionService {
     store;
     root;
@@ -859,7 +872,7 @@ export class ConstitutionService {
             const proof = proofs.find((candidate) => candidate.id === record.proof_id);
             if (!proof || proof.policy_hash !== record.policy_hash)
                 return false;
-            if (!shadowCommitEligible(this.root, policy, record.evaluation.repository.head))
+            if (!shadowCommitEligible(this.root, policy, shadowAncestryCommit(record)))
                 return false;
             const composition = compositionDescendants(policy, policies);
             return proof.policy_hash === policyProofHash(policy, composition);
@@ -1099,10 +1112,7 @@ export class ConstitutionService {
         const audit = this.repository.listShadowDispositions(opts).filter((record) => record.policy_id === id);
         const current = currentShadowDispositions(audit);
         const history = this.repository.listDispositions(opts).filter((record) => record.policy_id === id && record.proof_id === proof.id);
-        const scoringRecords = records.filter((record) => shadowCommitEligible(this.root, policy, 
-        // Workspace receipts retain their content-addressed pseudo-head for
-        // dedupe, but ancestry eligibility is anchored to the real base commit.
-        record.evaluation.repository.base ?? record.evaluation.repository.head));
+        const scoringRecords = records.filter((record) => shadowCommitEligible(this.root, policy, shadowAncestryCommit(record)));
         const report = scoreShadowPrecision(policy, proof, scoringRecords, audit, history, thresholds);
         return {
             ...report,

package/dist/core/topics.js

@@ -59,14 +59,36 @@ export function captureConflicts(decisions, topic, selfId, willCloseId) {
  *  assembleContext, so no freshness re-check is needed here — a superseded-only-anchored
  *  file is caught by the anchor-stale drift check, and the commit-time staleness gate
  *  applies the age-downgrade. Returns "" when no anchored decision governs the file. */
-export function renderGrounding(fileDecisions) {
+export function renderGrounding(fileDecisions, allDecisions = fileDecisions) {
+    // A CONTESTED topic must never be stated as authority. This is the same fail-safe
+    // currentForTopic applies (`live.length === 1 ? live[0] : null`) and renderDocGrounding
+    // already honours — this reader was the one that bypassed it, filtering per-decision
+    // instead of per-topic. Two live decisions on one topic each got their own assertive
+    // bullet, and because each bullet lists what it REJECTED, the agent was told, in the
+    // last context before it writes, that both answers are correct and each is forbidden.
+    //
+    // `allDecisions` is the FULL set, not the file slice, on purpose: the colliding pair
+    // can name different files, so a file-scoped check would see one decision, call it
+    // uncontested, and assert it as THE answer while the topic is globally disputed.
+    const contested = topicCollisions(allDecisions);
     const anchored = fileDecisions.filter((d) => d.topic && isLive(d));
     if (!anchored.length)
         return "";
-    const lines = anchored.map((d) => {
+    const settled = anchored.filter((d) => !contested.has(d.topic));
+    const disputed = [...new Set(anchored.filter((d) => contested.has(d.topic)).map((d) => d.topic))].sort();
+    const lines = settled.map((d) => {
         const rej = d.alternatives_rejected.length ? ` (rejected: ${d.alternatives_rejected.join("; ")})` : "";
         return `• "${d.topic}": ${d.decision || d.title} [${d.id}]${rej}`;
     });
+    // Name the conflict instead of silently dropping it: an unexplained absence would read
+    // as "nothing is recorded here", which is how a contested topic gets re-decided by
+    // accident. This is a question for the human, never an answer for the agent.
+    for (const topic of disputed) {
+        const ids = contested.get(topic).map((d) => d.id).join(", ");
+        lines.push(`• "${topic}": ⚠ UNRESOLVED — ${contested.get(topic).length} live decisions (${ids}). No current answer; ask the human before choosing. Resolve with \`hunch reconcile-topics\` (supersede one, or split the topic).`);
+    }
+    if (!lines.length)
+        return "";
     return `🧭 Hunch grounding — this file is anchored to recorded decisions; follow the graph, not a stale doc:\n${lines.join("\n")}`;
 }
 /** Every topic with MORE THAN ONE live decision — the invariant violations a post-merge

package/dist/mcp/server.js

@@ -606,7 +606,7 @@ export function buildServerWithRootControl(initialRoot) {
             L.push(`  • ${r.title} (${r.id}${r.topic ? `, ${r.topic}` : ""}, since ${r.date})\n      ${r.note}`);
         if (pendingReview > 0)
             L.push("", `${pendingReview} legacy un-vouched draft(s) — \`hunch adopt-drafts\` auto-trusts them as advisory (new captures land trusted automatically).`);
-        const escalations = pendingEscalations(store.json.loadAll("decisions"));
+        const escalations = pendingEscalations(store.advisoryRecs("decisions"));
         if (escalations.length) {
             L.push("", `⚖ ${escalations.length} decision(s) need the human's call — ASK inline (never queue): ${escalations.map((e) => e.question).join(" · ")}`);
         }
@@ -621,10 +621,10 @@ export function buildServerWithRootControl(initialRoot) {
     // (con_e04226bd05): no Claude-specific behavior.
     server.registerTool("hunch_escalations", {
         title: "Decisions the human must make now (ask inline, not a queue)",
-        description: "The rare decisions the graph cannot resolve on its own — surfaced so you ASK THE USER in the prompt at the moment, then act. Auto-captured memory is trusted automatically and never appears here; this returns topic conflicts (>1 live decision for one topic) and Constitution human moments (candidate policies awaiting review, proposed policies awaiting an activation decision). Normally empty. Raise each question with the user; do NOT decide it for them — an entry is a question, never an approval. Public store only.",
+        description: "The rare decisions the graph cannot resolve on its own — surfaced so you ASK THE USER in the prompt at the moment, then act. Auto-captured memory is trusted automatically and never appears here; this returns topic conflicts (>1 live decision for one topic) and Constitution human moments (candidate policies awaiting review, proposed policies awaiting an activation decision). Normally empty. Raise each question with the user; do NOT decide it for them — an entry is a question, never an approval. Reads the public store, or the unified overlay when the repo is in shared mode (where the overlay IS the store) — never private-mode overlay records.",
         inputSchema: {},
     }, async () => {
-        const items = pendingEscalations(store.json.loadAll("decisions"));
+        const items = pendingEscalations(store.advisoryRecs("decisions"));
         try {
             items.push(...policyEscalations(new ConstitutionService(store, root).list({ publicOnly: true }).map((p) => ({ ...p, last_action: p.audit.at(-1)?.action ?? null }))));
         }

package/dist/store/db.js

@@ -59,22 +59,60 @@ function createDb(sqlitePath) {
     db.exec("PRAGMA busy_timeout = 5000");
     return db;
 }
+/** Does this error mean the derived index FILE itself is unusable?
+ *
+ *  Matched narrowly, on SQLite's own corruption signatures only. An environment failure —
+ *  a permission denial, a full disk, a locked file — must still propagate: deleting the
+ *  file would not fix it and would destroy a cache the user may still be able to keep.
+ *  `SQLITE_CANTOPEN` ("unable to open database file") is deliberately NOT here for that
+ *  reason: it usually means a permissions or path problem, not corruption. */
+function isCorruptIndexFile(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /database disk image is malformed|file is not a database|file is encrypted or is not a database|malformed database schema|database corruption/i.test(message);
+}
+function discardDerivedIndex(sqlitePath) {
+    for (const path of [sqlitePath, `${sqlitePath}-wal`, `${sqlitePath}-shm`])
+        rmSync(path, { force: true });
+}
 export function openDb(sqlitePath) {
     mkdirSync(dirname(sqlitePath), { recursive: true });
-    let db = createDb(sqlitePath);
+    // A corrupt file can fail at OPEN as well as at schema init (node:sqlite opens lazily,
+    // so "file is not a database" typically surfaces on the first statement — but not always).
+    let db;
+    try {
+        db = createDb(sqlitePath);
+    }
+    catch (error) {
+        if (!isCorruptIndexFile(error))
+            throw error;
+        discardDerivedIndex(sqlitePath);
+        db = createDb(sqlitePath);
+    }
     try {
         initializeSchema(db);
         return db;
     }
     catch (error) {
-        if (!(error instanceof RebuildDerivedIndex)) {
+        // The ENTIRE database is derived from the Git-native JSON in .hunch/ — it is a cache,
+        // and a cache that cannot be read should be rebuilt, not fatal. That reasoning was
+        // already written here, but it was wired to exactly ONE trigger: RebuildDerivedIndex,
+        // thrown only when an fts5 index meets a runtime without the FTS5 module. Every other
+        // error propagated as a raw SQLite string, so a corrupt file took out `hunch index`,
+        // `query`, `check` and `doctor` at once — and, because the pre-edit hook must emit
+        // nothing and exit 0 on any failure (con_03a0b94b2e), it also went SILENTLY blind,
+        // permanently, with no command left that could repair it.
+        if (!(error instanceof RebuildDerivedIndex) && !isCorruptIndexFile(error)) {
             db.close();
             throw error;
         }
-        db.close();
-        for (const path of [sqlitePath, `${sqlitePath}-wal`, `${sqlitePath}-shm`])
-            rmSync(path, { force: true });
+        try {
+            db.close();
+        }
+        catch { /* a corrupt handle may refuse to close; the file goes anyway */ }
+        discardDerivedIndex(sqlitePath);
         db = createDb(sqlitePath);
+        // Deliberately NOT wrapped in another rebuild attempt: if a freshly created file also
+        // fails, the problem is the environment, not the cache, and it must surface.
         initializeSchema(db);
         return db;
     }

package/dist/store/hunchStore.js

@@ -226,6 +226,21 @@ export class HunchStore {
             byId.set(r.id, r);
         return [...byId.values()];
     }
+    /** Records for an AGENT-FACING advisory surface (escalations, orientation).
+     *
+     *  In unified ("shared") mode the overlay IS the one store — the public `.hunch/` is
+     *  only a routing shell — so reading the public home alone returns NOTHING and the
+     *  surface reports "all clear" for a store whose every record is elsewhere. That is
+     *  the worst possible answer for escalations, whose entire job is to raise the
+     *  questions only a human can settle: a real topic collision came back as an empty
+     *  list and the agent was affirmatively told there was nothing to escalate.
+     *
+     *  In "private" mode the split is a real privacy boundary, so this stays public-only:
+     *  private records must not surface on a public advisory surface. Mode-aware, not a
+     *  blanket union — the distinction is the point. */
+    advisoryRecs(kind) {
+        return this.unified ? this.recs(kind) : this.json.loadAll(kind);
+    }
     /** Records from exactly one storage home (no public/private union). Capture
      * paths use this for identity/lineage checks so a private record can never
      * inherit or disclose relationships from an identically-shaped public record. */
@@ -389,21 +404,37 @@ export class HunchStore {
     }
     /** Portable bounded fallback over titles/bodies. Each natural-language token
      * is an OR candidate, mirroring the high-recall FTS query closely enough for
-     * runtimes whose SQLite build omits the optional FTS5 module. */
+     * runtimes whose SQLite build omits the optional FTS5 module.
+     *
+     * `_` is BOTH a LIKE single-character wildcard and the dominant character in this
+     * codebase's identifiers (dec_/con_/bug_ ids, snake_case symbols). The old code
+     * STRIPPED it, so a search for `hunch_record_decision` looked for the literal
+     * `hunchrecorddecision` and matched nothing — on precisely the runtimes with no FTS5,
+     * where this fallback is the only search there is. Escaping keeps the term literal;
+     * leaving `_` unescaped would silently over-match instead. */
     likeSearch(query, limit, kind) {
         const terms = (query.toLowerCase().match(/[\p{L}\p{N}_]+/gu)
-            ?? [query.toLowerCase().replace(/[%_]/g, "").trim()].filter(Boolean)).slice(0, 32);
+            ?? [query.toLowerCase().trim()].filter(Boolean)).slice(0, 32);
         if (!terms.length)
             return [];
-        const predicates = terms.map(() => `(lower(title) LIKE ? OR lower(body) LIKE ?)`).join(" OR ");
+        const predicates = terms.map(() => `(lower(title) LIKE ? ESCAPE '\\' OR lower(body) LIKE ? ESCAPE '\\')`).join(" OR ");
         const likes = terms.flatMap((term) => {
-            const like = `%${term.replace(/[%_]/g, "")}%`;
+            const like = `%${term.replace(/[\\%_]/g, "\\$&")}%`;
             return [like, like];
         });
         const where = kind ? `kind = ? AND (${predicates})` : `(${predicates})`;
         const params = kind ? [kind, ...likes, limit] : [...likes, limit];
+        // Ordered so a TRUNCATING limit drops the least relevant row rather than an
+        // arbitrary one: a title hit outranks a body-only hit, then shortest title
+        // (a constraint's one-line statement beats a long decision body that merely
+        // mentions the term), then id for determinism. Without this, `LIMIT` returned
+        // rowid order and could drop the constraint a caller was checking for.
+        const titleLikes = terms.map(() => `lower(title) LIKE ? ESCAPE '\\'`).join(" OR ");
+        const titleParams = terms.map((term) => `%${term.replace(/[\\%_]/g, "\\$&")}%`);
         const rows = this.db.prepare(`SELECT ref, kind, title, substr(body,1,120) AS snip FROM search
-       WHERE ${where} LIMIT ?`).all(...params);
+       WHERE ${where}
+       ORDER BY CASE WHEN ${titleLikes} THEN 0 ELSE 1 END, length(title), ref
+       LIMIT ?`).all(...(kind ? [kind, ...likes, ...titleParams, limit] : [...likes, ...titleParams, limit]));
         return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: 0 }));
     }
     // ---- semantic search (opt-in embeddings) --------------------------------

package/dist/store/merge.js

@@ -95,9 +95,49 @@ export function pickWinner(ours, theirs) {
     const tr = recency(theirs);
     if (orr !== tr)
         return orr > tr ? ours : theirs;
+    // A merge must never silently UNDO recorded progress. Closing a bug does not touch
+    // `provenance` or `date` — captureTestRun writes
+    // `{ ...bug, status: "fixed", lineage: { ...lineage, fixed_commit: sha } }` — so
+    // recency() TIES against the still-open side and control always reached the
+    // lexicographic tiebreak below. That tiebreak then picked the LESS-resolved record,
+    // twice over: `"fixed_commit":null` sorts above `"fixed_commit":"<sha>"` (n > "), and
+    // `"status":"open"` sorts above `"status":"fixed"` (o > f). So a clean merge reverted
+    // the closure every time, in the subsystem whose entire job is not losing state.
+    //
+    // Prefer the side carrying more one-way lifecycle evidence. Deterministic and
+    // side-independent (a pure function of each record), so A-merges-B and B-merges-A
+    // still agree.
+    const oe = closureEvidence(ours);
+    const te = closureEvidence(theirs);
+    if (oe !== te)
+        return oe > te ? ours : theirs;
     // Deterministic, side-independent tiebreak so A-merges-B and B-merges-A agree.
     return canon(ours) >= canon(theirs) ? ours : theirs;
 }
+/** Count the one-way lifecycle facts a record carries: a fix commit, a spawned
+ *  decision/constraint, a supersession, an end of validity. Each is something that
+ *  HAPPENED and was recorded — never something a merge should quietly discard.
+ *
+ *  Deliberately counts EVIDENCE fields rather than reading `status`: a status string can
+ *  be moved in either direction (a reopened bug goes fixed -> open), but a recorded
+ *  `fixed_commit` is a fact about history. Ranking on evidence means a genuine reopen —
+ *  which clears the commit — is still allowed to win, while a merge can no longer drop a
+ *  closure that nobody reopened. */
+function closureEvidence(r) {
+    let n = 0;
+    const lineage = r.lineage;
+    if (isRec(lineage)) {
+        for (const key of ["fixed_commit", "spawned_decision", "spawned_constraint"]) {
+            if (typeof lineage[key] === "string" && lineage[key].length > 0)
+                n += 1;
+        }
+    }
+    for (const key of ["superseded_by", "valid_to"]) {
+        if (typeof r[key] === "string" && r[key].length > 0)
+            n += 1;
+    }
+    return n;
+}
 function parseSide(text) {
     const trimmed = (text ?? "").trim();
     if (!trimmed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.10.4",
+  "version": "1.10.6",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Engineering memory and a deterministic Change Gate for AI-assisted codebases: decisions, rejected approaches, constraints, and bug lineage become portable context and opt-in enforcement for every MCP assistant.",