@holmes-lab/holmes-kit 0.26.0 → 0.26.2

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,115 @@ 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 '';
+    // @implements A-SPEC-700.2 — name the tool that runs the whole plan under one approval. APPENDED:
+    // the per-move sentence stays, because `spec_renumber` is still how one family is moved by hand.
+    return parts.join('; ') + (plan.moves.length > 0
+        ? '; then re-seal with spec_approve, and merge (spec_reconcile plan → apply runs every move under one approval)' : '');
+}

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

@@ -0,0 +1,25 @@
+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;
+/**
+ * The local half of the comparison, spelled the way the remote half is: store-relative posix path,
+ * BOM stripped, CRLF folded, `collisionKeyOf` as the identity. Regular files only — a FIFO named
+ * `*.md` blocks `open(2)` forever (doctor round-6), so the type is asked before the read.
+ */
+export declare function collectLocalSpecEntries(specsRoot: string): {
+    entries: IdCollisionEntry[];
+    skipped: number;
+};

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

@@ -0,0 +1,236 @@
+"use strict";
+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.collectRemoteAddedSpecs = collectRemoteAddedSpecs;
+exports.collectLocalSpecEntries = collectLocalSpecEntries;
+// @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 fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+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;
+}
+// @implements A-SPEC-700.2
+/**
+ * The local half of the comparison, spelled the way the remote half is: store-relative posix path,
+ * BOM stripped, CRLF folded, `collisionKeyOf` as the identity. Regular files only — a FIFO named
+ * `*.md` blocks `open(2)` forever (doctor round-6), so the type is asked before the read.
+ */
+function collectLocalSpecEntries(specsRoot) {
+    const entries = [];
+    let skipped = 0;
+    const walk = (dir) => {
+        let listed;
+        try {
+            listed = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            skipped++;
+            return;
+        }
+        for (const e of listed.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+                continue;
+            }
+            if (!e.name.endsWith('.md'))
+                continue;
+            if (!e.isFile()) {
+                skipped++;
+                continue;
+            }
+            try {
+                const folded = fs.readFileSync(p, 'utf8').replace(/^/, '').replace(/\r\n/g, '\n');
+                const spec = (0, spec_parser_1.parseSpec)(folded);
+                if (!spec.id) {
+                    skipped++;
+                    continue;
+                }
+                entries.push({
+                    file: path.relative(specsRoot, p).split(path.sep).join('/'),
+                    id: spec.id,
+                    approvedDigest: typeof spec.frontmatter.approved_digest === 'string' ? spec.frontmatter.approved_digest : undefined,
+                    contentDigest: (0, id_collision_1.collisionKeyOf)(folded, spec),
+                });
+            }
+            catch {
+                skipped++;
+            }
+        }
+    };
+    walk(specsRoot);
+    return { entries, skipped };
+}

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[];
+};

package/dist/holmes/spec/renumber.js

@@ -489,9 +489,17 @@ function readSourcesForRenumber(projectRoot) {
     }
     return out;
 }
-/** Spec documents as the planner needs them, with store-relative POSIX paths. */
+/**
+ * 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.
+ */
 function readSpecsForRenumber(specsRoot) {
     const out = [];
+    const unreadable = [];
     for (const abs of walk(specsRoot).concat((function md(dir, acc = []) {
         let entries;
         try {
@@ -511,21 +519,32 @@ function readSpecsForRenumber(specsRoot) {
     })(specsRoot))) {
         if (!abs.endsWith('.md'))
             continue;
+        const rel = path.relative(specsRoot, abs).split(path.sep).join('/');
         let text;
         try {
             text = fs.readFileSync(abs, 'utf8');
         }
         catch {
+            unreadable.push(rel);
             continue;
         }
-        const fm = /^---\n([\s\S]*?)\n---/.exec(text);
-        if (!fm)
+        // @implements A-SPEC-699 — `\r?\n`, not `\n`. A checkout with core.autocrlf=true holds every
+        // spec as CRLF, and an LF-only fence matched none of them.
+        const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+        if (!fm) {
+            unreadable.push(rel);
             continue;
+        }
         const field = (k) => (new RegExp(`^${k}:[ \\t]*(.+)$`, 'm').exec(fm[1])?.[1] ?? '').trim();
         const id = field('id');
-        if (id === '')
+        if (id === '') {
+            unreadable.push(rel);
             continue;
-        const deps = (/^depends_on:\n((?:[ \t]*-[ \t]*.+\n?)+)/m.exec(fm[1])?.[1] ?? '')
+        }
+        // @implements A-SPEC-699 — the fence is not the only LF-only site. Fixing it alone would leave
+        // this one matching nothing on CRLF, so every family would come back with no edges and both
+        // unsealOrder and approveOrder would arrive empty: the same silence, one layer down.
+        const deps = (/^depends_on:\r?\n((?:[ \t]*-[ \t]*.+\r?\n?)+)/m.exec(fm[1])?.[1] ?? '')
             .split('\n').map((l) => l.replace(/^[ \t]*-[ \t]*/, '').trim()).filter((x) => x !== '');
         const inline = /^depends_on:[ \t]*\[(.*)\]/m.exec(fm[1])?.[1];
         out.push({
@@ -536,5 +555,5 @@ function readSpecsForRenumber(specsRoot) {
             body: text,
         });
     }
-    return out;
+    return { specs: out, unreadable };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",