@davesheffer/hunch 1.36.0 → 1.37.0

package/dist/core/taskRankEval.js

@@ -0,0 +1,195 @@
+/** 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 { DEFAULT_WEIGHTS, normalizePath, rankTaskRecords, recordIdsOf, selectTaskSlots } from "./taskRanking.js";
+export const TASK_RANK_EVAL_SCHEMA = "hunch.task-rank-eval/1";
+const GENERIC_TITLES = new Set(["Assistant task", "Claude task"]);
+function tokens(text) {
+    return new Set(text.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length > 2));
+}
+/** What T evidently used from older tasks. */
+export function groundTruth(task, older) {
+    const applied = new Set(task.applied.map((a) => a.record_id));
+    const received = new Set(task.lessons.map((l) => l.record_id));
+    const labels = new Set(task.checks.map((c) => c.label));
+    const files = new Set(task.files.map(normalizePath));
+    const truth = new Set();
+    for (const o of older) {
+        const ids = recordIdsOf(o);
+        const overlap = o.files.some((f) => files.has(normalizePath(f)));
+        if ([...applied].some((id) => ids.has(id))) {
+            truth.add(o.id);
+            continue;
+        }
+        if (overlap && o.checks.some((c) => labels.has(c.label))) {
+            truth.add(o.id);
+            continue;
+        }
+        if (o.conformance.some((c) => c.outcome === "violated" && received.has(c.record_id))) {
+            truth.add(o.id);
+            continue;
+        }
+    }
+    return truth;
+}
+/** T's own record as the query it would have had before editing. */
+export function evalQuery(task) {
+    const files = new Set(task.files.map(normalizePath));
+    return {
+        target: normalizePath(task.files[0] ?? task.title),
+        files,
+        recordIds: new Set(task.lessons.map((l) => l.record_id)),
+        phrase: GENERIC_TITLES.has(task.title) ? null : task.title,
+        now: Date.parse(task.finished_at) || 0,
+    };
+}
+/** A store-free context: IDF over the older set, lexical by token overlap. */
+export function pureContext(older, query) {
+    const df = new Map();
+    for (const r of older)
+        for (const id of recordIdsOf(r))
+            df.set(id, (df.get(id) ?? 0) + 1);
+    const n = Math.max(1, older.length);
+    const lexical = new Map();
+    if (query.phrase) {
+        const q = tokens(query.phrase);
+        let best = 0;
+        const raw = new Map();
+        for (const r of older) {
+            const doc = tokens(`${r.title} ${r.lessons.map((l) => l.title).join(" ")}`);
+            let inter = 0;
+            for (const t of q)
+                if (doc.has(t))
+                    inter++;
+            const score = q.size ? inter / q.size : 0;
+            if (score > 0) {
+                raw.set(r.id, score);
+                best = Math.max(best, score);
+            }
+        }
+        for (const [id, s] of raw)
+            lexical.set(id, s / best);
+    }
+    return {
+        dependents: new Set(), cochange: new Map(), lexical, anchorsAlive: () => 1,
+        ruleStats: (id) => { const d = df.get(id) ?? 0; return { df: d, idf: Math.log((n + 1) / (d + 1)) + 1e-6 }; },
+    };
+}
+export function buildCases(records) {
+    const sorted = [...records].filter((r) => r.state === "completed").sort((a, b) => a.finished_at.localeCompare(b.finished_at) || a.id.localeCompare(b.id));
+    const cases = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const task = sorted[i];
+        if (!task.files.length)
+            continue;
+        const older = sorted.slice(0, i);
+        if (!older.length)
+            continue;
+        const truth = groundTruth(task, older);
+        if (!truth.size)
+            continue;
+        cases.push({ task, file: normalizePath(task.files[0]), older, truth });
+    }
+    return cases;
+}
+export function rankedRanker(weights = DEFAULT_WEIGHTS) {
+    return (c) => {
+        const q = evalQuery(c.task);
+        const ranked = rankTaskRecords(c.older, q, pureContext(c.older, q), weights);
+        return selectTaskSlots(ranked).picks.map((p) => p.ranked.record.id);
+    };
+}
+export const latest3Ranker = (c) => c.older.filter((r) => r.files.map(normalizePath).includes(c.file))
+    .sort((a, b) => b.finished_at.localeCompare(a.finished_at) || a.id.localeCompare(b.id))
+    .slice(0, 3).map((r) => r.id);
+export function scoreRanker(name, ranker, cases) {
+    const hits = [];
+    let rr = 0;
+    for (const c of cases) {
+        const picks = ranker(c).slice(0, 5);
+        const rank = picks.findIndex((id) => c.truth.has(id));
+        hits.push(rank >= 0 ? 1 : 0);
+        if (rank >= 0)
+            rr += 1 / (rank + 1);
+    }
+    const n = cases.length || 1;
+    return { name, hit5: hits.reduce((s, h) => s + h, 0) / n, mrr: rr / n, hits };
+}
+/** xorshift32: deterministic resampling so two runs agree byte for byte. */
+function prng(seed) {
+    let x = seed >>> 0 || 0x9e3779b9;
+    return () => { x ^= x << 13; x >>>= 0; x ^= x >>> 17; x ^= x << 5; x >>>= 0; return x / 0x1_0000_0000; };
+}
+export function pairedBootstrap(a, b, resamples = 1000, seed = 42) {
+    const n = a.length;
+    if (!n)
+        return { mean: 0, ci95: [0, 0] };
+    const diffs = a.map((x, i) => x - (b[i] ?? 0));
+    const mean = diffs.reduce((s, d) => s + d, 0) / n;
+    const rnd = prng(seed);
+    const means = [];
+    for (let r = 0; r < resamples; r++) {
+        let s = 0;
+        for (let i = 0; i < n; i++)
+            s += diffs[Math.floor(rnd() * n)];
+        means.push(s / n);
+    }
+    means.sort((x, y) => x - y);
+    const at = (p) => means[Math.min(means.length - 1, Math.max(0, Math.floor(p * (means.length - 1))))];
+    return { mean, ci95: [at(0.025), at(0.975)] };
+}
+export function evaluateTaskRanking(records, options = {}) {
+    const split = options.split ?? 0.3;
+    const minEvaluated = options.minEvaluated ?? 5;
+    const all = buildCases(records);
+    let cases = all.slice(Math.floor(all.length * (1 - split)));
+    let note = null;
+    if (cases.length < minEvaluated) {
+        cases = all;
+        note = `fewer than ${minEvaluated} cases in the newest ${Math.round(split * 100)}%; evaluated every case`;
+    }
+    const weights = { ...(options.weights ?? DEFAULT_WEIGHTS) };
+    const ranked = scoreRanker("ranked", rankedRanker(weights), cases);
+    const baseline = scoreRanker("latest3", latest3Ranker, cases);
+    const resamples = options.resamples ?? 1000;
+    const delta = pairedBootstrap(ranked.hits, baseline.hits, resamples);
+    let verdict = "inconclusive";
+    if (cases.length < minEvaluated)
+        verdict = "insufficient-data";
+    else if (delta.ci95[0] > 0)
+        verdict = "ranked-better";
+    else if (delta.ci95[1] < 0)
+        verdict = "baseline-better";
+    return {
+        schema: TASK_RANK_EVAL_SCHEMA,
+        tasks: records.length,
+        evaluable: all.length,
+        split: { fraction: split, evaluated: cases.length, note },
+        rankers: [ranked, baseline].map(({ hits: _h, ...rest }) => rest),
+        delta_hit5: { ...delta, resamples },
+        verdict,
+        weights,
+    };
+}
+export function renderRankEval(report) {
+    const pct = (x) => `${(x * 100).toFixed(0)}%`;
+    const lines = [
+        `Task ranking evaluation — ${report.evaluable} evaluable of ${report.tasks} task record(s); evaluated ${report.split.evaluated}${report.split.note ? ` (${report.split.note})` : ` (newest ${Math.round(report.split.fraction * 100)}%)`}`,
+    ];
+    for (const r of report.rankers)
+        lines.push(`  ${r.name.padEnd(8)} Hit@5 ${pct(r.hit5).padStart(4)}  MRR ${r.mrr.toFixed(2)}`);
+    lines.push(`  Δ Hit@5 ranked − latest3: ${(report.delta_hit5.mean * 100).toFixed(0)} pts, 95% CI [${(report.delta_hit5.ci95[0] * 100).toFixed(0)}, ${(report.delta_hit5.ci95[1] * 100).toFixed(0)}] (${report.delta_hit5.resamples} resamples)`);
+    lines.push(`  verdict: ${report.verdict}${report.verdict === "insufficient-data" ? " — keep collecting; the kill rule needs a CI that excludes zero" : ""}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=taskRankEval.js.map

package/dist/core/taskRanking.d.ts

@@ -0,0 +1,113 @@
+/** Ranking of task records for pre-edit delivery (dec_66925aa0ee).
+ *
+ * Pure functions over plain data: no I/O, no clock, no model. The store gathers
+ * candidates and computes the corpus-level inputs (dependents, co-change, IDF,
+ * lexical scores, anchor liveness); this module gates, scores, slots and
+ * explains. Same inputs always give the same picks, so a selection is
+ * replayable and every line carries the reasons that produced it.
+ *
+ * Design, from the research synthesis: gate before rank (unfiltered injection
+ * is what lost in every negative result), structure over similarity, verified
+ * outcome as the importance proxy, recency as a decayed term with a floor and
+ * never a cutoff, convex weighted sum (not RRF, which degenerates on short
+ * lists), IDF-weighted overlap instead of Jaccard on tiny id sets, slots plus
+ * MMR instead of a flat top-k, one factual reason per pick. */
+import type { TaskRecord } from "./types.js";
+export interface RankingQuery {
+    /** File (posix path) or phrase the agent is working on. */
+    target: string;
+    /** Files this task has already touched (from its ledger). */
+    files: ReadonlySet<string>;
+    /** Record ids delivered, applied or saved in this task so far. */
+    recordIds: ReadonlySet<string>;
+    /** Task title (opt-in) or the hunch_context phrase; null when unknown. */
+    phrase: string | null;
+    /** Milliseconds since epoch; passed in so ranking is replayable. */
+    now: number;
+}
+export interface CochangeStrength {
+    /** Commits in which the file and the target changed together. */
+    count: number;
+    /** count / max(commits touching either), in [0, 1]. */
+    strength: number;
+}
+export interface RankingContext {
+    /** Files that depend on the target or share its component (posix paths). */
+    dependents: ReadonlySet<string>;
+    /** Co-change strength per file, for files that changed with the target. */
+    cochange: ReadonlyMap<string, CochangeStrength>;
+    /** Corpus statistics for a record id across all task records. */
+    ruleStats: (recordId: string) => {
+        idf: number;
+        df: number;
+    };
+    /** bm25 of the query phrase over task title + lesson titles, normalized to the top hit. */
+    lexical: ReadonlyMap<string, number>;
+    /** Fraction of a record's files that still exist; 1 when it names no files. */
+    anchorsAlive: (record: TaskRecord) => number;
+    /** Task ids some later record supersedes; never delivered. */
+    superseded?: ReadonlySet<string>;
+    /** Last time a task line was delivered (ms since epoch), when receipts know. */
+    lastDelivered?: (taskId: string) => number | null;
+}
+export interface RankingWeights {
+    file: number;
+    rules: number;
+    outcome: number;
+    lexical: number;
+    recency: number;
+    workingSet: number;
+}
+/** A prior, not a measurement. Changed only through `hunch task rank-eval`. */
+export declare const DEFAULT_WEIGHTS: Readonly<RankingWeights>;
+export declare const RECENCY_HALF_LIFE_DAYS = 30;
+export declare const RECENCY_FLOOR = 0.1;
+export declare const COCHANGE_MIN_COUNT = 2;
+/** A shared record admits a candidate only when it is informative: present in
+ * at most half of all task records (idf ≥ ln 2). A rule every task receives
+ * says nothing about relatedness; it still contributes to the score, weakly. */
+export declare const RULE_GATE_MIN_IDF: number;
+export type RankingTerm = keyof RankingWeights;
+export interface RankedTask {
+    record: TaskRecord;
+    score: number;
+    terms: Record<RankingTerm, number>;
+    /** Factual reasons, strongest first (weighted term contribution). */
+    reasons: string[];
+    anchorsAlive: number;
+    /** True when the record names the exact target file. */
+    exactFile: boolean;
+    /** True when a delivered rule was violated or a check failed in the record. */
+    problem: boolean;
+}
+export type SlotName = "latest" | "violation" | "relevant";
+export interface SlotPick {
+    slot: SlotName;
+    ranked: RankedTask;
+}
+export interface TaskSelection {
+    picks: SlotPick[];
+    /** Ranked candidates not shown. */
+    more: number;
+    candidates: number;
+}
+export interface SlotOptions {
+    limit?: number;
+    relevant?: number;
+    lambda?: number;
+}
+export declare function normalizePath(path: string): string;
+/** Every record id a task record references: lessons received, applications, saves. */
+export declare function recordIdsOf(record: TaskRecord): Set<string>;
+export declare function recencyTerm(record: TaskRecord, now: number, lastDelivered?: number | null): number;
+export declare function outcomeTerm(record: TaskRecord): {
+    value: number;
+    reason: string | null;
+};
+/** Gate, score and explain one record. Null when the gate rejects it. */
+export declare function rankTaskRecord(record: TaskRecord, query: RankingQuery, ctx: RankingContext, weights?: Readonly<RankingWeights>): RankedTask | null;
+export declare function rankTaskRecords(records: readonly TaskRecord[], query: RankingQuery, ctx: RankingContext, weights?: Readonly<RankingWeights>): RankedTask[];
+/** Jaccard over files ∪ record ids: the similarity MMR penalizes. */
+export declare function taskSimilarity(a: TaskRecord, b: TaskRecord): number;
+/** Slots: latest on the exact file, most recent problem, then relevant by MMR. */
+export declare function selectTaskSlots(ranked: readonly RankedTask[], options?: SlotOptions): TaskSelection;

package/dist/core/taskRanking.js

@@ -0,0 +1,202 @@
+/** A prior, not a measurement. Changed only through `hunch task rank-eval`. */
+export const DEFAULT_WEIGHTS = Object.freeze({
+    file: 0.30, rules: 0.25, outcome: 0.15, lexical: 0.10, recency: 0.10, workingSet: 0.10,
+});
+export const RECENCY_HALF_LIFE_DAYS = 30;
+export const RECENCY_FLOOR = 0.1;
+export const COCHANGE_MIN_COUNT = 2;
+/** A shared record admits a candidate only when it is informative: present in
+ * at most half of all task records (idf ≥ ln 2). A rule every task receives
+ * says nothing about relatedness; it still contributes to the score, weakly. */
+export const RULE_GATE_MIN_IDF = Math.log(2);
+const DAY_MS = 86_400_000;
+export function normalizePath(path) {
+    return path.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/** Every record id a task record references: lessons received, applications, saves. */
+export function recordIdsOf(record) {
+    const ids = new Set();
+    for (const l of record.lessons)
+        ids.add(l.record_id);
+    for (const a of record.applied)
+        ids.add(a.record_id);
+    for (const s of record.saved)
+        ids.add(s.record_id);
+    return ids;
+}
+function recordFiles(record) {
+    return record.files.map(normalizePath);
+}
+/** Age from the later of finishing and the last delivery: a record that keeps
+ * being delivered stays warm (access-based decay, as in Generative Agents). */
+function ageDays(record, now, lastDelivered = null) {
+    const finished = Date.parse(record.finished_at);
+    const anchor = Math.max(Number.isFinite(finished) ? finished : Number.NEGATIVE_INFINITY, lastDelivered ?? Number.NEGATIVE_INFINITY);
+    if (!Number.isFinite(anchor))
+        return Number.POSITIVE_INFINITY;
+    return Math.max(0, (now - anchor) / DAY_MS);
+}
+export function recencyTerm(record, now, lastDelivered = null) {
+    const days = ageDays(record, now, lastDelivered);
+    if (!Number.isFinite(days))
+        return RECENCY_FLOOR;
+    return Math.max(RECENCY_FLOOR, Math.pow(0.5, days / RECENCY_HALF_LIFE_DAYS));
+}
+export function outcomeTerm(record) {
+    if (record.conformance.some((c) => c.outcome === "violated"))
+        return { value: 1, reason: "RULE VIOLATED" };
+    if (record.checks.some((c) => c.state === "failed" || c.state === "timed out"))
+        return { value: 0.8, reason: "check failed" };
+    if (record.saved.length)
+        return { value: 0.6, reason: `saved ${record.saved[0].record_id}${record.saved.length > 1 ? ` +${record.saved.length - 1}` : ""}` };
+    if (record.applied.some((a) => a.supported_by))
+        return { value: 0.5, reason: "applied a rule (rule-supported)" };
+    if (record.checks.some((c) => c.state === "passed"))
+        return { value: 0.3, reason: "check passed" };
+    return { value: 0, reason: null };
+}
+function humanAge(days) {
+    if (!Number.isFinite(days))
+        return "undated";
+    if (days < 1)
+        return "today";
+    if (days < 2)
+        return "yesterday";
+    return `${Math.floor(days)} days ago`;
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+/** Gate, score and explain one record. Null when the gate rejects it. */
+export function rankTaskRecord(record, query, ctx, weights = DEFAULT_WEIGHTS) {
+    const target = normalizePath(query.target);
+    if (ctx.superseded?.has(record.id))
+        return null; // a later task verified over it
+    const files = recordFiles(record);
+    const alive = files.length ? ctx.anchorsAlive(record) : 1;
+    if (files.length && alive === 0)
+        return null; // nothing it names still exists
+    // --- file: same file 1, dependent / same component 0.5, co-change 0.3 × strength-ish
+    const exactFile = files.includes(target);
+    const dependent = !exactFile && files.some((f) => ctx.dependents.has(f));
+    let cochangeHit = null;
+    if (!exactFile && !dependent) {
+        for (const f of files) {
+            const c = ctx.cochange.get(f);
+            if (c && c.count >= COCHANGE_MIN_COUNT && (!cochangeHit || c.count > cochangeHit.count))
+                cochangeHit = { file: f, count: c.count };
+        }
+    }
+    const fileValue = exactFile ? 1 : dependent ? 0.5 : cochangeHit ? 0.3 : 0;
+    // --- rules: IDF-weighted intersection over the current task's own ids
+    const ids = recordIdsOf(record);
+    const shared = [];
+    let queryMass = 0;
+    for (const id of query.recordIds) {
+        const s = ctx.ruleStats(id);
+        queryMass += s.idf;
+        if (ids.has(id))
+            shared.push({ id, ...s });
+    }
+    const rulesValue = queryMass > 0 ? Math.min(1, shared.reduce((sum, s) => sum + s.idf, 0) / queryMass) : 0;
+    // --- gate: structure or an informative shared rule; lexical/recency/outcome alone never admit
+    const informative = shared.some((s) => s.idf >= RULE_GATE_MIN_IDF);
+    if (fileValue === 0 && !informative)
+        return null;
+    const outcome = outcomeTerm(record);
+    const lexicalValue = Math.max(0, Math.min(1, ctx.lexical.get(record.id) ?? 0));
+    const lastDelivered = ctx.lastDelivered?.(record.id) ?? null;
+    const recencyValue = recencyTerm(record, query.now, lastDelivered);
+    const touched = files.filter((f) => query.files.has(f));
+    const workingSetValue = query.files.size ? Math.min(1, touched.length / query.files.size) : 0;
+    const terms = {
+        file: fileValue, rules: rulesValue, outcome: outcome.value, lexical: lexicalValue, recency: recencyValue, workingSet: workingSetValue,
+    };
+    const score = Object.keys(terms).reduce((sum, k) => sum + weights[k] * terms[k], 0);
+    // --- reasons, ordered by weighted contribution
+    const reasons = [];
+    if (exactFile)
+        reasons.push({ weight: weights.file * 1, text: "same file" });
+    else if (dependent)
+        reasons.push({ weight: weights.file * 0.5, text: `dependent of ${target}` });
+    else if (cochangeHit)
+        reasons.push({ weight: weights.file * 0.3, text: `co-changed with ${target} in ${cochangeHit.count} commits` });
+    if (shared.length) {
+        const top = [...shared].sort((a, b) => b.idf - a.idf)[0];
+        reasons.push({ weight: weights.rules * rulesValue, text: `shares ${top.id}${top.df ? ` (${top.df === 1 ? "only here" : `${top.df} tasks`})` : ""}${shared.length > 1 ? ` +${shared.length - 1}` : ""}` });
+    }
+    if (outcome.reason)
+        reasons.push({ weight: weights.outcome * outcome.value, text: outcome.reason });
+    if (lexicalValue > 0 && query.phrase)
+        reasons.push({ weight: weights.lexical * lexicalValue, text: `matches "${clip(query.phrase, 40)}"` });
+    if (touched.length)
+        reasons.push({ weight: weights.workingSet * workingSetValue, text: `also touched ${touched[0]} this task` });
+    const finishedAge = ageDays(record, query.now);
+    const effectiveAge = ageDays(record, query.now, lastDelivered);
+    reasons.push({ weight: weights.recency * recencyValue, text: effectiveAge < finishedAge ? `delivered ${humanAge(effectiveAge)}` : humanAge(finishedAge) });
+    if (alive < 1)
+        reasons.push({ weight: 0, text: "files since changed" });
+    reasons.sort((a, b) => b.weight - a.weight);
+    return {
+        record, score, terms, reasons: reasons.map((r) => r.text), anchorsAlive: alive, exactFile,
+        problem: outcome.value >= 0.8,
+    };
+}
+/** Newest first, then id — the tie order the research insists on. */
+function newestFirst(a, b) {
+    return b.record.finished_at.localeCompare(a.record.finished_at) || a.record.id.localeCompare(b.record.id);
+}
+export function rankTaskRecords(records, query, ctx, weights = DEFAULT_WEIGHTS) {
+    const ranked = [];
+    for (const record of records) {
+        const r = rankTaskRecord(record, query, ctx, weights);
+        if (r)
+            ranked.push(r);
+    }
+    return ranked.sort((a, b) => (b.score - a.score) || newestFirst(a, b));
+}
+/** Jaccard over files ∪ record ids: the similarity MMR penalizes. */
+export function taskSimilarity(a, b) {
+    const sa = new Set([...recordFiles(a), ...recordIdsOf(a)]);
+    const sb = new Set([...recordFiles(b), ...recordIdsOf(b)]);
+    if (!sa.size && !sb.size)
+        return 0;
+    let inter = 0;
+    for (const x of sa)
+        if (sb.has(x))
+            inter++;
+    return inter / (sa.size + sb.size - inter);
+}
+/** Slots: latest on the exact file, most recent problem, then relevant by MMR. */
+export function selectTaskSlots(ranked, options = {}) {
+    const limit = Math.max(1, options.limit ?? 5);
+    const relevantMax = Math.max(0, options.relevant ?? 3);
+    const lambda = options.lambda ?? 0.7;
+    const picks = [];
+    const taken = new Set();
+    const take = (slot, r) => { picks.push({ slot, ranked: r }); taken.add(r.record.id); };
+    const latest = [...ranked].filter((r) => r.exactFile).sort(newestFirst)[0];
+    if (latest)
+        take("latest", latest);
+    const violation = [...ranked].filter((r) => r.problem && !taken.has(r.record.id)).sort(newestFirst)[0];
+    if (violation && picks.length < limit)
+        take("violation", violation);
+    let remaining = ranked.filter((r) => !taken.has(r.record.id));
+    while (picks.length < limit && picks.length - (latest ? 1 : 0) - (violation ? 1 : 0) < relevantMax && remaining.length) {
+        let best = null, bestValue = -Infinity;
+        for (const r of remaining) {
+            const redundancy = picks.length ? Math.max(...picks.map((p) => taskSimilarity(p.ranked.record, r.record))) : 0;
+            const value = lambda * r.score - (1 - lambda) * redundancy;
+            if (value > bestValue || (value === bestValue && best && newestFirst(r, best) < 0)) {
+                best = r;
+                bestValue = value;
+            }
+        }
+        if (!best)
+            break;
+        take("relevant", best);
+        remaining = remaining.filter((r) => r !== best);
+    }
+    return { picks, more: ranked.length - picks.length, candidates: ranked.length };
+}
+//# sourceMappingURL=taskRanking.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

@@ -111,6 +111,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 +145,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);

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,