@davesheffer/hunch 1.41.6 → 1.43.0

package/dist/extractors/nativeTreeSitter.js

@@ -1,9 +1,15 @@
 import { createRequire } from "node:module";
-import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { copyFileSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
 const runtimeRequire = createRequire(import.meta.url);
+/** Legacy per-process copy dirs (`hunch-tree-sitter-<pid>-*`), pruned when dead. */
 const COPY_PREFIX = "hunch-tree-sitter-";
+/** Per-user cache of content-addressed copies (`hunch-tree-sitter-cache-<user>`). */
+const CACHE_PREFIX = "hunch-tree-sitter-cache-";
+/** A hash dir no process has used for this long is pruned. */
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const NATIVE_PACKAGES = [
     "tree-sitter",
     "tree-sitter-typescript",
@@ -84,21 +90,116 @@ function removeStaleCopies() {
 function environmentKey(packageName) {
     return `${packageName.toUpperCase().replaceAll("-", "_")}_PREBUILD`;
 }
-function copyNativeBinding(packageName, copyRoot, nodeGypBuild) {
+/** The per-user copy cache. A binary copied to a fresh path costs a first-load
+ *  assessment (macOS checks every never-seen dylib: ~2s per addon, six addons)
+ *  on every process; the same bytes at a path already loaded once cost ~0ms. So
+ *  copies are content-addressed and reused across processes instead of made per
+ *  process. The directory is private to the user: an addon dlopen'd from a
+ *  location another account can write would be code execution as this user. */
+function cacheRoot() {
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    let user = String(uid ?? "");
+    if (!user) {
+        try {
+            user = userInfo().username;
+        }
+        catch {
+            user = "user";
+        }
+    }
+    const root = join(tmpdir(), `${CACHE_PREFIX}${user.replace(/[^A-Za-z0-9_.-]/g, "_")}`);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const st = lstatSync(root);
+    if (!st.isDirectory() || st.isSymbolicLink())
+        throw new Error(`tree-sitter copy cache is not a directory: ${root}`);
+    // POSIX: refuse a cache another account owns or can write into. (Windows has
+    // no uid and a per-user TEMP; its ACLs are not mode bits.)
+    if (uid !== null && (st.uid !== uid || (st.mode & 0o022) !== 0)) {
+        throw new Error(`tree-sitter copy cache is not private to this user: ${root}`);
+    }
+    return root;
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function copyNativeBinding(packageName, root, nodeGypBuild) {
     const packageRoot = dirname(runtimeRequire.resolve(`${packageName}/package.json`));
     const source = nodeGypBuild.path(packageRoot);
-    const packageCopy = join(copyRoot, packageName);
+    const bytes = readFileSync(source);
+    const digest = sha256(bytes);
+    const hashDir = join(root, digest.slice(0, 32));
+    const packageCopy = join(hashDir, packageName);
     const normalized = source.replaceAll("\\", "/");
     const prebuild = /\/prebuilds\/([^/]+)\/[^/]+$/.exec(normalized);
     const destination = prebuild
         ? join(packageCopy, "prebuilds", prebuild[1], basename(source))
         : join(packageCopy, "build", "Release", basename(source));
-    mkdirSync(dirname(destination), { recursive: true });
-    copyFileSync(source, destination);
+    // Reuse only bytes that still hash to the installed binary: a truncated or
+    // replaced copy is rewritten, never loaded.
+    const intact = () => {
+        try {
+            return sha256(readFileSync(destination)) === digest;
+        }
+        catch {
+            return false;
+        }
+    };
+    // Mark the hash dir in use BEFORE verifying it, so a concurrent prune
+    // cannot remove it between the check and the dlopen.
+    try {
+        const now = new Date();
+        utimesSync(hashDir, now, now);
+    }
+    catch { /* not created yet */ }
+    if (!intact()) {
+        mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+        // Atomic: a concurrent process sees the old file or the complete new one.
+        const partial = `${destination}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            copyFileSync(source, partial);
+            renameSync(partial, destination);
+        }
+        catch (error) {
+            try {
+                rmSync(partial, { force: true });
+            }
+            catch { /* best effort */ }
+            // Windows refuses to replace a copy another process has loaded; that copy
+            // is then the same bytes, which is all this needs.
+            if (!intact())
+                throw error;
+        }
+        if (!intact())
+            throw new Error(`tree-sitter copy does not match its source: ${destination}`);
+    }
     return packageCopy;
 }
+/** Hash dirs unused for CACHE_TTL_MS belong to replaced installs. Deleting one
+ *  that is still loaded fails on Windows (retried by a later process) and is
+ *  harmless on POSIX (the mapping outlives the directory entry). */
+function pruneCache(root, keep) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const cutoff = Date.now() - CACHE_TTL_MS;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || keep.has(entry.name))
+            continue;
+        const dir = join(root, entry.name);
+        try {
+            if (statSync(dir).mtimeMs < cutoff)
+                rmSync(dir, { recursive: true, force: true, maxRetries: 2 });
+        }
+        catch { /* in use or already gone */ }
+    }
+}
 /** Load all native tree-sitter addons (the parser runtime + every grammar) from
- * process-owned temp copies. Windows keeps loaded `.node` files locked for the
+ * content-addressed copies in a per-user temp cache — never from the installed
+ * package. Windows keeps loaded `.node` files locked for the
  * process lifetime; redirecting the upstream loaders means npm can replace the
  * installed package during an active MCP session without killing that session
  * or falling back to a stale binary. */
@@ -126,25 +227,33 @@ function loadRuntime() {
     // already-loaded source-built addon slip past this guard and defeat the
     // file-lock isolation entirely (issue #52).
     const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /(?:tree-sitter(?:-typescript|-python|-go|-php|-yaml)?|tree_sitter(?:_[a-z]+)*_binding)\.node$/.test(path)
-        && !new RegExp(`(?:^|[\\\\/])${COPY_PREFIX}\\d+-`).test(path));
+        && !new RegExp(`(?:^|[\\\\/])(?:${COPY_PREFIX}\\d+-|${CACHE_PREFIX})`).test(path));
     if (preloaded.length) {
         throw new Error(`tree-sitter native addon was loaded before Hunch could isolate it: ${preloaded.join(", ")}`);
     }
     removeStaleCopies();
-    const copyRoot = mkdtempSync(join(tmpdir(), `${COPY_PREFIX}${process.pid}-`));
+    // A refused cache (another account's or a group-writable dir squatting the
+    // predictable name) must not kill parsing: fall back to a private
+    // per-process copy dir, which removeStaleCopies prunes once the pid is gone.
+    let root;
+    let shared = true;
+    try {
+        root = cacheRoot();
+    }
+    catch {
+        root = mkdtempSync(join(tmpdir(), `${COPY_PREFIX}${process.pid}-`));
+        shared = false;
+    }
     const previous = new Map();
+    const used = new Set();
     try {
-        // Resolved INSIDE the try: if node-gyp-build cannot be resolved (a partial
-        // install, npm mid-swap) the catch below still removes the copy dir we just
-        // created. Outside it, every retry — and failure is deliberately not
-        // memoized, so a long-lived MCP server retries forever — leaked one empty
-        // hunch-tree-sitter-<pid>-* dir that removeStaleCopies can never prune,
-        // because it only prunes dirs whose pid is dead.
         const nodeGypBuild = runtimeRequire("node-gyp-build");
         for (const packageName of NATIVE_PACKAGES) {
             const key = environmentKey(packageName);
             previous.set(key, process.env[key]);
-            process.env[key] = copyNativeBinding(packageName, copyRoot, nodeGypBuild);
+            const packageCopy = copyNativeBinding(packageName, root, nodeGypBuild);
+            used.add(relative(root, packageCopy).split(sep)[0]);
+            process.env[key] = packageCopy;
         }
         const Parser = runtimeRequire("tree-sitter");
         const languages = runtimeRequire("tree-sitter-typescript");
@@ -154,13 +263,6 @@ function loadRuntime() {
         const yaml = runtimeRequire("@tree-sitter-grammars/tree-sitter-yaml");
         runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python, go, php: php.php, yaml };
     }
-    catch (error) {
-        try {
-            rmSync(copyRoot, { recursive: true, force: true });
-        }
-        catch { /* best effort */ }
-        throw error;
-    }
     finally {
         for (const [key, value] of previous) {
             if (value === undefined)
@@ -169,12 +271,8 @@ function loadRuntime() {
                 process.env[key] = value;
         }
     }
-    process.once("exit", () => {
-        try {
-            rmSync(copyRoot, { recursive: true, force: true });
-        }
-        catch { /* next process prunes it */ }
-    });
+    if (shared)
+        pruneCache(root, used);
     return runtime;
 }
 //# sourceMappingURL=nativeTreeSitter.js.map

package/dist/integrations/claudemd.d.ts

@@ -1,4 +1,18 @@
 import type { HunchStore } from "../store/hunchStore.js";
+import { groundingTemplate } from "../core/groundingLag.js";
+/** Version of the block's PROSE. Bump it whenever renderHunchSection's wording
+ *  changes. A block without the stamp is template 1. */
+export declare const GROUNDING_TEMPLATE = 2;
+export { groundingTemplate };
+/** Never downgrade a block's prose (fnd_f6875f475b). The post-commit capture runs
+ *  the PINNED hunch, which can be older than the renderer that wrote the committed
+ *  block (a branch that develops the renderer, or a repo whose pin lags its docs).
+ *  When the existing block carries a newer template than `section`, keep its prose
+ *  and move only the record counts, so the counts stay true without reverting text
+ *  this version did not author. The preserved block keeps its wiki line and those
+ *  Top-invariants lines whose constraint this version still renders.
+ *  Returns the section to write. */
+export declare function preserveNewerTemplate(existing: string, section: string): string;
 /** Remove the managed HUNCH section (markers inclusive), leaving only the
  *  user-authored surroundings. Lets a caller decide whether two versions of a
  *  doc differ ONLY in generated content (the stranded-grounding heal,
@@ -8,6 +22,10 @@ export declare function renderHunchSection(store: HunchStore, root?: string): st
 /** Insert/replace the marker-delimited HUNCH section in a markdown doc, preserving
  *  all user-authored content outside the markers. Shared by CLAUDE.md, AGENTS.md,
  *  and .github/copilot-instructions.md so every assistant gets the same grounding. */
-export declare function upsertSection(file: string, section: string, fallbackTitle: string): string;
+export declare function upsertSection(file: string, section: string, fallbackTitle: string, opts?: {
+    force?: boolean;
+}): string;
 /** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
-export declare function updateClaudeMd(root: string, store: HunchStore): string;
+export declare function updateClaudeMd(root: string, store: HunchStore, opts?: {
+    force?: boolean;
+}): string;

package/dist/integrations/claudemd.js

@@ -8,9 +8,56 @@ import { writeFileAtomic } from "../core/io.js";
 import { basename, join, dirname } from "node:path";
 import { wikiSummary } from "../wiki/wiki.js";
 import { PolicyRepository } from "../constitution/repository.js";
-import { renderCountsMatch } from "../core/groundingLag.js";
+import { renderCountsMatch, parseGroundingCounts, groundingTemplate } from "../core/groundingLag.js";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
 const END = "<!-- HUNCH:END -->";
+/** Version of the block's PROSE. Bump it whenever renderHunchSection's wording
+ *  changes. A block without the stamp is template 1. */
+export const GROUNDING_TEMPLATE = 2;
+/** The pre-edit hook injects each in-scope invariant in full; the always-loaded
+ *  list only has to name it (fnd_a65f71f38f, #369). Blocking statements are never
+ *  clipped; others are cut at a word boundary within this many chars. */
+const INVARIANT_CHARS = 200;
+export { groundingTemplate };
+/** Never downgrade a block's prose (fnd_f6875f475b). The post-commit capture runs
+ *  the PINNED hunch, which can be older than the renderer that wrote the committed
+ *  block (a branch that develops the renderer, or a repo whose pin lags its docs).
+ *  When the existing block carries a newer template than `section`, keep its prose
+ *  and move only the record counts, so the counts stay true without reverting text
+ *  this version did not author. The preserved block keeps its wiki line and those
+ *  Top-invariants lines whose constraint this version still renders.
+ *  Returns the section to write. */
+export function preserveNewerTemplate(existing, section) {
+    const iStart = existing.indexOf(START);
+    const iEnd = existing.indexOf(END);
+    if (iStart < 0 || iEnd <= iStart)
+        return section;
+    const current = existing.slice(iStart, iEnd + END.length);
+    if (groundingTemplate(current) <= groundingTemplate(section))
+        return section;
+    // Never republish an invariant this version no longer renders: a constraint that
+    // was retired, deleted, or moved to the private overlay drops out of the kept list.
+    const rendered = new Set(section.split(/\r?\n/).map((line) => INVARIANT_LINE_RE.exec(line)?.[1]).filter(Boolean));
+    const eol = current.includes("\r\n") ? "\r\n" : "\n";
+    const lines = current.split(/\r?\n/).filter((line) => {
+        const id = INVARIANT_LINE_RE.exec(line)?.[1];
+        return !id || rendered.has(id);
+    });
+    // A heading left with no invariants under it goes too.
+    const h = lines.findIndex((line) => line.startsWith(INVARIANTS_HEADING));
+    if (h >= 0 && !lines.slice(h + 1).some((line) => INVARIANT_LINE_RE.test(line))) {
+        lines.splice(lines[h - 1] === "" ? h - 1 : h, lines[h - 1] === "" ? 2 : 1);
+    }
+    const kept = lines.join(eol);
+    const have = parseGroundingCounts(kept);
+    const next = parseGroundingCounts(section);
+    // Unreadable counts leave the counts sentence as written rather than downgrading
+    // the block (two versions would flip-flop); `hunch grounding` reports countsReadable: false.
+    return have && next ? kept.replace(have.match, next.match) : kept;
+}
+const INVARIANTS_HEADING = "### ⛔ Top invariants";
+/** A Top-invariants line; group 1 is its constraint id. */
+const INVARIANT_LINE_RE = /^- \*\*\[[a-z]+\]\*\* .*; (con_[A-Za-z0-9_]+)\)_\r?$/;
 /** Remove the managed HUNCH section (markers inclusive), leaving only the
  *  user-authored surroundings. Lets a caller decide whether two versions of a
  *  doc differ ONLY in generated content (the stranded-grounding heal,
@@ -36,58 +83,27 @@ export function renderHunchSection(store, root) {
         policies: root ? new PolicyRepository(root, store).listPolicies({ publicOnly: true }).length : 0,
         findings: store.json.loadAll("findings").filter((f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled").length,
     };
+    // Name the policy tools only where the MCP server registers them by default
+    // (src/mcp/toolset.ts: on once the repo holds a policy). Only committed evidence counts:
+    // env and the gitignored .hunch/config.json would make the committed block differ by
+    // machine. No root (a bare render) keeps the full list.
+    const policyTools = !root || counts.policies > 0;
     const lines = [];
     lines.push(START);
+    lines.push(`<!-- hunch:template ${GROUNDING_TEMPLATE} -->`);
     lines.push("## 🧠 Hunch (Engineering Memory)");
     lines.push("");
-    lines.push("This repo has **Hunch** — a curated graph of *why* the code is the way it is " +
-        "(decisions, bug history, invariants). It currently holds " +
-        `${renderCountsMatch(counts)}.`);
-    lines.push("");
-    lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
-    lines.push("");
-    lines.push("**Orient (session/task start):**");
-    lines.push("- If the host's prompt hook already opened the task and printed a task ID plus a `task verify` command, reuse that exact ID and command — do NOT call `hunch_task(action: \"start\")` for it. Otherwise start the task yourself: call `hunch_task(action: \"start\", title: <short task title>)` once and take `verification_argv` from its result. Each new prompt has its own ID; reuse the ID for follow-up work on the same task and never borrow another task's ID. This is task bookkeeping; `hunch_context` remains the first memory lookup. If reporting fails, continue the work and disclose the gap.");
-    lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
-    lines.push("- `hunch_context(target, task_id)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST** for memory. Include the current task ID on each context call so its contribution is inspectable.");
-    lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
-    lines.push("- `hunch_workspaces(view?)` — which worktrees and branches are open on which machine, what is merged and deletable (read-only; this machine live, others from memory). Call it instead of `git branch` / `git worktree list`; never delete on its say-so.");
-    lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");
-    lines.push("- `hunch_escalations()` — the decisions only the HUMAN can make (including one exact imported ADR at a time, topic conflicts, and policy calls). Normally empty; when it isn't, ASK the user inline — an entry is a question, silence is never approval. Apply an ADR answer only through `hunch_review_imported_adr` with its printed source and review hashes.");
-    lines.push("- `hunch now` (CLI) — recent decisions + the live roadmap; `hunch log` — the memory-move timeline (every capture/adopt/supersede/prune/repair, each revertable).");
-    lines.push("");
-    lines.push("**Before designing / choosing an approach:**");
-    lines.push("- `hunch_why(target)` — why a file/symbol is shaped this way (decisions, bugs, constraints) — including what was already REJECTED.");
-    lines.push("- `hunch_current_decision(topic)` — the one live answer for a topic (history + rejected included).");
-    lines.push("- `hunch_bug_lineage(symptom_or_symbol)` — has this failed before? what was the root cause?");
-    lines.push("- `hunch_compare(candidates)` — rank candidate branches/commits by fewest invariant hits.");
-    lines.push("- `hunch_query(query)` — free-text search when nothing above fits.");
+    lines.push("This repo has **Hunch**, a graph of *why* the code is the way it is. It holds " +
+        `${renderCountsMatch(counts)}. Use the \`hunch_*\` MCP tools by moment:`);
     lines.push("");
-    lines.push("**Before editing:**");
-    lines.push("- `hunch_check_constraints(scope)` and `hunch_get_dependents(symbol)` / `hunch_blast_radius(target)` — invariants in scope + who you'd break. (The pre-edit hook injects this per file automatically; call these for PLANNING breadth.)");
-    lines.push("- `hunch_findings(scope?)` — known-but-unfixed gaps in the area (past audits, measurements, incidents) so you inherit them instead of re-discovering them.");
-    lines.push("");
-    lines.push("**Before committing / merging:**");
-    lines.push("- `hunch_conformance()` — does the code still SATISFY recorded intent? Run before and after a refactor.");
-    lines.push("- `hunch_policy_evaluate(policy_id?, active_only?)` / `hunch_policy_plan(policy_id)` / `hunch_policy_card(policy_id)` / `hunch_policy_proof(policy_id)` — evaluate canonical policy, inspect the planned corpus, review the evidence/uncertainty card, and inspect raw replay receipts; only an explicit human activation grants authority.");
-    lines.push("- `hunch_pr_impact(base?)` / `hunch_merge_verdict(...)` — a change's memory surface; would it re-open a closed bug?");
-    lines.push("");
-    lines.push("**Before the final response — make Hunch's contribution visible:**");
-    lines.push("- When running a relevant check, use the exact launcher the prompt hook printed — or, on a host without one, the `verification_argv` returned by hunch_task start — followed by the check command and its arguments, from this worktree. It runs `hunch task verify <task_id> -- <command> [arguments]` using the same installation as MCP, avoiding stale global binaries. This retains the actual exit result and source snapshot; raw output is not stored. Do not rerun an expensive check solely for reporting; missing evidence stays unverified.");
-    lines.push("- Include the current task_id when calling hunch_record_decision, hunch_record_correction, or hunch_record_finding. The save path records its actual memory home and verifies exact Git revisions when committing or pushing; never infer publication from a successful capture alone.");
-    lines.push("- Before claiming an application, call `hunch_report(task_id)` and copy the exact occurrence_id, record_id and content_hash from application_references, adding an action you actually took. Never derive an occurrence ID by replacing a receipt prefix or use the task's scope hash as a record hash. If you did not apply a lesson, omit applications.");
-    lines.push("- When this task actually used Hunch (a `hunch_*` call carrying the task_id, a verified check, Hunch hook context you acted on, or an application to claim), call `hunch_task(action: \"finish\", task_id, applications?)` and include the returned contribution_card in your final response without the user asking. Skip the finish call only when it used none of those AND the host's own stop hook closes the task and shows the evidence for you (its prompt-hook instruction says so); where no host hook closes the task, and for a task you started yourself with `hunch_task(action: \"start\")`, always finish it yourself. Copy the card verbatim, including its Evidence line (the command that renders the local report on demand) and the agent-reported label; the structured result contains the card even when the host hides text blocks. Do not replace it with a generic claim that Hunch helped. If presentation_enabled is false, omit the card. A delivered lesson or passing command alone does not prove causal impact.");
-    lines.push("- If interrupted, finish with `outcome: \"interrupted\"` when possible. `hunch_report(task_id, html: true)` opens the evidence trail by generating a local file; it may contain private memory and is not a public export. If report tools are unavailable after an update, say so and reconnect the host rather than inventing a report.");
-    lines.push("");
-    lines.push("**Build the Constitution review queue:**");
-    lines.push("- `hunch constitution bootstrap --since 90d --max-candidates 3` (CLI) — normalize recent structured human evidence into at most three non-active policy candidates; add `--history` for exact, human-identifier-grounded fix/revert deltas or explicit dependency retirements. Coincidence/ambiguity stays uncompilable; neither path grants authority.");
-    lines.push("- `hunch constitution ingest --since 90d [--instructions] [--from export.json]` (CLI) — normalize corrections/failures plus bounded committed instructions/ADRs and strict local review/conversation/PR exports into Git-native evidence; raw prose is hash-only, unsupported intent remains uncompilable, and no policy is minted.");
-    lines.push("");
-    lines.push("**After deciding / when corrected:**");
-    lines.push("- `hunch_capture_decision(topic?)` → `hunch_record_decision(...)` — interview first, then write; status `proposed` = roadmap intent (shows in `hunch now`).");
-    lines.push("- `hunch_record_correction(...)` — a human correction becomes an ENFORCED rule (Never Twice), not a one-session memory.");
-    lines.push("- `hunch_record_finding(...)` — an OBSERVATION with no code change (an audit that found a gap, a measured number, an incident) becomes durable memory anchored to a date + evidence; `/audit` runs the ritual.");
-    lines.push("- `hunch_timeline(target)` — decision history when investigating how something evolved.");
+    lines.push("- **Start:** reuse the task ID and `task verify` command the prompt hook printed; with none, call `hunch_task(action: \"start\", title)` once. Then `hunch_context(target, task_id)` first. Orient with `hunch_structure`, `hunch_workspaces`, `hunch_runbook(task)`. Ask the user about each `hunch_escalations()` entry; silence is never approval.");
+    lines.push("- **Design:** `hunch_why(target)` (includes what was rejected), `hunch_current_decision(topic)`, `hunch_bug_lineage(symptom_or_symbol)`, `hunch_compare(candidates)`, `hunch_query(query)`.");
+    lines.push("- **Edit:** `hunch_check_constraints(scope)`, `hunch_get_dependents(symbol)` / `hunch_blast_radius(target)`, `hunch_findings(scope?)`.");
+    lines.push("- **Merge:** `hunch_conformance()`, `hunch_pr_impact(base?)`, `hunch_merge_verdict`." +
+        (policyTools ? " Policy review: `hunch_policy_evaluate`, `hunch_policy_plan(policy_id)`, `hunch_policy_card(policy_id)`, `hunch_policy_proof`; only a human activates a policy." : ""));
+    lines.push("- **Record:** `hunch_capture_decision` → `hunch_record_decision`; `hunch_record_correction` turns a human correction into an enforced rule; `hunch_record_finding` keeps an observation with evidence. Pass the task_id.");
+    lines.push("- **Finish:** run checks through the `task verify` launcher. If the task used Hunch, you started it, or no host stop hook closes it, call `hunch_task(action: \"finish\", task_id)` and show its card verbatim. Its `applications` schema carries the claim rules.");
+    lines.push("- To update Hunch, run `hunch update` from the repo root.");
     const wiki = root ? wikiSummary(root) : null;
     if (wiki) {
         lines.push("");
@@ -97,19 +113,21 @@ export function renderHunchSection(store, root) {
         lines.push("");
         lines.push("### ⛔ Top invariants (do not break)");
         for (const c of constraints) {
-            lines.push(`- **[${c.severity}]** ${c.statement} _(scope: ${c.scope.join(", ") || "repo"}; ${c.id})_`);
+            lines.push(`- **[${c.severity}]** ${c.severity === "blocking" ? c.statement : clip(c.statement, INVARIANT_CHARS)} _(scope: ${c.scope.join(", ") || "repo"}; ${c.id})_`);
         }
     }
     lines.push("");
-    lines.push("_Hunch updates itself from commits and test failures. Records carry provenance + confidence; treat low-confidence items as advisory._");
+    lines.push("_Records carry provenance and confidence; treat low-confidence items as advisory._");
     lines.push(END);
     return lines.join("\n");
 }
 /** Insert/replace the marker-delimited HUNCH section in a markdown doc, preserving
  *  all user-authored content outside the markers. Shared by CLAUDE.md, AGENTS.md,
  *  and .github/copilot-instructions.md so every assistant gets the same grounding. */
-export function upsertSection(file, section, fallbackTitle) {
+export function upsertSection(file, section, fallbackTitle, opts) {
     let content = existsSync(file) ? readFileSync(file, "utf8") : "";
+    if (!opts?.force)
+        section = preserveNewerTemplate(content, section);
     const iStart = content.indexOf(START);
     const iEnd = content.indexOf(END);
     if (iStart >= 0 && iEnd > iStart) {
@@ -133,8 +151,16 @@ export function upsertSection(file, section, fallbackTitle) {
     return file;
 }
 /** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
-export function updateClaudeMd(root, store) {
-    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store, root), `# ${basename(root)}`);
+export function updateClaudeMd(root, store, opts) {
+    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store, root), `# ${basename(root)}`, opts);
+}
+/** Cut at the last whitespace at or before `max - 1` chars, so a word is never split. */
+function clip(text, max) {
+    if (text.length <= max)
+        return text;
+    const head = text.slice(0, max);
+    const cut = head.search(/\s\S*$/);
+    return `${(cut > 0 ? text.slice(0, cut) : text.slice(0, max - 1)).trimEnd()}…`;
 }
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;

package/dist/integrations/providers.d.ts

@@ -26,12 +26,16 @@ export declare function writeAntigravityWorkspaceMcp(root: string, inv: Invocati
 export declare function writeCodexConfig(root: string, inv: Invocation): string;
 /** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
  *  set of assistants read it). Marker-delimited so user prose is preserved. */
-export declare function writeAgentsMd(root: string, store: HunchStore): string;
+export declare function writeAgentsMd(root: string, store: HunchStore, opts?: GroundingWriteOptions): string;
 /** GitHub Copilot custom instructions (VS Code / github.com). Same grounding. */
-export declare function writeCopilotInstructions(root: string, store: HunchStore): string;
+export declare function writeCopilotInstructions(root: string, store: HunchStore, opts?: GroundingWriteOptions): string;
+/** `force` re-renders even a block written by a newer Hunch template. */
+export interface GroundingWriteOptions {
+    force?: boolean;
+}
 /** Cursor project rule (.mdc = frontmatter + body). `alwaysApply` keeps the Hunch
  *  grounding in context for every request. Fully managed by Hunch (overwritten). */
-export declare function writeCursorRule(root: string, store: HunchStore): string;
+export declare function writeCursorRule(root: string, store: HunchStore, opts?: GroundingWriteOptions): string;
 /** Windsurf (Cascade): .windsurf/mcp_config.json — same `mcpServers` shape as
  *  Cursor. Repo-local (committed, shared via git) to match Hunch's other configs,
  *  rather than the global ~/.codeium/windsurf path. Merges; refuses to clobber. */
@@ -43,7 +47,7 @@ export declare function windsurfMcpFile(home?: string): string | null;
 export declare function writeWindsurfGlobalMcp(inv: Invocation, home?: string): string | null;
 /** Windsurf project rule (.windsurf/rules/hunch.md). `trigger: always_on` keeps the
  *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
-export declare function writeWindsurfRule(root: string, store: HunchStore): string;
+export declare function writeWindsurfRule(root: string, store: HunchStore, opts?: GroundingWriteOptions): string;
 /** Cursor's hook API is beta, but its project-level config accepts this standard
  * event map. Context delivery is opportunistic; the always-on rule and MCP
  * registration remain the durable grounding path if a Cursor build suppresses
@@ -82,7 +86,7 @@ export declare const GROUNDING_DOC_PATHS: readonly string[];
  *  assistant). Run by `hunch index` and non-hook `hunch sync` so a project silently
  *  picks up generator fixes (e.g. corrected MCP tool param names) and fresh record
  *  counts on the next refresh — no manual `hunch init`. */
-export declare function refreshExistingGrounding(root: string, store: HunchStore): string[];
+export declare function refreshExistingGrounding(root: string, store: HunchStore, opts?: GroundingWriteOptions): string[];
 /** Capture-commit refresh: rewrite grounding docs that are git-clean OR whose only
  *  divergence from HEAD is generated content, and return the absolute paths to fold
  *  into the memory commit (commitAndPushHunch alsoStage). This keeps committed record

package/dist/integrations/providers.js

@@ -22,7 +22,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { isHunchHookCommand } from "./hookmatch.js";
-import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd } from "./claudemd.js";
+import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd, preserveNewerTemplate } from "./claudemd.js";
 import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 import { parseJsonc } from "../core/jsonc.js";
 import { parse as parseToml } from "smol-toml";
@@ -271,18 +271,26 @@ export function writeCodexConfig(root, inv) {
 }
 /** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
  *  set of assistants read it). Marker-delimited so user prose is preserved. */
-export function writeAgentsMd(root, store) {
-    return upsertSection(join(root, "AGENTS.md"), renderHunchSection(store, root), "# AGENTS.md");
+export function writeAgentsMd(root, store, opts) {
+    return upsertSection(join(root, "AGENTS.md"), renderHunchSection(store, root), "# AGENTS.md", opts);
 }
 /** GitHub Copilot custom instructions (VS Code / github.com). Same grounding. */
-export function writeCopilotInstructions(root, store) {
-    return upsertSection(join(root, ".github", "copilot-instructions.md"), renderHunchSection(store, root), "# Copilot instructions");
+export function writeCopilotInstructions(root, store, opts) {
+    return upsertSection(join(root, ".github", "copilot-instructions.md"), renderHunchSection(store, root), "# Copilot instructions", opts);
+}
+/** The block for a wholly-owned rule file, never downgrading newer prose (unless forced). */
+function ownedSection(file, store, root, opts) {
+    const section = renderHunchSection(store, root);
+    if (opts?.force)
+        return section;
+    const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+    return preserveNewerTemplate(existing, section);
 }
 /** Cursor project rule (.mdc = frontmatter + body). `alwaysApply` keeps the Hunch
  *  grounding in context for every request. Fully managed by Hunch (overwritten). */
-export function writeCursorRule(root, store) {
+export function writeCursorRule(root, store, opts) {
     const file = join(root, ".cursor", "rules", "hunch.mdc");
-    const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${renderHunchSection(store, root)}\n`;
+    const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${ownedSection(file, store, root, opts)}\n`;
     mkdirSync(dirname(file), { recursive: true });
     writeFileAtomic(file, body);
     return file;
@@ -315,9 +323,9 @@ export function writeWindsurfGlobalMcp(inv, home = homedir()) {
 }
 /** Windsurf project rule (.windsurf/rules/hunch.md). `trigger: always_on` keeps the
  *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
-export function writeWindsurfRule(root, store) {
+export function writeWindsurfRule(root, store, opts) {
     const file = join(root, ".windsurf", "rules", "hunch.md");
-    const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\n---\n\n${renderHunchSection(store, root)}\n`;
+    const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\n---\n\n${ownedSection(file, store, root, opts)}\n`;
     mkdirSync(dirname(file), { recursive: true });
     writeFileAtomic(file, body);
     return file;
@@ -356,7 +364,8 @@ export function writeCodexHooks(root, inv) {
     return writeHookConfig(file, {
         SessionStart: [entry()],
         UserPromptSubmit: [entry()],
-        PreToolUse: [entry("apply_patch")],
+        // The shell entries take the baseline a shell write is measured from.
+        PreToolUse: [entry("apply_patch|Bash|PowerShell|shell|local_shell")],
         // Codex's native command tool arrives as `Bash` (or `PowerShell` on
         // Windows), while older hosts may expose shell/local_shell names.
         PostToolUse: [entry("apply_patch|Bash|PowerShell|shell|local_shell")],
@@ -435,12 +444,16 @@ export function writeAntigravityHooks(root, inv) {
  *  docs reflect that no engineering memory is published here (renderHunchSection
  *  reads the public store only, so private records never leak into them). */
 export function regenerateGrounding(root, store) {
+    // FORCED: a block from a newer template would otherwise keep its prose — including
+    // its Top-invariants list — so a constraint that just moved to the overlay would stay
+    // printed in the committed public doc.
+    const force = { force: true };
     return [
-        updateClaudeMd(root, store),
-        writeAgentsMd(root, store),
-        writeCopilotInstructions(root, store),
-        writeCursorRule(root, store),
-        writeWindsurfRule(root, store),
+        updateClaudeMd(root, store, force),
+        writeAgentsMd(root, store, force),
+        writeCopilotInstructions(root, store, force),
+        writeCursorRule(root, store, force),
+        writeWindsurfRule(root, store, force),
     ];
 }
 /** The five grounding docs, repo-relative (POSIX separators, as git prints them). */
@@ -451,13 +464,13 @@ export const GROUNDING_DOC_PATHS = Object.freeze([
     ".cursor/rules/hunch.mdc",
     ".windsurf/rules/hunch.md",
 ]);
-function groundingTargets(root, store) {
+function groundingTargets(root, store, opts) {
     return [
-        ["CLAUDE.md", () => updateClaudeMd(root, store)],
-        ["AGENTS.md", () => writeAgentsMd(root, store)],
-        [join(".github", "copilot-instructions.md"), () => writeCopilotInstructions(root, store)],
-        [join(".cursor", "rules", "hunch.mdc"), () => writeCursorRule(root, store)],
-        [join(".windsurf", "rules", "hunch.md"), () => writeWindsurfRule(root, store)],
+        ["CLAUDE.md", () => updateClaudeMd(root, store, opts)],
+        ["AGENTS.md", () => writeAgentsMd(root, store, opts)],
+        [join(".github", "copilot-instructions.md"), () => writeCopilotInstructions(root, store, opts)],
+        [join(".cursor", "rules", "hunch.mdc"), () => writeCursorRule(root, store, opts)],
+        [join(".windsurf", "rules", "hunch.md"), () => writeWindsurfRule(root, store, opts)],
     ];
 }
 /** Self-heal: refresh the Hunch section in each grounding doc that ALREADY exists,
@@ -466,9 +479,9 @@ function groundingTargets(root, store) {
  *  assistant). Run by `hunch index` and non-hook `hunch sync` so a project silently
  *  picks up generator fixes (e.g. corrected MCP tool param names) and fresh record
  *  counts on the next refresh — no manual `hunch init`. */
-export function refreshExistingGrounding(root, store) {
+export function refreshExistingGrounding(root, store, opts) {
     const changed = [];
-    for (const [rel, write] of groundingTargets(root, store)) {
+    for (const [rel, write] of groundingTargets(root, store, opts)) {
         const file = join(root, rel);
         if (!existsSync(file))
             continue; // refresh-only: never scaffold a doc the project doesn't have

package/dist/integrations/scaffold.js

@@ -180,9 +180,10 @@ export function installClaudeHooks(root, hookCmd) {
         }
     }
     const keep = (arr) => (Array.isArray(arr) ? arr.map((entry) => withoutHunchCommands(entry, hookCmd)).filter((e) => e !== null) : []);
+    // Shell tools too: their PreToolUse takes the baseline a shell write is measured from.
     json.hooks.PreToolUse = [
         ...keep(json.hooks.PreToolUse),
-        { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: hookCmd }] },
+        { matcher: "Edit|Write|MultiEdit|Bash|PowerShell", hooks: [{ type: "command", command: hookCmd }] },
     ];
     json.hooks.UserPromptSubmit = [
         ...keep(json.hooks.UserPromptSubmit),