@davesheffer/hunch 1.43.0 → 1.44.0

package/dist/core/runbookDraft.js

@@ -0,0 +1,43 @@
+/**
+ * The deterministic runbook draft (`hunch runbook <range> --task`): the commits and files
+ * of a range that describe the work, without Hunch's own bookkeeping (issue #425). With
+ * auto-commit on, a range interleaves capture commits (`hunch: capture …`) whose files are
+ * the store (.hunch/**) and the grounding docs flushCapture regenerates beside it.
+ *
+ * Same notion of "Hunch-owned" as sync (src/synthesis/synthesize.ts) and the task report
+ * (src/core/taskTouched.ts): the store is never the work; a grounding doc is Hunch's when
+ * it changed alongside the store, and the work's when a human edited it on its own.
+ */
+import { HUNCH_COMMIT_SUBJECT, HUNCH_MANAGED_FILES } from "./taskTouched.js";
+/** Grounding docs that are wholly generated (no user text): never the work. */
+const FULLY_MANAGED = new Set([".cursor/rules/hunch.mdc", ".windsurf/rules/hunch.md"]);
+const STORE_SEGMENTS = new Set([".hunch", ".hunch-cache"]);
+const norm = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
+/** The store lives at the repository root; a user folder named .hunch further down is theirs. */
+const isStore = (p) => STORE_SEGMENTS.has(norm(p).split("/")[0]);
+export function runbookDraft(commits, rangeFiles) {
+    const steps = [];
+    const workDocs = new Set(); // grounding docs a non-capture commit edited on its own
+    for (const c of commits) {
+        if (HUNCH_COMMIT_SUBJECT.test(c.subject))
+            continue;
+        const files = c.files.map(norm);
+        const touchesStore = files.some(isStore);
+        const work = files.filter((f) => !isStore(f) && !FULLY_MANAGED.has(f) && !(touchesStore && HUNCH_MANAGED_FILES.has(f)));
+        if (files.length && !work.length)
+            continue; // only Hunch's own paths
+        if (c.subject.trim())
+            steps.push(c.subject); // an empty-message commit is no step
+        for (const f of work)
+            if (HUNCH_MANAGED_FILES.has(f))
+                workDocs.add(f);
+    }
+    const files = rangeFiles.filter((raw) => {
+        const f = norm(raw);
+        if (isStore(f) || FULLY_MANAGED.has(f))
+            return false;
+        return !HUNCH_MANAGED_FILES.has(f) || workDocs.has(f);
+    });
+    return { steps, files };
+}
+//# sourceMappingURL=runbookDraft.js.map

package/dist/core/taskTouched.d.ts

@@ -1,6 +1,8 @@
 /** Files Hunch regenerates on every capture (src/integrations/providers.ts,
  * claudemd.ts): a fresh mtime on them is the capture, not the task's work. */
 export declare const HUNCH_MANAGED_FILES: ReadonlySet<string>;
+/** Commit subjects Hunch writes itself. */
+export declare const HUNCH_COMMIT_SUBJECT: RegExp;
 export declare function gitTouchedFiles(root: string, startedAt: string, finishedAt: string | null, options?: {
     limit?: number;
     timeoutMs?: number;

package/dist/core/taskTouched.js

@@ -27,7 +27,7 @@ const EXCLUDED_SEGMENTS = new Set([".hunch", ".hunch-cache", ".git"]);
  * claudemd.ts): a fresh mtime on them is the capture, not the task's work. */
 export const HUNCH_MANAGED_FILES = new Set(["CLAUDE.md", "AGENTS.md", ".cursor/rules/hunch.mdc", ".github/copilot-instructions.md", ".windsurf/rules/hunch.md"]);
 /** Commit subjects Hunch writes itself. */
-const HUNCH_COMMIT_SUBJECT = /^hunch:/i;
+export const HUNCH_COMMIT_SUBJECT = /^hunch:/i;
 function gitDate(ms) {
     // Second resolution, a format every git accepts.
     return `${new Date(ms).toISOString().slice(0, 19).replace("T", " ")} +0000`;

package/dist/extractors/git.d.ts

@@ -125,7 +125,11 @@ export declare function headFileContent(root: string, rel: string): string | nul
  *  machines' memory. Never throws; leaves a clean tree. Serialized with the commit lock so it
  *  can't race a concurrent flush. Returns true only when the checked-out memory HEAD moved,
  *  allowing callers to avoid rebuilding the derived SQLite index after a no-op pull. */
-export type HunchPullStatus = "updated" | "current" | "busy" | "failed" | "unconfigured";
+export type HunchPullStatus = "updated" | "current" | "busy" | "failed" | "unconfigured" | "empty";
+/** A strict guard may pass only on a pull that proved this clone's memory matches the
+ *  advertised remote: it advanced, was already current, or both are provably empty (a
+ *  brand-new shared memory repo before its first capture, #427). */
+export declare function teamPullIsFresh(status: HunchPullStatus): boolean;
 export interface PullHunchOptions {
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
@@ -298,6 +302,17 @@ export type CommitRepairStatus = "orphaned" | "current" | "unresolvable" | "unkn
  *  be treated as repair-eligible; collapsing "false" and "error" into one
  *  boolean is exactly the bug this type exists to prevent. */
 export declare function commitRepairStatus(commit: string, ref: string, cwd: string): CommitRepairStatus;
+/** commitRepairStatus against several tips: "orphaned" only when NO ref
+ *  reaches the commit. A historical `--range old..new` must not make a commit
+ *  that HEAD still reaches look orphaned just because it is newer than `new`
+ *  (#450). The first non-orphaned answer wins, so "unknown" is never upgraded. */
+export declare function commitRepairStatusAgainst(commit: string, refs: readonly string[], cwd: string): CommitRepairStatus;
+/** `git patch-id --stable` of each commit, keyed by the sha exactly as given
+ *  (full or abbreviated). Same diff flags as the workspace ledger's squash
+ *  check. A merge or empty commit, an unknown sha, or any git failure leaves
+ *  no entry: a missing patch-id is never a match. One `git log` + one
+ *  `git patch-id` process for all of them. */
+export declare function commitPatchIds(shas: readonly string[], cwd: string): Map<string, string>;
 /** Byte budget for a diff embedded in a SYNTHESIS prompt. Gates never use it: a
  *  constraint check over a prefix of a change would read every file past the
  *  cutoff as "no added lines" and pass it. */
@@ -328,8 +343,19 @@ export declare function lastCommitForFile(file: string, cwd: string): string;
 /** Full SHA of the commit that introduced a path. Unlike lastCommitForFile this
  * remains stable when lifecycle/proof updates later touch the same policy file. */
 export declare function firstCommitForFile(file: string, cwd: string): string;
-/** ISO author-date of the most recent commit touching a file ("" if none). */
-export declare function lastChangeDate(file: string, cwd: string): string;
+/** ISO author-date of the most recent commit touching a file ("" if none), as of `rev`
+ *  (default HEAD). */
+export declare function lastChangeDate(file: string, cwd: string, rev?: string): string;
+/** The revision a checked change starts from, so freshness is judged WITHOUT the change
+ *  itself: a committed change under review must not make its own guarding record stale
+ *  (#426). `--base` diffs are 3-dot, so the merge-base; `--commit` is its parent;
+ *  staged/working changes are not committed yet, so HEAD (undefined). `--commit` judges
+ *  one commit in isolation, so an earlier commit of the same branch can still age the
+ *  record; `--base` (the CI guard) judges the whole branch and is the authoritative gate. */
+export declare function checkFreshnessRevision(source: {
+    base?: string;
+    commit?: string;
+}, cwd: string): string | undefined;
 /**
  * Newest author date for every changed path selected by a bounded set of repository-relative
  * Hunch scopes. One Git history walk replaces the per-file process loop used by `staleness()`.
@@ -370,9 +396,13 @@ export declare function revExists(ref: string, cwd: string): boolean;
 /** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
  *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
 export declare function rangeFiles(base: string, cwd: string, head?: string): string[];
-/** Commit subjects on `head` since `base` (2-dot: commits added by the task),
- *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
-export declare function rangeSubjects(base: string, cwd: string, head?: string, max?: number): string[];
+/** Commits on `head` since `base` (2-dot: commits added by the task), oldest-first, each
+ *  with its subject and the files it changed, for distilling a runbook's ordered steps
+ *  (roadmap #5); `runbookDraft` uses the files to tell Hunch's own captures from the work. */
+export declare function rangeCommits(base: string, cwd: string, head?: string, max?: number): {
+    subject: string;
+    files: string[];
+}[];
 /** Complete gating diff of a PR vs `base` (3-dot: the CI Constraint Guard's surface). */
 export declare function rangeGateDiff(base: string, cwd: string, head?: string): GateDiff;
 /** The PR's unified diff vs `base` (3-dot), noise-excluded and capped at the

package/dist/extractors/git.js

@@ -1607,6 +1607,12 @@ function pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeout
         return false;
     return tryPush(hunchDir, env, timeoutMs, contract, observe);
 }
+/** A strict guard may pass only on a pull that proved this clone's memory matches the
+ *  advertised remote: it advanced, was already current, or both are provably empty (a
+ *  brand-new shared memory repo before its first capture, #427). */
+export function teamPullIsFresh(status) {
+    return status === "updated" || status === "current" || status === "empty";
+}
 export function pullHunchStatus(hunchDir, opts = {}) {
     const env = foreignRepoEnv({
         ...process.env,
@@ -1622,7 +1628,13 @@ export function pullHunchStatus(hunchDir, opts = {}) {
     try {
         const merged = mergeRemote(hunchDir, env, opts.timeoutMs ?? READ_REMOTE_TIMEOUT_MS, opts.remote, opts.allowUnrelatedHistories ?? false);
         if (merged === "failed" || merged === "unconfigured" || !contractReady(opts.remote)) {
-            return merged === "unconfigured" ? merged : "failed";
+            if (merged !== "unconfigured" || !contractReady(opts.remote))
+                return "failed";
+            // The advertised remote has no branch yet AND this clone never committed memory:
+            // both sides are empty, so there is nothing to be stale against (#427). A clone
+            // WITH memory against an empty remote stays "unconfigured" (unpublished, or the
+            // remote lost its history) so strict guards keep failing closed on it.
+            return opts.remote && !before && !headShaWithEnv(hunchDir, env) ? "empty" : merged;
         }
         return headShaWithEnv(hunchDir, env) !== before ? "updated" : "current";
     }
@@ -2612,6 +2624,51 @@ export function commitRepairStatus(commit, ref, cwd) {
         return e.status === 1 ? "orphaned" : "unknown";
     }
 }
+/** commitRepairStatus against several tips: "orphaned" only when NO ref
+ *  reaches the commit. A historical `--range old..new` must not make a commit
+ *  that HEAD still reaches look orphaned just because it is newer than `new`
+ *  (#450). The first non-orphaned answer wins, so "unknown" is never upgraded. */
+export function commitRepairStatusAgainst(commit, refs, cwd) {
+    for (const ref of new Set(refs)) {
+        const status = commitRepairStatus(commit, ref, cwd);
+        if (status !== "orphaned")
+            return status;
+    }
+    return "orphaned";
+}
+/** `git patch-id --stable` of each commit, keyed by the sha exactly as given
+ *  (full or abbreviated). Same diff flags as the workspace ledger's squash
+ *  check. A merge or empty commit, an unknown sha, or any git failure leaves
+ *  no entry: a missing patch-id is never a match. One `git log` + one
+ *  `git patch-id` process for all of them. */
+export function commitPatchIds(shas, cwd) {
+    const out = new Map();
+    // Only shas that resolve: one unknown sha (a withheld queue entry) would make `git log`
+    // fail outright and drop every patch-id. Fed on stdin, so no argv length limit applies.
+    const exists = commitsExist([...new Set(shas)], cwd);
+    const valid = exists ? [...exists] : [];
+    if (!valid.length)
+        return out;
+    let ids;
+    try {
+        const log = execFileSync("git", ["-C", cwd, "log", "--stdin", "--no-walk=unsorted", "--format=%H", "-p", "--no-merges", "--binary", "--full-index", "--no-renames", "--no-ext-diff", "--no-textconv", "--"], { input: valid.join("\n") + "\n", maxBuffer: 256 * 1024 * 1024, timeout: 30_000, stdio: ["pipe", "pipe", "ignore"] });
+        if (!log.byteLength)
+            return out;
+        ids = execFileSync("git", ["-C", cwd, "patch-id", "--stable"], { input: log, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 30_000, stdio: ["pipe", "pipe", "ignore"] });
+    }
+    catch {
+        return out;
+    }
+    for (const line of ids.split("\n")) {
+        const [patchId = "", commit = ""] = line.trim().split(/\s+/);
+        if (!/^[0-9a-f]{40,64}$/.test(patchId))
+            continue;
+        for (const sha of valid)
+            if (commit.startsWith(sha.toLowerCase()))
+                out.set(sha, patchId);
+    }
+    return out;
+}
 /** Machine-generated paths that carry no design "why" — lockfiles, build output,
  *  vendored deps, snapshots, source maps. Excluded from synthesis diffs via git
  *  pathspec BEFORE git assembles/orders the patch: a huge lockfile sorts ahead of
@@ -2713,9 +2770,23 @@ export function firstCommitForFile(file, cwd) {
         return added;
     return gitSafe(["log", "--reverse", "--format=%H", "--", file], cwd).split("\n").find(Boolean) ?? "";
 }
-/** ISO author-date of the most recent commit touching a file ("" if none). */
-export function lastChangeDate(file, cwd) {
-    return gitSafe(["log", "-1", "--format=%aI", "--", file], cwd);
+/** ISO author-date of the most recent commit touching a file ("" if none), as of `rev`
+ *  (default HEAD). */
+export function lastChangeDate(file, cwd, rev) {
+    return gitSafe(["log", "-1", "--format=%aI", ...(rev ? [rev] : []), "--", file], cwd);
+}
+/** The revision a checked change starts from, so freshness is judged WITHOUT the change
+ *  itself: a committed change under review must not make its own guarding record stale
+ *  (#426). `--base` diffs are 3-dot, so the merge-base; `--commit` is its parent;
+ *  staged/working changes are not committed yet, so HEAD (undefined). `--commit` judges
+ *  one commit in isolation, so an earlier commit of the same branch can still age the
+ *  record; `--base` (the CI guard) judges the whole branch and is the authoritative gate. */
+export function checkFreshnessRevision(source, cwd) {
+    if (source.commit)
+        return `${source.commit}^`;
+    if (source.base)
+        return gitSafe(["merge-base", source.base, "HEAD"], cwd) || source.base;
+    return undefined;
 }
 /**
  * Newest author date for every changed path selected by a bounded set of repository-relative
@@ -2841,11 +2912,17 @@ export function revExists(ref, cwd) {
 export function rangeFiles(base, cwd, head = "HEAD") {
     return nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMR", `${base}...${head}`], cwd));
 }
-/** Commit subjects on `head` since `base` (2-dot: commits added by the task),
- *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
-export function rangeSubjects(base, cwd, head = "HEAD", max = 50) {
-    const out = gitSafe(["log", "--reverse", `-n${max}`, "--format=%s", `${base}..${head}`], cwd);
-    return out ? out.split("\n").filter(Boolean) : [];
+/** Commits on `head` since `base` (2-dot: commits added by the task), oldest-first, each
+ *  with its subject and the files it changed, for distilling a runbook's ordered steps
+ *  (roadmap #5); `runbookDraft` uses the files to tell Hunch's own captures from the work. */
+export function rangeCommits(base, cwd, head = "HEAD", max = 50) {
+    const out = gitSafe(["-c", "core.quotePath=false", "log", "--reverse", `-n${max}`, "--format=%x1e%s", "--name-only", `${base}..${head}`], cwd);
+    if (!out)
+        return [];
+    return out.split("\x1e").filter(Boolean).map((block) => {
+        const [subject = "", ...files] = block.split("\n");
+        return { subject: subject.trim(), files: files.map((f) => f.trim()).filter(Boolean) };
+    });
 }
 /** Complete gating diff of a PR vs `base` (3-dot: the CI Constraint Guard's surface). */
 export function rangeGateDiff(base, cwd, head = "HEAD") {

package/dist/extractors/indexer.js

@@ -13,7 +13,7 @@ import { dirname, join, posix } from "node:path";
 import { parseSource, attributeCalls, attributeRelations, MAX_BODY_TEXT_CHARS } from "./parse.js";
 import { isParserLoadError } from "./nativeTreeSitter.js";
 import { extractHelmDirectives } from "./helm.js";
-import { extractK8sManifest, namespacesCompatible } from "./k8sManifest.js";
+import { extractK8sManifest, extractKustomization, isKustomizationFile, kustomizeNamespaces, namespacesCompatible } from "./k8sManifest.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
@@ -143,9 +143,25 @@ export function scanRepo(store, root, opts = {}) {
     }
     const gitMeta = useGit ? fileGitMetrics(root, rels, opts.churn === false ? 0 : 90) : null;
     let skipped = 0;
+    // Kustomize namespace transformers must be known before any manifest is
+    // extracted, so kustomization files are read up front (their reads are
+    // reused by the main loop below, not repeated).
+    const preRead = new Map();
+    const kustomizations = new Map();
     for (const file of files) {
-        const rel = file.path;
+        if (!isKustomizationFile(file.path))
+            continue;
         const read = file.read();
+        preRead.set(file.path, read);
+        if (!read.absent && read.source !== null) {
+            const dir = posix.dirname(file.path);
+            kustomizations.set(dir === "." ? "" : dir, extractKustomization(read.source));
+        }
+    }
+    const kustomizeNamespaceFor = kustomizeNamespaces(kustomizations, new Set(rels));
+    for (const file of files) {
+        const rel = file.path;
+        const read = preRead.get(rel) ?? file.read();
         if (read.absent) {
             sourceFingerprint.push({ path: rel, mode: read.mode, content: "absent" });
             continue;
@@ -227,20 +243,41 @@ export function scanRepo(store, root, opts = {}) {
         // otherwise be indistinguishable by offset alone, and the wrong (Helm)
         // symbol id could get recorded instead of the K8s one.
         const k8sSymbolObjects = new Set();
+        // Identity name a K8s symbol's id is derived from when its kind/name is
+        // NOT unique in this file (issue #382). Absent for the common unique case,
+        // so that id is exactly what it always was; a same-kind/name pair in
+        // different namespaces gets kind/name@namespace for EVERY member, never a
+        // document-order ordinal, so reordering documents can't rename them. The
+        // file path is already in every symbol id, so the same resource repeated
+        // across overlay dirs is distinct by path without any extra disambiguator.
+        const k8sIdNames = new Map();
         if (languageFor(rel)?.id === "yaml") {
-            k8sDocs = extractK8sManifest(src);
-            const k8sSymbols = k8sDocs
-                .filter((d) => d.resource !== null)
+            k8sDocs = kustomizeNamespaceFor.has(rel)
+                ? extractK8sManifest(src, { namespace: kustomizeNamespaceFor.get(rel) })
+                : extractK8sManifest(src);
+            const resourceDocs = k8sDocs
+                .filter((d) => d.resource !== null);
+            const nameCounts = new Map();
+            for (const d of resourceDocs) {
+                const name = `${d.resource.kind}/${displayNameText(d.resource.name)}`;
+                nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
+            }
+            const k8sSymbols = resourceDocs
                 // k8sManifest.ts's own offsets are named *Char; mapped here into the
                 // shared startByte/endByte fields, same as the Helm merge above.
-                .map((d) => ({
-                name: `${d.resource.kind}/${displayNameText(d.resource.name)}`,
-                kind: "variable",
-                startByte: d.resource.startChar,
-                endByte: d.resource.endChar,
-                loc: src.slice(d.resource.startChar, d.resource.endChar).split("\n").length,
-                bodyText: src.slice(d.resource.startChar, d.resource.endChar).slice(0, MAX_BODY_TEXT_CHARS),
-            }));
+                .map((d) => {
+                const sym = {
+                    name: `${d.resource.kind}/${displayNameText(d.resource.name)}`,
+                    kind: "variable",
+                    startByte: d.resource.startChar,
+                    endByte: d.resource.endChar,
+                    loc: src.slice(d.resource.startChar, d.resource.endChar).split("\n").length,
+                    bodyText: src.slice(d.resource.startChar, d.resource.endChar).slice(0, MAX_BODY_TEXT_CHARS),
+                };
+                if ((nameCounts.get(sym.name) ?? 0) > 1)
+                    k8sIdNames.set(sym, `${sym.name}@${d.resource.namespace ?? ""}`);
+                return sym;
+            });
             for (const s of k8sSymbols)
                 k8sSymbolObjects.add(s);
             parsed.symbols = [...parsed.symbols, ...k8sSymbols].sort((a, b) => a.startByte - b.startByte);
@@ -253,10 +290,12 @@ export function scanRepo(store, root, opts = {}) {
         const idCounts = new Map(); // disambiguate same (file,name,kind)
         const k8sSymbolIdByStartByte = new Map();
         for (const [index, ps] of parsed.symbols.entries()) {
-            const base = symbolId(rel, ps.name, ps.kind);
+            const base = symbolId(rel, k8sIdNames.get(ps) ?? ps.name, ps.kind);
             const n = idCounts.get(base) ?? 0;
             idCounts.set(base, n + 1);
             // parse() returns symbols sorted by start byte, so the ordinal is stable
+            // (for K8s resources it is only reached by two documents with the SAME
+            // kind, namespace and name in one file -- indistinguishable by identity)
             const id = n === 0 ? base : `${base}_${n}`;
             idsInFile.push(id);
             symbolIndexId.set(index, id);

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;

package/dist/integrations/gitignore.d.ts

@@ -39,3 +39,10 @@ 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[];
+/** `.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

@@ -231,4 +231,22 @@ export function describeGitignoreUpgrade(upgrade) {
     }
     return out;
 }
+/** `.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