@davesheffer/hunch 1.43.0 → 1.45.0

package/dist/extractors/k8sManifest.d.ts

@@ -68,5 +68,35 @@ export declare function namespacesCompatible(a: string | null, b: string | null)
  *  paths below aren't hand-duplicated per kind. */
 export declare const POD_SPEC_PATH_BY_KIND: Record<string, string>;
 export declare const LABELS_PATH_BY_KIND: Record<string, string>;
-export declare function extractK8sManifest(source: string): K8sManifestDocument[];
+/** `namespace` is a Kustomize transformer namespace for this file (from
+ *  kustomizeNamespaces): undefined = no transformer, null = UNKNOWN (two
+ *  kustomizations render this file into different namespaces). */
+export declare function extractK8sManifest(source: string, opts?: {
+    namespace?: string | null;
+}): K8sManifestDocument[];
+export interface KustomizationInfo {
+    /** Top-level `namespace:` when it is a valid literal namespace, else null. */
+    namespace: string | null;
+    /** `resources:` entries exactly as written (paths relative to the kustomization's directory). */
+    resources: string[];
+}
+export declare function isKustomizationFile(path: string): boolean;
+/** Reads only the two top-level fields the namespace transformer needs:
+ *  `namespace:` and the `resources:` list (block `- item` lines or a one-line
+ *  flow `[a, b]`). One linear pass; everything else in the file is ignored. */
+export declare function extractKustomization(source: string): KustomizationInfo;
+/** The Kustomize namespace each manifest file is rendered into, keyed by repo
+ *  path. `kustomizations` is keyed by the kustomization's DIRECTORY ("" for
+ *  the repo root); `files` is the indexed file set.
+ *
+ *  A `resources:` entry naming a file applies the namespace to that file; an
+ *  entry naming a directory that holds its own kustomization is a base, and
+ *  the referring (outer) kustomization's namespace wins over the base's, as
+ *  Kustomize applies the overlay transformer to the base's output. Only
+ *  kustomizations no other kustomization references are rendered as roots.
+ *  A file rendered into two different namespaces (one base shared by dev and
+ *  prod overlays, the common layout) maps to null = UNKNOWN; a file rendered
+ *  only without any transformer is absent. Not modelled: remote resources,
+ *  `components:`, the deprecated `bases:` field, and globs. */
+export declare function kustomizeNamespaces(kustomizations: ReadonlyMap<string, KustomizationInfo>, files: ReadonlySet<string>): Map<string, string | null>;
 export {};

package/dist/extractors/k8sManifest.js

@@ -1,4 +1,5 @@
-import { sourceLines } from "../core/eol.js";
+import { posix } from "node:path";
+import { eolLengthAt, sourceLines } from "../core/eol.js";
 // ReplicaSet is included alongside the pod-spec-embedding/networking kinds
 // specifically because it's the dominant real-world bearer of
 // ownerReferences (Deployment -> ReplicaSet -> Pod is the common chain) --
@@ -606,7 +607,16 @@ function extractLiteralLabelMap(prefix, entries, unresolvedContainers, valueless
     }
     return pairs.length > 0 ? Object.fromEntries(pairs) : null;
 }
-function buildDocument(text, docStartChar, entries, unresolvedContainers, valuelessKeyParents) {
+/** Cluster-scoped kinds Kustomize's namespace transformer leaves alone. None
+ *  of them is in ALLOWED_KINDS today, so this is a guard for the override in
+ *  buildDocument rather than a live branch: an allowlist widening must not
+ *  start stamping a namespace onto a resource that cannot have one. */
+const CLUSTER_SCOPED_KINDS = new Set([
+    "Namespace", "Node", "PersistentVolume", "StorageClass", "CustomResourceDefinition",
+    "ClusterRole", "ClusterRoleBinding", "PriorityClass", "IngressClass", "RuntimeClass",
+    "MutatingWebhookConfiguration", "ValidatingWebhookConfiguration", "APIService",
+]);
+function buildDocument(text, docStartChar, entries, unresolvedContainers, valuelessKeyParents, namespaceOverride) {
     const kindEntry = findEntry(entries, "kind");
     const kind = kindEntry?.value.form === "literal" ? kindEntry.value.value : null;
     if (!kind || !ALLOWED_KINDS.has(kind))
@@ -615,8 +625,13 @@ function buildDocument(text, docStartChar, entries, unresolvedContainers, valuel
     // scanner's quote-stripping, comment-stripping and CRLF tolerance for free.
     // Read OUTSIDE the `resource` branch below: a document with no
     // metadata.name still emits references, and those references carry this
-    // document's namespace.
-    const namespace = namespaceAt(entries, "metadata.namespace");
+    // document's namespace. A Kustomize namespace transformer (see
+    // kustomizeNamespaces) REPLACES metadata.namespace on every namespaced
+    // resource, explicit or not, so it wins here; an explicit backendRefs
+    // namespace sibling is not rewritten and keeps its own.
+    const namespace = namespaceOverride !== undefined && !CLUSTER_SCOPED_KINDS.has(kind)
+        ? namespaceOverride
+        : namespaceAt(entries, "metadata.namespace");
     const nameEntry = findEntry(entries, "metadata.name");
     const resource = nameEntry
         ? { kind, name: nameEntry.value, namespace, startChar: docStartChar, endChar: docStartChar + text.length }
@@ -643,12 +658,18 @@ function buildDocument(text, docStartChar, entries, unresolvedContainers, valuel
 // and it still isn't here: the dashes must be followed by whitespace or end
 // of line.
 const DOC_SEPARATOR = /^(?:---(?:[ \t]+.*)?|\.\.\.)[ \t]*$/;
-export function extractK8sManifest(source) {
+/** `namespace` is a Kustomize transformer namespace for this file (from
+ *  kustomizeNamespaces): undefined = no transformer, null = UNKNOWN (two
+ *  kustomizations render this file into different namespaces). */
+export function extractK8sManifest(source, opts = {}) {
     const docs = [];
     const boundaries = [];
     for (const line of sourceLines(source)) {
-        if (DOC_SEPARATOR.test(line.content))
-            boundaries.push(line.start, line.end);
+        if (!DOC_SEPARATOR.test(line.content))
+            continue;
+        // The next document starts AFTER the separator's line terminator, so the
+        // same document text has the same span wherever it sits (#451).
+        boundaries.push(line.start, line.end + eolLengthAt(source, line.end));
     }
     const starts = [0, ...boundaries.filter((_, i) => i % 2 === 1)];
     const ends = [...boundaries.filter((_, i) => i % 2 === 0), source.length];
@@ -657,8 +678,112 @@ export function extractK8sManifest(source) {
         const end = ends[i];
         const text = source.slice(start, end);
         const { entries, unresolvedContainers, valuelessKeyParents } = scanFieldPaths(text, start);
-        docs.push(buildDocument(text, start, entries, unresolvedContainers, valuelessKeyParents));
+        docs.push(buildDocument(text, start, entries, unresolvedContainers, valuelessKeyParents, opts.namespace));
     }
     return docs;
 }
+const KUSTOMIZATION_FILE = /(?:^|\/)(?:kustomization\.ya?ml|Kustomization)$/;
+export function isKustomizationFile(path) {
+    return KUSTOMIZATION_FILE.test(path);
+}
+/** Reads only the two top-level fields the namespace transformer needs:
+ *  `namespace:` and the `resources:` list (block `- item` lines or a one-line
+ *  flow `[a, b]`). One linear pass; everything else in the file is ignored. */
+export function extractKustomization(source) {
+    let namespace = null;
+    const resources = [];
+    let inResources = false;
+    for (const { content } of sourceLines(source)) {
+        const line = stripTrailingComment(content).trimEnd();
+        if (line.trim() === "")
+            continue;
+        const item = /^\s*-\s+(.+)$/.exec(line);
+        if (inResources && item) {
+            resources.push(stripQuotes(item[1].trim()));
+            continue;
+        }
+        if (/^\s/.test(line))
+            continue; // nested content of some other top-level key
+        inResources = false;
+        const top = /^([A-Za-z]+):[ \t]*(.*)$/.exec(line);
+        if (!top)
+            continue;
+        const value = top[2].trim();
+        if (top[1] === "namespace") {
+            const ns = stripQuotes(value);
+            namespace = DNS_LABEL.test(ns) && ns !== "null" ? ns : null;
+        }
+        else if (top[1] === "resources") {
+            if (value === "")
+                inResources = true;
+            else if (value.startsWith("[") && value.endsWith("]")) {
+                for (const part of value.slice(1, -1).split(","))
+                    if (part.trim())
+                        resources.push(stripQuotes(part.trim()));
+            }
+        }
+    }
+    return { namespace, resources };
+}
+/** The Kustomize namespace each manifest file is rendered into, keyed by repo
+ *  path. `kustomizations` is keyed by the kustomization's DIRECTORY ("" for
+ *  the repo root); `files` is the indexed file set.
+ *
+ *  A `resources:` entry naming a file applies the namespace to that file; an
+ *  entry naming a directory that holds its own kustomization is a base, and
+ *  the referring (outer) kustomization's namespace wins over the base's, as
+ *  Kustomize applies the overlay transformer to the base's output. Only
+ *  kustomizations no other kustomization references are rendered as roots.
+ *  A file rendered into two different namespaces (one base shared by dev and
+ *  prod overlays, the common layout) maps to null = UNKNOWN; a file rendered
+ *  only without any transformer is absent. Not modelled: remote resources,
+ *  `components:`, the deprecated `bases:` field, and globs. */
+export function kustomizeNamespaces(kustomizations, files) {
+    const KEEP = "\0keep";
+    const childFiles = new Map();
+    const childDirs = new Map();
+    const referenced = new Set();
+    for (const [dir, k] of kustomizations) {
+        for (const entry of k.resources) {
+            let p = posix.normalize(posix.join(dir, entry)).replace(/\/+$/, "");
+            if (p === ".")
+                p = "";
+            if (p === ".." || p.startsWith("../"))
+                continue;
+            if (files.has(p))
+                (childFiles.get(dir) ?? childFiles.set(dir, []).get(dir)).push(p);
+            else if (p !== dir && kustomizations.has(p)) {
+                (childDirs.get(dir) ?? childDirs.set(dir, []).get(dir)).push(p);
+                referenced.add(p);
+            }
+        }
+    }
+    const seen = new Map();
+    const visited = new Set();
+    const render = (dir, outer) => {
+        const ns = outer ?? kustomizations.get(dir).namespace;
+        const key = `${dir}\0${ns ?? KEEP}`;
+        if (visited.has(key))
+            return; // memoised per (dir, namespace); also breaks cycles
+        visited.add(key);
+        for (const f of childFiles.get(dir) ?? [])
+            (seen.get(f) ?? seen.set(f, new Set()).get(f)).add(ns ?? KEEP);
+        for (const child of childDirs.get(dir) ?? [])
+            render(child, ns);
+    };
+    for (const dir of [...kustomizations.keys()].sort())
+        if (!referenced.has(dir))
+            render(dir, null);
+    const out = new Map();
+    for (const [file, set] of seen) {
+        if (set.size > 1)
+            out.set(file, null);
+        else {
+            const only = [...set][0];
+            if (only !== KEEP)
+                out.set(file, only);
+        }
+    }
+    return out;
+}
 //# sourceMappingURL=k8sManifest.js.map

package/dist/integrations/claudemd.d.ts

@@ -1,5 +1,7 @@
 import type { HunchStore } from "../store/hunchStore.js";
 import { groundingTemplate } from "../core/groundingLag.js";
+export declare const HUNCH_START = "<!-- HUNCH:START \u2014 auto-generated, do not edit by hand -->";
+export declare const HUNCH_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 declare const GROUNDING_TEMPLATE = 2;

package/dist/integrations/claudemd.js

@@ -9,8 +9,10 @@ import { basename, join, dirname } from "node:path";
 import { wikiSummary } from "../wiki/wiki.js";
 import { PolicyRepository } from "../constitution/repository.js";
 import { renderCountsMatch, parseGroundingCounts, groundingTemplate } from "../core/groundingLag.js";
-const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
-const END = "<!-- HUNCH:END -->";
+export const HUNCH_START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
+export const HUNCH_END = "<!-- HUNCH:END -->";
+const START = HUNCH_START;
+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;
@@ -96,7 +98,7 @@ export function renderHunchSection(store, root) {
     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("- **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("- **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)`. When the prompt hook raises an escalation this task touches, ask the user; silence is never approval. `hunch_escalations()` lists the rest.");
     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`." +

package/dist/integrations/gitignore.d.ts

@@ -39,3 +39,26 @@ export interface ManagedGitignoreUpgrade {
 export declare function upgradeManagedGitignore(root: string): ManagedGitignoreUpgrade;
 /** Output lines describing what an upgrade changed; empty when nothing did. */
 export declare function describeGitignoreUpgrade(upgrade: ManagedGitignoreUpgrade): string[];
+export interface MemoryIgnoreRule {
+    /** Ignore file that holds the rule, as git reports it (e.g. `.gitignore`). */
+    source: string;
+    /** 1-based line of the rule in `source`. */
+    line: number;
+    pattern: string;
+}
+/** The user's ignore rule that keeps engineering memory out of Git, or null.
+ *  A repository that ignores `.hunch/` (or `.hunch/decisions/`) silently loses every
+ *  capture: the records are written, never committed, and gone on a fresh clone.
+ *  Hunch's own private-only block ignores the same paths on purpose (memory lives
+ *  in an overlay), so a rule inside that block is not reported. Unknown git state
+ *  yields null: the caller then says nothing rather than guessing. */
+export declare function memoryIgnoreRule(root: string): MemoryIgnoreRule | null;
+/** One line telling the user their memory will not reach Git, and how to fix it. */
+export declare function describeMemoryIgnoreRule(rule: MemoryIgnoreRule): string;
+/** `.gitignore` text with both managed Hunch blocks removed (markers inclusive),
+ *  every other byte kept, for `hunch uninstall --purge` (#449). `damaged` when a
+ *  marker line has no matching end line: the block is never guessed at. */
+export declare function stripManagedGitignore(text: string): {
+    next: string;
+    damaged: boolean;
+};

package/dist/integrations/gitignore.js

@@ -12,6 +12,7 @@
  * block written by an older release gains entries added later) and is otherwise
  * byte-identical; everything outside the markers is left untouched.
  */
+import { spawnSync } from "node:child_process";
 import { readFileSync, existsSync, lstatSync, realpathSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { writeFileAtomic } from "../core/io.js";
@@ -231,4 +232,51 @@ export function describeGitignoreUpgrade(upgrade) {
     }
     return out;
 }
+/** The user's ignore rule that keeps engineering memory out of Git, or null.
+ *  A repository that ignores `.hunch/` (or `.hunch/decisions/`) silently loses every
+ *  capture: the records are written, never committed, and gone on a fresh clone.
+ *  Hunch's own private-only block ignores the same paths on purpose (memory lives
+ *  in an overlay), so a rule inside that block is not reported. Unknown git state
+ *  yields null: the caller then says nothing rather than guessing. */
+export function memoryIgnoreRule(root) {
+    const probe = ".hunch/decisions/dec_0000000000.json";
+    const r = spawnSync("git", ["check-ignore", "-v", "--no-index", "--", probe], { cwd: root, encoding: "utf8", windowsHide: true });
+    if (r.error || r.status !== 0)
+        return null;
+    const m = /^(.*):(\d+):(.*)\t/.exec(r.stdout ?? "");
+    if (!m)
+        return null;
+    const rule = { source: m[1], line: Number(m[2]), pattern: m[3] };
+    if (rule.pattern.startsWith("!"))
+        return null;
+    const file = resolve(root, rule.source);
+    if (existsSync(file)) {
+        const span = findBlock(readFileSync(file, "utf8").split("\n"), MEM_MARK, MEM_END);
+        if (span && rule.line - 1 > span.start && rule.line - 1 < span.end)
+            return null;
+    }
+    return rule;
+}
+/** One line telling the user their memory will not reach Git, and how to fix it. */
+export function describeMemoryIgnoreRule(rule) {
+    return `${rule.source} line ${rule.line} (\`${rule.pattern}\`) ignores .hunch/, so captured memory is never committed or shared and is lost on a fresh clone. Remove that line, or keep memory in a private repository with \`hunch private --repo <url>\`.`;
+}
+/** `.gitignore` text with both managed Hunch blocks removed (markers inclusive),
+ *  every other byte kept, for `hunch uninstall --purge` (#449). `damaged` when a
+ *  marker line has no matching end line: the block is never guessed at. */
+export function stripManagedGitignore(text) {
+    let lines = text.split("\n");
+    let damaged = false;
+    for (const [mark, end] of [[MARK, END], [MEM_MARK, MEM_END]]) {
+        if (!lines.some((l) => cleanLine(l) === mark))
+            continue;
+        const span = findBlock(lines, mark, end);
+        if (!span) {
+            damaged = true;
+            continue;
+        }
+        lines = [...lines.slice(0, span.start), ...lines.slice(span.end + 1)];
+    }
+    return { next: lines.join("\n"), damaged };
+}
 //# sourceMappingURL=gitignore.js.map

package/dist/integrations/hooks.d.ts

@@ -144,6 +144,21 @@ export declare function hookStatus(root: string): {
     postMerge: boolean;
     postCheckout: boolean;
 };
+/** One git hook file `hunch uninstall` would change. `next === null` deletes the
+ *  file (only a shebang was left); a `reason` means nothing is edited and the
+ *  user removes the block by hand. */
+export interface HookRemoval {
+    path: string;
+    hookName: string;
+    next?: string | null;
+    reason?: string;
+}
+/** Plan the removal of every Hunch-managed block from the hooks git runs (#449).
+ *  Read-only. Only a hook file Hunch itself writes (manager "none", or an
+ *  exec/exit file whose block it appended) is edited, and only a block with both
+ *  markers; a hook manager's file, a tracked hooks dir, or an unclosed block is
+ *  reported instead — the same lines Hunch refuses to write on install. */
+export declare function planHookRemoval(root: string): HookRemoval[];
 /** Doctor lines for where each installed/stale hook points (issue #315): hooks
  *  sharing one invocation share one line, and a line whose invocation is not the
  *  Hunch currently running says so. Informational — a hook may legitimately

package/dist/integrations/hooks.js

@@ -20,7 +20,7 @@ import { homedir } from "node:os";
 import { hooksDir, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
 import { HUNCH_NPX_PACKAGE_SPEC, HUNCH_PACKAGE_NAME } from "../core/version.js";
-import { normalizeEol } from "../core/eol.js";
+import { eolLengthAt, normalizeEol } from "../core/eol.js";
 const MARK = "# >>> hunch post-commit >>>";
 const ENDMARK = "# <<< hunch post-commit <<<";
 const GIT_CONTEXT = { checkoutType: "$3", portable: false };
@@ -942,6 +942,54 @@ export function hookStatus(root) {
         postCheckout: r.postCheckout.state === "installed",
     };
 }
+/** Plan the removal of every Hunch-managed block from the hooks git runs (#449).
+ *  Read-only. Only a hook file Hunch itself writes (manager "none", or an
+ *  exec/exit file whose block it appended) is edited, and only a block with both
+ *  markers; a hook manager's file, a tracked hooks dir, or an unclosed block is
+ *  reported instead — the same lines Hunch refuses to write on install. */
+export function planHookRemoval(root) {
+    const ends = {
+        [MARK]: ENDMARK, [PRE_MARK]: PRE_END, [GROUNDING_MERGE_MARK]: GROUNDING_MERGE_END,
+        [REPAIR_MERGE_MARK]: REPAIR_MERGE_END, [CHECKOUT_MARK]: CHECKOUT_END,
+    };
+    const byHook = new Map();
+    for (const [hookName, mark] of managedBlocks())
+        byHook.set(hookName, [...(byHook.get(hookName) ?? []), mark]);
+    const out = [];
+    for (const [hookName, marks] of byHook) {
+        const t = resolveHookTarget(root, hookName, marks[0]);
+        if (t.manager !== "none" && t.manager !== "exec-exit") {
+            const owner = readText(t.ownerFile);
+            if (owner !== null && marks.some((m) => owner.includes(m))) {
+                out.push({ path: t.ownerFile, hookName, reason: `${t.manager} owns this hook; remove the Hunch block from it by hand` });
+            }
+            continue;
+        }
+        const cur = readText(t.hookPath);
+        if (cur === null || !marks.some((m) => cur.includes(m)))
+            continue;
+        let next = cur;
+        let damaged = false;
+        for (const mark of marks) {
+            if (!next.includes(mark))
+                continue;
+            const m = new RegExp(`${escapeRe(mark)}[\\s\\S]*?${escapeRe(ends[mark])}`).exec(next);
+            if (!m) {
+                damaged = true;
+                continue;
+            }
+            const end = m.index + m[0].length;
+            next = next.slice(0, m.index) + next.slice(end + eolLengthAt(next, end));
+        }
+        if (damaged) {
+            out.push({ path: t.hookPath, hookName, reason: "a Hunch block here has no closing marker; remove it by hand" });
+            continue;
+        }
+        const body = normalizeEol(next).split("\n").filter((l, i) => !(i === 0 && l.startsWith("#!")));
+        out.push({ path: t.hookPath, hookName, next: body.every((l) => l.trim() === "") ? null : next });
+    }
+    return out;
+}
 /** Doctor lines for where each installed/stale hook points (issue #315): hooks
  *  sharing one invocation share one line, and a line whose invocation is not the
  *  Hunch currently running says so. Informational — a hook may legitimately

package/dist/integrations/mergeDriver.d.ts

@@ -1,3 +1,5 @@
+export declare const ATTR_LINES: readonly string[];
+export declare function targetRepositoryEnv(): NodeJS.ProcessEnv;
 export declare function installMergeDriver(root: string, invShell: string): {
     action: string;
 };

package/dist/integrations/mergeDriver.js

@@ -20,12 +20,12 @@ import { GROUNDING_DOC_PATHS } from "./providers.js";
 //
 // The five generated grounding docs get the OTHER driver — narrower in scope
 // (it only ever touches a hard conflict confined to the counts sentence).
-const ATTR_LINES = [
+export const ATTR_LINES = [
     ".hunch/**/*.json merge=hunch",
     ".hunch/manifest.json merge=text",
     ...GROUNDING_DOC_PATHS.map((f) => `${f} merge=hunch-grounding`),
 ];
-function targetRepositoryEnv() {
+export function targetRepositoryEnv() {
     const env = { ...process.env };
     for (const key of [
         "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT",

package/dist/integrations/providers.d.ts

@@ -1,5 +1,10 @@
 import type { HunchStore } from "../store/hunchStore.js";
 import type { Invocation } from "./scaffold.js";
+/** Read a JSON/JSONC object. Returns {} only for an ABSENT or empty file. A
+ *  non-empty file we cannot parse THROWS — overwriting it would silently wipe the
+ *  user's other MCP servers. */
+export declare function readJsonObj(file: string): Record<string, unknown>;
+export declare function isHunchProviderHook(entry: unknown): boolean;
 /** Cursor: .cursor/mcp.json — same `mcpServers` shape as Claude Desktop/Code. */
 export declare function writeCursorMcp(root: string, inv: Invocation): string;
 /** VS Code (Copilot agent mode): .vscode/mcp.json — root key is `servers`, and
@@ -20,6 +25,8 @@ export declare function writeAntigravityMcp(inv: Invocation, home?: string): str
  * committed with the repository, so every clone gets the same private/local
  * Hunch server without touching a user's home directory. */
 export declare function writeAntigravityWorkspaceMcp(root: string, inv: Invocation): string;
+export declare const TOML_START = "# >>> hunch mcp (managed) >>>";
+export declare const TOML_END = "# <<< hunch mcp <<<";
 /** Codex CLI: .codex/config.toml — `[mcp_servers.hunch]` stdio entry. We own only
  *  a marker-delimited block; any other TOML the user has is preserved. Paths use
  *  TOML single-quote LITERAL strings so Windows backslashes need no escaping. */
@@ -108,7 +115,16 @@ export interface ProviderScaffold {
  *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
  *  a writer that refuses to clobber a malformed file degrades to a warning rather
  *  than aborting the rest. Claude Code is handled separately by scaffold.ts. */
+/** The assistants `scaffoldProviders` can configure, besides the always-written AGENTS.md. */
+export declare const PROVIDER_ASSISTANTS: readonly ["Cursor", "VS Code (Copilot)", "Codex CLI", "Windsurf", "Google Antigravity"];
+export type ProviderAssistant = typeof PROVIDER_ASSISTANTS[number];
+/** Assistants with a footprint here: a config already in the repository (a teammate
+ *  set it up), a settings folder in the user's home, or a command on PATH. `hunch init`
+ *  configures only these, so a repository is not filled with settings for tools nobody
+ *  on it uses; when none is found it configures every assistant, as before. */
+export declare function detectAssistants(root: string, home?: string, env?: NodeJS.ProcessEnv): Set<ProviderAssistant>;
 export declare function scaffoldProviders(root: string, inv: Invocation, store: HunchStore, options?: {
     agentHooks?: boolean;
     home?: string;
+    only?: ReadonlySet<string>;
 }): ProviderScaffold[];

package/dist/integrations/providers.js

@@ -20,7 +20,7 @@
 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 { join, dirname, delimiter } from "node:path";
 import { isHunchHookCommand } from "./hookmatch.js";
 import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd, preserveNewerTemplate } from "./claudemd.js";
 import { headFileContent, isGitCleanPath } from "../extractors/git.js";
@@ -50,7 +50,7 @@ function hasJsoncComments(raw) {
 /** Read a JSON/JSONC object. Returns {} only for an ABSENT or empty file. A
  *  non-empty file we cannot parse THROWS — overwriting it would silently wipe the
  *  user's other MCP servers. */
-function readJsonObj(file) {
+export function readJsonObj(file) {
     if (!existsSync(file))
         return {};
     const raw = readFileSync(file, "utf8");
@@ -128,7 +128,7 @@ function shellToken(part) {
 function hookCommand(inv, provider) {
     return [inv.command, ...inv.args, "hook", "--provider", provider].map(shellToken).join(" ");
 }
-function isHunchProviderHook(entry) {
+export function isHunchProviderHook(entry) {
     const e = entry && typeof entry === "object" ? entry : null;
     // Codex (like Claude Code) nests commands under a matcher entry: an entry
     // whose every nested hook is ours is ours; a mixed entry stays foreign.
@@ -210,8 +210,8 @@ export function writeAntigravityWorkspaceMcp(root, inv) {
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
-const TOML_START = "# >>> hunch mcp (managed) >>>";
-const TOML_END = "# <<< hunch mcp <<<";
+export const TOML_START = "# >>> hunch mcp (managed) >>>";
+export const TOML_END = "# <<< hunch mcp <<<";
 /** Codex CLI: .codex/config.toml — `[mcp_servers.hunch]` stdio entry. We own only
  *  a marker-delimited block; any other TOML the user has is preserved. Paths use
  *  TOML single-quote LITERAL strings so Windows backslashes need no escaping. */
@@ -560,6 +560,32 @@ function runProvider(writers) {
  *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
  *  a writer that refuses to clobber a malformed file degrades to a warning rather
  *  than aborting the rest. Claude Code is handled separately by scaffold.ts. */
+/** The assistants `scaffoldProviders` can configure, besides the always-written AGENTS.md. */
+export const PROVIDER_ASSISTANTS = ["Cursor", "VS Code (Copilot)", "Codex CLI", "Windsurf", "Google Antigravity"];
+function onPath(names, env) {
+    const dirs = (env.PATH ?? env.Path ?? "").split(delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").concat("") : [""];
+    return dirs.some((dir) => names.some((name) => exts.some((ext) => existsSync(join(dir, name + ext)))));
+}
+/** Assistants with a footprint here: a config already in the repository (a teammate
+ *  set it up), a settings folder in the user's home, or a command on PATH. `hunch init`
+ *  configures only these, so a repository is not filled with settings for tools nobody
+ *  on it uses; when none is found it configures every assistant, as before. */
+export function detectAssistants(root, home = homedir(), env = process.env) {
+    const has = (...paths) => paths.some((p) => existsSync(p));
+    const found = new Set();
+    if (has(join(root, ".cursor"), join(home, ".cursor")) || onPath(["cursor", "cursor-agent"], env))
+        found.add("Cursor");
+    if (has(join(root, ".vscode"), join(root, ".github", "copilot-instructions.md"), join(home, ".vscode")) || onPath(["code", "code-insiders"], env))
+        found.add("VS Code (Copilot)");
+    if (has(join(root, ".codex"), join(home, ".codex")) || onPath(["codex"], env))
+        found.add("Codex CLI");
+    if (has(join(root, ".windsurf"), join(home, ".codeium", "windsurf")) || onPath(["windsurf"], env))
+        found.add("Windsurf");
+    if (has(join(root, ".agents", "mcp_config.json"), join(home, ".gemini")) || onPath(["antigravity"], env))
+        found.add("Google Antigravity");
+    return found;
+}
 export function scaffoldProviders(root, inv, store, options = {}) {
     const hooks = options.agentHooks !== false;
     const home = options.home;
@@ -584,6 +610,9 @@ export function scaffoldProviders(root, inv, store, options = {}) {
             }],
         ["Any (AGENTS.md)", () => runProvider([() => writeAgentsMd(root, store)])],
     ];
-    return tasks.map(([assistant, run]) => ({ assistant, ...run() }));
+    const only = options.only;
+    return tasks
+        .filter(([assistant]) => !only || only.has(assistant) || assistant === "Any (AGENTS.md)")
+        .map(([assistant, run]) => ({ assistant, ...run() }));
 }
 //# sourceMappingURL=providers.js.map

package/dist/integrations/scaffold.d.ts

@@ -23,6 +23,11 @@ export interface ClaudeHookInstall {
  * non-empty file we cannot parse THROWS rather than clobbering the user's config.
  */
 export declare function installClaudeHooks(root: string, hookCmd: string): ClaudeHookInstall;
+/** Ownership marker for generated slash commands: its presence means Hunch may
+ *  refresh the file; deleting the line hands the file to the user for good. */
+export declare const CMD_MARKER = "<!-- hunch:generated \u2014 refreshed by hunch init; delete this line to take ownership -->";
+/** File names `writeSlashCommands` writes under .claude/commands/. */
+export declare const SLASH_COMMAND_FILES: readonly string[];
 export declare function writeSlashCommands(root: string): {
     written: string[];
     skipped: string[];

package/dist/integrations/scaffold.js

@@ -62,7 +62,7 @@ Follow the Hunch-grounded workflow (DESIGN §5) — do NOT skip the memory looku
 2. Identify the suspect symbol/file, then \`hunch_get_dependents(<symbol>)\` to learn the blast radius.
 3. \`hunch_check_constraints(<scope>)\` — list invariants you must preserve.
 4. Propose a fix that honors past root causes AND constraints. Apply it and run the tests.
-5. If the fix encodes a non-trivial choice, \`hunch_record_decision(...)\` so the next session is grounded in it.
+5. If the human decided or corrected something during the fix, record it (\`hunch_record_decision\` / \`hunch_record_correction\`); the commit itself is captured automatically.
 `;
 const FRAGILE_CMD = `---
 description: Report the most fragile parts of this codebase, with evidence
@@ -233,13 +233,9 @@ export function installClaudeHooks(root, hookCmd) {
 }
 /** Ownership marker for generated slash commands: its presence means Hunch may
  *  refresh the file; deleting the line hands the file to the user for good. */
-const CMD_MARKER = "<!-- hunch:generated — refreshed by hunch init; delete this line to take ownership -->";
-export function writeSlashCommands(root) {
-    const dir = join(root, ".claude", "commands");
-    mkdirSync(dir, { recursive: true });
-    const written = [];
-    const skipped = [];
-    const files = [
+export const CMD_MARKER = "<!-- hunch:generated — refreshed by hunch init; delete this line to take ownership -->";
+function slashCommandFiles() {
+    return [
         ["hunch-why.md", WHY_CMD],
         ["hunch-fix.md", FIX_CMD],
         ["hunch-fragile.md", FRAGILE_CMD],
@@ -248,6 +244,15 @@ export function writeSlashCommands(root) {
         ["audit.md", AUDIT_CMD],
         ["worktrees.md", WORKTREES_CMD],
     ];
+}
+/** File names `writeSlashCommands` writes under .claude/commands/. */
+export const SLASH_COMMAND_FILES = Object.freeze(slashCommandFiles().map(([name]) => name));
+export function writeSlashCommands(root) {
+    const dir = join(root, ".claude", "commands");
+    mkdirSync(dir, { recursive: true });
+    const written = [];
+    const skipped = [];
+    const files = slashCommandFiles();
     for (const [name, body] of files) {
         const p = join(dir, name);
         // Generic names (capture/heal/audit) are plausibly the USER'S OWN commands;