@davesheffer/hunch 1.36.0 → 1.37.1

package/dist/core/taskRankingMode.js

@@ -0,0 +1,122 @@
+/** Automatic evaluation and the automatic kill rule for task-record ranking
+ * (dec_66925aa0ee). Nobody has to run anything:
+ *
+ *  - every time a task record is written, the leave-one-out evaluation is
+ *    recomputed over the graph's task records (pure, a few hundred records)
+ *    and cached under .hunch-cache — derived state, safe to delete;
+ *  - delivery reads the cache to pick its mode: `ranked` until the
+ *    pre-registered rule says otherwise, `latest` (three most recent on the
+ *    file) once the ranked selection has LOST to the baseline with a
+ *    confidence interval excluding zero over at least KILL_MIN_TASKS records;
+ *  - `hunch now` prints the current line; a verdict change becomes a finding.
+ *
+ * `.hunch/local.json` `taskRanking: "ranked" | "latest"` overrides the automatic
+ * choice for a repository that wants to pin it. */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { flushCapture } from "../integrations/sync.js";
+import { writeFileAtomic } from "./io.js";
+import { hunchPaths } from "./paths.js";
+import { evaluateTaskRanking } from "./taskRankEval.js";
+import { reportHash } from "./taskReport.js";
+import { FindingSchema } from "./types.js";
+export const RANK_EVAL_CACHE_SCHEMA = "hunch.task-rank-eval-cache/1";
+/** The decision's threshold: the kill rule needs at least this many task records. */
+export const KILL_MIN_TASKS = 200;
+function cachePath(root) {
+    return join(root, ".hunch-cache", "task-rank-eval.json");
+}
+export function readRankEvalCache(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(root), "utf8"));
+        return parsed && parsed.schema === RANK_EVAL_CACHE_SCHEMA && parsed.report ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function corpusHash(store) {
+    const records = store.recs("tasks");
+    const ids = records.map((r) => `${r.id}:${r.report_hash}`).sort();
+    return { hash: reportHash(ids), count: records.length };
+}
+/** Recompute when the corpus changed; otherwise return the cached report. Never throws. */
+export function refreshRankEval(root, store, options = {}) {
+    try {
+        const { hash, count } = corpusHash(store);
+        const cached = readRankEvalCache(root);
+        if (!options.force && cached && cached.corpus_hash === hash)
+            return cached;
+        const report = evaluateTaskRanking(store.recs("tasks"));
+        const next = { schema: RANK_EVAL_CACHE_SCHEMA, computed_at: (options.now ?? (() => new Date().toISOString()))(), records: count, corpus_hash: hash, report };
+        try {
+            const dir = join(root, ".hunch-cache");
+            if (!existsSync(dir))
+                return next; // no cache dir: still return the fresh report, just do not persist
+            writeFileAtomic(cachePath(root), JSON.stringify(next, null, 2));
+        }
+        catch { /* cache is a convenience */ }
+        if (cached && cached.report.verdict !== report.verdict)
+            noteVerdictChange(root, store, cached, next);
+        return next;
+    }
+    catch {
+        return readRankEvalCache(root);
+    }
+}
+/** The rule from the decision, applied to a report. */
+export function modeFromReport(report) {
+    if (!report)
+        return { mode: "ranked", reason: "no evaluation yet" };
+    if (report.verdict === "baseline-better" && report.tasks >= KILL_MIN_TASKS) {
+        return { mode: "latest", reason: `ranked selection lost to latest3 on ${report.split.evaluated} cases (Hit@5 ${pct(report.rankers[0]?.hit5)} vs ${pct(report.rankers[1]?.hit5)}, CI [${pts(report.delta_hit5.ci95[0])}, ${pts(report.delta_hit5.ci95[1])}])` };
+    }
+    return { mode: "ranked", reason: report.verdict === "ranked-better" ? "ranked selection beats latest3" : report.verdict === "baseline-better" ? `latest3 ahead but only ${report.tasks} of ${KILL_MIN_TASKS} task records; not yet decisive` : `evaluation ${report.verdict} (${report.split.evaluated} cases)` };
+}
+/** What delivery should do right now for this repository. */
+export function resolveTaskRankingMode(root, store) {
+    let override;
+    try {
+        override = JSON.parse(readFileSync(join(root, ".hunch", "local.json"), "utf8")).taskRanking;
+    }
+    catch { /* none */ }
+    const cache = refreshRankEval(root, store);
+    if (override === "ranked" || override === "latest")
+        return { mode: override, reason: `pinned by .hunch/local.json taskRanking`, source: "override", cache };
+    const { mode, reason } = modeFromReport(cache?.report);
+    return { mode, reason, source: "auto", cache };
+}
+function pct(x) { return x === undefined ? "–" : `${Math.round(x * 100)}%`; }
+function pts(x) { return `${x >= 0 ? "+" : ""}${Math.round(x * 100)}`; }
+/** One line for `hunch now` and the task stats. */
+export function rankingStatusLine(resolved) {
+    const r = resolved.cache?.report;
+    if (!r)
+        return `task ranking: ${resolved.mode} · no evaluation yet (no finished task records)`;
+    const ranked = r.rankers.find((x) => x.name === "ranked"), base = r.rankers.find((x) => x.name === "latest3");
+    return `task ranking: ${resolved.mode}${resolved.source === "override" ? " (pinned)" : ""} · Hit@5 ranked ${pct(ranked?.hit5)} vs latest3 ${pct(base?.hit5)}, CI [${pts(r.delta_hit5.ci95[0])}, ${pts(r.delta_hit5.ci95[1])}], n=${r.split.evaluated} of ${r.tasks} records · ${r.verdict}${r.tasks < KILL_MIN_TASKS ? ` · kill rule armed at ${KILL_MIN_TASKS} records` : ""}`;
+}
+/** A verdict change is memory: record it once, through the normal capture path. */
+function noteVerdictChange(root, store, prev, next) {
+    try {
+        const title = `Task ranking evaluation verdict changed: ${prev.report.verdict} → ${next.report.verdict} at ${next.records} task records`;
+        const id = `fnd_${reportHash(title).slice(7, 17)}`;
+        if (store.getRec("findings", id))
+            return;
+        const r = next.report;
+        const finding = FindingSchema.parse({
+            id, title,
+            observation: `Automatic leave-one-out evaluation of task-record ranking (dec_66925aa0ee) recomputed after a task record was written. Ranked Hit@5 ${pct(r.rankers[0]?.hit5)} vs latest3 ${pct(r.rankers[1]?.hit5)}, MRR ${r.rankers[0]?.mrr.toFixed(2)} vs ${r.rankers[1]?.mrr.toFixed(2)}, paired bootstrap CI on Hit@5 [${pts(r.delta_hit5.ci95[0])}, ${pts(r.delta_hit5.ci95[1])}] over ${r.split.evaluated} cases (${r.evaluable} evaluable of ${r.tasks}). Delivery mode now: ${modeFromReport(r).mode} — ${modeFromReport(r).reason}.`,
+            evidence: [`hunch task rank-eval --json (computed ${next.computed_at})`, `.hunch-cache/task-rank-eval.json corpus ${next.corpus_hash}`],
+            severity: next.report.verdict === "baseline-better" ? "high" : "low",
+            triage: "open",
+            affected_files: ["src/core/taskRanking.ts", "src/core/taskRankingMode.ts"],
+            observed_at: next.computed_at,
+            provenance: { source: "task_rank_eval", confidence: 0.9, evidence: ["hunch task rank-eval"], last_verified: next.computed_at },
+        });
+        store.putCapture("findings", finding, false);
+        flushCapture(store, hunchPaths(root).hunch, false, `hunch: capture ${id}`);
+    }
+    catch { /* the cache still carries the verdict; memory of the change is best-effort */ }
+}
+//# sourceMappingURL=taskRankingMode.js.map

package/dist/core/taskRecord.d.ts

@@ -18,6 +18,11 @@ export declare function taskRecordFromReport(report: TaskReport): TaskRecord | n
  * private save, or a delivered lesson that lives only there — must not be named
  * in a public record; the store's own routing (unified/shared mode) wins first. */
 export declare function taskRecordHome(store: HunchStore, record: TaskRecord): TaskRecordHome;
+/** Older records this one verified over: same file, a shared record, and this
+ * task's last check passed with no rule violated. Superseded records stay in
+ * the graph (append-only) but are never delivered; the newer line carries the
+ * verified state. Bounded. */
+export declare function computeSupersedes(record: TaskRecord, others: readonly TaskRecord[], limit?: number): string[];
 export interface PersistedTaskRecord {
     record: TaskRecord;
     home: TaskRecordHome;

package/dist/core/taskRecord.js

@@ -17,6 +17,7 @@ import { hunchPaths } from "./paths.js";
 import { isEmptyTaskReport, readTaskReport, reportHash } from "./taskReport.js";
 import { reportSourceSnapshot } from "./taskReportEvidence.js";
 import { ENTITY_KINDS, TaskRecordSchema } from "./types.js";
+import { refreshRankEval } from "./taskRankingMode.js";
 function localConfig(root) {
     try {
         return JSON.parse(readFileSync(join(root, ".hunch", "local.json"), "utf8"));
@@ -111,6 +112,33 @@ export function taskRecordHome(store, record) {
     }
     return "public";
 }
+/** Older records this one verified over: same file, a shared record, and this
+ * task's last check passed with no rule violated. Superseded records stay in
+ * the graph (append-only) but are never delivered; the newer line carries the
+ * verified state. Bounded. */
+export function computeSupersedes(record, others, limit = 20) {
+    const last = record.checks.at(-1);
+    if (!last || last.state !== "passed")
+        return [];
+    if (record.conformance.some((c) => c.outcome === "violated"))
+        return [];
+    const files = new Set(record.files.map((f) => f.replace(/\\/g, "/")));
+    const ids = new Set([...record.lessons.map((l) => l.record_id), ...record.applied.map((a) => a.record_id), ...record.saved.map((s) => s.record_id)]);
+    if (!files.size || !ids.size)
+        return [];
+    const out = [];
+    for (const o of others) {
+        if (o.id === record.id || o.finished_at >= record.finished_at)
+            continue;
+        if (!o.files.some((f) => files.has(f.replace(/\\/g, "/"))))
+            continue;
+        const oids = [...o.lessons.map((l) => l.record_id), ...o.applied.map((a) => a.record_id), ...o.saved.map((s) => s.record_id)];
+        if (!oids.some((id) => ids.has(id)))
+            continue;
+        out.push(o.id);
+    }
+    return out.sort().slice(0, limit);
+}
 /** Write (or refresh) the graph record for a finished task. Idempotent on the
  * report hash. A record never changes home once written. Returns null for an
  * open task, an empty report, or when task records are disabled locally. */
@@ -118,9 +146,10 @@ export function persistTaskRecord(root, store, taskId, options = {}) {
     if (!taskRecordsEnabled(root))
         return null;
     const report = readTaskReport(root, taskId, reportSourceSnapshot(root).hash);
-    const record = taskRecordFromReport(report);
-    if (!record)
+    const built = taskRecordFromReport(report);
+    if (!built)
         return null;
+    const record = { ...built, supersedes: computeSupersedes(built, store.recs("tasks")) };
     const inPrivate = store.hasPrivate ? store.getPrivateRec("tasks", record.id) : undefined;
     const inPublic = store.json.get("tasks", record.id);
     const home = inPrivate ? "private" : inPublic ? "public" : taskRecordHome(store, record);
@@ -131,6 +160,8 @@ export function persistTaskRecord(root, store, taskId, options = {}) {
     store.reindex();
     const flushNow = options.flush ?? taskRecordFlushMode(root) === "each";
     const flushed = flushNow ? flushCapture(store, hunchPaths(root).hunch, home === "private", `hunch: task ${record.id}`) : null;
+    // The ranking evaluation follows the corpus: recomputed here, read at delivery. Never blocks a finish.
+    refreshRankEval(root, store);
     return { record: stored, home, flushed, changed: true };
 }
 const GRAPH_SCOPE = reportHash("graph-record");

package/dist/core/taskRecordStats.d.ts

@@ -0,0 +1,14 @@
+import type { TaskRecord } from "./types.js";
+export interface TaskRecordStats {
+    records: number;
+    /** Later tasks that had a chance to re-verify (an earlier overlapping task with a check within the window). */
+    reverify_candidates: number;
+    reverified: number;
+    reverification_rate: number | null;
+    /** Later tasks that received a rule an earlier overlapping task violated. */
+    violation_candidates: number;
+    repeated_violations: number;
+    repeat_violation_rate: number | null;
+    window_hours: number;
+}
+export declare function taskRecordStats(records: readonly TaskRecord[], windowHours?: number): TaskRecordStats;

package/dist/core/taskRecordStats.js

@@ -0,0 +1,45 @@
+/** Online proxies for whether delivered task history is doing its job,
+ * computed from task records alone (no agent claims):
+ *  - re-verification: a later task on an overlapping file re-ran a check with
+ *    the same label as an earlier task within a window;
+ *  - repeat violation: a rule violated in an earlier task was violated again
+ *    in a later task on an overlapping file.
+ * Both should fall if the RECENT TASKS lines are read and acted on. */
+import { normalizePath } from "./taskRanking.js";
+export function taskRecordStats(records, windowHours = 24) {
+    const sorted = [...records].filter((r) => r.state === "completed").sort((a, b) => a.finished_at.localeCompare(b.finished_at) || a.id.localeCompare(b.id));
+    const windowMs = windowHours * 3_600_000;
+    let reverifyCandidates = 0, reverified = 0, violationCandidates = 0, repeated = 0;
+    for (let i = 0; i < sorted.length; i++) {
+        const t = sorted[i];
+        const files = new Set(t.files.map(normalizePath));
+        const tEnd = Date.parse(t.finished_at) || 0;
+        const overlapping = sorted.slice(0, i).filter((o) => o.files.some((f) => files.has(normalizePath(f))));
+        if (!overlapping.length)
+            continue;
+        const recent = overlapping.filter((o) => tEnd - (Date.parse(o.finished_at) || 0) <= windowMs);
+        const earlierLabels = new Set(recent.flatMap((o) => o.checks.map((c) => c.label)));
+        if (earlierLabels.size) {
+            reverifyCandidates++;
+            if (t.checks.some((c) => earlierLabels.has(c.label)))
+                reverified++;
+        }
+        const violatedBefore = new Set(overlapping.flatMap((o) => o.conformance.filter((c) => c.outcome === "violated").map((c) => c.record_id)));
+        const received = new Set(t.lessons.map((l) => l.record_id));
+        const exposed = [...violatedBefore].filter((id) => received.has(id));
+        if (exposed.length) {
+            violationCandidates++;
+            if (t.conformance.some((c) => c.outcome === "violated" && violatedBefore.has(c.record_id)))
+                repeated++;
+        }
+    }
+    return {
+        records: sorted.length,
+        reverify_candidates: reverifyCandidates, reverified,
+        reverification_rate: reverifyCandidates ? reverified / reverifyCandidates : null,
+        violation_candidates: violationCandidates, repeated_violations: repeated,
+        repeat_violation_rate: violationCandidates ? repeated / violationCandidates : null,
+        window_hours: windowHours,
+    };
+}
+//# sourceMappingURL=taskRecordStats.js.map

package/dist/core/types.d.ts

@@ -658,6 +658,7 @@ export declare const TaskRecordSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     refusals: z.ZodDefault<z.ZodNumber>;
     files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodDefault<z.ZodArray<z.ZodString>>;
     source_snapshot: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     report_hash: z.ZodString;
     provenance: z.ZodObject<{
@@ -1523,6 +1524,7 @@ export declare const SCHEMAS: {
         }, z.core.$strip>>>;
         refusals: z.ZodDefault<z.ZodNumber>;
         files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        supersedes: z.ZodDefault<z.ZodArray<z.ZodString>>;
         source_snapshot: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         report_hash: z.ZodString;
         provenance: z.ZodObject<{

package/dist/core/types.js

@@ -502,6 +502,7 @@ export const TaskRecordSchema = z.object({
     })).default([]).describe("Hunch's deterministic evaluation of each delivered rule against the changed files"),
     refusals: z.number().int().nonnegative().default(0).describe("edits the native gate denied during the task"),
     files: z.array(z.string()).default([]).describe("files the task touched: delivery targets, rule-checked changes, denied edits"),
+    supersedes: z.array(z.string()).default([]).describe("older task records this task verified over: same file, shared record, passing check; superseded records are not delivered"),
     source_snapshot: z.string().nullable().default(null).describe("bounded source snapshot hash at the last check, when one ran"),
     report_hash: z.string().describe("content hash of the full local report this record summarizes"),
     provenance: ProvenanceSchema,

package/dist/mcp/server.js

@@ -32,7 +32,8 @@ import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
 import { formatSearchHit, formatStructure } from "../core/format.js";
 import { isStateKind, stateSupplements } from "../core/stateDelivery.js";
-import { taskSupplements } from "../core/taskDelivery.js";
+import { taskSelectionSupplements } from "../core/taskDelivery.js";
+import { buildTaskRankingQuery } from "../core/taskQuery.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, EvidenceExecutionSchema, EvidenceInterventionSchema, EvidenceProbeSchema, formatVerifiedEvidenceMap, VerifiedEvidenceReceiptSchema, } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
@@ -360,19 +361,27 @@ function deliveredContext(root, target, envelope, sessionId) {
         const state = armExecutionObligations(loadPipelineState(sessionId), structuredContent.obligations, { replaceOrigin: "memory" });
         savePipelineState(sessionId, state);
     }
-    recordServed(root, structuredContent.delivered.map((item) => ({
-        event: "served",
-        kind: item.kind,
-        record_id: item.record_id,
-        target,
-        session_id: sessionId,
-        rank: item.rank,
-        delivery_reason: item.delivery_reason,
-        provenance_status: item.provenance_status,
-        token_cost: item.token_cost,
-        delivery_profile: structuredContent.profile,
-        ranking_policy: structuredContent.ranking_policy,
-    })));
+    recordServed(root, [
+        ...structuredContent.delivered.map((item) => ({
+            event: "served",
+            kind: item.kind,
+            record_id: item.record_id,
+            target,
+            session_id: sessionId,
+            rank: item.rank,
+            delivery_reason: item.delivery_reason,
+            provenance_status: item.provenance_status,
+            token_cost: item.token_cost,
+            delivery_profile: structuredContent.profile,
+            ranking_policy: structuredContent.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: "served", kind: "tasks", record_id: s.id, target, session_id: sessionId,
+            rank: s.rank, delivery_reason: "supplemental", token_cost: s.token_cost,
+            delivery_profile: structuredContent.profile, ranking_policy: structuredContent.ranking_policy,
+        })),
+    ]);
     return {
         content: [{ type: "text", text: structuredContent.text }],
         structuredContent,
@@ -1104,7 +1113,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         const stateGrounding = asOf ? [] : stateSupplements(store.stateSlice(target), target);
         // Recent finished tasks that touched the target: what earlier agent work did
         // here, from graph memory. Advisory history sharing the brief's budget.
-        const recentTasks = asOf ? [] : taskSupplements(store.tasksFor(target, 3), target);
+        const recentTasks = asOf ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, task_id ?? null, target)), target);
         const options = {
             root,
             symbols: store.recs("symbols"),

package/dist/mcp/taskReportTools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { TaskIdSchema, ReportClaimSchema, LessonReferenceSchema, finishReportTask, listReportTasks, readTaskReport, readLessonHistory, recordReportClaim, reportPresentationEnabled, startReportTask } from "../core/taskReport.js";
 import { persistTaskRecord } from "../core/taskRecord.js";
 import { reportSourceSnapshot, runReportConformance } from "../core/taskReportEvidence.js";
@@ -53,7 +53,11 @@ export function boundedTaskReportForHost(report) {
 function verificationLauncher() {
     const dev = import.meta.url.endsWith(".ts");
     const entry = fileURLToPath(new URL(`../cli/index.${dev ? "ts" : "js"}`, import.meta.url));
-    const argv = [process.execPath, ...(dev ? ["--import", fileURLToPath(import.meta.resolve("tsx"))] : []), entry];
+    // `--import` takes a URL. Converting the resolved loader to a path made Node on
+    // Windows reject it ("Received protocol 'c:'"), so every verification launched
+    // from a source checkout there failed before running and cards showed no check.
+    const loader = import.meta.resolve("tsx");
+    const argv = [process.execPath, ...(dev ? ["--import", loader.startsWith("file:") ? loader : pathToFileURL(loader).href] : []), entry];
     const quote = (s) => process.platform === "win32" ? `'${s.replace(/'/g, "''")}'` : `'${s.replace(/'/g, "'\\''")}'`;
     return { argv, shell: `${process.platform === "win32" ? "& " : ""}${argv.map(quote).join(" ")}` };
 }

package/dist/store/hunchStore.d.ts

@@ -3,6 +3,7 @@ import { type Component, type Constraint, type Bug, type Decision, type Symbol,
 import { type DB } from "./db.js";
 import { type Embedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
+import { type RankingContext, type RankingQuery, type RankingWeights, type SlotOptions, type TaskSelection } from "../core/taskRanking.js";
 import { type VetoTier } from "../core/strictgate.js";
 import { type DiffAnalysis } from "../extractors/diff.js";
 import type { CheckReport, CausalWhy, ImpactReport } from "../core/checkreport.js";
@@ -409,6 +410,29 @@ export declare class HunchStore {
      *  denied edits), newest first. Graph memory, so it spans machines and survives
      *  the local ledger's retention window. */
     tasksFor(scope: string, limit?: number): TaskRecord[];
+    /** Every task record that could matter for `target` under the ranking gate:
+     *  same file (exact or glob), a dependent's file, a co-changed file, or a
+     *  record sharing one of the current task's own record ids. Bounded; the
+     *  ranker does the gating and scoring. */
+    taskCandidates(target: string, query: RankingQuery, ctx: RankingContext): TaskRecord[];
+    /** Every task id some later record verified over. */
+    supersededTaskIds(): Set<string>;
+    /** Last delivery time per task record from the local receipt ledger, if any. */
+    taskLastDelivered(): Map<string, number>;
+    /** bm25 of a phrase over task titles and lesson titles, normalized to the top hit. */
+    taskLexicalScores(phrase: string | null, limit?: number): Map<string, number>;
+    /** Corpus inputs for ranking: dependents' files via the symbol graph, co-change
+     *  from git history (bounded, cached), record-id document frequencies across
+     *  task records, lexical scores, and which anchors still exist. */
+    taskRankingContext(target: string, query: RankingQuery): RankingContext;
+    /** Gate → score → slots for one target and the current task's query (dec_66925aa0ee). */
+    selectTasksFor(target: string, query: RankingQuery, options?: SlotOptions & {
+        weights?: Readonly<RankingWeights>;
+        mode?: "ranked" | "latest";
+    }): TaskSelection;
+    /** What delivery uses: the mode comes from the automatic evaluation (or a
+     *  local pin), never from a flag the caller has to remember. */
+    selectTasksAuto(target: string, query: RankingQuery): TaskSelection;
     /** The causal chain behind a constraint — the WHY a diff-only reviewer can't see.
      *  Deterministic graph join: constraint → source_decision (the decision that
      *  motivated the guard) → the bug whose root cause spawned it (via

package/dist/store/hunchStore.js

@@ -20,6 +20,10 @@ import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { gitCommonDir, gitWorktreeRoot, isolatedHeadSha, sameGitPublication, scopedLastChangeDates, } from "../extractors/git.js";
 import { pathMatchesGlob, pathsRelated } from "../core/glob.js";
+import { cochangeFor } from "../core/cochange.js";
+import { withServedDatabase } from "../core/served.js";
+import { normalizePath, rankTaskRecords, recordIdsOf, selectLatestTasks, selectTaskSlots } from "../core/taskRanking.js";
+import { resolveTaskRankingMode } from "../core/taskRankingMode.js";
 import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
@@ -1453,6 +1457,122 @@ export class HunchStore {
             .sort((a, b) => b.finished_at.localeCompare(a.finished_at) || a.id.localeCompare(b.id))
             .slice(0, Math.max(1, limit));
     }
+    /** Every task record that could matter for `target` under the ranking gate:
+     *  same file (exact or glob), a dependent's file, a co-changed file, or a
+     *  record sharing one of the current task's own record ids. Bounded; the
+     *  ranker does the gating and scoring. */
+    taskCandidates(target, query, ctx) {
+        const t = normalizePath(toPosixTarget(target));
+        const out = new Map();
+        for (const r of this.tasksFor(t, 200))
+            out.set(r.id, r);
+        if (ctx.dependents.size || ctx.cochange.size || query.recordIds.size) {
+            for (const r of this.recs("tasks")) {
+                if (out.has(r.id))
+                    continue;
+                const files = r.files.map(normalizePath);
+                if (files.some((f) => ctx.dependents.has(f) || ctx.cochange.has(f))) {
+                    out.set(r.id, r);
+                    continue;
+                }
+                if (query.recordIds.size) {
+                    const ids = recordIdsOf(r);
+                    for (const id of query.recordIds)
+                        if (ids.has(id)) {
+                            out.set(r.id, r);
+                            break;
+                        }
+                }
+            }
+        }
+        return [...out.values()];
+    }
+    /** Every task id some later record verified over. */
+    supersededTaskIds() {
+        const out = new Set();
+        for (const r of this.recs("tasks"))
+            for (const id of r.supersedes)
+                out.add(id);
+        return out;
+    }
+    /** Last delivery time per task record from the local receipt ledger, if any. */
+    taskLastDelivered() {
+        const out = new Map();
+        try {
+            withServedDatabase(this.paths.root, (db) => {
+                const rows = db.prepare("SELECT record_id, MAX(at) AS at FROM served WHERE kind = 'tasks' GROUP BY record_id").all();
+                for (const row of rows) {
+                    const t = Date.parse(row.at);
+                    if (Number.isFinite(t))
+                        out.set(row.record_id, t);
+                }
+            });
+        }
+        catch { /* no ledger on this machine: recency falls back to finished_at */ }
+        return out;
+    }
+    /** bm25 of a phrase over task titles and lesson titles, normalized to the top hit. */
+    taskLexicalScores(phrase, limit = 50) {
+        const scores = new Map();
+        if (!phrase || !phrase.trim())
+            return scores;
+        const hits = this.scopedFts(phrase, "tasks", limit).filter((h) => Number.isFinite(h.score));
+        if (!hits.length)
+            return scores;
+        // bm25 from FTS5 is negative, lower is better; normalize magnitude to the best hit.
+        const best = Math.max(...hits.map((h) => Math.abs(h.score)));
+        if (!(best > 0))
+            return scores;
+        for (const h of hits)
+            scores.set(h.ref, Math.max(0, Math.min(1, Math.abs(h.score) / best)));
+        return scores;
+    }
+    /** Corpus inputs for ranking: dependents' files via the symbol graph, co-change
+     *  from git history (bounded, cached), record-id document frequencies across
+     *  task records, lexical scores, and which anchors still exist. */
+    taskRankingContext(target, query) {
+        const t = normalizePath(toPosixTarget(target));
+        const dependents = new Set();
+        try {
+            const symbolFile = new Map(this.recs("symbols").map((s) => [s.id, normalizePath(s.file)]));
+            for (const sym of this.why(t).symbols) {
+                for (const d of this.getDependents(sym.id)) {
+                    const f = symbolFile.get(d.id);
+                    if (f && f !== t)
+                        dependents.add(f);
+                }
+            }
+        }
+        catch { /* no symbol graph: the dependents term is simply absent */ }
+        const cochange = /[./]/.test(t) && !/\s/.test(t) ? cochangeFor(this.paths.root, t) : new Map();
+        const tasks = this.recs("tasks");
+        const df = new Map();
+        for (const r of tasks)
+            for (const id of recordIdsOf(r))
+                df.set(id, (df.get(id) ?? 0) + 1);
+        const n = Math.max(1, tasks.length);
+        const ruleStats = (id) => { const d = df.get(id) ?? 0; return { df: d, idf: Math.log((n + 1) / (d + 1)) + 1e-6 }; };
+        const lexical = this.taskLexicalScores(query.phrase);
+        const anchorsAlive = (r) => r.files.length ? r.files.filter((f) => existsSync(join(this.paths.root, normalizePath(f)))).length / r.files.length : 1;
+        const superseded = this.supersededTaskIds();
+        const delivered = this.taskLastDelivered();
+        return { dependents, cochange, ruleStats, lexical, anchorsAlive, superseded, lastDelivered: (id) => delivered.get(id) ?? null };
+    }
+    /** Gate → score → slots for one target and the current task's query (dec_66925aa0ee). */
+    selectTasksFor(target, query, options = {}) {
+        const ctx = this.taskRankingContext(target, query);
+        const candidates = this.taskCandidates(target, query, ctx);
+        if (options.mode === "latest")
+            return selectLatestTasks(candidates, query, ctx);
+        const ranked = rankTaskRecords(candidates, query, ctx, options.weights);
+        return selectTaskSlots(ranked, options);
+    }
+    /** What delivery uses: the mode comes from the automatic evaluation (or a
+     *  local pin), never from a flag the caller has to remember. */
+    selectTasksAuto(target, query) {
+        const resolved = resolveTaskRankingMode(this.paths.root, this);
+        return this.selectTasksFor(target, query, { mode: resolved.mode });
+    }
     /** The causal chain behind a constraint — the WHY a diff-only reviewer can't see.
      *  Deterministic graph join: constraint → source_decision (the decision that
      *  motivated the guard) → the bug whose root cause spawned it (via

package/package.json

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

package/server.json

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