@davesheffer/hunch 1.35.0 → 1.37.0

package/dist/core/taskReportHook.js

@@ -1,6 +1,5 @@
 /** Native lifecycle coverage is independent of whether a model follows reporting
  * instructions. Only an authoritative prompt identity may join its evidence. */
-import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { findRoot } from "./paths.js";
@@ -8,7 +7,7 @@ import { canonicalReportRoot } from "./taskReportPaths.js";
 import { isCredentialFreeText } from "./types.js";
 import { isEmptyTaskReport, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, startReportTask } from "./taskReport.js";
 import { reportSourceSnapshot } from "./taskReportEvidence.js";
-import { renderTaskReport, writeTaskReportHtml } from "./taskReportRender.js";
+import { renderTaskReport } from "./taskReportRender.js";
 /** The exact task identity a native host prompt maps to. */
 export function promptTaskId(root, sessionId, promptId, agentId = null, provider = "claude") {
     return `htask_${reportHash([canonicalReportRoot(root), provider, sessionId, promptId, agentId]).slice(7, 31)}`;
@@ -131,13 +130,10 @@ export function stopHookReport(root, provider, event) {
         const report = readTaskReport(root, id, reportSourceSnapshot(root).hash);
         if (isEmptyTaskReport(report))
             return null;
-        let card = renderTaskReport(report);
-        try {
-            const file = writeTaskReportHtml(root, id);
-            card = card.replace(/^Evidence .*$/m, `Evidence  ${pathToFileURL(file).href}`);
-        }
-        catch { /* exact CLI evidence link remains available */ }
-        return { systemMessage: card };
+        // The HTML evidence view is a rendering of the local ledger, generated on
+        // demand (`hunch report <id> --html`, or a click in the VS Code view). The
+        // graph record is the durable memory; no file is written per prompt.
+        return { systemMessage: renderTaskReport(report) };
     }
     catch {
         return { systemMessage: `Hunch report unavailable for ${id}. Contribution is unverified; inspect with hunch report ${id}.` };

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/integrations/claudemd.js

@@ -75,7 +75,7 @@ export function renderHunchSection(store, root) {
     lines.push("- When running a relevant check, use the exact verification_argv launcher returned by hunch_task start, followed by the check command and its arguments, from this worktree. It runs `hunch task verify <task_id> -- <command> [arguments]` using the same installation as MCP, avoiding stale global binaries. This retains the actual exit result and source snapshot; raw output is not stored. Do not rerun an expensive check solely for reporting; missing evidence stays unverified.");
     lines.push("- Include the current task_id when calling hunch_record_decision, hunch_record_correction, or hunch_record_finding. The save path records its actual memory home and verifies exact Git revisions when committing or pushing; never infer publication from a successful capture alone.");
     lines.push("- Before claiming an application, call `hunch_report(task_id)` and copy the exact occurrence_id, record_id and content_hash from application_references, adding an action you actually took. Never derive an occurrence ID by replacing a receipt prefix or use the task's scope hash as a record hash. If you did not apply a lesson, omit applications.");
-    lines.push("- Call `hunch_task(action: \"finish\", task_id, applications?)` and include the returned contribution_card in your final response without the user asking. Render its Markdown evidence link outside any code block so it remains clickable. Copy the card with its evidence link and agent-reported label intact; the structured result contains the card even when the host hides text blocks. Do not replace it with a generic claim that Hunch helped. If presentation_enabled is false, omit the card. A delivered lesson or passing command alone does not prove causal impact.");
+    lines.push("- Call `hunch_task(action: \"finish\", task_id, applications?)` and include the returned contribution_card in your final response without the user asking. Copy the card verbatim, including its Evidence line (the command that renders the local report on demand) and the agent-reported label; the structured result contains the card even when the host hides text blocks. Do not replace it with a generic claim that Hunch helped. If presentation_enabled is false, omit the card. A delivered lesson or passing command alone does not prove causal impact.");
     lines.push("- If interrupted, finish with `outcome: \"interrupted\"` when possible. `hunch_report(task_id, html: true)` opens the evidence trail by generating a local file; it may contain private memory and is not a public export. If report tools are unavailable after an update, say so and reconnect the host rather than inventing a report.");
     lines.push("");
     lines.push("**Build the Constitution review queue:**");

package/dist/mcp/server.js

@@ -32,6 +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 { 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";
@@ -359,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,
@@ -1101,6 +1111,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         // latest receipts whose subject/text matches the target — bounded, ordered, sharing the
         // brief's budget as supplements. Withheld on time-travel: state records carry no as-of view.
         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 ? [] : taskSelectionSupplements(store.selectTasksFor(target, buildTaskRankingQuery(root, task_id ?? null, target)), target);
         const options = {
             root,
             symbols: store.recs("symbols"),
@@ -1108,7 +1121,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             decisionCorpus: store.recs("decisions"),
             historical: !!asOf,
             profile: profile ?? "builder",
-            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding, ...(asOf ? [] : conventionSupplements(store.recs("conventions")))],
+            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding, ...recentTasks, ...(asOf ? [] : conventionSupplements(store.recs("conventions")))],
         };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
@@ -1136,6 +1149,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     supplements: [
                         ...(dnaSupplement ? [dnaSupplement] : []),
                         ...stateGrounding,
+                        ...recentTasks,
                         ...hits
                             // State hits are delivered through the State section above, not as raw search lines.
                             .filter((hit) => !["constraints", "decisions", "bugs", "findings"].includes(hit.kind) && !isStateKind(hit.kind))

package/dist/mcp/taskReportTools.js

@@ -121,13 +121,10 @@ export function registerTaskReportTools(server, getRoot, getStore) {
             }
             const report = readTaskReport(root, task_id, reportSourceSnapshot(root).hash);
             const show = reportPresentationEnabled(root);
-            let file = null;
-            try {
-                file = writeTaskReportHtml(root, task_id);
-            }
-            catch { /* retained report remains inspectable through MCP */ }
-            const card = (file ? renderTaskReport(report).replace(/^Evidence .*$/m, `Evidence  [Open local report](<${file}>)`) : renderTaskReport(report)) + graphNote;
-            return { content: [{ type: "text", text: show ? card : "Task report retained. Automatic presentation is disabled; omit the contribution card from the final response." }], structuredContent: { ...boundedTaskReportForHost(report), presentation_enabled: show, contribution_card: show ? card : null, report_path: file, graph_record: graph } };
+            // The HTML evidence view is rendered on demand (hunch_report(html: true),
+            // `hunch report <id> --html`, or the VS Code view); finish writes no file.
+            const card = renderTaskReport(report) + graphNote;
+            return { content: [{ type: "text", text: show ? card : "Task report retained. Automatic presentation is disabled; omit the contribution card from the final response." }], structuredContent: { ...boundedTaskReportForHost(report), presentation_enabled: show, contribution_card: show ? card : null, report_path: null, graph_record: graph } };
         }
         catch (error) {
             const message = `Task report unavailable: ${error.message}`;

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,25 @@ 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>;
+    }): 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,9 @@ 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, selectTaskSlots } from "../core/taskRanking.js";
 import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
@@ -1453,6 +1456,113 @@ 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 ranked = rankTaskRecords(this.taskCandidates(target, query, ctx), query, ctx, options.weights);
+        return selectTaskSlots(ranked, options);
+    }
     /** 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.35.0",
+  "version": "1.37.0",
   "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.35.0",
+  "version": "1.37.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.35.0",
+      "version": "1.37.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {