@davesheffer/hunch 1.2.3 → 1.3.1

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>
 
@@ -44,7 +48,7 @@ guards, troubleshooting. This README is the tour. Jump to:
 [CLI reference](https://hunch-pi.vercel.app/docs#cli) ·
 [Troubleshooting](https://hunch-pi.vercel.app/docs#doctor)
 
-> 🆕 **v1.2.2** — the [component wiki + specs ledger](https://hunch-pi.vercel.app/docs#wiki): Hunch takes over your stale docs — graded deterministically, adopted into a graph-healed wiki copy, never rewriting your originals — with staleness drift-gated in CI. Plus honest auto-commit reporting, a friendly Node < 22.13 gate, and churn-free reindexing. [Full changelog →](https://hunch-pi.vercel.app/changelog)
+> 🆕 **v1.3.0** — retrieval that follows the graph: live decisions outrank superseded ones, human-vouched outrank drafts, and a query that hits history surfaces the topic's *current* decision (Recall@10 90→100% on the committed golden set). Plus `hunch now` + the roadmap-as-proposed-decisions, session-deduped hook grounding (~100× smaller on repeats), content-matched blocking gates, and duplicate auto-drafts skipped before the LLM is called. [Full changelog →](https://hunch-pi.vercel.app/changelog)
 
 ## The problem
 

package/dist/cli/index.js

@@ -49,10 +49,13 @@ import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 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 { draftDuplicateOf } from "../core/dupdetect.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
-import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWikiManifestAt } from "../wiki/wiki.js";
+import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWikiManifestAt, nowData } from "../wiki/wiki.js";
+import { adoptProsePrompt } from "../wiki/adopt.js";
 import { topicCollisions, renderGrounding } from "../core/topics.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
 import { compareCandidates } from "../core/compare.js";
@@ -1411,13 +1414,30 @@ program
     .argument("<target>", "file path or symbol")
     .option("--budget <n>", "rough token budget", "1500")
     .option("--as-of <ref>", "time-travel: assemble the slice as it stood at a commit/tag/branch")
-    .action((target, opts) => {
+    .action(async (target, opts) => {
     const { store, root } = storeFor();
     const asOf = opts.asOf ? asOfDate(opts.asOf, root) : undefined;
     if (opts.asOf && !asOf)
         return fail(`could not resolve --as-of "${opts.asOf}" to a commit`);
     store.reindex(); // reflect any out-of-band JSON edits before assembling
-    process.stdout.write(formatContext(store.assembleContext(target, Number(opts.budget), { asOf })));
+    const ctx = store.assembleContext(target, Number(opts.budget), { asOf });
+    // A task PHRASE ("improve retrieval ranking") resolves no file/symbol target and
+    // used to come back empty while the graph held the answer one FTS query away —
+    // the task-shaped entry point must not whiff on task-shaped input. Fall back to
+    // search so the caller always leaves with the closest graph matches.
+    const empty = !ctx.constraints.length && !ctx.decisions.length && !ctx.bugs.length && !ctx.blast_radius.length;
+    if (empty && !asOf) {
+        const hits = store.search(target, 8);
+        if (hits.length) {
+            console.log(`No file/symbol resolves for "${target}" — closest graph matches instead:\n`);
+            for (const h of hits)
+                console.log(`• ${h.ref} — ${h.title}\n    ${h.snippet}`);
+            console.log(`\n(For a file/symbol brief use a concrete target; for free-text this is what \`hunch query\` returns.)`);
+            store.close();
+            return;
+        }
+    }
+    process.stdout.write(formatContext(ctx));
     store.close();
 });
 // ---- timeline -------------------------------------------------------------
@@ -1541,9 +1561,46 @@ program
             // 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;
+            // 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).
+            if (injectionMode(evt.session_id, "prompt-reminder", text) === "delta")
+                return;
             emitContext("UserPromptSubmit", text);
             return;
         }
+        if (evt.hook_event_name === "SessionStart") {
+            // Orientation at the moment it matters: what just happened + what's next,
+            // straight from the graph — the agent sits down already knowing where it
+            // is instead of pulling (or worse, grepping) for it. Cheap reads only
+            // (no reindex, no drift walk); public store only — session transcripts
+            // travel further than a terminal. Union view: `hunch now --private`.
+            const s = new HunchStore(paths);
+            try {
+                const decisions = s.json.loadAll("decisions");
+                const { recent, roadmap, pendingReview } = nowData(decisions, 3);
+                if (!decisions.length)
+                    return;
+                const L = [];
+                L.push(`🧠 Hunch orientation — ${decisions.length} decision(s) in the graph.`);
+                if (recent.length) {
+                    L.push("Recent:");
+                    for (const r of recent)
+                        L.push(`  ${r.date} [${r.status}] ${r.title} (${r.id})`);
+                }
+                if (roadmap.length) {
+                    L.push(`Roadmap (${roadmap.length} live proposed): ${roadmap.slice(0, 3).map((r) => r.title).join(" · ")}${roadmap.length > 3 ? " · …" : ""}`);
+                }
+                if (pendingReview > 0)
+                    L.push(`${pendingReview} auto-draft(s) awaiting \`hunch review\`.`);
+                L.push("Orient further: hunch_context(task) · hunch_structure() · `hunch now`.");
+                emitContext("SessionStart", L.join("\n"));
+            }
+            finally {
+                s.close();
+            }
+            return;
+        }
         if (evt.hook_event_name !== "PreToolUse")
             return;
         const abs = evt.tool_input?.file_path;
@@ -1616,6 +1673,13 @@ program
             text += `\n\n${grounding}`;
         if (docGround)
             text += `\n\n${docGround}`;
+        // Identical grounding already shown this session → one-line delta instead of
+        // the full 10-16KB block. Any record change re-sends the full text; the
+        // strict-gate deny path above never routes through this (dec_244397d920).
+        if (injectionMode(evt.session_id, `pre:${target}`, text) === "delta") {
+            emitContext("PreToolUse", `Hunch grounding for ${target}: unchanged this session (${ctx.decisions.length} decision(s), ${ctx.constraints.length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
+            return;
+        }
         emitContext("PreToolUse", text);
     }
     catch {
@@ -1663,6 +1727,7 @@ program
     .option("--accept <id>", "promote a decision to accepted/human-confirmed (confirms its tripwires)")
     .option("--reject <id>", "delete a draft decision")
     .option("--accept-verified", "batch-accept every Critic-verified, well-grounded draft (>= --min-grounded)")
+    .option("--reject-duplicates", "batch-reject drafts that near-duplicate an accepted record (deterministic term+file similarity — hygiene, not judgment)")
     .option("--min-grounded <n>", "grounded-ness threshold for the ready group / --accept-verified", String(READY_MIN_GROUNDED))
     .action((opts) => {
     const { store, root } = storeFor();
@@ -1683,6 +1748,28 @@ program
         store.reindex();
         console.log(ok2 ? `✓ rejected and removed ${opts.reject}` : `decision ${opts.reject} not found`);
     }
+    else if (opts.rejectDuplicates) {
+        // Deterministic hygiene, not a trust decision (dec_a466655539 stays intact):
+        // only drafts, only against ACCEPTED records, conservative threshold.
+        const all = store.json.loadAll("decisions");
+        const drafts = all.filter((d) => d.status === "proposed" && !d.provenance.source.includes("human_confirmed"));
+        const dupes = drafts
+            .map((d) => ({ d, m: draftDuplicateOf(d, all) }))
+            .filter((x) => !!x.m);
+        if (!dupes.length) {
+            console.log("✓ No near-duplicate drafts.");
+        }
+        else {
+            let removed = 0;
+            for (const { d, m } of dupes) {
+                if (store.json.delete("decisions", d.id))
+                    removed++;
+                console.log(`  ✗ ${d.id} — "${d.title}"\n      duplicate of ${m.of.id} — "${m.of.title}" (${Math.round(m.score * 100)}%)`);
+            }
+            store.reindex();
+            console.log(`\n✓ Rejected ${removed} duplicate draft(s). Accepted records untouched.`);
+        }
+    }
     else if (opts.acceptVerified) {
         // Batch path: only Critic-verified, well-grounded drafts qualify — still the
         // human-driven accept gate (the operator runs this), just over a safe subset.
@@ -1717,8 +1804,18 @@ program
             }
             if (scrutiny.length) {
                 console.log(`⚠ ${scrutiny.length} need scrutiny — unverified / low-grounded (lowest confidence first):\n`);
-                for (const it of scrutiny)
+                const all = store.json.loadAll("decisions");
+                let dupCount = 0;
+                for (const it of scrutiny) {
                     printReviewItem(it);
+                    const m = draftDuplicateOf(it.d, all);
+                    if (m) {
+                        dupCount++;
+                        console.log(`      ⚠ likely DUPLICATE of ${m.of.id} — "${m.of.title}" (${Math.round(m.score * 100)}%)`);
+                    }
+                }
+                if (dupCount)
+                    console.log(`\n   Batch-reject the ${dupCount} duplicate(s): hunch review --reject-duplicates`);
             }
             console.log(`\nAccept: hunch review --accept <id>   Reject: hunch review --reject <id>`);
         }
@@ -1903,6 +2000,7 @@ program
     .option("--heal", "regenerate only new/stale pages (manifest hash mismatch) and remove orphans")
     .option("--check", "report stale pages and exit non-zero (CI gate); writes nothing")
     .option("--no-llm", "skip LLM prose; deterministic template pages only")
+    .option("--prose-heal", "also LLM-rewrite each adopted copy's reconciled overview (subscription; the deterministic corrections always remain)")
     .option("--private", "render the FULL graph (private overlay included) and write the wiki into the OVERLAY repo — nothing lands in this repo")
     .action(async (opts) => {
     const { store, root } = storeFor();
@@ -1965,21 +2063,27 @@ program
         // Prose is optional garnish on the deterministic skeleton: subscription CLI
         // only (same rule as synthesis), feature-detected, and any failure degrades
         // to a template page — generation never depends on a model being present.
+        if (opts.proseHeal && opts.llm === false)
+            return fail("--prose-heal needs the LLM — drop --no-llm.");
         let prose;
+        let adoptionProse;
         if (opts.llm !== false) {
             const provider = await selectProvider();
             if (provider.draftProse) {
                 console.log(`Prose via ${provider.name} (subscription); the drift-bearing skeleton stays deterministic.`);
                 prose = (pack, excerpts) => provider.draftProse(wikiPrompt(pack, excerpts));
+                if (opts.proseHeal)
+                    adoptionProse = (doc, content) => provider.draftProse(adoptProsePrompt(doc, content, status.decisions));
             }
             else {
-                console.log("No subscription CLI available — deterministic template pages.");
+                console.log(`No subscription CLI available — deterministic template pages${opts.proseHeal ? " (prose-heal skipped)" : ""}.`);
             }
         }
         const res = await generateWiki(store, root, home, {
             now: new Date().toISOString(),
             only: opts.heal ? "stale" : "all",
             prose,
+            adoptionProse,
             log: (l) => console.log(l),
         });
         if (!res.written.length && !res.removed.length) {
@@ -1997,6 +2101,34 @@ program
         store.close();
     }
 });
+// ---- now (the hot view: recent activity + roadmap) --------------------------
+program
+    .command("now")
+    .description("The hot view — last decisions recorded (any status) and the ROADMAP: every live PROPOSED decision. Record what's next as a proposed decision; shipping it (accept/supersede) removes it here automatically. Same data as the wiki's now.md page. Read-only.")
+    .option("--private", "include the private overlay (union) — local terminal output only")
+    .option("--recent <n>", "how many recent decisions to show", "10")
+    .action((opts) => {
+    const { store } = storeFor();
+    try {
+        if (opts.private && !store.hasPrivate)
+            return fail("no private overlay configured — run `hunch private` (or `hunch shared`) first.");
+        const decisions = opts.private ? store.recs("decisions") : store.json.loadAll("decisions");
+        const { recent, roadmap, pendingReview } = nowData(decisions, Number(opts.recent) || 10);
+        console.log(`🔥 Recent (${recent.length})${opts.private ? " — union incl. private overlay; do not paste publicly" : ""}:`);
+        for (const r of recent)
+            console.log(`  ${r.date}  [${r.status}] ${r.title}  (${r.id}${r.topic ? `, ${r.topic}` : ""})`);
+        console.log(`\n🗺 Roadmap — live proposed decisions (${roadmap.length}):`);
+        if (!roadmap.length)
+            console.log("  (empty — record what's next as a PROPOSED decision via /capture and it appears here)");
+        for (const r of roadmap)
+            console.log(`  • ${r.title}  (${r.id}${r.topic ? `, ${r.topic}` : ""}, since ${r.date})\n      ${r.note}`);
+        if (pendingReview > 0)
+            console.log(`\n  (${pendingReview} auto-drafted proposal(s) awaiting review — \`hunch review\`)`);
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- heal (decision-grounded drift reconciliation front door) -------------
 program
     .command("heal")

package/dist/core/dupdetect.js

@@ -0,0 +1,100 @@
+import { toPosixTarget } from "./paths.js";
+/** Days a human-confirmed decision "covers" its files against auto-drafts.
+ *  Wide enough for record-then-commit workflows (even across a weekend),
+ *  narrow enough that revisiting the same files next month drafts normally. */
+const COVER_WINDOW_DAYS = 14;
+const STOP = new Set([
+    "the", "a", "an", "and", "or", "not", "for", "with", "into", "onto", "over", "under", "this", "that",
+    "when", "then", "than", "from", "are", "is", "was", "were", "will", "must", "never", "always", "via",
+    "instead", "rather", "only", "every", "each", "its", "their", "our", "your", "has", "have", "had",
+    "feat", "fix", "chore", "docs", "refactor", "test", "tests", "add", "adds", "added", "new", "now",
+]);
+/** Lowercased salient terms (≥4 chars, non-stopword) — deliberately simple and
+ *  deterministic; shared by both layers so their notion of "similar" agrees. */
+export function dupTerms(text) {
+    const out = new Set();
+    for (const m of text.toLowerCase().matchAll(/[a-z][a-z0-9_-]{3,}/g))
+        if (!STOP.has(m[0]))
+            out.add(m[0]);
+    return out;
+}
+function jaccard(a, b) {
+    if (!a.size || !b.size)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+function fileSet(files) {
+    return new Set((files ?? []).map(toPosixTarget).filter((f) => f && !f.includes("*")));
+}
+/** Does a RECENT human-confirmed live decision already claim this commit's
+ *  files (and roughly its subject)? Deterministic pre-draft gate. */
+export function commitCoveredBy(codeFiles, subject, existing, nowMs) {
+    const commitFiles = fileSet(codeFiles);
+    if (!commitFiles.size)
+        return null;
+    const subjectTerms = dupTerms(subject);
+    let best = null;
+    for (const d of existing) {
+        if (!d.provenance.source.includes("human_confirmed"))
+            continue;
+        if (d.status === "superseded" || d.status === "rejected" || d.superseded_by || d.valid_to)
+            continue;
+        const at = Date.parse(d.valid_from ?? d.date);
+        if (!Number.isFinite(at))
+            continue;
+        const ageDays = (nowMs - at) / 86400000;
+        if (ageDays < 0 || ageDays > COVER_WINDOW_DAYS)
+            continue;
+        const decFiles = fileSet(d.related_files);
+        if (!decFiles.size)
+            continue;
+        let overlap = 0;
+        for (const f of commitFiles)
+            if (decFiles.has(f))
+                overlap++;
+        const overlapRatio = overlap / commitFiles.size; // how much of the COMMIT the decision claims
+        const termSim = jaccard(subjectTerms, dupTerms(`${d.title} ${d.decision}`));
+        // Strong file claim alone, or a moderate claim corroborated by the subject.
+        const covered = overlapRatio >= 0.6 || (overlap >= 2 && overlapRatio >= 0.34 && termSim >= 0.15);
+        if (!covered)
+            continue;
+        const cov = { id: d.id, title: d.title, hoursAgo: Math.round((nowMs - at) / 3600000), fileOverlapPct: Math.round(overlapRatio * 100) };
+        if (!best || cov.fileOverlapPct > best.fileOverlapPct)
+            best = cov;
+    }
+    return best;
+}
+/** Is an existing DRAFT a near-duplicate of an accepted record? Review-time
+ *  flag; threshold callers use 0.35 (batch-reject) — conservative on purpose. */
+export function draftDuplicateOf(draft, existing) {
+    const draftTerms = dupTerms(`${draft.title} ${draft.decision}`);
+    const draftFiles = fileSet(draft.related_files);
+    let best = null;
+    for (const d of existing) {
+        if (d.id === draft.id)
+            continue;
+        if (!d.provenance.source.includes("human_confirmed"))
+            continue;
+        if (d.status === "superseded" || d.status === "rejected" || d.superseded_by || d.valid_to)
+            continue;
+        const termSim = jaccard(draftTerms, dupTerms(`${d.title} ${d.decision}`));
+        let fileBoost = 0;
+        if (draftFiles.size) {
+            const decFiles = fileSet(d.related_files);
+            let overlap = 0;
+            for (const f of draftFiles)
+                if (decFiles.has(f))
+                    overlap++;
+            fileBoost = draftFiles.size ? (overlap / draftFiles.size) * 0.25 : 0;
+        }
+        const score = Math.min(1, termSim + fileBoost);
+        if (score >= 0.35 && (!best || score > best.score))
+            best = { of: d, score };
+    }
+    return best;
+}
+//# sourceMappingURL=dupdetect.js.map

package/dist/core/hookcache.js

@@ -0,0 +1,75 @@
+/**
+ * Session-scoped injection dedup (roadmap dec_244397d920): the pre-edit hook
+ * re-fires on EVERY edit, and re-injecting an identical 10-16KB grounding block
+ * 20+ times per session buries the agent's working context under repeats — the
+ * cost of being grounded starts competing with the work.
+ *
+ * Mechanism: per Claude-Code session (the hook event carries session_id), keep
+ * a tiny {key → content-hash} map in the OS tmpdir. First injection for a key
+ * (or any time the underlying records CHANGE) → "full". Identical repeat →
+ * "delta" (the caller emits a one-liner, or nothing).
+ *
+ * Failure posture inherits con_03a0b94b2e but inverted for safety: the hook
+ * must never crash an edit AND dedup must never cost grounding — so on ANY
+ * cache error (unwritable tmpdir, corrupt file, missing session id) the answer
+ * is "full". Deny decisions are never routed through here: the gate re-checks
+ * every edit regardless. Kill switch: HUNCH_HOOK_DEDUP=0.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+const MAX_KEYS = 300;
+const SWEEP_AGE_MS = 48 * 3600 * 1000;
+/** Decide whether this injection should be the FULL grounding block or a delta
+ *  one-liner. Records the content hash as a side effect (so the next identical
+ *  call dedups). Never throws. */
+export function injectionMode(sessionId, key, content) {
+    try {
+        if (!sessionId || process.env.HUNCH_HOOK_DEDUP === "0")
+            return "full";
+        const dir = join(tmpdir(), "hunch-hookcache");
+        mkdirSync(dir, { recursive: true });
+        sweep(dir);
+        const file = join(dir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+        const hash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+        let map;
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            map = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+        }
+        catch {
+            map = {};
+        }
+        if (map[key] === hash)
+            return "delta";
+        map[key] = hash;
+        const keys = Object.keys(map);
+        if (keys.length > MAX_KEYS)
+            for (const k of keys.slice(0, keys.length - MAX_KEYS))
+                delete map[k];
+        writeFileSync(file, JSON.stringify(map));
+        return "full";
+    }
+    catch {
+        return "full"; // grounded beats deduped, always
+    }
+}
+/** Drop session caches from long-gone sessions (best effort, bounded dir). */
+function sweep(dir) {
+    try {
+        for (const f of readdirSync(dir)) {
+            try {
+                if (Date.now() - statSync(join(dir, f)).mtimeMs > SWEEP_AGE_MS)
+                    rmSync(join(dir, f), { force: true });
+            }
+            catch {
+                /* someone else's file / raced — skip */
+            }
+        }
+    }
+    catch {
+        /* dir unreadable — skip */
+    }
+}
+//# sourceMappingURL=hookcache.js.map

package/dist/integrations/claudemd.js

@@ -27,16 +27,32 @@ export function renderHunchSection(store, root) {
         "(decisions, bug history, invariants). It currently holds " +
         `**${counts.decisions} decisions, ${counts.bugs} bugs, ${counts.constraints} constraints, ${counts.components} components**.`);
     lines.push("");
-    lines.push("**Before reasoning about or editing this codebase, consult Hunch via the `hunch_*` MCP tools:**");
-    lines.push("- `hunch_why(target)` — why a file/symbol is shaped this way (decisions, bugs, constraints).");
-    lines.push("- `hunch_check_constraints(scope)` — invariants you must not break. **Always run before editing.**");
-    lines.push("- `hunch_get_dependents(symbol)` — blast radius before a change.");
-    lines.push("- `hunch_bug_lineage(symptom_or_symbol)` — has this bug happened before? what was the root cause?");
-    lines.push("- `hunch_query(query)` — free-text search across all of Hunch.");
-    lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task (e.g. \"add an MCP tool\", \"cut a release\").");
-    lines.push("- `hunch_compare(candidates)` — rank N candidate branches/commits by architectural fit (fewest invariant hits).");
-    lines.push("- `hunch_conformance()` — does the code still SATISFY recorded intent? (e.g. `pay` still reaches `verifySession`). Run before a refactor.");
-    lines.push("- `hunch_record_decision(...)` — write back a decision after a non-trivial choice.");
+    lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
+    lines.push("");
+    lines.push("**Orient (session/task start):**");
+    lines.push("- `hunch_context(target_or_task)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
+    lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
+    lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");
+    lines.push("- `hunch now` (CLI) — recent decisions + the live roadmap.");
+    lines.push("");
+    lines.push("**Before designing / choosing an approach:**");
+    lines.push("- `hunch_why(target)` — why a file/symbol is shaped this way (decisions, bugs, constraints) — including what was already REJECTED.");
+    lines.push("- `hunch_current_decision(topic)` — the one live answer for a topic (history + rejected included).");
+    lines.push("- `hunch_bug_lineage(symptom_or_symbol)` — has this failed before? what was the root cause?");
+    lines.push("- `hunch_compare(candidates)` — rank candidate branches/commits by fewest invariant hits.");
+    lines.push("- `hunch_query(query)` — free-text search when nothing above fits.");
+    lines.push("");
+    lines.push("**Before editing:**");
+    lines.push("- `hunch_check_constraints(scope)` and `hunch_get_dependents(symbol)` / `hunch_blast_radius(target)` — invariants in scope + who you'd break. (The pre-edit hook injects this per file automatically; call these for PLANNING breadth.)");
+    lines.push("");
+    lines.push("**Before committing / merging:**");
+    lines.push("- `hunch_conformance()` — does the code still SATISFY recorded intent? Run before and after a refactor.");
+    lines.push("- `hunch_pr_impact(base?)` / `hunch_merge_verdict(...)` — a change's memory surface; would it re-open a closed bug?");
+    lines.push("");
+    lines.push("**After deciding / when corrected:**");
+    lines.push("- `hunch_capture_decision(topic?)` → `hunch_record_decision(...)` — interview first, then write; status `proposed` = roadmap intent (shows in `hunch now`).");
+    lines.push("- `hunch_record_correction(...)` — a human correction becomes an ENFORCED rule (Never Twice), not a one-session memory.");
+    lines.push("- `hunch_timeline(target)` — decision history when investigating how something evolved.");
     const wiki = root ? wikiSummary(root) : null;
     if (wiki) {
         lines.push("");

package/dist/integrations/scaffold.js

@@ -135,6 +135,12 @@ export function installClaudeHooks(root, hookCmd) {
         ...keep(json.hooks.UserPromptSubmit),
         { hooks: [{ type: "command", command: hookCmd }] },
     ];
+    // Orientation at session start: recent decisions + the live roadmap, injected
+    // once, so the agent begins already knowing where the work stands.
+    json.hooks.SessionStart = [
+        ...keep(json.hooks.SessionStart),
+        { 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

@@ -23,6 +23,7 @@ import { formatContext, formatStructure } from "../core/format.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
 import { renderMarkdown, renderImpact, verdict } from "../core/checkreport.js";
+import { nowData, wikiStatus, publicHome, readWikiManifestAt } from "../wiki/wiki.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { liveForTopic, historyForTopic, rejectedForTopic, captureConflicts } from "../core/topics.js";
 import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken } from "../core/capturetoken.js";
@@ -264,9 +265,9 @@ export function buildServer(root) {
     // -- hunch_context (surgical retrieval) -----------------------------------
     server.registerTool("hunch_context", {
         title: "Assemble the minimal relevant Hunch slice for a task",
-        description: "Given a file or symbol you're about to work on, return the MINIMAL relevant memory — invariants to preserve, decisions explaining the design, bug history not to reintroduce, and the blast radius — as a compact brief. Call this FIRST when starting work on something.",
+        description: "Given a file, symbol, or task phrase you're about to work on, return the MINIMAL relevant memory — invariants to preserve, decisions explaining the design, bug history not to reintroduce, and the blast radius — as a compact brief. Call this FIRST when starting work on something. A task phrase that resolves to no file/symbol falls back to the closest graph matches.",
         inputSchema: {
-            target: z.string().describe("A file path or symbol you're about to edit."),
+            target: z.string().describe("A file path, symbol, or task phrase you're about to work on."),
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
             as_of: z.string().optional().describe("Time-travel ref (commit/tag/branch): assemble the slice as it stood then."),
         },
@@ -274,7 +275,65 @@ export function buildServer(root) {
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
             return err(`Could not resolve as_of "${as_of}" to a commit.`);
-        return ok(formatContext(store.assembleContext(target, budget_tokens ?? 1500, { asOf })));
+        const ctx = store.assembleContext(target, budget_tokens ?? 1500, { asOf });
+        // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
+        // used to return an empty brief while the graph held the answer — fall back to
+        // FTS so the assistant always leaves with the closest matches, not a shrug.
+        const empty = !ctx.constraints.length && !ctx.decisions.length && !ctx.bugs.length && !ctx.blast_radius.length;
+        if (empty && !asOf) {
+            const hits = store.search(target, 8);
+            if (hits.length) {
+                const lines = hits.map((h) => `• ${h.ref} — ${h.title}\n    ${h.snippet}`);
+                return ok(`No file/symbol resolves for "${target}" — closest graph matches instead:\n\n${lines.join("\n")}\n\n(For a file/symbol brief pass a concrete target; free-text goes through the same search as hunch_query.)`);
+            }
+        }
+        return ok(formatContext(ctx));
+    });
+    // -- hunch_now (the hot view: recent activity + roadmap) --------------------
+    // PUBLIC store only, per dec_29eff08c69's jurisdiction rule: an assistant may
+    // paste this anywhere, so it must be publishable by construction. Union view
+    // stays behind `hunch now --private` on the local terminal.
+    server.registerTool("hunch_now", {
+        title: "Recent activity + the roadmap (the hot view)",
+        description: "What just happened and what's next, straight from the graph: the last N decisions (any status — a supersession IS activity) and the ROADMAP (every live human-vouched PROPOSED decision). Call at session start to orient, or before planning what to work on. Same data as the wiki's now.md. Public store only.",
+        inputSchema: {
+            recent_limit: z.number().optional().describe("How many recent decisions to include (default 10)."),
+        },
+    }, async ({ recent_limit }) => {
+        const { recent, roadmap, pendingReview } = nowData(store.json.loadAll("decisions"), recent_limit ?? 10);
+        const L = [`🔥 Recent (${recent.length}):`];
+        for (const r of recent)
+            L.push(`  ${r.date} [${r.status}] ${r.title} (${r.id}${r.topic ? `, ${r.topic}` : ""})`);
+        L.push("", `🗺 Roadmap — live proposed decisions (${roadmap.length}):`);
+        if (!roadmap.length)
+            L.push("  (empty — record intent as a PROPOSED decision and it appears here)");
+        for (const r of roadmap)
+            L.push(`  • ${r.title} (${r.id}${r.topic ? `, ${r.topic}` : ""}, since ${r.date})\n      ${r.note}`);
+        if (pendingReview > 0)
+            L.push("", `${pendingReview} auto-drafted proposal(s) awaiting review — \`hunch review\`.`);
+        return ok(L.join("\n"));
+    });
+    // -- hunch_wiki_status (generated-wiki freshness) ---------------------------
+    server.registerTool("hunch_wiki_status", {
+        title: "Freshness of the generated wiki (public home)",
+        description: "Which generated wiki pages are fresh vs stale (graph moved, source doc changed, hand-edited), plus the specs ledger's doc grades. Call before trusting wiki pages or when deciding whether `hunch wiki --heal` is needed. Public home only — the private overlay wiki is a local concern.",
+        inputSchema: {},
+    }, async () => {
+        const home = publicHome(root);
+        if (!readWikiManifestAt(home.manifestPath))
+            return ok("No wiki adopted in this repo (no wiki manifest). Generate one with `hunch wiki`.");
+        const s = wikiStatus(store, home, root);
+        const stale = [...s.entries.filter((e) => e.state !== "fresh").map((e) => `${e.page} — ${e.reason || e.state}`),
+            ...(s.specs.state !== "fresh" ? [`${s.specs.page} — doc grade snapshot moved`] : []),
+            ...(s.now.state !== "fresh" ? [`${s.now.page} — activity/roadmap moved`] : []),
+            ...(s.index.state !== "fresh" ? [`${s.index.page} — index inputs moved`] : []),
+            ...s.adoptions.filter((a) => a.state !== "fresh").map((a) => `${a.page} — adopted copy of ${a.doc.rel} (${a.state})`)];
+        const grades = { grounded: s.docs.filter((d) => d.status === "grounded").length, stale: s.docs.filter((d) => d.status === "stale").length, unverified: s.docs.filter((d) => d.status === "unverified").length };
+        const head = `Wiki "${home.dir}/": ${s.entries.length} component page(s), ${s.adoptions.length} adopted doc(s). Docs graded: ${grades.grounded} grounded / ${grades.stale} stale / ${grades.unverified} unverified.`;
+        if (!stale.length && !s.orphans.length && !s.adoptionOrphans.length)
+            return ok(`${head}\n✓ Everything fresh.`);
+        const orphans = [...s.orphans, ...s.adoptionOrphans].map((p) => `${p} — orphaned (heal removes it)`);
+        return ok(`${head}\n${[...stale, ...orphans].map((l) => `· ${l}`).join("\n")}\nHeal: \`hunch wiki --heal\`.`);
     });
     // -- hunch_timeline (decision history) ------------------------------------
     server.registerTool("hunch_timeline", {
@@ -441,7 +500,7 @@ export function buildServer(root) {
                 ? " [via capture front door]"
                 : capture_token
                     ? ""
-                    : "\n\n⚠ Recorded WITHOUT a capture interview. Prefer /capture (hunch_capture_decision), which grills the decision to a resolved state before writing — the graph should hold a well-examined decision, not a guess. (A future major version will require a capture token here.)";
+                    : `\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.)`;
             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

package/dist/store/hunchStore.js

@@ -20,6 +20,7 @@ import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { gitCommonDir } from "../extractors/git.js";
 import { pathMatchesGlob } from "../core/glob.js";
+import { currentForTopic } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
 import { effectiveForbids, matchForbids } from "../core/constraintmatch.js";
@@ -270,8 +271,10 @@ export class HunchStore {
         return { counts };
     }
     // ---- read path ----------------------------------------------------------
-    /** FTS5 ranked search (hunch_query). Falls back to LIKE if the query has no
-     *  FTS-tokenizable terms. */
+    /** FTS5 ranked search — the RAW bm25 primitive, no priors. Callers wanting
+     *  relevance ordering (liveness/provenance/recency + topic-chain promotion)
+     *  go through hybridSearch/searchScoped, where rerankByPriors applies.
+     *  Falls back to LIKE if the query has no FTS-tokenizable terms. */
     search(query, limit = 12) {
         const match = toFtsQuery(query);
         // No FTS-tokenizable terms (e.g. a CJK-only query) — degrade to LIKE rather
@@ -369,6 +372,98 @@ export class HunchStore {
         }
         return { embedded, skipped: docs.length - todo.length, total: docs.length };
     }
+    /** Post-fusion rerank by graph PRIORS (dec_25e277f479): relevance ordering, not
+     *  just reachability. Rank-based blend — blended(i) = 1/(60+i) × liveness ×
+     *  provenance × recency — so bm25's negative scale never leaks in. Priors are
+     *  BOUNDED (a superseded or ancient record dims, never disappears): liveness 0.6
+     *  for superseded/retired/rejected, provenance 1.0 / 0.85 / 0.75 for
+     *  human_confirmed / llm_draft / extracted-inferred, recency 0.7 + 0.3·½^(age/90d).
+     *  Runbook trigger phrases matching the query boost ×1.5 (exact intent beats
+     *  keyword luck). Structural refs (symbols/components/edges) stay neutral.
+     *  Deterministic; ties keep fused order (stable sort). */
+    rerankByPriors(hits, limit, query) {
+        if (!hits.length)
+            return hits; // a SINGLE hit still runs — topic-chain promotion must fire for the lone stale match
+        const now = Date.now();
+        const q = query?.toLowerCase();
+        // Topic-chain promotion: for every superseded decision in the pool whose topic
+        // has a live successor NOT already in the pool, inject the successor at the
+        // predecessor's rank — the reader asked about the topic, and the graph's one
+        // live answer must be reachable even when only history matches lexically.
+        const present = new Set(hits.map((h) => h.ref));
+        // Each candidate carries its BASE rank position; an injected successor
+        // inherits its predecessor's position (× a hair under, so an exact-match
+        // live record already in the pool is never displaced by an injection).
+        const pool = hits.map((h, i) => ({ h, base: 1 / (60 + i) }));
+        for (const [i, h] of hits.entries()) {
+            if (h.kind !== "decisions")
+                continue;
+            const d = this.recs("decisions").find((x) => x.id === h.ref);
+            if (!d?.topic || !(d.status === "superseded" || d.superseded_by))
+                continue;
+            const cur = currentForTopic(this.recs("decisions"), d.topic);
+            if (!cur || cur.id === h.ref || present.has(cur.id))
+                continue;
+            present.add(cur.id);
+            pool.push({
+                h: { ref: cur.id, kind: "decisions", title: cur.title, snippet: `current for topic "${d.topic}" (supersedes ${h.ref})`, score: h.score },
+                base: (1 / (60 + i)) * 0.98,
+            });
+        }
+        const scored = pool.map(({ h, base }) => {
+            const m = this.priorMeta(h.ref, h.kind);
+            let w = 1;
+            if (m) {
+                if (m.dead)
+                    w *= 0.6;
+                w *= m.provenance.includes("human_confirmed") ? 1 : 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))
+                        w *= 0.7 + 0.3 * Math.pow(0.5, ageDays / 90);
+                }
+                if (q && m.triggers?.some((tr) => q.includes(tr) || tr.includes(q)))
+                    w *= 1.5;
+            }
+            return { h, s: base * w };
+        });
+        scored.sort((a, b) => b.s - a.s);
+        return scored.slice(0, limit).map((x) => x.h);
+    }
+    /** The prior-bearing metadata for a hit: liveness, provenance, effective date,
+     *  and (runbooks) trigger phrases. null = structural ref, neutral prior. */
+    priorMeta(ref, kind) {
+        if (kind === "decisions") {
+            const d = this.recs("decisions").find((x) => x.id === ref);
+            if (!d)
+                return null;
+            return {
+                dead: d.status === "superseded" || d.status === "rejected" || !!d.superseded_by || !!d.valid_to,
+                provenance: d.provenance.source,
+                at: d.valid_from ?? d.date,
+            };
+        }
+        if (kind === "runbooks") {
+            const r = this.recs("runbooks").find((x) => x.id === ref);
+            if (!r)
+                return null;
+            return { dead: !!r.valid_to, provenance: r.provenance.source, at: r.valid_from ?? r.date, triggers: r.trigger.map((x) => x.toLowerCase()) };
+        }
+        if (kind === "constraints") {
+            const c = this.recs("constraints").find((x) => x.id === ref);
+            if (!c)
+                return null;
+            return { dead: c.status === "retired" || !!c.valid_to, provenance: c.provenance.source, at: c.valid_from };
+        }
+        if (kind === "bugs") {
+            const b = this.recs("bugs").find((x) => x.id === ref);
+            if (!b)
+                return null;
+            // A fixed bug is not "dead" — lineage is the point of keeping it findable.
+            return { dead: false, provenance: b.provenance.source };
+        }
+        return null;
+    }
     /** Hybrid search (hunch_query / `hunch query --semantic`): FTS bm25 fused with
      *  cosine over stored embeddings via Reciprocal Rank Fusion. Degrades to pure
      *  sync FTS (zero added latency) when there's no embedder or no vectors yet, so
@@ -402,8 +497,9 @@ export class HunchStore {
         // zero-fusion-overhead fast path is preserved.
         const graph = this.graphExpand([...fts, ...sem], 50, gw);
         if (!sem.length && !graph.length)
-            return fts.slice(0, limit);
-        return this.rrfFuse(fts, sem, graph, limit, gw);
+            return this.rerankByPriors(fts, limit, query);
+        // Fuse with headroom so the prior rerank can promote from below the cut line.
+        return this.rerankByPriors(this.rrfFuse(fts, sem, graph, Math.max(limit, 24), gw), limit, query);
     }
     /** Runbook-scoped retrieval (roadmap #5): the same FTS+graph(+semantic) fusion,
      *  restricted to the `runbooks` kind — so a "what's the procedure for X" query
@@ -433,8 +529,8 @@ export class HunchStore {
             }
         }
         if (!sem.length)
-            return fts.slice(0, limit);
-        return this.rrfFuse(fts, sem, [], limit);
+            return this.rerankByPriors(fts, limit, query);
+        return this.rerankByPriors(this.rrfFuse(fts, sem, [], Math.max(limit, 20)), limit, query);
     }
     /** FTS bm25 over a single kind (the `kind` column is UNINDEXED, so a plain `=`
      *  constraint composes with MATCH). Empty when the query has no FTS-able terms. */

package/dist/synthesis/synthesize.js

@@ -2,6 +2,7 @@ import { commitMeta, commitDiff, headSha, currentBranch } from "../extractors/gi
 import { analyzeDiff } from "../extractors/diff.js";
 import { selectProvider, selectEnsemble, selectVerifier, verifyDecisionSafe, DeterministicProvider } from "./provider.js";
 import { decisionId, bugId, constraintId } from "../core/ids.js";
+import { commitCoveredBy } from "../core/dupdetect.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { draftTripwires, knownRepoDeps } from "./tripwires.js";
 const CODE_RE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
@@ -61,6 +62,19 @@ export async function syncCommit(store, root, sha, opts = {}) {
             decision: existing,
         };
     }
+    // Duplicate-factory gate (deterministic, pre-LLM): the human recorded this
+    // choice via MCP minutes-to-days ago (commit: null, different id), and now the
+    // post-commit hook would re-draft the same content under a commit-keyed id —
+    // review triage measured 7 of 14 queued drafts as exactly this. A recent
+    // human-confirmed decision claiming this commit's files → skip the draft (and
+    // the subscription call). Recency-windowed; --force overrides.
+    const covered = commitCoveredBy(codeFiles, meta.subject, store.recs("decisions"), Date.now());
+    if (covered && !opts.force) {
+        return {
+            status: "skipped",
+            reason: `already covered by ${covered.id} — "${covered.title}" (recorded ${covered.hoursAgo}h ago, claims ${covered.fileOverlapPct}% of this commit's files; --force to draft anyway)`,
+        };
+    }
     const diff = commitDiff(target, root);
     const analysis = analyzeDiff(diff);
     // Significance gate: reserve the paid LLM for substantive commits; trivial ones

package/dist/wiki/adopt.js

@@ -55,8 +55,34 @@ export function adoptionHash(content, decisions, doc) {
         .update(JSON.stringify({ content, topical, issues: doc.issues }))
         .digest("hex").slice(0, 16);
 }
-/** Render the wiki-managed copy of a stale doc, healed against the graph. */
-export function renderAdoptedDoc(doc, content, decisions) {
+/** Prompt for the optional PROSE-HEAL tier (dec roadmap.adoption-prose-heal):
+ *  a subscription-CLI rewrite of what the stale doc SHOULD say now. The output
+ *  is garnish on the deterministic skeleton — never hashed, never a substitute
+ *  for the graph corrections rendered below it. */
+export function adoptProsePrompt(doc, content, decisions) {
+    const topical = doc.topics
+        .map((t) => {
+        const cur = currentForTopic(decisions, t);
+        return cur ? `topic "${t}" → CURRENT decision ${cur.id} — ${cur.title}: ${clip(cur.decision, 400)}` : null;
+    })
+        .filter((x) => !!x);
+    return `You are the documentation engine of an Engineering Memory OS. A repo doc went STALE
+against the decision graph. Write the short RECONCILED version: what this doc should say NOW,
+grounded ONLY in the current decisions below — never invent behavior, cite decision ids inline
+like (dec_xxx). Plain markdown paragraphs, no headings or lists, 100-180 words.
+
+## The stale doc (${doc.rel})
+${content.slice(0, 4000)}
+
+## Current decisions for its topics
+${topical.join("\n") || "(none — the doc is stale for non-pin reasons: " + doc.issues.join("; ") + ")"}
+
+Write the reconciled version now.`;
+}
+/** Render the wiki-managed copy of a stale doc, healed against the graph.
+ *  `reconciled` (optional, LLM prose-heal) slots in under the banner; the
+ *  deterministic corrections below remain the authoritative layer. */
+export function renderAdoptedDoc(doc, content, decisions, reconciled = null) {
     const byId = new Map(decisions.map((d) => [d.id, d]));
     const lines = content.split("\n");
     const out = [];
@@ -67,6 +93,9 @@ export function renderAdoptedDoc(doc, content, decisions) {
     for (const i of doc.issues)
         out.push(`> - ${i}`);
     out.push("");
+    if (reconciled) {
+        out.push("## 🩹 Reconciled overview", "", reconciled.trim(), "", "_LLM-drafted from the current decisions (subscription); the graph corrections below are the deterministic, authoritative layer._", "");
+    }
     const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     for (const raw of lines) {
         // Heal EVERY stale pin on the line, and only inside its own marker — a bare

package/dist/wiki/wiki.js

@@ -79,7 +79,7 @@ const SEV = { blocking: 3, warning: 2, advisory: 1, critical: 4, high: 3, medium
  *  the leak boundary: "public" reads the committed store only; "all" unions the
  *  private overlay and must only ever feed a PRIVATE home's pages. `repoDocs`
  *  (pre-scanned specs) associate by the src files they mention. */
-export function assemblePack(store, component, source = "public", repoDocs = [], adoptedPageByRel = new Map()) {
+export function assemblePack(store, component, source = "public", repoDocs = [], adoptedPageByRel = new Map(), slugById = new Map()) {
     const read = (kind) => (source === "all" ? store.recs(kind) : store.json.loadAll(kind));
     const prefixes = component.paths.map(globPrefix);
     const symbols = read("symbols")
@@ -121,7 +121,7 @@ export function assemblePack(store, component, source = "public", repoDocs = [],
         if (e.to === component.id && componentsById.has(e.from) && e.from !== component.id)
             usedBy.set(e.from, componentsById.get(e.from).name);
     }
-    const rel = (m) => [...m].map(([id, name]) => ({ id, name })).sort((a, b) => a.id.localeCompare(b.id));
+    const rel = (m) => [...m].map(([id, name]) => ({ id, name, slug: slugById.get(id) ?? null })).sort((a, b) => a.id.localeCompare(b.id));
     const docs = repoDocs
         .filter((doc) => doc.srcRefs.some((f) => owns(prefixes, f)))
         .map((doc) => ({ path: doc.rel, title: doc.title, status: doc.status, adopted: adoptedPageByRel.get(doc.rel) ?? null }));
@@ -163,7 +163,7 @@ export function slugFor(name, id, taken) {
     let slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || id;
     // "readme" and "specs" are reserved page names (index + specs ledger); the
     // id-suffix itself can collide with a literal name, so loop until unique.
-    if (slug === "readme" || slug === "specs" || taken.has(slug))
+    if (slug === "readme" || slug === "specs" || slug === "now" || taken.has(slug))
         slug = `${slug}-${id.replace(/^cmp_/, "").slice(0, 6)}`;
     while (taken.has(slug))
         slug = `${slug}-x`;
@@ -174,7 +174,7 @@ const DOC_BADGE = { grounded: "✅ grounded", stale: "⚠ stale", unverified: "
 /** `docsLinkable`: pages in the MAIN repo can relative-link ../<doc>; a private
  *  home's pages live in the OVERLAY repo where those paths don't resolve, so
  *  they render doc paths as plain text instead. */
-export function renderPage(pack, prose, slugById, docsLinkable = true) {
+export function renderPage(pack, prose, docsLinkable = true) {
     const c = pack.component;
     const L = [];
     L.push(`<!-- hunch:wiki ${c.id} — GENERATED from the Hunch graph by \`hunch wiki\`; the graph is the source of truth. Edit records (/capture, hunch_record_decision), then \`hunch wiki --heal\` — do not edit this page by hand. -->`);
@@ -229,7 +229,7 @@ export function renderPage(pack, prose, slugById, docsLinkable = true) {
     }
     if (pack.dependsOn.length || pack.usedBy.length) {
         L.push("## Relations", "");
-        const link = (r) => { const s = slugById.get(r.id); return s ? `[${r.name}](${s}.md)` : r.name; };
+        const link = (r) => (r.slug ? `[${r.name}](${r.slug}.md)` : r.name);
         if (pack.dependsOn.length)
             L.push(`- Depends on: ${pack.dependsOn.map(link).join(", ")}`);
         if (pack.usedBy.length)
@@ -262,6 +262,7 @@ export function renderIndex(entries, repoWide, home, docs = []) {
         const n = (s) => docs.filter((d) => d.status === s).length;
         L.push("", `📄 [Specs & docs ledger](specs.md) — ${docs.length} repo doc(s): ${n("grounded")} grounded, ${n("stale")} stale, ${n("unverified")} unverified.`);
     }
+    L.push("", "🔥 [Now — recent activity & roadmap](now.md)");
     if (repoWide.length) {
         L.push("", "## Repo-wide invariants", "");
         for (const k of repoWide)
@@ -340,8 +341,58 @@ export function wikiSummary(root) {
 const SPECS_ID = "_specs";
 /** Reserved manifest component id for the README index page. */
 const INDEX_ID = "_index";
+/** Reserved manifest component id for the NOW page (activity ledger + roadmap). */
+const NOW_ID = "_now";
 /** Manifest component-id prefix for adopted (wiki-managed) doc copies. */
 const ADOPTED_PREFIX = "doc:";
+/** The hot view's inputs: last `recentLimit` decisions by date (any status — a
+ *  supersession IS activity), and every live PROPOSED decision (the roadmap:
+ *  record intent as a proposed decision; accepting or superseding it removes it
+ *  from the roadmap with zero file maintenance). Home-scoped like every read. */
+export function nowData(decisions, recentLimit = 10) {
+    const clip1 = (s) => (s.length > 220 ? s.slice(0, 219).trimEnd() + "…" : s).replace(/\s*\n\s*/g, " ");
+    const byDateDesc = (a, b) => (b.valid_from ?? b.date).localeCompare(a.valid_from ?? a.date) || a.id.localeCompare(b.id);
+    const recent = [...decisions].sort(byDateDesc).slice(0, recentLimit)
+        .map((d) => ({ id: d.id, topic: d.topic, title: d.title, status: d.status, date: (d.valid_from ?? d.date).slice(0, 10), note: clip1(d.decision) }));
+    // Roadmap = INTENT the human vouched for. Auto-synthesized drafts are also
+    // status "proposed", but they describe work already done and belong to the
+    // review queue (`hunch review`) — surfacing them here would bury real plans.
+    const live = decisions.filter((d) => d.status === "proposed" && !d.superseded_by && !d.valid_to);
+    const vouched = live.filter((d) => d.provenance.source.includes("human_confirmed"));
+    const roadmap = vouched
+        .sort(byDateDesc)
+        .map((d) => ({ id: d.id, topic: d.topic, title: d.title, status: d.status, date: (d.valid_from ?? d.date).slice(0, 10), note: clip1(d.context || d.decision) }));
+    return { recent, roadmap, pendingReview: live.length - vouched.length };
+}
+/** The hot file — a DERIVED view like every other page: what just happened
+ *  (last N decisions) and what's next (live proposed decisions). No topic pins
+ *  by design: ledger entries going stale is history, not drift — the freshness
+ *  hash alone re-renders the page when the graph moves. */
+export function renderNowPage(recent, roadmap, home, pendingReview = 0) {
+    const L = [];
+    L.push("<!-- hunch:wiki _now — GENERATED activity ledger + roadmap by `hunch wiki`; do not edit by hand. Roadmap items are PROPOSED decisions — record intent with /capture (status: proposed); shipping it (accept/supersede) removes it here automatically. -->");
+    L.push("# Now — recent activity & roadmap", "");
+    if (home.kind === "private")
+        L.push("> ⚠ **PRIVATE** — includes overlay records; do not publish.", "");
+    L.push("## 🔥 Recent", "");
+    if (!recent.length)
+        L.push("_No decisions recorded yet._", "");
+    for (const r of recent)
+        L.push(`- ${r.date} · **${r.title}** — ${r.note || "(no decision text)"} _(${r.id}${r.topic ? `, topic \`${r.topic}\`` : ""}, ${r.status})_`);
+    if (recent.length)
+        L.push("");
+    L.push("## 🗺 Roadmap — live proposed decisions", "");
+    if (!roadmap.length)
+        L.push("_Empty. Record what's next as a PROPOSED decision (`/capture`, status: proposed) and it appears here._", "");
+    for (const r of roadmap)
+        L.push(`- **${r.title}** — ${r.note || "(no context)"} _(${r.id}${r.topic ? `, topic \`${r.topic}\`` : ""}, since ${r.date})_`);
+    if (roadmap.length)
+        L.push("");
+    if (pendingReview > 0)
+        L.push(`_${pendingReview} auto-drafted proposed decision(s) awaiting review are not shown — triage with \`hunch review\`._`, "");
+    L.push("---", "", "_Derived from the decision graph — regen: `hunch wiki --heal`. Ship a roadmap item by accepting/superseding its decision; never edit this page._", "");
+    return L.join("\n");
+}
 const sha16 = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
 /** The one freshness state machine every generated artifact goes through:
  *  unknown/mismatched manifest entry → new; input hash moved → stale; file
@@ -394,10 +445,14 @@ export function wikiStatus(store, home, srcRoot) {
         adoptions.push({ doc, content, page, hash, state });
     }
     const adoptedPageByRel = new Map(adoptions.map((a) => [a.doc.rel, a.page.slice(home.dir.length + 1)]));
+    // Slugs FIRST (single authority): packs embed their relations' slugs, so the
+    // freshness hash covers cross-page links — a sibling rename re-renders every
+    // page that links to it instead of leaving a fresh page pointing at a ghost.
     const taken = new Set();
+    const slugById = new Map(components.map((c) => [c.id, slugFor(c.name, c.id, taken)]));
     const entries = components.map((c) => {
-        const pack = assemblePack(store, c, home.source, docs, adoptedPageByRel);
-        const slug = slugFor(c.name, c.id, taken);
+        const pack = assemblePack(store, c, home.source, docs, adoptedPageByRel, slugById);
+        const slug = slugById.get(c.id);
         const page = `${home.dir}/${slug}.md`;
         const hash = packHash(pack);
         const { state, reason } = pageState(home, page, c.id, hash, manifest?.pages[page]);
@@ -424,11 +479,16 @@ export function wikiStatus(store, home, srcRoot) {
         docs: { grounded: docs.filter((d) => d.status === "grounded").length, stale: docs.filter((d) => d.status === "stale").length, unverified: docs.filter((d) => d.status === "unverified").length, total: docs.length },
     })));
     const index = { page: indexPage, hash: indexHash, state: pageState(home, indexPage, INDEX_ID, indexHash, manifest?.pages[indexPage]).state };
+    // The NOW page: recent activity + live proposed decisions (the roadmap).
+    const { recent, roadmap, pendingReview } = nowData(decisions);
+    const nowPage = `${home.dir}/now.md`;
+    const nowHash = sha16(JSON.stringify(canonical({ recent, roadmap, pendingReview })));
+    const now = { page: nowPage, hash: nowHash, state: pageState(home, nowPage, NOW_ID, nowHash, manifest?.pages[nowPage]).state, recent, roadmap, pendingReview };
     // Orphans by PAGE KEY, not component id: anything the manifest tracks that no
     // current artifact claims (deleted component, renamed component whose slug
     // moved, a retired adoption) gets removed on heal — nothing generated is ever
     // stranded on disk while the manifest forgets it.
-    const expected = new Set([...entries.map((e) => e.page), ...adoptions.map((a) => a.page), specsPage, indexPage]);
+    const expected = new Set([...entries.map((e) => e.page), ...adoptions.map((a) => a.page), specsPage, indexPage, nowPage]);
     const orphans = [];
     const adoptionOrphans = [];
     for (const [page, p] of Object.entries(manifest?.pages ?? {})) {
@@ -436,7 +496,7 @@ export function wikiStatus(store, home, srcRoot) {
             continue;
         (p.component.startsWith(ADOPTED_PREFIX) ? adoptionOrphans : orphans).push(page);
     }
-    return { home, entries, docs, adoptions, adoptionOrphans, decisions, specs, index, repoWide, orphans };
+    return { home, entries, docs, adoptions, adoptionOrphans, decisions, specs, index, now, repoWide, orphans };
 }
 /** Read short excerpts of the component's heaviest files as LLM grounding.
  *  Source files always live in the MAIN repo (`srcRoot`), even for the private
@@ -468,8 +528,8 @@ export async function generateWiki(store, srcRoot, home, opts) {
     const targets = status.entries.filter((e) => opts.only === "all" || e.state !== "fresh");
     const specsTarget = opts.only === "all" || status.specs.state !== "fresh";
     const indexTarget = opts.only === "all" || status.index.state !== "fresh";
+    const nowTarget = opts.only === "all" || status.now.state !== "fresh";
     const log = opts.log ?? (() => { });
-    const slugById = new Map(status.entries.map((e) => [e.pack.component.id, e.slug]));
     const written = [];
     /** Written-bytes ledger — the hand-edit tripwire recorded per page. */
     const bytesByPage = new Map();
@@ -489,7 +549,7 @@ export async function generateWiki(store, srcRoot, home, opts) {
                 prose = null; // template-only page; never fail generation on a CLI hiccup
             }
         }
-        put(e.page, renderPage(e.pack, prose, slugById, home.kind === "public"));
+        put(e.page, renderPage(e.pack, prose, home.kind === "public"));
         log(`  ✎ ${e.page}${e.state === "fresh" ? "" : ` (${e.state})`}${prose ? "" : " [template]"}`);
     }
     if (specsTarget) {
@@ -502,8 +562,21 @@ export async function generateWiki(store, srcRoot, home, opts) {
     if (adoptionTargets.length)
         mkdirSync(join(home.pagesRoot, home.dir, "docs"), { recursive: true });
     for (const a of adoptionTargets) {
-        put(a.page, renderAdoptedDoc(a.doc, a.content, status.decisions));
-        log(`  ✚ ${a.page}${a.state === "fresh" ? "" : ` (${a.state})`} [adopted from ${a.doc.rel}]`);
+        let reconciled = null;
+        if (opts.adoptionProse) {
+            try {
+                reconciled = await opts.adoptionProse(a.doc, a.content);
+            }
+            catch {
+                reconciled = null; // deterministic copy; a CLI hiccup never fails adoption
+            }
+        }
+        put(a.page, renderAdoptedDoc(a.doc, a.content, status.decisions, reconciled));
+        log(`  ✚ ${a.page}${a.state === "fresh" ? "" : ` (${a.state})`} [adopted from ${a.doc.rel}]${reconciled ? " [prose-healed]" : ""}`);
+    }
+    if (nowTarget) {
+        put(status.now.page, renderNowPage(status.now.recent, status.now.roadmap, home, status.now.pendingReview));
+        log(`  ✎ ${status.now.page}${status.now.state === "fresh" ? "" : ` (${status.now.state})`} [${status.now.recent.length} recent, ${status.now.roadmap.length} roadmap]`);
     }
     if (indexTarget) {
         put(status.index.page, renderIndex(status.entries.map((e) => ({ pack: e.pack, slug: e.slug })), status.repoWide, home, status.docs));
@@ -537,6 +610,7 @@ export async function generateWiki(store, srcRoot, home, opts) {
             entry(a.page, `${ADOPTED_PREFIX}${a.doc.rel}`, a.hash, a.state);
         entry(status.specs.page, SPECS_ID, status.specs.hash, status.specs.state);
         entry(status.index.page, INDEX_ID, status.index.hash, status.index.state);
+        entry(status.now.page, NOW_ID, status.now.hash, status.now.state);
         writeWikiManifestAt(home.manifestPath, { version: 1, dir: home.dir, pages });
     }
     return { written, removed, unchanged: status.entries.length - targets.length };
@@ -582,6 +656,13 @@ export function computeWikiDrift(store, root) {
                 detail: `the index's inputs moved (component set/names, repo-wide invariants, or doc counts) — regenerate with \`${heal}\`${where}`,
             });
         }
+        if (status.now.state !== "fresh") {
+            findings.push({
+                kind: "wiki-stale",
+                id: status.now.page,
+                detail: `the activity ledger / roadmap moved (a decision was recorded, accepted, or superseded) — regenerate with \`${heal}\`${where}`,
+            });
+        }
         for (const a of status.adoptions) {
             if (a.state === "fresh")
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "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).",