@davesheffer/hunch 1.41.6 → 1.43.0

package/dist/constitution/experiment.d.ts

@@ -59,8 +59,8 @@ export declare const ExperimentCaseBankSchema: z.ZodObject<{
     id: z.ZodString;
     content_hash: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     preregistration_id: z.ZodString;
     preregistration_hash: z.ZodString;
@@ -137,8 +137,8 @@ export declare const ExperimentRunSchema: z.ZodObject<{
     id: z.ZodString;
     content_hash: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     preregistration_id: z.ZodString;
     preregistration_hash: z.ZodString;
@@ -210,8 +210,8 @@ export declare const ExperimentOutcomeSchema: z.ZodObject<{
     run_id: z.ZodString;
     assignment_id: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     arm: z.ZodString;
     status: z.ZodEnum<{

package/dist/constitution/g3.d.ts

@@ -42,8 +42,8 @@ export declare const ExperimentPreregistrationSchema: z.ZodObject<{
     id: z.ZodString;
     content_hash: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     revision: z.ZodNumber;
     hypothesis: z.ZodString;

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/footprint.d.ts

@@ -0,0 +1,15 @@
+export interface FootprintSurface {
+    id: string;
+    chars: number;
+    est_tokens: number;
+    detail?: Record<string, number>;
+}
+export interface FootprintReport {
+    schema: "hunch.footprint/1";
+    estimate: "chars/4";
+    surfaces: FootprintSurface[];
+    unmeasured: string[];
+}
+export declare function measureFootprint(root: string, opts?: {
+    target?: string;
+}): Promise<FootprintReport>;

package/dist/core/footprint.js

@@ -0,0 +1,167 @@
+// Context footprint (#372): how much text Hunch injects into an agent's
+// context, measured deterministically from the same code paths the product
+// serves. Tokens are an estimate (characters / 4), not a tokenizer.
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { buildServer } from "../mcp/server.js";
+import { renderHunchSection } from "../integrations/claudemd.js";
+import { HunchStore } from "../store/hunchStore.js";
+import { hunchPaths } from "./paths.js";
+import { PIPELINE_LOOP } from "./pipeline.js";
+import { HOOK_REMINDER } from "./hookText.js";
+import { taskInstruction } from "./taskReportHook.js";
+const CONTEXT_BUDGET = 1500;
+const estTokens = (chars) => Math.ceil(chars / 4);
+const surface = (id, chars, detail) => ({ id, chars, est_tokens: estTokens(chars), ...(detail ? { detail } : {}) });
+const jsonChars = (v) => (v === undefined ? 0 : JSON.stringify(v).length);
+/** A host shows one channel of a tool result: Claude Code shows only
+ * structuredContent, text-only hosts only content. The larger one is the cost. */
+function hostVisible(id, result) {
+    const content = jsonChars(result.content), structured = jsonChars(result.structuredContent);
+    return surface(id, Math.max(content, structured), { content_chars: content, structured_chars: structured });
+}
+/** The hunch_task start and finish results for a task with one delivered lesson.
+ * Driven in a throwaway store, never `root`: a task writes a ledger row, and
+ * `taskRecords: false` keeps finish from writing or committing a graph record. */
+async function measureTaskLifecycle() {
+    const dir = mkdtempSync(join(tmpdir(), "hunch-footprint-"));
+    try {
+        // A real task runs in a git repo; the source snapshot reads git.
+        try {
+            execFileSync("git", ["init", "-q", dir], { stdio: "ignore" });
+        }
+        catch { /* measured without git */ }
+        const store = new HunchStore(hunchPaths(dir));
+        try {
+            store.json.ensureDirs();
+            writeFileSync(join(dir, ".hunch", "local.json"), JSON.stringify({ taskRecords: false, autoCommit: false }));
+            store.json.put("constraints", {
+                id: "con_footprint_sample", type: "architecture", statement: "Tool results stay machine-readable.",
+                scope: ["src/sample.ts"], severity: "blocking", enforcement: "advisory_v1", match: null, forbids: null,
+                rationale: "Orchestrators must not parse prose.", source_decision: null, violations: [], status: "active",
+                valid_from: "2026-01-01T00:00:00.000Z", valid_to: null,
+                provenance: { source: "human_confirmed", confidence: 1, evidence: [] },
+            });
+            store.reindex();
+        }
+        finally {
+            store.close();
+        }
+        const server = buildServer(dir);
+        const [ct, st] = InMemoryTransport.createLinkedPair();
+        const client = new Client({ name: "hunch-footprint", version: "1" });
+        await Promise.all([server.connect(st), client.connect(ct)]);
+        try {
+            const start = await client.callTool({ name: "hunch_task", arguments: { action: "start", title: "Assistant task" } });
+            const taskId = start.structuredContent?.task?.task_id;
+            if (start.isError || !taskId)
+                throw new Error("hunch_task start failed");
+            await client.callTool({ name: "hunch_context", arguments: { target: "src/sample.ts", task_id: taskId } });
+            const finish = await client.callTool({ name: "hunch_task", arguments: { action: "finish", task_id: taskId } });
+            if (finish.isError)
+                throw new Error("hunch_task finish failed");
+            return [hostVisible("mcp.hunch_task.start", start), hostVisible("mcp.hunch_task.finish", finish)];
+        }
+        finally {
+            await client.close();
+            await server.close();
+        }
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Surfaces built inline from live host/session state; not measurable in-process. */
+const UNMEASURED = [
+    "hook.session.orientation — SessionStart text is built inline in the `hook` command action (src/cli/index.ts) from live session state",
+    "hook.pre_edit.grounding — PreToolUse grounding is built per edited file and event",
+];
+/** The file most decisions cite — a FILE target, so the brief carries per-record
+ *  lines and omissions the way a pre-edit call does. "src" when no decision names one. */
+function busiestFile(store) {
+    const counts = new Map();
+    for (const d of store.advisoryRecs("decisions")) {
+        for (const f of new Set(d.related_files))
+            if (!f.includes("*"))
+                counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+    return [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0] ?? "src";
+}
+export async function measureFootprint(root, opts = {}) {
+    const surfaces = [];
+    let target = opts.target;
+    if (!target) {
+        const store = new HunchStore(hunchPaths(root));
+        try {
+            target = busiestFile(store);
+        }
+        finally {
+            store.close();
+        }
+    }
+    const server = buildServer(root);
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "hunch-footprint", version: "1" });
+    await Promise.all([server.connect(st), client.connect(ct)]);
+    try {
+        const tools = (await client.listTools()).tools;
+        let outputChars = 0, inputChars = 0, descriptionChars = 0, largest = 0;
+        for (const t of tools) {
+            outputChars += jsonChars(t.outputSchema);
+            inputChars += jsonChars(t.inputSchema);
+            descriptionChars += (t.description ?? "").length;
+            largest = Math.max(largest, jsonChars(t));
+        }
+        surfaces.push(surface("mcp.tools_list", jsonChars(tools), {
+            output_schema_chars: outputChars,
+            input_schema_chars: inputChars,
+            description_chars: descriptionChars,
+            tools: tools.length,
+            largest_tool_chars: largest,
+        }));
+        // What hosts that drop outputSchema actually pay.
+        const core = tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+        surfaces.push(surface("mcp.tools_list.core", jsonChars(core)));
+        const result = await client.callTool({ name: "hunch_context", arguments: { target, budget_tokens: CONTEXT_BUDGET } });
+        // A host shows the model one channel — structuredContent when it reads it,
+        // content otherwise — so the cost it pays is the larger, not the sum.
+        const contentChars = jsonChars(result.content);
+        const structuredChars = jsonChars(result.structuredContent);
+        const chars = Math.max(contentChars, structuredChars);
+        surfaces.push(surface("mcp.hunch_context", chars, {
+            content_chars: contentChars,
+            structured_chars: structuredChars,
+            budget_tokens: CONTEXT_BUDGET,
+            // est_tokens / budget, ×100 as an integer percentage.
+            budget_ratio_pct: Math.round((estTokens(chars) / CONTEXT_BUDGET) * 100),
+        }));
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+    surfaces.push(...await measureTaskLifecycle());
+    const store = new HunchStore(hunchPaths(root));
+    try {
+        surfaces.push(surface("grounding.block", renderHunchSection(store, root).length));
+    }
+    finally {
+        store.close();
+    }
+    surfaces.push(surface("hook.session.pipeline_loop", PIPELINE_LOOP.length));
+    surfaces.push(surface("hook.prompt.reminder", HOOK_REMINDER.length));
+    // Every prompt gets a task instruction: full once per session, compact after.
+    // Measured for a host whose stop hook closes the task, with a fixed installed
+    // launcher and cwd so the number does not move with the checkout path.
+    const sampleTask = { task_id: "htask_" + "0".repeat(24), title: "Assistant task" };
+    const sampleCwd = JSON.stringify("/home/user/repo");
+    const sampleLauncher = () => ({ shell: "node /home/user/repo/node_modules/@davesheffer/hunch/dist/cli/index.js" });
+    surfaces.push(surface("hook.prompt.task_instruction", taskInstruction(sampleTask, sampleCwd, "claude", sampleLauncher).length));
+    surfaces.push(surface("hook.prompt.task_instruction.compact", taskInstruction(sampleTask, sampleCwd, "claude", sampleLauncher, "compact").length));
+    return { schema: "hunch.footprint/1", estimate: "chars/4", surfaces, unmeasured: [...UNMEASURED] };
+}
+//# sourceMappingURL=footprint.js.map

package/dist/core/groundingLag.d.ts

@@ -25,6 +25,9 @@
  * run ahead (missing record). Open findings move both ways (a finding resolved on one
  * branch, a finding recorded on another), so a differing findings count alone is lag.
  */
+/** The block's prose template version (claudemd.ts GROUNDING_TEMPLATE). A block
+ *  without the stamp is template 1. */
+export declare function groundingTemplate(block: string): number;
 export interface GroundingCounts {
     decisions: number;
     bugs: number;
@@ -71,11 +74,23 @@ export type GroundingFreshness =
     committed: GroundingCounts;
     generated: GroundingCounts;
     ahead: string[];
+    newerTemplate?: {
+        committed: number;
+        renderer: number;
+    };
 }
 /** The block differs outside the counts sentence (or a counts sentence is missing). */
  | {
     kind: "diverged";
     reason: string;
+}
+/** The committed block was written by a newer renderer template than this
+ *  version's: its prose is preserved (preserveNewerTemplate), never a failure. */
+ | {
+    kind: "newer";
+    committedTemplate: number;
+    rendererTemplate: number;
+    countsReadable: boolean;
 };
 /** Classify a committed managed block against the one the graph generates NOW.
  *  Both inputs are block CONTENT (markers stripped, trimmed). */

package/dist/core/groundingLag.js

@@ -25,6 +25,13 @@
  * run ahead (missing record). Open findings move both ways (a finding resolved on one
  * branch, a finding recorded on another), so a differing findings count alone is lag.
  */
+const TEMPLATE_RE = /<!-- hunch:template (\d+) -->/;
+/** The block's prose template version (claudemd.ts GROUNDING_TEMPLATE). A block
+ *  without the stamp is template 1. */
+export function groundingTemplate(block) {
+    const m = TEMPLATE_RE.exec(block);
+    return m ? Number(m[1]) : 1;
+}
 const COUNTS_RE = /\*\*(\d+) decisions?, (\d+) bugs?, (\d+) constraints?, (\d+) components?, (\d+) polic(?:y|ies)(?:, (\d+) open findings?)?\*\*/;
 /** Record kinds whose committed count may only ever lag behind the store. */
 export const APPEND_ONLY_COUNT_KINDS = ["decisions", "bugs", "constraints", "components", "policies"];
@@ -64,8 +71,19 @@ export function parseGroundingCounts(block) {
 export function classifyGroundingBlock(committed, generated) {
     if (committed === generated)
         return { kind: "fresh" };
+    const committedTemplate = groundingTemplate(committed);
+    const rendererTemplate = groundingTemplate(generated);
     const c = parseGroundingCounts(committed);
     const g = parseGroundingCounts(generated);
+    if (committedTemplate > rendererTemplate) {
+        // A newer template may reword the prose, but a count AHEAD of the store still
+        // means the doc knows a record this repository does not carry.
+        const ahead = c && g ? APPEND_ONLY_COUNT_KINDS.filter((k) => c.counts[k] > g.counts[k]) : [];
+        if (c && g && ahead.length) {
+            return { kind: "ahead", committed: c.counts, generated: g.counts, ahead, newerTemplate: { committed: committedTemplate, renderer: rendererTemplate } };
+        }
+        return { kind: "newer", committedTemplate, rendererTemplate, countsReadable: c !== null };
+    }
     if (!c)
         return { kind: "diverged", reason: "the committed block carries no record-counts sentence" };
     if (!g)
@@ -88,9 +106,18 @@ export function describeGroundingFreshness(doc, verdict) {
         case "lagging":
             return `${doc}: counts lag the store (${delta(verdict.committed, verdict.generated, verdict.behind)}) — records merged in behind the doc; heals on the next capture or \`hunch grounding --refresh\``;
         case "ahead":
+            // A newer Hunch may have written records this version skips as unreadable, and a
+            // plain refresh keeps a newer block's prose: only an upgrade or --force settles it.
+            if (verdict.newerTemplate) {
+                return `${doc}: counts run AHEAD of the store (${delta(verdict.committed, verdict.generated, verdict.ahead)}) in a block written by a newer Hunch (template ${verdict.newerTemplate.committed} > ${verdict.newerTemplate.renderer}) — this version may skip records it cannot read, or the record was removed; upgrade Hunch, or run \`hunch grounding --refresh --force\` and commit`;
+            }
             return `${doc}: counts run AHEAD of the store (${delta(verdict.committed, verdict.generated, verdict.ahead)}) — the doc counted a record this repository does not carry; commit the missing .hunch/ record or regenerate`;
         case "diverged":
             return `${doc}: stale — ${verdict.reason}; regenerate with \`hunch grounding --refresh\` and commit`;
+        case "newer":
+            return `${doc}: written by a newer Hunch (template ${verdict.committedTemplate} > ${verdict.rendererTemplate}); ${verdict.countsReadable
+                ? "its prose is kept and a refresh updates only the counts"
+                : "this version cannot read its counts sentence, so a refresh leaves the block as written"}. Upgrade Hunch, or run \`hunch grounding --refresh --force\` to re-render with this version`;
     }
 }
 //# sourceMappingURL=groundingLag.js.map

package/dist/core/hookText.d.ts

@@ -0,0 +1,4 @@
+/** The UserPromptSubmit reminder `hunch hook` injects once per session (and with
+ *  every correction). Lives in
+ *  core so `hunch footprint` measures the exact text the hook sends. */
+export declare const HOOK_REMINDER: string;

package/dist/core/hookText.js

@@ -0,0 +1,8 @@
+/** The UserPromptSubmit reminder `hunch hook` injects once per session (and with
+ *  every correction). Lives in
+ *  core so `hunch footprint` measures the exact text the hook sends. */
+export const HOOK_REMINDER = "Hunch (engineering memory) is available for this repo. Before editing, call " +
+    "hunch_check_constraints(scope) for do-not-break invariants and hunch_why(target) " +
+    "for the rationale; use hunch_get_dependents for blast radius and hunch_bug_lineage " +
+    "for prior root causes. After a non-trivial choice, record it with hunch_record_decision.";
+//# sourceMappingURL=hookText.js.map

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/pipeline.d.ts

@@ -150,6 +150,23 @@ export interface PipelineState {
     /** Activity index and count for bounded mid-flight reminders. */
     proofReminderActivity: number;
     proofReminders: number;
+    /** Sibling-fix lessons delivered this session (see core/siblingfix.ts). */
+    lessons: PendingLesson[];
+}
+/** A delivered lesson the agent has not visibly acted on yet. `hash` is the
+ *  target function's body at delivery; a different body later means the agent
+ *  touched it, so the lesson is no longer pending. */
+export interface PendingLesson {
+    id: string;
+    file: string;
+    symbol: string;
+    sibling: string;
+    siblingFile: string;
+    /** "<sha8> <subject>" of the change the sibling received. */
+    change: string;
+    callers: string[];
+    hash: string | null;
+    reminded: boolean;
 }
 export declare const emptyState: () => PipelineState;
 /** Validate untrusted MCP/env episode data. Invalid entries are ignored so the
@@ -273,6 +290,17 @@ export declare function proofCheckpoint(before: PipelineState, after: PipelineSt
 export declare const PIPELINE_LOOP: string;
 export declare const UNVERIFIED_NAG = "Hunch pipeline: earlier product edits are still UNVERIFIED \u2014 run the relevant test/build/typecheck before claiming anything about them.";
 export declare function unverifiedNag(state: PipelineState): string;
+/** Record lessons the grounding just delivered (dedup by id; first delivery keeps its baseline). */
+export declare function onLessonsDelivered(state: PipelineState, lessons: readonly Omit<PendingLesson, "reminded">[]): PipelineState;
+/** The one follow-up an advisory lesson gets. It fires when the agent runs a
+ *  check (test/build/typecheck) while a delivered lesson's function is still
+ *  untouched: the moment the agent thinks it is done, which is when an ignored
+ *  lesson would otherwise ship. Once per lesson, never a block. `hashOf`
+ *  returns the function's current body hash (null: cannot tell, stay silent). */
+export declare function lessonReminder(state: PipelineState, command: string, hashOf: (lesson: PendingLesson) => string | null): {
+    state: PipelineState;
+    reminder: string;
+};
 /** Stop-gate verdict. Blocks only at firm/strict, only with unverified product
  *  edits, and at most twice per turn. */
 export declare function stopVerdict(state: PipelineState, firmness: Firmness): {

package/dist/core/pipeline.js

@@ -63,6 +63,7 @@ export const emptyState = () => ({
     proofActivity: 0,
     proofReminderActivity: 0,
     proofReminders: 0,
+    lessons: [],
 });
 const MAX_OBLIGATIONS = 12;
 const MAX_ALTERNATIVES = 6;
@@ -1033,6 +1034,51 @@ export function unverifiedNag(state) {
         return generic;
     return `${generic} Controller obligations still pending: ${pending.slice(0, 4).map((item) => `[${item.category}] ${item.description}`).join("; ")}.`;
 }
+const MAX_LESSONS = 6;
+/** Any profile's check shape: the reminder fires when the agent starts proving
+ *  its work, whatever the domain. */
+const CHECK_SHAPE = new RegExp([...Object.values(DEFAULT_PROFILES).map((p) => p.verify.source), "node (--test|-e\\b)"].join("|"), "i");
+/** Record lessons the grounding just delivered (dedup by id; first delivery keeps its baseline). */
+export function onLessonsDelivered(state, lessons) {
+    const known = new Set(state.lessons.map((l) => l.id));
+    const added = lessons.filter((l) => !known.has(l.id)).map((l) => ({ ...l, reminded: false }));
+    return added.length ? { ...state, lessons: [...state.lessons, ...added].slice(-MAX_LESSONS) } : state;
+}
+/** The one follow-up an advisory lesson gets. It fires when the agent runs a
+ *  check (test/build/typecheck) while a delivered lesson's function is still
+ *  untouched: the moment the agent thinks it is done, which is when an ignored
+ *  lesson would otherwise ship. Once per lesson, never a block. `hashOf`
+ *  returns the function's current body hash (null: cannot tell, stay silent). */
+export function lessonReminder(state, command, hashOf) {
+    if (!CHECK_SHAPE.test(command) || !state.lessons.some((l) => !l.reminded))
+        return { state, reminder: "" };
+    const due = [];
+    const lessons = state.lessons.map((l) => {
+        if (l.reminded)
+            return l;
+        const now = hashOf(l);
+        if (now === null || l.hash === null)
+            return l;
+        if (now !== l.hash)
+            return { ...l, reminded: true };
+        due.push(l);
+        return { ...l, reminded: true };
+    });
+    if (!due.length)
+        return { state: { ...state, lessons }, reminder: "" };
+    const lines = due.map((l) => {
+        const via = l.callers.length ? ` ${l.callers.slice(0, 3).map((c) => `\`${c}\``).join(", ")} call${l.callers.length === 1 ? "s" : ""} it, so your change runs through the copy that lacks the fix.` : "";
+        return `- \`${l.symbol}\` (${l.file}) is unchanged since Hunch showed you the change its same-shaped sibling \`${l.sibling}\` (${l.siblingFile}) received: ${l.change}.${via}`;
+    });
+    return {
+        state: { ...state, lessons },
+        reminder: [
+            "Hunch — before you finish: a lesson delivered earlier is still open.",
+            ...lines,
+            "The checks you are running were written before this lesson; unless one feeds this function the input the sibling's change handles, they do not show it is covered. Carry the change with a test. It does not apply only if that input cannot reach the function or is already handled another way; then say which in your final answer. \"Pre-existing\" or \"outside this task\" does not count: your change runs through this copy, so leaving it ships the gap again inside your change.",
+        ].join("\n"),
+    };
+}
 /** Stop-gate verdict. Blocks only at firm/strict, only with unverified product
  *  edits, and at most twice per turn. */
 export function stopVerdict(state, firmness) {
@@ -1071,6 +1117,10 @@ export function loadPipelineState(sessionId) {
         state.proofReminderActivity = Number.isSafeInteger(raw.proofReminderActivity) && raw.proofReminderActivity >= 0 ? raw.proofReminderActivity : 0;
         state.proofReminders = Number.isSafeInteger(raw.proofReminders) && raw.proofReminders >= 0 ? raw.proofReminders : 0;
         state.probeBlocks = Number.isSafeInteger(raw.probeBlocks) && raw.probeBlocks >= 0 ? raw.probeBlocks : 0;
+        state.lessons = (Array.isArray(raw.lessons) ? raw.lessons : []).filter((l) => !!l && typeof l === "object"
+            && typeof l.id === "string" && typeof l.file === "string" && typeof l.symbol === "string" && typeof l.sibling === "string"
+            && typeof l.siblingFile === "string" && typeof l.change === "string" && Array.isArray(l.callers)
+            && (l.hash === null || typeof l.hash === "string") && typeof l.reminded === "boolean").slice(-MAX_LESSONS);
         const specs = normalizeExecutionObligations(raw.obligations);
         const tracked = new Map((Array.isArray(raw.obligations) ? raw.obligations : []).map((item) => {
             const candidate = item;

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/shellwrites.d.ts

@@ -0,0 +1,7 @@
+/** Record the working tree as it stands, so later shell writes are measured
+ *  from here (a prompt, or any tool call that is not a shell command). */
+export declare function refreshShellBaseline(root: string, sessionId: string | undefined, agentId?: string): void;
+/** Repo-relative files the shell command that just ran wrote (created or
+ *  modified), and the baseline moves forward. Empty without a baseline: a
+ *  session's first observation cannot tell its own writes from earlier ones. */
+export declare function shellWrittenFiles(root: string, sessionId: string | undefined, agentId?: string): string[];