@holmes-lab/holmes-kit 0.25.1 → 0.26.1

package/dist/holmes/rtm/rtm-builder.js

@@ -46,6 +46,7 @@ exports.addDecisionEdges = addDecisionEdges;
 const path = __importStar(require("node:path"));
 const fs = __importStar(require("node:fs"));
 const language_capability_1 = require("../cpg/language-capability");
+const import_resolver_1 = require("../cpg/import-resolver");
 /**
  * @implements A-SPEC-281
  * Build one fact's provenance from the shared observation context plus what this call site knows.
@@ -429,146 +430,10 @@ function fsReadGoMod(p) {
     }
 }
 function addImportEdges(scanned, graph, opts) {
-    const known = new Set(scanned.map((f) => f.sourcePath));
-    const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx', '.py',
-        '/index.ts', '/index.js', '/__init__.py'];
-    const firstKnown = (base) => EXTENSIONS.map((ext) => `${base}${ext}`).find((candidate) => known.has(candidate)) ?? null;
-    // @implements A-SPEC-525.1 — the five languages' resolution rules, selected by the IMPORTING
-    // file's extension because resolution IS per-language semantics. The founding rule is unchanged
-    // everywhere: resolve only to files the scan actually contains; the ambiguous resolve to none.
-    const knownList = [...known];
-    const uniqueSuffix = (suffix) => {
-        const hits = knownList.filter((k) => k === suffix || k.endsWith(`/${suffix}`));
-        return hits.length === 1 ? hits[0] : null; // two files may not become a guess
-    };
-    // go.mod discovery: injected via opts when the caller knows it; otherwise walked up from the
-    // first Go file's ABSOLUTE path (bounded), so production builds resolve without extra wiring.
-    let goModCache;
-    const goModuleOf = () => {
-        if (opts?.goModule)
-            return opts.goModule;
-        if (goModCache !== undefined)
-            return goModCache ?? undefined;
-        goModCache = null;
-        const anyGo = scanned.find((f) => /\.go$/.test(f.sourcePath) && f.path);
-        if (anyGo) {
-            let dir = path.dirname(anyGo.path);
-            for (let hops = 0; hops < 12; hops++) {
-                try {
-                    const txt = fsReadGoMod(path.join(dir, 'go.mod'));
-                    if (txt !== null) {
-                        goModCache = txt;
-                        break;
-                    }
-                }
-                catch { /* keep walking */ }
-                const up = path.dirname(dir);
-                if (up === dir)
-                    break;
-                dir = up;
-            }
-        }
-        return goModCache ?? undefined;
-    };
-    const goPackage = (spec) => {
-        const mod = goModuleOf();
-        if (!mod || !(spec === mod || spec.startsWith(`${mod}/`)))
-            return []; // external, honestly
-        const dir = spec === mod ? '' : spec.slice(mod.length + 1);
-        const prefix = dir === '' ? '' : `${dir}/`;
-        return knownList.filter((k) => k.startsWith(prefix) && k.endsWith('.go')
-            && !k.endsWith('_test.go') && !k.slice(prefix.length).includes('/'));
-    };
-    const rustResolve = (fromFile, spec) => {
-        const segs = spec.split('::');
-        const head = segs.shift();
-        let baseDir;
-        if (head === 'crate') {
-            // the crate root is the src/ directory nearest above the importing file
-            const m = fromFile.match(/^(.*?src)\//);
-            baseDir = m ? m[1] : 'src';
-        }
-        else if (head === 'super') {
-            baseDir = path.posix.dirname(path.posix.dirname(fromFile));
-            while (segs[0] === 'super') {
-                // @implements A-SPEC-527.1 — super:: above the crate root is an rustc error; resolving
-                // it pinned '.' and produced edges to repo-root files (adversarial sweep). Refuse.
-                if (baseDir === '.' || baseDir === '/')
-                    return null;
-                segs.shift();
-                baseDir = path.posix.dirname(baseDir);
-            }
-        }
-        else if (head === 'self') {
-            baseDir = path.posix.dirname(fromFile);
-        }
-        else {
-            return null; // external crate
-        }
-        const tryPath = (parts) => {
-            if (parts.length === 0)
-                return null;
-            const base = path.posix.normalize(path.posix.join(baseDir, ...parts));
-            if (known.has(`${base}.rs`))
-                return `${base}.rs`;
-            if (known.has(`${base}/mod.rs`))
-                return `${base}/mod.rs`;
-            return null;
-        };
-        // the last segment may be an ITEM, not a module — drop it once and retry
-        return tryPath(segs) ?? tryPath(segs.slice(0, -1));
-    };
-    const resolve = (fromFile, spec) => {
-        // @implements A-SPEC-525.1 — language branches BEFORE the JS/Python-shaped fallthrough.
-        if (/\.go$/.test(fromFile))
-            return null; // Go fans out separately (a package is its files)
-        if (/\.rs$/.test(fromFile))
-            return rustResolve(fromFile, spec);
-        if (/\.java$/.test(fromFile))
-            return uniqueSuffix(`${spec.split('.').join('/')}.java`);
-        if (/\.cs$/.test(fromFile))
-            return uniqueSuffix(`${spec.split('.').join('/')}.cs`);
-        if (/\.(cpp|cc|cxx|hpp|h)$/.test(fromFile)) {
-            // @implements A-SPEC-527.1 — an ABSOLUTE include is not a repository coordinate: joining
-            // it into the repo frame let `#include "/etc/passwd"` match a coincidentally-shaped
-            // scanned file (adversarial sweep). Absolute means absolute; it resolves to nothing here.
-            if (spec.startsWith('/'))
-                return null;
-            // extension preserved: the dotted split below would butcher `util/env.h`
-            const relative = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec));
-            if (known.has(relative))
-                return relative;
-            return known.has(spec) ? spec : null; // repo-root-relative include
-        }
-        // @implements A-SPEC-406
-        // A specifier without a leading dot used to be refused outright, on the ground that it names an
-        // external package. That holds for `node:fs` and `js-yaml`; it does NOT hold for Python, which
-        // writes intra-repository modules absolutely — `from src.core.memory_audit import X`. Measured
-        // on the jarvis corpus: 1060 specifiers, 0 relative, 542 naming a file the scan already had, and
-        // 0 import edges in the graph. The whole import layer was missing for that language because the
-        // resolver's shape was JS's.
-        //
-        // The rule the original was written under is unchanged and is what makes this safe: resolve
-        // ONLY to a file the scan actually contains. `os.path` becomes `os/path.py`, which is in no
-        // scan, so it still emits nothing. Nothing is invented; the dotted form is simply also read.
-        if (!spec.startsWith('.')) {
-            if (spec.includes(':'))
-                return null; // `node:fs` and friends are never a repository path
-            return firstKnown(path.posix.normalize(spec.split('.').filter(Boolean).join('/')));
-        }
-        // @implements A-SPEC-289
-        // Python writes a relative import as `.b` / `..pkg.mod`, where the leading dots are LEVELS and
-        // the remaining dots are path separators — not the `./b` form JS uses. Treating `.b` as a path
-        // yields the literal name `.b`, which matches nothing. Detected by the absence of a slash: a
-        // specifier that already contains one is a JS-style path and is left alone.
-        let relative = spec;
-        if (!spec.includes('/')) {
-            const dots = spec.match(/^\.+/)[0].length;
-            const rest = spec.slice(dots).split('.').filter(Boolean).join('/');
-            relative = `${'../'.repeat(Math.max(0, dots - 1)) || './'}${rest}`;
-        }
-        return firstKnown(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), relative)));
-    };
+    // @implements A-SPEC-688 — the resolution rules moved to `cpg/import-resolver` so the cycle
+    // ratchet consumes the SAME code instead of re-deriving a weaker copy. The rules themselves are
+    // unchanged; this call is where they used to be spelled out.
+    const { resolve, fanOut } = (0, import_resolver_1.createImportResolver)(scanned, { goModule: opts?.goModule });
     graph.transaction(() => {
         for (const f of scanned) {
             for (const e of f.edges ?? []) {
@@ -578,7 +443,7 @@ function addImportEdges(scanned, graph, opts) {
                 // language's semantics, not an invention), so one specifier fans out to each scanned
                 // file of the package directory.
                 if (/\.go$/.test(f.sourcePath)) {
-                    for (const target of goPackage(e.to)) {
+                    for (const target of fanOut(f.sourcePath, e.to)) {
                         graph.addNode(`FILE:${f.sourcePath}`, 'FILE', f.sourcePath, fact(opts, f.sourcePath, 'ast-scan', 1));
                         graph.addNode(`FILE:${target}`, 'FILE', target, fact(opts, target, 'ast-scan', 1));
                         graph.addEdge(`FILE:${f.sourcePath}`, `FILE:${target}`, 'imports', f.sourcePath, fact(opts, `${f.sourcePath} -> ${e.to}`, 'import-resolution', 1));

package/dist/holmes/spec/id-collision.d.ts

@@ -1,3 +1,4 @@
+import type { Spec } from './spec-parser';
 /**
  * Distributed id-preemption detection (REQ-254): two disconnected workspaces each see the same local
  * max and issue the same spec number, and the collision is silent at create AND at push — the
@@ -37,3 +38,100 @@ export interface IdCollisionIssue {
     detail: string;
 }
 export declare function detectIdCollisions(entries: IdCollisionEntry[]): IdCollisionIssue[];
+/**
+ * Which colliding number moves, and where to.
+ *
+ * `detectIdCollisions` above (REQ-254) says a number is claimed twice; `spec_renumber` (REQ-255)
+ * can move a family. Nothing joined them, so doctor's advice still reads "renumber one (manual
+ * until REQ-255)" — stale, since REQ-255 shipped — and the decision fell to a person every time.
+ * Measured 2026-09-20: two machines each allocated REQ-694, and recovering it by hand cost a
+ * rebuilt slice and five out-of-band approvals.
+ *
+ * This is the rule, not the execution: it consumes the detector's issues and returns destinations.
+ * Applying them stays with `spec_renumber`, so adopting the entity store later swaps the engine
+ * without touching this.
+ */
+export interface ReconcileMove {
+    from: string;
+    to: string;
+    reason: string;
+}
+export interface ReconcileBlock {
+    base: string;
+    reason: string;
+}
+export interface ReconcilePlan {
+    moves: ReconcileMove[];
+    unresolved: ReconcileBlock[];
+}
+export interface ReconcileInput {
+    /** Output of `detectIdCollisions`; entries that are not `id-collision` are ignored. */
+    issues: readonly IdCollisionIssue[];
+    /** Every base this checkout holds. */
+    localBases: ReadonlySet<string>;
+    /** Every base the remote-tracking refs hold. */
+    remoteBases: ReadonlySet<string>;
+    /**
+     * The bases of THIS CHECKOUT that are already on the remote — not "what the remote holds".
+     *
+     * A colliding base is by definition published on the remote side, so the only open question is
+     * whether the LOCAL one is too. This input was first called `pushedBases` ("bases already
+     * published"), which reads as the remote's set; a caller filling it that way puts every collision
+     * in it and receives an empty plan, silently. A contract that makes the natural caller wrong is the
+     * defect, so the name now says whose publication it means. A base in here must not move — a public
+     * number may already be cited — and the plan says so instead of choosing.
+     */
+    localPublishedBases: ReadonlySet<string>;
+}
+/** "REQ-694" -> "694"; "T-SPEC-700.1" -> "700"; anything else has no base. */
+export declare function baseOfSpecId(id: string): string | undefined;
+export declare function planIdReconcile(input: ReconcileInput): ReconcilePlan;
+/**
+ * The collision identity of one spec document: the WHOLE BODY, canonicalised.
+ *
+ * Moved here from doctor's collection layer, unchanged, because a second collector now needs it —
+ * the one that reads remote-tracking refs. Two copies of an identity function is how the same
+ * document comes to have two keys, and then every shared spec reads as a collision.
+ *
+ * What it hashes is the record of three adversarial rounds (see doctor.ts): not a composite of
+ * parser splits (each split blind spot leaked, one at a time), but everything after the frontmatter
+ * with CRLF folded by the caller, per-line trailing whitespace and blank lines dropped, plus the
+ * substantive frontmatter (type, title, sorted depends_on) through JSON array serialisation so no
+ * field can alias another. The SEAL digest is a separate signal and is not part of this key.
+ *
+ * `folded` must already be CRLF-folded — both collectors fold exactly where they read.
+ */
+export declare function collisionKeyOf(folded: string, spec: Spec): string;
+/**
+ * The planner's inputs, derived from what the two collectors already know.
+ *
+ * `planIdReconcile` shipped with no caller. This is the first half of giving it one; it stays pure
+ * (entries in, sets out) so the rule it feeds remains assertable without a repository.
+ *
+ * THE ONE DECISION HERE is what "published" means for a LOCAL base. It cannot be "the path exists on
+ * the remote": a spec's path is derived from its number, so a colliding number has that path on the
+ * remote by definition, and reading it that way marks every collision as published on both sides —
+ * the exact misreading `localPublishedBases` was renamed to prevent (A-SPEC-700). A local document
+ * is published when some remote ref holds the SAME CONTENT at the same path.
+ */
+export declare function reconcileInputsFrom(input: {
+    issues: readonly IdCollisionIssue[];
+    /** Every local entry — all of them claim a number, whether or not they were added recently. */
+    local: readonly IdCollisionEntry[];
+    /** The local entries that were not present at a merge-base. */
+    addedLocally: readonly IdCollisionEntry[];
+    /** `collectRemoteAddedSpecs` output: `entries[].file` is `<ref>:<store-relative path>`. */
+    remote: {
+        entries: readonly IdCollisionEntry[];
+        baseFiles: ReadonlySet<string>;
+    };
+}): ReconcileInput;
+/**
+ * The plan, worded for the person who has to act on it. Empty plan → empty string, so the caller
+ * can tell "nothing to say" apart and fall back to a general sentence.
+ *
+ * The engine's name appears HERE and nowhere in the planner: `planIdReconcile` says what moves
+ * where, and only this sentence says with what — so swapping `spec_renumber` for `entity_renumber`
+ * after adoption is a one-line change to wording, not to the rule.
+ */
+export declare function reconcileAdvice(plan: ReconcilePlan): string;

package/dist/holmes/spec/id-collision.js

@@ -1,7 +1,46 @@
 "use strict";
-// @implements A-SPEC-254.1
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectIdCollisions = detectIdCollisions;
+exports.baseOfSpecId = baseOfSpecId;
+exports.planIdReconcile = planIdReconcile;
+exports.collisionKeyOf = collisionKeyOf;
+exports.reconcileInputsFrom = reconcileInputsFrom;
+exports.reconcileAdvice = reconcileAdvice;
+// @implements A-SPEC-254.1
+const crypto = __importStar(require("node:crypto"));
 // Only A-SPEC and T-SPEC may carry dot sub-numbers (the engine enforces this), so only they can
 // have a bare/dotted family split. REQ/H-SPEC ids are structurally exempt.
 const DOTTED = /^([AT]-SPEC-\d+)\.\d+$/;
@@ -84,3 +123,112 @@ function detectIdCollisions(entries) {
     }
     return issues.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.kind < b.kind ? -1 : 1));
 }
+/** "REQ-694" -> "694"; "T-SPEC-700.1" -> "700"; anything else has no base. */
+function baseOfSpecId(id) {
+    return /-(\d{3,})(?:\.\d+)?$/.exec(id)?.[1];
+}
+function planIdReconcile(input) {
+    const { issues, localBases, remoteBases, localPublishedBases } = input;
+    const bases = new Set();
+    for (const issue of issues) {
+        if (issue.kind !== 'id-collision')
+            continue;
+        const base = baseOfSpecId(issue.id);
+        if (base !== undefined)
+            bases.add(base);
+    }
+    const moves = [];
+    const unresolved = [];
+    // Destinations must clear BOTH sides, and each other: choosing from the local maximum alone walks
+    // straight into the next merge, and two collisions resolved in one pass must not land together.
+    const taken = new Set([...localBases, ...remoteBases]);
+    for (const base of [...bases].sort((a, b) => Number(a) - Number(b))) {
+        if (localPublishedBases.has(base)) {
+            unresolved.push({ base, reason: 'both sides are published; a person has to choose which one moves' });
+            continue;
+        }
+        let candidate = Number(base) + 1;
+        while (taken.has(String(candidate)))
+            candidate++;
+        const to = String(candidate);
+        taken.add(to);
+        moves.push({ from: base, to, reason: 'local base is not published yet' });
+    }
+    return { moves, unresolved };
+}
+// @implements A-SPEC-254.2
+/**
+ * The collision identity of one spec document: the WHOLE BODY, canonicalised.
+ *
+ * Moved here from doctor's collection layer, unchanged, because a second collector now needs it —
+ * the one that reads remote-tracking refs. Two copies of an identity function is how the same
+ * document comes to have two keys, and then every shared spec reads as a collision.
+ *
+ * What it hashes is the record of three adversarial rounds (see doctor.ts): not a composite of
+ * parser splits (each split blind spot leaked, one at a time), but everything after the frontmatter
+ * with CRLF folded by the caller, per-line trailing whitespace and blank lines dropped, plus the
+ * substantive frontmatter (type, title, sorted depends_on) through JSON array serialisation so no
+ * field can alias another. The SEAL digest is a separate signal and is not part of this key.
+ *
+ * `folded` must already be CRLF-folded — both collectors fold exactly where they read.
+ */
+function collisionKeyOf(folded, spec) {
+    const fence = /^---\n[\s\S]*?\n---\n?/.exec(folded);
+    const body = (fence ? folded.slice(fence[0].length) : folded)
+        .split('\n').map((l) => l.trimEnd()).filter((l) => l !== '').join('\n');
+    return 'sha256:' + crypto.createHash('sha256')
+        .update(JSON.stringify([spec.type, spec.title, [...spec.dependsOn].sort(), body])).digest('hex');
+}
+// @implements A-SPEC-700.1
+/**
+ * The planner's inputs, derived from what the two collectors already know.
+ *
+ * `planIdReconcile` shipped with no caller. This is the first half of giving it one; it stays pure
+ * (entries in, sets out) so the rule it feeds remains assertable without a repository.
+ *
+ * THE ONE DECISION HERE is what "published" means for a LOCAL base. It cannot be "the path exists on
+ * the remote": a spec's path is derived from its number, so a colliding number has that path on the
+ * remote by definition, and reading it that way marks every collision as published on both sides —
+ * the exact misreading `localPublishedBases` was renamed to prevent (A-SPEC-700). A local document
+ * is published when some remote ref holds the SAME CONTENT at the same path.
+ */
+function reconcileInputsFrom(input) {
+    const basesOf = (ids) => {
+        const out = new Set();
+        for (const id of ids) {
+            const b = baseOfSpecId(id);
+            if (b !== undefined)
+                out.add(b);
+        }
+        return out;
+    };
+    // A store-relative path names its spec id: `01_req/REQ-900.md` → `REQ-900`.
+    const idOfPath = (file) => file.slice(file.lastIndexOf('/') + 1).replace(/\.md$/, '');
+    const remotePathOf = (file) => file.slice(file.indexOf(':') + 1);
+    const remoteKeys = new Set(input.remote.entries.map((e) => `${remotePathOf(e.file)}\u0000${e.contentDigest}`));
+    const published = input.addedLocally.filter((e) => remoteKeys.has(`${e.file}\u0000${e.contentDigest}`));
+    return {
+        issues: input.issues,
+        localBases: basesOf(input.local.map((e) => e.id)),
+        remoteBases: basesOf([...[...input.remote.baseFiles].map(idOfPath), ...input.remote.entries.map((e) => e.id)]),
+        localPublishedBases: basesOf(published.map((e) => e.id)),
+    };
+}
+// @implements A-SPEC-700.1
+/**
+ * The plan, worded for the person who has to act on it. Empty plan → empty string, so the caller
+ * can tell "nothing to say" apart and fall back to a general sentence.
+ *
+ * The engine's name appears HERE and nowhere in the planner: `planIdReconcile` says what moves
+ * where, and only this sentence says with what — so swapping `spec_renumber` for `entity_renumber`
+ * after adoption is a one-line change to wording, not to the rule.
+ */
+function reconcileAdvice(plan) {
+    const parts = [
+        ...plan.moves.map((m) => `move ${m.from} → ${m.to}: spec_renumber(oldBase=${m.from}, newBase=${m.to})`),
+        ...plan.unresolved.map((u) => `${u.base}: both sides are published — a person has to choose which one moves`),
+    ];
+    if (parts.length === 0)
+        return '';
+    return parts.join('; ') + (plan.moves.length > 0 ? '; then re-seal with spec_approve, and merge' : '');
+}

package/dist/holmes/spec/remote-spec-refs.d.ts

@@ -0,0 +1,16 @@
+import { type IdCollisionEntry } from './id-collision';
+export interface RemoteAddedSpecs {
+    /** The remote-tracking refs that were compared — a PASS must be able to name what it looked at. */
+    refs: string[];
+    /** Documents each ref added since the merge-base, `file` spelled `<ref>:<store-relative path>`. */
+    entries: IdCollisionEntry[];
+    /** Store-relative spec paths already present at a merge-base: local files NOT in here are "added locally". */
+    baseFiles: Set<string>;
+    /** Blobs and refs that could not be read — a reduced scope is said, never hidden. */
+    skipped: number;
+    /** Why nothing was compared (no git, no remote-tracking ref). An answer, not a refusal (REQ-128). */
+    unavailable?: string;
+}
+/** Runs one git command and returns its stdout as a Buffer. Injectable so a failure can be staged. */
+export type GitRunner = (root: string, args: string[], input?: string) => Buffer;
+export declare function collectRemoteAddedSpecs(root: string, git?: GitRunner): RemoteAddedSpecs;

package/dist/holmes/spec/remote-spec-refs.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectRemoteAddedSpecs = collectRemoteAddedSpecs;
+// @implements A-SPEC-254.2
+/**
+ * The merge-time half of REQ-254: which spec documents did each remote-tracking ref ADD since this
+ * checkout and that ref parted?
+ *
+ * `detectIdCollisions` shipped with doctor walking `.ax/specs` alone, so a number another machine
+ * took stayed invisible until git refused the push. Measured 2026-09-20: the Mac Studio committed
+ * REQ-694 at 11:05, a Windows checkout allocated REQ-694 at 11:18, neither could see the other, and
+ * it surfaced as an add/add conflict on `.ax/specs/01_req/REQ-694.md`. What was missing was
+ * collection, not judgement — so this module collects and judges nothing.
+ *
+ * WHY "ADDED SINCE THE MERGE-BASE" AND NOT "SAME ID, DIFFERENT CONTENT". The same spec edited on one
+ * side (a re-seal after a correction, a body that was expanded) is ordinary divergence, and calling
+ * it a collision would cry wolf before every pull. A collision is two sides taking the same NEW
+ * number without seeing each other. A spec's path is derived from its number, so that set is exactly
+ * what git would report as an add/add conflict — asked before the merge instead of after it.
+ *
+ * NO NETWORK. Remote-tracking refs are read as they stand; `fetch` is the caller's business.
+ * Detection tied to the network cannot prepare a merge offline (REQ-254: local-first).
+ *
+ * READ-ONLY. The only git subcommands are for-each-ref, merge-base, diff, ls-tree and cat-file.
+ */
+const node_child_process_1 = require("node:child_process");
+const spec_parser_1 = require("./spec-parser");
+const id_collision_1 = require("./id-collision");
+const root_1 = require("../project/root");
+const SPECS = '.ax/specs';
+const defaultGit = (root, args, input) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], {
+    input, stdio: ['pipe', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(process.env), maxBuffer: 256 * 1024 * 1024,
+});
+const lines = (buf) => buf.toString('utf8').split('\n').map((l) => l.trim()).filter((l) => l !== '');
+const storeRelative = (repoPath) => repoPath.slice(SPECS.length + 1);
+/**
+ * Parse `git cat-file --batch` output: `<sha> <type> <size>\n<bytes>\n` per object, or
+ * `<name> missing\n`. Sizes are BYTES, so this walks the Buffer — a string walk would drift on the
+ * first multi-byte character, and these documents are mostly Korean.
+ */
+function readBatch(out, count) {
+    const blobs = [];
+    let at = 0;
+    for (let i = 0; i < count && at < out.length; i++) {
+        const eol = out.indexOf(0x0a, at);
+        if (eol === -1)
+            break;
+        const header = out.subarray(at, eol).toString('utf8');
+        at = eol + 1;
+        if (header.endsWith(' missing')) {
+            blobs.push(null);
+            continue;
+        }
+        const size = Number(header.split(' ')[2]);
+        if (!Number.isFinite(size)) {
+            blobs.push(null);
+            continue;
+        }
+        blobs.push(out.subarray(at, at + size));
+        at += size + 1;
+    }
+    while (blobs.length < count)
+        blobs.push(null);
+    return blobs;
+}
+function collectRemoteAddedSpecs(root, git = defaultGit) {
+    const result = { refs: [], entries: [], baseFiles: new Set(), skipped: 0 };
+    // `--show-prefix` also tells us where the workspace sits inside the repository. A workspace that is
+    // not the repository root would need its paths re-based; that shape is reported, not guessed at.
+    let prefix;
+    try {
+        prefix = git(root, ['rev-parse', '--show-prefix']).toString('utf8').trim();
+    }
+    catch {
+        result.unavailable = 'not a git repository — nothing to compare against';
+        return result;
+    }
+    if (prefix !== '') {
+        result.unavailable = 'the workspace is not the repository root — nothing to compare against';
+        return result;
+    }
+    // `%(symref)` is non-empty for origin/HEAD: a symbolic ref names another ref, and counting it
+    // would read every document twice and inflate the ref count a PASS reports.
+    const refs = lines(git(root, ['for-each-ref', '--format=%(refname:short)%09%(symref)', 'refs/remotes']))
+        .map((l) => l.split('\t')).filter(([, symref]) => !symref).map(([name]) => name).sort();
+    if (refs.length === 0) {
+        result.unavailable = 'no remote-tracking refs — nothing to compare against';
+        return result;
+    }
+    const seenBlob = new Set();
+    for (const ref of refs) {
+        let base;
+        try {
+            base = git(root, ['merge-base', 'HEAD', ref]).toString('utf8').trim();
+        }
+        catch {
+            result.skipped++;
+            continue;
+        } // unrelated history, or no HEAD yet
+        if (base === '') {
+            result.skipped++;
+            continue;
+        }
+        result.refs.push(ref);
+        for (const p of lines(git(root, ['ls-tree', '-r', '--name-only', base, '--', SPECS]))) {
+            if (p.endsWith('.md'))
+                result.baseFiles.add(storeRelative(p));
+        }
+        const added = lines(git(root, ['diff', '--name-only', '--diff-filter=A', '--no-renames', base, ref, '--', SPECS]))
+            .filter((p) => p.endsWith('.md'));
+        if (added.length === 0)
+            continue;
+        // ONE process per ref, not one per document.
+        const blobs = readBatch(git(root, ['cat-file', '--batch'], added.map((p) => `${ref}:${p}`).join('\n') + '\n'), added.length);
+        added.forEach((repoPath, i) => {
+            const blob = blobs[i];
+            if (blob === null) {
+                result.skipped++;
+                return;
+            }
+            try {
+                // Folded exactly where doctor's local walker folds (BOM stripped, CRLF → LF), so a CRLF
+                // working-tree copy and the LF blob of the same document get the same key.
+                const folded = blob.toString('utf8').replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+                const spec = (0, spec_parser_1.parseSpec)(folded);
+                if (!spec.id) {
+                    result.skipped++;
+                    return;
+                }
+                const contentDigest = (0, id_collision_1.collisionKeyOf)(folded, spec);
+                const dedupe = `${repoPath}\u0000${contentDigest}`;
+                if (seenBlob.has(dedupe))
+                    return; // the same document reached through two refs
+                seenBlob.add(dedupe);
+                result.entries.push({
+                    file: `${ref}:${storeRelative(repoPath)}`,
+                    id: spec.id,
+                    approvedDigest: typeof spec.frontmatter.approved_digest === 'string' ? spec.frontmatter.approved_digest : undefined,
+                    contentDigest,
+                });
+            }
+            catch {
+                result.skipped++;
+            }
+        });
+    }
+    return result;
+}

package/dist/holmes/spec/renumber.d.ts

@@ -126,5 +126,15 @@ export declare function readSourcesForRenumber(projectRoot: string): {
     file: string;
     text: string;
 }[];
-/** Spec documents as the planner needs them, with store-relative POSIX paths. */
-export declare function readSpecsForRenumber(specsRoot: string): RenumberSpec[];
+/**
+ * Spec documents as the planner needs them, with store-relative POSIX paths.
+ *
+ * @implements A-SPEC-699 — `unreadable` exists because the absence of it cost a day. A `.md` whose
+ * frontmatter would not parse used to be skipped by a bare `continue`, so "this store holds no
+ * specs" and "I could not read any of these specs" reached the caller as the same answer. They are
+ * different facts and the caller has to be able to tell them apart.
+ */
+export declare function readSpecsForRenumber(specsRoot: string): {
+    specs: RenumberSpec[];
+    unreadable: string[];
+};