@davesheffer/hunch 1.32.1 → 1.32.2

package/dist/cli/index.js

@@ -80,8 +80,9 @@ import { appendEvent, readEvents } from "../core/events.js";
 import { computeStats, formatStats } from "../core/stats.js";
 import { injectionMode, resetSessionInjections } from "../core/hookcache.js";
 import { recordServed, servedSummary } from "../core/served.js";
-import { recordTaskDelivery, reportActivity } from "../core/taskReport.js";
+import { recordTaskDelivery, reportActivity, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
 import { snapshotDeliveredRecords } from "../core/taskReportEvidence.js";
+import { renderRecalledLine } from "../core/taskReportRender.js";
 import { hookReportTaskId, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
 import { recordHookObservation } from "../core/hookObservations.js";
 import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
@@ -90,7 +91,7 @@ import { draftDuplicateOf, isAcceptedDuplicateAnchor } from "../core/dupdetect.j
 import { planAutoReview, planMutations } from "../core/autoreview.js";
 import { loadGoldenSet, evaluateRetrieval, evaluateTraversalLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
-import { computeDrift } from "../core/drift.js";
+import { DRIFT_KINDS, computeDrift } from "../core/drift.js";
 import { renderCompilerScorecard, scoreCompilerCaseBank } from "../constitution/scorecard.js";
 import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWikiManifestAt, nowData } from "../wiki/wiki.js";
 import { adoptProsePrompt } from "../wiki/adopt.js";
@@ -108,6 +109,7 @@ import { MAX_LANDSCAPE_REFRESH_REVISIONS, planLandscapeAdoption, } from "../core
 import { discoverRepositoryLandscape } from "../extractors/landscapeDiscovery.js";
 import { checkConformance } from "../core/conformance.js";
 import { ConstitutionService, policyEvaluationEnvelope } from "../constitution/service.js";
+import { renderPolicyEvaluations } from "../constitution/renderEvaluations.js";
 import { sourceGraphSnapshot } from "../constitution/evaluator.js";
 import { renderProofCard } from "../constitution/card.js";
 import { movePolicyArtifactsToPrivate } from "../constitution/repository.js";
@@ -2295,20 +2297,6 @@ policyCmd
         store.close();
     }
 });
-function renderPolicyEvaluations(results) {
-    if (!results.length)
-        return ["No Constitution policies matched."];
-    const icon = { satisfied: "✅", violated: "⛔", not_applicable: "·", unknown: "?", error: "‼" };
-    const out = [`Constitution policy evaluation: ${results.length} canonical receipt(s)`];
-    for (const r of results) {
-        out.push(`  ${icon[r.evaluation.result] ?? "·"} ${r.policy.id} [${r.policy.state}] ${r.evaluation.result}${r.blocks ? " — BLOCK" : ""}`);
-        out.push(`     ${r.evaluation.explanation}`);
-        if (r.gate_error)
-            out.push(`     gate error: ${r.gate_error}`);
-        out.push(`     receipt: ${r.evaluation.deterministic_hash}`);
-    }
-    return out;
-}
 // ---- constitution (deterministic evidence -> candidate bootstrap) --------
 const constitutionCmd = program
     .command("constitution")
@@ -4201,8 +4189,9 @@ program
     if (opts.task) {
         try {
             const records = asOf ? [] : snapshotDeliveredRecords(store, envelope);
+            const recalled = renderRecalledLine(unseenLessons(root, opts.task, records));
             const occurrence = recordTaskDelivery(root, opts.task, envelope, records);
-            console.log(`\nTask evidence: ${opts.task} · occurrence ${occurrence}`);
+            console.log(`\n${recalled ? `${recalled}\n` : ""}Task evidence: ${opts.task} · occurrence ${occurrence}`);
         }
         catch {
             console.error(`Task evidence could not be recorded for ${opts.task}; context remains available but report attribution is unverified.`);
@@ -4894,16 +4883,22 @@ program
         }
         receipts("served");
         let reportNotice = "";
+        let recalled = null;
         if (reportTaskId) {
             try {
-                const occurrence = recordTaskDelivery(root, reportTaskId, envelope, snapshotDeliveredRecords(store, envelope));
+                const snapshots = snapshotDeliveredRecords(store, envelope);
+                // The first time a lesson reaches this prompt's task, tell the USER in one
+                // line (systemMessage); repeats of the same revision stay silent.
+                recalled = reportPresentationEnabled(root) ? renderRecalledLine(unseenLessons(root, reportTaskId, snapshots)) : null;
+                const occurrence = recordTaskDelivery(root, reportTaskId, envelope, snapshots);
                 reportNotice = `\n\nHunch task ${reportTaskId} · delivery ${occurrence}. Inspect exact application references with hunch_report(task_id).`;
             }
             catch {
                 reportNotice = "\n\nTask report observation unavailable; this delivery's task contribution remains unverified.";
+                recalled = null;
             }
         }
-        emitContext(provider, "PreToolUse", text + reportNotice);
+        emitContext(provider, "PreToolUse", text + reportNotice, recalled ?? undefined);
     }
     catch {
         // swallow — never block an edit on a hook failure
@@ -6031,8 +6026,13 @@ program
 // ---- drift (doc≠graph detector; advisory + CI-gateable) -------------------
 program
     .command("drift")
-    .description("Detect memory drift: dead refs, dangling supersedes, stale 'proposed' docs, commit-unresolvable (a decision cites a commit that no longer resolves in this repository), doc≠graph anchor-stale (a file still anchored to a superseded decision), markdown sections whose <!-- hunch:topic … dec_id --> pin points at a superseded or missing decision (AGENTS.md/CLAUDE.md as a drift surface), and ledger≠records replay divergence when this partition has a change ledger. Exits non-zero on any anchor-stale drift, topic collision or replay divergence — the doc≠graph and ledger≠records gate.")
-    .action(() => {
+    .description("Detect memory drift: dead refs, dangling supersedes, stale 'proposed' docs, commit-unresolvable (a decision cites a commit that no longer resolves in this repository), doc≠graph anchor-stale (a file still anchored to a superseded decision), markdown sections whose <!-- hunch:topic … dec_id --> pin points at a superseded or missing decision (AGENTS.md/CLAUDE.md as a drift surface), and ledger≠records replay divergence when this partition has a change ledger. Exits non-zero on any anchor-stale drift, topic collision or replay divergence — the doc≠graph and ledger≠records gate. --fail-on adds further kinds to the gate (the release gate passes finding-stale).")
+    .option("--fail-on <kinds>", `comma-separated drift kinds that also fail the gate (${DRIFT_KINDS.join(", ")})`)
+    .action((opts) => {
+    const failOn = new Set((opts.failOn ?? "").split(",").map((k) => k.trim()).filter(Boolean));
+    for (const kind of failOn)
+        if (!DRIFT_KINDS.includes(kind))
+            return fail(`--fail-on: unknown drift kind "${kind}" (known: ${DRIFT_KINDS.join(", ")})`);
     const { store, root } = storeFor();
     try {
         const { findings } = computeDrift(store, root);
@@ -6056,8 +6056,9 @@ program
         if (replayCount && !replayFailing.length)
             console.log(`· [replay-fingerprint] ${scopePath(own)}: ledger fold ${replay.replay_hash} ≠ stored ${replay.stored_hash}`);
         const anchor = findings.filter((f) => f.kind === "anchor-stale" || f.kind === "doc-anchor-stale").length;
-        console.log(`\n${findings.length + replayCount} finding(s)${anchor ? `, ${anchor} doc≠graph (anchor-stale)` : ""}${collisions.size ? `, ${collisions.size} topic-collision(s)` : ""}${replayCount ? `, ${replayCount} ledger≠records (replay: hunch serve replay --root .)` : ""}.`);
-        if (anchor || collisions.size || replayCount)
+        const failing = findings.filter((f) => failOn.has(f.kind)).length;
+        console.log(`\n${findings.length + replayCount} finding(s)${anchor ? `, ${anchor} doc≠graph (anchor-stale)` : ""}${collisions.size ? `, ${collisions.size} topic-collision(s)` : ""}${replayCount ? `, ${replayCount} ledger≠records (replay: hunch serve replay --root .)` : ""}${failing ? `, ${failing} failing by --fail-on (${[...failOn].join(", ")})` : ""}.`);
+        if (anchor || collisions.size || replayCount || failing)
             process.exitCode = 1;
     }
     finally {
@@ -6813,7 +6814,10 @@ function realpathNorm(p) {
 function toRepoRel(root, abs) {
     return relative(realpathNorm(root), realpathNorm(abs)).split("\\").join("/");
 }
-function emitContext(provider, event, text) {
+function emitContext(provider, event, text, 
+/** One user-facing line where the host shows hook messages (Claude Code's
+ * `systemMessage`); never a block, never a second model turn. */
+systemMessage) {
     if (event === "SessionStart") {
         const warning = integrationSessionWarning(findRoot(), provider);
         if (warning)
@@ -6821,7 +6825,7 @@ function emitContext(provider, event, text) {
     }
     const output = contextHookOutput(provider, event, text);
     if (output)
-        process.stdout.write(JSON.stringify(output));
+        process.stdout.write(JSON.stringify(provider === "claude" && systemMessage ? { ...output, systemMessage } : output));
 }
 function emitDeny(provider, reason) {
     const result = denyHookOutput(provider, reason);

package/dist/constitution/behaviorEvaluator.js

@@ -1,7 +1,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { headSha } from "../extractors/git.js";
 import { canonicalHash } from "./canonical.js";
@@ -125,7 +125,14 @@ export function evaluateExecutableBehaviorPolicy(root, policy, opts = {}) {
     }
     const dependency = dependencySnapshotForCommit(root, commit, assertion.dependency_snapshot_ids);
     if (!dependency) {
-        return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-unavailable" }, "error", "no unique exact dependency snapshot is available for executable behavior evaluation");
+        // Two different situations hid behind one message (fnd_b421b3f7ab): a machine
+        // that never built the snapshot cache, and a policy whose pinned snapshots no
+        // longer match the commit's dependency inputs. Name each with its recovery;
+        // both stay `error`, never a coerced pass.
+        if (!existsSync(join(root, ".hunch-cache", "behavior-deps"))) {
+            return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-cache-absent" }, "error", "no dependency snapshot cache exists on this machine (.hunch-cache/behavior-deps); executable behavior is unevaluated here, not failed — provision the policy's snapshots (hunch constitution bootstrap --behavior-deps <candidate>) or evaluate where they were built");
+        }
+        return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-unavailable" }, "error", `no unique exact dependency snapshot matches this commit's package.json/package-lock.json among the policy's pinned ids (${assertion.dependency_snapshot_ids.join(", ")}); dependency inputs changed since compilation — re-plan and re-prove the policy (rb_g2_stale_policy_01)`);
     }
     const session = mkdtempSync(join(tmpdir(), "hunch-behavior-policy-"));
     const hooks = join(session, "hooks-disabled");

package/dist/constitution/renderEvaluations.d.ts

@@ -0,0 +1,8 @@
+/** Terminal rendering of canonical policy receipts, shared by `hunch policy
+ * evaluate` and the pre-commit `hunch check`. Rendering never alters a receipt.
+ * Receipts that did not evaluate (error / unknown / not_applicable) and share
+ * one explanation are grouped, so ten policies failing for the same
+ * 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[];

package/dist/constitution/renderEvaluations.js

@@ -0,0 +1,48 @@
+const ICON = { satisfied: "✅", violated: "⛔", not_applicable: "·", unknown: "?", error: "‼" };
+const GROUP_AT = 3;
+function groupKey(r) {
+    const result = r.evaluation.result;
+    const groupable = (result === "error" || result === "unknown" || result === "not_applicable") && !r.blocks && !r.gate_error;
+    if (!groupable)
+        return `one ${r.policy.id}`;
+    return `${r.policy.state} ${result} ${r.evaluation.explanation}`;
+}
+export function renderPolicyEvaluations(results) {
+    if (!results.length)
+        return ["No Constitution policies matched."];
+    const out = [`Constitution policy evaluation: ${results.length} canonical receipt(s)`];
+    const groups = new Map();
+    for (const r of results) {
+        const key = groupKey(r);
+        const members = groups.get(key) ?? [];
+        members.push(r);
+        groups.set(key, members);
+    }
+    const rendered = new Set();
+    for (const r of results) {
+        if (rendered.has(r))
+            continue;
+        const members = groups.get(groupKey(r)) ?? [r];
+        const icon = ICON[r.evaluation.result] ?? "·";
+        if (members.length >= GROUP_AT) {
+            for (const member of members)
+                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)}`);
+            out.push(`  ${icon} ${members.length} policies [${r.policy.state}] ${r.evaluation.result} — same cause`);
+            out.push(`     ${r.evaluation.explanation}`);
+            out.push(`     policies: ${ids.join(", ")}`);
+            out.push(`     receipts: ${receipts.join(" ")}`);
+            out.push("     full receipts: hunch policy evaluate --json");
+            continue;
+        }
+        rendered.add(r);
+        out.push(`  ${icon} ${r.policy.id} [${r.policy.state}] ${r.evaluation.result}${r.blocks ? " — BLOCK" : ""}`);
+        out.push(`     ${r.evaluation.explanation}`);
+        if (r.gate_error)
+            out.push(`     gate error: ${r.gate_error}`);
+        out.push(`     receipt: ${r.evaluation.deterministic_hash}`);
+    }
+    return out;
+}
+//# sourceMappingURL=renderEvaluations.js.map

package/dist/core/drift.d.ts

@@ -1,5 +1,6 @@
 import type { HunchStore } from "../store/hunchStore.js";
-export type DriftKind = "dead-ref" | "supersede" | "doc-stale" | "anchor-stale" | "doc-anchor-stale" | "doc-anchor-dangling" | "wiki-stale" | "finding-stale" | "premise-stale" | "commit-unresolvable" | "madr-stale" | "madr-edited" | "madr-orphan";
+export declare const DRIFT_KINDS: readonly ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
+export type DriftKind = typeof DRIFT_KINDS[number];
 export interface DriftFinding {
     kind: DriftKind;
     id: string;

package/dist/core/drift.js

@@ -27,6 +27,7 @@ import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
 import { computeWikiDrift } from "../wiki/wiki.js";
 import { computeMadrDrift } from "../integrations/madrManifest.js";
 import { commitsExist, isGitRepo } from "../extractors/git.js";
+export const DRIFT_KINDS = ["dead-ref", "supersede", "doc-stale", "anchor-stale", "doc-anchor-stale", "doc-anchor-dangling", "wiki-stale", "finding-stale", "premise-stale", "commit-unresolvable", "madr-stale", "madr-edited", "madr-orphan"];
 export function computeDrift(store, root, deps = {}) {
     const findings = [];
     const decisions = store.recs("decisions");

package/dist/core/taskReport.d.ts

@@ -198,6 +198,12 @@ export declare function readLessonHistory(root: string, reference: LessonReferen
     before?: number;
 }): LessonHistory;
 export declare function startReportTask(root: string, title: string, taskId?: string): ReportTask;
+/** The record revisions among `records` that this task has not received before.
+ * Powers the one-line "Hunch recalled …" indication on a lesson's FIRST delivery
+ * in a task; repeats of the same revision stay silent (deduplicated per task and
+ * revision, never per session or file). Read-only; never throws for callers
+ * that must stay silent on failure — they catch. */
+export declare function unseenLessons(root: string, taskId: string, records: readonly ReportRecord[]): ReportRecord[];
 /** Strict operation for explicit callers. Passive integrations catch failure
  * and disclose it without blocking context delivery. Empty envelopes count. */
 export declare function recordTaskDelivery(root: string, taskId: string, envelope: DeliveryEnvelope, records: ReportRecord[], occurrenceId?: string): string;

package/dist/core/taskReport.js

@@ -281,6 +281,21 @@ function appendEvent(root, taskId, kind, body, eventId) {
         return id;
     }));
 }
+/** The record revisions among `records` that this task has not received before.
+ * Powers the one-line "Hunch recalled …" indication on a lesson's FIRST delivery
+ * in a task; repeats of the same revision stay silent (deduplicated per task and
+ * revision, never per session or file). Read-only; never throws for callers
+ * that must stay silent on failure — they catch. */
+export function unseenLessons(root, taskId, records) {
+    if (!records.length)
+        return [];
+    return taskDb(root, db => {
+        readTask(db, root, taskId);
+        const seen = db.prepare(`SELECT 1 FROM report_record_links l JOIN report_events e ON e.event_id = l.event_id
+      WHERE e.task_id = ? AND e.kind = 'delivery' AND l.kind = ? AND l.record_id = ? AND l.content_hash = ? LIMIT 1`);
+        return records.filter(r => !seen.get(taskId, r.kind, r.record_id, r.content_hash));
+    });
+}
 /** Strict operation for explicit callers. Passive integrations catch failure
  * and disclose it without blocking context delivery. Empty envelopes count. */
 export function recordTaskDelivery(root, taskId, envelope, records, occurrenceId = `hocc_${randomBytes(12).toString("hex")}`) {

package/dist/core/taskReportRender.d.ts

@@ -1,5 +1,10 @@
 import { type LessonHistory, type TaskReport } from "./taskReport.js";
 export declare function writeTaskReportHtml(root: string, taskId: string, publicOnly?: boolean): string;
+/** One short line for the first time a lesson reaches a task; null when every
+ * delivered revision was already seen in this task. Never a banner per delivery. */
+export declare function renderRecalledLine(fresh: readonly {
+    title: string;
+}[]): string | null;
 export declare function renderTaskReport(report: TaskReport): string;
 /** Standalone, local-only projection. No active content, external assets or
  * untrusted outbound URLs; evidence references are internal anchors. */

package/dist/core/taskReportRender.js

@@ -36,6 +36,14 @@ function ruleStanding(report) {
 function recordTitle(report, rule) {
     return uniqueRecords(report).find(r => r.kind === rule.kind && r.record_id === rule.record_id && r.content_hash === rule.content_hash)?.title ?? rule.record_id;
 }
+/** One short line for the first time a lesson reaches a task; null when every
+ * delivered revision was already seen in this task. Never a banner per delivery. */
+export function renderRecalledLine(fresh) {
+    if (!fresh.length)
+        return null;
+    const rest = fresh.length - 1;
+    return `Hunch recalled: ${clip(fresh[0].title, 90)}${rest ? ` (+${rest} more lesson${rest === 1 ? "" : "s"})` : ""}`;
+}
 export function renderTaskReport(report) {
     const records = uniqueRecords(report);
     const lines = [`Hunch · ${clip(report.task.title)}`, `Task ${report.task.task_id} · ${report.task.state}`];

package/dist/mcp/server.js

@@ -40,7 +40,8 @@ import { PROJECT_DNA_DELTA_SCHEMA_VERSION, diffProjectDna } from "../core/projec
 import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
 import { armExecutionObligations, loadPipelineState, savePipelineState } from "../core/pipeline.js";
 import { recordServed } from "../core/served.js";
-import { TaskIdSchema, recordTaskDelivery } from "../core/taskReport.js";
+import { TaskIdSchema, recordTaskDelivery, unseenLessons } from "../core/taskReport.js";
+import { renderRecalledLine } from "../core/taskReportRender.js";
 import { observeReportCapture } from "../core/taskReportCapture.js";
 import { snapshotDeliveredRecords } from "../core/taskReportEvidence.js";
 import { registerTaskReportTools } from "./taskReportTools.js";
@@ -1049,8 +1050,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 try {
                     // Historical contexts must not borrow today's record text/revision.
                     const records = as_of ? [] : snapshotDeliveredRecords(store, envelope);
+                    // First delivery of a revision in this task earns one line; repeats stay quiet.
+                    const recalled = renderRecalledLine(unseenLessons(root, task_id, records));
                     const occurrence = recordTaskDelivery(root, task_id, envelope, records);
-                    result.content.push({ type: "text", text: `Task evidence: ${task_id} · occurrence ${occurrence}.\n${records.slice(0, 20).map(r => `${r.record_id} @ ${r.content_hash}`).join("\n")}${records.length > 20 ? "\nMore record identities: hunch_report(task_id)." : ""}` });
+                    result.content.push({ type: "text", text: `${recalled ? `${recalled}\n` : ""}Task evidence: ${task_id} · occurrence ${occurrence}.\n${records.slice(0, 20).map(r => `${r.record_id} @ ${r.content_hash}`).join("\n")}${records.length > 20 ? "\nMore record identities: hunch_report(task_id)." : ""}` });
                 }
                 catch {
                     result.content.push({ type: "text", text: `Task evidence could not be recorded for ${task_id}. Context remains available; this delivery's report attribution is unverified. Check the task ID, working directory, and local ledger.` });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.32.1",
+  "version": "1.32.2",
   "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.32.1",
+  "version": "1.32.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.32.1",
+      "version": "1.32.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {