@holmes-lab/holmes-kit 0.26.1 → 0.27.0

package/dist/holmes/rtm/traced-files.js

@@ -0,0 +1,207 @@
+"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.UNTRACED_LINE_CAP = exports.ATTEST_SCHEMA = exports.ATTEST_END = exports.ATTEST_BEGIN = void 0;
+exports.normalizeExcludes = normalizeExcludes;
+exports.flooredPct = flooredPct;
+exports.tracedFiles = tracedFiles;
+exports.attestProvenance = attestProvenance;
+exports.renderAttestText = renderAttestText;
+exports.renderAttestJson = renderAttestJson;
+exports.renderAttestSvg = renderAttestSvg;
+exports.renderAttestMarker = renderAttestMarker;
+exports.replaceMarkerRegion = replaceMarkerRegion;
+// @implements A-SPEC-702
+/**
+ * How many of a repository's source files trace to an APPROVED spec — said as a number anyone can
+ * reproduce, with the commit and spec-store state it was measured at.
+ *
+ * This exists INSTEAD of a "generated under holmes-kit" header in every file (REQ-702). A header is
+ * a claim: it can be pasted, and it keeps saying "governed" after an ungoverned edit. Line 1 already
+ * carries the `implements` anchor, which a gate verifies. What was missing is a repository-level
+ * statement, and the spec-side half of it (`linkCensus`) lived only inside the dashboard.
+ *
+ * NO NEW JUDGEMENT. The denominator is whatever the scanner returned, the numerator is anchors ∩
+ * approved ids. Everything here is pure — no clock, no filesystem, no git — so the same input is the
+ * same bytes and a committed badge does not churn. The CLI that feeds it is `cli/attest.ts`.
+ */
+const crypto = __importStar(require("node:crypto"));
+exports.ATTEST_BEGIN = '<!-- holmes-kit:attest:begin -->';
+exports.ATTEST_END = '<!-- holmes-kit:attest:end -->';
+exports.ATTEST_SCHEMA = 'holmes-attest/1';
+/** Above this many untraced files the text names none and points at `--json`. */
+exports.UNTRACED_LINE_CAP = 10;
+const posix = (p) => p.replace(/\\/g, '/').replace(/^\.\//, '');
+/**
+ * Backslashes folded, one trailing slash. A prefix that means "everything" is DROPPED: excluding the
+ * whole tree would read as n/a at best and 100% at worst (the same rule A-SPEC-694 pinned for
+ * `cycleIgnore`). Sorted and de-duplicated so the provenance does not depend on how it was typed.
+ */
+function normalizeExcludes(raw) {
+    const out = new Set();
+    for (const r of raw ?? []) {
+        const p = posix(String(r).trim()).replace(/^\/+/, '').replace(/\/+$/, '');
+        if (p === '' || p === '.')
+            continue;
+        out.add(p + '/');
+    }
+    return [...out].sort();
+}
+/** Floored to one decimal: 99.96 must not read as 100 — 100 means every file. */
+function flooredPct(num, den) {
+    if (den <= 0)
+        return null;
+    return Math.floor((num / den) * 1000) / 10;
+}
+function tracedFiles(input) {
+    const approved = new Set(input.approvedIds);
+    const excludes = normalizeExcludes(input.exclude);
+    let excluded = 0, traced = 0, total = 0;
+    const untraced = [];
+    for (const f of input.files) {
+        const p = posix(f.path);
+        // Boundary match: every prefix ends in '/', so `reference/` cannot pardon `reference-impl/`.
+        if (excludes.some((e) => p.startsWith(e))) {
+            excluded++;
+            continue;
+        }
+        total++;
+        if (f.anchors.some((id) => approved.has(id)))
+            traced++;
+        else
+            untraced.push(p);
+    }
+    untraced.sort();
+    const reason = total === 0 ? 'no source files' : approved.size === 0 ? 'no approved specs' : undefined;
+    return {
+        total, traced, excluded, untraced,
+        measurable: reason === undefined,
+        ...(reason !== undefined ? { reason } : {}),
+        tracedPct: reason === undefined ? flooredPct(traced, total) : null,
+    };
+}
+/**
+ * Where and when the number is true. `+dirty` because a commit alone would call an unreproducible
+ * number reproducible. The spec digest covers (id, seal) of every approved spec — that set is what
+ * decides the numerator. No clock anywhere.
+ */
+function attestProvenance(input) {
+    const lines = input.approved.map((a) => `${a.id}\t${a.digest}`).sort();
+    const specs = crypto.createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 12);
+    const commit = (input.commit ?? '').trim();
+    const at = commit === '' ? 'unversioned' : commit.slice(0, 12) + (input.dirty ? '+dirty' : '');
+    return { at, specs, exclude: normalizeExcludes(input.exclude) };
+}
+const pctText = (pct) => (pct === null ? 'n/a' : `${pct}%`);
+const ratio = (num, den, sep) => `${num}${sep}${den}`;
+function renderAttestText(r) {
+    const f = r.files;
+    const filesLine = f.measurable
+        ? `${ratio(f.traced, f.total, ' / ')} (${pctText(f.tracedPct)})`
+        : `n/a — ${f.reason}`;
+    const specPct = flooredPct(r.specs.linked, r.specs.total);
+    const specsLine = specPct === null ? 'n/a — no approved A-SPECs' : `${ratio(r.specs.linked, r.specs.total, ' / ')} (${pctText(specPct)})`;
+    const lines = [
+        `traced files   ${filesLine}   — source files anchored to an APPROVED spec`,
+        `linked specs   ${specsLine}   — approved A-SPECs anchored from code`,
+    ];
+    // Few enough to act on → name them; a wall of paths helps nobody, so beyond that point to --json.
+    if (f.measurable && f.untraced.length > 0) {
+        lines.push(f.untraced.length <= exports.UNTRACED_LINE_CAP
+            ? `untraced       ${f.untraced.join(', ')}`
+            : `untraced       ${f.untraced.length} file(s) — list them with --json`);
+    }
+    if (r.provenance.exclude.length > 0)
+        lines.push(`excluded       ${f.excluded} file(s) under: ${r.provenance.exclude.join(', ')}`);
+    lines.push(`at             ${r.provenance.at} · specs sha256:${r.provenance.specs}`);
+    return lines.join('\n') + '\n';
+}
+function renderAttestJson(r) {
+    return JSON.stringify({ schema: exports.ATTEST_SCHEMA, files: r.files, specs: r.specs, provenance: r.provenance }, null, 2) + '\n';
+}
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** Self-contained: no href, font, script or fetch. Only the ratio, the percentage and `at` go in. */
+function renderAttestSvg(r) {
+    const f = r.files;
+    const value = f.measurable ? `${ratio(f.traced, f.total, '/')} · ${pctText(f.tracedPct)}` : 'n/a';
+    const label = 'traced files';
+    const lw = 86, vw = Math.max(64, 14 + value.length * 7), w = lw + vw;
+    const colour = !f.measurable ? '#9f9f9f' : (f.tracedPct ?? 0) >= 90 ? '#2e7d32' : (f.tracedPct ?? 0) >= 60 ? '#b08900' : '#b3541e';
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="34" role="img" aria-label="${xml(label + ': ' + value)}">`,
+        `<title>${xml(label + ': ' + value + ' @ ' + r.provenance.at)}</title>`,
+        `<rect width="${lw}" height="20" fill="#444"/>`,
+        `<rect x="${lw}" width="${vw}" height="20" fill="${colour}"/>`,
+        `<g fill="#fff" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">`,
+        `<text x="${lw / 2}" y="14" text-anchor="middle">${xml(label)}</text>`,
+        `<text x="${lw + vw / 2}" y="14" text-anchor="middle">${xml(value)}</text>`,
+        `</g>`,
+        `<text x="0" y="31" fill="#666" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="9">${xml('at ' + r.provenance.at)}</text>`,
+        `</svg>`,
+    ].join('') + '\n';
+}
+/** What goes between the markers. Carries the excludes, so the README says how to reproduce it. */
+function renderAttestMarker(r) {
+    const f = r.files;
+    const files = f.measurable ? `**${ratio(f.traced, f.total, '/')}** source files (${pctText(f.tracedPct)}) trace to an approved spec` : `traced files: n/a — ${f.reason}`;
+    const specPct = flooredPct(r.specs.linked, r.specs.total);
+    const specs = specPct === null ? '' : ` · **${ratio(r.specs.linked, r.specs.total, '/')}** approved A-SPECs (${pctText(specPct)}) are anchored from code`;
+    const excl = r.provenance.exclude.length > 0 ? ` --exclude ${r.provenance.exclude.join(',')}` : '';
+    return [
+        `![traced files](.ax/badges/traced.svg)`,
+        ``,
+        `${files}${specs}.`,
+        `Measured at \`${r.provenance.at}\` (specs \`sha256:${r.provenance.specs}\`) — reproduce with \`holmes-kit attest${excl}\`.`,
+    ].join('\n');
+}
+const count = (hay, needle) => hay.split(needle).length - 1;
+/**
+ * Replace what lies between the two markers — and ONLY when each appears exactly once, begin first.
+ * No marker is `no-marker`: the person never asked, so nothing is written. Anything else malformed is
+ * `unbalanced`: a lone begin marker followed by "replace to the end" is this feature's worst failure.
+ * The README's own line ending is kept, so a CRLF file does not become one whole-file diff.
+ */
+function replaceMarkerRegion(readme, inner) {
+    const begins = count(readme, exports.ATTEST_BEGIN), ends = count(readme, exports.ATTEST_END);
+    if (begins === 0 && ends === 0)
+        return { ok: false, reason: 'no-marker' };
+    const b = readme.indexOf(exports.ATTEST_BEGIN), e = readme.indexOf(exports.ATTEST_END);
+    if (begins !== 1 || ends !== 1 || e < b)
+        return { ok: false, reason: 'unbalanced' };
+    const eol = readme.includes('\r\n') ? '\r\n' : '\n';
+    const body = inner.replace(/\r\n/g, '\n').split('\n').join(eol);
+    const text = readme.slice(0, b + exports.ATTEST_BEGIN.length) + eol + body + eol + readme.slice(e);
+    return { ok: true, text, changed: text !== readme };
+}

package/dist/holmes/spec/entity-store.js

@@ -148,10 +148,8 @@ function validUuid(v) { return typeof v === 'string' && UUID.test(v); }
 function locator(v) {
     return typeof v === 'string' && v.length > 0 && !/[\\:\x00]/.test(v) && v.split('/').every(p => p.length > 0 && p !== '.' && p !== '..');
 }
-function recordJson(file) {
-    const bytes = (0, entity_transaction_1.readEntityBytes)(file);
-    if (!bytes)
-        throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'An entity record disappeared.');
+/** @implements A-SPEC-701 — the parse, shared, so a caller that already HOLDS the bytes never reads the file again. */
+function parseRecord(bytes) {
     try {
         return JSON.parse(bytes.toString('utf8'));
     }
@@ -159,6 +157,12 @@ function recordJson(file) {
         throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Entity state contains malformed JSON.');
     }
 }
+function recordJson(file) {
+    const bytes = (0, entity_transaction_1.readEntityBytes)(file);
+    if (!bytes)
+        throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'An entity record disappeared.');
+    return parseRecord(bytes);
+}
 function validateEntityAdoptionPlan(value) {
     const p = object(value, ['schema', 'operationId', 'workspaceId', 'storeId', 'storeLocator', 'entries']);
     if (p.schema !== 'holmes-entity-adoption/1' || !validUuid(p.operationId) || !validUuid(p.workspaceId) || !validUuid(p.storeId) || !locator(p.storeLocator) || !Array.isArray(p.entries))
@@ -247,9 +251,27 @@ function assertNoPending(bound) {
         const op = (0, entity_transaction_1.entityDirectory)(dir, name);
         // @implements A-SPEC-634 — a pending directory without a journal is an operation that died
         // between taking its locks and publishing; name it, do not fail on the missing record.
-        if (!(0, entity_transaction_1.readEntityBytes)(path.join(op, 'journal.json')))
+        //
+        // @implements A-SPEC-701 — the journal is read ONCE. It used to be read twice (once to see it
+        // exists, once to parse it) while `retireEntityOperation` moves the whole operation directory
+        // with a single rename — so an operation that FINISHED while this lock-free scan was looking
+        // was reported either as "interrupted before its journal existed" (retired before the first
+        // read) or as "An entity record disappeared." (retired between the two). Measured 2026-09-20 on
+        // the Linux CI: one of four racing adopters got the second, a code outside the three that race
+        // calls legal. Both refusals were safe and both were false.
+        //
+        // What separates the two causes of "no journal" is whether the DIRECTORY remains. Retirement
+        // moves it whole, so there is no ordinary path that leaves the directory and takes the journal:
+        // directory present + no journal is A-SPEC-634's dead operation and is still refused by name;
+        // directory gone is an operation that is simply no longer pending. The real write re-runs this
+        // scan under the lock, so skipping a finished operation here cannot admit a conflicting one.
+        const bytes = (0, entity_transaction_1.readEntityBytes)(path.join(op, 'journal.json'));
+        if (!bytes) {
+            if (!(0, entity_transaction_1.entityStat)(op))
+                continue;
             throw new entity_transaction_1.EntityStoreError('recovery-required', 'Operation ' + name + ' was interrupted before its journal existed; inspect entity_store recovery-plan and recover it.');
-        const raw = recordJson(path.join(op, 'journal.json'));
+        }
+        const raw = parseRecord(bytes);
         if (raw?.schema === 'holmes-entity-integration-journal/1') {
             const journal = object(raw, ['schema', 'plan', 'storeOwner', 'sourceOwner']);
             const plan = journal.plan;

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

@@ -230,5 +230,8 @@ function reconcileAdvice(plan) {
     ];
     if (parts.length === 0)
         return '';
-    return parts.join('; ') + (plan.moves.length > 0 ? '; then re-seal with spec_approve, and merge' : '');
+    // @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

@@ -14,3 +14,12 @@ export interface RemoteAddedSpecs {
 /** 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

@@ -1,6 +1,40 @@
 "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
@@ -24,6 +58,8 @@ exports.collectRemoteAddedSpecs = collectRemoteAddedSpecs;
  * 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");
@@ -146,3 +182,55 @@ function collectRemoteAddedSpecs(root, git = defaultGit) {
     }
     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/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "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",