@holmes-lab/holmes-kit 0.23.3 → 0.24.1

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/stop.d.ts

@@ -4,7 +4,9 @@ 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[];
 /**
@@ -45,6 +47,11 @@ export interface StopEvidence {
      * 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,7 @@ 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;
@@ -85,6 +86,7 @@ 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
@@ -132,6 +134,22 @@ 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.
@@ -560,6 +578,7 @@ const TRACK_LABELS = {
     'ART-9': 'known-defect debt',
     'CI': 'matrix',
     'DIST': 'build freshness',
+    'ANALYSIS': 'graph analysis',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -641,6 +660,13 @@ function evaluateStop(specs, evidence) {
         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.
@@ -1241,7 +1267,15 @@ if (require.main === module) {
             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-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/project/analysis-currency.d.ts

@@ -0,0 +1,22 @@
+export type AnalysisState = 'analysed' | 'missing' | 'not-adopted' | 'unknown';
+export interface AnalysisVerdict {
+    state: AnalysisState;
+    openCount: number | null;
+    changedSources: number;
+}
+export interface AnalysisInput {
+    adopted: boolean;
+    openAnalyses: number | null;
+    changedSources: number;
+}
+/** Adoption is the directory's existence. A project that never analysed anything did not opt in. */
+export declare function hasAnalysisDir(root: string): boolean;
+/**
+ * Judged by COMMIT, never by clock. "An analysis within N hours" is an invented constant that turns
+ * a slow slice into a violation; what matters is whether an analysis stands open for the work that
+ * changed these files, which is exactly what `test_run` closes when it reconciles a persisted
+ * analysis against the files a slice actually touched.
+ */
+export declare function analysisCurrency(input: AnalysisInput): AnalysisVerdict;
+/** Empty when there is nothing to say; the two unjudgeable states say so rather than passing. */
+export declare function analysisStatusLine(v: AnalysisVerdict): string;

package/dist/holmes/project/analysis-currency.js

@@ -0,0 +1,96 @@
+"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.hasAnalysisDir = hasAnalysisDir;
+exports.analysisCurrency = analysisCurrency;
+exports.analysisStatusLine = analysisStatusLine;
+// @implements A-SPEC-681
+/**
+ * Whether the graph analysis this project's own instructions require was actually run.
+ *
+ * `AGENTS.md` step 3 asks for `maintenance_analyze({persist:true})` before editing source, and
+ * nothing enforced it: measured 2026-09-19, the last persisted analysis was at 10:52 the previous
+ * day and seventeen feat/fix commits followed it with none. A user had to point at the gap.
+ *
+ * The cost was concrete. Searching for the precedent for spawning a browser, grep returned a CSS
+ * class named 'open', a d3 'start' event and a schema enum; the analysis returned `wiringSpawnCheck`
+ * and `Supervisor.spawnChild`. The question was "who opens a browser" and the answer lived under
+ * "who spawns a child" — a gap lexical search cannot cross and the graph does not notice.
+ *
+ * This OBSERVES. It does not block, and it never runs the tool on the operator's behalf: analysis is
+ * expensive and what to ask is a person's judgement.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Adoption is the directory's existence. A project that never analysed anything did not opt in. */
+function hasAnalysisDir(root) {
+    try {
+        return fs.statSync(path.join(root, '.ax', 'evidence', 'maintenance')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Judged by COMMIT, never by clock. "An analysis within N hours" is an invented constant that turns
+ * a slow slice into a violation; what matters is whether an analysis stands open for the work that
+ * changed these files, which is exactly what `test_run` closes when it reconciles a persisted
+ * analysis against the files a slice actually touched.
+ */
+function analysisCurrency(input) {
+    const changedSources = typeof input.changedSources === 'number' && Number.isFinite(input.changedSources)
+        ? Math.max(0, input.changedSources) : 0;
+    const open = input.openAnalyses;
+    const base = { openCount: typeof open === 'number' && Number.isFinite(open) ? open : null, changedSources };
+    if (!input.adopted)
+        return { state: 'not-adopted', ...base };
+    // The discipline is about editing source. Nothing changed, nothing to say.
+    if (changedSources === 0)
+        return { state: 'analysed', ...base };
+    if (typeof open !== 'number' || !Number.isFinite(open) || open < 0)
+        return { state: 'unknown', ...base };
+    return { state: open > 0 ? 'analysed' : 'missing', ...base };
+}
+/** Empty when there is nothing to say; the two unjudgeable states say so rather than passing. */
+function analysisStatusLine(v) {
+    if (v.state === 'analysed' || v.state === 'not-adopted')
+        return '';
+    if (v.state === 'unknown') {
+        return 'the persisted analyses could not be counted — whether this change was analysed could not be judged';
+    }
+    const n = v.changedSources;
+    return `${n} source file${n === 1 ? '' : 's'} changed with no analysis standing open — `
+        + 'AGENTS.md step 3 asks for `maintenance_analyze({ persist: true })` first; it finds precedents a name search cannot reach';
+}

package/dist/holmes/project/field-report-url.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The report's way to us: a PREFILLED GitHub issue URL that a person submits on GitHub's own page.
+ *
+ * The alternative — holmes-kit holding a token and posting through the API — was rejected for a
+ * measured reason, not a stylistic one. Consent is the weakest link here: the first field report of
+ * the approval queue counted 1,412 unique requests against 8 decisions, 99.4% undecided. A yes/no
+ * buried in a stream of prompts is not a decision, and a user consents to "report this" without
+ * reading forty lines of body.
+ *
+ * A URL moves the decision to where the bytes are visible. The person sees the whole body in
+ * GitHub's own editor, can change it, and cancelling costs nothing — closing the tab is the entire
+ * undo. Four consequences follow structurally rather than by discipline: no token exists to leak,
+ * nothing can be sent silently, there is no auth/rate-limit/retry surface, and this module cannot
+ * exfiltrate anything because it has no transport at all. It only builds strings.
+ */
+import type { FieldReport } from './field-report';
+export declare const ISSUE_REPO = "holmes-kit/holmes-kit";
+/** Conservative: GitHub accepts more, but a URL that silently fails to open helps nobody. */
+export declare const URL_BUDGET = 8000;
+/**
+ * The repository owner, offered as the default assignee.
+ *
+ * KNOWN LIMIT, stated rather than implied: GitHub honours `assignee=` only when the person filling
+ * the form may assign (write or triage on the repo). A third-party reporter usually cannot, and the
+ * parameter is then dropped silently. It costs nothing either way — it routes when it can and is
+ * discarded when it cannot — but it is not a guarantee, and nobody should plan triage around it.
+ */
+export declare const ISSUE_ASSIGNEE = "sungnamparkkorea-arch";
+export interface UrlOptions {
+    repo?: string;
+    localPath?: string;
+    budget?: number;
+    title?: string;
+    assignee?: string | null;
+}
+/**
+ * The fingerprint rides in the title so a person scanning the issue list recognises a duplicate
+ * without opening anything. The MESSAGE deliberately does not: a title is the most visible place in
+ * the tracker, and `message` is the one allowlisted field whose VALUE can be withheld as unsafe.
+ */
+export declare function issueTitle(r: FieldReport): string;
+export declare function issueUrl(body: string, opts?: UrlOptions): {
+    url: string;
+    truncated: boolean;
+};
+/** Empty in, empty out: a query with no fingerprint lists every issue, which is not a duplicate check. */
+export declare function searchUrl(fingerprint: string, opts?: UrlOptions): string;

package/dist/holmes/project/field-report-url.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ISSUE_ASSIGNEE = exports.URL_BUDGET = exports.ISSUE_REPO = void 0;
+exports.issueTitle = issueTitle;
+exports.issueUrl = issueUrl;
+exports.searchUrl = searchUrl;
+exports.ISSUE_REPO = 'holmes-kit/holmes-kit';
+/** Conservative: GitHub accepts more, but a URL that silently fails to open helps nobody. */
+exports.URL_BUDGET = 8000;
+/**
+ * The repository owner, offered as the default assignee.
+ *
+ * KNOWN LIMIT, stated rather than implied: GitHub honours `assignee=` only when the person filling
+ * the form may assign (write or triage on the repo). A third-party reporter usually cannot, and the
+ * parameter is then dropped silently. It costs nothing either way — it routes when it can and is
+ * discarded when it cannot — but it is not a guarantee, and nobody should plan triage around it.
+ */
+exports.ISSUE_ASSIGNEE = 'sungnamparkkorea-arch';
+/**
+ * The fingerprint rides in the title so a person scanning the issue list recognises a duplicate
+ * without opening anything. The MESSAGE deliberately does not: a title is the most visible place in
+ * the tracker, and `message` is the one allowlisted field whose VALUE can be withheld as unsafe.
+ */
+function issueTitle(r) {
+    const what = r.article || r.tool || 'report';
+    return `holmes-kit ${r.kit}: ${what} (${r.fingerprint.slice(0, 8)})`;
+}
+const NOTE = (localPath) => localPath
+    ? `\n\n— truncated to fit the URL; the full report is at ${localPath}`
+    : '\n\n— truncated to fit the URL; the full report stayed on the reporter\'s machine';
+function issueUrl(body, opts = {}) {
+    const repo = opts.repo ?? exports.ISSUE_REPO;
+    const budget = opts.budget ?? exports.URL_BUDGET;
+    // The title goes in the URL, not just into a helper nobody calls. It was missing here for a
+    // slice: `issueTitle` existed, a pin called it directly, and the product path built `?body=`
+    // alone — so GitHub opened with a blank title. A function pinned in isolation says nothing about
+    // the path that is supposed to feed it.
+    const titlePart = opts.title && opts.title.trim() !== '' ? `title=${encodeURIComponent(opts.title)}&` : '';
+    // Omitted rather than emptied when absent: a fork or an internal mirror must not point at someone
+    // else's account, and `assignee=` with nothing after it is noise in the form.
+    const assigneePart = typeof opts.assignee === 'string' && opts.assignee.trim() !== ''
+        ? `assignee=${encodeURIComponent(opts.assignee.trim())}&` : '';
+    const base = `https://github.com/${repo}/issues/new?${titlePart}${assigneePart}body=`;
+    const build = (text) => base + encodeURIComponent(text);
+    const whole = build(body);
+    if (whole.length <= budget)
+        return { url: whole, truncated: false };
+    // Never a silent cut: the note is part of the body that gets sent, so the reader of the ISSUE — not
+    // just the reporter — learns that something was left out.
+    const note = NOTE(opts.localPath);
+    let keep = body.length;
+    while (keep > 0 && build(body.slice(0, keep) + note).length > budget) {
+        keep = Math.floor(keep * 0.9);
+    }
+    return { url: build(body.slice(0, keep) + note), truncated: true };
+}
+/** Empty in, empty out: a query with no fingerprint lists every issue, which is not a duplicate check. */
+function searchUrl(fingerprint, opts = {}) {
+    if (typeof fingerprint !== 'string' || fingerprint.trim() === '')
+        return '';
+    const repo = opts.repo ?? exports.ISSUE_REPO;
+    return `https://github.com/${repo}/issues?q=${encodeURIComponent(`is:issue ${fingerprint.trim()}`)}`;
+}

package/dist/holmes/project/field-report.d.ts

@@ -0,0 +1,54 @@
+/** The only keys a report may carry. Adding one is an edit here, which the pin makes visible. */
+export declare const FIELD_REPORT_KEYS: readonly ["kit", "harness", "os", "arch", "node", "message", "article", "tool", "specIds", "observations", "fingerprint", "withheld"];
+export interface FieldReportInput {
+    kit: string;
+    harness: string;
+    os: string;
+    arch: string;
+    node: string;
+    message?: string;
+    article?: string;
+    tool?: string;
+    specIds?: string[];
+    observations?: Array<{
+        label: string;
+        value: number;
+    }>;
+    /** Strings that identify this machine or person, injected by the caller so a pin can search for them. */
+    identity?: string[];
+}
+export interface FieldReport {
+    kit: string;
+    harness: string;
+    os: string;
+    arch: string;
+    node: string;
+    message: string;
+    article: string;
+    tool: string;
+    specIds: string[];
+    observations: Array<{
+        label: string;
+        value: number;
+    }>;
+    fingerprint: string;
+    withheld: string[];
+}
+/**
+ * Injected rather than read from `os` here, so a pin can search a composed body for THIS machine's
+ * real values. A module that reads the environment itself can only be tested against fixtures, and
+ * fixtures are exactly what a redaction pin must not trust.
+ *
+ * Tokens shorter than two characters are dropped: a one-character identity would redact every
+ * sentence, which is destruction rather than redaction.
+ */
+export declare function machineIdentity(env: {
+    hostname?: string;
+    username?: string;
+    homedir?: string;
+    replicas?: string[];
+}): string[];
+export declare function isSafeValue(text: string, identity: string[]): boolean;
+export declare function composeFieldReport(input: FieldReportInput): FieldReport;
+/** The bytes a human will read and paste. Anything withheld is named, never dropped in silence. */
+export declare function fieldReportBody(r: FieldReport): string;

package/dist/holmes/project/field-report.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_REPORT_KEYS = void 0;
+exports.machineIdentity = machineIdentity;
+exports.isSafeValue = isSafeValue;
+exports.composeFieldReport = composeFieldReport;
+exports.fieldReportBody = fieldReportBody;
+// @implements A-SPEC-675
+/**
+ * A field report: what a consumer workspace may tell us about a holmes-kit defect.
+ *
+ * There is no channel today. The one field defect we know about — REQ-671, where the AGENTS.md we
+ * ship told agents to author specs with four tools and none of them can write a section body —
+ * reached us because a user pasted a transcript. It reproduced for every consumer on every slice.
+ *
+ * What may be sent is decided by an ALLOWLIST, never by scrubbing. This repository has already been
+ * punctured by a denylist once (the secret-free path rule, holed by UNC paths), and the hazards here
+ * are measured rather than imagined: its replica ids carry a person's name, its homedir carries the
+ * OS username, and its git remote carries a forty-character token before the `@`. That last one is
+ * why an ALLOWED FIELD can still hold a dangerous VALUE — hence two layers, shape and content.
+ *
+ * It never guesses a cause. This module carries what was OBSERVED and leaves the diagnosis to a
+ * person: in one session here, four instrument failures and three confident wrong conclusions were
+ * caught only by re-measuring, and an issue tracker full of confident auto-diagnoses costs a
+ * maintainer more than an empty one.
+ */
+const advisory_outcomes_1 = require("../rtm/advisory-outcomes");
+/** The only keys a report may carry. Adding one is an edit here, which the pin makes visible. */
+exports.FIELD_REPORT_KEYS = ['kit', 'harness', 'os', 'arch', 'node', 'message',
+    'article', 'tool', 'specIds', 'observations', 'fingerprint', 'withheld'];
+/**
+ * Injected rather than read from `os` here, so a pin can search a composed body for THIS machine's
+ * real values. A module that reads the environment itself can only be tested against fixtures, and
+ * fixtures are exactly what a redaction pin must not trust.
+ *
+ * Tokens shorter than two characters are dropped: a one-character identity would redact every
+ * sentence, which is destruction rather than redaction.
+ */
+function machineIdentity(env) {
+    const raw = [env.hostname, env.username, env.homedir, ...(env.replicas ?? [])];
+    return [...new Set(raw.filter((s) => typeof s === 'string' && s.trim().length >= 2).map((s) => s.trim()))];
+}
+const ABSOLUTE_PATH = /(^|[\s"'`(])(\/(?:Users|home|root|var|opt|private)\/|[A-Za-z]:[\\/])/;
+/** `user@host` with a long opaque user is how this repository's own remote carries its token. */
+const CREDENTIAL = /[A-Za-z0-9_.-]{8,}@[A-Za-z0-9.-]+/;
+function isSafeValue(text, identity) {
+    if (typeof text !== 'string' || text === '')
+        return true;
+    if (ABSOLUTE_PATH.test(text) || CREDENTIAL.test(text))
+        return false;
+    const lower = text.toLowerCase();
+    return !identity.some((id) => id.length >= 2 && lower.includes(id.toLowerCase()));
+}
+/** Ids only. A spec TITLE is unreleased product intent and must not ride in on the id field. */
+const SPEC_ID = /^(?:REQ|H-SPEC|A-SPEC|T-SPEC|C-SPEC)-\d+(?:\.\d+)?$/;
+function composeFieldReport(input) {
+    const identity = input.identity ?? [];
+    const withheld = [];
+    const guard = (name, value) => {
+        const v = value ?? '';
+        if (v === '')
+            return '';
+        if (isSafeValue(v, identity))
+            return v;
+        withheld.push(name);
+        return '';
+    };
+    const message = guard('message', input.message);
+    const article = guard('article', input.article);
+    const tool = guard('tool', input.tool);
+    const specIds = (input.specIds ?? []).filter((s) => typeof s === 'string' && SPEC_ID.test(s));
+    // Numbers only: prose in a measurement's place is how a narrative smuggles itself past the
+    // allowlist, and the reports worth having in this repository were always numbers.
+    const observations = (input.observations ?? []).filter((o) => o && typeof o.label === 'string'
+        && typeof o.value === 'number' && Number.isFinite(o.value) && isSafeValue(o.label, identity));
+    const fingerprint = (0, advisory_outcomes_1.advisoryId)('field-report', article || tool || 'unknown', { kit: input.kit, harness: input.harness, os: input.os, message, article, tool, specIds });
+    return {
+        kit: input.kit, harness: input.harness, os: input.os, arch: input.arch, node: input.node,
+        message, article, tool, specIds, observations, fingerprint, withheld,
+    };
+}
+/** The bytes a human will read and paste. Anything withheld is named, never dropped in silence. */
+function fieldReportBody(r) {
+    const lines = [
+        `holmes-kit ${r.kit} · ${r.harness} · ${r.os}/${r.arch} · node ${r.node}`,
+        '',
+        `fingerprint: ${r.fingerprint}`,
+    ];
+    if (r.article)
+        lines.push(`article: ${r.article}`);
+    if (r.tool)
+        lines.push(`tool: ${r.tool}`);
+    if (r.specIds.length > 0)
+        lines.push(`specs: ${r.specIds.join(', ')}`);
+    if (r.message)
+        lines.push('', 'what holmes-kit said:', '', '> ' + r.message);
+    if (r.observations.length > 0) {
+        lines.push('', 'observed:');
+        for (const o of r.observations)
+            lines.push(`- ${o.label}: ${o.value}`);
+    }
+    if (r.withheld.length > 0) {
+        lines.push('', `withheld (contained a path, a credential or a machine identifier): ${r.withheld.join(', ')}`);
+    }
+    lines.push('', 'This report states what was observed. It does not diagnose a cause.');
+    return lines.join('\n');
+}

package/dist/holmes/update/workspaces.d.ts

@@ -9,6 +9,20 @@ export interface Registry {
     version: 1;
     workspaces: WorkspaceEntry[];
 }
+/**
+ * @implements A-SPEC-678
+ * Where the registry lives — with one seam a test can reach.
+ *
+ * Measured 2026-09-18: inside jest, `process.env` is a plain object copy in the sandbox, so
+ * assigning `HOME` never reaches `setenv` and `os.homedir()` keeps answering the developer's real
+ * home. Plain node follows `$HOME`; jest does not. An in-process test therefore cannot isolate a
+ * module that calls `os.homedir()` directly — which is how 599 of this machine's 603 registry
+ * entries came to be test temp directories.
+ *
+ * jest DOES control `process.env`, so one lookup there is the smallest seam that works. Consumers
+ * set nothing and get `os.homedir()`; an empty value is not a setting.
+ */
+export declare function holmesHome(env: NodeJS.ProcessEnv, fallback: string): string;
 export declare const EMPTY_REGISTRY: Registry;
 /**
  * @implements A-SPEC-543.1
@@ -28,8 +42,45 @@ export declare function mergeWorkspaceEntry(reg: Registry, entry: WorkspaceEntry
  * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
  * swallowed (returns false) — a registry problem must never fail the init that feeds it.
  */
-export declare function recordWorkspace(home: string, entry: WorkspaceEntry, io?: {
+/**
+ * @implements A-SPEC-677 — the I/O a recorder needs. `exists` and `tmpdir` are injected so a pin can
+ * judge without depending on this machine's real paths.
+ */
+export interface RecordIo {
     read: (p: string) => string;
     write: (p: string, c: string) => void;
     mkdir: (p: string) => void;
-}): boolean;
+    exists?: (p: string) => boolean;
+    tmpdir?: () => string;
+    onPrune?: (dropped: number) => void;
+}
+/**
+ * @implements A-SPEC-677
+ * Whether a target lives under the OS temp root — and therefore is ephemeral by construction.
+ *
+ * macOS spells that root two ways: `os.tmpdir()` answers `/var/folders/...` while a realpath gives
+ * `/private/var/folders/...`. Both appear in this machine's registry, so both are judged. A `/tmp`
+ * literal would have missed all 599 of them.
+ *
+ * An empty root filters NOTHING. When the judgement cannot be made, keeping an entry costs a line
+ * and dropping one the user wanted costs them something they cannot get back.
+ */
+export declare function isTempTarget(target: string, tmpdir: string): boolean;
+/**
+ * @implements A-SPEC-677
+ * Drop what has certainly gone; COUNT what merely cannot be seen.
+ *
+ * The asymmetry is the whole judgement. A vanished temp path is gone by construction — nothing
+ * re-creates a `mkdtemp` directory. A vanished normal path may be an unmounted volume, an external
+ * disk or a network share, and `upgrade` already skips it harmlessly with one line. Deleting it is
+ * the one outcome the user cannot undo, so absence outside the temp root is reported, never acted on.
+ */
+export declare function pruneRegistry(reg: Registry, p: {
+    exists(t: string): boolean;
+    isTemp(t: string): boolean;
+}): {
+    registry: Registry;
+    dropped: number;
+    absent: number;
+};
+export declare function recordWorkspace(home: string, entry: WorkspaceEntry, io?: RecordIo): boolean;