@davesheffer/hunch 1.10.5 → 1.10.7

package/dist/cli/index.js

@@ -39,7 +39,7 @@ import { writeTeamConfig, ensureTeamOverlay, readTeamConfig, safeGitUrl, safeTea
 import { runbookId, decisionId } from "../core/ids.js";
 import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
-import { renderText, renderMarkdown, renderImpact, reportFailsStrict } from "../core/checkreport.js";
+import { renderText, renderMarkdown, renderSarif, renderImpact, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, isReviewDraft, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
@@ -70,6 +70,7 @@ import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWiki
 import { adoptProsePrompt } from "../wiki/adopt.js";
 import { topicCollisions, renderGrounding, isInForce } from "../core/topics.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
+import { premiseEscalations } from "../core/premises.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
@@ -3193,7 +3194,7 @@ program
     .option("--commit <sha>", "check a specific commit's files")
     .option("--base <ref>", "check a PR/branch: files changed vs <ref> (e.g. origin/main) — for CI")
     .option("--strict", "exit non-zero ONLY on a direct, high-confidence, non-stale blocking invariant (near/stale/low-confidence stay advisory)")
-    .option("--format <fmt>", "output: text (default) | markdown (a PR comment)", "text")
+    .option("--format <fmt>", "output: text (default) | markdown (a PR comment) | sarif (SARIF 2.1.0 for code scanning)", "text")
     .option("--blast", "also print the dependency blast radius of the changed files")
     .option("--public-only", "exclude the private overlay (HUNCH_PRIVATE_DIR) from the report — use for any output that may be posted publicly (the CI PR comment passes this)")
     .action((opts) => {
@@ -3201,6 +3202,9 @@ program
     if (sources.length > 1)
         return fail(`pick one of --staged / --working / --commit / --base (got ${sources.join(", ")})`);
     const markdown = opts.format === "markdown";
+    // SARIF collects every gate family into ONE JSON document at the end, so all
+    // interleaved section prints are suppressed for this format.
+    const sarif = opts.format === "sarif";
     const emptyReport = { fileCount: 0, strict: !!opts.strict, direct: [], near: [], regressions: [], vetoes: [], redundant: [], strictBlockers: 0, regBlocking: 0, vetoBlocking: 0 };
     const { store, root, teamPullStatus } = storeFor({ requireFreshTeamMemory: !!opts.strict && !opts.publicOnly });
     const teamFreshnessFailure = teamPullStatus !== null
@@ -3246,7 +3250,7 @@ program
         ? sourceGraphSnapshot(root, graphScan.source, graphScan.symbols, graphScan.edges, graphScan.components)
         : undefined;
     const semanticIssues = graphScan?.issues ?? [];
-    if (semanticIssues.length) {
+    if (semanticIssues.length && !sarif) {
         if (markdown) {
             console.log(`\n### ‼ Incomplete semantic source scan — ${semanticIssues.length} file(s) rejected\n`);
             for (const issue of semanticIssues)
@@ -3281,7 +3285,7 @@ program
             publicOnly: !!opts.publicOnly,
         })
         : emptyReport;
-    if (opts.blast && !markdown && files.length) {
+    if (opts.blast && !markdown && !sarif && files.length) {
         console.log(`Blast radius of ${files.length} changed file(s):`);
         for (const f of files) {
             const b = store.blastRadiusFiles(f);
@@ -3290,9 +3294,11 @@ program
         }
         console.log("");
     }
-    console.log(files.length
-        ? (markdown ? renderMarkdown(report) : renderText(report))
-        : (markdown ? renderMarkdown(emptyReport) : "No changed files to check."));
+    if (!sarif) {
+        console.log(files.length
+            ? (markdown ? renderMarkdown(report) : renderText(report))
+            : (markdown ? renderMarkdown(emptyReport) : "No changed files to check."));
+    }
     // ARCHITECTURAL CONFORMANCE: does the RESULTING code still satisfy every recorded
     // architectural invariant? This is graph-reachability, not a diff — so it catches semantic
     // violations a pattern-matcher / SAST can't express (a controller that now reaches the DB
@@ -3305,7 +3311,7 @@ program
             graph: { symbols: graphScan.symbols, edges: graphScan.edges },
         }).filter((c) => !c.satisfied)
         : [];
-    if (confViolations.length) {
+    if (confViolations.length && !sarif) {
         if (markdown) {
             console.log(`\n### ⛔ Architectural conformance — ${confViolations.length} invariant(s) violated\n`);
             for (const c of confViolations) {
@@ -3339,7 +3345,7 @@ program
     const policyResults = hasActivePolicies
         ? constitution.evaluate({ activeOnly: true, publicOnly: !!opts.publicOnly, behavior, snapshot: staticSnapshot })
         : [];
-    if (policyResults.length) {
+    if (policyResults.length && !sarif) {
         if (markdown) {
             console.log(`\n### 📜 Hunch Constitution — ${policyResults.length} policy receipt(s)\n`);
             for (const r of policyResults) {
@@ -3354,6 +3360,24 @@ program
             renderPolicyEvaluations(policyResults).forEach((line) => console.log(line));
         }
     }
+    if (sarif) {
+        const extras = {
+            conformance: confViolations.map((c) => {
+                const dec = store.json.get("decisions", c.decision);
+                return { decision: c.decision, title: c.title, detail: c.detail, ...(dec?.context ? { why: dec.context } : {}), ...(dec?.caused_by_bug ? { bug: dec.caused_by_bug } : {}) };
+            }),
+            policies: policyResults.map((r) => ({
+                id: r.policy.id,
+                result: r.evaluation.result,
+                explanation: r.evaluation.explanation,
+                blocks: r.blocks,
+                receipt: r.evaluation.deterministic_hash,
+                ...(r.gate_error ? { gateError: r.gate_error } : {}),
+            })),
+            scanIssues: semanticIssues.map((s) => ({ path: s.path, detail: s.detail, code: s.code })),
+        };
+        console.log(renderSarif(report, HUNCH_VERSION, extras));
+    }
     const constitutionFails = policyResults.some((r) => r.blocks || r.strict_error);
     if (teamFreshnessFailure)
         console.error(`error: ${teamFreshnessFailure}`);
@@ -3781,7 +3805,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.
@@ -3802,6 +3831,7 @@ program
                 if (pendingReview > 0)
                     L.push(`${pendingReview} legacy un-vouched draft(s) — adopt as advisory memory with \`hunch adopt-drafts\` (new captures auto-trust).`);
                 const escalations = pendingEscalations(decisions);
+                escalations.push(...premiseEscalations(decisions, { now: new Date().toISOString(), exists: (p) => existsSync(join(paths.root, p)) }));
                 try {
                     // Constitution human moments ride the same line; a broken policy store
                     // must never take session-start orientation down (fail open). Public
@@ -3912,7 +3942,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)
@@ -4370,7 +4403,11 @@ program
     .action(async (opts) => {
     const { store, root } = storeFor();
     try {
-        const items = pendingEscalations(store.recs("decisions"));
+        const decisionsForEsc = store.recs("decisions");
+        const items = pendingEscalations(decisionsForEsc);
+        // Premise decay rides the same inline surface: a decision whose recorded
+        // reason died is a QUESTION for the human — authority never changes here.
+        items.push(...premiseEscalations(decisionsForEsc, { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
         // Constitution moments ride the same inline surface (§59.5.3) — never a queue.
         // Fail open: a broken policy store must not take the memory escalations down.
         try {

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/checkreport.js

@@ -211,4 +211,79 @@ export function renderMarkdown(r) {
     out.push(`\n<sub>🧠 Hunch · engineering memory · run \`hunch why <file>\` for the full reasoning.</sub>`);
     return out.join("\n");
 }
+const sarifLoc = (file) => file ? [{ physicalLocation: { artifactLocation: { uri: file.replace(/\\/g, "/") } } }] : undefined;
+/** Render the full check verdict as a SARIF 2.1.0 document. Level mapping is
+ *  severity-truth, independent of the exit code: `error` = would fail --strict
+ *  (strict-blocking invariants, blocking-linked regressions/vetoes, conformance
+ *  violations, authorized policy blocks, incomplete scans), `warning` = blocking
+ *  records the strict gate downgraded plus warning-severity hits, `note` = advisory
+ *  (near, redundant, non-blocking receipts). */
+export function renderSarif(r, version, extras = {}) {
+    const rules = new Map();
+    const results = [];
+    const add = (ruleId, level, text, ruleText, file) => {
+        if (!rules.has(ruleId))
+            rules.set(ruleId, { id: ruleId, shortDescription: { text: clip(ruleText, 300) }, defaultConfiguration: { level } });
+        results.push({ ruleId, level, message: { text }, ...(sarifLoc(file) ? { locations: sarifLoc(file) } : {}) });
+    };
+    for (const c of r.direct) {
+        const level = c.strictBlocks ? "error" : c.severity === "advisory" ? "note" : "warning";
+        let text = `[${c.severity}] ${c.statement}`;
+        if (c.rationale)
+            text += ` — ${c.rationale}`;
+        if (c.downgrade)
+            text += ` (advisory under strict: ${c.downgrade})`;
+        if (c.why?.decision)
+            text += `\nwhy: “${c.why.decision.title}” (${c.why.decision.id})`;
+        if (c.why?.bug)
+            text += `\nguards against: ${c.why.bug.title} (${c.why.bug.id})`;
+        add(c.id, level, text, c.statement, c.files[0]);
+    }
+    for (const n of r.near) {
+        add(n.id, "note", `[${n.severity}] near via blast radius: ${n.statement}${n.via[0] ? `\nvia ${n.via[0]}` : ""}`, n.statement);
+    }
+    for (const h of r.regressions) {
+        add(h.decision, h.blocking ? "error" : "warning", `re-adds ${h.kind} \`${h.name}\` — ${h.decision} deliberately removed it: “${h.title}”. ${h.reason}`, h.title);
+    }
+    for (const v of r.vetoes) {
+        add(v.decision, v.blocking ? "error" : "warning", `reverses rejected approach: you rejected “${clip(v.alternative)}”; you chose “${clip(v.chosen)}” (${v.decision})`, v.title);
+    }
+    for (const x of r.redundant) {
+        add("hunch/redundant-symbol", "note", `adds ${x.kind} \`${x.name}\` — already defined in ${x.existingFile}`, "Possibly re-implements an existing symbol", x.existingFile);
+    }
+    for (const c of extras.conformance ?? []) {
+        let text = `architectural conformance violated: ${c.detail} (“${c.title}”)`;
+        if (c.why)
+            text += `\nwhy: ${c.why}`;
+        if (c.bug)
+            text += `\nprevents recurrence of: ${c.bug}`;
+        add(c.decision, "error", text, c.title);
+    }
+    for (const p of extras.policies ?? []) {
+        const level = p.blocks || p.gateError ? "error" : p.result === "satisfied" ? "note" : "warning";
+        let text = `policy ${p.result}${p.blocks ? " (authorized block)" : ""}: ${p.explanation}\nreceipt: ${p.receipt}`;
+        if (p.gateError)
+            text += `\ngate error: ${p.gateError}`;
+        add(p.id, level, text, `Constitution policy ${p.id}`);
+    }
+    for (const s of extras.scanIssues ?? []) {
+        add("hunch/incomplete-scan", "error", `semantic source scan rejected ${s.path}: ${s.detail} [${s.code}] — an omitted file could hide a violation, so strict fails closed`, "Incomplete semantic source scan", s.path);
+    }
+    const doc = {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [{
+                tool: {
+                    driver: {
+                        name: "hunch",
+                        informationUri: "https://github.com/davesheffer/hunch",
+                        version,
+                        rules: [...rules.values()],
+                    },
+                },
+                results,
+            }],
+    };
+    return JSON.stringify(doc, null, 2);
+}
 //# sourceMappingURL=checkreport.js.map

package/dist/core/drift.js

@@ -16,6 +16,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { toPosixTarget } from "./paths.js";
 import { currentForTopic, isLive } from "./topics.js";
+import { evaluatePremises } from "./premises.js";
 import { parseDocAnchors } from "./docanchors.js";
 import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
 import { computeWikiDrift } from "../wiki/wiki.js";
@@ -28,6 +29,7 @@ export function computeDrift(store, root) {
     // anchor-stale. Keeps the doc≠graph gate's false-positive rate ~zero: a routine
     // narrowing supersession (successor lists fewer files) never flags files still governed.
     const liveFiles = new Set(decisions.filter(isLive).flatMap((d) => (d.related_files ?? []).map(toPosixTarget)));
+    const premiseEnv = { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) };
     for (const d of decisions) {
         // 1. DEAD-REFERENCE — only for in-force decisions; a superseded one referencing
         //    a since-deleted file is legitimate history, not drift.
@@ -76,6 +78,18 @@ export function computeDrift(store, root) {
                 }
             }
         }
+        // 7. PREMISE-STALE (world≠graph) — the decision's recorded REASON no longer
+        //    holds while code and docs may be perfectly in sync. Advisory like every
+        //    kind here, and authority is NEVER changed by a dead premise — the
+        //    escalation surface asks the human (a self-relaxing gate could be
+        //    disarmed by the very actor it guards against).
+        if (isLive(d) && d.premises?.length) {
+            for (const v of evaluatePremises(d, premiseEnv)) {
+                if (!v.holds) {
+                    findings.push({ kind: "premise-stale", id: d.id, detail: `premise "${v.claim}" no longer holds — ${v.reason}. Re-attest, supersede, or retire; authority unchanged until a human decides.` });
+                }
+            }
+        }
     }
     // One markdown pass feeds both prose checks (3 + 5): read each doc once.
     for (const doc of markdownDocs(root)) {

package/dist/core/premises.js

@@ -0,0 +1,72 @@
+import { isLive } from "./topics.js";
+const clip = (s, n = 90) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s);
+/** Repo-relative only — a premise check is not an escape hatch into arbitrary
+ *  local files (same containment rule as private doc references). */
+function validRel(p) {
+    return !!p && !p.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(p) && !p.split(/[\\/]/).includes("..");
+}
+function checkPath(claim, rel, wantExists, env) {
+    if (!validRel(rel)) {
+        return { claim, holds: false, reason: `unevaluable: path must be repo-relative ("${rel}") — fix the premise record` };
+    }
+    const exists = env.exists(rel);
+    if (wantExists) {
+        return exists
+            ? { claim, holds: true, reason: `"${rel}" still exists` }
+            : { claim, holds: false, reason: `"${rel}" no longer exists` };
+    }
+    return exists
+        ? { claim, holds: false, reason: `"${rel}" now exists` }
+        : { claim, holds: true, reason: `"${rel}" still absent` };
+}
+function checkOne(p, env) {
+    if (p.path_absent !== undefined)
+        return checkPath(p.claim, p.path_absent, false, env);
+    if (p.path_exists !== undefined)
+        return checkPath(p.claim, p.path_exists, true, env);
+    if (p.review_by !== undefined) {
+        const due = Date.parse(p.review_by);
+        if (!Number.isFinite(due)) {
+            return { claim: p.claim, holds: false, reason: `unevaluable: review_by is not a date ("${p.review_by}") — fix the premise record` };
+        }
+        if (Date.parse(env.now) > due) {
+            const attested = p.attested ? ` (last attested ${p.attested.slice(0, 10)})` : "";
+            return { claim: p.claim, holds: false, reason: `attestation expired ${p.review_by.slice(0, 10)}${attested} — needs a human re-attest` };
+        }
+        return { claim: p.claim, holds: true, reason: `attested until ${p.review_by.slice(0, 10)}` };
+    }
+    // Claim-only: documents the reason, can never fire. Deliberately allowed —
+    // an honest unwatchable premise beats a fake check.
+    return { claim: p.claim, holds: true, reason: "documented only (no check attached)" };
+}
+/** Evaluate every recorded premise of one decision. Empty when none recorded. */
+export function evaluatePremises(d, env) {
+    return (d.premises ?? []).map((p) => checkOne(p, env));
+}
+/** One inline escalation per LIVE decision with ≥1 dead premise — the question
+ *  a human must answer, framed with its resolution verbs. Rejected alternatives
+ *  are MENTIONED (count only), never re-litigated into agent context: reopening
+ *  a settled rejection is a human call, and consistency alone is a valid reason
+ *  to keep a decision whose original premise died. */
+export function premiseEscalations(decisions, env) {
+    const out = [];
+    for (const d of decisions) {
+        if (!isLive(d) || !d.premises?.length)
+            continue;
+        const dead = evaluatePremises(d, env).filter((v) => !v.holds);
+        if (!dead.length)
+            continue;
+        const rejected = d.alternatives_rejected.length;
+        out.push({
+            kind: "premise-stale",
+            topic: d.topic ?? d.id,
+            decisionIds: [d.id],
+            question: `Decision "${clip(d.title)}" (${d.id}) rests on ${dead.length} premise(s) that no longer hold — is it still right?`,
+            detail: dead.map((v) => `"${clip(v.claim, 80)}" — ${v.reason}`).join("  ·  ")
+                + (rejected ? `  ·  ${rejected} rejected alternative(s) on record — reopening them is your call, and keeping the decision for consistency is a valid answer` : ""),
+            resolution: "re-attest (update the premise's review_by/attested), supersede via /capture, or retire the decision — its authority is UNCHANGED until you decide.",
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=premises.js.map

package/dist/core/topics.js

@@ -59,14 +59,46 @@ 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}`;
+        // Memory supply chain: an agent-recorded decision (no capture interview, no
+        // human countersign) is TESTIMONY. It still grounds — but never with the same
+        // voice as a human-confirmed record, because this block is delivered with
+        // doc-precedence framing ("follow the graph") and would otherwise launder an
+        // unvouched write into the most trusted context the next agent sees.
+        // Token-aware match (mirrors strictgate.isHumanConfirmed; not imported — that
+        // module imports this one).
+        const testimony = d.provenance.source.split("+").includes("agent_recorded")
+            ? " — ⚠ agent-recorded testimony, no human countersign yet (/capture confirms it)"
+            : "";
+        return `• "${d.topic}": ${d.decision || d.title} [${d.id}]${rej}${testimony}`;
     });
+    // 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/core/types.js

@@ -106,6 +106,22 @@ export const ConformancePredicateSchema = z.object({
     object: z.string().optional().describe("required (calls/imports) or forbidden (not-*) target"),
     transitive: z.boolean().default(false).describe("allow an indirect path over the dependency graph"),
 });
+// A premise: the WHY under the decision, as a checkable record. Decisions decay
+// when their REASONS die, not (only) when code changes — a premise makes one
+// recorded reason watchable. Exactly one check per premise (or none: claim-only
+// premises document the reason but can never fire). Checks are deterministic and
+// explicit — path presence or a dated human attestation — never semantic guesses.
+// A failing premise NEVER changes authority; it only raises an inline escalation
+// (the human renews, supersedes, or retires — same ethos as topic anchors).
+export const PremiseSchema = z.object({
+    claim: z.string().min(1).describe("the human-readable reason this decision rests on"),
+    path_absent: z.string().optional().describe("premise holds while this repo-relative path does NOT exist"),
+    path_exists: z.string().optional().describe("premise holds while this repo-relative path exists"),
+    review_by: z.string().optional().describe("dated attestation: premise holds until this ISO date, then needs re-attesting"),
+    attested: z.string().optional().describe("ISO date a human last attested the claim (informational)"),
+}).refine((p) => [p.path_absent, p.path_exists, p.review_by].filter((x) => x !== undefined).length <= 1, {
+    message: "a premise carries at most one check (path_absent | path_exists | review_by)",
+});
 export const DecisionSchema = z.object({
     id: z.string().describe("dec_*"),
     title: z.string(),
@@ -137,6 +153,12 @@ export const DecisionSchema = z.object({
     valid_to: z.string().nullable().default(null).describe("ISO instant it was superseded (null = in force)"),
     retired: RetiredSignalSchema.default({ symbols: [], deps: [] }),
     conformance: z.array(ConformancePredicateSchema).optional().describe("deterministic intent-conformance checks over the graph"),
+    // Optional like `topic`/`conformance`: absent = today's behavior exactly (no
+    // migration, no new burden). Intended to be RARE — blocking constraints and
+    // contested decisions, not every record (attestation fatigue kills reminder
+    // systems). A decision with premises is "conditioned on [these]", never
+    // "verified valid" — the system watches recorded reasons only.
+    premises: z.array(PremiseSchema).optional().describe("the checkable reasons this decision rests on; a dead premise escalates, never auto-relaxes"),
     provenance: ProvenanceSchema,
     date: z.string(),
 });

package/dist/mcp/server.js

@@ -33,6 +33,7 @@ import { HUNCH_VERSION } from "../core/version.js";
 import { assertCompleteRepoScan, indexRepo, scanRepo } from "../extractors/indexer.js";
 import { liveForTopic, historyForTopic, rejectedForTopic, captureConflicts } from "../core/topics.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
+import { premiseEscalations } from "../core/premises.js";
 import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken } from "../core/capturetoken.js";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
@@ -606,7 +607,8 @@ 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"));
+        escalations.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
         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 +623,13 @@ 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), premise-stale decisions (a live decision whose recorded REASON no longer holds — its authority is unchanged until the human re-attests, supersedes, or retires), 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"));
+        // Premise decay: a live decision whose recorded reason died. Question-framed
+        // like every entry here — authority never changes until the human answers.
+        items.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
         try {
             items.push(...policyEscalations(new ConstitutionService(store, root).list({ publicOnly: true }).map((p) => ({ ...p, last_action: p.audit.at(-1)?.action ?? null }))));
         }
@@ -726,6 +731,14 @@ export function buildServerWithRootControl(initialRoot) {
                 related_files: z.array(z.string()).optional(),
                 related_components: z.array(z.string()).optional(),
                 topic: z.string().optional().describe("decision-grounding anchor — one topic per decision; enables doc≠graph drift detection for it. Omit to leave un-anchored."),
+                premises: z.array(z.object({
+                    claim: z.string().describe("the checkable reason this decision rests on, in plain words"),
+                    check: z.object({
+                        kind: z.enum(["path_absent", "path_exists", "review_by"]),
+                        path: z.string().optional().describe("repo-relative path for path_absent / path_exists"),
+                        review_by: z.string().optional().describe("ISO date this attestation expires (review_by)"),
+                    }).optional().describe("at most one deterministic check; omit for an unchecked note"),
+                })).optional().describe("the checkable reasons this decision rests on. A dead premise NEVER changes authority — it raises an escalation for the human. Omit on re-record to keep the incumbent's premises."),
                 status: z.enum(["proposed", "accepted", "rejected", "superseded"]).optional(),
                 commit: z.string().optional(),
                 supersedes: z.string().optional().describe("id of a decision this one replaces — closes its valid-time window (invalidate, don't delete)"),
@@ -758,17 +771,51 @@ export function buildServerWithRootControl(initialRoot) {
             const sameHumanIdentity = existing?.topic && decision.topic
                 ? decision.topic === existing.topic
                 : existing?.title === decision.title;
-            const conflictsWithHuman = !!existing?.provenance.source.includes("human_confirmed")
-                && !sameHumanIdentity;
+            // CURATED slots are overwrite-protected, not just human-confirmed ones:
+            // agent_recorded testimony carries session content a silent replace would
+            // destroy (issue #23's harm, one tier down). Only regenerable machine
+            // drafts (llm_draft/inferred synthesis, deterministically re-derivable
+            // from the commit) stay upgradeable by a different identity. Same-identity
+            // re-record remains the countersign/refine path for every tier.
+            const curated = ["human_confirmed", "agent_recorded"].some((t) => existing?.provenance.source.split("+").includes(t));
+            // AUTHORSHIP STAMP (memory supply chain): only a consumed capture token — proof a
+            // grilling interview preceded this write — mints human_confirmed. Any agent can
+            // CALL this tool mid-session, possibly steered by untrusted content it read;
+            // "the human probably asked me to" is testimony, not a signature.
+            //
+            // Resolved HERE, before the overwrite guard, because the guard's answer depends on
+            // it: testimony must yield to a signature. (Consuming before a possible refusal
+            // burns the token, which is the safe direction — a re-run of /capture mints another.)
+            const gated = consumeCaptureToken(capture_token);
+            const existingTiers = existing?.provenance.source.split("+") ?? [];
+            const existingIsHuman = existingTiers.includes("human_confirmed");
+            // A slot held only by AGENT TESTIMONY must not block a later human capture — the
+            // stamp's own contract says so ("never lock the id slot against a later human
+            // capture"), but including agent_recorded in `curated` did exactly that. A
+            // human_confirmed slot stays protected as before (issue #23): a signature is never
+            // displaced by a differently-identified record, vouched or not.
+            const conflictsWithHuman = curated && !sameHumanIdentity && !(gated && !existingIsHuman);
             if (conflictsWithHuman) {
-                return err(`Decision id ${id} already identifies a different human-confirmed decision: ` +
+                return err(`Decision id ${id} already identifies a different curated decision: ` +
                     `"${existing.title}"${existing.topic ? ` (topic "${existing.topic}")` : ""}. ` +
                     `Refusing to overwrite it with "${decision.title}"${decision.topic ? ` (topic "${decision.topic}")` : ""}. ` +
                     "Record the additional decision without commit, or reuse the incumbent topic/title when refining the same decision.");
             }
+            // Un-token'd writes land as agent_recorded: fully functional advisory memory that
+            // never carries human authority (strict/veto gates key on human_confirmed) and
+            // surfaces with a testimony marker. Re-record through /capture to countersign.
+            //
+            // A signature already on this slot is INHERITED, never erased. The un-token'd path
+            // is exactly what the nudge below tells an agent to do ("re-record… supersedes"),
+            // and the tier expression preserved `llm_draft` while dropping `human_confirmed` —
+            // so an un-vouched agent write silently stripped human authority from a decision a
+            // human had vouched for. That inverts the whole point of the stamp: it exists to
+            // stop an agent CLAIMING human authority, not to let one DESTROY it. Downgrading a
+            // signature is a human act (`hunch review --reject`, or supersede via /capture).
+            const tier = gated || existingIsHuman ? "human_confirmed" : "agent_recorded";
             const source = existing && existing.provenance.source.includes("llm_draft")
-                ? "llm_draft+human_confirmed"
-                : "human_confirmed";
+                ? `llm_draft+${tier}`
+                : tier;
             const now = new Date().toISOString();
             const rec = {
                 id,
@@ -780,6 +827,14 @@ export function buildServerWithRootControl(initialRoot) {
                 consequences: decision.consequences ?? [],
                 alternatives_rejected: decision.alternatives_rejected ?? [],
                 rejected_tripwires: existing?.rejected_tripwires ?? [], // preserve confirmed tripwires across re-record
+                // Premises survive a re-record for the same reason tripwires do. Rebuilding the
+                // record field-by-field WITHOUT them silently deleted the decision's recorded
+                // reasons — so the escalation for a dead premise stopped firing while the
+                // decision kept full authority, and nothing reported the loss. That is the exact
+                // fail-open premise decay exists to prevent, relocated from the evaluator to the
+                // writer — and the escalation's own advice ("re-attest… or re-record") walked
+                // straight into it. Caller-supplied premises win; otherwise the incumbent's carry.
+                premises: decision.premises ?? existing?.premises ?? [],
                 related_components: decision.related_components ?? existing?.related_components ?? [],
                 related_files: (decision.related_files ?? existing?.related_files ?? []).map(toPosixTarget),
                 supersedes: decision.supersedes ?? existing?.supersedes ?? null,
@@ -789,7 +844,7 @@ export function buildServerWithRootControl(initialRoot) {
                 valid_from: existing?.valid_from ?? now,
                 valid_to: existing?.valid_to ?? null,
                 retired: existing?.retired ?? { symbols: [], deps: [] },
-                provenance: { source, confidence: 0.95, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
+                provenance: { source, confidence: gated ? 0.95 : 0.75, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
                 date: now,
             };
             // Where this write will actually land (see captureHome). Resolved BEFORE the
@@ -843,16 +898,17 @@ export function buildServerWithRootControl(initialRoot) {
             // (commit only — it rides the user's next push, never auto-pushing their code branch).
             const flush = flushCapture(store, hunchPaths(root).hunch, !!decision.private, `hunch: capture ${id}`, startupTeamRoute ?? undefined);
             const flushed = flushNote(flush, home, store.mode);
-            // Capture-session gate (staged deprecation, §9.3): a token proves an interview
-            // preceded the write. No token still writes (non-breaking), but returns a nudge
-            // toward /capture so the un-interviewed bypass is visible, not silent. A token
-            // presented but unknown to THIS process (server restart/expiry) is not shamed.
-            const gated = consumeCaptureToken(capture_token);
+            // Capture-session gate (staged deprecation, §9.3): the token was consumed
+            // above (it also decides the provenance tier). No token still writes
+            // (non-breaking) but lands as agent_recorded with a nudge toward /capture.
+            // A token presented but unknown to THIS process (server restart/expiry) is
+            // not shamed — but it also cannot be VERIFIED, so the record still lands
+            // agent_recorded with a note saying how to countersign.
             const captureNote = gated
                 ? " [via capture front door]"
                 : capture_token
-                    ? ""
-                    : `\n\n⚠ Recorded WITHOUT a capture interview — the record stands, but harden it NOW in one exchange instead of switching flows: answer the first grilling question directly — "What alternative did you seriously consider and reject for '${rec.title.slice(0, 60)}', and what breaks if a future session re-introduces it?" — then fold the answer into alternatives_rejected via hunch_record_decision(supersedes: ${id}) or start the full interview with hunch_capture_decision. (A future major version will require a capture token here.)`;
+                    ? `\n\nℹ The capture token could not be verified (server restart or expiry), so this record is stamped agent_recorded. Re-record through hunch_capture_decision → hunch_record_decision to countersign it as human_confirmed.`
+                    : `\n\n⚠ Recorded WITHOUT a capture interview — the record stands as agent_recorded TESTIMONY (advisory: it never carries human authority; a /capture interview on the same topic/title countersigns it). Harden it NOW in one exchange instead of switching flows: answer the first grilling question directly — "What alternative did you seriously consider and reject for '${rec.title.slice(0, 60)}', and what breaks if a future session re-introduces it?" — then fold the answer into alternatives_rejected via a /capture interview (hunch_capture_decision → hunch_record_decision(supersedes: ${id})), which countersigns the record as human_confirmed. (A future major version will require a capture token here.)`;
             // Quality nudge only when the untokened deprecation nudge isn't already
             // grilling — one advisory voice per response, never two.
             const quality = gated || capture_token ? qualityNudge(rec) : "";

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/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.10.5",
+  "version": "1.10.7",
+  "mcpName": "io.github.davesheffer/hunch",
   "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.",
@@ -18,6 +19,7 @@
   },
   "files": [
     "dist/**/*.js",
+    "server.json",
     "bench/constitution-exp03-v1.json",
     "tooling/competitive-watch.mjs",
     "tooling/md1-benchmark.mjs",

package/server.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "io.github.davesheffer/hunch",
+  "description": "Engineering memory for AI-assisted codebases: decisions, rejected alternatives, bug lineage, and deterministic architectural gates, served git-natively over MCP.",
+  "repository": {
+    "url": "https://github.com/davesheffer/hunch",
+    "source": "github"
+  },
+  "websiteUrl": "https://hunch-pi.vercel.app",
+  "version": "1.10.7",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@davesheffer/hunch",
+      "version": "1.10.7",
+      "runtimeHint": "npx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "mcp",
+          "description": "Start the Hunch MCP server (stdio) for the current repository."
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/tooling/competitive-watch.mjs

@@ -18,16 +18,29 @@ const distinctivePhrases = [
   "deterministic Change Gate for AI-assisted codebases",
 ];
 
-const token = process.env.GITHUB_TOKEN?.trim();
-const headers = {
-  Accept: "application/vnd.github+json",
-  "User-Agent": "hunch-competitive-watch",
-  "X-GitHub-Api-Version": "2022-11-28",
-  ...(token ? { Authorization: `Bearer ${token}` } : {}),
-};
+let token = process.env.GITHUB_TOKEN?.trim();
+// A rejected token must DEGRADE the run, never kill it: ambient CI/proxy tokens
+// are often invalid for api.github.com, and the metadata half of this watch
+// works unauthenticated. Flipped on the first 401 so every later call skips
+// the bad credential instead of failing eight times.
+let tokenRejected = false;
+
+function headers() {
+  return {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "hunch-competitive-watch",
+    "X-GitHub-Api-Version": "2022-11-28",
+    ...(token && !tokenRejected ? { Authorization: `Bearer ${token}` } : {}),
+  };
+}
 
 async function github(path) {
-  const response = await fetch(`https://api.github.com${path}`, { headers });
+  let response = await fetch(`https://api.github.com${path}`, { headers: headers() });
+  if (response.status === 401 && token && !tokenRejected) {
+    tokenRejected = true;
+    process.stderr.write("competitive-watch: GITHUB_TOKEN rejected (401) — continuing unauthenticated; phrase search will be skipped.\n");
+    response = await fetch(`https://api.github.com${path}`, { headers: headers() });
+  }
   if (!response.ok) {
     const detail = (await response.text()).slice(0, 300).replaceAll("\n", " ");
     throw new Error(`GitHub ${response.status} for ${path}: ${detail}`);
@@ -36,20 +49,26 @@ async function github(path) {
 }
 
 async function repoSnapshot(repo) {
-  const data = await github(`/repos/${repo}`);
-  return {
-    repo,
-    created: data.created_at,
-    pushed: data.pushed_at,
-    stars: data.stargazers_count,
-    forks: data.forks_count,
-    issues: data.open_issues_count,
-    url: data.html_url,
-  };
+  // One vanished/renamed repo is itself a signal worth a row — never a reason
+  // to lose the other seven.
+  try {
+    const data = await github(`/repos/${repo}`);
+    return {
+      repo,
+      created: data.created_at,
+      pushed: data.pushed_at,
+      stars: data.stargazers_count,
+      forks: data.forks_count,
+      issues: data.open_issues_count,
+      url: data.html_url,
+    };
+  } catch (error) {
+    return { repo, error: error instanceof Error ? error.message : String(error) };
+  }
 }
 
 async function phraseSnapshot(phrase) {
-  const query = encodeURIComponent(`\"${phrase}\"`);
+  const query = encodeURIComponent(`"${phrase}"`);
   const data = await github(`/search/code?q=${query}&per_page=100`);
   const external = data.items
     .filter((item) => !item.repository.full_name.startsWith("davesheffer/"))
@@ -72,14 +91,25 @@ function render(snapshot, phrases) {
   ];
 
   for (const item of snapshot) {
+    if (item.error) {
+      lines.push(`| ${item.repo} | — | — | — | — | — |`);
+      continue;
+    }
     lines.push(
       `| [${item.repo}](${item.url}) | ${item.created.slice(0, 10)} | ${item.pushed.slice(0, 10)} | ${item.stars} | ${item.forks} | ${item.issues} |`,
     );
   }
+  const failed = snapshot.filter((item) => item.error);
+  if (failed.length) {
+    lines.push("");
+    for (const item of failed) lines.push(`- ⚠ ${item.repo}: ${item.error}`);
+  }
 
   lines.push("", "## Distinctive phrase search", "");
   if (!token) {
     lines.push("Skipped: set `GITHUB_TOKEN` to enable authenticated GitHub code search.");
+  } else if (tokenRejected) {
+    lines.push("Skipped: `GITHUB_TOKEN` was rejected by api.github.com (401) — repo metadata above was collected unauthenticated. Provide a valid token (e.g. `GITHUB_TOKEN=\"$(gh auth token)\"`) to run the phrase-copy check.");
   } else {
     for (const result of phrases) {
       lines.push(`- **${result.phrase}** — ${result.external.length} external indexed match(es)`);
@@ -97,8 +127,11 @@ function render(snapshot, phrases) {
 }
 
 try {
-  const snapshot = await Promise.all(repos.map(repoSnapshot));
-  const phrases = token
+  const snapshot = [];
+  // Sequential on purpose: the first call settles token validity before the
+  // rest, and unauthenticated rate limits are too small to burst against.
+  for (const repo of repos) snapshot.push(await repoSnapshot(repo));
+  const phrases = token && !tokenRejected
     ? await Promise.all(distinctivePhrases.map(phraseSnapshot))
     : [];
   process.stdout.write(render(snapshot, phrases));