@davesheffer/hunch 1.35.0 → 1.37.0

package/dist/cli/index.js

@@ -66,6 +66,8 @@ import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refre
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatSearchHit, formatStructure } from "../core/format.js";
 import { isStateKind, renderStateLine, stateSupplements } from "../core/stateDelivery.js";
+import { taskSelectionSupplements } from "../core/taskDelivery.js";
+import { buildTaskRankingQuery } from "../core/taskQuery.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
@@ -3884,7 +3886,7 @@ program
         }
         else {
             console.log("");
-            renderPolicyEvaluations(policyResults).forEach((line) => console.log(line));
+            renderPolicyEvaluations(policyResults, { compact: true }).forEach((line) => console.log(line));
         }
     }
     if (sarif) {
@@ -4210,7 +4212,7 @@ program
         decisionCorpus: store.recs("decisions"),
         historical: !!asOf,
         profile: opts.profile,
-        supplements: stateGrounding,
+        supplements: [...stateGrounding, ...(asOf ? [] : taskSelectionSupplements(store.selectTasksFor(target, buildTaskRankingQuery(root, opts.task ?? null, target)), target))],
     });
     process.stdout.write(envelope.text);
     if (opts.task) {
@@ -4880,6 +4882,7 @@ program
         // 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.selectTasksFor(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target)), target);
         const hasContent = ctx.constraints.length ||
             ctx.decisions.length ||
             ctx.bugs.length ||
@@ -4888,6 +4891,7 @@ program
             ctx.landscape?.resources.length ||
             ctx.landscape?.relationships.length ||
             retired.length ||
+            recentTasks.length ||
             docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
@@ -4905,6 +4909,7 @@ program
                         text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
                     }] : []),
                 ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
+                ...recentTasks,
             ],
         });
         const text = envelope.text.trim();
@@ -4914,19 +4919,27 @@ program
         // Delivery receipts (dec_925f4bcaad): the ledger of what actually reached
         // an agent. A full injection is a serve; a delta one-liner attests the
         // earlier serve is still standing. Never throws, never blocks.
-        const receipts = (event) => recordServed(root, envelope.delivered.map((item) => ({
-            event,
-            kind: item.kind,
-            record_id: item.record_id,
-            target,
-            session_id: evt.session_id,
-            rank: item.rank,
-            delivery_reason: item.delivery_reason,
-            provenance_status: item.provenance_status,
-            token_cost: item.token_cost,
-            delivery_profile: envelope.profile,
-            ranking_policy: envelope.ranking_policy,
-        })));
+        const receipts = (event) => recordServed(root, [
+            ...envelope.delivered.map((item) => ({
+                event,
+                kind: item.kind,
+                record_id: item.record_id,
+                target,
+                session_id: evt.session_id,
+                rank: item.rank,
+                delivery_reason: item.delivery_reason,
+                provenance_status: item.provenance_status,
+                token_cost: item.token_cost,
+                delivery_profile: envelope.profile,
+                ranking_policy: envelope.ranking_policy,
+            })),
+            // Delivered task lines are receipts too: they feed access-based recency.
+            ...envelope.supplements.filter((s) => s.kind === "recent-task" && s.delivered).map((s) => ({
+                event, kind: "tasks", record_id: s.id, target, session_id: evt.session_id,
+                rank: s.rank, delivery_reason: "supplemental", token_cost: s.token_cost,
+                delivery_profile: envelope.profile, ranking_policy: envelope.ranking_policy,
+            })),
+        ]);
         const reportTaskId = hookReportTaskId(root, provider, evt);
         // A new authoritative prompt gets its own full delivery. An earlier
         // prompt's session-level delta cannot establish this task's receipt.

package/dist/cli/taskReport.js

@@ -8,6 +8,8 @@ import { renderTaskReport, writeTaskReportHtml } from "../core/taskReportRender.
 import { assertReportPath } from "../core/taskReportPaths.js";
 import { publicTaskReport } from "../core/taskReportPublic.js";
 import { mergeDurableTaskSummaries, persistTaskRecord } from "../core/taskRecord.js";
+import { evaluateTaskRanking, renderRankEval } from "../core/taskRankEval.js";
+import { taskRecordStats } from "../core/taskRecordStats.js";
 export function registerTaskReportCommands(program, openStore) {
     const task = program.command("task").description("Record an explicit task lifecycle for Hunch contribution reports");
     task.command("start <title>").option("--id <id>", "retry an exact existing task identity")
@@ -106,6 +108,37 @@ export function registerTaskReportCommands(program, openStore) {
         console.log(`  memory saved                  ${stats.with_save}  ${pct(stats.with_save)}`);
         console.log(`  edit denied                   ${stats.with_refusal}  ${pct(stats.with_refusal)}`);
         console.log(`  nothing observed              ${stats.empty}  ${pct(stats.empty)}`);
+        // Graph-record proxies (dec_66925aa0ee): do agents redo verified work, or repeat a violation?
+        try {
+            const opened = openStore();
+            try {
+                const rs = taskRecordStats(opened.store.recs("tasks"));
+                const rate = (r, n) => r === null ? "–" : `${Math.round(r * 100)}% of ${n}`;
+                console.log(`Graph task records: ${rs.records}`);
+                console.log(`  re-verified an earlier check (24h)  ${rate(rs.reverification_rate, rs.reverify_candidates)}`);
+                console.log(`  repeated an earlier violation       ${rate(rs.repeat_violation_rate, rs.violation_candidates)}`);
+            }
+            finally {
+                opened.store.close();
+            }
+        }
+        catch { /* no store: ledger stats only */ }
+    });
+    task.command("rank-eval").description("Offline leave-one-out check of task-record ranking against 'latest 3 on the file' (Hit@5, MRR, paired bootstrap CI); the pre-registered metric behind dec_66925aa0ee")
+        .option("--since <days>", "only task records finished in the last N days", "365")
+        .option("--split <fraction>", "evaluate the newest fraction of cases (temporal split)", "0.3")
+        .option("--json", "machine-readable report")
+        .action((opts) => {
+        const { store } = openStore();
+        try {
+            const cutoff = Date.now() - (Number(opts.since) || 365) * 86_400_000;
+            const records = store.recs("tasks").filter((r) => (Date.parse(r.finished_at) || 0) >= cutoff);
+            const report = evaluateTaskRanking(records, { split: Math.min(1, Math.max(0.05, Number(opts.split) || 0.3)) });
+            console.log(opts.json ? JSON.stringify(report, null, 2) : renderRankEval(report));
+        }
+        finally {
+            store.close();
+        }
     });
     task.command("status").description("One line for a terminal status line: the current prompt's task when Claude Code's status-line JSON arrives on stdin, otherwise the most recent task here")
         .option("--json", "machine-readable summary")

package/dist/constitution/renderEvaluations.d.ts

@@ -5,4 +5,10 @@
  * environmental reason read as one actionable block instead of ten
  * (fnd_b421b3f7ab); satisfied and violated policies always stay one per line. */
 import type { PolicyEvaluationSet } from "./service.js";
-export declare function renderPolicyEvaluations(results: PolicyEvaluationSet[]): string[];
+export interface RenderPolicyOptions {
+    /** Commit-time rendering: a grouped non-evaluation is one line and satisfied
+     * receipts collapse to one line. Violations, blocks and gate errors always
+     * render in full. `hunch policy evaluate` keeps the complete form. */
+    compact?: boolean;
+}
+export declare function renderPolicyEvaluations(results: PolicyEvaluationSet[], options?: RenderPolicyOptions): string[];

package/dist/constitution/renderEvaluations.js

@@ -7,10 +7,25 @@ function groupKey(r) {
         return `one ${r.policy.id}`;
     return `${r.policy.state} ${result} ${r.evaluation.explanation}`;
 }
-export function renderPolicyEvaluations(results) {
+/** The cause of a grouped non-evaluation in a few words: the explanation up to
+ * its first parenthesis, semicolon or dash, so "no dependency snapshot cache
+ * exists on this machine (.hunch-cache/behavior-deps); executable behavior …"
+ * reads as its first clause. */
+function shortCause(explanation) {
+    const cut = explanation.split(/[(;]| — /)[0].trim();
+    return cut.length > 110 ? `${cut.slice(0, 109).trimEnd()}…` : cut;
+}
+export function renderPolicyEvaluations(results, options = {}) {
     if (!results.length)
         return ["No Constitution policies matched."];
     const out = [`Constitution policy evaluation: ${results.length} canonical receipt(s)`];
+    if (options.compact) {
+        const satisfied = results.filter((r) => r.evaluation.result === "satisfied" && !r.blocks && !r.gate_error);
+        if (satisfied.length > 1) {
+            out.push(`  ✅ ${satisfied.length} policies satisfied: ${satisfied.map((r) => r.policy.id).join(", ")}`);
+            results = results.filter((r) => !satisfied.includes(r));
+        }
+    }
     const groups = new Map();
     for (const r of results) {
         const key = groupKey(r);
@@ -29,6 +44,11 @@ export function renderPolicyEvaluations(results) {
                 rendered.add(member);
             const ids = members.map((m) => m.policy.id);
             const receipts = members.map((m) => `${m.policy.id}=${m.evaluation.deterministic_hash.slice(0, 17)}`);
+            if (options.compact) {
+                // One line per cause at commit time; the ids and receipts are one command away.
+                out.push(`  ${icon} ${members.length} policies [${r.policy.state}] ${r.evaluation.result} — ${shortCause(r.evaluation.explanation)} · hunch policy evaluate for ids and receipts`);
+                continue;
+            }
             out.push(`  ${icon} ${members.length} policies [${r.policy.state}] ${r.evaluation.result} — same cause`);
             out.push(`     ${r.evaluation.explanation}`);
             out.push(`     policies: ${ids.join(", ")}`);

package/dist/core/cochange.d.ts

@@ -0,0 +1,15 @@
+import type { CochangeStrength } from "./taskRanking.js";
+export interface CochangeOptions {
+    /** Commits touching the target to inspect (newest first). */
+    maxCommits?: number;
+    /** Commits touching more files than this are bulk moves, not coupling. */
+    maxFilesPerCommit?: number;
+    timeoutMs?: number;
+    /** Set false to bypass the .hunch-cache read/write (tests). */
+    cache?: boolean;
+}
+/** Parse `git log --format=%H --name-only` output into per-commit file lists. */
+export declare function parseNameOnlyLog(output: string): string[][];
+/** Co-change strength for every file that changed with `file`. */
+export declare function computeCochange(commits: readonly (readonly string[])[], file: string, maxFilesPerCommit: number): Map<string, CochangeStrength>;
+export declare function cochangeFor(root: string, file: string, options?: CochangeOptions): Map<string, CochangeStrength>;

package/dist/core/cochange.js

@@ -0,0 +1,113 @@
+/** Co-change (evolutionary coupling) for one file, from git history.
+ *
+ * Files that changed together with the target in past commits are a
+ * deterministic proximity signal (Zimmermann et al. ROSE; Ying et al.): a
+ * task that touched such a file is about the same place even when the paths
+ * differ. Bounded on purpose: the last N commits touching the target, bulk
+ * commits ignored, a hard time limit, and a per-HEAD cache under
+ * .hunch-cache so the pre-edit hook never pays twice. Any failure yields an
+ * empty map — the ranking term goes to zero, nothing throws. */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+function gitEnv() {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (!k.startsWith("GIT_"))
+            env[k] = v;
+    env.GIT_OPTIONAL_LOCKS = "0";
+    env.GIT_TERMINAL_PROMPT = "0";
+    return env;
+}
+function headSha(root, env, timeoutMs) {
+    try {
+        return execFileSync("git", ["-C", root, "rev-parse", "HEAD"], { env, timeout: timeoutMs, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse `git log --format=%H --name-only` output into per-commit file lists. */
+export function parseNameOnlyLog(output) {
+    const commits = [];
+    let current = null;
+    for (const raw of output.split("\n")) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (/^[0-9a-f]{40}$/.test(line)) {
+            current = [];
+            commits.push(current);
+            continue;
+        }
+        current?.push(line.replace(/\\/g, "/"));
+    }
+    return commits;
+}
+/** Co-change strength for every file that changed with `file`. */
+export function computeCochange(commits, file, maxFilesPerCommit) {
+    const target = file.replace(/\\/g, "/");
+    const counts = new Map();
+    let touching = 0;
+    for (const files of commits) {
+        if (!files.includes(target) || files.length > maxFilesPerCommit)
+            continue;
+        touching++;
+        for (const f of files)
+            if (f !== target)
+                counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+    const out = new Map();
+    if (!touching)
+        return out;
+    for (const [f, count] of counts)
+        out.set(f, { count, strength: count / touching });
+    return out;
+}
+export function cochangeFor(root, file, options = {}) {
+    const maxCommits = options.maxCommits ?? 500;
+    const maxFiles = options.maxFilesPerCommit ?? 30;
+    const timeoutMs = options.timeoutMs ?? 2_000;
+    const target = file.replace(/\\/g, "/");
+    const env = gitEnv();
+    const head = headSha(root, env, timeoutMs);
+    if (!head)
+        return new Map();
+    const cacheDir = join(root, ".hunch-cache", "cochange");
+    const cacheFile = join(cacheDir, `${head.slice(0, 12)}-${createHash("sha256").update(`${target}\n${maxCommits}\n${maxFiles}`).digest("hex").slice(0, 16)}.json`);
+    if (options.cache !== false && existsSync(cacheFile)) {
+        try {
+            const parsed = JSON.parse(readFileSync(cacheFile, "utf8"));
+            return new Map(Object.entries(parsed));
+        }
+        catch { /* recompute */ }
+    }
+    // `git log -- <file> --name-only` lists only files matching the pathspec, so
+    // co-changed files would never appear. Two steps: the commits that touched the
+    // target, then each commit's complete file list.
+    let output;
+    try {
+        const shas = execFileSync("git", ["-C", root, "log", "--format=%H", "-n", String(maxCommits), "--", target], {
+            env, timeout: timeoutMs, encoding: "utf8", maxBuffer: 4_000_000, stdio: ["ignore", "pipe", "ignore"],
+        }).split(/\r?\n/).filter((line) => /^[0-9a-f]{40}$/.test(line));
+        if (!shas.length)
+            return new Map();
+        output = execFileSync("git", ["-C", root, "show", "--format=%H", "--name-only", "--no-renames", ...shas], {
+            env, timeout: timeoutMs, encoding: "utf8", maxBuffer: 16_000_000, stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return new Map();
+    }
+    const result = computeCochange(parseNameOnlyLog(output), target, maxFiles);
+    if (options.cache !== false) {
+        try {
+            mkdirSync(cacheDir, { recursive: true });
+            writeFileSync(cacheFile, JSON.stringify(Object.fromEntries(result)));
+        }
+        catch { /* cache is a convenience */ }
+    }
+    return result;
+}
+//# sourceMappingURL=cochange.js.map

package/dist/core/spawnCommand.d.ts

@@ -0,0 +1,14 @@
+export interface ResolvedSpawn {
+    file: string;
+    args: string[];
+    /** Set when a batch launcher runs through cmd.exe and the line is pre-quoted. */
+    windowsVerbatimArguments?: boolean;
+    how: "direct" | "npm-cli" | "pathext" | "cmd-shim";
+}
+export interface SpawnResolveOptions {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    exists?: (path: string) => boolean;
+}
+export declare function resolveSpawnCommand(command: readonly string[], options?: SpawnResolveOptions): ResolvedSpawn;

package/dist/core/spawnCommand.js

@@ -0,0 +1,61 @@
+/** Resolve a user-supplied argv into something `spawn` can run without a shell.
+ *
+ * On POSIX the argv is already right. On Windows, `spawn("npx", ...)` with
+ * `shell: false` fails: the launcher is `npx.cmd`, and Node refuses to run
+ * `.cmd`/`.bat` files directly. The verification runner used to swallow that
+ * as `exit_code: null`, so every contribution card on Windows said "no
+ * independent command result". This keeps `shell: false` for real
+ * executables and only routes batch launchers through `cmd.exe`, with the
+ * npm/npx launchers run as plain Node scripts (no shell at all). */
+import { existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+/** cmd.exe quoting for one argument: wrap when it has whitespace or shell
+ * metacharacters; double embedded quotes. Good for test/build commands; a
+ * deliberately hostile argument still cannot escape because the whole line is
+ * passed as one `/s /c "..."` token. */
+function quoteForCmd(arg) {
+    if (arg === "")
+        return '""';
+    if (!/[\s"&|<>^()%!]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+export function resolveSpawnCommand(command, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const [cmd = "", ...args] = command;
+    if (platform !== "win32")
+        return { file: cmd, args, how: "direct" };
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? existsSync;
+    const execPath = options.execPath ?? process.execPath;
+    // Resolve Windows paths with Windows semantics even when the resolution is
+    // exercised (tested) on another platform; the host's default `path` is POSIX there.
+    const { join, dirname } = platform === "win32" ? win32 : posix;
+    // npm / npx: run the CLI script with this same Node. No shim, no shell.
+    if (/^(npm|npx)$/i.test(cmd)) {
+        const script = join(dirname(execPath), "node_modules", "npm", "bin", `${cmd.toLowerCase()}-cli.js`);
+        if (exists(script))
+            return { file: execPath, args: [script, ...args], how: "npm-cli" };
+    }
+    // A path or an explicit executable extension: spawn as given.
+    if (/[\\/]/.test(cmd) || /\.(exe|com)$/i.test(cmd))
+        return { file: cmd, args, how: "direct" };
+    const pathExt = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim()).filter(Boolean);
+    const dirs = (env.PATH ?? env.Path ?? "").split(";").map((d) => d.trim()).filter(Boolean);
+    for (const dir of dirs) {
+        for (const ext of ["", ...pathExt]) {
+            const candidate = join(dir, cmd + ext);
+            if (!exists(candidate))
+                continue;
+            if (/\.(cmd|bat)$/i.test(candidate)) {
+                const line = [candidate, ...args].map(quoteForCmd).join(" ");
+                return { file: env.ComSpec ?? "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true, how: "cmd-shim" };
+            }
+            if (ext === "" && !/\.(exe|com)$/i.test(candidate))
+                continue; // an extensionless file is not runnable on Windows
+            return { file: candidate, args, how: "pathext" };
+        }
+    }
+    return { file: cmd, args, how: "direct" };
+}
+//# sourceMappingURL=spawnCommand.js.map

package/dist/core/taskDelivery.d.ts

@@ -0,0 +1,19 @@
+/** Recent finished tasks as delivered context.
+ *
+ * Task records (`.hunch/tasks/`) say what earlier agent work did around a file:
+ * which lessons it received, what it applied, saved and checked, and whether a
+ * rule was violated. Delivering the newest few next to the invariants lets the
+ * next agent build on verified work instead of rediscovering it. Supplements
+ * share the brief's budget and are advisory: a task line is history, never a
+ * rule, and never an instruction to repeat or skip anything. */
+import type { DeliverySupplement } from "./delivery.js";
+import type { TaskSelection } from "./taskRanking.js";
+import type { TaskRecord } from "./types.js";
+export declare const TASK_SUPPLEMENT_LIMIT = 3;
+/** One bounded line for a task: identity, when, what reached it, what it did. */
+export declare function describeTaskRecord(t: TaskRecord): string;
+/** Render a ranked, slotted selection (dec_66925aa0ee): one line per pick with
+ * its slot and the two strongest factual reasons. Empty selection → nothing. */
+export declare function taskSelectionSupplements(selection: TaskSelection, target: string): DeliverySupplement[];
+/** Newest first, bounded. Empty input yields no supplement at all (no header noise). */
+export declare function taskSupplements(tasks: readonly TaskRecord[], target: string, limit?: number): DeliverySupplement[];

package/dist/core/taskDelivery.js

@@ -0,0 +1,68 @@
+export const TASK_SUPPLEMENT_LIMIT = 3;
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+/** One bounded line for a task: identity, when, what reached it, what it did. */
+export function describeTaskRecord(t) {
+    const when = t.finished_at.slice(0, 10);
+    const lessons = t.lessons.length
+        ? `${t.lessons.length} lesson(s): ${t.lessons.slice(0, 3).map((l) => l.record_id).join(", ")}${t.lessons.length > 3 ? "…" : ""}`
+        : "no memory delivered";
+    const applied = t.applied.length
+        ? `applied ${t.applied.length} (${t.applied.some((a) => a.supported_by) ? "rule-supported" : "agent-reported"})`
+        : null;
+    const saved = t.saved.length ? `saved ${t.saved.slice(0, 3).map((s) => s.record_id).join(", ")}${t.saved.length > 3 ? "…" : ""}` : null;
+    const last = t.checks.at(-1);
+    const check = last ? `check "${clip(last.label, 40)}" ${last.state}` : "no check recorded";
+    const violated = t.conformance.some((c) => c.outcome === "violated") ? "RULE VIOLATED" : null;
+    const denied = t.refusals ? `${t.refusals} edit(s) denied` : null;
+    const files = t.files.length ? `files ${t.files.slice(0, 4).join(", ")}${t.files.length > 4 ? "…" : ""}` : null;
+    return `${t.id} · ${when} · ${t.state} · "${clip(t.title, 80)}" — ${[lessons, applied, saved, check, violated, denied, files].filter(Boolean).join(" · ")}`;
+}
+function summarizeRecord(t) {
+    const lessons = t.lessons.length ? `${t.lessons.length} lesson(s)` : "no memory delivered";
+    const applied = t.applied.length ? `applied ${t.applied.length}` : null;
+    const saved = t.saved.length ? `saved ${t.saved.length}` : null;
+    const last = t.checks.at(-1);
+    const check = last ? `check ${last.state}` : null;
+    return [lessons, applied, saved, check].filter(Boolean).join(", ");
+}
+const SLOT_LABEL = { latest: "latest  ", violation: "problem ", relevant: "relevant" };
+/** Render a ranked, slotted selection (dec_66925aa0ee): one line per pick with
+ * its slot and the two strongest factual reasons. Empty selection → nothing. */
+export function taskSelectionSupplements(selection, target) {
+    if (!selection.picks.length)
+        return [];
+    const counts = { latest: 0, violation: 0, relevant: 0 };
+    for (const p of selection.picks)
+        counts[p.slot]++;
+    const parts = [counts.latest ? "latest" : null, counts.violation ? "problem" : null, counts.relevant ? `relevant ${counts.relevant}` : null].filter(Boolean).join(" · ");
+    return [
+        {
+            id: "recent-tasks", kind: "recent-tasks", priority: 415,
+            text: `RECENT TASKS on ${target} — ${parts} — earlier agent work here, from graph memory (advisory history, not rules): build on what was verified instead of redoing it blind.${selection.more > 0 ? ` ${selection.more} more: hunch task list ${target}.` : ""}`,
+        },
+        ...selection.picks.map((p, i) => {
+            const t = p.ranked.record;
+            const reasons = p.ranked.reasons.slice(0, 2).join(" · ");
+            return { id: t.id, kind: "recent-task", priority: 414 - i, text: `${SLOT_LABEL[p.slot]} ${t.id} · ${t.finished_at.slice(0, 10)} · "${clip(t.title, 80)}" — ${reasons} · ${summarizeRecord(t)}` };
+        }),
+    ];
+}
+/** Newest first, bounded. Empty input yields no supplement at all (no header noise). */
+export function taskSupplements(tasks, target, limit = TASK_SUPPLEMENT_LIMIT) {
+    const recent = [...tasks]
+        .sort((a, b) => b.finished_at.localeCompare(a.finished_at) || a.id.localeCompare(b.id))
+        .slice(0, Math.max(1, limit));
+    if (!recent.length)
+        return [];
+    const older = tasks.length - recent.length;
+    return [
+        {
+            id: "recent-tasks", kind: "recent-tasks", priority: 415,
+            text: `RECENT TASKS on ${target} — earlier agent work here, from graph memory (advisory history, not rules): build on what was verified instead of redoing it blind.${older > 0 ? ` ${older} older task(s) not shown; hunch task list.` : ""}`,
+        },
+        ...recent.map((t, i) => ({ id: t.id, kind: "recent-task", priority: 414 - i, text: describeTaskRecord(t) })),
+    ];
+}
+//# sourceMappingURL=taskDelivery.js.map

package/dist/core/taskQuery.d.ts

@@ -0,0 +1,7 @@
+import { type RankingQuery } from "./taskRanking.js";
+export interface TaskQueryOptions {
+    /** A phrase the caller has (hunch_context's target when it is not a path). */
+    phrase?: string | null;
+    now?: number;
+}
+export declare function buildTaskRankingQuery(root: string, taskId: string | null | undefined, target: string, options?: TaskQueryOptions): RankingQuery;

package/dist/core/taskQuery.js

@@ -0,0 +1,44 @@
+/** The agent's own context as a ranking query.
+ *
+ * What a task has already done is the best statement of what it is doing:
+ * the files context was delivered for, the rules and decisions it received,
+ * applied or saved, and its title when the repository opted into prompt
+ * titles. All of it is already in the local ledger; nothing new is stored and
+ * no prompt text is read. Without a task id the query is the target alone. */
+import { readTaskReport } from "./taskReport.js";
+import { targetLooksLikePath } from "./taskRecord.js";
+import { normalizePath } from "./taskRanking.js";
+const GENERIC_TITLES = new Set(["Assistant task", "Claude task"]);
+export function buildTaskRankingQuery(root, taskId, target, options = {}) {
+    const now = options.now ?? Date.now();
+    const files = new Set();
+    const recordIds = new Set();
+    let phrase = options.phrase && !targetLooksLikePath(options.phrase) ? options.phrase : null;
+    if (targetLooksLikePath(target))
+        files.add(normalizePath(target));
+    else if (!phrase)
+        phrase = target;
+    if (taskId) {
+        try {
+            const report = readTaskReport(root, taskId);
+            for (const d of report.deliveries) {
+                if (d.target && targetLooksLikePath(d.target))
+                    files.add(normalizePath(d.target));
+                for (const r of d.records)
+                    recordIds.add(r.record_id);
+            }
+            for (const c of report.conformance)
+                for (const f of c.files)
+                    files.add(normalizePath(f));
+            for (const c of report.claims)
+                recordIds.add(c.record_id);
+            for (const s of report.saves)
+                recordIds.add(s.record.record_id);
+            if (!GENERIC_TITLES.has(report.task.title))
+                phrase = phrase ?? report.task.title;
+        }
+        catch { /* an unreadable ledger degrades to a target-only query */ }
+    }
+    return { target: normalizePath(target), files, recordIds, phrase, now };
+}
+//# sourceMappingURL=taskQuery.js.map

package/dist/core/taskRankEval.d.ts

@@ -0,0 +1,70 @@
+/** Offline evaluation of task-record ranking (dec_66925aa0ee, PR B).
+ *
+ * Leave-one-out over finished task records: for each task T, rank the tasks
+ * that finished before it with a query built from T's own record, and ask
+ * whether the records T evidently needed appear in the five slots. Compared
+ * against the previous behaviour ("latest 3 on the file") with a paired
+ * bootstrap confidence interval. Deterministic: seeded resampling, no clock.
+ *
+ * Ground truth is what the record itself proves T used: an older task that
+ * received or saved a record T applied, that ran the same check T ran on an
+ * overlapping file, or whose violated rule T received. This is a proxy, not a
+ * label; the metric is pre-registered so the ranker cannot be tuned to it and
+ * then evaluated on the same window. */
+import { type RankingContext, type RankingQuery, type RankingWeights } from "./taskRanking.js";
+import type { TaskRecord } from "./types.js";
+export declare const TASK_RANK_EVAL_SCHEMA: "hunch.task-rank-eval/1";
+export interface EvalCase {
+    task: TaskRecord;
+    file: string;
+    older: TaskRecord[];
+    truth: Set<string>;
+}
+export interface RankerScore {
+    name: string;
+    hit5: number;
+    mrr: number;
+    hits: number[];
+}
+export interface RankEvalReport {
+    schema: typeof TASK_RANK_EVAL_SCHEMA;
+    tasks: number;
+    evaluable: number;
+    split: {
+        fraction: number;
+        evaluated: number;
+        note: string | null;
+    };
+    rankers: Array<Omit<RankerScore, "hits">>;
+    /** Paired difference ranked − baseline on Hit@5. */
+    delta_hit5: {
+        mean: number;
+        ci95: [number, number];
+        resamples: number;
+    };
+    verdict: "ranked-better" | "baseline-better" | "inconclusive" | "insufficient-data";
+    weights: RankingWeights;
+}
+/** What T evidently used from older tasks. */
+export declare function groundTruth(task: TaskRecord, older: readonly TaskRecord[]): Set<string>;
+/** T's own record as the query it would have had before editing. */
+export declare function evalQuery(task: TaskRecord): RankingQuery;
+/** A store-free context: IDF over the older set, lexical by token overlap. */
+export declare function pureContext(older: readonly TaskRecord[], query: RankingQuery): RankingContext;
+export declare function buildCases(records: readonly TaskRecord[]): EvalCase[];
+export type Ranker = (c: EvalCase) => string[];
+export declare function rankedRanker(weights?: Readonly<RankingWeights>): Ranker;
+export declare const latest3Ranker: Ranker;
+export declare function scoreRanker(name: string, ranker: Ranker, cases: readonly EvalCase[]): RankerScore;
+export declare function pairedBootstrap(a: readonly number[], b: readonly number[], resamples?: number, seed?: number): {
+    mean: number;
+    ci95: [number, number];
+};
+export interface RankEvalOptions {
+    split?: number;
+    minEvaluated?: number;
+    resamples?: number;
+    weights?: Readonly<RankingWeights>;
+}
+export declare function evaluateTaskRanking(records: readonly TaskRecord[], options?: RankEvalOptions): RankEvalReport;
+export declare function renderRankEval(report: RankEvalReport): string;