@holmes-lab/holmes-kit 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -5,6 +5,92 @@ 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.24.0] - 2026-09-19
+
+A way for a consumer's defect to reach us, and two rules that existed only in prose.
+
+### Added
+- **`holmes-kit report`** (A-SPEC-675, A-SPEC-676, A-SPEC-679, A-SPEC-680). A consumer project had no channel by which a
+  holmes-kit defect could reach us: the one field defect we knew about arrived because a user pasted
+  a transcript, and it had reproduced for every consumer on every slice. The command writes a
+  **redacted** report to `.ax/reports/<fingerprint>.md` and prints a prefilled GitHub issue link —
+  carrying the title, the repository owner as assignee, and the body — plus a search link for the
+  same fingerprint so a duplicate is visible before filing. `--open` opens it; a headless box, an SSH
+  session or CI simply keeps the printed link. **No token, no API, no automatic submission**: the
+  person presses Submit on GitHub's own page with the body visible and editable, which puts consent
+  where the bytes are. Redaction is an **allowlist**, not a scrubber, because a denylist has been
+  punctured here before; the machine's hostname, username, home directory and replica ids are
+  searched for in the composed body by the pins themselves. A spec id passes by shape and a spec
+  TITLE does not — that is unreleased product intent. Observations take numbers only.
+  What holmes-kit cannot know, it says: no ledger keeps the product's refusal text, so a run without
+  `--message` writes the report, states that no description was given, explains why it cannot be
+  recovered, and exits non-zero rather than handing a maintainer a version string.
+- **A stale graph analysis is visible** (A-SPEC-681). The Stop hook's tracked channel reports source
+  changed with no `maintenance_analyze` standing open. Measured here: the procedure had been skipped
+  for seventeen consecutive commits, and the one run that followed found child-process precedents a
+  name search had missed entirely. Non-blocking, silent in a workspace that never analysed anything,
+  and judged by commit rather than by clock.
+
+### Fixed
+- **The workspace registry no longer fills with dead temp directories** (A-SPEC-677, 678). Measured:
+  603 entries, 458 (76%) pointing at paths that no longer existed and 599 of them temp directories —
+  **three** were real projects. `upgrade` believed the list: it would print 458 skip lines and then
+  run `runInit({force:true})` against 142 abandoned temp directories, writing wiring files into them.
+  A temp target is now never recorded, and recording prunes what has vanished. The pruning is
+  deliberately asymmetric: a vanished temp path is gone by construction, while a vanished normal path
+  may be an unmounted volume, so it is counted and kept — `upgrade` already skips it harmlessly, and
+  deleting it is the one outcome a user cannot undo.
+- **Tests can no longer write into the developer's real registry** (A-SPEC-678). That is how 599 of
+  those entries arrived. Inside jest, `process.env` is a sandbox copy, so setting `HOME` never
+  reaches `setenv` and `os.homedir()` keeps answering the real home — an in-process test cannot
+  isolate a module that calls it directly. `HOLMES_HOME` is the seam; consumers set nothing and
+  behaviour is unchanged for them.
+
+## [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,9 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 📮 **`holmes-kit report` — a defect can reach the maintainers** *(new in 0.24.0)*: until now a consumer's holmes-kit defect had no way back to us; the one we learned about arrived because someone pasted a transcript, and it had been reproducing for every consumer on every slice. The command writes a **redacted** report to `.ax/reports/<fingerprint>.md` and prints a prefilled GitHub issue link — title, assignee, body — plus a search link for the same fingerprint so you can see whether it is already known. `--open` opens it; on a headless box or over SSH the printed link is the whole of it. **No token, no API, nothing sent automatically**: you press Submit on GitHub's own page with the body in front of you and editable. Redaction is an allowlist rather than a scrubber — this project's own remote carries a token before the `@`, its replica ids carry a person's name, and its spec titles are unreleased product intent, so a path, a credential or a machine identifier withholds the field and the report says which. A spec id passes by shape; a spec title does not. And what holmes-kit cannot know, it says: no ledger keeps its own refusal text, so a report with no description states that rather than pretending.
+- 🧭 **A skipped graph analysis is visible** *(new in 0.24.0)*: `AGENTS.md` asks for `maintenance_analyze` before editing source, and nothing checked. Measured on this repository, the step had been skipped for seventeen consecutive commits — and the run that followed named child-process precedents a name search had missed completely, because the question was "who opens a browser" while the answer lived under "who spawns a child". The Stop hook now reports source changed with no analysis standing open: non-blocking, judged by commit rather than by clock, and silent in a workspace that never adopted the habit.
+- 🧱 **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
+d23fd983-mu76a9wy

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/cli/index.js

@@ -234,6 +234,8 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
                              Setting the key is consent to egress (spec prose, paths, symbol names sent externally).
 
   holmes-kit doctor [flags]    diagnose the install
+  holmes-kit report --message "<what happened>" [--harness <name>]
+                               write a redacted field report and print a prefilled issue link
     --target <dir>             also verify that target's wiring points at this install
     --json                     machine-readable output
 
@@ -347,6 +349,33 @@ async function main(argv) {
             return r.exitCode;
         });
     }
+    // @implements A-SPEC-679 — the surface that calls the report composer. Nothing here reaches the
+    // network: it writes a file and prints links, and a person decides whether to open them.
+    if (cmd === 'report') {
+        const { runReport } = require('./report');
+        const { machineIdentity } = require('../project/field-report');
+        const os3 = require('node:os');
+        const mIdx = argv.indexOf('--message');
+        const message = mIdx >= 0 ? argv[mIdx + 1] : undefined;
+        const reported = runReport({ message, open: argv.includes('--open'), root: process.cwd(), packageRoot: packageRoot(), harness: (() => { const i = argv.indexOf('--harness'); return i >= 0 ? argv[i + 1] : undefined; })() }, {
+            write: (p2, c) => fs.writeFileSync(p2, c),
+            mkdir: (p2) => { fs.mkdirSync(p2, { recursive: true }); },
+            stdout: (t) => process.stdout.write(t),
+            readFile: (p2) => fs.readFileSync(p2, 'utf8'),
+            now: () => new Date(),
+            identity: machineIdentity({ hostname: os3.hostname(), username: os3.userInfo().username, homedir: os3.homedir() }),
+        });
+        // @implements A-SPEC-680 — the flag now does what it says. Failing to open is the NORMAL case on
+        // a headless box and never changes the report's own exit code: the URL is already on stdout.
+        if (argv.includes('--open')) {
+            const { openUrl } = require('./open-url');
+            const { spawn } = require('node:child_process');
+            const opened = openUrl(reported.url, process.platform, (f, a, o) => spawn(f, a, o).unref());
+            process.stdout.write(opened ? '\nopened in your browser — press Submit there.\n'
+                : '\ncould not open a browser here; the link above is the whole of it.\n');
+        }
+        return reported.code;
+    }
     if (cmd === 'doctor') {
         // A nonexistent target read as "healthy but unwired" and both advised remedies then refused it
         // (round-6) — the typo is the diagnosis, so say it.
@@ -1183,7 +1212,18 @@ async function main(argv) {
                             return '';
                         }
                     })();
-                    recordWorkspace(os2.homedir(), { target: opts.target, agents: [...agents], version: pkgVersion, ts: new Date().toISOString() });
+                    // @implements A-SPEC-677 — the recorder prunes what has vanished while it is already here.
+                    // A deletion the user cannot see is a deletion they cannot check, so the count is printed.
+                    // @implements A-SPEC-678 — the seam a test can reach; consumers set nothing and get homedir().
+                    const { holmesHome } = require('../update/workspaces');
+                    recordWorkspace(holmesHome(process.env, os2.homedir()), { target: opts.target, agents: [...agents], version: pkgVersion, ts: new Date().toISOString() }, {
+                        read: (p2) => fs.readFileSync(p2, 'utf8'),
+                        write: (p2, c) => fs.writeFileSync(p2, c),
+                        mkdir: (p2) => { fs.mkdirSync(p2, { recursive: true }); },
+                        exists: (p2) => fs.existsSync(p2),
+                        tmpdir: () => os2.tmpdir(),
+                        onPrune: (n) => process.stdout.write(`  registry: dropped ${n} workspace entr${n === 1 ? 'y' : 'ies'} whose temporary path no longer exists\n`),
+                    });
                 }
                 catch { /* registry failure never fails init */ }
             }

package/dist/holmes/cli/open-url.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Opening a URL in whatever the operating system calls a browser.
+ *
+ * `report --open` used to parse the flag and do nothing: A-SPEC-679 said "opening is left to the
+ * caller" and that caller was never written. A flag accepted and ignored is worse than no flag —
+ * the user believes the browser opened and walks away. This repository has the lesson on file as
+ * "left as an integration point means dead".
+ *
+ * Judgement is separated from doing so all three platforms can be pinned from one machine. Wiring
+ * being present has never been the same thing as wiring that works.
+ *
+ * NO SHELL. The URL carries `&` and `#`, and a shell would split the command at them; it goes in as
+ * a single argument, which is the same discipline `Supervisor.spawnChild` and doctor's spawn checks
+ * already follow here.
+ */
+export interface OpenCommand {
+    file: string;
+    args: string[];
+}
+export type SpawnLike = (file: string, args: string[], opts: Record<string, unknown>) => unknown;
+/** `null` when the platform cannot be judged: not opening is better than guessing a command. */
+export declare function openCommand(platform: string): OpenCommand | null;
+/**
+ * True only when the spawn was actually attempted and did not throw.
+ *
+ * A missing browser is the NORMAL case on a headless box, an SSH session or CI. It costs the user
+ * nothing — the URL is already on stdout — so it returns false rather than throwing, and the
+ * caller's exit code does not change.
+ */
+export declare function openUrl(url: string, platform: string, spawn: SpawnLike): boolean;

package/dist/holmes/cli/open-url.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCommand = openCommand;
+exports.openUrl = openUrl;
+/** `null` when the platform cannot be judged: not opening is better than guessing a command. */
+function openCommand(platform) {
+    if (typeof platform !== 'string' || platform.trim() === '')
+        return null;
+    if (platform === 'darwin')
+        return { file: 'open', args: [] };
+    // `start` reads its first quoted argument as the WINDOW TITLE, so a URL passed without the empty
+    // title becomes a title and nothing opens.
+    if (platform === 'win32')
+        return { file: 'cmd', args: ['/c', 'start', ''] };
+    return { file: 'xdg-open', args: [] };
+}
+/**
+ * True only when the spawn was actually attempted and did not throw.
+ *
+ * A missing browser is the NORMAL case on a headless box, an SSH session or CI. It costs the user
+ * nothing — the URL is already on stdout — so it returns false rather than throwing, and the
+ * caller's exit code does not change.
+ */
+function openUrl(url, platform, spawn) {
+    if (typeof url !== 'string' || url.trim() === '')
+        return false;
+    const cmd = openCommand(platform);
+    if (!cmd)
+        return false;
+    try {
+        // detached + ignored stdio: the browser outlives this process and never holds the terminal.
+        spawn(cmd.file, [...cmd.args, url], { detached: true, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/holmes/cli/report.d.ts

@@ -0,0 +1,20 @@
+export interface ReportOptions {
+    message?: string;
+    open?: boolean;
+    root: string;
+    packageRoot: string;
+    harness?: string;
+}
+export interface ReportIo {
+    write(p: string, c: string): void;
+    mkdir(p: string): void;
+    stdout(s: string): void;
+    readFile(p: string): string;
+    now(): Date;
+    /** Strings that identify this machine or person, injected so a pin can search for them. */
+    identity: string[];
+}
+export declare function runReport(o: ReportOptions, io: ReportIo): {
+    code: number;
+    url: string;
+};

package/dist/holmes/cli/report.js

@@ -0,0 +1,115 @@
+"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.runReport = runReport;
+// @implements A-SPEC-679
+/**
+ * `holmes-kit report` — the surface that finally calls the report composer.
+ *
+ * Two measurements decided what this command can honestly claim. No ledger keeps the product's
+ * refusal text: it is returned to the caller and vanishes, so holmes-kit cannot know what went
+ * wrong. And a report assembled from only what IS auto-fillable — version, harness, OS, node, a
+ * spec id out of a ledger — cannot be triaged; a maintainer receives a version string and a
+ * fingerprint.
+ *
+ * So the human's one sentence IS the report, and everything here is context wrapped around it. That
+ * is still worth having: a pasted transcript leaks paths, spec titles and commit messages and can
+ * never be deduplicated, while this carries a redacted context and a fingerprint that recognises
+ * the same defect reported by someone else.
+ *
+ * Nothing here reaches the network. Opening a browser is the caller's act, which keeps this module
+ * pure enough to pin and keeps "going out" a decision a person makes.
+ */
+const path = __importStar(require("node:path"));
+const field_report_1 = require("../project/field-report");
+const field_report_url_1 = require("../project/field-report-url");
+const reported_log_1 = require("./reported-log");
+/** `unknown` rather than an empty string: a blank version reads as a version we know to be blank. */
+const versionOf = (io, packageRoot) => {
+    try {
+        return String(JSON.parse(io.readFile(path.join(packageRoot, 'package.json'))).version ?? 'unknown');
+    }
+    catch {
+        return 'unknown';
+    }
+};
+function runReport(o, io) {
+    const described = typeof o.message === 'string' && o.message.trim() !== '';
+    const report = (0, field_report_1.composeFieldReport)({
+        kit: versionOf(io, o.packageRoot),
+        harness: o.harness ?? 'unknown',
+        os: process.platform,
+        arch: process.arch,
+        node: process.version,
+        ...(described ? { message: o.message.trim() } : {}),
+        identity: io.identity,
+    });
+    let body = (0, field_report_1.fieldReportBody)(report);
+    if (!described) {
+        // Incomplete, not failed. A quiet empty report hands a maintainer a version string and calls it
+        // a bug report; saying so is the difference between a report and a shrug.
+        body += '\n\nno description was given — rerun with `--message "<what happened>"`; holmes-kit cannot'
+            + ' recover what it said to you, because no ledger keeps its refusal text.';
+    }
+    const dir = path.join(o.root, '.ax', 'reports');
+    const file = path.join(dir, `${report.fingerprint}.md`);
+    io.mkdir(dir);
+    io.write(file, `${body}\n`);
+    // @implements A-SPEC-679 — leave the fingerprint of THIS report, so a future briefing can match it.
+    // Best-effort: a log problem must never fail the report it accompanies.
+    try {
+        const logFile = path.join(dir, 'reported.jsonl');
+        let prior = null;
+        try {
+            prior = io.readFile(logFile);
+        }
+        catch {
+            prior = null;
+        }
+        io.write(logFile, (0, reported_log_1.mergeReported)(prior, { fingerprint: report.fingerprint, kit: report.kit, ts: io.now().toISOString() }).lines);
+    }
+    catch { /* the report itself still stands */ }
+    const url = (0, field_report_url_1.issueUrl)(body, { localPath: file, title: (0, field_report_url_1.issueTitle)(report), assignee: field_report_url_1.ISSUE_ASSIGNEE });
+    io.stdout(`report written: ${file}\n`);
+    io.stdout(`\nopen this to file it (you press Submit, and you can edit the body first):\n${url.url}\n`);
+    io.stdout(`\ncheck whether it is already known:\n${(0, field_report_url_1.searchUrl)(report.fingerprint)}\n`);
+    if (url.truncated)
+        io.stdout('\n(the URL body was truncated; the file above holds the whole report)\n');
+    if (!described)
+        io.stdout('\nno description was given — this report says so rather than pretending.\n');
+    // @implements A-SPEC-680 — the URL is returned rather than rebuilt by the caller: two places
+    // composing it would drift, and the caller needs the exact bytes it printed.
+    return { code: described ? 0 : 2, url: url.url };
+}

package/dist/holmes/cli/reported-log.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What this machine has reported — a SET of fingerprints, not a history.
+ *
+ * It exists for a briefing that does not exist yet: "the thing you reported is fixed in 0.24.0".
+ * That can only work if the fingerprint from the MOMENT of reporting is on disk, because a
+ * fingerprint is derived from content and recomputing one later can disagree — redaction may
+ * withhold a different field next time. A line costs nothing now; without it such a briefing would
+ * stay silent about every report made before it shipped.
+ *
+ * A set rather than a log because the question is "what have I reported", not "when". Reporting the
+ * same defect twice adds nothing.
+ *
+ * Local only. Nothing here sends anything anywhere.
+ */
+export interface ReportedEntry {
+    fingerprint: string;
+    kit: string;
+    ts: string;
+}
+export declare function mergeReported(existing: string | null, entry: ReportedEntry): {
+    lines: string;
+    added: boolean;
+};

package/dist/holmes/cli/reported-log.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeReported = mergeReported;
+function mergeReported(existing, entry) {
+    const kept = [];
+    const seen = new Set();
+    for (const line of (existing ?? '').split('\n')) {
+        const t = line.trim();
+        if (t === '')
+            continue;
+        try {
+            const row = JSON.parse(t);
+            // A row that cannot name a fingerprint cannot answer the question this file exists for.
+            if (typeof row.fingerprint !== 'string' || row.fingerprint === '')
+                continue;
+            if (seen.has(row.fingerprint))
+                continue;
+            seen.add(row.fingerprint);
+            kept.push({ fingerprint: row.fingerprint, kit: String(row.kit ?? ''), ts: String(row.ts ?? '') });
+        }
+        catch {
+            // A torn line is dropped, never fatal: a broken log must not fail the report it accompanies,
+            // the same best-effort rule the workspace registry states for itself.
+            continue;
+        }
+    }
+    const added = !seen.has(entry.fingerprint);
+    if (added)
+        kept.push(entry);
+    return { lines: `${kept.map((e) => JSON.stringify(e)).join('\n')}\n`, added };
+}

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,11 @@ 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';
+import { type AnalysisVerdict } from '../project/analysis-currency';
 export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
+export declare function collectAnalysisCurrency(root: string, changedSources: number): AnalysisVerdict | 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 +42,16 @@ 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;
+    /**
+     * @implements A-SPEC-681 — whether the graph analysis AGENTS.md asks for was run before this
+     * turn's source edits. Absent when the workspace never analysed anything.
+     */
+    analysis?: AnalysisVerdict;
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
     provenance?: {
         ok: boolean;

package/dist/holmes/hooks/stop.js

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
 exports.collectKnownDefects = collectKnownDefects;
+exports.collectAnalysisCurrency = collectAnalysisCurrency;
+exports.collectDistFreshness = collectDistFreshness;
 exports.collectCiVerdicts = collectCiVerdicts;
 exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
@@ -55,6 +57,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 +85,8 @@ 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");
+const analysis_currency_1 = require("../project/analysis-currency");
 // @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 +134,48 @@ function collectKnownDefects(root, now) {
         return undefined;
     }
 }
+// @implements A-SPEC-681 — the I/O half of the analysis line: count the analyses still open against
+// the source files this turn changed. A workspace that never analysed anything did not adopt the
+// discipline and hears nothing; a count that cannot be taken says so rather than passing.
+function collectAnalysisCurrency(root, changedSources) {
+    if (!(0, analysis_currency_1.hasAnalysisDir)(root))
+        return undefined;
+    let openAnalyses = null;
+    try {
+        const { openArtifacts } = require('../mcp/maintenance-evidence');
+        openAnalyses = openArtifacts(path.join(root, '.ax', 'evidence', 'maintenance')).length;
+    }
+    catch {
+        openAnalyses = null;
+    }
+    return (0, analysis_currency_1.analysisCurrency)({ adopted: true, openAnalyses, changedSources });
+}
+// @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 +577,8 @@ const TRACK_LABELS = {
     'ART-2': 'code-graph cycles',
     'ART-9': 'known-defect debt',
     'CI': 'matrix',
+    'DIST': 'build freshness',
+    'ANALYSIS': 'graph analysis',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -602,6 +652,21 @@ 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 }];
+    }
+    // @implements A-SPEC-681 — AGENTS.md step 3 asks for a graph analysis before editing source, and
+    // nothing enforced it: seventeen feat/fix commits ran without one. Observed here, never blocked.
+    if (evidence?.analysis) {
+        const detail = (0, analysis_currency_1.analysisStatusLine)(evidence.analysis);
+        if (detail)
+            tracked = [...(tracked ?? []), { article: 'ANALYSIS', 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 +1259,23 @@ 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;
+            }
+            // @implements A-SPEC-681 — the analysis line rides the same non-blocking channel.
+            let analysis;
+            try {
+                analysis = collectAnalysisCurrency(stopProjectRoot(), (unanchored ?? []).length);
+            }
+            catch {
+                analysis = 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 } : {}), ...(analysis ? { analysis } : {}) });
             // @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