@davesheffer/hunch 1.42.0 → 1.43.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.

package/dist/cli/index.js

@@ -91,12 +91,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";
@@ -5100,8 +5101,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 +5281,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 +5318,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 +5345,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)
@@ -7522,6 +7524,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 +7598,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 +7637,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/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)));

package/dist/core/hookcache.d.ts

@@ -15,3 +15,25 @@ export declare function injectionMode(sessionId: string | undefined, key: string
  *  reset, or post-compact edits get delta one-liners against grounding the
  *  agent no longer has. Never throws (same posture as injectionMode). */
 export declare function resetSessionInjections(sessionId: string | undefined): void;
+/** The machine-local directory every hook cache lives in (OS tmpdir). */
+export declare function hookCacheDir(): string;
+/** A task's prompt-time memory selection (taskSelection.ts): record ids only —
+ *  never the prompt text it was scored from. Kill switch: HUNCH_TASK_SELECTION=0
+ *  (no selection is written or read, so file grounding stays unfiltered). */
+export interface TaskSelectionFile {
+    task_id: string;
+    qualifying: string[];
+    top: string[];
+}
+export declare function taskSelectionPath(taskId: string): string;
+/** Persist a task's selection (atomic temp+rename). Throws; callers fail open. */
+export declare function saveTaskSelection(selection: TaskSelectionFile): void;
+export declare function taskSelectionEnabled(): boolean;
+/** Remove a task's selection file (an empty selection is no selection). Never throws. */
+export declare function clearTaskSelection(taskId: string): void;
+/** The task's selection, or null when none was written (a host without a prompt
+ *  hook, a legacy session), it holds no decision/bug/finding id (constraints
+ *  are never filtered, so a constraint-only selection would only hide memory),
+ *  it is unreadable, or selection is switched off — callers then keep today's
+ *  unfiltered grounding. Never throws. */
+export declare function loadTaskSelection(taskId: string | null | undefined): TaskSelectionFile | null;

package/dist/core/hookcache.js

@@ -18,7 +18,9 @@
 import { createHash } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { isFilterableSelectionId } from "./taskSelection.js";
 import { tmpdir } from "node:os";
+import { writeFileAtomic } from "./io.js";
 const MAX_KEYS = 300;
 const SWEEP_AGE_MS = 48 * 3600 * 1000;
 /** Decide whether this injection should be the FULL grounding block or a delta
@@ -35,7 +37,7 @@ export function injectionMode(sessionId, key, content, hashInput = content) {
     try {
         if (!sessionId || process.env.HUNCH_HOOK_DEDUP === "0")
             return "full";
-        const dir = join(tmpdir(), "hunch-hookcache");
+        const dir = hookCacheDir();
         mkdirSync(dir, { recursive: true });
         sweep(dir);
         const file = join(dir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
@@ -71,13 +73,62 @@ export function resetSessionInjections(sessionId) {
     try {
         if (!sessionId)
             return;
-        const file = join(tmpdir(), "hunch-hookcache", `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+        const file = join(hookCacheDir(), `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
         rmSync(file, { force: true });
     }
     catch {
         /* unwritable tmpdir — next injectionMode call falls back to "full" anyway */
     }
 }
+/** The machine-local directory every hook cache lives in (OS tmpdir). */
+export function hookCacheDir() {
+    return join(tmpdir(), "hunch-hookcache");
+}
+export function taskSelectionPath(taskId) {
+    return join(hookCacheDir(), `task-${taskId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+}
+/** Persist a task's selection (atomic temp+rename). Throws; callers fail open. */
+export function saveTaskSelection(selection) {
+    const dir = hookCacheDir();
+    mkdirSync(dir, { recursive: true });
+    sweep(dir);
+    writeFileAtomic(taskSelectionPath(selection.task_id), JSON.stringify({
+        task_id: selection.task_id, qualifying: [...selection.qualifying], top: [...selection.top],
+    }));
+}
+export function taskSelectionEnabled() {
+    return process.env.HUNCH_TASK_SELECTION !== "0";
+}
+/** Remove a task's selection file (an empty selection is no selection). Never throws. */
+export function clearTaskSelection(taskId) {
+    try {
+        rmSync(taskSelectionPath(taskId), { force: true });
+    }
+    catch {
+        /* fail open: a stale file is read back as whatever it holds */
+    }
+}
+/** The task's selection, or null when none was written (a host without a prompt
+ *  hook, a legacy session), it holds no decision/bug/finding id (constraints
+ *  are never filtered, so a constraint-only selection would only hide memory),
+ *  it is unreadable, or selection is switched off — callers then keep today's
+ *  unfiltered grounding. Never throws. */
+export function loadTaskSelection(taskId) {
+    try {
+        if (!taskId || !taskSelectionEnabled())
+            return null;
+        const raw = JSON.parse(readFileSync(taskSelectionPath(taskId), "utf8"));
+        if (!raw || raw.task_id !== taskId || !Array.isArray(raw.qualifying) || !Array.isArray(raw.top))
+            return null;
+        const qualifying = raw.qualifying.filter((id) => typeof id === "string");
+        if (!qualifying.some(isFilterableSelectionId))
+            return null;
+        return { task_id: taskId, qualifying, top: raw.top.filter((id) => typeof id === "string") };
+    }
+    catch {
+        return null;
+    }
+}
 /** Drop session caches from long-gone sessions (best effort, bounded dir). */
 function sweep(dir) {
     try {

package/dist/core/publication.js

@@ -33,9 +33,23 @@ export function isStructural(hit) {
  *  `/Users/me/repo` appears in src/integrations/claudeConfig.ts and its test as an
  *  illustration; flagging those would train everyone to ignore the scanner. */
 const PLACEHOLDER_USER = /^(me|you|user|username|<[^>]+>|\$\{[^}]+\}|example|test|foo|bar)$/i;
+/** A regex quoted in a record (`\/home\/([^/]+)`, `C:\\Users\\([^\\]+)`) names a
+ *  pattern, not a user: its capture starts with a regex metacharacter and, past a
+ *  `(?<name>` label, holds no word. A group that lists names (`(alice|bob)`,
+ *  `{alice,bob}`) still names users. */
+const PATTERN_USER = /^[([*^{|+?]/;
+function isPatternUser(who) {
+    return PATTERN_USER.test(who) && !/[A-Za-z]{3,}/.test(who.replace(/^\(\?<\w+>/, ""));
+}
+/** Home directories in the forms tools print them: a drive path (also as a URI's
+ *  `c%3A`), a POSIX path after any separator (`file:///Users/x`, `cwd=/home/x`,
+ *  `git -C /Users/x`) but not after a drive letter's colon, which the drive rule
+ *  reports, and Git Bash's `/c/Users/x` or WSL's `/mnt/c/Users/x`. A letter right
+ *  before the colon makes it a scheme (`file:/Users/x`), not a drive. */
 const MACHINE_PATH = [
-    /[A-Za-z]:[\\/]Users[\\/]([^\\/"'\s,)\]]+)/g,
-    /(?:^|[\s"'(])\/(?:Users|home)\/([^/"'\s,)\]]+)/g,
+    /(?<![A-Za-z])[A-Z](?::|%3A)[\\/]Users[\\/]([^\\/"'\s,)\]]+)/gi,
+    /(?:^|[^A-Za-z0-9_.~])(?<!(?<![A-Za-z])[A-Za-z]:)\/(?:Users|home)\/([^/"'\s,)\]]+)/g,
+    /(?:^|[^A-Za-z0-9_.~])\/(?:mnt\/)?[A-Za-z]\/Users\/([^/"'\s,)\]]+)/g,
 ];
 /** A path INTO the overlay (dir + file), not a bare mention of the feature. The
  *  gitignore entry and the CLAUDE.md description name `.hunch-private` legitimately;
@@ -151,7 +165,7 @@ export function scanRecord(record, opts = {}) {
         for (const re of MACHINE_PATH) {
             for (const m of text.matchAll(re)) {
                 const who = m[1] ?? "";
-                if (PLACEHOLDER_USER.test(who))
+                if (PLACEHOLDER_USER.test(who) || isPatternUser(who))
                     continue;
                 hits.push({ kind: "machine-path", field, excerpt: clip(m[0]) });
             }

package/dist/core/taskReportHook.js

@@ -200,7 +200,7 @@ export function taskInstruction(task, cwdLiteral, provider, launcher = verificat
             const finishRule = HOST_CLOSES_TASK.has(provider) ? "finish only if this task used Hunch" : `finish it yourself with hunch_task(action: "finish", task_id, cwd)`;
             return `Hunch report for this prompt: ${task.task_id} (cwd: ${cwdLiteral}). Use it instead of any earlier ID. Never call hunch_task start. Checks: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Same rules as this session's first report; ${finishRule}.`;
         }
-        verify = ` Never call hunch_task start for it. For checks, run: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Default budget 15 min; add --timeout <seconds> before -- for longer suites.`;
+        verify = ` Never call hunch_task start for it. For checks, run: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Verify with the tests that cover your change (the files you edited and their tests); the full suite is CI's job. The default budget is 15 min; add --timeout <seconds> before -- only if the whole suite is really needed.`;
     }
     catch {
         return `${head} Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv, and finish with hunch_task(action: "finish", task_id, cwd) before responding and show its card.`;

package/dist/core/taskSelection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Task-scored memory selection (memory-selection design, point 1-3; Gate A v5).
+ *
+ * The pre-edit hook used to deliver every record anchored to a file, so a hub
+ * file filled the headline cap with memory unrelated to the task. This selector
+ * scores the live store against the prompt ONCE per task; file grounding then
+ * keeps only the decisions, bugs and findings that qualified (constraints are
+ * exempt: they are scoped rules, not relevance guesses).
+ *
+ * PURE on purpose: no fs, no store. Inputs are passed in, so an offline replay
+ * can run it against an old store snapshot. The rule is fixed before
+ * measurement (no vectors in this step): a record qualifies on >= 2 distinct
+ * task terms in its title/rationale, or on a repo path the prompt names that
+ * matches the record's files or scope. Below that, nothing (silence, no filler).
+ * A term common to many live records (document frequency above the cap) names
+ * no task and does not count toward the two.
+ */
+import type { Bug, Constraint, Decision, Finding } from "./types.js";
+export interface TaskSelectionRecords {
+    decisions: readonly Decision[];
+    bugs: readonly Bug[];
+    constraints: readonly Constraint[];
+    findings: readonly Finding[];
+}
+export type TaskSelectionKind = "decision" | "bug" | "constraint" | "finding";
+export interface TaskSelection {
+    /** Every record clearing the threshold (ids only). */
+    qualifying: string[];
+    /** At most k, ordered; blocking constraints are never listed (they arrive at edit time). */
+    top: Array<{
+        id: string;
+        kind: TaskSelectionKind;
+        title: string;
+    }>;
+}
+export declare function isFilterableSelectionId(id: string): boolean;
+export declare function isBareFollowUp(prompt: string): boolean;
+export interface TaskSelectionOptions {
+    /** Prompt-time list size (design: K = 3). */
+    k?: number;
+    /** Optional existence check for a repo-relative path the prompt names. */
+    pathExists?: (path: string) => boolean;
+    /** Repository root, only to strip it from absolute paths in the prompt (string work, no fs). */
+    root?: string;
+}
+/** Document-frequency cap, fixed before the pilot replay: a prompt term counts
+ *  only when at most max(MIN_DF_CAP, ceil(DF_CAP_RATIO × live records)) records
+ *  contain it. */
+export declare const MIN_DF_CAP = 3;
+export declare const DF_CAP_RATIO = 0.05;
+/** The live slice the pre-edit grounding would ever deliver at HEAD: decisions and
+ *  constraints still in force (the store's why() window plus delivery's retired
+ *  test), every bug (why() keeps fixed ones as lessons), and findings whose triage
+ *  liveFindingsFor() keeps. */
+export declare function liveSelectionRecords(all: TaskSelectionRecords): TaskSelectionRecords;
+/** Repo paths the prompt names: a markdown link `[label](target)` reads as its
+ *  target, then a whitespace token containing `/` or ending in a file extension,
+ *  stripped of quoting/punctuation/unmatched brackets, a trailing `:line[:col]`
+ *  or `:start-end` and a possessive `'s`, forward-slashed, repo-relative. A drive-letter root compares
+ *  case-insensitively (Windows paths are case-insensitive on every host). */
+export declare function promptPaths(prompt: string, root?: string): string[];
+/** Score live records against one prompt. Text fields per kind (title + rationale):
+ *  decision title/context/decision; bug title/symptom/root_cause; constraint
+ *  statement/rationale; finding title/observation. Path anchors: decision
+ *  related_files, bug/finding affected_files, constraint scope globs. Priority
+ *  ties break on the builder profile's kind/severity score in delivery.ts. */
+export declare function selectForTask(records: TaskSelectionRecords, promptText: string, opts?: TaskSelectionOptions): TaskSelection;

package/dist/core/taskSelection.js

@@ -0,0 +1,196 @@
+import { lexicalTokens, PROFILE_BASE_SCORE, SEVERITY } from "./delivery.js";
+import { pathMatchesGlob } from "./glob.js";
+/** Id prefixes of the kinds file grounding filters by a selection (ids.ts:
+ *  decisionId/bugId/findingId). Constraints (con_) always pass, so a selection
+ *  holding no id with one of these prefixes filters nothing useful — it would
+ *  only hide every decision, bug and finding — and counts as no selection. */
+const FILTERABLE_ID_PREFIXES = ["dec_", "bug_", "fnd_"];
+export function isFilterableSelectionId(id) {
+    return FILTERABLE_ID_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+/** Words a bare follow-up is made of ("continue", "go on", "yes do it", "ok,
+ *  next step please"). A prompt of only these names no task of its own and
+ *  inherits the continued task's selection; any other word — a verb and an
+ *  object ("fix sampler"), a path, another language — is a task of its own
+ *  (fail-safe: its own selection, or unfiltered grounding). */
+const CONTINUATION_WORDS = new Set([
+    "continue", "continuing", "go", "on", "ahead", "proceed", "resume", "carry", "keep", "going",
+    "yes", "yep", "yeah", "y", "ok", "okay", "sure", "please", "pls", "do", "it", "that", "this",
+    "next", "step", "again", "lgtm", "sounds", "good", "fine", "and", "the", "with", "now",
+]);
+export function isBareFollowUp(prompt) {
+    const words = (prompt ?? "").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    return words.length > 0 && words.every((word) => CONTINUATION_WORDS.has(word));
+}
+const BRACKET_PAIRS = { "(": ")", "[": "]", "{": "}" };
+const CLOSING_BRACKETS = { ")": "(", "]": "[", "}": "{" };
+/** Every `close` in text[from, to) follows its `open` (properly nested, none left open). */
+function balanced(text, from, to, open, close) {
+    let depth = 0;
+    for (let i = from; i < to; i++) {
+        if (text[i] === open)
+            depth++;
+        else if (text[i] === close && --depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/** Strip quoting, sentence punctuation, unmatched or wrapping brackets and a
+ *  possessive `'s` from a prompt token until stable. A bracket the path itself
+ *  uses (`(auth)/x.ts`, `[id]/page.tsx`, `src/app/(auth)`) is balanced and stays.
+ *  Works on [a, b) indices with bracket counts kept current, so trimming a run of
+ *  n unmatched brackets is linear, not n rescans of the token. */
+const MAX_PATH_TOKEN_CHARS = 1024;
+/** Wrapping pairs unwrapped per token; each unwrap rescans the token, and prose never nests deeper. */
+const MAX_UNWRAPS = 8;
+function trimPathToken(raw) {
+    const counts = { "(": 0, ")": 0, "[": 0, "]": 0, "{": 0, "}": 0 };
+    for (let i = 0; i < raw.length; i++)
+        if (raw[i] in counts)
+            counts[raw[i]]++;
+    const n = (ch) => counts[ch];
+    const dropAt = (i) => { if (raw[i] in counts)
+        counts[raw[i]]--; };
+    let a = 0;
+    let b = raw.length;
+    let unwraps = 0;
+    for (let before = -1; a < b && before !== b - a;) {
+        before = b - a;
+        // A trailing opening bracket can never close, so it goes first (keeps `[id]/x.ts[` from losing its head).
+        const lastOpen = raw[b - 1];
+        if (BRACKET_PAIRS[lastOpen] && n(lastOpen) > n(BRACKET_PAIRS[lastOpen]))
+            dropAt(--b);
+        if (a >= b)
+            break;
+        const head = raw[a];
+        const close = BRACKET_PAIRS[head];
+        const headOpen = CLOSING_BRACKETS[head];
+        if ("`'\"<\u2018\u201c".includes(head))
+            dropAt(a++);
+        else if (close && unwraps < MAX_UNWRAPS && b - a >= 2 && raw[b - 1] === close && n(head) === n(close) && balanced(raw, a + 1, b - 1, head, close)) {
+            unwraps++;
+            dropAt(a++);
+            dropAt(--b);
+        }
+        else if (close && n(head) > n(close))
+            dropAt(a++);
+        else if (headOpen && n(head) > n(headOpen))
+            dropAt(a++);
+        if (a >= b)
+            break;
+        const tail = raw[b - 1];
+        const open = CLOSING_BRACKETS[tail];
+        if ("`'\">,.;:!?\u2019\u201d".includes(tail))
+            dropAt(--b);
+        else if (open && n(open) < n(tail))
+            dropAt(--b);
+        if (b - a >= 2 && "sS".includes(raw[b - 1]) && "'\u2019".includes(raw[b - 2]))
+            b -= 2;
+    }
+    return raw.slice(a, b);
+}
+const MIN_DISTINCT_TERMS = 2;
+/** Document-frequency cap, fixed before the pilot replay: a prompt term counts
+ *  only when at most max(MIN_DF_CAP, ceil(DF_CAP_RATIO × live records)) records
+ *  contain it. */
+export const MIN_DF_CAP = 3;
+export const DF_CAP_RATIO = 0.05;
+const DEFAULT_K = 3;
+const LIVE_FINDING_TRIAGE = new Set(["open", "accepted-risk", "scheduled"]);
+/** The live slice the pre-edit grounding would ever deliver at HEAD: decisions and
+ *  constraints still in force (the store's why() window plus delivery's retired
+ *  test), every bug (why() keeps fixed ones as lessons), and findings whose triage
+ *  liveFindingsFor() keeps. */
+export function liveSelectionRecords(all) {
+    return {
+        decisions: all.decisions.filter((d) => d.status !== "rejected" && d.status !== "superseded" && !d.superseded_by && d.valid_to == null),
+        bugs: [...all.bugs],
+        constraints: all.constraints.filter((c) => c.status !== "retired" && c.valid_to == null),
+        findings: all.findings.filter((f) => LIVE_FINDING_TRIAGE.has(f.triage)),
+    };
+}
+/** Repo paths the prompt names: a markdown link `[label](target)` reads as its
+ *  target, then a whitespace token containing `/` or ending in a file extension,
+ *  stripped of quoting/punctuation/unmatched brackets, a trailing `:line[:col]`
+ *  or `:start-end` and a possessive `'s`, forward-slashed, repo-relative. A drive-letter root compares
+ *  case-insensitively (Windows paths are case-insensitive on every host). */
+export function promptPaths(prompt, root) {
+    const out = new Set();
+    const rootPrefix = root ? `${root.replace(/\\/g, "/").replace(/\/+$/, "")}/` : null;
+    // Label and target may each hold one level of brackets (`[app/[id]/x.ts](app/[id]/x.ts)`,
+    // a linked `src/app/(auth)/page.tsx`); the label never spans a `[`, so a run of `[` fails fast.
+    const links = prompt.replace(/\[(?:[^[\]\n]|\[[^[\]\n]{0,256}\]){0,256}\]\(((?:[^()\s]|\([^()\s]{0,256}\)){1,1024})\)/g, " $1 ");
+    for (const raw of links.split(/\s+/)) {
+        // No repo path is this long; trimming pasted junk one bracket at a time would stall the prompt hook.
+        if (raw.length > MAX_PATH_TOKEN_CHARS)
+            continue;
+        let token = trimPathToken(raw).replace(/\\/g, "/").replace(/:\d+(?:[:-]\d+)?$/, "");
+        if (!token || /^[a-z][a-z0-9+.-]*:\/\//i.test(token))
+            continue;
+        if (!token.includes("/") && !/\.[a-z0-9]{1,8}$/i.test(token))
+            continue;
+        if (rootPrefix) {
+            const foldCase = process.platform === "win32" || /^[a-z]:\//i.test(token);
+            if (foldCase ? token.toLowerCase().startsWith(rootPrefix.toLowerCase()) : token.startsWith(rootPrefix))
+                token = token.slice(rootPrefix.length);
+        }
+        token = token.replace(/^(?:\.\/)+/, "");
+        // Absolute (outside the root) or parent-relative paths name nothing in this repo.
+        if (!token || token.startsWith("/") || /^[a-z]:/i.test(token) || token.split("/").includes(".."))
+            continue;
+        out.add(token);
+    }
+    return [...out];
+}
+/** Score live records against one prompt. Text fields per kind (title + rationale):
+ *  decision title/context/decision; bug title/symptom/root_cause; constraint
+ *  statement/rationale; finding title/observation. Path anchors: decision
+ *  related_files, bug/finding affected_files, constraint scope globs. Priority
+ *  ties break on the builder profile's kind/severity score in delivery.ts. */
+export function selectForTask(records, promptText, opts = {}) {
+    const k = Math.max(0, opts.k ?? DEFAULT_K);
+    const taskTerms = lexicalTokens(promptText ?? "");
+    // Without an existence check (pure/offline) only a slashed token is trusted as a
+    // path: "e.g.", "Node.js" or "v1.2" would otherwise match a broad glob.
+    const paths = promptPaths(promptText ?? "", opts.root).filter((p) => opts.pathExists ? opts.pathExists(p) : p.includes("/"));
+    if (!taskTerms.size && !paths.length)
+        return { qualifying: [], top: [] };
+    const base = PROFILE_BASE_SCORE.builder;
+    // Tokenize every record once: the same tokens feed the document frequency and the score.
+    const candidates = [];
+    const consider = (id, kind, title, text, anchors, priority, listable) => {
+        candidates.push({ id, kind, title, tokens: lexicalTokens(text.join(" ")), anchors, priority, listable });
+    };
+    for (const c of records.constraints) {
+        consider(c.id, "constraint", c.statement, [c.statement, c.rationale], c.scope, base.constraints + SEVERITY[c.severity] * 10 + (c.provenance.confidence ?? 0), c.severity !== "blocking");
+    }
+    for (const d of records.decisions) {
+        consider(d.id, "decision", d.title, [d.title, d.context, d.decision], d.related_files, base.decisions + (d.status === "accepted" ? 20 : 0) + (d.provenance.confidence ?? 0), true);
+    }
+    for (const b of records.bugs) {
+        consider(b.id, "bug", b.title, [b.title, b.symptom, b.root_cause], b.affected_files, base.bugs + SEVERITY[b.severity] * 10 + (b.status === "open" || b.status === "regressed" ? 10 : 0), true);
+    }
+    for (const f of records.findings) {
+        consider(f.id, "finding", f.title, [f.title, f.observation], f.affected_files, base.findings + SEVERITY[f.severity] * 10, true);
+    }
+    const dfCap = Math.max(MIN_DF_CAP, Math.ceil(DF_CAP_RATIO * candidates.length));
+    const rareTerms = [...taskTerms].filter((term) => candidates.filter((c) => c.tokens.has(term)).length <= dfCap);
+    const scored = [];
+    for (const { tokens, anchors, ...rest } of candidates) {
+        let terms = 0;
+        for (const term of rareTerms)
+            if (tokens.has(term))
+                terms++;
+        const pathHits = paths.filter((p) => anchors.some((anchor) => pathMatchesGlob(p, anchor))).length;
+        if (pathHits > 0 || terms >= MIN_DISTINCT_TERMS)
+            scored.push({ ...rest, pathHits, terms });
+    }
+    // A record anchored to more of the files the prompt names outranks one that
+    // shares a single (often hub) file with it; rare terms break the remaining ties.
+    scored.sort((a, b) => b.pathHits - a.pathHits || b.terms - a.terms || b.priority - a.priority || a.id.localeCompare(b.id));
+    return {
+        qualifying: scored.map((s) => s.id),
+        top: scored.filter((s) => s.listable).slice(0, k).map(({ id, kind, title }) => ({ id, kind, title })),
+    };
+}
+//# sourceMappingURL=taskSelection.js.map

package/dist/integrations/providers.js

@@ -364,7 +364,8 @@ export function writeCodexHooks(root, inv) {
     return writeHookConfig(file, {
         SessionStart: [entry()],
         UserPromptSubmit: [entry()],
-        PreToolUse: [entry("apply_patch")],
+        // The shell entries take the baseline a shell write is measured from.
+        PreToolUse: [entry("apply_patch|Bash|PowerShell|shell|local_shell")],
         // Codex's native command tool arrives as `Bash` (or `PowerShell` on
         // Windows), while older hosts may expose shell/local_shell names.
         PostToolUse: [entry("apply_patch|Bash|PowerShell|shell|local_shell")],

package/dist/integrations/scaffold.js

@@ -180,9 +180,10 @@ export function installClaudeHooks(root, hookCmd) {
         }
     }
     const keep = (arr) => (Array.isArray(arr) ? arr.map((entry) => withoutHunchCommands(entry, hookCmd)).filter((e) => e !== null) : []);
+    // Shell tools too: their PreToolUse takes the baseline a shell write is measured from.
     json.hooks.PreToolUse = [
         ...keep(json.hooks.PreToolUse),
-        { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: hookCmd }] },
+        { matcher: "Edit|Write|MultiEdit|Bash|PowerShell", hooks: [{ type: "command", command: hookCmd }] },
     ];
     json.hooks.UserPromptSubmit = [
         ...keep(json.hooks.UserPromptSubmit),

package/dist/mcp/taskReportTools.js

@@ -90,7 +90,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                 const launcher = verificationLauncher();
                 // Compact by design (#370): the rules an agent needs to act, and exact
                 // identities; scope, title and timestamps stay in `hunch report <id> --json`.
-                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to hunch_context and every decision/correction/finding capture (a capture is not proof of a commit or push). To claim an application, copy occurrence_id, record_id and content_hash exactly from hunch_report(task_id) application_references, with the action you took; omit applications you did not make. Before the final response, finish with hunch_task (outcome "interrupted" if cut short) and include its contribution card verbatim, Evidence line and agent-reported label included, unless presentation_enabled is false. Never rerun an expensive check only for reporting; missing evidence stays unverified. Checks, with this exact installation (a global hunch may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]${launcher.note} (15-minute default; --timeout <seconds> before -- for longer).` }], structuredContent: { task: { task_id: task.task_id, state: task.state }, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
+                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to hunch_context and every decision/correction/finding capture (a capture is not proof of a commit or push). To claim an application, copy occurrence_id, record_id and content_hash exactly from hunch_report(task_id) application_references, with the action you took; omit applications you did not make. Before the final response, finish with hunch_task (outcome "interrupted" if cut short) and include its contribution card verbatim, Evidence line and agent-reported label included, unless presentation_enabled is false. Never rerun an expensive check only for reporting; missing evidence stays unverified. Checks, with this exact installation (a global hunch may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]${launcher.note} Verify with the tests that cover your change (the files you edited and their tests); the full suite is CI's job. The default budget is 15 minutes; --timeout <seconds> before -- is only for when the whole suite is really needed.` }], structuredContent: { task: { task_id: task.task_id, state: task.state }, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
             }
             if (!task_id)
                 throw new Error("finish requires the exact task_id");

package/package.json

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

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.42.0",
+  "version": "1.43.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.42.0",
+      "version": "1.43.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {