@holmes-lab/holmes-kit 0.25.1 → 0.26.1

package/dist/holmes/hooks/stop.js

@@ -56,6 +56,8 @@ exports.decideStopGuard = decideStopGuard;
 exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
 exports.guardCountOrZero = guardCountOrZero;
 exports.readGuardCount = readGuardCount;
+exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
+exports.scanCodeCycles = scanCodeCycles;
 exports.writeGuardCount = writeGuardCount;
 const fs = __importStar(require("node:fs"));
 // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
@@ -88,6 +90,9 @@ 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");
+const forbidden_edges_1 = require("../cpg/forbidden-edges");
+const forbidden_edge_report_1 = require("../cpg/forbidden-edge-report");
+const cycle_report_1 = require("../cpg/cycle-report");
 // @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
@@ -664,8 +669,10 @@ function evaluateStop(specs, evidence) {
     if (evidence?.cycles !== undefined && evidence.cycles.mode === 'track') {
         const scope = evidence.cycles.scope.unavailable.length > 0
             ? ` (NOT judged: ${evidence.cycles.scope.unavailable.join(', ')})` : '';
-        const t = (0, cycle_detect_1.cycleRatchetViolations)(evidence.cycles.current, evidence.cycles.allowed)
-            .map((x) => ({ article: 'ART-2', detail: `code ${x.detail}${scope}` }));
+        // @implements A-SPEC-694 — rendered through `cycleStatusDetails`, which bounds the line: every
+        // detail of an article is joined into ONE line, and a 46-member cycle was measured in this tree.
+        const t = (0, cycle_report_1.cycleStatusDetails)((0, cycle_detect_1.cycleRatchetViolations)(evidence.cycles.current, evidence.cycles.allowed), scope)
+            .map((detail) => ({ article: 'ART-2', detail }));
         if (t.length)
             tracked = [...(tracked ?? []), ...t];
     }
@@ -699,6 +706,15 @@ function evaluateStop(specs, evidence) {
         if (detail)
             tracked = [...(tracked ?? []), { article: 'ANALYSIS', detail }];
     }
+    // @implements A-SPEC-693 — the declared architecture's verdict rides the same non-blocking channel.
+    // Blocking is the pre-edit gate's job and an expired baseline is never a block (owner decision,
+    // 2026-09-19); what was missing is that nobody could SEE a violation, an expiry or an unjudged
+    // language. Never enters `problems`.
+    if (evidence?.forbiddenEdges) {
+        const t = (0, forbidden_edge_report_1.forbiddenEdgeStatusLines)(evidence.forbiddenEdges).map((detail) => ({ article: 'ARCH', detail }));
+        if (t.length)
+            tracked = [...(tracked ?? []), ...t];
+    }
     // @implements A-SPEC-683 — the vector-coverage line rides the same non-blocking channel. It is a
     // STRING here, not a verdict object: the hook read what the refresh child wrote and has nothing
     // to judge. An absent verdict already reads as "not run" inside coverageStopLine.
@@ -1018,6 +1034,120 @@ function readGuardCount(sessionId) {
  * Exported for the §19 race discriminator: the persistence layer was the untested half (round-11),
  * and a test that can only reach it through a spawned hook cannot pin what the lock does.
  */
+/**
+ * @implements A-SPEC-688
+ * Type erasure is a TypeScript fact, not a universal one.
+ *
+ * `classifyEdgeByTarget` reads TS syntax to decide whether an import survives into the emit. Python,
+ * Go, Java, C#, Rust and C++ have no erasure — every import there is an eager runtime dependency —
+ * so running a TS-syntax detector over their source can only mislabel. REQ-574 sorted cycles into
+ * (a) type-erasable, (b) lazy require and (c) eager value; category (a) does not exist in these
+ * languages, so the classification is not consulted and the edge is eager by construction.
+ */
+// @implements A-SPEC-693 — the gate is "can the classifier READ this syntax", not "does this language
+// erase types". The classifier reads `require()` and `from`, which is the whole JS family; gating on
+// erasure alone switched it off for `.js/.cjs/.mjs/.jsx` and REQ-574's category (b), lazy require,
+// stopped being recorded there. The other languages stay eager by construction, as above.
+const CLASSIFIER_READS = /\.[cm]?[jt]sx?$/;
+function kindOfEdge(text, from, to) {
+    return CLASSIFIER_READS.test(from) ? (0, cycle_detect_1.classifyEdgeByTarget)(text, from, to) : 'eager-value';
+}
+/**
+ * @implements A-SPEC-693
+ * The scan-wide forbidden-edge judgement, over the SAME rules the pre-edit gate reads: approved
+ * C-SPECs only, rules and baselines out of one parse of one section.
+ *
+ * Returns `undefined` when no rule is declared — the project never adopted this, so it pays nothing
+ * and hears nothing. The scan is handed in rather than made here: the Stop hook already scans once a
+ * turn for the cycle ratchet, and scanning is that hook's dominant cost.
+ */
+function collectForbiddenEdgeJudgement(specs, scanned, now) {
+    const rules = [];
+    const baselines = [];
+    for (const sp of specs) {
+        if (sp.type !== 'C-SPEC' || sp.status !== 'approved')
+            continue;
+        const parsed = (0, forbidden_edges_1.parseForbiddenEdges)(sp.sections?.['Forbidden Edges'] ?? '');
+        rules.push(...parsed.rules);
+        baselines.push(...parsed.baselines);
+    }
+    if (rules.length === 0)
+        return undefined;
+    return (0, forbidden_edges_1.judgeForbiddenEdges)(scanned, rules, { baselines, now });
+}
+/**
+ * @implements A-SPEC-688
+ * The code graph's cycles, judged where the code exists — extracted from the hook body so the
+ * judgement is observable without driving a whole Stop turn.
+ *
+ * Returns `undefined` when the scan could not run at all. That is NOT "no cycles": the caller must
+ * keep the article silent rather than report a clean tree, because "we could not look" and "there
+ * is nothing there" are different facts (REQ-574).
+ *
+ * @implements A-SPEC-693 — `shared` is a scan the caller already made. When given it is BELIEVED
+ * and no second scan runs, so one turn pays for one scan however many judgements read it.
+ */
+function scanCodeCycles(root, shared) {
+    try {
+        const { CpgScanner } = require('../cpg/cpg-scanner');
+        const { createImportResolver } = require('../cpg/import-resolver');
+        const scanned = shared ?? new CpgScanner().scan(root, root);
+        // The resolver the graph builder uses. Re-deriving it here is what made seven language
+        // families read as `unavailable` while the tree could already resolve them.
+        const resolver = createImportResolver(scanned);
+        const edges = [];
+        const judged = new Set();
+        const sawImports = new Set();
+        for (const f of scanned) {
+            const ext = f.sourcePath.slice(f.sourcePath.lastIndexOf('.'));
+            let text = '';
+            try {
+                text = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            let sawImport = false;
+            for (const e of f.edges ?? []) {
+                if (e.rel !== 'imports' || !e.to)
+                    continue;
+                sawImport = true;
+                // Go: a package specifier names every file of the package, so one specifier is many edges.
+                // The ratchet must see the same graph the builder does, or the two disagree about cycles.
+                const targets = [...resolver.fanOut(f.sourcePath, e.to)];
+                const single = targets.length === 0 ? resolver.resolve(f.sourcePath, e.to) : null;
+                if (single !== null)
+                    targets.push(single);
+                for (const to of targets) {
+                    if (to === f.sourcePath)
+                        continue;
+                    edges.push({ from: f.sourcePath, to, kind: kindOfEdge(text, f.sourcePath, to) });
+                    judged.add(ext);
+                }
+            }
+            // A file whose imports are all bare specifiers is not evidence that its LANGUAGE is
+            // unresolvable — subtract the judged set at the end instead of marking per file, or one
+            // such file makes the whole language read as unjudged (measured: `.ts` and `.js` landed in
+            // both lists).
+            if (sawImport)
+                sawImports.add(ext);
+        }
+        return {
+            current: (0, cycle_detect_1.detectCycles)(edges).cycles,
+            allowed: [],
+            mode: 'track',
+            // Unjudged = saw imports, resolved none, anywhere. Naming these is the difference between
+            // "no cycles" and "no cycles in the languages we could follow".
+            scope: {
+                judged: [...judged].sort(),
+                unavailable: [...sawImports].filter((e) => !judged.has(e)).sort(),
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 function writeGuardCount(sessionId, n) {
     // @implements A-SPEC-191 §19 — no project, no state. Minting `<cwd>/.ax` to hold a counter is how
     // the gate lost the project in the first place; returning false puts the caller on the stateless
@@ -1145,56 +1275,41 @@ if (require.main === module) {
             // import edge starts from. Fail-open in every direction: any error leaves the article silent,
             // because "we could not look" must never be reported as "there is nothing there".
             let cycles;
+            // @implements A-SPEC-693 — ONE scan a turn, read by both judgements below. A scan that cannot
+            // run leaves both silent; neither judgement scans again on its own.
+            let sharedScan;
             try {
-                const root = stopProjectRoot();
                 const { CpgScanner } = require('../cpg/cpg-scanner');
-                const scanned = new CpgScanner().scan(root, root);
-                const known = new Set(scanned.map((f) => f.sourcePath));
-                const edges = [];
-                const judged = new Set();
-                const sawImports = new Set();
-                for (const f of scanned) {
-                    const ext = f.sourcePath.slice(f.sourcePath.lastIndexOf('.'));
-                    let text = '';
-                    try {
-                        text = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
-                    }
-                    catch {
-                        continue;
-                    }
-                    let sawImport = false;
-                    for (const e of f.edges ?? []) {
-                        if (e.rel !== 'imports' || !e.to)
-                            continue;
-                        sawImport = true;
-                        if (!e.to.startsWith('.'))
-                            continue;
-                        const base = path.posix.normalize(path.posix.join(path.posix.dirname(f.sourcePath), e.to));
-                        const to = ['.ts', '.tsx', '.js', '/index.ts'].map((x) => base + x).find((c) => known.has(c))
-                            ?? (known.has(base) ? base : null);
-                        if (to === null || to === f.sourcePath)
-                            continue;
-                        edges.push({ from: f.sourcePath, to, kind: (0, cycle_detect_1.classifyEdgeByTarget)(text, f.sourcePath, to) });
-                        judged.add(ext);
-                    }
-                    // A file whose imports are all bare specifiers is not evidence that its LANGUAGE is
-                    // unresolvable — subtract the judged set at the end instead of marking per file, or one
-                    // such file makes the whole language read as unjudged (measured: `.ts` and `.js` landed in
-                    // both lists).
-                    if (sawImport)
-                        sawImports.add(ext);
+                sharedScan = new CpgScanner().scan(stopProjectRoot(), stopProjectRoot());
+            }
+            catch {
+                sharedScan = undefined;
+            }
+            // Its OWN try, like the observation below: a fault in the architecture judgement must not
+            // discard the cycle evidence, nor the other way round.
+            let forbiddenEdges;
+            try {
+                if (sharedScan !== undefined)
+                    forbiddenEdges = collectForbiddenEdgeJudgement(specs, sharedScan, new Date());
+            }
+            catch {
+                forbiddenEdges = undefined;
+            }
+            try {
+                const root = stopProjectRoot();
+                if (sharedScan === undefined)
+                    throw new Error('cycle scan unavailable');
+                cycles = scanCodeCycles(root, sharedScan);
+                if (cycles === undefined)
+                    throw new Error('cycle scan unavailable');
+                // @implements A-SPEC-694 — the named exception A-SPEC-574.4 promised finally has a source.
+                // A config that cannot be read excepts NOTHING: this list must never fail toward wider.
+                try {
+                    cycles.allowed = (0, cycle_report_1.ignoredCycleKeys)(cycles.current, (0, config_1.loadConfig)(root).architecture.cycleIgnore);
+                }
+                catch {
+                    cycles.allowed = [];
                 }
-                cycles = {
-                    current: (0, cycle_detect_1.detectCycles)(edges).cycles,
-                    allowed: [],
-                    mode: 'track',
-                    // Unjudged = saw imports, resolved none, anywhere. Naming these is the difference between
-                    // "no cycles" and "no cycles in the languages we could follow".
-                    scope: {
-                        judged: [...judged].sort(),
-                        unavailable: [...sawImports].filter((e) => !judged.has(e)).sort(),
-                    },
-                };
                 // @implements A-SPEC-578.1 — record the observation the promotion criterion waits on.
                 // EVERY run, including a clean one: a false-positive rate is violations over chances, and a
                 // ledger that only speaks when something is wrong keeps the numerator and drops the
@@ -1322,7 +1437,11 @@ if (require.main === module) {
             catch {
                 semantic = 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 } : {}), ...(semantic ? { semantic } : {}) });
+            // @implements A-SPEC-694 — `cycles` rides in the evidence below. It was computed and written
+            // to the observation ledger from the founding commit on (071bbf0c) and never handed over, so
+            // the ART-2 track branch and the constitution's strict branch were dead code in the product:
+            // the ratchet had never spoken to anyone. The mode it carries is still the constant `track`.
+            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 } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
             // @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/handlers/entity-integration.js

@@ -36,13 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renumberedMappingInputs = renumberedMappingInputs;
 exports.integrationSealTransitions = integrationSealTransitions;
 exports.createEntityIntegrationHandlers = createEntityIntegrationHandlers;
-// @implements A-SPEC-629
-// @implements A-SPEC-645
-// @implements A-SPEC-642
-// @implements A-SPEC-639
-// @implements A-SPEC-632
-// @implements A-SPEC-635
-const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const entity_store_1 = require("../../spec/entity-store");
 const root_1 = require("../../project/root");
@@ -129,7 +122,11 @@ function createEntityIntegrationHandlers(context) {
                 if (!context.storeRoot)
                     throw new entity_store_1.EntityStoreError('unsupported-store', 'Git integration requires a configured filesystem spec store.');
                 const bound = (0, entity_store_1.entityStoreBinding)(context.storeRoot);
-                if (a.root !== undefined && fs.realpathSync((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root) !== bound.root)
+                // @implements A-SPEC-692 — `bound.root` is already canonical (A-SPEC-651.1 says so in as
+                // many words); the JS `fs.realpathSync` that stood on this side is not, and it leaves a
+                // Windows 8.3 alias spelled as it arrived. The same workspace then read as foreign.
+                // `sameCanonicalDirectory` exists for exactly this comparison — one canonicaliser, both sides.
+                if (a.root !== undefined && !(0, root_1.sameCanonicalDirectory)((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root, bound.root))
                     throw new entity_store_1.EntityStoreError('foreign-workspace', 'The requested workspace differs from the configured store.');
                 const recoveryTarget = (plan) => 'entity-store:integrate-recover:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan));
                 const requireStore = (plan) => {

package/dist/holmes/mcp/handlers/entity-renumber.js

@@ -34,10 +34,6 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEntityRenumberHandlers = createEntityRenumberHandlers;
-// @implements A-SPEC-628
-// @implements A-SPEC-642
-// @implements A-SPEC-639
-const fs = __importStar(require("node:fs"));
 const entity_store_1 = require("../../spec/entity-store");
 const entity_renumber_1 = require("../../spec/entity-renumber");
 const root_1 = require("../../project/root");
@@ -56,7 +52,10 @@ function createEntityRenumberHandlers(context) {
                 if (!context.storeRoot)
                     throw new entity_store_1.EntityStoreError('unsupported-store', 'Entity renumbering requires a configured filesystem spec store.');
                 const bound = (0, entity_store_1.entityStoreBinding)(context.storeRoot);
-                if (a.root !== undefined && fs.realpathSync((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root) !== bound.root)
+                // @implements A-SPEC-692 — one canonicaliser on both sides; see the twin in
+                // `entity-integration.ts`. `bound.root` is canonical, so this side must be too, or an 8.3
+                // spelling of the SAME workspace is refused as foreign.
+                if (a.root !== undefined && !(0, root_1.sameCanonicalDirectory)((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root, bound.root))
                     throw new entity_store_1.EntityStoreError('foreign-workspace', 'The requested workspace differs from the configured store.');
                 if (a.operation === 'recovery-plan')
                     return { ok: true, plan: (0, entity_renumber_transaction_1.planEntityRenumberRecovery)(context.storeRoot) };

package/dist/holmes/mcp/handlers/spec-authoring.js

@@ -42,6 +42,7 @@ const validator_1 = require("../../spec/validator");
 const spec_types_1 = require("../../spec/spec-types");
 const legacy_format_1 = require("../../spec/legacy-format");
 const write_target_1 = require("../../guardrail/write-target");
+const root_1 = require("../../project/root");
 const spec_id_guard_1 = require("../spec-id-guard");
 function createSpecAuthoringHandlers(context) {
     const { store, projectRootOf, resolver } = context;
@@ -105,8 +106,15 @@ function createSpecAuthoringHandlers(context) {
             // deployments refuse their own root. It is "you named a project that already exists, and my
             // store is not inside it", which is true whatever the specs directory is called.
             if (typeof reqRoot === 'string' && reqRoot !== '' && derivedForCreate === null && boundSpecsRoot !== null) {
+                // @implements A-SPEC-692 — BOTH sides of this comparison go through ONE canonicaliser.
+                // `projectRootOf` below already expands Windows 8.3 aliases (it ends in `canonicalPath`,
+                // i.e. `realpathSync.native`); the JS `fs.realpathSync` that used to stand here does not.
+                // So the same directory arrived under two spellings and the containment test said "another
+                // project": measured 2026-09-19, `C:\Users\SUNGNA~1\…\probe83` was refused while
+                // `C:\Users\SungNam Park\…\probe83` — the same directory — created. `change-source.ts`
+                // named this rule on 2026-08-23 after the identical failure; this is the same rule, here.
                 const real = (p2) => { try {
-                    return fs.realpathSync(p2);
+                    return (0, root_1.canonicalPath)(p2);
                 }
                 catch {
                     return path.resolve(p2);

package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts

@@ -70,20 +70,22 @@ export declare function createSpecLifecycleHandlers(context: SpecLifecycleContex
         newBase: string;
         dryRun?: boolean;
     }): Promise<{
+        unreadable?: string[] | undefined;
+        ok: boolean;
+        reason: string;
+        dryRun?: undefined;
+        plan?: undefined;
+        movedSpecs?: undefined;
+    } | {
         ok: boolean;
         dryRun: boolean;
         plan: import("../../spec/renumber").RenumberPlan;
-        reason?: undefined;
         movedSpecs?: undefined;
     } | {
         ok: boolean;
         dryRun: boolean;
         movedSpecs: number;
         plan: import("../../spec/renumber").RenumberPlan;
-        reason?: undefined;
-    } | {
-        ok: boolean;
-        reason: string;
     }>;
     /**
      * @implements A-SPEC-538.1

package/dist/holmes/mcp/handlers/spec-lifecycle.js

@@ -181,13 +181,26 @@ function createSpecLifecycleHandlers(context) {
                     }
                 }
                 const projectRoot = path.resolve(specsRoot, '..', '..');
+                const read = (0, renumber_1.readSpecsForRenumber)(specsRoot);
                 const plan = (0, renumber_1.planRenumber)({
-                    specs: (0, renumber_1.readSpecsForRenumber)(specsRoot),
+                    specs: read.specs,
                     sources: (0, renumber_1.readSourcesForRenumber)(projectRoot),
                     oldBase: String(a.oldBase), newBase: String(a.newBase),
                 });
+                // @implements A-SPEC-699 — a refusal that cannot say whether the store was empty or merely
+                // unreadable sends the caller to the source. Measured 2026-09-20: this tool answered
+                // "nothing to move" while 300-odd specs sat in front of it, and the answer alone could not
+                // distinguish the two. Carry the counts, and name the files while there are few.
                 if (plan.refusal)
-                    return { ok: false, reason: plan.refusal };
+                    return {
+                        ok: false,
+                        reason: plan.refusal
+                            + ` (읽은 스펙 ${read.specs.length}개`
+                            + (read.unreadable.length > 0
+                                ? `, 프론트매터를 읽지 못한 파일 ${read.unreadable.length}개: ${read.unreadable.slice(0, 5).join(', ')}${read.unreadable.length > 5 ? ' …' : ''})`
+                                : ')'),
+                        ...(read.unreadable.length > 0 ? { unreadable: read.unreadable } : {}),
+                    };
                 if (a.dryRun !== false)
                     return { ok: true, dryRun: true, plan };
                 // @implements A-SPEC-638 — in a registered workspace the raw publication is preceded by a

package/dist/holmes/mcp/handlers.d.ts

@@ -728,20 +728,22 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         newBase: string;
         dryRun?: boolean;
     }) => Promise<{
+        unreadable?: string[] | undefined;
+        ok: boolean;
+        reason: string;
+        dryRun?: undefined;
+        plan?: undefined;
+        movedSpecs?: undefined;
+    } | {
         ok: boolean;
         dryRun: boolean;
         plan: import("../spec/renumber").RenumberPlan;
-        reason?: undefined;
         movedSpecs?: undefined;
     } | {
         ok: boolean;
         dryRun: boolean;
         movedSpecs: number;
         plan: import("../spec/renumber").RenumberPlan;
-        reason?: undefined;
-    } | {
-        ok: boolean;
-        reason: string;
     }>;
     spec_unseal: (a: {
         root?: string;

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

@@ -0,0 +1,48 @@
+/**
+ * The other end of the loop `holmes-kit report` opened.
+ *
+ * `report` writes every fingerprint this machine reported into `.ax/reports/reported.jsonl`, and
+ * until now nothing read it — the file's own header said it existed "for a briefing that does not
+ * exist yet". So the set accumulated on consumers' disks while the person who took the trouble to
+ * report a defect learned nothing when it was fixed.
+ *
+ * The match is a **local set intersection**: a file this machine wrote against a list that shipped
+ * in the package. Nothing is sent, nothing is requested, and there is no device id and no MAC
+ * address — a fingerprint identifies a DEFECT, not a person, which is why it can do this job at all.
+ *
+ * PURE. Every input is passed in; the caller owns the filesystem and the clock.
+ */
+import type { ResolvedReport } from './resolved-reports';
+export interface BriefingInput {
+    reported: ReadonlyArray<{
+        fingerprint: string;
+    }>;
+    resolved: ReadonlyArray<ResolvedReport>;
+    /** The version running now. */
+    installed: string;
+    /** Versions this installation's code contains — the installed one and everything before it. */
+    shipped: ReadonlyArray<string>;
+    announced: ReadonlySet<string>;
+}
+/**
+ * Lines to say, or none.
+ *
+ * A fingerprint is briefed when this machine reported it, the list resolves it, the resolving
+ * version is one this installation actually CONTAINS, and it has not been said before.
+ *
+ * "Contains" is membership in the shipped list, not semver arithmetic: the question is whether the
+ * consumer is running the fix, and a list of released versions answers that without this module
+ * having to know how versions compare.
+ */
+export declare function briefingLines(input: BriefingInput): string[];
+/** Tolerant: one unparseable line must not take the rest of the set down. */
+export declare function reportedFrom(raw: string | null): Array<{
+    fingerprint: string;
+}>;
+/**
+ * An unreadable marker yields an EMPTY set on purpose: the briefing then speaks. Hearing it twice
+ * is a smaller harm than a consumer who never hears it, and that is the rule the tier invitation
+ * follows for the same reason.
+ */
+export declare function announcedFrom(raw: string | null): Set<string>;
+export declare function announcedTo(set: ReadonlySet<string>): string;

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.briefingLines = briefingLines;
+exports.reportedFrom = reportedFrom;
+exports.announcedFrom = announcedFrom;
+exports.announcedTo = announcedTo;
+/**
+ * Lines to say, or none.
+ *
+ * A fingerprint is briefed when this machine reported it, the list resolves it, the resolving
+ * version is one this installation actually CONTAINS, and it has not been said before.
+ *
+ * "Contains" is membership in the shipped list, not semver arithmetic: the question is whether the
+ * consumer is running the fix, and a list of released versions answers that without this module
+ * having to know how versions compare.
+ */
+function briefingLines(input) {
+    const mine = new Set(input.reported.map((r) => r.fingerprint).filter((f) => typeof f === 'string' && f !== ''));
+    const has = new Set([...input.shipped, input.installed]);
+    const out = [];
+    for (const r of input.resolved) {
+        if (!mine.has(r.fingerprint))
+            continue; // not ours — this is not a release-notes feed
+        if (!has.has(r.version))
+            continue; // not running the fix yet; the update notice owns that
+        if (input.announced.has(r.fingerprint))
+            continue; // once is once
+        out.push(`a defect you reported (${r.fingerprint}) was fixed in ${r.version} — ${r.note}`);
+    }
+    return out;
+}
+/** Tolerant: one unparseable line must not take the rest of the set down. */
+function reportedFrom(raw) {
+    if (raw === null)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (t === '')
+            continue;
+        try {
+            const o = JSON.parse(t);
+            if (typeof o.fingerprint === 'string' && o.fingerprint !== '')
+                out.push({ fingerprint: o.fingerprint });
+        }
+        catch { /* a malformed line is skipped, never fatal */ }
+    }
+    return out;
+}
+/**
+ * An unreadable marker yields an EMPTY set on purpose: the briefing then speaks. Hearing it twice
+ * is a smaller harm than a consumer who never hears it, and that is the rule the tier invitation
+ * follows for the same reason.
+ */
+function announcedFrom(raw) {
+    if (raw === null)
+        return new Set();
+    try {
+        const o = JSON.parse(raw);
+        if (!Array.isArray(o.announced))
+            return new Set();
+        return new Set(o.announced.filter((x) => typeof x === 'string' && x !== ''));
+    }
+    catch {
+        return new Set();
+    }
+}
+function announcedTo(set) {
+    return JSON.stringify({ announced: [...set].sort() }, null, 2) + '\n';
+}

package/dist/holmes/project/resolved-reports.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Field reports this project has resolved, and the version that resolved them.
+ *
+ * A DATA MODULE rather than a JSON file: TypeScript compiles it into `dist/` automatically, so it
+ * ships with no change to `package.json`'s `files` and no build step anyone can forget.
+ *
+ * The fingerprint is the one that appeared in the report — `advisoryId`-shaped, the first 16 hex of
+ * a sha256 over the canonical report. It identifies a DEFECT, never a person or a machine.
+ *
+ * This list is kept alive by the publish ritual, not by a command: before cutting a release the
+ * playbook asks for the fingerprints that release resolved. A command nobody runs would leave this
+ * empty and the briefing permanently silent, and this repository already records six instruments
+ * that were built and never consumed.
+ */
+export interface ResolvedReport {
+    fingerprint: string;
+    version: string;
+    note: string;
+}
+export declare const RESOLVED_REPORTS: ReadonlyArray<ResolvedReport>;

package/dist/holmes/project/resolved-reports.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOLVED_REPORTS = void 0;
+exports.RESOLVED_REPORTS = [
+// Empty until a field report is resolved. The briefing is silent while it is, which is correct:
+// no consumer has reported anything this project has since fixed.
+];

package/dist/holmes/project/root.js

@@ -86,7 +86,17 @@ function cleanSubprocessEnv(env = process.env) {
 // elicitation path — 9 elicitation tests red on a tree whose full suite was green, twice, and
 // identically on the previous commit. A posture is an approval channel, never a property of the code
 // under test; an evidence run must judge the same in an autonomous workspace and a human-gated one.
-const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL']);
+// @implements A-SPEC-695
+// `NPM_CONFIG_DRY_RUN` is the fourth of the same family and the first that is not ours. Measured
+// 2026-09-20: `npm publish --dry-run` — the command the publish playbook itself prescribes — exports
+// `npm_config_dry_run=true` to `prepublishOnly`; the release gate handed it to jest; and the
+// mcp-launcher suite's own `npx -p <tarball>` then installed NOTHING, so the handshake returned null
+// and the gate refused a green tree twice with "this source is not publishable". Load was suspected
+// first (load 38, the Linux CI running); the failure reproduces alone in 0.25 s with the variable set.
+// "Do nothing" is the one npm setting that contradicts what an evidence run is for. It is named, not
+// swept: a `/^npm_config_/` sweep would take the registry, the cache and the proxy with it, and a
+// suite behind a private registry would go red for a reason that has nothing to do with the tree.
+const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL', 'NPM_CONFIG_DRY_RUN']);
 function cleanTestEnv(env = process.env) {
     const cleaned = cleanSubprocessEnv(env);
     for (const k of Object.keys(cleaned)) {