@davesheffer/hunch 1.18.1 → 1.19.0

package/README.md

@@ -18,6 +18,23 @@ strict enforcement.
 **Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
 then a deterministic check of the change against the rules your team has explicitly trusted.
 
+> **New in v1.19.0:** correction search now keeps the flat top five but adds
+> transfer-tested semantic declaration families and an efficiency-tested progressive queue.
+> Evidence receipts are read-only annotations: they never reorder candidates or claim an exact
+> owner. Install the stable release with `npm i -g @davesheffer/hunch`.
+
+The measured improvement is deliberately scoped to fresh, preregistered transfer cases:
+
+| Measure | Flat/baseline | v1.19 bounded view | Change |
+| --- | ---: | ---: | ---: |
+| Changed declaration found | 3/12 (25%) | 6/12 (50%) | +25 percentage points |
+| Correct file found | 8/12 (66.7%) | 10/12 (83.3%) | +16.6 percentage points |
+| Declarations inspected for the same five hits | 18.9 average | 11 average | 41.9% less |
+
+These are bounded diagnostic and inspection results, not a claim that Hunch is universally twice as
+accurate. Failed evidence and causal rerankers remain disabled; the receipts annotate the shortlist
+without changing its order or asserting an exact owner.
+
 > **New in v1.18.0:** YAML and Helm now enter the same dependency graph as application code.
 > Anchors and aliases become reference edges; chart-scoped `define`, `include`, and `template`
 > relationships survive pre-render syntax without weakening fail-closed handling for ordinary
@@ -72,10 +89,50 @@ Most memory work happens automatically after commits. These commands cover the c
 | `hunch why <file>` | Decisions, bugs, constraints, and blast radius behind a file |
 | `hunch query "<question>"` | Search project memory |
 | `hunch check --working` | Review all current changes against recorded intent |
+| `hunch shortlist --issue "..."` | Experimental flat shortlist plus a progressive, file-anchored semantic inspection plan; add `--evidence receipt.json` for read-only evidence annotations |
+| `hunch evidence-map receipt.json` | Compile observed probe/execution receipts without guessing an exact owner |
 | `hunch log` | See the memory timeline and its reversible moves |
 | `hunch escalations` | See the rare decisions only a human can make |
 | `hunch doctor` | Diagnose setup, provider, index, or private-overlay problems |
 
+`hunch evidence-map` accepts a bounded JSON receipt containing a red target, a distinct green
+control, optional execution counts, and optional intervention outcomes. It reports target-only and
+shared execution plus behavior-sensitive files. It does not run the probes, edit the repository, or
+claim that behaviorally influential code owns the correction. Use `--json` for the machine-readable
+map; MCP clients can submit the same receipt through `hunch_evidence_map`.
+
+`hunch shortlist --evidence` attaches authenticated observations to the relevant candidates but does
+not reorder them. Three fresh transfer experiments failed to prove that execution or intervention
+influence identifies the correction owner, so the production path converts that result into a hard
+safeguard: no candidate is promoted or displaced by evidence. JSON output still includes a
+deterministic receipt and the explicit `exact_owner_enabled: false` policy.
+
+Every shortlist also preserves its flat top five and adds a deterministic hierarchical inspection
+view anchored to those files: at most five files, two semantic declaration families per file, and
+three declarations per family. On a preregistered 12-case fresh transfer, the preserved union found
+6/12 changed declarations versus 3/12 for the flat top five (**+25 percentage points**, three
+rescues), while correct-file coverage improved from 8/12 to 10/12. The view averaged 18.8 unique
+declarations and never exceeded 24. This promotes the clusters as a supplemental diagnostic, not as
+a top-five accuracy claim; exact-owner output and per-case confidence remain disabled. JSON output
+includes the deterministic cluster receipt and the transfer calibration.
+
+The default output also turns those clusters into a progressive inspection queue. It preserves the
+flat shortlist, adds only the strongest members of already-selected semantic families, stops at ten
+when the behavior is explained, and permits one final fallback declaration before reporting
+uncertainty. Development replay retained all 21/36 combined hits from the full cluster view while
+reducing the hard inspection ceiling to 11 from an average of 19.8 declarations (44% less). On a
+separate preregistered 12-case ArkType transfer it retained all 5 full-cluster hits with zero losses
+and reduced mean inspection from 18.9 declarations to 11 (41.9% less). It found no additional fresh
+hit, so the queue is retained as an efficiency advisory rather than promoted as an accuracy gain.
+
+Follow-up optimization attempts stay out of production. Replacing cluster slots with same-file
+declarations produced four development rescues but also three losses. Appending two same-file slots
+removed those development losses, but a second blind 12-case ArkType transfer produced 3/12 hits for
+both the existing and expanded plans, with zero rescues. Product-source filtering lost one prior hit,
+one-hop relationship expansion added none, and evidence/causal rerankers also failed their frozen
+transfer gates. The receipts remain in `bench/external/results`; rejected mechanisms cannot silently
+change the production ordering.
+
 Corrections can become scoped rules, but captured memory cannot hard-block on its own. Enforcement is
 deterministic and opt-in:
 
@@ -92,7 +149,7 @@ Git repo that every teammate can access, install the Matrix release on team mach
 have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.18.1
+npm i -g @davesheffer/hunch@1.19.0
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -107,7 +164,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.18.1
+npm i -g @davesheffer/hunch@1.19.0
 git pull
 hunch init
 hunch doctor

package/dist/cli/index.js

@@ -52,6 +52,9 @@ import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integra
 import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatContext, formatStructure } from "../core/format.js";
+import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
+import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
+import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
 import { buildDeliveryEnvelope } from "../core/delivery.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
@@ -61,7 +64,7 @@ import { computeStats, formatStats } from "../core/stats.js";
 import { injectionMode, resetSessionInjections } from "../core/hookcache.js";
 import { recordServed, servedSummary } from "../core/served.js";
 import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
-import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
+import { PIPELINE_LOOP, armExecutionObligations, beforeEditProbeVerdict, compileExecutableProbes, environmentExecutableProbes, environmentExecutionObligations, executionObligationBrief, isProductPath, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, proofCheckpoint, savePipelineState, stopVerdict, unverifiedNag, } from "../core/pipeline.js";
 import { draftDuplicateOf, isAcceptedDuplicateAnchor } from "../core/dupdetect.js";
 import { planAutoReview, planMutations } from "../core/autoreview.js";
 import { loadGoldenSet, evaluateRetrieval, evaluateTraversalLift } from "../eval/harness.js";
@@ -3636,6 +3639,69 @@ program
         console.log(`· ${rel(root, r.path)} already exists — left untouched. Delete it to regenerate.`);
     }
 });
+// ---- shortlist (experimental correction-stage diagnostic) -----------------
+program
+    .command("shortlist")
+    .description("Experimental repository-adaptive diagnostic: preserve a flat top five, add file-anchored semantic clusters, and emit an efficiency-tested advisory inspection plan capped at eleven. --evidence is annotation-only; no exact-owner claim.")
+    .argument("<issue...>", "issue report or reproduction prose")
+    .option("--limit <n>", "candidate count (1-5)", "5")
+    .option("--evidence <receipt>", "verified-evidence JSON receipt path, or - for stdin")
+    .option("--json", "emit the diagnostic as JSON")
+    .action((issueParts, opts) => {
+    const issue = issueParts.join(" ").trim();
+    if (!issue)
+        return fail("issue text must not be empty");
+    const rawLimit = Number(opts.limit);
+    if (!Number.isSafeInteger(rawLimit) || rawLimit < 1 || rawLimit > 5)
+        return fail("--limit must be an integer from 1 to 5");
+    const root = findRoot();
+    try {
+        let evidence = undefined;
+        if (opts.evidence) {
+            const raw = opts.evidence === "-" ? readFileSync(0, "utf8") : readFileSync(resolve(opts.evidence), "utf8");
+            if (Buffer.byteLength(raw, "utf8") > 1_000_000)
+                return fail("evidence receipt exceeds the 1 MB safety limit");
+            evidence = JSON.parse(raw);
+        }
+        const collection = collectCorrectionStageSources(root, issue);
+        const diagnostic = diagnoseIssueCorrectionStage(issue, collection.sources, rawLimit, evidence);
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ...diagnostic,
+                scan: {
+                    files_read: collection.files_read,
+                    bytes_read: collection.bytes_read,
+                    files_skipped: collection.files_skipped,
+                },
+            }, null, 2));
+        }
+        else {
+            console.log(formatCorrectionStageDiagnostic(diagnostic));
+            console.log(`Scan: ${collection.files_read} source file(s), ${collection.files_skipped} skipped by safety/budget limits.`);
+        }
+    }
+    catch (error) {
+        fail(`could not build the correction-stage shortlist: ${error.message}`);
+    }
+});
+// ---- evidence-map (compile supplied behavioral receipts) ------------------
+program
+    .command("evidence-map")
+    .description("Compile authenticated probe/execution/intervention receipts into a read-only evidence map. Runs no code and never claims an exact owner.")
+    .argument("<receipt>", "JSON receipt path, or - to read stdin")
+    .option("--json", "emit the evidence map as JSON")
+    .action((receiptFile, opts) => {
+    try {
+        const raw = receiptFile === "-" ? readFileSync(0, "utf8") : readFileSync(resolve(receiptFile), "utf8");
+        if (Buffer.byteLength(raw, "utf8") > 1_000_000)
+            return fail("evidence receipt exceeds the 1 MB safety limit");
+        const map = compileVerifiedEvidenceMap(JSON.parse(raw));
+        console.log(opts.json ? JSON.stringify(map, null, 2) : formatVerifiedEvidenceMap(map));
+    }
+    catch (error) {
+        fail(`could not compile the verified evidence map: ${error.message}`);
+    }
+});
 // ---- context (surgical retrieval) -----------------------------------------
 program
     .command("context")
@@ -3939,18 +4005,33 @@ program
         // Verification pipeline (delivery enforced, not hoped for — see core/pipeline.ts).
         // PostToolUse records facts; Stop gates on them. Both are pipeline-only events,
         // handled before the grounding dispatch below.
-        if (evt.hook_event_name === "PostToolUse" && evt.session_id && pipelineEnabled()) {
+        if ((evt.hook_event_name === "PostToolUse" || evt.hook_event_name === "PostToolUseFailure") && evt.session_id && pipelineEnabled()) {
             let st = loadPipelineState(evt.session_id);
+            const before = st;
+            let activity = null;
             if (/^(Edit|Write|MultiEdit)$/.test(evt.tool_name ?? "")) {
                 const p = evt.tool_input?.file_path;
-                if (p)
+                if (p) {
                     st = onEdit(st, toRepoRel(root, p));
+                    activity = { kind: "edit" };
+                }
             }
             else if (evt.tool_name === "Bash" || evt.tool_name === "PowerShell") {
-                st = onCommand(st, String(evt.tool_input?.command ?? ""));
+                const command = String(evt.tool_input?.command ?? "");
+                st = onCommand(st, command, evt.tool_outcome);
+                activity = { kind: "command", command };
             }
             else if (evt.tool_name === "Skill") {
                 st = onSkill(st, String(evt.tool_input?.skill ?? ""));
+                activity = { kind: "skill" };
+            }
+            if (activity) {
+                const checkpoint = proofCheckpoint(before, st, activity);
+                st = checkpoint.state;
+                savePipelineState(evt.session_id, st);
+                if (checkpoint.reminder)
+                    emitContext(provider, evt.hook_event_name, checkpoint.reminder);
+                return;
             }
             savePipelineState(evt.session_id, st);
             return;
@@ -3982,8 +4063,8 @@ program
             if (evt.session_id && pipelineEnabled()) {
                 const st = onPrompt(loadPipelineState(evt.session_id));
                 savePipelineState(evt.session_id, st);
-                if (!st.verifyAfterEdit) {
-                    text += `\n\n${UNVERIFIED_NAG}`;
+                if (!st.verifyAfterEdit || st.obligations.some((item) => item.status !== "satisfied")) {
+                    text += `\n\n${unverifiedNag(st)}`;
                     mustDeliver = true;
                 }
             }
@@ -4097,6 +4178,15 @@ program
             // is instead of pulling (or worse, grepping) for it. Cheap reads only
             // (no reindex, no drift walk); public store only — session transcripts
             // travel further than a terminal. Union view: `hunch now --private`.
+            let controllerBrief = "";
+            if (evt.session_id && pipelineEnabled()) {
+                const state = armExecutionObligations(loadPipelineState(evt.session_id), [
+                    ...compileExecutableProbes(environmentExecutableProbes()),
+                    ...environmentExecutionObligations(),
+                ], { replaceOrigin: "episode" });
+                savePipelineState(evt.session_id, state);
+                controllerBrief = executionObligationBrief(state);
+            }
             const s = new HunchStore(paths);
             try {
                 // Mode-aware: in unified ("shared") mode the public `.hunch/` is only a routing
@@ -4109,7 +4199,7 @@ program
                 if (!decisions.length) {
                     // Fresh graph: nothing to orient on, but the operating loop still ships.
                     if (pipelineEnabled())
-                        emitContext(provider, "SessionStart", PIPELINE_LOOP);
+                        emitContext(provider, "SessionStart", [PIPELINE_LOOP, controllerBrief].filter(Boolean).join("\n\n"));
                     return;
                 }
                 const L = [];
@@ -4142,6 +4232,8 @@ program
                 // (the zod bench showed ambient skills are read in ~0% of sessions).
                 if (pipelineEnabled())
                     L.push("", PIPELINE_LOOP);
+                if (controllerBrief)
+                    L.push("", controllerBrief);
                 const orientation = L.join("\n");
                 // Antigravity's nearest equivalent is PreInvocation, which can fire
                 // repeatedly in one conversation. Deduplicate it just like edit
@@ -4165,6 +4257,17 @@ program
         // → nothing for Hunch to say.
         if (!target || target.startsWith("..") || /^[a-zA-Z]:/.test(target))
             return;
+        // A compiled red→green probe is only meaningful if its red receipt exists
+        // before implementation. Firm/strict may deny two edits per prompt, then
+        // fail open so a malformed or unavailable probe can never deadlock work.
+        if ((firmness === "firm" || firmness === "strict") && evt.session_id && pipelineEnabled() && isProductPath(target)) {
+            const baseline = beforeEditProbeVerdict(loadPipelineState(evt.session_id));
+            if (baseline.block) {
+                savePipelineState(evt.session_id, baseline.state);
+                emitDeny(provider, baseline.reason ?? "Hunch evidence gate — establish the pre-edit probe baseline first.");
+                return;
+            }
+        }
         // Pre-edit grounding must resolve the same advertised graph as every CLI
         // and MCP consumer. Any unavailable/mismatched team route falls through to
         // the outer fail-open catch and emits nothing, preserving the hook's

package/dist/core/agenthook.js

@@ -68,6 +68,42 @@ function normalizeToolInput(value) {
     };
     return Object.values(out).some((v) => v !== undefined) ? out : undefined;
 }
+const MAX_TOOL_OUTPUT = 200_000;
+function toolOutput(value) {
+    if (typeof value === "string")
+        return value.slice(0, MAX_TOOL_OUTPUT);
+    const raw = obj(value);
+    if (raw) {
+        const parts = ["stdout", "stderr", "output", "content", "error", "message"]
+            .map((key) => raw[key])
+            .flatMap((item) => typeof item === "string" && item ? [item] : []);
+        if (parts.length)
+            return parts.join("\n").slice(0, MAX_TOOL_OUTPUT);
+    }
+    try {
+        return JSON.stringify(value ?? "").slice(0, MAX_TOOL_OUTPUT);
+    }
+    catch {
+        return "";
+    }
+}
+function normalizeToolOutcome(input, event) {
+    if (event !== "PostToolUse" && event !== "PostToolUseFailure")
+        return undefined;
+    const response = input.tool_response ?? input.toolResponse ?? input.tool_result ?? input.toolResult;
+    return {
+        // Claude Code splits successful and failed calls into separate lifecycle
+        // events. Providers without that split may expose an explicit result flag.
+        status: event === "PostToolUseFailure"
+            ? "failure"
+            : obj(response)?.success === false || obj(response)?.is_error === true || obj(response)?.isError === true
+                ? "failure"
+                : "success",
+        output: event === "PostToolUseFailure"
+            ? toolOutput(input.error ?? response)
+            : toolOutput(response),
+    };
+}
 function eventName(value, provider) {
     if (typeof value !== "string")
         return undefined;
@@ -75,6 +111,7 @@ function eventName(value, provider) {
     const map = {
         pretooluse: "PreToolUse",
         posttooluse: "PostToolUse",
+        posttoolusefailure: "PostToolUseFailure",
         userpromptsubmit: "UserPromptSubmit",
         sessionstart: "SessionStart",
         subagentstart: "SubagentStart",
@@ -139,11 +176,13 @@ export function normalizeHookEvent(raw, provider) {
             return null;
         const info = obj(input.tool_info) ?? obj(input.toolInput) ?? obj(input.tool_input);
         const toolInput = normalizeToolInput(info);
+        const toolOutcome = normalizeToolOutcome(input, event);
         return {
             hook_event_name: event,
             session_id: stringAt(input, "trajectory_id", "session_id", "sessionId"),
             tool_name: hunchToolName(stringAt(input, "agent_action_name", "tool_name", "toolName"), toolInput ?? {}),
             tool_input: toolInput,
+            ...(toolOutcome ? { tool_outcome: toolOutcome } : {}),
             prompt: stringAt(input, "prompt", "user_prompt", "userPrompt"),
         };
     }
@@ -151,11 +190,13 @@ export function normalizeHookEvent(raw, provider) {
     if (!event)
         return null;
     const toolInput = normalizeToolInput(input.tool_input ?? input.toolInput);
+    const toolOutcome = normalizeToolOutcome(input, event);
     return {
         hook_event_name: event,
         session_id: stringAt(input, "session_id", "sessionId", "conversation_id", "conversationId"),
         tool_name: hunchToolName(stringAt(input, "tool_name", "toolName"), toolInput ?? {}),
         tool_input: toolInput,
+        ...(toolOutcome ? { tool_outcome: toolOutcome } : {}),
         prompt: stringAt(input, "prompt", "user_prompt", "userPrompt"),
         source: stringAt(input, "source"),
         agent_type: stringAt(input, "agent_type", "agentType", "subagent_type", "subagentType"),