@holmes-lab/holmes-kit 0.23.2 → 0.23.3

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.23.3] - 2026-09-18
+
+A suite that takes half as long, a build that admits when it is stale, and a CI matrix that stopped
+reporting its own noise as a verdict.
+
+### Fixed
+- **The Files-to-Touch declarations that were anchored, and the ones that were not** (A-SPEC-670,
+  A-SPEC-665, A-SPEC-672, A-SPEC-674). Five trace gaps that REQ-670's parser fix uncovered are
+  closed: `A-SPEC-495`, `A-SPEC-549.3` and `A-SPEC-549.4` declared scanned production files and
+  carried no anchor in any of them. Every one of the six places was checked before it was claimed —
+  an anchor is an assertion, not a metric — and all six were true. Unlinked approved specs 52 → 49,
+  `codeLinkedPct` 91.95 → 92.41, trace gaps 5 → 0.
+- **The CI matrix was reporting its own noise as a verdict** (A-SPEC-664, A-SPEC-674). Measured over
+  22 runs: **every one was red**, and the reds were dominated by two suites this repository knows as
+  load gauges (`dashboard.test` 20/22, `entity-store-boundaries` 12/22). The cause was contention —
+  the Linux VM takes 11 of the host's 12 cores and ran jest with default workers. A signal that is
+  always red cannot separate a regression from itself. With the worker cap below, both canaries went
+  green on Linux for the first time in 23 runs, and the matrix immediately produced its first real
+  finding.
+- **A dead lock holder could stop the matrix for ever, silently** (A-SPEC-674). The runner's lock was
+  released by `trap ... EXIT`, which SIGKILL and a process-group teardown skip; one such lock stood
+  for 95 minutes while nine commits went unjudged. The lock now names its holder and liveness is
+  judged by PID, never by elapsed time — calling a slow run dead would start a second run on the
+  same machine. A skipped run also leaves a `skipped` row now: REQ-664's rule is that no row means
+  "not run", so a silent skip erased the skip itself.
+
+### Added
+- **The Stop hook says when `dist/` no longer represents the source** (A-SPEC-673). Thirty suites
+  load `dist/` while they run and nothing asserted it was current; only the release gate compared the
+  build id to HEAD, and only at publish time. A stale build does not go red — it verifies old code
+  and returns green. The judgement is built on the build id and **not** on mtime, measured: this
+  tree's `.build-id` had a newer mtime than every source while naming a commit nine behind, and two
+  changed sources were missing from `dist` entirely. Five states, of which `fresh` and `absent` say
+  nothing at all, and the two unjudgeable ones say **the check could not run** rather than passing
+  quietly. Non-blocking, on the `tracked` channel, and silent in a workspace that does not build.
+
+### Changed
+- **The test suite runs in 353s instead of 505s** (A-SPEC-672). The wall clock equalled the longest
+  single file to the decimal, so more workers could not help. Splitting the two heaviest files alone
+  moved it 505s → 493s while the serial total rose 2,836s → 5,109s: four heavy suites running at once
+  contended hard enough to swallow the win. Measured 2x2, the split and a worker cap **interact** —
+  alone they are worth 12s and 44s, together 132s. `jest.maxWorkers` is now `"50%"`, a proportion
+  rather than a number, because a fixed count means something else on a machine with a different core
+  count. Cases are preserved exactly, per-spec execution counts included.
+
 ## [0.23.2] - 2026-09-18
 
 Three rules that existed only in prose, and the one number a broken parser had published.

package/README.md

@@ -16,6 +16,7 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🧱 **A stale build is told, not discovered** *(new in 0.23.3)*: thirty suites in this project load `dist/` while they run, and nothing asserted that it still represented the source — only the release gate compared the build id to HEAD, and only at publish time. A stale build does not go red; it verifies old code and returns green. The Stop hook now reports it on the non-blocking `tracked` channel, judged by the **build id and never by mtime**: measured here, `.build-id` had a newer mtime than every source file while naming a commit nine behind HEAD, with two changed sources missing from `dist` entirely. A workspace that does not build hears nothing, `fresh` says nothing, and the two states that cannot be judged say **that** rather than passing quietly.
 - 📐 **Declarations are read as written** *(new in 0.23.2)*: `Files to Touch` is where a spec declares the files it will touch, and three things read it — fulfilment advisories, the declaration census and the approval impact note. The parser took only the **first word of a list item**, so measured over 678 approved specs here, **88 specs and 172 paths were declared and never read**; 24 of them parsed to zero while naming files plainly. Several paths on one line, an indented continuation, a Korean first word, a prose paragraph — all invisible. They are read now, wherever they sit, and a bare `name.ext` keeps its old position rule so a property access like `module.exports` is still not a file. A declared path that does not exist but is the suffix of exactly one repository file is reported as an abbreviation rather than a defect; two candidates stays an ambiguity and nothing is guessed. Cost, measured across the whole corpus: **zero** new `missing` findings.
 - 📄 **The publish gate reads the docs** *(new in 0.23.2)*: the publish playbook has demanded "bring README and CHANGELOG up to this release" since 0.16.0 and only prose enforced it, so it failed four times — including 0.21.0, 0.22.0 and 0.23.0, which each shipped with a feature list frozen at 0.20.0. The release gate now refuses two things it can decide: a missing CHANGELOG entry for the version being published, and an entry with `### Added` while `README.md` has not changed since the previous release. Replayed over eight releases it refuses exactly the three that were stale and passes the other five. What needs judgement — is the old wording still true? — stays with the person and is **reported**, never faked; a check that could not run says so instead of reading as a pass.
 - 🧩 **Your config files survive a re-wire** *(new in 0.23.0)*: `init --agent antigravity` and `init --agent codex` used to replace `.agents/mcp_config.json`, `.agents/hooks.json` and `marketplace.json` **whole**. Measured with a real `--dry-run` before the fix: a neighbour MCP server, a neighbour hook namespace, a neighbour plugin, a marketplace's own name and an operator's `disabled` flag all survived a re-wire at a rate of **zero**. They now survive — only the holmes-kit entry is refreshed, and `init` names what it kept. A `disabled` you set stays set (and `init` says the gate will not run while it stands, rather than switching it back on silently); an existing file that is not readable JSON is refused with a reason instead of being replaced. The Claude wiring already merged; the other two harnesses now have the same discipline.

package/dist/.build-id

@@ -1 +1 @@
-86f8d89c-mu6hz0ua
+970ee6cf-mu6tt9oo

package/dist/holmes/cli/approve.js

@@ -48,6 +48,8 @@ exports.renderRefusals = renderRefusals;
 exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
 // @implements A-SPEC-246, A-SPEC-626
+// @implements A-SPEC-549.4 — renderPending and renderNonTtyHint in this file are the English CLI
+// surface the Hangul-absence guard reads.
 const execution_context_1 = require("../project/execution-context");
 const root_1 = require("../project/root");
 const fs = __importStar(require("node:fs"));

package/dist/holmes/hooks/pre-tool-use.js

@@ -46,6 +46,8 @@ exports.wiredSpecsDir = wiredSpecsDir;
 exports.evaluateHook = evaluateHook;
 exports.readSpecsSync = readSpecsSync;
 // @implements A-SPEC-278
+// @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
+// evaluateHook in this file to prove it.
 // @implements A-SPEC-643
 // @implements A-SPEC-642
 // @implements A-SPEC-194, A-SPEC-195

package/dist/holmes/hooks/stop.d.ts

@@ -3,7 +3,9 @@ import { Spec } from '../spec/spec-parser';
 import type { TestOutcome } from '../review/test-runner';
 import { type KnownDefectJudgement } from '../rtm/known-defects';
 import { type CiVerdict } from '../project/ci-runs';
+import { type DistVerdict } from '../project/dist-freshness';
 export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
+export declare function collectDistFreshness(root: string): DistVerdict | undefined;
 export declare function collectCiVerdicts(root: string, now?: Date): CiVerdict[];
 /**
  * @implements A-SPEC-100.2
@@ -38,6 +40,11 @@ export interface StopEvidence {
      * hook could not look; a `not-run` verdict when it looked and found no row (never silence).
      */
     ci?: CiVerdict[];
+    /**
+     * @implements A-SPEC-673 — whether `dist/` still represents the source. Absent when the workspace
+     * does not build at all; a `no-build-id`/`unknown` verdict when it looked and could not judge.
+     */
+    dist?: DistVerdict;
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
     provenance?: {
         ok: boolean;

package/dist/holmes/hooks/stop.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
 exports.collectKnownDefects = collectKnownDefects;
+exports.collectDistFreshness = collectDistFreshness;
 exports.collectCiVerdicts = collectCiVerdicts;
 exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
@@ -55,6 +56,8 @@ exports.guardCountOrZero = guardCountOrZero;
 exports.readGuardCount = readGuardCount;
 exports.writeGuardCount = writeGuardCount;
 const fs = __importStar(require("node:fs"));
+// @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
+// calls into this file.
 // @implements A-SPEC-645
 // @implements A-SPEC-642
 const npx_bin_1 = require("../project/npx-bin");
@@ -81,6 +84,7 @@ const root_1 = require("../project/root");
 const known_defects_1 = require("../rtm/known-defects");
 const test_files_1 = require("../cpg/test-files");
 const ci_runs_1 = require("../project/ci-runs");
+const dist_freshness_1 = require("../project/dist-freshness");
 // @implements A-SPEC-660 — the I/O half of the known-defect marker: walk the workspace's test files
 // (the same directory rule and test predicate ART-4's anchor scan uses), parse each for markers,
 // judge them against the injected clock. A walk that cannot START is NO SIGNAL (undefined) — never
@@ -128,6 +132,32 @@ function collectKnownDefects(root, now) {
         return undefined;
     }
 }
+// @implements A-SPEC-673 — the I/O half of the build-freshness line: read `dist/.build-id` and ask
+// git how far that commit sits behind HEAD. A workspace that does not build hears nothing; a build
+// that cannot be judged says so rather than passing quietly.
+function collectDistFreshness(root) {
+    if (!(0, dist_freshness_1.hasDist)(root))
+        return undefined;
+    const buildId = (0, dist_freshness_1.distBuildId)(root);
+    let head = null;
+    try {
+        head = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--short', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() }).trim();
+    }
+    catch {
+        head = null;
+    }
+    let behind = null;
+    if (buildId && head) {
+        try {
+            const n = Number((0, node_child_process_1.execFileSync)('git', ['rev-list', '--count', `${buildId}..HEAD`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() }).trim());
+            behind = Number.isFinite(n) ? n : null;
+        }
+        catch {
+            behind = null;
+        }
+    }
+    return (0, dist_freshness_1.distFreshness)({ distExists: true, buildId, head, behind });
+}
 // @implements A-SPEC-664 — the I/O half of the CI line: read the ci-runs ledger, judge Linux (always)
 // and any other OS that has a row, with git measuring how far each judged commit sits behind HEAD.
 // A tree without a ledger yields a `not-run` verdict — a line, not an absence.
@@ -529,6 +559,7 @@ const TRACK_LABELS = {
     'ART-2': 'code-graph cycles',
     'ART-9': 'known-defect debt',
     'CI': 'matrix',
+    'DIST': 'build freshness',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -602,6 +633,14 @@ function evaluateStop(specs, evidence) {
         const t = evidence.ci.map((v) => ({ article: 'CI', detail: (0, ci_runs_1.ciStatusLine)(v) }));
         tracked = [...(tracked ?? []), ...t];
     }
+    // @implements A-SPEC-673 — a build that no longer represents the source. Thirty suites load `dist/`
+    // while they run, so a stale one does not go red: it verifies old code and returns green. `fresh`
+    // and `absent` produce no line, because a line is spent only on something the reader can act on.
+    if (evidence?.dist) {
+        const detail = (0, dist_freshness_1.distStatusLine)(evidence.dist);
+        if (detail)
+            tracked = [...(tracked ?? []), { article: 'DIST', detail }];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -1194,7 +1233,15 @@ if (require.main === module) {
             catch {
                 ci = undefined;
             }
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}) });
+            // @implements A-SPEC-673 — the build-freshness line rides the same non-blocking channel.
+            let dist;
+            try {
+                dist = collectDistFreshness(stopProjectRoot());
+            }
+            catch {
+                dist = undefined;
+            }
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}) });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
             // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty

package/dist/holmes/mcp/tool-schemas.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
 // @implements A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627
+// @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
+// consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
 // @implements A-SPEC-642
 // @implements A-SPEC-641
 // @implements A-SPEC-639

package/dist/holmes/project/ci-lock.d.ts

@@ -0,0 +1,20 @@
+export interface CiLockHolder {
+    pid: number;
+    host: string;
+    rev: string;
+    at: string;
+}
+export type CiLockState = 'free' | 'held' | 'dead' | 'unknown';
+export interface CiLockInput {
+    holder: CiLockHolder | null;
+    thisHost: string;
+    alive: boolean;
+}
+/** Null for every shape we cannot trust — including the legacy empty directory. */
+export declare function readCiLock(lockDir: string): CiLockHolder | null;
+/**
+ * A holder written by ANOTHER host is `unknown`, not dead: we cannot ask that machine about its
+ * pids, and guessing would hand two runners the same VM. Unknown is respected like `held`.
+ */
+export declare function ciLockState(input: CiLockInput): CiLockState;
+export declare function ciLockLine(state: CiLockState, holder: CiLockHolder | null, now?: Date): string;

package/dist/holmes/project/ci-lock.js

@@ -0,0 +1,111 @@
+"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.readCiLock = readCiLock;
+exports.ciLockState = ciLockState;
+exports.ciLockLine = ciLockLine;
+// @implements A-SPEC-674
+/**
+ * Who holds the CI runner's lock, and is that holder still alive.
+ *
+ * The runner serialises itself with a `mkdir` lock — atomic, and that atomicity is the whole reason
+ * it works — released by `trap ... EXIT`. SIGKILL and launchd tearing down the process group skip
+ * that trap. Measured 2026-09-18: one such lock survived 95 minutes while the matrix judged nothing
+ * and nine commits went unjudged, with zero jest processes in the VM and a load of 0.57.
+ *
+ * The lock used to be an EMPTY directory, so it could not say who held it — and a lock that cannot
+ * name its holder cannot be asked whether that holder is alive. It now carries a holder file, and
+ * the judgement below is about liveness, never about elapsed time: calling a slow run dead would
+ * start a second run on the same VM, which is a worse failure than waiting.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Null for every shape we cannot trust — including the legacy empty directory. */
+function readCiLock(lockDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(lockDir, 'holder.json'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const h = parsed;
+    if (typeof h?.pid !== 'number' || !Number.isFinite(h.pid))
+        return null;
+    if (typeof h.host !== 'string' || typeof h.rev !== 'string' || typeof h.at !== 'string')
+        return null;
+    return { pid: h.pid, host: h.host, rev: h.rev, at: h.at };
+}
+/**
+ * A holder written by ANOTHER host is `unknown`, not dead: we cannot ask that machine about its
+ * pids, and guessing would hand two runners the same VM. Unknown is respected like `held`.
+ */
+function ciLockState(input) {
+    const { holder, thisHost, alive } = input;
+    if (!holder)
+        return 'free';
+    if (holder.host !== thisHost)
+        return 'unknown';
+    return alive ? 'held' : 'dead';
+}
+const elapsed = (at, now) => {
+    const t = Date.parse(at);
+    if (!Number.isFinite(t))
+        return null;
+    const mins = Math.floor((now.getTime() - t) / 60000);
+    // A clock that runs backwards is a fact about the clock, not about the holder; never report it as
+    // negative time.
+    return mins < 0 ? null : `${mins} min`;
+};
+function ciLockLine(state, holder, now = new Date()) {
+    if (state === 'free' || !holder)
+        return '';
+    const held = elapsed(holder.at, now);
+    const forHow = held ? ` for ${held}` : '';
+    if (state === 'dead') {
+        return `ci lock holder pid ${holder.pid} is gone (held${forHow}, rev ${holder.rev}) — reclaiming it; the matrix judges nothing while a dead holder stands`;
+    }
+    if (state === 'unknown') {
+        return `ci lock was taken by ${holder.host} (rev ${holder.rev}${forHow}) — this host cannot judge another machine's pids, so it is respected`;
+    }
+    return `ci lock is held by pid ${holder.pid} running rev ${holder.rev}${forHow}`;
+}

package/dist/holmes/project/dist-freshness.d.ts

@@ -0,0 +1,30 @@
+export type DistState = 'fresh' | 'behind' | 'absent' | 'no-build-id' | 'unknown';
+export interface DistVerdict {
+    state: DistState;
+    buildId: string | null;
+    head: string | null;
+    behind: number | null;
+}
+export interface DistInput {
+    distExists: boolean;
+    buildId: string | null;
+    head: string | null;
+    /** Commits from the build id to HEAD, or null when it could not be obtained. */
+    behind: number | null;
+}
+/**
+ * The adoption predicate: existence, never contents. A workspace that does not build has no build
+ * freshness to report, and telling it about one would be noise it can do nothing with (the same
+ * reasoning REQ-664 used for the CI ledger).
+ */
+export declare function hasDist(root: string): boolean;
+/** The commit the artefact came from — the part before the dash `npm run build` writes. */
+export declare function distBuildId(root: string): string | null;
+/**
+ * Five states because each calls for something different: `behind` means build, `absent` means
+ * nothing at all to this workspace, and the two unjudgeable ones mean the check did not run — which
+ * must never be reported as a check that passed.
+ */
+export declare function distFreshness(input: DistInput): DistVerdict;
+/** Empty when there is nothing to say. A line is spent only on a fact the reader can act on. */
+export declare function distStatusLine(v: DistVerdict): string;

package/dist/holmes/project/dist-freshness.js

@@ -0,0 +1,114 @@
+"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.hasDist = hasDist;
+exports.distBuildId = distBuildId;
+exports.distFreshness = distFreshness;
+exports.distStatusLine = distStatusLine;
+// @implements A-SPEC-673
+/**
+ * Whether the built artefact still represents the source.
+ *
+ * Thirty suites in this repository load `dist/` while they run — they spawn it or require it — and
+ * nothing asserted that it was current. `scripts/verify-release.js` compares the build id to HEAD,
+ * but only at publish time, so during development a stale build does not go red: it quietly verifies
+ * old code and returns green. This repository has already paid for that once.
+ *
+ * The judgement is built on the BUILD ID, never on mtime, for a measured reason. On 2026-09-18 this
+ * tree's `dist` was nine commits behind HEAD and two changed sources were missing from it entirely,
+ * while `find src -newer dist/.build-id` answered zero — the marker's mtime had been touched without
+ * a rebuild. mtime lies. The build id says which commit the artefact actually came from.
+ *
+ * This module only JUDGES. It never rebuilds: a hook does not change the operator's tree in silence.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * The adoption predicate: existence, never contents. A workspace that does not build has no build
+ * freshness to report, and telling it about one would be noise it can do nothing with (the same
+ * reasoning REQ-664 used for the CI ledger).
+ */
+function hasDist(root) {
+    try {
+        return fs.statSync(path.join(root, 'dist')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** The commit the artefact came from — the part before the dash `npm run build` writes. */
+function distBuildId(root) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(root, 'dist', '.build-id'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const id = raw.trim().split('-')[0];
+    // A shape we do not recognise falls through to a judgement we cannot make, never to a pass.
+    return /^[0-9a-f]{7,40}$/.test(id) ? id : null;
+}
+/**
+ * Five states because each calls for something different: `behind` means build, `absent` means
+ * nothing at all to this workspace, and the two unjudgeable ones mean the check did not run — which
+ * must never be reported as a check that passed.
+ */
+function distFreshness(input) {
+    const { distExists, buildId, head, behind } = input;
+    const base = { buildId: buildId ?? null, head: head ?? null, behind: typeof behind === 'number' ? behind : null };
+    if (!distExists)
+        return { state: 'absent', ...base };
+    if (!buildId)
+        return { state: 'no-build-id', ...base };
+    if (!head || typeof behind !== 'number' || !Number.isFinite(behind) || behind < 0)
+        return { state: 'unknown', ...base };
+    return { state: behind === 0 ? 'fresh' : 'behind', ...base };
+}
+/** Empty when there is nothing to say. A line is spent only on a fact the reader can act on. */
+function distStatusLine(v) {
+    if (v.state === 'fresh' || v.state === 'absent')
+        return '';
+    if (v.state === 'no-build-id') {
+        return 'dist/.build-id is missing or unreadable — the build could not be judged against the source; `npm run build` writes it';
+    }
+    if (v.state === 'unknown') {
+        return `dist was built from ${v.buildId ?? 'an unknown commit'} and the distance to HEAD could not be obtained — the build could not be judged`;
+    }
+    // No invented threshold: one commit is reported like nine, because which commits matter is a
+    // question the reader can answer and this function cannot.
+    const n = v.behind ?? 0;
+    return `dist is ${n} commit${n === 1 ? '' : 's'} behind HEAD (built from ${v.buildId}) — suites that load dist are verifying that build, not this tree; \`npm run build\``;
+}

package/dist/holmes/semantic/credentials.js

@@ -37,6 +37,8 @@ exports.resolveSemanticKey = resolveSemanticKey;
 exports.storeSemanticKey = storeSemanticKey;
 exports.removeSemanticKey = removeSemanticKey;
 // @implements A-SPEC-592
+// @implements A-SPEC-549.4 — declared by that spec's Files to Touch and carries no Hangul; note that
+// the guard's own SOURCES list does not cover this file (reported, not fixed here).
 // @implements A-SPEC-477
 /**
  * The cloud tier's credential: WHERE the consent lives, and in what order it is looked up.

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.23.2",
+  "version": "0.23.3",
   "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",
@@ -62,7 +62,8 @@
     "testTimeout": 30000,
     "setupFilesAfterEnv": [
       "<rootDir>/src/holmes/test-support/jest-timeouts-setup.ts"
-    ]
+    ],
+    "maxWorkers": "50%"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",