@davesheffer/hunch 1.10.7 → 1.11.0

package/dist/cli/index.js

@@ -4939,6 +4939,17 @@ program
                 console.log(`· ${f.id} — ${f.detail}`);
             console.log(`\nHeal: run \`hunch wiki --heal\` — regenerates only the stale pages (the wiki is a derived view; never edit it by hand).\n`);
         }
+        // Every drift kind heals here — see bug_drift_heal_asymmetry above. premise-stale
+        // shipped in the drift report without a section here, so a repo whose ONLY drift
+        // was a dead premise got "N findings" from `hunch drift` and a bare closing line
+        // from `hunch heal` — exactly the broken loop that bug is about.
+        const premiseStale = kind("premise-stale");
+        if (premiseStale.length) {
+            console.log(`${premiseStale.length} decision(s) rest on a premise that no longer holds (world≠graph):\n`);
+            for (const f of premiseStale)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: this is a HUMAN call — the decision's authority is unchanged until you make it. Re-attest (update the premise's review_by/attested), supersede via /capture, or retire the decision. Keeping it for consistency is a valid answer.\n`);
+        }
         console.log(`Hunch never rewrites prose for you; this is a read-only reconciliation report.`);
     }
     finally {

package/dist/core/correction.js

@@ -88,6 +88,19 @@ export function buildCorrectionConstraint(input, now) {
     let severity = input.severity ?? "warning";
     if (severity === "blocking" && repoWide && !input.applies_to_all)
         severity = "warning";
+    // AUTHORSHIP TIER. This function hardcoded provenance human_confirmed @1, and
+    // isStrictBlocker treats human_confirmed + blocking as a DENY — so an un-interviewed
+    // agent call could mint a repo-wide deny carrying a signature nobody gave. That made
+    // the highest-authority write path the least gated one, and strictly worse than
+    // hunch_record_decision, which only ever produced advisory memory and is now tiered.
+    //
+    // The token sets the TIER, never whether the write lands. An un-vouched correction is
+    // still recorded immediately and still held against every assistant at edit time and
+    // in CI — Never Twice keeps its promise. What waits for a countersign is only the
+    // authority to DENY.
+    const vouched = input.vouched !== false;
+    if (!vouched && severity === "blocking")
+        severity = "warning";
     return {
         id: constraintId(rule),
         type: input.type ?? "correctness",
@@ -101,13 +114,21 @@ export function buildCorrectionConstraint(input, now) {
         // rule that goes stale. Validated against the repo's real deps when supplied → never mints a
         // never-firing rule for a non-dependency. null when nothing derivable → falls back to scope.
         forbids: deriveForbids(rule, input.knownDeps),
-        rationale: input.rationale ?? "Captured from a human correction of the agent (Never Twice).",
+        rationale: input.rationale ?? (vouched
+            ? "Captured from a human correction of the agent (Never Twice)."
+            : "Recorded by the agent as a correction, WITHOUT a capture interview — advisory testimony until a human countersigns it via /capture (Never Twice)."),
         source_decision: input.source_decision ?? null,
         violations: [],
         status: "active",
         valid_from: now,
         valid_to: null,
-        provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: now },
+        // The signature is EARNED, not assumed. isStrictBlocker treats human_confirmed as
+        // authority to deny, so stamping it on an un-interviewed write forges the one thing
+        // the strict gate trusts. agent_recorded is the same tier hunch_record_decision uses
+        // for an un-token'd write — advisory, real, and honest about who wrote it.
+        provenance: vouched
+            ? { source: "human_confirmed", confidence: 1, evidence: [], last_verified: now }
+            : { source: "agent_recorded", confidence: 0.75, evidence: [], last_verified: now },
     };
 }
 //# sourceMappingURL=correction.js.map

package/dist/core/docanchors.js

@@ -1,12 +1,45 @@
 import { currentForTopic, rejectedForTopic } from "./topics.js";
 const MARKER = /<!--\s*hunch:topic\s+([A-Za-z0-9._/-]+)(?:\s+(dec_[A-Za-z0-9]+))?\s*-->/g;
-/** Parse every hunch:topic marker out of a markdown document. */
+/** Character ranges covered by fenced code blocks (``` or ~~~), so a
+ *  documentation EXAMPLE of a marker never registers as a live anchor.
+ *  CommonMark-lite: a fence of N chars (≤3 leading spaces) closes only on a
+ *  line of ≥N of the same char and nothing else; an unclosed fence runs to
+ *  EOF; a backtick fence's info string may not itself contain a backtick. */
+function fencedRanges(text) {
+    const ranges = [];
+    let open = null;
+    let offset = 0;
+    for (const line of text.split("\n")) {
+        const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        if (m) {
+            const ch = m[1][0];
+            if (!open) {
+                if (!(ch === "`" && m[2].includes("`")))
+                    open = { ch, len: m[1].length, start: offset };
+            }
+            else if (ch === open.ch && m[1].length >= open.len && m[2].trim() === "") {
+                ranges.push([open.start, offset + line.length]);
+                open = null;
+            }
+        }
+        offset += line.length + 1;
+    }
+    if (open)
+        ranges.push([open.start, text.length]);
+    return ranges;
+}
+/** Parse every hunch:topic marker out of a markdown document. Markers inside
+ *  fenced code blocks are examples, not declarations, and are skipped. */
 export function parseDocAnchors(text) {
     const out = [];
+    const fences = fencedRanges(text);
     MARKER.lastIndex = 0;
     let m;
     while ((m = MARKER.exec(text))) {
-        out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, m.index).split("\n").length });
+        const at = m.index;
+        if (fences.some(([s, e]) => at >= s && at <= e))
+            continue;
+        out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, at).split("\n").length });
     }
     return out;
 }

package/dist/core/premises.js

@@ -5,7 +5,7 @@ const clip = (s, n = 90) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…"
 function validRel(p) {
     return !!p && !p.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(p) && !p.split(/[\\/]/).includes("..");
 }
-function checkPath(claim, rel, wantExists, env) {
+function checkPath(claim, rel, wantExists, env, under) {
     if (!validRel(rel)) {
         return { claim, holds: false, reason: `unevaluable: path must be repo-relative ("${rel}") — fix the premise record` };
     }
@@ -15,13 +15,39 @@ function checkPath(claim, rel, wantExists, env) {
             ? { claim, holds: true, reason: `"${rel}" still exists` }
             : { claim, holds: false, reason: `"${rel}" no longer exists` };
     }
+    // NEGATIVE probe. A missing path proves nothing on its own: a deleted subtree, a
+    // renamed directory and a typo all read as "absent". The `under` anchor is what makes
+    // the answer mean something — when the ancestor is gone, the question no longer has a
+    // subject, so the premise is UNEVALUABLE rather than quietly satisfied. That is the
+    // decay this closes: it is what rotted five decisions pointing into vscode-extension/
+    // after that tree was cut.
+    if (under !== undefined) {
+        if (!validRel(under)) {
+            return { claim, holds: false, reason: `unevaluable: under must be repo-relative ("${under}") — fix the premise record` };
+        }
+        if (!env.exists(under)) {
+            return { claim, holds: false, reason: `unevaluable: the anchor "${under}" no longer exists, so "${rel}" being absent proves nothing — re-anchor or supersede` };
+        }
+    }
     return exists
         ? { claim, holds: false, reason: `"${rel}" now exists` }
-        : { claim, holds: true, reason: `"${rel}" still absent` };
+        // The residual risk is stated, not hidden: a MISTYPED path is also absent, and it
+        // stays absent forever — the harm is a premise that silently never fires, which no
+        // existence probe can detect. Saying so is what keeps "holds" honest.
+        : { claim, holds: true, reason: `"${rel}" still absent${under ? ` under "${under}"` : ""} (a mistyped path also reads as absent — confirm it on re-attest)` };
 }
 function checkOne(p, env) {
+    // The clock is an INJECTED input, so it is an unevaluable case like any other.
+    // `Date.parse("nope")` is NaN, and `NaN > due` is false — which fell through to
+    // "attested until …", i.e. HOLDS. The module's hard rule ("cannot-evaluate is
+    // never holds") was enforced for a bad review_by but not for a bad now, and the
+    // unenforced half is the one a future caller can get wrong. Checked once, here,
+    // so it covers every check kind rather than only the dated one.
+    if (!Number.isFinite(Date.parse(env.now))) {
+        return { claim: p.claim, holds: false, reason: `unevaluable: caller supplied a non-ISO clock ("${env.now}")` };
+    }
     if (p.path_absent !== undefined)
-        return checkPath(p.claim, p.path_absent, false, env);
+        return checkPath(p.claim, p.path_absent, false, env, p.under);
     if (p.path_exists !== undefined)
         return checkPath(p.claim, p.path_exists, true, env);
     if (p.review_by !== undefined) {

package/dist/core/types.js

@@ -115,12 +115,29 @@ export const ConformancePredicateSchema = z.object({
 // (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_absent: z.string().optional().describe("premise holds while this repo-relative path does NOT exist. Requires `under`. PREFER path_exists where you can: a negative probe cannot tell 'verified absent' from 'wrong path', so it fails OPEN, while path_exists fails closed."),
+    under: z.string().optional().describe("required with path_absent: an EXISTING repo-relative ancestor of it. When this anchor disappears (a directory deleted or moved), the premise reads unevaluable instead of silently 'still absent'."),
     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)",
+}).refine((p) => p.path_absent === undefined || (typeof p.under === "string" && p.under.trim().length > 0), {
+    message: "path_absent requires `under`: an existing ancestor path. Without an anchor, a deleted or renamed subtree reads as 'still absent' forever. Prefer path_exists where you can — it fails closed.",
+    path: ["under"],
+}).refine((p) => {
+    if (p.path_absent === undefined || typeof p.under !== "string")
+        return true;
+    const norm = (s) => s.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    const target = norm(p.path_absent);
+    const anchor = norm(p.under);
+    // Must be a real ANCESTOR, not an arbitrary existing path: `under` is what makes
+    // "absent" meaningful ("nothing named gateway UNDER src"). An unrelated anchor
+    // would prove the premise still evaluable while telling you nothing about it.
+    return anchor !== "" && target !== anchor && target.startsWith(`${anchor}/`);
+}, {
+    message: "`under` must be a proper ancestor of `path_absent` (e.g. path_absent 'src/gateway' with under 'src')",
+    path: ["under"],
 });
 export const DecisionSchema = z.object({
     id: z.string().describe("dec_*"),

package/dist/mcp/server.js

@@ -731,14 +731,20 @@ 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."),
+                // FLAT, matching PremiseSchema exactly. A nested { check: {...} } shape is
+                // silently STRIPPED by Zod, leaving a claim-only premise — and a claim-only
+                // premise is "documented only (no check attached)", which ALWAYS HOLDS. An
+                // agent following a wrong schema would record a premise that can never fire:
+                // the exact fail-open this feature exists to prevent. Keep in lockstep with
+                // PremiseSchema in src/core/types.ts.
                 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."),
+                    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. REQUIRES `under`. Prefer path_exists where you can — a negative probe fails OPEN, a positive one fails closed."),
+                    under: z.string().optional().describe("required with path_absent: an EXISTING repo-relative ANCESTOR of it (path_absent 'src/gateway' -> under 'src'). When the anchor disappears the premise reads unevaluable instead of silently 'still absent'."),
+                    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)"),
+                })).optional().describe("the checkable reasons this decision rests on — at most ONE check per premise (path_absent | path_exists | review_by). 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)"),
@@ -936,6 +942,7 @@ export function buildServerWithRootControl(initialRoot) {
             rationale: z.string().optional().describe("Why it must hold."),
             source_decision: z.string().optional().describe("id of a decision this correction derives from."),
             private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — a sensitive rule enforced locally (pre-edit hook + local check) but never exposed in a public PR comment. Errors if no private store is configured."),
+            capture_token: z.string().optional().describe("token from hunch_capture_decision. The rule is recorded and enforced either way — the token only decides whether it may DENY: without one it lands as advisory testimony capped at severity 'warning'."),
         },
     }, async (input) => {
         try {
@@ -945,7 +952,12 @@ export function buildServerWithRootControl(initialRoot) {
             // paths (edit-tool payloads and MCP roots are absolute) and every consumer matches
             // repo-relative — without this the rule would be blocking-but-inert and would leak
             // the local filesystem path into the committed graph.
-            const rec = buildCorrectionConstraint({ ...input, knownDeps: knownRepoDeps(root), root }, new Date().toISOString());
+            // Same authorship tier as hunch_record_decision: a consumed token mints the
+            // signature, an un-token'd write is testimony. Here the stakes are HIGHER — a
+            // blocking constraint DENIES edits, so an un-vouched write is capped at
+            // "warning" rather than being refused. Never Twice still lands immediately.
+            const vouched = consumeCaptureToken(input.capture_token);
+            const rec = buildCorrectionConstraint({ ...input, knownDeps: knownRepoDeps(root), root, vouched }, new Date().toISOString());
             // Private corrections go to the overlay (enforced locally via the merged read,
             // never rendered into the public CI comment, which is public-only by construction).
             const home = store.captureHome(!!input.private);
@@ -978,7 +990,14 @@ export function buildServerWithRootControl(initialRoot) {
             // The Constraint itself is the durable retry queue. Normal `hunch index`
             // and post-commit sync rescan it; no in-process timer can be lost on exit.
             const reviewNote = "\n\nREVIEW PENDING: After the fix is committed, run hunch index; an installed post-commit hook retries this automatically on the fixing commit. Only the supported static ESM import-declaration package projection is eligible, and it remains activation-blocked; the immediate guard is already durable.";
-            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.${reviewNote}`);
+            // Say plainly which tier this landed in. A silent downgrade would be its own
+            // dishonesty: the caller asked for "blocking" and must be told it is not.
+            const tierNote = vouched
+                ? ""
+                : `
+
+⚠ Recorded WITHOUT a capture interview — this rule is agent_recorded TESTIMONY${input.severity === "blocking" ? ' and was capped from "blocking" to "warning"' : ""}. It IS enforced: the pre-edit hook and CI surface it on every matching edit from now on. What it cannot do is DENY an edit — only a rule a human countersigned may block. Countersign it by re-recording through hunch_capture_decision → hunch_record_correction(capture_token).`;
+            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.${reviewNote}${tierNote}`);
         }
         catch (e) {
             return err(`Failed to record correction: ${e.message}`);

package/dist/store/hunchStore.js

@@ -571,7 +571,17 @@ export class HunchStore {
             if (m) {
                 if (m.dead)
                     w *= 0.6;
-                w *= m.provenance.includes("human_confirmed") ? 1 : m.provenance.includes("llm_draft") ? 0.85 : 0.75;
+                // agent_recorded sits BETWEEN human_confirmed and llm_draft. It is testimony —
+                // a human directed the capture but did not countersign it through /capture — so
+                // it must not carry human authority (strict/veto gates key on human_confirmed).
+                // But it is a deliberate, human-prompted write, and the unlabelled tier (0.75)
+                // is for extracted/inferred machine output. Without this it fell to 0.75 and
+                // ranked BELOW an llm_draft the model produced unprompted, which inverts what
+                // the authorship stamp is trying to express.
+                w *= m.provenance.includes("human_confirmed") ? 1
+                    : m.provenance.includes("agent_recorded") ? 0.9
+                        : m.provenance.includes("llm_draft") ? 0.85
+                            : 0.75;
                 if (m.at) {
                     const ageDays = Math.max(0, now - Date.parse(m.at)) / 86400000;
                     if (Number.isFinite(ageDays))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.10.7",
+  "version": "1.11.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -1,19 +1,19 @@
 {
-  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/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.",
+  "description": "Engineering memory for AI-assisted codebases: decisions, bug lineage and invariants, over MCP.",
   "repository": {
     "url": "https://github.com/davesheffer/hunch",
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.10.7",
+  "version": "1.11.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.10.7",
+      "version": "1.11.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {