@davesheffer/hunch 1.42.0 → 1.44.0

package/README.md

@@ -12,6 +12,10 @@ Hunch keeps that record in Git and makes the relevant parts available to your ag
 
 The goal is simple: agents working from the same maintained record, with sources they can inspect. Hunch supplies memory and checks; the assistant still does the work.
 
+[![Watch: Hunch Memory in 2 minutes](https://img.youtube.com/vi/m2PM6pV7D9Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=m2PM6pV7D9Y)
+
+▶ **[Watch Hunch Memory in 2 minutes](https://www.youtube.com/watch?v=m2PM6pV7D9Y)**, then the [7-episode series](https://www.youtube.com/playlist?list=PLIXqtdE0LcNI) on setup, hooks, memory capture, delivery, rules, drift and teams.
+
 ## Start with your coding assistant
 
 Requires **Node 22.13+** and a Git repository.
@@ -102,6 +106,16 @@ hunch integrations check --harness codex --require context
 
 The first command checks configuration. The probe starts a fresh MCP process and reads memory. The context check requires observed hook delivery on the expected version, so run it after the new assistant session begins. `--require` fails when the named capability is not verified; none of these checks proves that a model followed the advice.
 
+## Remove Hunch from a repository
+
+```bash
+hunch uninstall --dry-run   # show what would change
+hunch uninstall             # remove what Hunch installed; keep .hunch/ (your memory)
+hunch uninstall --purge     # also delete .hunch/, the derived cache and Hunch's .gitignore blocks
+```
+
+It removes the instruction blocks, MCP entries, agent and git hooks, merge driver, slash commands and CI workflow that Hunch installed, and leaves your own content in those files alone. If a file it needs to edit can't be parsed, it changes nothing and says which file. It writes `.hunch-removed`: while that file exists, no Hunch command sets Hunch up here again. Commit it so every clone stays opted out; to reinstall, delete it and run `hunch init`. Close running `hunch mcp` / `hunch serve` processes first, so they can't recreate files.
+
 ## See what Hunch contributed
 
 Task reports answer: what memory reached this task, what did the agent say it used, and what checks actually ran?

package/dist/cli/index.js

@@ -43,7 +43,8 @@ import { isParserLoadError, loadNativeTreeSitter } from "../extractors/nativeTre
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
-import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, firstCommitForFile, stagedFiles, workingFiles, commitFiles, asOfDate, stagedGateDiff, workingGateDiff, commitGateDiff, rangeFiles, rangeGateDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunchStatus, syncExistingHunch, gitUntrackCached, gitCommonDir, checkoutCommonDir, separateGitDirCandidate, separateGitDirLink, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges, commitRepairStatus, mergeRangeChanges, commitsExist } from "../extractors/git.js";
+import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, firstCommitForFile, stagedFiles, workingFiles, commitFiles, asOfDate, stagedGateDiff, workingGateDiff, commitGateDiff, rangeFiles, rangeGateDiff, rangeCommits, revExists, revParse, commitAndPushHunch, pullHunchStatus, syncExistingHunch, gitUntrackCached, gitCommonDir, checkoutCommonDir, separateGitDirCandidate, separateGitDirLink, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges, commitRepairStatusAgainst, commitPatchIds, mergeRangeChanges, commitsExist } from "../extractors/git.js";
+import { runbookDraft } from "../core/runbookDraft.js";
 import { parseMemoryLog } from "../core/memorylog.js";
 import { renamesOf, planRepair, repairDecision, repairConstraint } from "../core/repair.js";
 import { orphanedCommitDecisions, planCommitRepair, repairDecisionCommit, pickRewrite, commitRepairReviewHash, mergeRewrites, firstFor, deadRewrites, resolvedRewriteIds, withoutDropped, addDropped, withheldForUnresolvableTo } from "../core/commitrepair.js";
@@ -61,6 +62,7 @@ import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, share
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS, upgradeManagedGitignore, describeGitignoreUpgrade } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
+import { applyUninstall, formatUninstallPlan, isOptedOut, OPT_OUT_FILE, optOutMessage, planUninstall } from "../integrations/uninstall.js";
 import { updateClaudeMd, renderHunchSection } from "../integrations/claudemd.js";
 import { HOOK_REMINDER } from "../core/hookText.js";
 import { measureFootprint } from "../core/footprint.js";
@@ -91,12 +93,13 @@ import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpol
 import { isHumanConfirmed } from "../core/strictgate.js";
 import { appendEvent, readEvents } from "../core/events.js";
 import { computeStats, formatStats } from "../core/stats.js";
-import { injectionMode, resetSessionInjections } from "../core/hookcache.js";
+import { clearTaskSelection, injectionMode, loadTaskSelection, resetSessionInjections, saveTaskSelection, taskSelectionEnabled } from "../core/hookcache.js";
+import { isBareFollowUp, isFilterableSelectionId, liveSelectionRecords, selectForTask } from "../core/taskSelection.js";
 import { recordServed, servedSummary } from "../core/served.js";
-import { recordTaskDelivery, reportActivity, reportHash, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
+import { readTaskReport, recordTaskDelivery, reportActivity, reportHash, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
 import { snapshotDeliveredRecords } from "../core/taskReportEvidence.js";
 import { renderRecalledLine } from "../core/taskReportRender.js";
-import { closeHookTask, hookReportTaskId, nativeHookCwd, settleHookSession, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
+import { closeHookTask, hookReportTaskId, isNotificationPrompt, nativeHookCwd, settleHookSession, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
 import { persistTaskRecord } from "../core/taskRecord.js";
 import { recordHookObservation } from "../core/hookObservations.js";
 import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
@@ -217,6 +220,26 @@ registerReviewMemoryCommands(program, (records, repository, privateOnly) => {
     return { root, existing: store.captureHome(privateOnly) === "private"
             ? store.recs("constraints") : store.json.loadAll("constraints") };
 });
+// Opt-out gate (#449): a repository `hunch uninstall` opted out stays out. Setup
+// and every other command refuse; the commands a leftover git or agent hook may
+// still call exit 0 so they never break the user's commit, merge or agent turn
+// (`hook` silently: its stdout is the agent's context). The merge drivers still
+// run: a leftover driver that exits without writing %A would let git drop `theirs`.
+const OPT_OUT_ALLOWED = new Set(["uninstall", "doctor", "help", "merge-driver", "merge-driver-grounding"]);
+const OPT_OUT_QUIET = new Set(["hook", "sync", "check", "grounding", "repair-provenance", "workspaces"]);
+program.hook("preAction", (_thisCommand, actionCommand) => {
+    let top = actionCommand;
+    while (top.parent && top.parent !== program)
+        top = top.parent;
+    const name = top.name();
+    if (OPT_OUT_ALLOWED.has(name))
+        return;
+    if (!isOptedOut(findRoot()))
+        return;
+    if (name !== "hook")
+        console.error(optOutMessage());
+    process.exit(OPT_OUT_QUIET.has(name) ? 0 : 1);
+});
 // Read an already-known update and schedule any registry refresh in a detached
 // worker. No network handle is opened in this command's process, so the
 // advisory cannot delay command completion or process exit.
@@ -509,6 +532,46 @@ program
     console.log("Cold start? Seed from history:  hunch backfill --since 90d");
     console.log("\n⭐ If Hunch earns its keep, a star helps others find it → https://github.com/davesheffer/hunch");
 });
+// ---- uninstall ------------------------------------------------------------
+program
+    .command("uninstall")
+    .description("Remove everything Hunch installed in this repository (instruction blocks, MCP entries, agent and git hooks, merge driver, slash commands, CI workflow) and opt the repository out so Hunch never sets itself up here again. Keeps .hunch/ (your engineering memory) unless --purge.")
+    .option("--dry-run", "print what would change and write nothing")
+    .option("--purge", "also delete .hunch/ (the engineering memory), the derived cache, Hunch's .gitignore blocks and this clone's pointer in the git dir")
+    .action((opts) => {
+    const root = findRoot();
+    const plan = planUninstall(root, { purge: !!opts.purge });
+    if (plan.refused.length) {
+        console.error(`Hunch uninstall at ${root}: nothing was changed — fix the file(s) below, then re-run.`);
+        for (const line of formatUninstallPlan(plan, !!opts.dryRun))
+            console.error(line);
+        process.exitCode = 1;
+        return;
+    }
+    const { applied, failed } = opts.dryRun ? { applied: plan.steps, failed: [] } : applyUninstall(plan);
+    // The header follows what actually ran: a failed opt-out marker stops
+    // everything, and saying "uninstalled" then would be a lie.
+    const header = opts.dryRun ? "Hunch uninstall (dry run — nothing written)"
+        : !failed.length ? "Hunch uninstalled"
+            : applied.some((s) => s.kind !== "keep") ? "Hunch partly uninstalled"
+                : "Hunch uninstall: nothing was changed";
+    console.log(`${header} at ${root}${opts.purge ? " (--purge)" : ""}`);
+    if (!plan.steps.some((s) => s.kind !== "keep"))
+        console.log("  nothing to remove — Hunch is not installed here");
+    for (const line of formatUninstallPlan({ ...plan, steps: applied }, !!opts.dryRun))
+        console.log(line);
+    if (failed.length) {
+        console.error(`
+✗ ${failed.length} step(s) could not be applied — close running Hunch processes (\`hunch mcp\`, \`hunch serve\`, editors using them), then re-run \`hunch uninstall${opts.purge ? " --purge" : ""}\`:`);
+        for (const f of failed)
+            console.error(`  ✗ ${f.path}: ${f.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!opts.dryRun && plan.steps.some((s) => s.path === OPT_OUT_FILE)) {
+        console.log(`\nCommit ${OPT_OUT_FILE} (and the removals) so every clone stays opted out. To reinstall later, delete ${OPT_OUT_FILE} and run \`hunch init\`.`);
+    }
+});
 // ---- index ----------------------------------------------------------------
 program
     .command("index")
@@ -1974,11 +2037,14 @@ program
         store.close();
         return fail(`base ref "${base ?? ""}" not found (range: ${range})`);
     }
-    const steps = rangeSubjects(base, root, head);
-    const files = rangeFiles(base, root, head);
+    // Hunch's own capture commits and store/grounding files are bookkeeping, not steps (#425).
+    const commits = rangeCommits(base, root, head);
+    const { steps, files } = runbookDraft(commits, rangeFiles(base, root, head));
     if (!steps.length && !files.length) {
         store.close();
-        return fail(`no commits or changes in range ${range}`);
+        return fail(commits.length
+            ? `range ${range} only holds Hunch's own capture commits and files; nothing to draft`
+            : `no commits or changes in range ${range}`);
     }
     const now = new Date().toISOString();
     const rec = {
@@ -4108,7 +4174,7 @@ program
     .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard. Also flags (advisory) symbols you add that already exist elsewhere — possible re-implementation/sprawl.")
     .option("--staged", "check git staged files (default)")
     .option("--working", "check all working-tree edits vs HEAD (staged, unstaged, and untracked files)")
-    .option("--commit <sha>", "check a specific commit's files")
+    .option("--commit <sha>", "check a specific commit's files (judged alone, against its parent; use --base to gate a whole branch)")
     .option("--base <ref>", "check a PR/branch: files changed vs <ref> (e.g. origin/main) — for CI")
     .option("--strict", "exit non-zero ONLY on a direct, high-confidence, non-stale blocking invariant (near/stale/low-confidence stay advisory)")
     .option("--format <fmt>", "output: text (default) | markdown (a PR comment) | sarif (SARIF 2.1.0 for code scanning)", "text")
@@ -4124,11 +4190,14 @@ program
     const sarif = opts.format === "sarif";
     const emptyReport = { fileCount: 0, strict: !!opts.strict, direct: [], near: [], regressions: [], vetoes: [], redundant: [], strictBlockers: 0, regBlocking: 0, vetoBlocking: 0 };
     const { store, root, teamPullStatus } = storeFor({ requireFreshTeamMemory: !!opts.strict && !opts.publicOnly });
-    const teamFreshnessFailure = teamPullStatus !== null
-        && teamPullStatus !== "updated"
-        && teamPullStatus !== "current"
-        ? `strict check could not refresh the advertised team memory (${teamPullStatus}); refusing a stale pass`
+    const teamFreshnessFailure = teamPullStatus !== null && !teamPullIsFresh(teamPullStatus)
+        ? `strict check could not refresh the advertised team memory (${teamPullStatus}); refusing a stale pass` +
+            (teamPullStatus === "unconfigured" ? " — the shared memory remote has no published branch while this clone has memory; publish it with `hunch shared --sync`" : "")
         : null;
+    // An empty team remote is in sync with a never-committed clone, but it is also what
+    // lost team memory looks like: never let that strict pass be silent (#427).
+    if (teamPullStatus === "empty")
+        console.error("· the advertised team memory has no published branch yet; this strict check ran with no team rules (publish with `hunch shared --sync` after the first capture)");
     // Fail loudly on an unresolvable --base (e.g. CI forgot to fetch the base
     // branch) — otherwise the diff is empty and the guard passes vacuously.
     if (opts.base && !revExists(opts.base, root)) {
@@ -4194,13 +4263,14 @@ program
     // blocking conformance predicate or an active policy guards.
     // The COMPLETE diff (no synthesis byte budget); an incomplete one is flagged so
     // content-matched blocking invariants fail closed instead of passing unseen.
+    const freshAt = checkFreshnessRevision({ base: opts.base, commit: exactCommit }, root);
     const gate = files.length
         ? (exactCommit ? commitGateDiff(exactCommit, root) : opts.base ? rangeGateDiff(opts.base, root) : opts.working ? workingGateDiff(root) : stagedGateDiff(root))
         : { diff: "" };
     const report = files.length
         ? store.buildCheckReport(files, gate.diff, {
             strict: !!opts.strict,
-            lastChange: (f) => lastChangeDate(f, root),
+            lastChange: (f) => lastChangeDate(f, root, freshAt),
             publicOnly: !!opts.publicOnly,
             diffStatus: gate,
         })
@@ -4341,7 +4411,8 @@ const vetoCmd = program
         return;
     }
     const gate = opts.commit ? commitGateDiff(opts.commit, root) : opts.base ? rangeGateDiff(opts.base, root) : stagedGateDiff(root);
-    const full = store.buildCheckReport(files, gate.diff, { strict: !!opts.strict, lastChange: (f) => lastChangeDate(f, root), diffStatus: gate });
+    const freshAt = checkFreshnessRevision({ base: opts.base, commit: opts.commit }, root);
+    const full = store.buildCheckReport(files, gate.diff, { strict: !!opts.strict, lastChange: (f) => lastChangeDate(f, root, freshAt), diffStatus: gate });
     if (!full.vetoes.length) {
         console.log(`✓ ${files.length} changed file(s) reverse no decision you rejected.`);
         store.close();
@@ -4983,8 +5054,7 @@ program
                         const opened = openTeamStore(root, { requireFreshTeamMemory: firmness === "strict" });
                         store = opened.store;
                         // Same rule as the pre-edit path: strict never grounds from stale team rules.
-                        const stale = firmness === "strict" && opened.teamPullStatus
-                            && opened.teamPullStatus !== "updated" && opened.teamPullStatus !== "current";
+                        const stale = firmness === "strict" && opened.teamPullStatus && !teamPullIsFresh(opened.teamPullStatus);
                         if (!stale)
                             shellGround = shellWriteGrounding(root, store, provider, evt, written);
                     }
@@ -5100,8 +5170,13 @@ program
             // Reporting failure must not suppress the existing correction/policy reminder.
             try {
                 const report = startHookReport(root, provider, evt);
-                if (report)
+                if (report) {
                     parts.push(report);
+                    store ??= new HunchStore(paths);
+                    const selected = promptTaskSelection(root, store, provider, evt);
+                    if (selected)
+                        parts.push(selected);
+                }
             }
             catch { /* passive reporting remains fail-open */ }
             // A task an earlier prompt of this session left open (interrupted before
@@ -5275,7 +5350,7 @@ program
                 // in the overlay. Private mode stays public-only: session transcripts travel
                 // further than a terminal.
                 const decisions = s.advisoryRecs("decisions");
-                const { recent, roadmap, pendingReview } = nowData(decisions, 3);
+                const { pendingReview } = nowData(decisions, 3);
                 const escalations = pendingEscalations(decisions);
                 escalations.push(...premiseEscalations(decisions, { now: new Date().toISOString(), exists: (p) => existsSync(join(paths.root, p)) }));
                 // liveness checked against the full store even in private mode — a
@@ -5312,17 +5387,6 @@ program
                 }
                 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.unconfirmed ? `${r.title} [unconfirmed, ${r.id}]` : r.title)).join(" · ")}${roadmap.length > 3 ? " · …" : ""}`);
-                    const unconfirmed = roadmap.filter((r) => r.unconfirmed).length;
-                    if (unconfirmed)
-                        L.push(`${unconfirmed} roadmap item(s) are unconfirmed agent testimony — the human confirms each with \`hunch review --confirm <id>${s.unified ? " --private" : ""}\`.`);
-                }
                 if (pendingReview > 0)
                     L.push(`${pendingReview} legacy un-vouched draft(s) — adopt as advisory memory with \`hunch adopt-drafts\` (new captures auto-trust).`);
                 if (actionableEsc.length) {
@@ -5350,6 +5414,13 @@ program
         }
         if (evt.hook_event_name !== "PreToolUse")
             return;
+        // A shell command's writes are measured from its own start: a file written
+        // before it (a parallel tool call, another process, a host that skipped the
+        // last PostToolUse) is not this command's to be blamed for.
+        if (evt.tool_name === "Bash" || evt.tool_name === "PowerShell") {
+            refreshShellBaseline(root, evt.session_id, evt.agent_id);
+            return;
+        }
         const targets = editTargets(root, evt.tool_input);
         // Nothing inside the repo → nothing for Hunch to say.
         if (!targets.length)
@@ -5373,8 +5444,7 @@ program
         // never grounding from public/stale memory (dec_77d99014e0).
         const opened = openTeamStore(root, { requireFreshTeamMemory: firmness === "strict" });
         store = opened.store;
-        if (firmness === "strict" && opened.teamPullStatus
-            && opened.teamPullStatus !== "updated" && opened.teamPullStatus !== "current") {
+        if (firmness === "strict" && opened.teamPullStatus && !teamPullIsFresh(opened.teamPullStatus)) {
             // A strict deny is only trustworthy when it includes the latest team
             // rules. Offline/busy/unconfigured team memory is unavailable, so the
             // non-blocking hook says so instead of denying from stale state.
@@ -6321,8 +6391,11 @@ program
                 console.log(`Pruned ${deadEntries.length} dead queue entr${deadEntries.length === 1 ? "y" : "ies"} (decision moved on, has no commit on record, or was superseded/rejected): ${deadEntries.map((r) => r.id).join(", ")}`);
         }
         const candidates = rangeResolves && !opts.apply && !opts.drop ? mergeRangeChanges(oldRef, newRef, root) : [];
-        const orphaned = candidates.length ? orphanedCommitDecisions(decisions, (sha) => commitRepairStatus(sha, newRef, root)) : [];
-        const freshPlan = candidates.length ? planCommitRepair(orphaned, candidates) : { rewrites: [], records: [] };
+        // Orphaned means HEAD no longer reaches the commit either: a historical
+        // --range tip alone would flag every newer, perfectly reachable commit (#450).
+        const orphaned = candidates.length ? orphanedCommitDecisions(decisions, (sha) => commitRepairStatusAgainst(sha, [newRef, "HEAD"], root)) : [];
+        const patchIds = orphaned.length ? commitPatchIds([...orphaned.map((d) => d.commit), ...candidates.map((c) => c.sha)], root) : new Map();
+        const freshPlan = candidates.length ? planCommitRepair(orphaned, candidates, (sha) => patchIds.get(sha) ?? null) : { rewrites: [], records: [] };
         // Detection always queues a fresh match — local-only, never committed, so
         // it's safe to persist unconditionally. This is what makes running
         // opportunistically (from the hook) worth anything: the match survives
@@ -6475,12 +6548,17 @@ program
                 console.log(unresolvedCount
                     ? `Would repair ${toApply.length - unresolvedCount} of ${toApply.length} listed:`
                     : `Would repair ${toApply.length} commit reference(s):`);
+                // Match strength, so a reviewer can tell an identical change from a
+                // file-overlap guess before applying it into shared memory (#450).
+                const previewPatchIds = commitPatchIds(toApply.flatMap((r) => [r.from, r.to]), root);
                 for (const r of toApply) {
                     const reason = reasonQueued(r);
+                    const samePatch = !!previewPatchIds.get(r.from) && previewPatchIds.get(r.from) === previewPatchIds.get(r.to);
                     const label = reason === "invisible" ? "not visible this run — --apply would leave it queued"
                         : reason === "withheld" ? "proposed replacement commit doesn't resolve in this repository — --apply would leave it queued"
                             : reason === "duplicate" ? "another queued entry for this same decision would be applied instead — --apply would leave this one queued"
-                                : null;
+                                : samePatch ? "same patch-id: identical change"
+                                    : "file match only — check the diff before applying";
                     console.log(`  ${r.id}  ${r.from} → ${r.to}${label ? `  (${label})` : ""}`);
                 }
                 const reviewHash = commitRepairReviewHash(queue, withheldRewrites(root, queue));
@@ -7126,6 +7204,13 @@ program
                 console.log(`· ${f.id} — ${f.detail}`);
             console.log(`\nHeal: this is a HUMAN call — check \`hunch repair-provenance\` for a queued match (the post-merge hook detects these automatically while the commit is still resolvable, but never applies one unattended); run \`hunch repair-provenance --apply\` to confirm it, or if the commit is already gone, manually correct the decision's provenance or leave it as historical record.\n`);
         }
+        const fenceUnclosed = kind("doc-fence-unclosed");
+        if (fenceUnclosed.length) {
+            console.log(`${fenceUnclosed.length} markdown file(s) open a code fence that never closes, hiding the topic markers below it:\n`);
+            for (const f of fenceUnclosed)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: close the fence (a line of the same \`\`\` or ~~~ run) where the example ends; the markers after it become live again.\n`);
+        }
         console.log(`Hunch never rewrites prose for you; this is a read-only reconciliation report.`);
     }
     finally {
@@ -7248,7 +7333,19 @@ program
     .command("doctor")
     .description("Diagnose the environment (git, synthesis provider, index freshness).")
     .action(async () => {
-    const integrations = inspectIntegrations(findRoot());
+    const doctorRoot = findRoot();
+    if (isOptedOut(doctorRoot)) {
+        console.log(`Hunch: not installed (opted out — ${OPT_OUT_FILE} is present).`);
+        const left = planUninstall(doctorRoot).steps.filter((s) => s.kind === "edit" || s.kind === "delete");
+        if (left.length) {
+            console.log(`  ⚠ ${left.length} Hunch leftover(s) remain; \`hunch uninstall\` removes them:`);
+            for (const s of left)
+                console.log(`    - ${s.path}`);
+        }
+        console.log(`  To reinstall: delete ${OPT_OUT_FILE}, then run \`hunch init\`.`);
+        return;
+    }
+    const integrations = inspectIntegrations(doctorRoot);
     console.log(formatIntegrationHealth(integrations));
     // A pin npm cannot serve kills every npx launcher (hooks and MCP) before Hunch
     // runs, and the hosts report nothing. Name it here; bounded, offline-safe.
@@ -7522,6 +7619,62 @@ function shellWriteGrounding(root, store, provider, evt, written) {
     const sibling = parts.some((p) => p.startsWith(SIBLING_HEADING)) ? " It starts with a fix a same-shaped function elsewhere received and this file's copy never did: resolve it before you finish." : "";
     return `Hunch: this shell command wrote ${grounded.join(", ")}${more}. Edits made outside the Edit/Write tools skip the pre-edit grounding, so it arrives now: re-check the change against it before relying on it.${sibling}\n\n${parts.join("\n\n")}`;
 }
+/** Score the store against this prompt once per task (taskSelection.ts) and keep
+ *  the selected ids — never the prompt — for the task's file grounding. Returns
+ *  the short prompt-time list, or "" when nothing clears the threshold (silence).
+ *  A follow-up prompt widens the qualifying set rather than replacing it, so a
+ *  "go" cannot unselect the task's memory. */
+const TASK_SELECTION_TITLE_CHARS = 80;
+function promptTaskSelection(root, store, provider, evt) {
+    // A host notification is not a task prompt: the earlier selection stands untouched.
+    if (!taskSelectionEnabled() || isNotificationPrompt(evt.prompt))
+        return "";
+    const taskId = hookReportTaskId(root, provider, evt);
+    if (!taskId)
+        return "";
+    const selection = selectForTask(liveSelectionRecords({
+        decisions: store.recs("decisions"),
+        bugs: store.recs("bugs"),
+        constraints: store.recs("constraints"),
+        findings: store.recs("findings"),
+    }), evt.prompt ?? "", { root, pathExists: (p) => existsSync(join(root, p)) });
+    // Same task id again (a notification alias) keeps its own earlier selection; a
+    // new task that CONTINUES the session's previous one inherits that task's
+    // selection only on a bare follow-up ("continue", "go on"), so it is not left
+    // ungrounded. A substantive prompt names its own task: a same-session prompt
+    // inside the continuation window must not hide memory behind an old selection.
+    let previous = loadTaskSelection(taskId);
+    if (!previous && isBareFollowUp(evt.prompt ?? "")) {
+        try {
+            const continues = readTaskReport(root, taskId).task.continues;
+            previous = continues ? loadTaskSelection(continues) : null;
+        }
+        catch { /* no continuity; the prompt's own selection stands */ }
+    }
+    const qualifying = [...new Set([...(previous?.qualifying ?? []), ...selection.qualifying])];
+    // An empty selection is no selection: the task keeps the unfiltered grounding.
+    // Emptiness counts only the kinds grounding filters (decisions, bugs,
+    // findings): constraints always pass, so a constraint-only set would hide every
+    // other record anchored to the file. The prompt-time list may still print.
+    if (!qualifying.some(isFilterableSelectionId)) {
+        clearTaskSelection(taskId);
+    }
+    else {
+        saveTaskSelection({
+            task_id: taskId,
+            qualifying,
+            top: selection.qualifying.length ? selection.top.map((item) => item.id) : previous?.top ?? [],
+        });
+    }
+    // An inherited selection was listed when its own prompt ran: not again.
+    if (!selection.top.length)
+        return "";
+    const clip = (text) => {
+        const flat = text.replace(/\s+/g, " ").trim();
+        return flat.length > TASK_SELECTION_TITLE_CHARS ? `${flat.slice(0, TASK_SELECTION_TITLE_CHARS - 1).trimEnd()}…` : flat;
+    };
+    return `Hunch memory for this task: ${selection.top.map((item) => `${item.id} — ${clip(item.title)}`).join(" · ")} (hunch_why(id) for detail)`;
+}
 /** Memory budget beside a sibling lesson (the default is 1500 tokens). */
 const SIBLING_MEMORY_BUDGET_TOKENS = 800;
 /** The advisory grounding for one repo-relative file: the ranked memory slice,
@@ -7540,7 +7693,21 @@ function fileGrounding(root, store, provider, evt, target, abs) {
         }
         catch { /* unreadable / not yet created — no doc grounding */ }
     }
-    const ctx = store.assembleContext(target);
+    // A task whose prompt was scored (promptTaskSelection) gets the file's
+    // decisions, bugs and findings conditioned on it. Constraints always pass (any
+    // severity): they are scoped rules, including agent-recorded corrections capped
+    // at warning, not relevance guesses. No selection (a host without a prompt
+    // hook, a legacy session, a prompt that selected nothing) keeps the unfiltered
+    // grounding.
+    const selection = loadTaskSelection(hookReportTaskId(root, provider, evt));
+    const assembled = store.assembleContext(target);
+    const selected = selection ? new Set(selection.qualifying) : null;
+    const ctx = selected ? {
+        ...assembled,
+        decisions: assembled.decisions.filter((d) => selected.has(d.id)),
+        bugs: assembled.bugs.filter((b) => selected.has(b.id)),
+        findings: assembled.findings.filter((f) => selected.has(f.id)),
+    } : assembled;
     // Sibling fixes: a same-shaped function elsewhere was fixed and this copy
     // never was — the concrete lesson a scoped constraint cannot carry.
     const siblings = siblingGrounding(root, target, store.recs("symbols"), ctx.constraints.filter((c) => c.severity === "blocking" && c.scope.some((g) => pathMatchesGlob(target, g))).map((c) => ({ id: c.id, statement: c.statement })));
@@ -7565,7 +7732,9 @@ function fileGrounding(root, store, provider, evt, target, abs) {
     // from this file. No diff exists yet, so this is context — "don't re-add X" —
     // not a block; the commit-time `hunch check` does the actual gating.
     const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
-    const recentTasks = taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target, { excludeTargetDeliveries: true })), target);
+    // Recent-task history is advisory; under a task selection it is dropped
+    // (`hunch task list` still has it).
+    const recentTasks = selected ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target, { excludeTargetDeliveries: true })), target);
     const hasContent = ctx.constraints.length ||
         ctx.decisions.length ||
         ctx.bugs.length ||

package/dist/core/changeProof.js

@@ -313,7 +313,8 @@ export function deriveChangeProof(root, store, baseRef, resultRef = "HEAD", opti
         // A diff cut at MAX_DIFF_BYTES is a prefix: content-matched blocking rules over the
         // files it omits fail closed rather than read as compliant (dec_20db57c576).
         diffStatus: diff.gaps.length ? { incomplete: `the guard diff exceeded ${MAX_DIFF_BYTES} bytes and was cut`, truncated: true } : undefined,
-        lastChange: (path) => lastChangeAt(root, change.head_revision, path),
+        // Freshness as of the base: the change under proof must not make its own guard stale (#426).
+        lastChange: (path) => lastChangeAt(root, change.base_revision, path),
     });
     const allStrictBlockerIds = sortedUnique([
         ...guardReport.direct.filter((item) => item.strictBlocks).map((item) => item.id),

package/dist/core/commitrepair.d.ts

@@ -30,9 +30,15 @@ export interface CommitRepairPlan {
  *  doesn't resolve at all ("unresolvable") is out of repair scope, and a git
  *  failure ("unknown") must never be mistaken for repair-eligible. */
 export declare function orphanedCommitDecisions(decisions: readonly Decision[], status: (sha: string) => CommitRepairStatus): Decision[];
-/** Match each orphaned decision to exactly one candidate whose changed files are
- *  a superset of the decision's related_files (non-empty, no globs). */
-export declare function planCommitRepair(orphaned: readonly Decision[], candidates: readonly CommitCandidate[]): CommitRepairPlan;
+/** Match each orphaned decision to exactly one candidate. A candidate with the
+ *  same `git patch-id --stable` as the orphaned commit (a rebase- or
+ *  single-commit squash-merge of it) is the strong match and wins. Only when
+ *  no candidate shares the patch-id does it fall back to the one candidate
+ *  whose changed files are a superset of the decision's related_files
+ *  (non-empty, no globs) -- needed for a squash of several commits, whose
+ *  patch-id never equals any one of them, but weak: shared files like
+ *  CHANGELOG.md often have one wrong superset (#450). */
+export declare function planCommitRepair(orphaned: readonly Decision[], candidates: readonly CommitCandidate[], patchIdOf?: (sha: string) => string | null): CommitRepairPlan;
 /** Whether a queued rewrite is still worth ASKING about: the decision it
  *  names still exists, still cites the commit the entry expects to replace (a
  *  decision that already moved on would make repairDecisionCommit's own

package/dist/core/commitrepair.js

@@ -4,9 +4,10 @@
  * A squash-merge produces one new commit whose parent is the pre-merge target
  * tip — the original per-commit SHAs it squashed are never ancestors of it.
  * This module matches an orphaned decision to the ONE newly-merged commit
- * whose changed files are a superset of the decision's related_files. Zero or
- * multiple qualifying candidates means "don't guess" — same discipline as
- * repair.ts's rename-repair.
+ * with the same patch-id, or failing that the ONE whose changed files are a
+ * superset of the decision's related_files. Zero or multiple qualifying
+ * candidates means "don't guess" — same discipline as repair.ts's
+ * rename-repair.
  */
 import { createHash } from "node:crypto";
 import { replaceExact } from "./refrepair.js";
@@ -33,11 +34,27 @@ export function orphanedCommitDecisions(decisions, status) {
         return status(d.commit) === "orphaned";
     });
 }
-/** Match each orphaned decision to exactly one candidate whose changed files are
- *  a superset of the decision's related_files (non-empty, no globs). */
-export function planCommitRepair(orphaned, candidates) {
+/** Match each orphaned decision to exactly one candidate. A candidate with the
+ *  same `git patch-id --stable` as the orphaned commit (a rebase- or
+ *  single-commit squash-merge of it) is the strong match and wins. Only when
+ *  no candidate shares the patch-id does it fall back to the one candidate
+ *  whose changed files are a superset of the decision's related_files
+ *  (non-empty, no globs) -- needed for a squash of several commits, whose
+ *  patch-id never equals any one of them, but weak: shared files like
+ *  CHANGELOG.md often have one wrong superset (#450). */
+export function planCommitRepair(orphaned, candidates, patchIdOf = () => null) {
     const rewrites = [];
     for (const d of orphaned) {
+        const patchId = patchIdOf(d.commit);
+        if (patchId) {
+            const same = candidates.filter((c) => patchIdOf(c.sha) === patchId);
+            if (same.length === 1) {
+                rewrites.push({ id: d.id, from: d.commit, to: same[0].sha });
+                continue;
+            }
+            if (same.length > 1)
+                continue; // ambiguous: never guess
+        }
         const files = (d.related_files ?? []).filter(isExactPath);
         if (!files.length)
             continue;

package/dist/core/correction.d.ts

@@ -30,7 +30,7 @@ export interface CorrectionInput {
      *  enough — any agent can mint and consume one. Determines the TIER, never whether
      *  the write lands: an un-vouched correction still records immediately and still
      *  surfaces at edit time and in CI. Only the authority to DENY waits for a countersign
-     *  (`hunch review --confirm <id>`). */
+     *  (`hunch review --confirm <id>`). Omitted means false. */
     vouched?: boolean;
 }
 /** Default rationales, exported so a later human countersign can replace the testimony

package/dist/core/correction.js

@@ -5,8 +5,8 @@
  *  agent hook so they are unit-testable without spinning either up:
  *   - looksLikeCorrection(): does a user prompt read like "no / that's wrong /
  *     never do X" — the cue to nudge the agent to persist it.
- *   - buildCorrectionConstraint(): mint the Constraint record (human-confirmed,
- *     scoped conservatively) that the pre-edit hook + CI guard then enforce.
+ *   - buildCorrectionConstraint(): mint the Constraint record (human-confirmed
+ *     only when vouched, scoped conservatively) that the pre-edit hook + CI guard then enforce.
  */
 import { isAbsolute } from "node:path";
 import { constraintId } from "./ids.js";
@@ -108,7 +108,8 @@ export function buildCorrectionConstraint(input, now) {
     // still recorded immediately and still held against every assistant at edit time and
     // in CI — Never Twice keeps its promise. What waits for a countersign is only the
     // authority to DENY.
-    const vouched = input.vouched !== false;
+    // Fails closed: an omitted flag is testimony, never a signature.
+    const vouched = input.vouched === true;
     if (!vouched && severity === "blocking")
         severity = "warning";
     return {

package/dist/core/delivery.d.ts

@@ -112,6 +112,18 @@ export interface DeliveryOptions {
     /** Injectable for deterministic tests. Omit to use the local Git graph. */
     commitReachability?: (commit: string) => CommitReachability;
 }
+export declare const SEVERITY: {
+    readonly advisory: 1;
+    readonly warning: 2;
+    readonly blocking: 3;
+    readonly low: 1;
+    readonly medium: 2;
+    readonly high: 3;
+    readonly critical: 4;
+};
+export declare const PROFILE_BASE_SCORE: Record<DeliveryProfile, Record<DeliveryKind, number>>;
+export declare const TASK_STOP_WORDS: Set<string>;
+export declare function lexicalTokens(value: string): Set<string>;
 /** Validate the public receipt without trusting a caller-supplied identity. */
 export declare function assertDeliveryEnvelope(envelope: DeliveryEnvelope): void;
 /** The string a hash-based injection dedup (`injectionMode`'s `hashInput`) must

package/dist/core/delivery.js

@@ -16,7 +16,7 @@ import { LANDSCAPE_FRAGMENT_SCHEMA_VERSION, assertLandscapeDeliveryFragment, cre
 export const DELIVERY_ENVELOPE_SCHEMA_VERSION = "hunch.delivery-envelope/1";
 export const DELIVERY_PROFILE_POLICY_VERSION = "hunch.delivery-profile/1";
 export const DELIVERY_PROFILES = ["builder", "reviewer", "architect"];
-const SEVERITY = { advisory: 1, warning: 2, blocking: 3, low: 1, medium: 2, high: 3, critical: 4 };
+export const SEVERITY = { advisory: 1, warning: 2, blocking: 3, low: 1, medium: 2, high: 3, critical: 4 };
 const MIN_ADVISORY_CONFIDENCE = 0.5;
 const MIN_UNCONDITIONED_CONFIDENCE = 0.7;
 const MAX_ACTIONABLE_HYPOTHESES = 2;
@@ -24,7 +24,7 @@ const MAX_PROFILE_HEADLINES = 8;
 /** How far a supplement's text is clipped in the rendered line. Shared so
  *  `deliveryDedupeInput` can reconstruct that exact line to project over it. */
 const SUPPLEMENT_HEADLINE_CHARS = 700;
-const PROFILE_BASE_SCORE = {
+export const PROFILE_BASE_SCORE = {
     builder: {
         constraints: 900,
         decisions: 800,
@@ -50,7 +50,7 @@ const PROFILE_BASE_SCORE = {
         relationships: 825,
     },
 };
-const TASK_STOP_WORDS = new Set([
+export const TASK_STOP_WORDS = new Set([
     "a", "an", "and", "are", "as", "at", "be", "been", "but", "by", "can", "does", "for", "from",
     "has", "have", "in", "into", "is", "it", "its", "of", "on", "or", "that", "the", "this", "to",
     "use", "uses", "using", "was", "when", "where", "which", "while", "with", "without",
@@ -91,7 +91,7 @@ function stemToken(token) {
         return token.slice(0, -1);
     return token;
 }
-function lexicalTokens(value) {
+export function lexicalTokens(value) {
     const expanded = value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").toLowerCase();
     const words = expanded.match(/[\p{L}\p{N}]+/gu) ?? [];
     return new Set(words.map(stemToken).filter((token) => token.length >= 3 && !TASK_STOP_WORDS.has(token)));