@davesheffer/hunch 1.10.1 → 1.10.2

package/dist/cli/index.js

@@ -3259,26 +3259,29 @@ program
             console.log("   Strict mode fails closed because an omitted source file could hide a semantic violation.");
         }
     }
-    if (!files.length) {
-        console.log(markdown ? renderMarkdown(emptyReport) : "No changed files to check.");
-        if (teamFreshnessFailure)
-            fail(teamFreshnessFailure);
-        if (opts.strict && semanticIssues.length)
-            process.exitCode = 1;
-        store.close();
-        return;
-    }
     // DIRECT (scope match) + NEAR (blast radius) + REGRESSION (re-added retired
     // code) + REDUNDANT (adds a symbol already defined elsewhere — advisory) + the
     // hardened strict gate + causal `why` citations — all assembled by the shared
     // store.buildCheckReport (also used by the hunch_merge_verdict tool).
-    const diff = exactCommit ? commitDiff(exactCommit, root) : opts.base ? rangeDiff(opts.base, root) : opts.working ? workingDiff(root) : stagedDiff(root);
-    const report = store.buildCheckReport(files, diff, {
-        strict: !!opts.strict,
-        lastChange: (f) => lastChangeDate(f, root),
-        publicOnly: !!opts.publicOnly,
-    });
-    if (opts.blast && !markdown) {
+    //
+    // A ZERO-FILE diff must NOT short-circuit the run: the per-file report has nothing
+    // to say, but the GRAPH-WIDE gates below (Architectural Conformance and Constitution
+    // policy) ask "does the code, right now, still satisfy recorded intent?" — a question
+    // independent of what this diff touched. Returning early here made a delete-only PR a
+    // vacuous green (deletions are excluded by the enumerators' --diff-filter=ACMR, so
+    // such a PR enumerates zero files) — including a deletion of the very symbol a
+    // blocking conformance predicate or an active policy guards.
+    const diff = files.length
+        ? (exactCommit ? commitDiff(exactCommit, root) : opts.base ? rangeDiff(opts.base, root) : opts.working ? workingDiff(root) : stagedDiff(root))
+        : "";
+    const report = files.length
+        ? store.buildCheckReport(files, diff, {
+            strict: !!opts.strict,
+            lastChange: (f) => lastChangeDate(f, root),
+            publicOnly: !!opts.publicOnly,
+        })
+        : emptyReport;
+    if (opts.blast && !markdown && files.length) {
         console.log(`Blast radius of ${files.length} changed file(s):`);
         for (const f of files) {
             const b = store.blastRadiusFiles(f);
@@ -3287,7 +3290,9 @@ program
         }
         console.log("");
     }
-    console.log(markdown ? renderMarkdown(report) : renderText(report));
+    console.log(files.length
+        ? (markdown ? renderMarkdown(report) : renderText(report))
+        : (markdown ? renderMarkdown(emptyReport) : "No changed files to check."));
     // ARCHITECTURAL CONFORMANCE: does the RESULTING code still satisfy every recorded
     // architectural invariant? This is graph-reachability, not a diff — so it catches semantic
     // violations a pattern-matcher / SAST can't express (a controller that now reaches the DB
@@ -3741,19 +3746,29 @@ program
             // When the prompt reads like a correction ("no / that's wrong / never X"),
             // nudge the agent to PERSIST it as an enforced constraint (Never Twice) —
             // not just obey it this once and forget it next session.
-            let text = looksLikeCorrection(evt.prompt) ? `${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}` : HOOK_REMINDER;
+            const isCorrection = looksLikeCorrection(evt.prompt);
+            let text = isCorrection ? `${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}` : HOOK_REMINDER;
+            // Payloads that must NEVER be deduped away. The dedup key hashes CONTENT, and
+            // this content is assembled from constants — so two back-to-back corrections
+            // produce byte-identical text and the second (usually the escalating one) was
+            // silently swallowed, never becoming an enforced rule. Same for the unverified
+            // nag, which is documented as the one nag that must repeat but rode the same
+            // deduped payload and so fired once per streak.
+            let mustDeliver = isCorrection;
             // Pipeline turn bookkeeping (fresh block budget) + the one nag that must
             // repeat: edits from an earlier turn still unverified.
             if (evt.session_id && pipelineEnabled()) {
                 const st = onPrompt(loadPipelineState(evt.session_id));
                 savePipelineState(evt.session_id, st);
-                if (!st.verifyAfterEdit)
+                if (!st.verifyAfterEdit) {
                     text += `\n\n${UNVERIFIED_NAG}`;
+                    mustDeliver = true;
+                }
             }
-            // Once per session is enough for the availability reminder — repeating it
-            // every prompt burns context for zero information. A correction nudge has
-            // different content, so it always comes through (dec_244397d920).
-            if (injectionMode(evt.session_id, "prompt-reminder", text) === "delta")
+            // Once per session is enough for the bare availability reminder — repeating it
+            // every prompt burns context for zero information (dec_244397d920). Only that
+            // ambient case is deduped.
+            if (!mustDeliver && injectionMode(evt.session_id, "prompt-reminder", text) === "delta")
                 return;
             emitContext(provider, "UserPromptSubmit", text);
             return;
@@ -4687,6 +4702,7 @@ program
     .option("--no-llm", "skip LLM prose; deterministic template pages only")
     .option("--prose-heal", "also LLM-rewrite each adopted copy's reconciled overview (subscription; the deterministic corrections always remain)")
     .option("--private", "render the FULL graph (private overlay included) and write the wiki into the OVERLAY repo — nothing lands in this repo")
+    .option("--private-prose", "opt in to LLM prose for a PRIVATE-split overlay wiki — this SENDS overlay records (decision text, private constraints, private bug root causes) to the configured provider. Off by default.")
     .action(async (opts) => {
     const { store, root } = storeFor();
     try {
@@ -4752,7 +4768,21 @@ program
             return fail("--prose-heal needs the LLM — drop --no-llm.");
         let prose;
         let adoptionProse;
-        if (opts.llm !== false) {
+        // A PRIVATE-SPLIT overlay's packs carry the full union (source: "all") — overlay
+        // decision context/rationale/rejected alternatives, private constraint statements,
+        // private bug root causes. Sending that to an external subscription CLI would
+        // silently break the storage-private promise every other path here enforces
+        // (public-only CI comments, public-only grounding, public-only wiki manifests), in
+        // the very command documented as the way to build the private wiki. So prose is OFF
+        // by default for that home and needs an explicit --private-prose. A SHARED overlay
+        // is deliberately excluded: there the team already routes captures through the
+        // configured provider by recorded policy.
+        const privateSplit = home.kind === "private" && store.mode === "private";
+        const proseBlockedForPrivacy = privateSplit && !opts.privateProse;
+        if (opts.llm !== false && proseBlockedForPrivacy) {
+            console.log("Private overlay: LLM prose is OFF (pages would send overlay records to the configured provider). Deterministic template pages; pass --private-prose to opt in.");
+        }
+        if (opts.llm !== false && !proseBlockedForPrivacy) {
             const provider = await selectProvider({ root });
             if (provider.draftProse) {
                 console.log(`Prose via ${provider.name}; the drift-bearing skeleton stays deterministic.`);

package/dist/core/conformance.js

@@ -1,3 +1,4 @@
+import { externalImportNodeId } from "./externalImports.js";
 function resolveSymbols(graph, ref) {
     const syms = graph.symbols;
     if (ref.startsWith("sym_"))
@@ -48,17 +49,30 @@ function evalPredicate(graph, d, p) {
         return { ...base, satisfied: false, detail: `subject "${p.subject}" not found in the graph — intent's subject is gone` };
     const wantReach = p.assert === "calls" || p.assert === "imports";
     const objects = p.object ? resolveSymbols(graph, p.object) : [];
-    if (!objects.length) {
-        // a required target gone ⇒ the link can't hold (violated); a forbidden one trivially holds.
+    // An external package is a VIRTUAL graph node (`ext_<hash>`, see core/externalImports.ts),
+    // never a Symbol record — so resolveSymbols can NEVER find one. Without this, every
+    // `not-imports <symbol> <package>` predicate fell straight into the "target not found ⇒
+    // a forbidden relation trivially holds" branch below and reported ✅ forever, while the
+    // graph right beside it recorded the violating `imports` edge. Resolve the package from
+    // the edge set instead, which is where the indexer actually puts it.
+    const externalId = p.object ? externalImportNodeId(p.object) : null;
+    const objectIds = objects.length
+        ? objects.map((o) => o.id)
+        : externalId && graph.edges.some((e) => e.to === externalId)
+            ? [externalId]
+            : [];
+    if (!objectIds.length) {
+        // a required target gone ⇒ the link can't hold (violated); a forbidden one trivially
+        // holds — nothing can reach a node the graph does not contain.
         return { ...base, satisfied: !wantReach, detail: `target "${p.object ?? ""}" not found in the graph` };
     }
     // A required relation cannot guess which same-name symbol carries the intent.
     // Force qualification instead of accidentally proving a different binding.
-    if (wantReach && (subjects.length !== 1 || objects.length !== 1)) {
+    if (wantReach && (subjects.length !== 1 || objectIds.length !== 1)) {
         return {
             ...base,
             satisfied: false,
-            detail: `ambiguous required binding (${subjects.length} subject, ${objects.length} target matches) — qualify as file:symbol; intent VIOLATED`,
+            detail: `ambiguous required binding (${subjects.length} subject, ${objectIds.length} target matches) — qualify as file:symbol; intent VIOLATED`,
         };
     }
     // A forbidden relation is conservative in the other direction: ANY matching
@@ -66,7 +80,7 @@ function evalPredicate(graph, d, p) {
     // only the first target lets a duplicate symbol hide a violation.
     const linked = subjects.some((subject) => {
         const reached = reaches(graph, subject.id, p.transitive);
-        return objects.some((object) => reached.has(object.id));
+        return objectIds.some((id) => reached.has(id));
     });
     const satisfied = wantReach ? linked : !linked;
     const via = p.transitive ? " (transitively)" : "";

package/dist/core/constraintmatch.js

@@ -25,9 +25,17 @@ export function matchForbids(f, addedDeps, scopedAdded) {
     // tripping an in-scope edit.
     const hitDeps = [];
     for (const dep of f.deps) {
-        const added = [...addedDeps].find((d) => d === dep || d.startsWith(`${dep}/`));
-        if (added && codeLines.some((l) => importsDep(l, added)))
-            hitDeps.push(added);
+        // EVERY added specifier that satisfies the forbid, not just the first: one commit
+        // can add `lodash` in an out-of-scope file and `lodash/groupBy` in the scoped one.
+        // Taking only `.find`'s first match meant the out-of-scope spelling shadowed the
+        // real in-scope violation and the blocking rule failed OPEN — with the outcome
+        // depending on diff order, i.e. on an unrelated file's name.
+        for (const added of addedDeps) {
+            if (added !== dep && !added.startsWith(`${dep}/`))
+                continue;
+            if (codeLines.some((l) => importsDep(l, added)))
+                hitDeps.push(added);
+        }
     }
     if (hitDeps.length)
         return { tier: "dep", evidence: hitDeps.map((d) => `+import ${d}`) };

package/dist/core/docscan.js

@@ -89,6 +89,16 @@ export function scanRepoDocs(decisions, root) {
             else if (superseded && current && current.id !== a.pin) {
                 issues.push(`line ${a.line}: pinned to superseded ${a.pin}; current for "${a.topic}" is ${current.id}`);
             }
+            else if (pinned.status === "rejected") {
+                // The ledger tells readers to "Trust ✅". A doc pinned to an approach the team
+                // explicitly REJECTED is the opposite of grounded — and the pre-edit hook, which
+                // only injects live decisions, already disagrees with the ✅ this used to award.
+                issues.push(`line ${a.line}: pinned to ${a.pin}, a REJECTED decision (topic "${a.topic}")${current ? `; current is ${current.id}` : ""}`);
+            }
+            else if (pinned.status === "proposed") {
+                // Roadmap intent, not an in-force answer: it neither grounds the doc nor makes
+                // it stale, so the doc falls to the honest "unverified" tier.
+            }
             else if (!superseded) {
                 groundedPins++;
             }

package/dist/extractors/diff.js

@@ -131,18 +131,26 @@ export function analyzeDiff(diff) {
         }
         // ---- inside a hunk: content lines ----
         if (raw.startsWith("+")) {
-            if (!isCode(curFile))
-                continue;
-            addedLines++;
-            if (!curAdded && !curDeleted)
-                filesModified.add(curFile);
             const body = raw.slice(1);
+            // Raw added lines are captured for EVERY file, before the code-only gate:
+            // content-matched constraints and Veto tripwires are not code-only rules
+            // (a blocking invariant legitimately scopes .github/workflows/**, *.sql,
+            // Dockerfile). Skipping them here left `scopedAdded` empty, which
+            // buildCheckReport reads as "cannot prove a violation ⇒ complies" — so the
+            // pre-edit hook denied the edit while `hunch check --strict` passed the
+            // very commit that landed it. Symbol/import extraction and the churn
+            // counters below stay code-only, unchanged.
             let lines = addedLinesBy.get(curFile);
             if (!lines) {
                 lines = [];
                 addedLinesBy.set(curFile, lines);
             }
             lines.push(body);
+            if (!isCode(curFile))
+                continue;
+            addedLines++;
+            if (!curAdded && !curDeleted)
+                filesModified.add(curFile);
             const d = declOf(body);
             if (d)
                 declsFor(curFile)?.added.set(d.name, d);

package/dist/extractors/git.js

@@ -711,6 +711,22 @@ export function isGitCleanPath(root, rel) {
         return false;
     }
 }
+/** The committed (HEAD) content of a tracked file, or null when the path is
+ *  untracked/absent at HEAD or git is unavailable. Used to decide whether a
+ *  dirty grounding doc differs from HEAD ONLY inside its generated section
+ *  (the stranded-grounding heal, fnd_b269d5c422). */
+export function headFileContent(root, rel) {
+    try {
+        return execFileSync("git", ["-C", root, "show", `HEAD:${rel.replace(/\\/g, "/")}`], {
+            encoding: "utf8",
+            env: foreignRepoEnv(process.env),
+            maxBuffer: 16 * 1024 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+}
 /** Is the staged set a clean, MEMORY-ONLY change — only JSON record adds/updates, nothing else?
  *  The overlay store is entirely JSON (decisions/, bugs/, …, manifest.json). A real memory sync
  *  is purely additive; a DELETION, rename, or any non-.json staged path means hunchDir is NOT a

package/dist/extractors/languages.js

@@ -6,19 +6,25 @@
  * four files.
  */
 import { loadNativeTreeSitter } from "./nativeTreeSitter.js";
-const TS_QUERY = `
-  (function_declaration name: (identifier) @fn.name) @fn.def
-  (generator_function_declaration name: (identifier) @fn.name) @fn.def
-  (method_definition name: (property_identifier) @method.name) @method.def
-  (class_declaration name: (type_identifier) @class.name) @class.def
-  (interface_declaration name: (type_identifier) @iface.name) @iface.def
-  (type_alias_declaration name: (type_identifier) @type.name) @type.def
-  (variable_declarator
-     name: (identifier) @arrow.name
-     value: [(arrow_function) (function_expression)]) @arrow.def
-  (import_statement source: (string) @import.src)
-  (call_expression function: (identifier) @call.id)
-  (call_expression function: (member_expression property: (property_identifier) @call.member))
+const TS_QUERY = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (generator_function_declaration name: (identifier) @fn.name) @fn.def
+  (method_definition name: (property_identifier) @method.name) @method.def
+  (class_declaration name: (type_identifier) @class.name) @class.def
+  (interface_declaration name: (type_identifier) @iface.name) @iface.def
+  (type_alias_declaration name: (type_identifier) @type.name) @type.def
+  (variable_declarator
+     name: (identifier) @arrow.name
+     value: [(arrow_function) (function_expression)]) @arrow.def
+  (import_statement source: (string) @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (member_expression property: (property_identifier) @call.member))
+  ;; Construction IS a call. Without these, \`new Foo()\` produced no edge at all, so
+  ;; every class in a TS/JS repo had fan_in 0: blast radius before a constructor
+  ;; change came back empty, and a \`not-calls\` conformance predicate over a class
+  ;; could never see its own counterexample.
+  (new_expression constructor: (identifier) @call.id)
+  (new_expression constructor: (member_expression property: (property_identifier) @call.member))
 `;
 const TS_BUILTIN_METHODS = new Set([
     "map", "filter", "forEach", "reduce", "find", "findIndex", "some", "every", "includes",
@@ -65,21 +71,28 @@ const TSX = {
     grammarKey: "tsx",
     loadGrammar: () => loadNativeTreeSitter().tsx,
 };
-const PY_QUERY = `
-  (class_definition
-    name: (identifier) @class.name
-    body: (block
-      [
-        (function_definition name: (identifier) @method.name) @method.def
-        (decorated_definition definition: (function_definition name: (identifier) @method.name) @method.def)
-      ])) @class.def
-  (function_definition name: (identifier) @fn.name) @fn.def
-  (import_statement name: (dotted_name) @import.src)
-  (import_statement name: (aliased_import name: (dotted_name) @import.src))
-  (import_from_statement module_name: (dotted_name) @import.src)
-  (import_from_statement module_name: (relative_import) @import.src)
-  (call function: (identifier) @call.id)
-  (call function: (attribute attribute: (identifier) @call.member))
+const PY_QUERY = `
+  (class_definition
+    name: (identifier) @class.name
+    body: (block
+      [
+        (function_definition name: (identifier) @method.name) @method.def
+        (decorated_definition definition: (function_definition name: (identifier) @method.name) @method.def)
+      ])) @class.def
+  ;; Every class, including one with no directly-nested def: dataclasses, Exception
+  ;; subclasses, Enums, TypedDicts and pydantic models are method-less by design and
+  ;; were invisible to the entire graph (no symbol, no component, no edges), so
+  ;; \`hunch why\` and blast radius came back empty for exactly the classes a refactor
+  ;; breaks. parse.ts keys pendingDefs by node id and keeps the first classification,
+  ;; so a class that ALSO matches the method-bearing pattern above is not duplicated.
+  (class_definition name: (identifier) @class.name) @class.def
+  (function_definition name: (identifier) @fn.name) @fn.def
+  (import_statement name: (dotted_name) @import.src)
+  (import_statement name: (aliased_import name: (dotted_name) @import.src))
+  (import_from_statement module_name: (dotted_name) @import.src)
+  (import_from_statement module_name: (relative_import) @import.src)
+  (call function: (identifier) @call.id)
+  (call function: (attribute attribute: (identifier) @call.member))
 `;
 const PY_BUILTIN_METHODS = new Set([
     "get", "set", "keys", "values", "items", "pop", "popitem", "update", "setdefault", "copy", "clear",

package/dist/integrations/claudemd.js

@@ -10,6 +10,17 @@ import { wikiSummary } from "../wiki/wiki.js";
 import { PolicyRepository } from "../constitution/repository.js";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
 const END = "<!-- HUNCH:END -->";
+/** 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,
+ *  fnd_b269d5c422): equal outside the block ⇒ regenerating cannot lose prose. */
+export function stripManagedSection(text) {
+    const iStart = text.indexOf(START);
+    const iEnd = text.indexOf(END);
+    if (iStart < 0 || iEnd <= iStart)
+        return text;
+    return text.slice(0, iStart) + text.slice(iEnd + END.length);
+}
 export function renderHunchSection(store, root) {
     const constraints = store.json
         .loadAll("constraints")

package/dist/integrations/providers.js

@@ -21,8 +21,8 @@ import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { writeFileAtomic } from "../core/io.js";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
-import { renderHunchSection, upsertSection, updateClaudeMd } from "./claudemd.js";
-import { isGitCleanPath } from "../extractors/git.js";
+import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd } from "./claudemd.js";
+import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 /** Strip // line and block comments + trailing commas (JSONC → JSON). String-aware
  *  (double-quoted, with escapes) so a // inside a value isn't mangled. VS Code's
  *  .vscode/mcp.json is JSONC, so we must tolerate comments. */
@@ -444,22 +444,50 @@ export function refreshExistingGrounding(root, store) {
     }
     return changed;
 }
-/** Capture-commit refresh: rewrite ONLY grounding docs that are git-clean, and return the
- *  absolute paths of the ones that changed so the caller folds them into the memory commit
- *  (commitAndPushHunch alsoStage). This keeps committed record counts permanently true —
- *  every capture used to bump the count and re-stale the committed docs, failing the
- *  release gate's clean-tree check on the next CI index (the refresh-counts treadmill).
- *  A user-dirty or untracked doc is left completely untouched (never refreshed, never
- *  staged); it heals on the next manual `hunch sync` or `hunch index`. */
+/** Wholly-Hunch-owned grounding docs (namespaced rule files the generators emit
+ *  in full). Any dirt in these is generated dirt by contract — there is no user
+ *  prose to protect, so a stale copy is always safe to regenerate and stage. */
+const WHOLLY_OWNED_GROUNDING = new Set([
+    join(".cursor", "rules", "hunch.mdc"),
+    join(".windsurf", "rules", "hunch.md"),
+]);
+/** Is a DIRTY grounding doc's divergence from HEAD confined to generated content?
+ *  Marker-managed docs (CLAUDE.md, AGENTS.md, copilot-instructions): compare
+ *  worktree vs HEAD with the managed section stripped from both — equal outside
+ *  the block means regenerating cannot lose user prose. Wholly-owned rule files
+ *  need no comparison. Untracked files return false: a doc the user hasn't
+ *  committed is theirs to stage. */
+function generatedDirtOnly(root, rel, current) {
+    if (WHOLLY_OWNED_GROUNDING.has(rel))
+        return headFileContent(root, rel) !== null;
+    const head = headFileContent(root, rel);
+    if (head === null)
+        return false;
+    return stripManagedSection(head) === stripManagedSection(current);
+}
+/** 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
+ *  counts permanently true — every capture used to bump the count and re-stale the
+ *  committed docs, failing the release gate's clean-tree check on the next CI index
+ *  (the refresh-counts treadmill). The generated-dirt branch closes the second half
+ *  (fnd_b269d5c422): once a doc went stale-dirty, the clean-only rule skipped it on
+ *  every later flush FOREVER, and each release needed a manual chore commit. A doc
+ *  whose USER PROSE differs from HEAD is still left completely untouched. */
 export function refreshCommittableGrounding(root, store) {
     const changed = [];
     for (const [rel, write] of groundingTargets(root, store)) {
         const file = join(root, rel);
-        if (!existsSync(file) || !isGitCleanPath(root, rel))
+        if (!existsSync(file))
             continue;
         const before = readFileSync(file, "utf8");
+        const clean = isGitCleanPath(root, rel);
+        if (!clean && !generatedDirtOnly(root, rel, before))
+            continue;
         write();
-        if (readFileSync(file, "utf8") !== before)
+        // A doc that was stale-DIRTY must be staged even when the regeneration is a
+        // byte no-op — the commit is what re-syncs HEAD with the worktree.
+        if (readFileSync(file, "utf8") !== before || !clean)
             changed.push(file);
     }
     return changed;

package/dist/mcp/server.js

@@ -1527,6 +1527,7 @@ export function buildServerWithRootControl(initialRoot) {
         server,
         getRoot: () => root,
         setRoot,
+        cancelPendingRoot: () => { pendingRoot = null; },
     };
 }
 /** Back-compatible server construction for tests and callers that do not need
@@ -1555,6 +1556,14 @@ export function wireClientRoots(control, fallback) {
                 return;
             const next = resolveActiveRoot((response?.roots ?? []).map((root) => root.uri), fallback);
             if (!next) {
+                // Cancel a swap parked by an EARLIER generation. setRoot defers when a tool
+                // request is in flight; if the client's advertised set has since become
+                // ambiguous, applying that stale swap once the request drains would re-home
+                // to a repo the client no longer unambiguously advertises — writing (and
+                // auto-committing) a capture into the wrong repository, which is precisely
+                // what this refusal exists to prevent. Without this the message below was
+                // also a lie: the root did NOT stay put.
+                control.cancelPendingRoot();
                 console.error("[hunch-mcp] multiple client roots are equally plausible; keeping the current Hunch root");
                 return;
             }

package/dist/wiki/wiki.js

@@ -28,7 +28,7 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, mkdirSync, rmSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { writeFileAtomic } from "../core/io.js";
 import { compareCodeUnits } from "../core/canonicalOrder.js";
 import { hunchPaths, toPosixTarget } from "../core/paths.js";
@@ -36,15 +36,61 @@ import { isLive } from "../core/topics.js";
 import { scanRepoDocs } from "../core/docscan.js";
 import { adoptedSlug, adoptionHash, renderAdoptedDoc } from "./adopt.js";
 import { assembleGraphData, renderGraphPage } from "./graph.js";
+/** A wiki directory that is safe to join against the pages root: relative, POSIX,
+ *  no trailing slash, and free of any "." / ".." / empty segment. `.` would alias
+ *  the pages root itself (clobbering tracked files like README.md) and `..` writes
+ *  the rendered graph — which for the private home is the FULL overlay union —
+ *  outside the repository entirely. Returns undefined for anything unsafe. */
+function validDir(d) {
+    if (!d)
+        return undefined;
+    const v = toPosixTarget(d).replace(/\/+$/, "");
+    if (!v || isAbsolute(v) || /^[a-zA-Z]:/.test(v))
+        return undefined;
+    if (v.split("/").some((seg) => seg === "" || seg === "." || seg === ".."))
+        return undefined;
+    return v;
+}
 /** Normalize a --dir override: POSIX separators, no trailing slash — the dir is
- *  a committed manifest key prefix, so it must hash identically on every OS. */
-const normDir = (d) => d ? toPosixTarget(d).replace(/\/+$/, "") || undefined : undefined;
+ *  a committed manifest key prefix, so it must hash identically on every OS.
+ *  An unsafe override THROWS rather than silently falling back, so a rejected flag
+ *  can never quietly write somewhere else. */
+const normDir = (d) => {
+    if (d === undefined)
+        return undefined;
+    const v = validDir(d);
+    if (!v) {
+        throw new Error(`refusing --dir ${JSON.stringify(d)}: the wiki directory must be a relative path inside the repository (no "." or ".." segments, not absolute).`);
+    }
+    return v;
+};
+/** Resolve a manifest page key to an absolute path INSIDE this home's page
+ *  directory, or null when it escapes.
+ *
+ *  Both inputs that reach the join are untrusted. `.hunch/wiki-manifest.json` is a
+ *  COMMITTED file (so CI can gate on it), which makes every page KEY inside it
+ *  PR- and merge-influenceable — and `wikiStatus` classifies any key no current
+ *  artifact claims as an orphan to be deleted. Without this check a key like
+ *  "../../id_rsa" turned a plain `hunch wiki` into arbitrary file deletion, with
+ *  `hunch drift` politely instructing the maintainer to run it. Re-checked at BOTH
+ *  the write and the delete site, so a manifest written before this guard existed
+ *  still cannot escape. */
+function containedPagePath(home, page) {
+    if (!page || page.includes("\0") || isAbsolute(page) || /^[a-zA-Z]:/.test(page))
+        return null;
+    const baseDir = resolve(join(home.pagesRoot, home.dir));
+    const abs = resolve(join(home.pagesRoot, ...page.split("/")));
+    const rel = relative(baseDir, abs);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return null;
+    return abs;
+}
 export function publicHome(root, dirOverride) {
     const manifestPath = join(hunchPaths(root).hunch, "wiki-manifest.json");
     return {
         kind: "public",
         pagesRoot: root,
-        dir: normDir(dirOverride) ?? readWikiManifestAt(manifestPath)?.dir ?? "wiki",
+        dir: normDir(dirOverride) ?? validDir(readWikiManifestAt(manifestPath)?.dir) ?? "wiki",
         manifestPath,
         source: "public",
     };
@@ -60,7 +106,7 @@ export function privateHome(store, dirOverride) {
     return {
         kind: "private",
         pagesRoot: dirname(store.privateDir),
-        dir: normDir(dirOverride) ?? readWikiManifestAt(manifestPath)?.dir ?? "wiki",
+        dir: normDir(dirOverride) ?? validDir(readWikiManifestAt(manifestPath)?.dir) ?? "wiki",
         manifestPath,
         source: "all",
     };
@@ -515,6 +561,11 @@ export function wikiStatus(store, home, srcRoot) {
     for (const [page, p] of Object.entries(manifest?.pages ?? {})) {
         if (expected.has(page))
             continue;
+        // The manifest is committed, so a key is attacker-influenceable through an
+        // ordinary PR — and reaching this list means "delete this file". Only a key
+        // that resolves inside this home's page directory may be classified at all.
+        if (!containedPagePath(home, page))
+            continue;
         (p.component.startsWith(ADOPTED_PREFIX) ? adoptionOrphans : orphans).push(page);
     }
     return { home, entries, docs, adoptions, adoptionOrphans, decisions, specs, index, now, graph, repoWide, orphans };
@@ -556,7 +607,10 @@ export async function generateWiki(store, srcRoot, home, opts) {
     /** Written-bytes ledger — the hand-edit tripwire recorded per page. */
     const bytesByPage = new Map();
     const put = (page, content) => {
-        writeFileAtomic(join(home.pagesRoot, ...page.split("/")), content);
+        const abs = containedPagePath(home, page);
+        if (!abs)
+            throw new Error(`refusing to write wiki page ${JSON.stringify(page)}: it resolves outside ${join(home.pagesRoot, home.dir)}`);
+        writeFileAtomic(abs, content);
         bytesByPage.set(page, sha16(content));
         written.push(page);
     };
@@ -614,8 +668,16 @@ export async function generateWiki(store, srcRoot, home, opts) {
     const removed = [];
     for (const [pages, why] of [[status.orphans, "component gone"], [status.adoptionOrphans, "original healed or removed — copy retired"]]) {
         for (const page of pages) {
+            // Re-assert containment at the DELETE site too: wikiStatus already filters
+            // escaping manifest keys, but this is the primitive that removes files, so it
+            // must not depend on an upstream filter having run.
+            const abs = containedPagePath(home, page);
+            if (!abs) {
+                log(`  ⚠ ${page} — refusing to remove a manifest entry that resolves outside ${join(home.pagesRoot, home.dir)}`);
+                continue;
+            }
             try {
-                rmSync(join(home.pagesRoot, ...page.split("/")), { force: true });
+                rmSync(abs, { force: true });
             }
             catch {
                 /* best effort */
@@ -627,8 +689,26 @@ export async function generateWiki(store, srcRoot, home, opts) {
     if (written.length || removed.length) {
         const pages = {};
         const entry = (page, component, hash, state) => {
-            const keep = state === "fresh" ? prior?.pages[page] : undefined;
-            pages[page] = keep ?? { component, hash, generated: opts.now, bytes: bytesByPage.get(page) };
+            const prev = prior?.pages[page];
+            const justWritten = bytesByPage.get(page);
+            // Carry the prior entry forward ONLY for a fresh page this run did not rewrite.
+            // A full regen (`only: "all"`) rewrites every page, so reusing the prior entry
+            // there recorded the OLD bytes against freshly written content — making the
+            // hand-edit tripwire fire on Hunch's own output, so `hunch wiki --check` exited
+            // 1 immediately after a successful `hunch wiki` and the tripwire's signal for a
+            // REAL hand edit was destroyed.
+            if (state === "fresh" && justWritten === undefined && prev) {
+                pages[page] = prev;
+                return;
+            }
+            pages[page] = {
+                component,
+                hash,
+                // Keep the original stamp for an unchanged-but-rewritten page so a full regen
+                // stays byte-idempotent in git.
+                generated: state === "fresh" && prev ? prev.generated : opts.now,
+                bytes: justWritten ?? prev?.bytes,
+            };
         };
         for (const e of status.entries)
             entry(e.page, e.pack.component.id, e.hash, e.state);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.10.1",
+  "version": "1.10.2",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Engineering memory and a deterministic Change Gate for AI-assisted codebases: decisions, rejected approaches, constraints, and bug lineage become portable context and opt-in enforcement for every MCP assistant.",