@holmes-lab/holmes-kit 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -5,6 +5,124 @@ 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.11] - 2026-08-23
+
+### Added
+- **`doctor` diagnoses the global npm prefix (REQ-243)**: after a Windows adopter hit `EPERM` on
+  `npm install -g` twice — once elevated — `doctor` now reads the npm global prefix, computes where
+  a global install would land (win32: `<prefix>\\node_modules`; POSIX: `<prefix>/lib/node_modules`),
+  and checks writability on the deepest existing ancestor, which is what decides the real mkdir's
+  fate. An unwritable prefix is a **WARN** naming the exact directory the install would die in, with
+  a user-space prefix prescription — never elevation, which npm's own error text suggests and which
+  would run better-sqlite3's install script with system privileges. An unreadable probe is a WARN
+  carrying the reason, never a silent pass. The check cannot FAIL: a red doctor would tell a user
+  with a healthy local install that the install is broken.
+
+### Unchanged
+- The `-g` EPERM itself is not fixable by any package: it occurs while npm creates the scope
+  directory, before a single package file is transferred. The supported regular-account path remains
+  the local install (`npm install --save-dev`), which touches no protected directory.
+
+<!-- @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
+c3422e5-mt570gca

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

@@ -28,6 +28,45 @@ export interface DoctorOptions {
  * real key-related failure.
  */
 export declare const STRIPPED_FOR_PROBE: readonly ["HOLMES_APPROVAL", "HOLMES_SPECS"];
+/**
+ * Where a global install actually lands for a given prefix.
+ *
+ * @implements A-SPEC-243
+ * The shapes differ, not just the separators: win32 puts global modules directly under the prefix,
+ * POSIX puts them under `lib/`. The win32 result is the exact directory the reported EPERM died in
+ * — npm mkdir-ing `@holmes-lab` inside `C:\Program Files\nodejs\node_modules`, before a single
+ * package file was transferred. That is why no package content can fix that failure, and why the
+ * only lever left is naming the condition here.
+ */
+export declare function globalInstallDir(prefix: string, platform: string): string;
+/** What the global-prefix probe saw. `unreadable` carries WHY npm could not be consulted. */
+export interface PrefixProbe {
+    prefix?: unknown;
+    dir?: string;
+    writable?: boolean;
+    platform?: string;
+    unreadable?: string;
+}
+/**
+ * Judge the global prefix. Pure — the probing lives with the caller.
+ *
+ * @implements A-SPEC-243
+ * Never FAIL: the `-g` path is optional, and a red doctor tells a user with a healthy local
+ * install that the install is broken — a false signal that comes back as distrust of the check.
+ *
+ * Never elevation: npm's own EPERM text ends with "try running the command again as
+ * root/Administrator", and pointing the opposite way is this check's reason to exist — elevation
+ * runs better-sqlite3's install script (`prebuild-install || node-gyp rebuild`) with system
+ * privileges. The prescription is a user-space prefix, per platform.
+ *
+ * An unreadable probe is a WARN carrying the reason, not a silent pass: a silent pass reads as
+ * "checked, no problem", which translates what was not seen into a verdict.
+ */
+export declare function prefixVerdict(input: PrefixProbe): {
+    level: Level;
+    detail: string;
+    fix?: string;
+};
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */

package/dist/holmes/cli/doctor.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STRIPPED_FOR_PROBE = void 0;
+exports.globalInstallDir = globalInstallDir;
+exports.prefixVerdict = prefixVerdict;
 exports.probeEnv = probeEnv;
 exports.runDoctor = runDoctor;
 exports.formatChecks = formatChecks;
@@ -63,6 +65,56 @@ const GRAMMARS = [
  * real key-related failure.
  */
 exports.STRIPPED_FOR_PROBE = ['HOLMES_APPROVAL', 'HOLMES_SPECS'];
+/**
+ * Where a global install actually lands for a given prefix.
+ *
+ * @implements A-SPEC-243
+ * The shapes differ, not just the separators: win32 puts global modules directly under the prefix,
+ * POSIX puts them under `lib/`. The win32 result is the exact directory the reported EPERM died in
+ * — npm mkdir-ing `@holmes-lab` inside `C:\Program Files\nodejs\node_modules`, before a single
+ * package file was transferred. That is why no package content can fix that failure, and why the
+ * only lever left is naming the condition here.
+ */
+function globalInstallDir(prefix, platform) {
+    return platform === 'win32'
+        ? `${prefix.replace(/[\\/]+$/, '')}\\node_modules`
+        : `${prefix.replace(/\/+$/, '')}/lib/node_modules`;
+}
+/**
+ * Judge the global prefix. Pure — the probing lives with the caller.
+ *
+ * @implements A-SPEC-243
+ * Never FAIL: the `-g` path is optional, and a red doctor tells a user with a healthy local
+ * install that the install is broken — a false signal that comes back as distrust of the check.
+ *
+ * Never elevation: npm's own EPERM text ends with "try running the command again as
+ * root/Administrator", and pointing the opposite way is this check's reason to exist — elevation
+ * runs better-sqlite3's install script (`prebuild-install || node-gyp rebuild`) with system
+ * privileges. The prescription is a user-space prefix, per platform.
+ *
+ * An unreadable probe is a WARN carrying the reason, not a silent pass: a silent pass reads as
+ * "checked, no problem", which translates what was not seen into a verdict.
+ */
+function prefixVerdict(input) {
+    const reason = input.unreadable ?? (typeof input.prefix !== 'string' || input.prefix === ''
+        ? `npm 이 돌려준 prefix 를 해석할 수 없습니다 (${String(input.prefix)})`
+        : undefined);
+    if (reason !== undefined) {
+        return { level: 'WARN', detail: `전역 prefix 를 판독하지 못했습니다 — ${reason}. 로컬 설치(--save-dev)는 이 판정과 무관하게 동작합니다.` };
+    }
+    const prefix = input.prefix;
+    if (input.writable) {
+        return { level: 'PASS', detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 가능합니다 — npm install -g 가 권한 문제 없이 동작합니다.` };
+    }
+    const fix = input.platform === 'win32'
+        ? 'npm config set prefix "%APPDATA%\\npm" 실행 후 %APPDATA%\\npm 을 PATH 에 추가하고 터미널을 다시 여세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.'
+        : 'npm config set prefix "$HOME/.npm-global" 실행 후 $HOME/.npm-global/bin 을 PATH 에 추가하세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.';
+    return {
+        level: 'WARN',
+        detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 불가입니다 — npm install -g 는 ${input.dir ?? ''} 에 디렉터리를 만들다 EPERM 으로 죽습니다. 패키지가 도착하기 전 단계라 어떤 패키지도 이를 고칠 수 없습니다.`,
+        fix,
+    };
+}
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 function probeEnv(parent) {
     const out = { ...parent };
@@ -451,6 +503,33 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         catch { /* an unreadable settings file is `target wiring`'s business, not this check's */ }
     }
     add('gate blind spots', 'PASS', (0, blind_spots_1.blindSpotSummary)());
+    // @implements A-SPEC-243 — the writability of the deepest EXISTING ancestor is what decides the
+    // real mkdir's fate, since the scope directory being created does not exist yet.
+    {
+        let verdict;
+        try {
+            const prefix = (0, node_child_process_1.execFileSync)('npm', ['config', 'get', 'prefix'], { encoding: 'utf8' }).trim();
+            const dir = globalInstallDir(prefix, process.platform);
+            let probe = dir;
+            while (!fs.existsSync(probe)) {
+                const parent = path.dirname(probe);
+                if (parent === probe)
+                    break;
+                probe = parent;
+            }
+            let writable = false;
+            try {
+                fs.accessSync(probe, fs.constants.W_OK);
+                writable = true;
+            }
+            catch { /* not writable */ }
+            verdict = prefixVerdict({ prefix, dir, writable, platform: process.platform });
+        }
+        catch (e) {
+            verdict = prefixVerdict({ unreadable: e instanceof Error ? e.message.split('\n')[0] : String(e) });
+        }
+        add('global prefix', verdict.level, verdict.detail, verdict.fix);
+    }
     add('environment', 'PASS', present);
     if (extraChecks) {
         checks.push(...extraChecks);

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[];