@davesheffer/hunch 1.36.0 → 1.37.1

package/dist/cli/index.js

@@ -66,7 +66,9 @@ 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 { taskSupplements } from "../core/taskDelivery.js";
+import { taskSelectionSupplements } from "../core/taskDelivery.js";
+import { buildTaskRankingQuery } from "../core/taskQuery.js";
+import { rankingStatusLine, resolveTaskRankingMode } from "../core/taskRankingMode.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
@@ -3885,7 +3887,7 @@ program
         }
         else {
             console.log("");
-            renderPolicyEvaluations(policyResults).forEach((line) => console.log(line));
+            renderPolicyEvaluations(policyResults, { compact: true }).forEach((line) => console.log(line));
         }
     }
     if (sarif) {
@@ -4211,7 +4213,7 @@ program
         decisionCorpus: store.recs("decisions"),
         historical: !!asOf,
         profile: opts.profile,
-        supplements: [...stateGrounding, ...(asOf ? [] : taskSupplements(store.tasksFor(target, 3), target))],
+        supplements: [...stateGrounding, ...(asOf ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, opts.task ?? null, target)), target))],
     });
     process.stdout.write(envelope.text);
     if (opts.task) {
@@ -4881,7 +4883,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 = taskSupplements(store.tasksFor(target, 3), target);
+        const recentTasks = taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target)), target);
         const hasContent = ctx.constraints.length ||
             ctx.decisions.length ||
             ctx.bugs.length ||
@@ -4918,19 +4920,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.
@@ -6464,6 +6474,11 @@ program
             console.log(`  • ${r.title}  (${r.id}${r.topic ? `, ${r.topic}` : ""}, since ${r.date})\n      ${r.note}`);
         if (pendingReview > 0)
             console.log(`\n  (${pendingReview} legacy un-vouched draft(s) — \`hunch adopt-drafts\` to auto-trust them as advisory)`);
+        // Task-record ranking: evaluated automatically on every task write; the kill rule applies itself.
+        try {
+            console.log(`\n📊 ${rankingStatusLine(resolveTaskRankingMode(store.publicRoot, store))}`);
+        }
+        catch { /* no task records or no cache dir: nothing to say */ }
     }
     finally {
         store.close();

package/dist/cli/taskReport.js

@@ -8,6 +8,9 @@ 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 { rankingStatusLine, refreshRankEval, resolveTaskRankingMode } from "../core/taskRankingMode.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 +109,40 @@ 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)}`);
+                console.log(`  ${rankingStatusLine(resolveTaskRankingMode(opened.root, opened.store))}`);
+            }
+            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)) });
+            // Keep the automatic cache current too, so delivery and `hunch now` agree with what was just printed.
+            refreshRankEval(findRoot(), store, { force: true });
+            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/constitution/schema.d.ts

@@ -275,11 +275,11 @@ export declare const EvidenceEventSchema: z.ZodObject<{
     }, z.core.$strict>>;
     compiler: z.ZodOptional<z.ZodObject<{
         status: z.ZodEnum<{
-            conflicted: "conflicted";
-            eligible: "eligible";
             compiled: "compiled";
+            eligible: "eligible";
             covered: "covered";
             uncompilable: "uncompilable";
+            conflicted: "conflicted";
         }>;
         policy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         reason: z.ZodDefault<z.ZodString>;

package/dist/constitution/scorecard.d.ts

@@ -10,9 +10,9 @@ export declare const CompilerCaseBankSchema: z.ZodObject<{
         evidence: z.ZodString;
         expected: z.ZodObject<{
             outcome: z.ZodEnum<{
-                conflicted: "conflicted";
                 covered: "covered";
                 uncompilable: "uncompilable";
+                conflicted: "conflicted";
                 assertion: "assertion";
             }>;
             assertion: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -97,9 +97,9 @@ export declare const CompilerCaseBankSchema: z.ZodObject<{
         }, z.core.$strict>;
         actual: z.ZodObject<{
             outcome: z.ZodEnum<{
-                conflicted: "conflicted";
                 covered: "covered";
                 uncompilable: "uncompilable";
+                conflicted: "conflicted";
                 assertion: "assertion";
             }>;
             assertion: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{

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

@@ -59,8 +59,8 @@ export declare const UsefulnessObservationSchema: z.ZodObject<{
         kind: z.ZodEnum<{
             observation: "observation";
             artifact: "artifact";
-            receipt: "receipt";
             event: "event";
+            receipt: "receipt";
             verification: "verification";
         }>;
         ref: z.ZodString;

package/dist/core/stateContract.d.ts

@@ -92,8 +92,8 @@ export declare const CaptureRequestSchema: z.ZodObject<{
     relevance: z.ZodObject<{
         use: z.ZodEnum<{
             decision: "decision";
-            constraint: "constraint";
             preference: "preference";
+            constraint: "constraint";
             operational_fact: "operational_fact";
             ongoing_issue: "ongoing_issue";
         }>;
@@ -160,8 +160,8 @@ export declare const CaptureBatchRequestSchema: z.ZodObject<{
         relevance: z.ZodObject<{
             use: z.ZodEnum<{
                 decision: "decision";
-                constraint: "constraint";
                 preference: "preference";
+                constraint: "constraint";
                 operational_fact: "operational_fact";
                 ongoing_issue: "ongoing_issue";
             }>;
@@ -255,8 +255,8 @@ export declare const ReadRequestSchema: z.ZodObject<{
     subject: z.ZodOptional<z.ZodString>;
     task: z.ZodOptional<z.ZodString>;
     profile: z.ZodOptional<z.ZodEnum<{
-        builder: "builder";
         reviewer: "reviewer";
+        builder: "builder";
         architect: "architect";
     }>>;
     budget_tokens: z.ZodOptional<z.ZodNumber>;

package/dist/core/taskDelivery.d.ts

@@ -7,9 +7,13 @@
  * 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

@@ -19,6 +19,38 @@ export function describeTaskRecord(t) {
     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 = selection.mode === "latest"
+        ? `latest ${counts.latest} (ranking off: it lost its evaluation; hunch task rank-eval)`
+        : [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]

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;