@davesheffer/hunch 1.41.6 → 1.42.0

package/dist/mcp/server.js

@@ -1,5 +1,6 @@
 import { conventionSupplements } from '../core/conventionDelivery.js';
 import { fieldCitationText } from "../core/fieldProvenance.js";
+import { siblingGrounding } from "../core/siblingfix.js";
 /**
  * MCP server — the structured two-way API into the Hunch (DESIGN.md §7 / App. A).
  * Exposes read tools (query/why/bug_lineage/check_constraints/get_dependents) and
@@ -15,6 +16,7 @@ import { z } from "zod";
 import { hunchPaths, findRoot, toPosixTarget, repoRelativeTarget } from "../core/paths.js";
 import { matchSymbolsTiered } from "../core/glob.js";
 import { resolveMcpToolset } from "./toolset.js";
+import { PolicyRepository } from "../constitution/repository.js";
 import { readConfig } from "../core/config.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
@@ -33,7 +35,7 @@ import { workspacesConfig } from "../core/config.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatus, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
-import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
+import { advertisedTeamRemoteContract, ensureTeamOverlay, isTeamStoreTrusted, overlayMatchesTeamRemote, teamWiringConsented, untrustedTeamStoreMessage, 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";
@@ -90,10 +92,12 @@ const invalid = (text) => err(`Invalid: ${text}`);
  *  cannot see an agent-driven `cd`/EnterWorktree, so a stdio server's cached root
  *  never moves on its own — this is the client-agnostic fallback, resolved fresh on
  *  every call by the generic tool wrapper below (see extractCwdHint). */
-const cwdHintField = z.string().optional().describe("Your ACTUAL current working directory for THIS call. Pass it whenever it differs from where this MCP " +
-    "session started — most commonly after entering a git worktree (EnterWorktree) or `cd`-ing to a different " +
-    "checkout — so the write commits to that repo/branch instead of silently landing on the server's original " +
-    "root. Omit only when you are still in the session's starting directory.");
+const cwdHintField = z.string().optional().describe("Your current directory, when it differs from where this session started (e.g. a worktree); " +
+    "writes then commit there, not to the original root.");
+/** Shared by hunch_record_decision/correction/finding — identical text repeated 3x
+ *  otherwise. hunch_context's task_id field differs (delivery vs. save) and keeps its
+ *  own description. */
+const saveTaskIdField = TaskIdSchema.optional().describe("Task ID, to attribute this save to it; never affects capture authority.");
 /** Pull `cwd` out of a tool call's already-parsed input without assuming any one
  *  tool's exact input shape — every write tool spreads the same cwdHintField in,
  *  but the wrapper below runs for every tool, read or write. */
@@ -594,6 +598,29 @@ const WHY_CAP = 6; // per record-type in hunch_why
 const DEP_CAP = 25; // dependents in hunch_get_dependents
 const QUERY_HITS = 8; // hunch_query matches (was 12)
 const FINDINGS_CAP = 12; // hunch_findings listing
+const FINDINGS_MAX = 50; // hunch_findings limit ceiling
+const FINDING_GIST_CHARS = 200; // list view: first sentence, clipped
+const FINDING_GIST_MIN = 60; // keep reading past a dateline like "Observed 2026-09-14."
+const NOT_A_SENTENCE_END = /(?:\b(?:e\.g|i\.e|vs|etc|cf|approx|incl)|^\d+|\s\d+)\.$/i;
+/** The list view's gist of an observation: whole sentences until the gist says
+ *  something (≥ FINDING_GIST_MIN chars), clipped to FINDING_GIST_CHARS. A
+ *  period after an abbreviation or a list number is not a sentence end. */
+export const firstSentence = (text) => {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const ends = /[.!?](?=\s|$)/g;
+    let cut = flat.length;
+    for (let m = ends.exec(flat); m; m = ends.exec(flat)) {
+        const end = m.index + 1;
+        if (NOT_A_SENTENCE_END.test(flat.slice(0, end)))
+            continue;
+        if (end >= FINDING_GIST_MIN) {
+            cut = end;
+            break;
+        }
+    }
+    const gist = flat.slice(0, cut);
+    return gist.length > FINDING_GIST_CHARS ? `${gist.slice(0, FINDING_GIST_CHARS - 1)}…` : gist;
+};
 const SEV_CONSTRAINT = { blocking: 3, warning: 2, advisory: 1 };
 const SEV_BUG = { critical: 4, high: 3, medium: 2, low: 1 };
 const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} more${hint ? ` — ${hint}` : ""})` : "";
@@ -683,6 +710,12 @@ const DELIVERY_OUTPUT_SCHEMA = z.object({
         reason: z.enum(["budget", "stale-provenance", "retired", "actionability-cap", "endpoint-not-delivered", "landscape-cap", "profile-cap", "low-confidence", "insufficient-context", "low-relevance"]),
         detail: z.string(),
     })),
+    // The per-record list above is a SAMPLE on MCP (see compactOmissions); these
+    // two carry the whole picture in constant size. Optional: the CLI envelope
+    // keeps its full list and omits them.
+    omitted_total: z.number().int().nonnegative().optional(),
+    omitted_truncated: z.boolean().optional(),
+    omitted_by_reason: z.record(z.string(), z.number().int().positive()).optional(),
     landscape: LANDSCAPE_FRAGMENT_SCHEMA.nullable(),
     budget_tokens: z.number().int().nonnegative(),
     used_chars: z.number().int().nonnegative(),
@@ -699,6 +732,28 @@ const DELIVERY_OUTPUT_SCHEMA = z.object({
         retry_hint: z.string().nullable(),
     }),
 });
+/** What tools/list advertises for hunch_context (#368). The landscape fragment embeds
+ *  the full Resource and Edge record schemas (~7k of the ~13k chars), which every
+ *  schema-loading host would pay on every session; it is advertised by its identity
+ *  fields only. The handler still parses the result with the full
+ *  DELIVERY_OUTPUT_SCHEMA, so the delivered shape is exactly as strict as before. */
+const DELIVERY_ADVERTISED_OUTPUT_SCHEMA = DELIVERY_OUTPUT_SCHEMA.extend({
+    // The MCP result carries drill-down ids only (see compactEnvelope, #371): the
+    // per-record receipt facts stay in the served ledger and hunch_report. Optional,
+    // so a reader of the full CLI envelope and of the MCP result shares one shape.
+    delivered: z.array(DELIVERY_OUTPUT_SCHEMA.shape.delivered.element.partial({
+        rank: true, delivery_reason: true, provenance_status: true, token_cost: true,
+    })),
+    supplements: z.array(DELIVERY_OUTPUT_SCHEMA.shape.supplements.element.partial({
+        reason: true, rank: true, token_cost: true,
+    })),
+    omitted: z.array(DELIVERY_OUTPUT_SCHEMA.shape.omitted.element.partial({ detail: true })),
+    landscape: z.object({
+        schema: z.literal("hunch.landscape-fragment/1"),
+        target: z.string(),
+        fragmentHash: z.string(),
+    }).passthrough().nullable(),
+});
 const CHANGE_IDENTITY_OUTPUT_SCHEMA = z.object({
     schema: z.literal(CHANGE_IDENTITY_SCHEMA_VERSION),
     algorithm: z.literal(CHANGE_IDENTITY_ALGORITHM),
@@ -815,7 +870,53 @@ function deliveredContext(root, target, envelope, sessionId) {
     ]);
     return {
         content: [{ type: "text", text: structuredContent.text }],
-        structuredContent,
+        structuredContent: compactEnvelope(structuredContent),
+    };
+}
+/** What the MCP result names per record: enough to drill down (hunch_why), no
+ *  more. A host shows the model either `content` or `structuredContent`, and
+ *  `text` is the only brief a structured-only host sees, so every other field
+ *  repeats what the brief already says; rank, costs and provenance stay in the
+ *  receipt. Undelivered supplements are dropped (the brief never showed them). */
+export function compactEnvelope(envelope) {
+    return {
+        ...compactOmissions(envelope),
+        delivered: envelope.delivered.map(({ kind, record_id }) => ({ kind, record_id })),
+        supplements: envelope.supplements.filter((s) => s.delivered).map(({ id, kind, delivered }) => ({ id, kind, delivered })),
+    };
+}
+/** Omitted records the MCP result names individually; the rest are counted. */
+const OMITTED_SAMPLE = 5;
+/** The budget must govern the whole tool result, not only the brief: a host
+ *  that shows the model structuredContent otherwise pays for one repeated
+ *  sentence per withheld record (104 of them measured on this repo, issue #371).
+ *  Keep a few ids — round-robin across reasons so every reason the brief cites
+ *  keeps an id to pass to hunch_why, budget first — and count all of them by
+ *  reason. Runs after recordServed and after the full envelope validated, so
+ *  receipts and receipt_id are unchanged. */
+export function compactOmissions(envelope) {
+    const groups = new Map();
+    for (const item of envelope.omitted)
+        groups.set(item.reason, [...(groups.get(item.reason) ?? []), item]);
+    const byReason = {};
+    for (const [reason, items] of groups)
+        byReason[reason] = items.length;
+    const order = [...groups.keys()].sort((left, right) => Number(right === "budget") - Number(left === "budget") || left.localeCompare(right));
+    const sample = [];
+    for (let depth = 0; sample.length < OMITTED_SAMPLE && sample.length < envelope.omitted.length; depth++) {
+        for (const reason of order) {
+            const item = groups.get(reason)[depth];
+            // The per-record detail sentence is left out: hunch_why(record_id) explains it.
+            if (item && sample.length < OMITTED_SAMPLE)
+                sample.push({ kind: item.kind, record_id: item.record_id, reason: item.reason });
+        }
+    }
+    return {
+        ...envelope,
+        omitted: sample,
+        omitted_total: envelope.omitted.length,
+        omitted_truncated: sample.length < envelope.omitted.length,
+        omitted_by_reason: byReason,
     };
 }
 // Capture-session tokens live in src/core/capturetoken.ts (pure + testable). These
@@ -957,10 +1058,14 @@ function prepareRoot(root, explicitOverlay, requireIndex) {
         const overlayWarning = store.overlayResolutionWarning(explicitOverlay && existsSync(teamFile));
         if (overlayWarning)
             console.error(`[hunch-mcp] ⚠ ${overlayWarning}`);
-        if (teamAdvertised && (store.mode !== "shared"
+        if (startupTeamConfig && (store.mode !== "shared"
             || !store.privateDir
             || !existsSync(store.privateDir)
+            || !teamWiringConsented(root, startupTeamConfig, store.privateDir)
             || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
+            const consented = !!store.privateDir && teamWiringConsented(root, startupTeamConfig, store.privateDir);
+            if (!consented && !isTeamStoreTrusted(root, startupTeamConfig))
+                throw new Error(untrustedTeamStoreMessage(startupTeamConfig));
             throw new Error("the advertised team memory store is unavailable or tracks a different remote; refusing to start MCP on another graph");
         }
         const startupTeamRoute = teamAdvertised && store.privateDir
@@ -1082,7 +1187,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // Everyday tools by default; specialist groups by evidence, config, or env
     // (src/mcp/toolset.ts). Hidden tools are never registered, so tools/list is
     // exactly what the host can call.
-    const toolset = resolveMcpToolset(root, { configSpec: readConfig(hunchPaths(root)).mcp_tools ?? null, pinned });
+    let hasPolicies = false;
+    try {
+        hasPolicies = new PolicyRepository(root, store).listPolicies().length > 0;
+    }
+    catch { /* unreadable policies: keep the group hidden */ }
+    const toolset = resolveMcpToolset(root, { configSpec: readConfig(hunchPaths(root)).mcp_tools ?? null, pinned, hasPolicies });
+    const hiddenTools = new Set(toolset.hidden);
     if (toolset.hidden.length)
         process.stderr.write(`[hunch-mcp] tool groups: ${toolset.groups.length ? toolset.groups.join(", ") : "core only"} (${toolset.source}); ${toolset.hidden.length} specialist tool(s) hidden — HUNCH_MCP_TOOLS=all or .hunch/config.json mcp_tools to expose\n`);
     const server = new McpServer({ name: "hunch", version: HUNCH_VERSION }, { instructions: MCP_INSTRUCTIONS });
@@ -1167,7 +1278,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         priorOnClose?.();
     };
     const registerTool = server.registerTool.bind(server);
-    server.registerTool = ((name, config, callback) => registerTool(name, config, async (...args) => {
+    server.registerTool = ((name, config, callback) => hiddenTools.has(name) ? undefined : registerTool(name, config, async (...args) => {
         // Claude Code CLI never advertises `roots`/`roots/list_changed` for an agent-driven
         // `cd` or EnterWorktree (issue #20) — the cached `root` above just never moves, so a
         // write silently lands wherever the process was spawned. Write tools accept an
@@ -1529,19 +1640,27 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_context (surgical retrieval) -----------------------------------
     server.registerTool("hunch_context", {
         title: "Assemble the minimal relevant Hunch slice for a task",
-        description: "Given a file, symbol, or task phrase you're about to work on, return the MINIMAL relevant memory — invariants to preserve, decisions explaining the design, bug history not to reintroduce, and the blast radius — as a compact brief. Call this FIRST when starting work on something. A task phrase that resolves to no file/symbol falls back to the closest graph matches. Returns a budgeted brief plus a delivery receipt. Not for exhaustive rationale on one file (hunch_why) or keyword search (hunch_query).",
+        description: "Given a file, symbol, or task phrase you're about to work on, return the MINIMAL relevant memory — invariants, decisions, bug history, blast radius — as a compact brief. Call FIRST when starting work. A task phrase with no file/symbol match falls back to the closest graph matches. Returns a budgeted brief plus a delivery receipt. Not for exhaustive rationale on one file (hunch_why) or keyword search (hunch_query).",
         inputSchema: {
             target: z.string().describe("A file path, symbol, or task phrase you're about to work on."),
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
             profile: z.enum(DELIVERY_PROFILES).optional().describe("Delivery role: builder (default), reviewer, or architect. Changes non-blocking order only."),
             as_of: z.string().optional().describe("Time-travel ref (commit/tag/branch): assemble the slice as it stood then."),
             task_id: TaskIdSchema.optional().describe("Exact task ID from hunch_task; records this delivery for the task's contribution report."),
+            include: z.array(z.enum(["recent_tasks", "project_dna"])).optional().describe("Opt-in extras; omitted by default to keep the brief small."),
             cwd: cwdHintField,
         },
-        outputSchema: DELIVERY_OUTPUT_SCHEMA,
-    }, async ({ target, budget_tokens, profile, as_of, task_id }, extra) => {
+        outputSchema: DELIVERY_ADVERTISED_OUTPUT_SCHEMA,
+    }, async ({ target, budget_tokens, profile, as_of, task_id, include }, extra) => {
         const deliver = (envelope) => {
             const result = deliveredContext(root, as_of ? `${target} (as_of:${as_of})` : target, envelope, extra.sessionId);
+            // Same sibling-fix lesson the pre-edit hook injects, for a file target.
+            // Sibling lessons need a repo-relative file; a target outside the repo gets none.
+            const rel = relative(root, resolve(root, target)).replace(/\\/g, "/");
+            const siblings = as_of || !rel || rel.startsWith("..") || isAbsolute(rel) ? null : siblingGrounding(root, rel, store.recs("symbols"));
+            // Leads the result: the most specific lesson must not trail the memory slice.
+            if (siblings?.text)
+                result.content.unshift({ type: "text", text: siblings.text });
             if (task_id) {
                 try {
                     // Historical contexts must not borrow today's record text/revision.
@@ -1561,14 +1680,18 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         if (as_of && !asOf)
             return invalid(`Could not resolve as_of "${as_of}" to a commit.`);
         const ctx = store.assembleContext(target, budget_tokens ?? 1500, { asOf });
+        // Both extras below cost brief tokens (and, for DNA/recent-tasks selection, extra
+        // latency) — opt-in only via `include`, omitted from the default brief.
         let dnaSupplement = null;
-        try {
-            dnaSupplement = projectDnaDeliverySupplement(discoverProjectDna(root, as_of ?? "HEAD"));
-        }
-        catch {
-            // Context retrieval must keep its existing graceful behavior when the
-            // Git checkout cannot provide DNA; the dedicated DNA tool reports the
-            // exact derivation error when a caller needs diagnostics.
+        if (include?.includes("project_dna")) {
+            try {
+                dnaSupplement = projectDnaDeliverySupplement(discoverProjectDna(root, as_of ?? "HEAD"));
+            }
+            catch {
+                // Context retrieval must keep its existing graceful behavior when the
+                // Git checkout cannot provide DNA; the dedicated DNA tool reports the
+                // exact derivation error when a caller needs diagnostics.
+            }
         }
         // The "State" section (nuryel.state/1): current derived, in-force commitments and the
         // latest receipts whose subject/text matches the target — bounded, ordered, sharing the
@@ -1576,7 +1699,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         const stateGrounding = asOf ? [] : stateSupplements(store.stateSlice(target), target);
         // Recent finished tasks that touched the target: what earlier agent work did
         // here, from graph memory. Advisory history sharing the brief's budget.
-        const recentTasks = asOf ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, task_id ?? null, target)), target);
+        const recentTasks = (asOf || !include?.includes("recent_tasks"))
+            ? []
+            : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, task_id ?? null, target)), target);
         const options = {
             root,
             symbols: store.recs("symbols"),
@@ -1633,7 +1758,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_shortlist (bounded correction-stage diagnostic) ----------------
     server.registerTool("hunch_shortlist", {
         title: "Shortlist the likely correction stage and declarations",
-        description: "Experimental, deterministic, read-only repository-adaptive diagnostic for a schema/validation issue or reproduction. Preserves a flat top five, adds a transfer-tested hierarchical inspection view, and emits an efficiency-tested advisory progressive inspection queue capped at eleven declarations with deterministic receipts. Optional authenticated same-claim evidence is annotated but cannot reorder candidates because fresh transfer rejected that mechanism. It never claims an exact implementation owner or per-case confidence and does not edit, gate, or capture memory.",
+        description: "Experimental, deterministic, read-only diagnostic for a schema/validation issue or reproduction: a flat top five, a hierarchical inspection view, and an advisory progressive inspection queue (max eleven declarations) with receipts. Same-claim evidence is annotated, never reorders. It never claims an exact implementation owner or per-case confidence and does not edit, gate, or capture memory.",
         inputSchema: {
             issue: z.string().min(1).max(100_000).describe("Issue report or reproduction prose, including observed and expected behavior when available."),
             limit: z.number().int().min(1).max(5).optional().describe("Candidate count, capped at five (default 5)."),
@@ -1680,18 +1805,27 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         title: "Recent activity + the roadmap (the hot view)",
         description: "What just happened and what's next, straight from the graph: the last N decisions, the ROADMAP, and any inline human question such as an imported ADR awaiting explicit approve/decline. Call at session start to orient, or before planning what to work on. Same data as the wiki's now.md. Public store only, EXCEPT a queued commit-repair's liveness is checked against the full store (so a private-overlay decision's fully-answerable repair doesn't go silently unanswerable); only its id and the commit shas ever surface, never its title.",
         inputSchema: {
-            recent_limit: z.number().optional().describe("How many recent decisions to include (default 10)."),
+            recent_limit: z.number().optional().describe("How many recent decisions to include (default 5)."),
+            roadmap_limit: z.number().optional().describe("How many roadmap entries to include (default 2); the rest are counted."),
         },
-    }, async ({ recent_limit }) => {
-        const { recent, roadmap, pendingReview } = nowData(store.json.loadAll("decisions"), recent_limit ?? 10);
+    }, async ({ recent_limit, roadmap_limit }) => {
+        // Bounded by default (#371): the hot view is read at session start, so its
+        // size is paid on every session; the rest stays one call away.
+        const decisions = store.json.loadAll("decisions");
+        const { recent, roadmap, pendingReview } = nowData(decisions, recent_limit ?? 5);
+        const shownRoadmap = roadmap.slice(0, Math.max(0, roadmap_limit ?? 2));
         const L = [`🔥 Recent (${recent.length}):`];
         for (const r of recent)
             L.push(`  ${r.date} [${r.status}] ${r.title} (${r.id}${r.topic ? `, ${r.topic}` : ""})`);
+        if (decisions.length > recent.length)
+            L.push(`  +${decisions.length - recent.length} more — hunch_now(recent_limit) or hunch now`);
         L.push("", `🗺 Roadmap — live proposed decisions (${roadmap.length}):`);
         if (!roadmap.length)
             L.push("  (empty — record intent as a PROPOSED decision and it appears here)");
-        for (const r of roadmap)
+        for (const r of shownRoadmap)
             L.push(`  • ${r.title} (${r.id}${r.topic ? `, ${r.topic}` : ""}, since ${r.date})\n      ${r.note}`);
+        if (roadmap.length > shownRoadmap.length)
+            L.push(`  +${roadmap.length - shownRoadmap.length} more — hunch_now(roadmap_limit) or hunch now`);
         if (pendingReview > 0)
             L.push("", `${pendingReview} legacy un-vouched draft(s) — \`hunch adopt-drafts\` auto-trusts them as advisory (new captures land trusted automatically).`);
         // Workspace ledger, from stored PUBLIC records only (same jurisdiction rule as the rest
@@ -1723,7 +1857,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // git; other machines come from stored records, which are display-only.
     server.registerTool("hunch_workspaces", {
         title: "Worktrees and branches across machines",
-        description: "The workspace ledger: which git worktrees are open on which machine, and every local branch with a deterministic verdict — merged (ancestry / squash / rebase), never pushed, upstream gone, dirty worktree — plus a recommended action per branch. Call this INSTEAD of running git branch / git worktree list / git log to answer 'what is open, what is stale, what can be deleted'. This machine is read live; other machines from memory (a machine older than the staleness window is marked unverified). Read-only: it never deletes anything. Not for design rationale (hunch_why) or code structure (hunch_structure).",
+        description: "Worktrees per machine and every local branch with a deterministic verdict — merged (ancestry / squash / rebase), never pushed, upstream gone, dirty — plus a recommended action. Use INSTEAD of git branch / git worktree list to see what is open, stale, or deletable. This machine is read live; others from memory (stale ones marked unverified). Read-only. Not for design rationale (hunch_why) or code structure (hunch_structure).",
         inputSchema: {
             view: z.enum(["inventory", "branches"]).optional().describe("inventory = one row per worktree (default); branches = one row per branch with its verdict and action."),
             machine: z.string().optional().describe("Only this machine label."),
@@ -1772,7 +1906,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // (con_e04226bd05): no Claude-specific behavior.
     server.registerTool("hunch_escalations", {
         title: "Decisions the human must make now (ask inline, not a queue)",
-        description: "The rare decisions the graph cannot resolve on its own — surfaced so you ASK THE USER in the prompt at the moment, then act. Auto-captured memory is trusted automatically and never appears here; this returns topic conflicts (>1 live decision for one topic), premise-stale decisions (a live decision whose recorded REASON no longer holds — its authority is unchanged until the human re-attests, supersedes, or retires), one exact imported ADR at a time awaiting approve/decline, a queued commit-provenance repair (the post-merge hook detected a decision's commit was squash-merged away but never applies the fix unattended — apply with `hunch repair-provenance --apply` or leave it queued), and Constitution human moments (candidate policies awaiting review, proposed policies awaiting an activation decision). Normally empty. Raise each question with the user; do NOT decide it for them — an entry is a question, silence is never approval. Reads the public store, or the unified overlay when the repo is in shared mode — never private-mode overlay records, EXCEPT a queued commit-repair, whose liveness is checked against the full store; only its id and commit shas ever surface, never its title.",
+        description: "Decisions only the human can make, so you ASK THE USER before acting: topic conflicts (>1 live decision per topic), premise-stale decisions (the recorded reason no longer holds; authority is unchanged until the human re-attests, supersedes, or retires), one imported ADR at a time awaiting approve/decline, a queued commit-provenance repair (`hunch repair-provenance --apply`, never applied unattended), and Constitution policies awaiting review or activation. Normally empty. Never decide an entry for the user — silence is never approval. Reads the public or shared-mode store, never private-mode records — except a queued repair, whose liveness is checked against the full store and which surfaces only its id and commit shas.",
         inputSchema: {},
     }, async () => {
         const items = pendingEscalations(store.advisoryRecs("decisions"));
@@ -1806,7 +1940,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_review_imported_adr (the chat-native countersign) --------------
     server.registerTool("hunch_review_imported_adr", {
         title: "Apply the human's exact imported-ADR answer",
-        description: "Use ONLY after the human explicitly answers the currently surfaced imported-ADR question with approve or decline in this conversation. Never infer approval from silence, continued work, a generic earlier sign-off, or the ADR file's own status. The source and review hashes bind the answer to both the exact bytes and mapped meaning shown. Approve grants human-confirmed authority; decline records review but keeps the ADR advisory.",
+        description: "Use ONLY after the human explicitly answers the currently surfaced imported-ADR question with approve or decline, in this conversation. Never infer approval from silence, continued work, an earlier generic sign-off, or the ADR file's own status. The source and review hashes bind the answer to the exact bytes and mapped meaning shown. Approve grants human-confirmed authority; decline records review but keeps the ADR advisory.",
         inputSchema: {
             decision_id: z.string().regex(/^dec_[A-Za-z0-9_-]+$/),
             expected_source_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
@@ -1887,7 +2021,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_capture_decision (decision-grounding: the grilling front door) --
     server.registerTool("hunch_capture_decision", {
         title: "Capture a decision (grilling interview)",
-        description: "Start a decision-capture interview: returns the grilling protocol (interrogate ONE question at a time until the decision tree is resolved) plus a capture-session token. Grill the human, then commit via hunch_record_decision with the token + confirmed topic. Use for '/capture', 'record this decision', 'grill me on this'. The token proves the write is the tail of an interview, not a silent guess — it is NOT a human signature: human-confirmed authority needs the human's own confirmation (a client prompt, or `hunch review --confirm <id>`). Returns the protocol text and the token; it writes nothing. Not for corrections (hunch_record_correction) or observations (hunch_record_finding).",
+        description: "Start a decision-capture interview ('/capture', 'grill me'): returns the protocol — ONE question at a time until resolved — and a capture-session token; writes nothing. Then commit via hunch_record_decision with the token + confirmed topic. The token is NOT a human signature: human-confirmed authority needs the human's own confirmation (client prompt, or `hunch review --confirm <id>`). Not for corrections (hunch_record_correction) or observations (hunch_record_finding).",
         inputSchema: {
             topic: z.string().optional().describe("proposed topic anchor (confirm with the human before committing)"),
             seed: z.string().optional().describe("what the decision is about, to focus the first question"),
@@ -1941,7 +2075,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_record_decision (write-back) -----------------------------------
     server.registerTool("hunch_record_decision", {
         title: "Record a decision (write-back)",
-        description: "Persist a new Decision (ADR) into Hunch with provenance. Use after making a non-trivial design choice so future sessions are grounded in it. Set private:true to keep a SENSITIVE decision out of a (possibly public) repo — it is written to the HUNCH_PRIVATE_DIR overlay store and stays queryable locally, never committed here. Returns the stored id, home, and status. Not for a rule the agent must obey (hunch_record_correction) or an observation with no choice made (hunch_record_finding). Errors are classed by prefix: 'Refused:' means a gate held (resolve it, do not retry), 'Invalid:' means fix the arguments, 'Failed to' means internal.",
+        description: "Persist a Decision (ADR) with provenance after a non-trivial design choice. private:true keeps it in the HUNCH_PRIVATE_DIR overlay, never committed here. Returns id, home, status. Not for an agent-obeyed rule (hunch_record_correction) or an observation (hunch_record_finding). Errors: 'Refused:' a gate held (don't retry); 'Invalid:' fix arguments; 'Failed to' internal.",
         inputSchema: {
             decision: z.object({
                 title: z.string(),
@@ -1951,7 +2085,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 alternatives_rejected: z.array(z.string()).optional(),
                 related_files: z.array(z.string()).optional(),
                 related_components: z.array(z.string()).optional(),
-                topic: z.string().optional().describe("decision-grounding anchor — one topic per decision; enables doc≠graph drift detection for it. Omit to leave un-anchored."),
+                topic: z.string().optional().describe("decision-grounding anchor — one topic per decision; enables doc≠graph drift detection. Omit to leave un-anchored."),
                 // FLAT, matching PremiseSchema exactly. A nested { check: {...} } shape is
                 // silently STRIPPED by Zod, leaving a claim-only premise — and a claim-only
                 // premise is "documented only (no check attached)", which ALWAYS HOLDS. An
@@ -1959,20 +2093,20 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 // the exact fail-open this feature exists to prevent. Keep in lockstep with
                 // PremiseSchema in src/core/types.ts.
                 premises: z.array(z.object({
-                    claim: z.string().min(1).describe("the human-readable reason this decision rests on"),
-                    path_absent: z.string().optional().describe("premise holds while this repo-relative path does NOT exist. REQUIRES `under`. Prefer path_exists where you can — a negative probe fails OPEN, a positive one fails closed."),
-                    under: z.string().optional().describe("required with path_absent: an EXISTING repo-relative ANCESTOR of it (path_absent 'src/gateway' -> under 'src'). When the anchor disappears the premise reads unevaluable instead of silently 'still absent'."),
-                    path_exists: z.string().optional().describe("premise holds while this repo-relative path exists"),
-                    review_by: z.string().optional().describe("dated attestation: premise holds until this ISO date, then needs re-attesting"),
-                    attested: z.string().optional().describe("ISO date a human last attested the claim (informational)"),
-                })).optional().describe("the checkable reasons this decision rests on — at most ONE check per premise (path_absent | path_exists | review_by). A dead premise NEVER changes authority; it raises an escalation for the human. Omit on re-record to keep the incumbent's premises."),
+                    claim: z.string().min(1).describe("human-readable reason"),
+                    path_absent: z.string().optional().describe("holds while this repo-relative path does NOT exist; requires `under`. Prefer path_exists — negative probes fail OPEN, positive fail closed."),
+                    under: z.string().optional().describe("required with path_absent: an EXISTING repo-relative ancestor ('src/gateway' -> under 'src'). If it disappears, reads unevaluable, not silently absent."),
+                    path_exists: z.string().optional().describe("holds while this repo-relative path exists"),
+                    review_by: z.string().optional().describe("holds until this ISO date, then needs re-attesting"),
+                    attested: z.string().optional().describe("ISO date a human last attested (informational)"),
+                })).optional().describe("checkable reasons this decision rests on, at most one check per premise. A dead premise never changes authority, only raises a human escalation. Omit on re-record to keep the incumbent's."),
                 status: z.enum(["proposed", "accepted", "rejected", "superseded"]).optional(),
                 commit: z.string().optional(),
-                supersedes: z.string().optional().describe("id of a decision this one replaces — closes its valid-time window (invalidate, don't delete)"),
-                private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — for sensitive decisions kept out of a public repo. Errors if no private store is configured."),
+                supersedes: z.string().optional().describe("id of a decision this replaces — closes its valid-time window (invalidate, don't delete)"),
+                private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR), not the committed repo — for sensitive decisions. Errors if no private store is configured."),
             }),
-            capture_token: z.string().optional().describe("token from hunch_capture_decision — proves this write is the tail of a grilling interview (not a human signature: Hunch asks the human to confirm in the client when supported). Omit only for a quick manual record (a deprecation nudge is returned)."),
-            task_id: TaskIdSchema.optional().describe("Exact task ID for observing this successful save; reporting never changes capture authority."),
+            capture_token: z.string().optional().describe("token from hunch_capture_decision — proves this write tails a grilling interview (not a signature: the client may still ask the human to confirm). Omit only for a quick manual record (returns a deprecation nudge)."),
+            task_id: saveTaskIdField,
             cwd: cwdHintField,
         },
     }, async ({ decision, capture_token, task_id }) => {
@@ -2196,18 +2330,18 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_record_correction (write-back: "Never Twice") ------------------
     server.registerTool("hunch_record_correction", {
         title: "Capture a correction as an enforced constraint (Never Twice)",
-        description: "When a human corrects the agent ('no, do it this way' / 'never call X here'), persist that correction as a first-class, SCOPED Constraint with provenance — so the pre-edit hook and the CI Constraint Guard hold EVERY assistant to it from now on, instead of it being forgotten next session. Writes to the shared .hunch/ graph (client-agnostic). Set severity:'blocking' only when the human said never/must; set applies_to_all:true only when the rule is genuinely repo-wide (otherwise it is scoped to scope_hint_file). Returns the constraint id, scope, and what it now enforces. Not for a design choice with alternatives (hunch_record_decision) or an observed gap with no rule yet (hunch_record_finding).",
+        description: "When a human corrects the agent ('never call X here'), persist it as a SCOPED Constraint with provenance, so the pre-edit hook and CI Constraint Guard hold every assistant to it. severity:'blocking' only when the human said never/must; applies_to_all:true only for a genuinely repo-wide rule (else scoped to scope_hint_file). Returns the constraint id and scope. Not for a design choice (hunch_record_decision) or an observed gap with no rule yet (hunch_record_finding).",
         inputSchema: {
             rule: z.string().describe("The invariant in the human's words, e.g. \"never call the pay-per-token API here\"."),
-            scope_hint_file: z.string().optional().describe("A file the correction was about; scopes the constraint to it (the conservative default). Prefer a REPO-RELATIVE path (src/foo.ts); an absolute path is relativized against the repo root, and one outside the repo is discarded rather than scoped to a path that could never match."),
+            scope_hint_file: z.string().optional().describe("File the correction was about; scopes the constraint to it (conservative default). Prefer a repo-relative path — an absolute one is relativized, and one outside the repo is discarded rather than scoped to a path that could never match."),
             severity: z.enum(["advisory", "warning", "blocking"]).optional().describe("Default 'warning'. Use 'blocking' only for a hard never/must rule."),
             applies_to_all: z.boolean().optional().describe("True ONLY if the rule is genuinely repo-wide (scopes to **); required to make a repo-wide rule blocking."),
             type: z.enum(["security", "performance", "correctness", "architecture", "compliance"]).optional(),
             rationale: z.string().optional().describe("Why it must hold."),
             source_decision: z.string().optional().describe("id of a decision this correction derives from."),
-            private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — a sensitive rule enforced locally (pre-edit hook + local check) but never exposed in a public PR comment. Errors if no private store is configured."),
-            capture_token: z.string().optional().describe("token from hunch_capture_decision. The rule is recorded and enforced either way, as agent testimony capped at severity 'warning'. A token never lets it DENY: blocking authority comes only from a human running the printed `hunch review --confirm <id> --severity <s>` command."),
-            task_id: TaskIdSchema.optional().describe("Exact task ID for observing this successful save; reporting never changes capture authority."),
+            private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR), not the committed repo — enforced locally (pre-edit hook + check), never in a public PR comment. Errors if no private store is configured."),
+            capture_token: z.string().optional().describe("token from hunch_capture_decision. Recorded and enforced either way, as agent testimony capped at severity 'warning'. A token never lets it DENY: blocking authority needs a human running the printed `hunch review --confirm <id> --severity <s>`."),
+            task_id: saveTaskIdField,
             cwd: cwdHintField,
         },
     }, async (input) => {
@@ -2295,12 +2429,12 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_record_finding (write-back: observations, no diff) ---------------
     server.registerTool("hunch_record_finding", {
         title: "Record a finding (an observation with no code change)",
-        description: "Persist an OBSERVATION into Hunch — audited knowledge with no diff: an audit that surfaced a gap (e.g. queries missing tenant scoping), a measured number, a vendor/platform fact, an incident with no code fix. The anchor is a date + evidence, not a commit. Advisory: it grounds future edits to the affected files/symbols (pre-edit hook + hunch_context) and is listed by hunch_findings; it never blocks. Re-record the SAME title to update triage (e.g. triage:'resolved' + resolved_commit once fixed). If the finding is a violation of a rule that ISN'T recorded yet, record the rule first (hunch_record_correction) and link it via violates_constraint. Returns the finding id, triage, and the files it now grounds. Not for a rule to enforce (hunch_record_correction) or a choice between alternatives (hunch_record_decision).",
+        description: "Persist an OBSERVATION with no code change — an audit gap, a measured number, a platform fact, an incident — anchored to a date + evidence, not a commit. Advisory: grounds future edits to the affected files (pre-edit hook, hunch_context) and is listed by hunch_findings; never blocks. Re-record the SAME title to update triage (e.g. triage:'resolved' + resolved_commit). If it violates an unrecorded rule, record the rule first (hunch_record_correction) and link it via violates_constraint. Not for a rule to enforce (hunch_record_correction) or a choice between alternatives (hunch_record_decision).",
         inputSchema: {
             finding: z.object({
                 title: z.string().describe("stable one-line name — re-recording the same title updates the finding"),
                 observation: z.string().describe("what was observed, in plain words"),
-                evidence: z.array(z.string()).optional().describe("the query/command run + representative output — a finding without evidence is an opinion"),
+                evidence: z.array(z.string()).optional().describe("query/command run + representative output — a finding without evidence is an opinion"),
                 method: z.string().optional().describe("rb_* runbook that re-runs the audit (makes it re-verifiable)"),
                 severity: z.enum(["low", "medium", "high", "critical"]).optional(),
                 triage: z.enum(["open", "accepted-risk", "scheduled", "resolved", "stale"]).optional().describe("default 'open'. 'resolved' should carry resolved_commit."),
@@ -2309,9 +2443,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 violates_constraint: z.string().optional().describe("con_* this finding is a known violation of"),
                 spawned_decision: z.string().optional().describe("dec_* recorded in response"),
                 resolved_commit: z.string().optional().describe("the commit that fixed it (with triage:'resolved')"),
-                private: z.boolean().optional().describe("write into the PRIVATE overlay store instead of the committed repo. Errors if no private store is configured."),
+                private: z.boolean().optional().describe("write into the PRIVATE overlay store, not the committed repo. Errors if no private store is configured."),
             }),
-            task_id: TaskIdSchema.optional().describe("Exact task ID for observing this successful save; reporting never changes capture authority."),
+            task_id: saveTaskIdField,
             cwd: cwdHintField,
         },
     }, async ({ finding, task_id }) => {
@@ -2557,32 +2691,44 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_findings (read: the open-observations ledger) --------------------
     server.registerTool("hunch_findings", {
         title: "Open findings for a scope",
-        description: "List LIVE findings (observed gaps/debt with no fix yet — triage open/accepted-risk/scheduled) concerning a file, glob, or symbol; omit scope for the whole ledger. Call before planning work in an area to inherit past audits instead of re-discovering them. Advisory; resolved/stale findings are excluded unless all:true. Not for invariants (hunch_check_constraints) or bug history (hunch_bug_lineage): findings are observations, never rules.",
+        description: "List LIVE findings (observed gaps/debt with no fix yet — triage open/accepted-risk/scheduled) for a file, glob, or symbol; omit scope for the whole ledger. Call before planning work in an area to inherit past audits instead of re-discovering them. Lists each finding's first sentence; pass id for one finding's full observation. Advisory; resolved/stale findings are excluded unless all:true. Not for invariants (hunch_check_constraints) or bug history (hunch_bug_lineage): findings are observations, never rules.",
         inputSchema: {
             scope: z.string().optional().describe("a path, glob, or symbol (e.g. src/procs/** or dbo.GetOrders); omit for all"),
             all: z.boolean().optional().describe("include resolved/stale findings (the full history)"),
+            id: z.string().optional().describe("one finding id (fnd_*) — returns its full observation, whatever its triage; scope/all/limit are ignored"),
+            limit: z.number().int().min(1).max(FINDINGS_MAX).optional().describe(`how many to list (default ${FINDINGS_CAP}, max ${FINDINGS_MAX})`),
         },
-    }, async ({ scope, all }) => {
+    }, async ({ scope, all, id, limit }) => {
+        const concerns = (f) => [...f.affected_files, ...f.affected_symbols].join(", ") || "(unscoped)";
+        const links = (f) => [f.violates_constraint ? `violates ${f.violates_constraint}` : "", f.method ? `re-verify via ${f.method}` : "", f.resolved_commit ? `fixed in ${f.resolved_commit.slice(0, 9)}` : ""].filter(Boolean).join("; ");
+        if (id) {
+            const f = store.recs("findings").find((r) => r.id === id);
+            if (!f)
+                return ok(`No finding "${id}".`);
+            return ok(`[${f.triage}/${f.severity}] ${f.title} (${f.id}, observed ${f.observed_at.slice(0, 10)})\n${f.observation}\nconcerns: ${concerns(f)}${links(f) ? `\n${links(f)}` : ""}`);
+        }
         const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
         const list = (scope ? store.liveFindingsFor(scope) : store.recs("findings").filter(all ? () => true : live))
             .filter(all ? () => true : live)
             .sort((a, b) => (SEV_BUG[b.severity] ?? 0) - (SEV_BUG[a.severity] ?? 0) || a.id.localeCompare(b.id));
         if (!list.length)
             return ok(`No ${all ? "" : "live "}findings${scope ? ` for "${scope}"` : ""}. (Record one after an audit with hunch_record_finding.)`);
-        const L = list.slice(0, FINDINGS_CAP).map((f) => {
-            const links = [f.violates_constraint ? `violates ${f.violates_constraint}` : "", f.method ? `re-verify via ${f.method}` : "", f.resolved_commit ? `fixed in ${f.resolved_commit.slice(0, 9)}` : ""].filter(Boolean).join("; ");
-            return `• [${f.triage}/${f.severity}] ${f.title} (${f.id}, observed ${f.observed_at.slice(0, 10)})\n    ${f.observation}\n    concerns: ${[...f.affected_files, ...f.affected_symbols].join(", ") || "(unscoped)"}${links ? `\n    ${links}` : ""}`;
+        const cap = limit ?? FINDINGS_CAP;
+        const L = list.slice(0, cap).map((f) => {
+            const where = [...f.affected_files, ...f.affected_symbols];
+            const shown = where.length > 3 ? `${where.slice(0, 3).join(", ")} (+${where.length - 3})` : concerns(f);
+            return `• [${f.triage}/${f.severity}] ${f.title} (${f.id}, observed ${f.observed_at.slice(0, 10)})\n    ${firstSentence(f.observation)}\n    concerns: ${shown}`;
         });
-        return ok(`${list.length} finding(s)${scope ? ` for "${scope}"` : ""}:\n${L.join("\n")}${more(list.length, FINDINGS_CAP)}`);
+        return ok(`${list.length} finding(s)${scope ? ` for "${scope}"` : ""} — hunch_findings(id) for one in full:\n${L.join("\n")}${more(list.length, cap, "raise limit or narrow scope")}`);
     });
     server.registerTool("hunch_policy_upgrade_correction", {
         title: "Build a proved review proposal from one exact correction",
-        description: "Upgrade the exact supported static ESM import-declaration package projection of one captured correction into a deterministic review packet when the baseline is clean. Writes proposal, plan, proof, and evidence artifacts only; never activates, warns, blocks, or grants authority. Unsupported corrections keep their immediate legacy guard and create no policy.",
+        description: "Upgrade the exact supported static ESM import-declaration package projection of one captured correction into a deterministic review packet, when the baseline is clean. Writes proposal, plan, proof, and evidence artifacts only; never activates, warns, blocks, or grants authority. Unsupported corrections keep their immediate legacy guard and create no policy.",
         inputSchema: {
             constraint_id: z.string().describe("Captured correction constraint id (con_*)."),
             public_only: z.boolean().optional().describe("Read and write only the public correction home."),
-            private_only: z.boolean().optional().describe("Keep correction-derived evidence/policy/proof artifacts in the configured private overlay; the public source-code graph is refreshed before proof."),
-            include_artifacts: z.boolean().optional().describe("Include the complete Policy IR, proof plan, proof receipts, and evidence object. Default output is a concise review envelope."),
+            private_only: z.boolean().optional().describe("Keep correction-derived artifacts in the private overlay; the public source-code graph is refreshed before proof."),
+            include_artifacts: z.boolean().optional().describe("Include the full Policy IR, proof plan, receipts, and evidence. Default is a concise review envelope."),
             cwd: cwdHintField,
         },
     }, async ({ constraint_id, public_only, private_only, include_artifacts }) => {
@@ -2647,7 +2793,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_merge_verdict (Causal Merge Verdict — read-only, client-agnostic) --
     server.registerTool("hunch_merge_verdict", {
         title: "Causal merge verdict: is this change safe against the recorded WHY?",
-        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base, commit, and working to check STAGED changes; pass working:true for all local changes, base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change. Not for an advisory impact map (hunch_pr_impact), intent erosion with no diff (hunch_conformance), or a sealed proof of one committed transition (hunch_change_proof).",
+        description: "Before opening or merging a PR, replay a diff against memory and return ONE verdict — BLOCK / WARN / PASS — citing the decision and bug behind each invariant in scope, plus advisory blast-radius invariants, re-introduced retired code, and symbols already defined elsewhere. Deterministic, no LLM. Default: staged changes; working:true for all local changes, base (e.g. origin/main) for a PR range, commit for one commit. Not for an advisory impact map (hunch_pr_impact), or intent erosion with no diff (hunch_conformance).",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Diff a single commit (sha/ref). Omit base AND commit to check staged changes."),
@@ -2690,7 +2836,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_pr_impact (read-only impact surface — advisory, never gates) ----
     server.registerTool("hunch_pr_impact", {
         title: "PR impact: the dependency + memory surface of a change",
-        description: "Given a change (staged, working tree, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base, commit, and working for staged changes. Not for a verdict (hunch_merge_verdict) or a sealed proof (hunch_change_proof).",
+        description: "IMPACT SURFACE of a change (default staged; or working:true, base, or commit): files that transitively depend on it, invariants in scope and via blast radius, and decisions on the touched files. Read-only, advisory. Not for a verdict (hunch_merge_verdict).",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Impact of a single commit (sha/ref). Omit base AND commit for staged changes."),