@davesheffer/hunch 1.3.0 → 1.4.0

package/README.md

@@ -7,30 +7,34 @@
 [![node](https://img.shields.io/badge/node-%E2%89%A522.13-2742ff)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-native-2742ff)](https://modelcontextprotocol.io)
 
-> **A linter checks whether code matches a *pattern*. Hunch checks whether code still matches your *architecture*** —
-> and blocks the AI change that breaks it, citing the decision and the past bug it would reopen.
-> The semantic invariants pattern-SAST can't express (layering, must-reach, dependency direction),
-> enforced deterministically over a **git-native** graph of *why* — across any MCP assistant.
+> **Your repo remembers *what* changed. Hunch makes it remember *why*** — the decisions, the
+> trade-offs, the bugs you already paid for — and keeps every AI coding session consistent with them.
+> When a change would quietly undo something you decided on purpose, Hunch notices and shows the
+> receipt: which decision, and which past bug it protects you from. A linter checks *patterns*;
+> Hunch understands your *architecture* (layering, must-reach, dependency direction) — deterministically,
+> from a **git-native** graph, across any MCP assistant.
 
 ```bash
 npm i -g @davesheffer/hunch
-cd your-repo && hunch init
+cd your-repo && hunch init    # 2 minutes; advisory by default — nothing blocks until you say so
 
-# record an architectural invariant — the kind Semgrep/SonarQube structurally can't express
+# teach it one architectural rule, in plain words — with the why
 hunch conform --add "controllers never reach the DB directly — go through the service layer" \
-  --assert not-calls --subject listOrders --object dbQuery --why "the Mar-2025 N+1 meltdown"
+  --assert not-calls --subject listOrders --object dbQuery --why "the Mar-2025 N+1 incident"
 
-hunch conform --strict     # ✅/⛔ deterministic gate — wire into CI; runs on every AI change
+hunch conform     # ✅ deterministic check — and when you're ready, --strict wires it into CI
 ```
 
-> An AI "optimizes" the controller to query the DB directly. **Semgrep: green. SonarQube: green.**
-> (it's a legitimate internal import — no bad pattern.) **Hunch: ⛔ BLOCKED** — *"listOrders now reaches
-> dbQuery — VIOLATED · why: the Mar-2025 N+1 meltdown · prevents recurrence of bug_0317."* See
+> Here's the moment it earns its keep: an AI "optimizes" your controller to query the DB directly.
+> Pattern tools stay **green** — it's a legitimate internal import, no bad pattern to match.
+> Hunch quietly flags it: *"listOrders now reaches dbQuery · why this matters: the Mar-2025 N+1
+> incident · protects against a repeat of bug_0317."* You decide what happens next — advisory
+> shows the note, **strict** (opt-in) holds the change. Watch the whole loop in 15 seconds:
 > [`demo/architectural-conformance.sh`](demo/architectural-conformance.sh).
 
-**It works both ways — prevent *and* catch — and you need both:**
-- **Prevent** — in a reproducible benchmark ([`bench/`](bench/architectural-conformance.md): n=90, Haiku/Sonnet/Opus, 3 invariant classes), the recorded invariant in context cut architectural violations **58% → 16%** overall (Sonnet **67% → 0%**). But prevention is *necessary, not sufficient*: **even Opus ignored a layering rule 60% of the time when told.** Each violation passes a linter clean.
-- **Catch** — which is exactly why the deterministic gate exists. `hunch check --strict` (the pre-commit hook + the [`hunch ci`](https://hunch-pi.vercel.app/docs#ci) PR gate) **blocks** what the model ignores — with the receipt, **no model in the gate**. Injection helps; the gate is the guarantee.
+**It helps twice — before the change, and after:**
+- **Before** — the recorded rule rides into the AI's context. In a reproducible benchmark ([`bench/`](bench/architectural-conformance.md): n=90, three models, 3 invariant classes), that alone cut architectural drift **58% → 16%** (one model: **67% → 0%**).
+- **After** — reminders help, but models still drift even when told (the same benchmark measured it). So a deterministic check — [`hunch check`](https://hunch-pi.vercel.app/docs#ci) on commit or in your PR gate — catches what reminders miss, always with the receipt, **no model in the loop**. Advisory first; you choose the [firmness](https://hunch-pi.vercel.app/docs#firmness).
 
 <sub>Works with **Claude Code, Cursor, Copilot, Windsurf & Google Antigravity** from one shared, git-native graph.</sub>
 

package/dist/cli/index.js

@@ -50,6 +50,7 @@ import { formatContext, formatStructure } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { injectionMode } from "../core/hookcache.js";
+import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
 import { draftDuplicateOf } from "../core/dupdetect.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
@@ -1556,11 +1557,47 @@ program
         const firmness = readConfig(paths).firmness;
         if (firmness === "off")
             return;
+        // Verification pipeline (delivery enforced, not hoped for — see core/pipeline.ts).
+        // PostToolUse records facts; Stop gates on them. Both are pipeline-only events,
+        // handled before the grounding dispatch below.
+        if (evt.hook_event_name === "PostToolUse" && evt.session_id && pipelineEnabled()) {
+            let st = loadPipelineState(evt.session_id);
+            if (/^(Edit|Write|MultiEdit)$/.test(evt.tool_name ?? "")) {
+                const p = evt.tool_input?.file_path;
+                if (p)
+                    st = onEdit(st, toRepoRel(root, p));
+            }
+            else if (evt.tool_name === "Bash" || evt.tool_name === "PowerShell") {
+                st = onCommand(st, String(evt.tool_input?.command ?? ""));
+            }
+            else if (evt.tool_name === "Skill") {
+                st = onSkill(st, String(evt.tool_input?.skill ?? ""));
+            }
+            savePipelineState(evt.session_id, st);
+            return;
+        }
+        if (evt.hook_event_name === "Stop" && evt.session_id && pipelineEnabled()) {
+            const st = loadPipelineState(evt.session_id);
+            const verdict = stopVerdict(st, firmness);
+            if (verdict.block) {
+                savePipelineState(evt.session_id, verdict.state);
+                process.stdout.write(JSON.stringify({ decision: "block", reason: verdict.reason }));
+            }
+            return;
+        }
         if (evt.hook_event_name === "UserPromptSubmit") {
             // When the prompt reads like a correction ("no / that's wrong / never X"),
             // nudge the agent to PERSIST it as an enforced constraint (Never Twice) —
             // not just obey it this once and forget it next session.
-            const text = looksLikeCorrection(evt.prompt) ? `${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}` : HOOK_REMINDER;
+            let text = looksLikeCorrection(evt.prompt) ? `${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}` : HOOK_REMINDER;
+            // Pipeline turn bookkeeping (fresh block budget) + the one nag that must
+            // repeat: edits from an earlier turn still unverified.
+            if (evt.session_id && pipelineEnabled()) {
+                const st = onPrompt(loadPipelineState(evt.session_id));
+                savePipelineState(evt.session_id, st);
+                if (!st.verifyAfterEdit)
+                    text += `\n\n${UNVERIFIED_NAG}`;
+            }
             // Once per session is enough for the availability reminder — repeating it
             // every prompt burns context for zero information. A correction nudge has
             // different content, so it always comes through (dec_244397d920).
@@ -1579,8 +1616,12 @@ program
             try {
                 const decisions = s.json.loadAll("decisions");
                 const { recent, roadmap, pendingReview } = nowData(decisions, 3);
-                if (!decisions.length)
+                if (!decisions.length) {
+                    // Fresh graph: nothing to orient on, but the operating loop still ships.
+                    if (pipelineEnabled())
+                        emitContext("SessionStart", PIPELINE_LOOP);
                     return;
+                }
                 const L = [];
                 L.push(`🧠 Hunch orientation — ${decisions.length} decision(s) in the graph.`);
                 if (recent.length) {
@@ -1594,6 +1635,10 @@ program
                 if (pendingReview > 0)
                     L.push(`${pendingReview} auto-draft(s) awaiting \`hunch review\`.`);
                 L.push("Orient further: hunch_context(task) · hunch_structure() · `hunch now`.");
+                // The operating loop rides session start — guaranteed delivery, once
+                // (the zod bench showed ambient skills are read in ~0% of sessions).
+                if (pipelineEnabled())
+                    L.push("", PIPELINE_LOOP);
                 emitContext("SessionStart", L.join("\n"));
             }
             finally {

package/dist/core/docanchors.js

@@ -29,8 +29,11 @@ export function renderDocGrounding(anchors, decisions) {
         const rejected = rejectedForTopic(decisions, a.topic);
         if (rejected.length)
             line += `\n    rejected: ${rejected.slice(0, 3).map((r) => clip(r, 90)).join("; ")}`;
-        if (a.pin && a.pin !== current.id) {
-            line += `\n    ⚠ this section is PINNED to ${a.pin}, which is no longer current — reconcile the prose with ${current.id}, then re-pin.`;
+        // Scan ALL markers for this topic, not just the first: the topic dedupe must not
+        // let an earlier unpinned marker swallow a later marker's stale-pin warning.
+        const stalePin = anchors.find((x) => x.topic === a.topic && x.pin && x.pin !== current.id)?.pin;
+        if (stalePin) {
+            line += `\n    ⚠ this section is PINNED to ${stalePin}, which is no longer current — reconcile the prose with ${current.id}, then re-pin.`;
         }
         parts.push(line);
     }

package/dist/core/docscan.js

@@ -47,6 +47,12 @@ export function markdownDocs(root) {
         }
     };
     walk(root, "", 0);
+    // Agent-facing prose lives under dot-dirs the general walk skips: skills and
+    // commands are exactly the docs that rot against the graph (a skill preaching
+    // a superseded decision misleads every future session) — scan them explicitly.
+    for (const sub of [".claude/skills", ".claude/commands"]) {
+        walk(join(root, sub), sub, 1);
+    }
     return out;
 }
 /** Grade every repo doc. GENERATED wiki pages (hunch:wiki header) are views of

package/dist/core/pipeline.js

@@ -0,0 +1,182 @@
+/**
+ * Verification pipeline (the "enforcement spine"): hooks that guarantee the
+ * operating loop — evidence → change → verify → attack → report — instead of
+ * hoping the agent reads a skill. Measured motivation (2026-07-08 zod bench):
+ * skills-as-files were read in 0/20 sessions; when the same content was
+ * guaranteed-delivered, FAIL→PASS flipped on every discriminating cell.
+ * Delivery, not content, was the bottleneck — so delivery is enforced here.
+ *
+ * Gates evaluate OBSERVABLE FACTS recorded from PostToolUse events (which
+ * files were edited, which verify-shaped commands ran afterwards) — never the
+ * agent's claims. The Stop gate refuses to end a turn with unverified product
+ * edits, at most twice per turn: a broken gate degrades to advisory, never a
+ * lockout.
+ *
+ * Firmness mapping (no new knob):
+ *   off      → pipeline inert
+ *   advisory → inject the loop at SessionStart + nag on unverified edits; no blocks
+ *   firm     → + Stop gate (max 2 blocks per turn)
+ *   strict   → same as firm (strict's extra bite lives in the pre-edit deny gate)
+ *
+ * State is per-session scratch in the OS tmpdir (NOT .hunch/ — it is derived,
+ * disposable, and single-writer), mirroring hookcache.ts. Failure posture is
+ * con_03a0b94b2e: any error → do nothing, exit clean. Kill switch: HUNCH_PIPELINE=0.
+ */
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const emptyState = () => ({
+    turn: 0,
+    soulInjected: false,
+    blocks: 0,
+    domains: {},
+    editedFiles: [],
+    verifyAfterEdit: true,
+});
+export const DEFAULT_PROFILES = {
+    backend: {
+        paths: /(^|\/)(src|lib|server|api|core|store|services?)\/|\.(ts|mts|cts|js|mjs|cjs|py|go|rs|java|rb|php)$/i,
+        verify: /vitest|jest|pytest|go test|cargo test|tsx --test|npm (run )?test|pnpm (run )?test|tsc|typecheck/i,
+    },
+    frontend: {
+        paths: /\.(tsx|jsx|css|scss|html|vue|svelte)$|(^|\/)(components|pages|site|app|ui)\//i,
+        verify: /vite|next (build|dev)|npm run (build|dev)|pnpm (run )?(build|dev)|playwright|storybook|tsc/i,
+    },
+    tests: {
+        paths: /(^|\/)(test|tests|__tests__|e2e|spec)\/|\.(test|spec)\./i,
+        verify: /vitest|jest|pytest|tsx --test|npm (run )?test|pnpm (run )?test|playwright/i,
+    },
+    infra: {
+        paths: /Dockerfile|docker-compose|\.tf$|\.tfvars$|(^|\/)(\.github|k8s|helm|terraform|infra|deploy)\/|\.ya?ml$/i,
+        verify: /terraform (plan|validate)|docker (build|compose)|kubectl .*--dry-run|helm (lint|template)|actionlint|npm run build/i,
+    },
+};
+/** Product code = behavior that ships. Docs, hunch's own graph, and .claude
+ *  config are not gated — editing THIS machinery must never trip it. */
+export function isProductPath(p) {
+    const norm = String(p).replace(/\\/g, "/");
+    if (/\.(md|mdx|txt)$/i.test(norm))
+        return false;
+    if (/(^|\/)\.(claude|hunch)(\/|$)/.test(norm))
+        return false;
+    return true;
+}
+export function classifyDomains(path, profiles = DEFAULT_PROFILES) {
+    const norm = path.replace(/\\/g, "/");
+    return Object.entries(profiles)
+        .filter(([, d]) => d.paths.test(norm))
+        .map(([name]) => name);
+}
+function verifyPattern(state, profiles = DEFAULT_PROFILES) {
+    const active = Object.keys(state.domains).filter((d) => profiles[d]);
+    const src = (active.length ? active : Object.keys(profiles)).map((d) => profiles[d].verify.source).join("|");
+    return new RegExp(src, "i");
+}
+// ------------------------------------------------------- state transitions
+/** New user prompt: fresh block budget. */
+export function onPrompt(state) {
+    return { ...state, turn: state.turn + 1, blocks: 0 };
+}
+/** Edit/Write/MultiEdit landed on `path`. */
+export function onEdit(state, path, profiles = DEFAULT_PROFILES) {
+    if (!path || !isProductPath(path))
+        return state;
+    const domains = { ...state.domains };
+    for (const d of classifyDomains(path, profiles))
+        domains[d] = true;
+    return {
+        ...state,
+        domains,
+        verifyAfterEdit: false,
+        editedFiles: state.editedFiles.includes(path) ? state.editedFiles : [...state.editedFiles, path],
+    };
+}
+/** A shell command ran. Verify-shaped + after an edit → the edits are covered. */
+export function onCommand(state, command, profiles = DEFAULT_PROFILES) {
+    if (state.editedFiles.length && verifyPattern(state, profiles).test(command)) {
+        return { ...state, verifyAfterEdit: true };
+    }
+    return state;
+}
+/** A verification-class skill ran (/verify, /code-review) — counts as coverage. */
+export function onSkill(state, skill) {
+    if (/code-review|verify|review/i.test(skill))
+        return { ...state, verifyAfterEdit: true };
+    return state;
+}
+// ------------------------------------------------------------------- gates
+export const PIPELINE_LOOP = [
+    "Hunch pipeline — operating loop (enforced on observable facts, not claims):",
+    "1. SCOPE — restate the task; define done as something observable (a passing test, a rendered page, a number).",
+    "2. EVIDENCE — observe current behavior before editing: run the failing thing, read the real code path, quote the real error.",
+    "3. CHANGE — smallest edit that fixes the root cause, not the symptom.",
+    "4. VERIFY — after the last edit, RUN the relevant check (test/build/typecheck/plan). A claim without an exit code is not a result.",
+    "5. ATTACK — one honest paragraph: what would make this conclusion wrong?",
+    "6. REPORT — what ran, what passed, what stays unverified. Failures verbatim.",
+].join("\n");
+export const UNVERIFIED_NAG = "Hunch pipeline: earlier product edits are still UNVERIFIED — run the relevant test/build/typecheck before claiming anything about them.";
+/** Stop-gate verdict. Blocks only at firm/strict, only with unverified product
+ *  edits, and at most twice per turn. */
+export function stopVerdict(state, firmness) {
+    const gated = firmness === "firm" || firmness === "strict";
+    if (!gated || state.verifyAfterEdit || state.editedFiles.length === 0 || state.blocks >= 2)
+        return { block: false };
+    const domains = Object.keys(state.domains).join(", ") || "generic";
+    return {
+        block: true,
+        state: { ...state, blocks: state.blocks + 1 },
+        reason: `Hunch pipeline gate — VERIFY unsatisfied. Product files were edited (${state.editedFiles.slice(-5).join(", ")}) ` +
+            `but no verifying command ran afterwards (domain: ${domains}). Do now, in order: ` +
+            `(1) run the relevant test/build/typecheck for those files; ` +
+            `(2) one honest paragraph attacking your own conclusion — what would make it wrong; ` +
+            `(3) report what ran, what passed, what stays unverified. ` +
+            `If verification is truly impossible here, say so explicitly and why.`,
+    };
+}
+// ------------------------------------------------------------------ storage
+const STATE_DIR = join(tmpdir(), "hunch-pipeline");
+const SWEEP_AGE_MS = 48 * 3600 * 1000;
+export function pipelineEnabled() {
+    return process.env.HUNCH_PIPELINE !== "0";
+}
+/** Load session state; on ANY problem return a fresh state (never throw). */
+export function loadPipelineState(sessionId) {
+    try {
+        const raw = JSON.parse(readFileSync(stateFile(sessionId), "utf8"));
+        return { ...emptyState(), ...raw };
+    }
+    catch {
+        return emptyState();
+    }
+}
+/** Persist session state (best effort — scratch data, single writer). */
+export function savePipelineState(sessionId, state) {
+    try {
+        mkdirSync(STATE_DIR, { recursive: true });
+        sweep();
+        writeFileSync(stateFile(sessionId), JSON.stringify(state));
+    }
+    catch {
+        /* losing scratch state beats breaking the hook */
+    }
+}
+function stateFile(sessionId) {
+    return join(STATE_DIR, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+}
+function sweep() {
+    try {
+        for (const f of readdirSync(STATE_DIR)) {
+            try {
+                if (Date.now() - statSync(join(STATE_DIR, f)).mtimeMs > SWEEP_AGE_MS)
+                    rmSync(join(STATE_DIR, f), { force: true });
+            }
+            catch {
+                /* raced — skip */
+            }
+        }
+    }
+    catch {
+        /* dir unreadable — skip */
+    }
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/integrations/scaffold.js

@@ -141,6 +141,17 @@ export function installClaudeHooks(root, hookCmd) {
         ...keep(json.hooks.SessionStart),
         { hooks: [{ type: "command", command: hookCmd }] },
     ];
+    // Verification pipeline (core/pipeline.ts): PostToolUse records observable
+    // facts (edits, verify commands); Stop refuses to end a turn with unverified
+    // product edits at firm/strict firmness. Delivery is enforced, not hoped for.
+    json.hooks.PostToolUse = [
+        ...keep(json.hooks.PostToolUse),
+        { matcher: "Edit|Write|MultiEdit|Bash|PowerShell|Skill", hooks: [{ type: "command", command: hookCmd }] },
+    ];
+    json.hooks.Stop = [
+        ...keep(json.hooks.Stop),
+        { hooks: [{ type: "command", command: hookCmd }] },
+    ];
     const next = JSON.stringify(json, null, 2) + "\n";
     if (existed && before === next)
         return { path: file, action: "unchanged" };

package/dist/mcp/server.js

@@ -53,9 +53,23 @@ const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} m
 // thin wrappers bind the process clock and id source at the call site (§5 Stage 1).
 const issueCaptureToken = () => issueToken(randomUUID, Date.now());
 const consumeCaptureToken = (token) => consumeToken(token, Date.now());
-/** The interrogation protocol returned by hunch_capture_decision. */
-function grillingProtocol(topic, token) {
-    return [
+/** The interrogation protocol returned by hunch_capture_decision. With `deciding`,
+ *  the choice is NOT yet made: the verdict loop runs first so the record's
+ *  alternatives_rejected are attacks that actually ran — not post-hoc fiction. */
+function grillingProtocol(topic, token, deciding = false) {
+    const verdict = [
+        "The decision is NOT yet made — run the VERDICT LOOP first (one question at a time), then the grilling rules below.",
+        "",
+        "VERDICT LOOP:",
+        "A. SPLIT — one separable call per verdict, one topic per call. If the ask bundles several decisions, split and run each.",
+        "B. CANDIDATES — elicit at least TWO real options (include do-nothing when sane). One candidate = anchoring; keep asking.",
+        "C. ATTACK — attack each candidate from INDEPENDENT lenses: product, technical, strategy, economics, and self-consistency (does it contradict a recorded decision or constraint? cite dec_/con_ ids). Every attack cites evidence observed this session; no evidence → mark it plausible and weigh it less.",
+        "D. CONVERGE — two or more independent landing attacks kill a candidate. Keep the FAILED attacks too — they are the tested-safe surface; fold them into context. No convergence → prefer the candidate whose failure is REVERSIBLE.",
+        "E. TRIPWIRES — for each rejected candidate, ask what future evidence would make it right after all; embed it in the rejected alternative ('rejected X — revisit if Y').",
+        "",
+        "",
+    ].join("\n");
+    return (deciding ? verdict : "") + [
         "You are capturing an engineering decision into Hunch's graph. Run the GRILLING LOOP, then commit.",
         "",
         "RULES:",
@@ -68,6 +82,20 @@ function grillingProtocol(topic, token) {
         "Required before commit: topic, title, decision, context (the rationale/why), alternatives_rejected. Missing any → keep grilling.",
     ].join("\n");
 }
+/** Deterministic quality nudge for a freshly recorded ACCEPTED decision: an
+ *  unattacked record (no rejected alternatives) or rejections without a
+ *  "revisit if" flip condition get ONE advisory line — never a gate. */
+function qualityNudge(rec) {
+    if (rec.status !== "accepted")
+        return "";
+    if (!rec.alternatives_rejected.length) {
+        return `\n\n△ Unattacked record: no alternatives_rejected. The graph can only veto what was explicitly rejected — next time run hunch_capture_decision(deciding:true) so rejections come from attacks that actually ran.`;
+    }
+    if (!rec.alternatives_rejected.some((a) => /revisit if/i.test(a))) {
+        return `\n\n△ Tip: none of the ${rec.alternatives_rejected.length} rejected alternative(s) carries a "revisit if …" flip condition — embed one per rejection so a future session knows when the call expires.`;
+    }
+    return "";
+}
 /** Resolve a free-form target (symbol id / name / file path) to symbol records. */
 function resolveSymbols(store, target) {
     target = toPosixTarget(target);
@@ -359,10 +387,11 @@ export function buildServer(root) {
         inputSchema: {
             topic: z.string().optional().describe("proposed topic anchor (confirm with the human before committing)"),
             seed: z.string().optional().describe("what the decision is about, to focus the first question"),
+            deciding: z.boolean().optional().describe("the choice is NOT yet made — prepend the verdict loop (candidates → evidenced attacks → convergence → tripwires) so alternatives_rejected come from attacks that actually ran, then grill and record as usual"),
         },
-    }, async ({ topic, seed }) => {
+    }, async ({ topic, seed, deciding }) => {
         const token = issueCaptureToken();
-        return ok(`${grillingProtocol(topic, token)}${seed ? `\n\nSeed: ${seed}` : ""}`);
+        return ok(`${grillingProtocol(topic, token, !!deciding)}${seed ? `\n\nSeed: ${seed}` : ""}`);
     });
     // -- hunch_current_decision (decision-grounding: current(topic)) ----------
     server.registerTool("hunch_current_decision", {
@@ -448,31 +477,36 @@ export function buildServer(root) {
                 provenance: { source, confidence: 0.95, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
                 date: now,
             };
+            // Where this write will actually land (see captureHome). Resolved BEFORE the
+            // uniqueness guard: in unified ("shared") mode home is the overlay even when
+            // private:false, so the guard must key its incumbent lookup on HOME, not on
+            // the flag — keying on the flag let a shared-mode supersede of a public
+            // incumbent pass the guard and then no-op the close (two live decisions).
+            const home = store.captureHome(!!decision.private);
             // Decision-grounding uniqueness guard (§4 Enforcement): never create a SECOND
             // live decision for one topic. Exclude ONLY the incumbent this write will
             // actually close — one resolvable in the SAME store the write lands in. A
-            // cross-store supersede (public write vs a private incumbent, or vice-versa)
+            // cross-store supersede (the incumbent lives where this write can't close it)
             // would no-op and leave two live decisions, so it is treated as unresolved
             // (willClose=null) → the guard fires and refuses. Same-id re-record is allowed.
             if (rec.topic && rec.status === "accepted") {
-                const willClose = decision.supersedes && store.decisionInStore(decision.supersedes, !!decision.private)
+                const willClose = decision.supersedes && store.decisionInStore(decision.supersedes, home === "private")
                     ? decision.supersedes
                     : null;
                 const others = captureConflicts(store.recs("decisions"), rec.topic, id, willClose);
                 if (others.length) {
                     const list = others.map((d) => `${d.id} ("${d.title}")`).join(", ");
                     const crossStore = decision.supersedes && !willClose
-                        ? ` (note: supersedes:"${decision.supersedes}" is not in the ${decision.private ? "private" : "public"} store, so it can't be closed from here)`
+                        ? ` (note: supersedes:"${decision.supersedes}" is not in the ${home} store this write lands in, so it can't be closed from here)`
                         : "";
                     return err(`Topic "${rec.topic}" already has a live decision: ${list}.${crossStore} ` +
                         `Hunch will not create a second current decision for one topic. Resolve it: ` +
                         `re-record with supersedes:<id> to replace it (linked, same store), pick a distinct topic to split, or discard this capture.`);
                 }
             }
-            // Route the write to its ONE home (captureHome): an explicit private:true goes to
-            // the overlay (putPrivate throws rather than silently falling public); in unified
-            // ("shared") mode EVERY capture goes to the overlay; else the public store.
-            const home = store.captureHome(!!decision.private);
+            // Route the write to its ONE home: an explicit private:true goes to the overlay
+            // (putPrivate throws rather than silently falling public); in unified ("shared")
+            // mode EVERY capture goes to the overlay; else the public store.
             if (home === "private")
                 store.putPrivate("decisions", rec);
             else
@@ -501,12 +535,15 @@ export function buildServer(root) {
                 : 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.)`;
+            // 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) : "";
             const supNote = superseded ? ` Superseded ${superseded.id} (window closed at ${rec.valid_from}).` : "";
             const note = decision.commit && !fullSha ? ` (note: commit "${decision.commit}" could not be resolved — recorded as a standalone decision, not linked to a commit)` : "";
             const where = decision.private
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}${captureNote}`);
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}${captureNote}${quality}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",