@holmes-lab/holmes-kit 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -5,6 +5,105 @@ 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.1.10] - 2026-08-23
+
+Forty-one commits since 0.1.9. Two of the defects below were found only by installing the packed
+tarball into projects outside this repository — the in-repo suite was green over both the whole time.
+
+### Added
+- **C-SPEC structural constraints are enforced at write time (REQ-224…231)**: `## Forbidden Edges`
+  and `## Layer Rules` are parsed and judged against the code property graph, so a banned import or
+  an unmet call obligation is refused as it is written rather than found later. A `draft` C-SPEC
+  enforces nothing — authority, not spelling, decides. The refusal names the rule, the file and the
+  edge, and states what the check does NOT see: control flow, aliased calls, computed specifiers.
+- **Non-Functional obligations are machine-readable (REQ-234/235)**: `- [tag] text` in an H-SPEC's
+  `## Non-Functional` declares an obligation; a T-SPEC case opening `- [tag]` answers it. An
+  unanswered obligation widens the regression tier. Opt-in: prose obligations are not judged, and the
+  tag vocabulary is not a fixed list.
+- **Risk reaches the regression tier (REQ-233)**: a change touching a C-SPEC or an ADR runs full
+  regression. Previously the architecture axis of `assessRisk` returned `hard-hitl` while the same
+  change received the narrowest possible test run.
+- **`spec_retire` (REQ-208…212)**: the only path to a status nothing could previously reach. The
+  2026-04 harness-era generation and the 23 JOB work orders are gone from the store.
+- **Windows Native promoted to Tier 1 (REQ-220)**: path verdicts are read from syntax rather than
+  from `process.platform`, so a drive-letter or UNC path is judged the same way everywhere. See
+  *Unverified* below.
+- **Release provenance gate (REQ-242)**: `npm publish` now refuses a dirty tree, a red suite, or a
+  `dist/` that does not name HEAD, and says which file or value is at fault.
+- **Runtime dependency set is pinned (REQ-236)**: twenty-seven H-SPECs asserted "no new dependency"
+  and nothing checked it. All four declaration surfaces are judged, not just `dependencies`.
+
+### Changed
+Behaviour an existing adopter will notice:
+- **Approval refuses placeholder prose.** A section that is nothing but a `TODO` prompt now blocks
+  approval. Already-approved specs are unaffected — the rule runs at approval time only.
+- **A corrupt guard-state file now blocks instead of passing silently.** If `.ax/ledger/stop-guard.json`
+  is damaged, the Stop gate evaluates as normal rather than yielding.
+- **The regression tier widens** for changes touching architecture documents and for unmet
+  obligations. Expect longer runs on those changes, and a reason that names the cause.
+- **`reverse_scan` reports fewer tests.** Dependencies' own test files are no longer discovered or
+  attributed; on a real 235-file Python codebase this removed 254 of 340.
+- **Install guidance leads with a local install.** `npm install -g` on Windows commonly lands in
+  `C:\Program Files\nodejs` and fails with `EPERM`; the README now documents a user-space prefix
+  instead of elevation, which would run native install scripts with system privileges.
+
+### Fixed
+- **A corrupt state file switched the governance gate off (REQ-237).** Four characters — `null` — in
+  a gitignored file made the Stop hook produce no output and exit 0 on a project with eight article
+  violations. `try { JSON.parse } catch` sees a parse failure, not a parse that succeeds into the
+  wrong shape.
+- **A document that said nothing could be sealed as normative (REQ-240).** An H-SPEC whose every
+  prose section read `TODO` received `status: approved` and a digest. The existing check keyed on an
+  HTML-comment marker that human editing strips.
+- **A dependency's tests counted as the project's coverage (REQ-241).** Source candidates excluded
+  vendor directories; test discovery did not, so three third-party tests were attributed to project
+  clusters.
+- **A trailing space switched No-Spec-No-Code off.** `"src/a.ts "` did not match the extension test,
+  and an unrecognised action passed.
+- **Shell seal bypass closed.** `sed -i`, `perl -i` and `ex` edited governance files without
+  tripping the write gate.
+- **Four ways past a Forbidden Edges ban closed**: dynamic `import()`, `require()`, re-export, and
+  `export *`.
+- **The scan walk is linear.** A 2KB deeply-nested file cost 10,558ms on the write path; depth, not
+  size, was the driver.
+- **Eleven performance budgets were boilerplate.** Four were measured and all four were false —
+  `Standalone execution within <100ms` appeared verbatim on three unrelated subsystems. Numbers now
+  cite a measurement or say none was taken.
+- **A timed-out test left the repository broken for every later run**: a jest timeout does not unwind
+  an async function, so `dist/.build-id` stayed at the value the test writes.
+
+### Unverified
+- **Windows has never been executed.** Tier 1 removed the *unverifiability* of platform verdicts; it
+  did not produce verification. Seventeen assertions are still skipped as POSIX-only and
+  `package.json` declares no `os`.
+- **There is no CI.** The suite has never run outside one macOS machine.
+- Transitive dependency growth, control flow, aliased calls and computed module specifiers are
+  outside what the constraint engine can see — each stated in the refusal that would otherwise read
+  as safety.
+
+<!-- @implements A-SPEC-209 -->
+## [0.1.9] - 2026-08-21
+
+### Added
+- **Quantitative REQ RTM Matrix Grid (REQ-219)**: per-REQ 6-stage counts (H/A/T-SPEC, code files, AST symbols) with an accordion drill-down, replacing the single coverage bar.
+- **REQ-Grouped 6-Stage Pipeline Heatmap (REQ-219)**: trace chains grouped under REQ master blocks with a multi-lens quick filter bar, ending the row repetition of the flat table.
+- **Rich node/edge hover inspector (REQ-219)**: node type, provenance digest, in/out degree and file location on hover across all four graph layouts.
+- **Unmapped Specs tab**: the 155 documents whose `status` falls outside `draft|review|approved|outdated` are now visible and grouped by kind, instead of being invisible while sitting in the headline denominator.
+
+### Changed
+- **Coverage is reported on two axes, not one number**: approval (signed off) and implementation (code anchored) are separate percentages, and specs with a legacy status vocabulary are excluded from both rather than silently scored zero. The fused `coveragePct` field is gone.
+- **Release metadata check is self-consistent**: `packaging.test.ts` asserts that `package.json` version is semver AND has a matching CHANGELOG section, instead of pinning a literal version that went stale on every release.
+
+### Fixed
+- **Fabricated trace chains removed**: rows for REQs with no implementing file were back-filled with `dashboard.ts#startDashboardServer`, producing 64 of 787 traces that named code they do not own. Missing stages now report `null` and are listed in `missingStages`.
+- **Synthesized spec ids removed**: absent H/A/T-SPECs were invented as `H-SPEC-<n>` and rendered indistinguishably from real ones.
+- **Coverage is measured, not asserted**: `status: COVERED` was hardcoded for every matched file; a chain is COVERED only when all six stages resolve.
+- **Mutation score no longer reported as a constant**: `mutationScore: 100` is replaced by `null` with `mutationScoreMeasured: false` — the endpoint generates mutants statically and has no basis for a score.
+- **Findings attribution is exact**: `specRef.includes(numPart)` let `REQ-021` claim a finding filed against `A-SPEC-0219`.
+- **An unscanned audit is distinguished from a clean one**: with no `.ax/ledger/findings.jsonl`, Lens 2 rendered "0 open findings" over every chain. Rows now carry `findingsScanned`.
+- **Silent truncation removed**: `slice(0, 3)` dropped AST symbols in both the API and the drill-down while the badge showed the full count.
+- **Graph truncation is disclosed**: the canvas draws a bounded subgraph (30 of 3544 nodes by default) and now says so with numbers.
+
 ## [0.1.8] - 2026-08-20
 
 ### Added

package/README.md

@@ -51,11 +51,53 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 
 ## ⚡ Quickstart (3-Minute Setup)
 
-### 1. Install CLI
+### 1. Install
+
+Install it into the project you want to govern. This is the path verified end to end — the
+wiring `init` writes uses absolute paths, so a local install works from any directory:
+
+```bash
+npm install --save-dev @holmes-lab/holmes-kit
+```
+
+<details>
+<summary>Prefer one install for many projects? (<code>npm install -g</code>)</summary>
+
+A global install works too, but **do not elevate to get it**. Where npm puts global packages is
+your npm configuration, not ours — and on Windows it often points inside the Node.js installation
+directory:
+
+```text
+npm error code EPERM
+npm error path C:\Program Files\nodejs\node_modules\@holmes-lab
+```
+
+Running the install as Administrator would "fix" that by executing this package's native
+dependency install scripts with system privileges. Point npm at a user-writable prefix instead:
+
+```powershell
+npm config set prefix "$env:APPDATA\npm"          # Windows
+# then ensure %APPDATA%\npm is on PATH
+```
 ```bash
-npm install -g @holmes-lab/holmes-kit
+npm config set prefix "$HOME/.npm-global"          # macOS / Linux
+export PATH="$HOME/.npm-global/bin:$PATH"
 ```
-*(Prerequisites: Node.js `>= 20.0.0`. Prebuilt binaries are provided automatically for macOS, Linux, and Windows. For minimal Alpine Docker containers, install build tools: `apk add --no-cache python3 make g++`)*
+
+A Node version manager (`nvm`, `fnm`, `volta`) does the same thing by keeping the whole
+toolchain under your home directory.
+</details>
+
+**Prerequisites** — Node.js `>= 20.0.0`, plus a native binary for two kinds of dependency:
+
+| Dependency | How the binary arrives |
+|---|---|
+| 8 tree-sitter grammars | Prebuilt binaries ship inside the packages (`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) — nothing is compiled |
+| `better-sqlite3` | Downloaded at install time by `prebuild-install`, **falling back to compiling** if no prebuild matches your platform and Node ABI |
+
+Only the second can require a toolchain. If it has to compile, you need a C++ build environment:
+Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows, or
+`apk add --no-cache python3 make g++` on Alpine.
 
 ### 2. Initialize in Your Project
 ```bash
@@ -152,9 +194,11 @@ Holmes-Kit embeds native AST & Code Property Graph (D-CPG) analyzers to track ca
 | **macOS** | Apple Silicon (arm64) / Intel (x64) | ✅ Tier 1 | macOS 12+ (Full hook enforcement) |
 | **Linux** | x86_64 / arm64 | ✅ Tier 1 | Ubuntu, Debian, Fedora, Arch, RHEL |
 | **Windows (WSL2)** | x86_64 | ✅ Tier 1 | WSL2 Ubuntu/Debian recommended |
-| **Windows Native** | x86_64 | ✅ Tier 2 | Windows 10/11 (Node.js 20+ with C++ build tools) |
+| **Windows Native** | x86_64 | ✅ Tier 1 | Windows 10/11 (Node.js 20+ with C++ build tools). Gate parity verified from CI — see [ADR-015](.ax/decisions/ADR-015_platform-tier-is-decided-by-executed-verification.md) for the graduation criteria and the residual risks (NTFS 8.3 names, reserved device names, 260-char paths) |
 
 > **Runtime Requirement**: Node.js `>= 20.0.0` (LTS recommended)
+>
+> **How a tier is decided**: by the verification that actually executes, not by declaration. A platform is Tier 1 only while its gate verdicts are exercised by the suite; if that stops being true it is demoted and the demotion is recorded. See [ADR-015](.ax/decisions/ADR-015_platform-tier-is-decided-by-executed-verification.md).
 
 ---
 

package/dist/.build-id

@@ -1 +1 @@
-ef6b2ad-mt1pqqxf
+a400784-mt568ove

package/dist/holmes/cli/test-platform.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A test that cannot run here says so, instead of returning early and being counted as a pass.
+ *
+ * @implements A-SPEC-220.3
+ * `if (process.platform === 'win32') return;` inside a test body is an unexecution that reports as
+ * green. Five of them in `playbook-skills.test.ts` are why the Windows platform tier was, in
+ * substance, "no evidence" rather than "no feature" (ADR-015). Choosing `it.skip` moves the fact
+ * into the report where a reader can see it.
+ *
+ * `reason` is required and must be non-empty: a skip without a stated reason is the same silence in
+ * different syntax. There is no minimum length, because a length rule is a promise this cannot keep.
+ *
+ * An unrecognised platform gets `it`, not `it.skip` — leaning toward running. An assertion that
+ * cannot hold there surfaces as a failure, which is information; skipping it is not.
+ */
+export declare function posixOnly(reason: string, platform?: string): typeof it | typeof it.skip;
+/**
+ * As `posixOnly`, and additionally skipped when the process is root.
+ *
+ * @implements A-SPEC-220.3
+ * `chmod`-based assertions are vacuous for root, which bypasses the permission bits being tested.
+ * That is a property of the RUNNING process, knowable at definition time just like the platform, so
+ * it belongs in the same choice rather than in a second early return inside the body.
+ */
+export declare function posixOnlyNonRoot(reason: string, platform?: string, uid?: number | undefined): typeof it | typeof it.skip;

package/dist/holmes/cli/test-platform.js

@@ -0,0 +1,38 @@
+"use strict";
+// @implements A-SPEC-220.3
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.posixOnly = posixOnly;
+exports.posixOnlyNonRoot = posixOnlyNonRoot;
+/**
+ * A test that cannot run here says so, instead of returning early and being counted as a pass.
+ *
+ * @implements A-SPEC-220.3
+ * `if (process.platform === 'win32') return;` inside a test body is an unexecution that reports as
+ * green. Five of them in `playbook-skills.test.ts` are why the Windows platform tier was, in
+ * substance, "no evidence" rather than "no feature" (ADR-015). Choosing `it.skip` moves the fact
+ * into the report where a reader can see it.
+ *
+ * `reason` is required and must be non-empty: a skip without a stated reason is the same silence in
+ * different syntax. There is no minimum length, because a length rule is a promise this cannot keep.
+ *
+ * An unrecognised platform gets `it`, not `it.skip` — leaning toward running. An assertion that
+ * cannot hold there surfaces as a failure, which is information; skipping it is not.
+ */
+function posixOnly(reason, platform = process.platform) {
+    if (typeof reason !== 'string' || reason.trim().length === 0) {
+        throw new Error('posixOnly(reason): 사유 없는 스킵은 문법만 바뀐 침묵입니다 — 왜 이 단언이 Windows에서 무의미한지 적으십시오.');
+    }
+    return platform === 'win32' ? it.skip : it;
+}
+/**
+ * As `posixOnly`, and additionally skipped when the process is root.
+ *
+ * @implements A-SPEC-220.3
+ * `chmod`-based assertions are vacuous for root, which bypasses the permission bits being tested.
+ * That is a property of the RUNNING process, knowable at definition time just like the platform, so
+ * it belongs in the same choice rather than in a second early return inside the body.
+ */
+function posixOnlyNonRoot(reason, platform = process.platform, uid = typeof process.getuid === 'function' ? process.getuid() : undefined) {
+    const base = posixOnly(reason, platform);
+    return uid === 0 ? it.skip : base;
+}

package/dist/holmes/cpg/cpg-scanner.d.ts

@@ -49,6 +49,27 @@ export interface ScannedFile {
  * below catches the case that actually matters through evidence rather than by name.
  */
 export declare const SKIP: Set<string>;
+/**
+ * Does this repo-relative path lie inside a directory that never holds the project's own source?
+ *
+ * @implements A-SPEC-241
+ * The walker above consults `SKIP` while descending, so a path it never produced is never judged.
+ * Anything that arrives from ELSEWHERE — `git ls-files`, a caller's list — has had no such filter
+ * applied, and that asymmetry shipped: measured 2026-08-23 on a real 235-file Python codebase,
+ * `reverse_scan`'s source candidates were correctly 149 while its TEST discovery returned 340 files
+ * of which 254 (75%) were dependencies' own tests under `node_modules`. Three of them were attributed
+ * to a project cluster, so a reverse-engineered T-SPEC would have cited a third-party package's test
+ * as its own coverage — exactly what `SKIP`'s comment above warns about.
+ *
+ * SEGMENTS, not prefixes or substrings. A prefix test claims `node_modules_backup/`; a substring
+ * test claims `src/my_vendor_code/`. The last segment is a FILE name and is not consulted: a file
+ * called `dist` is not a build directory.
+ *
+ * Reading `SKIP` rather than restating it is the point — one definition of what counts as vendor,
+ * whichever code asks. Two copies of `isTestFile` once let a Python file be excluded from the graph
+ * as a test AND gated as production at the same time.
+ */
+export declare function isUnderSkippedDir(p: unknown): boolean;
 /** Single source of truth for which file extensions CpgScanner ingests (REQ-124 gate 2). */
 export declare const SCANNABLE_EXTENSIONS: readonly [".ts", ".mts", ".cts", ".tsx", ".jsx", ".js", ".mjs", ".cjs", ".py", ".cs", ".java", ".go", ".rs", ".cpp", ".cc", ".cxx", ".hpp", ".hh", ".h"];
 export { TEST_FILE_PATTERNS, isTestFile } from './test-files';
@@ -65,5 +86,25 @@ export declare class CpgScanner {
         file: string;
         reason: string;
     }[];
+    /**
+     * The production graph: every scannable file that is NOT a test.
+     *
+     * The exclusion is load-bearing, not incidental — change impact, RTM coverage, clustering and
+     * reverse-engineered drafts all read this return, and test symbols entering it corrupts all four.
+     * `scanTests` exists precisely so nothing has to widen this one.
+     */
     scan(rootDir: string, repoRoot?: string): ScannedFile[];
+    /**
+     * The test corpus, for structural-constraint checking only.
+     *
+     * @implements A-SPEC-229
+     * Measured 2026-08-22: `scan()` returned 326 files and none of them a test, while 166 existed on
+     * disk — so every C-SPEC rule was reading half the source. One of the three `filterGoverned`
+     * bypasses (`tspec-mirror.test.ts`) lived in exactly that half and no rule could see it.
+     *
+     * A SEPARATE entry point rather than an option on `scan()`: the two corpora must never merge by
+     * accident, and a caller that wants both should have to say so.
+     */
+    scanTests(rootDir: string, repoRoot?: string): ScannedFile[];
+    private walkScan;
 }

package/dist/holmes/cpg/cpg-scanner.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CpgScanner = exports.isTestFile = exports.TEST_FILE_PATTERNS = exports.SCANNABLE_EXTENSIONS = exports.SKIP = void 0;
+exports.isUnderSkippedDir = isUnderSkippedDir;
 // @implements A-SPEC-208
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -64,6 +65,33 @@ exports.SKIP = new Set([
     // VCS + generic tool output
     '.git', '.hg', '.svn', 'coverage', '.idea', '.vscode',
 ]);
+/**
+ * Does this repo-relative path lie inside a directory that never holds the project's own source?
+ *
+ * @implements A-SPEC-241
+ * The walker above consults `SKIP` while descending, so a path it never produced is never judged.
+ * Anything that arrives from ELSEWHERE — `git ls-files`, a caller's list — has had no such filter
+ * applied, and that asymmetry shipped: measured 2026-08-23 on a real 235-file Python codebase,
+ * `reverse_scan`'s source candidates were correctly 149 while its TEST discovery returned 340 files
+ * of which 254 (75%) were dependencies' own tests under `node_modules`. Three of them were attributed
+ * to a project cluster, so a reverse-engineered T-SPEC would have cited a third-party package's test
+ * as its own coverage — exactly what `SKIP`'s comment above warns about.
+ *
+ * SEGMENTS, not prefixes or substrings. A prefix test claims `node_modules_backup/`; a substring
+ * test claims `src/my_vendor_code/`. The last segment is a FILE name and is not consulted: a file
+ * called `dist` is not a build directory.
+ *
+ * Reading `SKIP` rather than restating it is the point — one definition of what counts as vendor,
+ * whichever code asks. Two copies of `isTestFile` once let a Python file be excluded from the graph
+ * as a test AND gated as production at the same time.
+ */
+function isUnderSkippedDir(p) {
+    if (typeof p !== 'string' || p === '')
+        return false;
+    const segments = p.split('/');
+    segments.pop(); // the file name is not a directory
+    return segments.some((seg) => exports.SKIP.has(seg));
+}
 /**
  * Evidence-based virtualenv detection. A Python virtualenv is defined by containing `pyvenv.cfg`,
  * whatever the user named the directory (`env`, `.env311`, `myproject-venv`, …), so name matching
@@ -126,7 +154,31 @@ class CpgScanner {
     scanSkipped() {
         return [...this.skipped].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
     }
+    /**
+     * The production graph: every scannable file that is NOT a test.
+     *
+     * The exclusion is load-bearing, not incidental — change impact, RTM coverage, clustering and
+     * reverse-engineered drafts all read this return, and test symbols entering it corrupts all four.
+     * `scanTests` exists precisely so nothing has to widen this one.
+     */
     scan(rootDir, repoRoot = rootDir) {
+        return this.walkScan(rootDir, repoRoot, (rel) => !(0, test_files_2.isTestFile)(rel));
+    }
+    /**
+     * The test corpus, for structural-constraint checking only.
+     *
+     * @implements A-SPEC-229
+     * Measured 2026-08-22: `scan()` returned 326 files and none of them a test, while 166 existed on
+     * disk — so every C-SPEC rule was reading half the source. One of the three `filterGoverned`
+     * bypasses (`tspec-mirror.test.ts`) lived in exactly that half and no rule could see it.
+     *
+     * A SEPARATE entry point rather than an option on `scan()`: the two corpora must never merge by
+     * accident, and a caller that wants both should have to say so.
+     */
+    scanTests(rootDir, repoRoot = rootDir) {
+        return this.walkScan(rootDir, repoRoot, (rel) => (0, test_files_2.isTestFile)(rel));
+    }
+    walkScan(rootDir, repoRoot, include) {
         this.skipped = [];
         const out = [];
         const walk = (d) => {
@@ -146,7 +198,7 @@ class CpgScanner {
                         continue;
                     walk(p);
                 }
-                else if (SCANNABLE_RE.test(e.name) && !(0, test_files_2.isTestFile)(path.relative(rootDir, p).split(path.sep).join('/'))) {
+                else if (SCANNABLE_RE.test(e.name) && include(path.relative(rootDir, p).split(path.sep).join('/'))) {
                     // Test detection needs the path, not the basename: a Rust integration test is `tests/x.rs`
                     // and a JVM one is `src/test/java/X.java` — nothing in the filename says "test". Relative
                     // to the SCAN ROOT, so a repository that merely lives under some `/…/test/` directory on

package/dist/holmes/cpg/forbidden-edges.d.ts

@@ -0,0 +1,73 @@
+import { ScannedFile } from './cpg-scanner';
+/**
+ * Which half of the source a rule judges.
+ *
+ * @implements A-SPEC-229
+ * The rule declares this, not the caller. If it were decided by which file list someone passed in,
+ * the same rule would mean different things depending on who invoked it — that is configuration,
+ * not a rule. The default is `production` so the ten rules already approved in C-SPEC-224 keep
+ * their meaning exactly.
+ */
+export type RuleCorpus = 'production' | 'tests';
+/** Split a leading `tests:` marker off a source prefix. */
+export declare function splitCorpus(prefix: string): {
+    corpus: RuleCorpus;
+    sourcePrefix: string;
+};
+/**
+ * One prohibition, read from a C-SPEC's `## Forbidden Edges`.
+ *
+ * @implements A-SPEC-224
+ * The two kinds are not a taxonomy choice — they are the two things the D-CPG can actually see.
+ * Measured 2026-08-22 on this repository: 23,854 `calls` edges and 1,646 `imports` edges, and
+ * nothing else. Property access (`process.platform`) produces no edge at all, so no rule shape
+ * expresses it; offering one would recreate the "documented but unenforced" state this slice exists
+ * to remove.
+ */
+export interface ForbiddenEdgeRule {
+    kind: 'import' | 'call';
+    /** Which corpus this rule judges. @implements A-SPEC-229 */
+    corpus: RuleCorpus;
+    /** Repo-relative prefix of the files the rule judges. */
+    sourcePrefix: string;
+    /** Module specifier (import) or callee name (call). */
+    target: string;
+    /** The rule's own text, so a violation can quote what it broke. */
+    text: string;
+}
+export interface ForbiddenEdgeViolation {
+    rule: string;
+    sourcePath: string;
+    /** The enclosing definition the edge leaves from — `<module>` for a top-level import. */
+    from: string;
+    to: string;
+    kind: 'import' | 'call';
+}
+/**
+ * Read the rules out of a `## Forbidden Edges` section.
+ *
+ * @implements A-SPEC-224
+ * A malformed list item is RETURNED, never dropped. A typo that silently parses to nothing reads as
+ * "the rule passed" — the same shape as a gate that concludes there is nothing to govern, which
+ * this repository has now paid for in A-SPEC-191 §17, §29 and again in A-SPEC-222.2.
+ *
+ * Prose and blank lines are neither: a section is allowed to explain itself, and treating every
+ * sentence as a broken rule would make the report useless.
+ */
+export declare function parseForbiddenEdges(section: string): {
+    rules: ForbiddenEdgeRule[];
+    malformed: string[];
+};
+/**
+ * Judge a scan against a set of prohibitions.
+ *
+ * @implements A-SPEC-224
+ * Pure: no filesystem, no `process`. That is what lets the same function be exercised by synthetic
+ * fixtures AND by the real corpus — and the real corpus is the one that matters, because a rule
+ * checked only against fixtures stays green while the repository drifts.
+ *
+ * `import` matches by PREFIX so one rule covers a directory and survives an extension-less
+ * specifier. `call` matches EXACTLY, because its target is a bare callee name and a prefix there
+ * would make `list` catch `listFiles`.
+ */
+export declare function findForbiddenEdgeViolations(files: ScannedFile[], rules: ForbiddenEdgeRule[]): ForbiddenEdgeViolation[];

package/dist/holmes/cpg/forbidden-edges.js

@@ -0,0 +1,140 @@
+"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.splitCorpus = splitCorpus;
+exports.parseForbiddenEdges = parseForbiddenEdges;
+exports.findForbiddenEdgeViolations = findForbiddenEdgeViolations;
+// @implements A-SPEC-224
+const path = __importStar(require("node:path"));
+const test_files_1 = require("./test-files");
+/** Split a leading `tests:` marker off a source prefix. */
+function splitCorpus(prefix) {
+    return prefix.startsWith('tests:')
+        ? { corpus: 'tests', sourcePrefix: prefix.slice('tests:'.length) }
+        : { corpus: 'production', sourcePrefix: prefix };
+}
+const RULE = /^(import|call)\s+(\S+)\s+-x->\s+(\S+)$/;
+/**
+ * Read the rules out of a `## Forbidden Edges` section.
+ *
+ * @implements A-SPEC-224
+ * A malformed list item is RETURNED, never dropped. A typo that silently parses to nothing reads as
+ * "the rule passed" — the same shape as a gate that concludes there is nothing to govern, which
+ * this repository has now paid for in A-SPEC-191 §17, §29 and again in A-SPEC-222.2.
+ *
+ * Prose and blank lines are neither: a section is allowed to explain itself, and treating every
+ * sentence as a broken rule would make the report useless.
+ */
+function parseForbiddenEdges(section) {
+    const rules = [];
+    const malformed = [];
+    for (const raw of String(section ?? '').split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('- '))
+            continue; // prose, blank, or a non-list line
+        // Strip a trailing comment and the backticks a Markdown author naturally reaches for, so the
+        // rule reads the same whether or not it was written for a human eye.
+        const body = line.slice(2).replace(/\s+#.*$/, '').replace(/`/g, '').trim().replace(/\s+/g, ' ');
+        const m = RULE.exec(body);
+        if (!m) {
+            malformed.push(raw.trim());
+            continue;
+        }
+        const { corpus, sourcePrefix } = splitCorpus(m[2]);
+        rules.push({ kind: m[1], corpus, sourcePrefix, target: m[3], text: body });
+    }
+    return { rules, malformed };
+}
+/**
+ * Where an import specifier lands, as a repo-relative path.
+ *
+ * A relative specifier is resolved against the importing file; anything else (`node:path`, a package
+ * name) has nothing to resolve against and is compared as the literal string it is. Mixing the two
+ * inside one comparison would make a rule mean different things depending on how the author spelled
+ * the target.
+ */
+function importTargetOf(sourcePath, to) {
+    if (!to.startsWith('.'))
+        return to;
+    return path.posix.normalize(path.posix.join(path.posix.dirname(sourcePath), to));
+}
+/**
+ * Judge a scan against a set of prohibitions.
+ *
+ * @implements A-SPEC-224
+ * Pure: no filesystem, no `process`. That is what lets the same function be exercised by synthetic
+ * fixtures AND by the real corpus — and the real corpus is the one that matters, because a rule
+ * checked only against fixtures stays green while the repository drifts.
+ *
+ * `import` matches by PREFIX so one rule covers a directory and survives an extension-less
+ * specifier. `call` matches EXACTLY, because its target is a bare callee name and a prefix there
+ * would make `list` catch `listFiles`.
+ */
+function findForbiddenEdgeViolations(files, rules) {
+    const out = [];
+    if (!Array.isArray(files) || !Array.isArray(rules) || rules.length === 0)
+        return out;
+    for (const f of files) {
+        const sourcePath = f?.sourcePath;
+        if (typeof sourcePath !== 'string')
+            continue;
+        // @implements A-SPEC-229 — the file's corpus is decided by `isTestFile`, the same table the
+        // scanner and the phase gate already share. A third definition would drift from those two, and
+        // the cost of that drift is on record: one Python file was excluded from the graph as a test
+        // AND gated as production code at the same time.
+        const corpus = (0, test_files_1.isTestFile)(sourcePath) ? 'tests' : 'production';
+        const applicable = rules.filter((r) => r.corpus === corpus && sourcePath.startsWith(r.sourcePrefix));
+        if (applicable.length === 0)
+            continue;
+        for (const e of f.edges ?? []) {
+            for (const r of applicable) {
+                if (r.kind === 'import') {
+                    if (e.rel !== 'imports')
+                        continue;
+                    if (!importTargetOf(sourcePath, e.to).startsWith(r.target))
+                        continue;
+                }
+                else {
+                    if (e.rel !== 'calls')
+                        continue;
+                    if (e.to !== r.target)
+                        continue;
+                }
+                out.push({ rule: r.text, sourcePath, from: e.from, to: e.to, kind: r.kind });
+            }
+        }
+    }
+    return out;
+}

package/dist/holmes/cpg/hash-cache.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HashCache = void 0;
 const fs = __importStar(require("node:fs"));
+const json_state_1 = require("../project/json-state");
 const path = __importStar(require("node:path"));
 const node_crypto_1 = require("node:crypto");
 // @implements A-SPEC-113.1
@@ -58,16 +59,23 @@ class HashCache {
         this.hashes = this.load();
     }
     load() {
+        let parsed;
         try {
-            const raw = fs.readFileSync(this.file, 'utf8');
-            return JSON.parse(raw);
+            parsed = JSON.parse(fs.readFileSync(this.file, 'utf8'));
         }
         catch {
-            // Missing dir/file, or unreadable/corrupt JSON: treat as no prior hash
-            // rather than throwing — a cold or damaged cache must never block a
-            // reindex, only make it fall back to a full re-scan.
+            // Missing dir/file, or JSON that does not parse.
             return {};
         }
+        // @implements A-SPEC-237
+        // A SECOND check, because the one above cannot see the corruption that matters most. `null`,
+        // `42`, `"x"`, `true` and `[1,2]` are all valid JSON: the parse SUCCEEDS and the failure
+        // lands later, at the first property access, as a TypeError. Measured 2026-08-23 — four of those
+        // forms made `unchanged()` and `put()` throw, while this method's own comment promised that a
+        // damaged cache "must never block a reindex". The promise lived only in prose, so nobody checked.
+        if (!(0, json_state_1.isJsonStateObject)(parsed))
+            return {};
+        return parsed;
     }
     static hashOf(content) {
         return (0, node_crypto_1.createHash)('sha256').update(content, 'utf8').digest('hex');