vigiles 16.1.0 → 16.1.2

package/dist/core/source-refs.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * vigiles — recovering a FILE REFERENCE from PLAIN SOURCE TEXT.
+ *
+ * The third of three reference grammars, and the only one with no parser behind
+ * it. A markdown body is read by markdown-it (`core/markdown.ts` →
+ * `markdownRefs`), a hook `command` is read by mvdan-sh (`core/bash-effects.ts`
+ * → `commandWords`), and what is left — the body of a hook script, a helper
+ * `.js` / `.py` / `.rb` — is scanned for path-shaped character runs, because a
+ * general-purpose "find every path this program touches" analysis is not a
+ * thing this tool can be.
+ *
+ * Since that scan IS a character run, the only thing standing between it and a
+ * false accusation is where the run may START and STOP. This module owns both
+ * boundaries and the extension vocabularies, so no caller can build a pattern
+ * without them.
+ *
+ * ## The two boundaries, and the two live defects that came from omitting them
+ *
+ * RIGHT — the extension must END the token. `INTRA_REF_EXTS` used to be a bare
+ * alternation with no trailing assertion, and `js` sits ahead of `json` in it,
+ * so `hooks/hooks.json` matched as `hooks/hooks.js`. Measured 2026-08-17 on
+ * `microsoft/power-platform-skills`: a `//` comment naming `hooks/hooks.json`,
+ * with that exact file sitting beside it on disk, was reported as
+ * "hooks/hooks.js (referenced but MISSING)" — a maintainer told a file they
+ * have is missing, under a name they never wrote.
+ *
+ * LEFT — the surface dir must START the token. `(?:agents|hooks|skills)/` with
+ * nothing before it also matches the tail of `claude-agents/`. Measured the
+ * same day on `fcakyon/claude-codex-settings`: a
+ * `new URL("../../../claude-agents/fable-advisor.md", …)` — a correct,
+ * resolving reference — was reported as a broken `agents/fable-advisor.md`.
+ * That boundary is a predicate ({@link startsAtSeparator}) rather than a regex
+ * lookbehind, because the browser twin (`scan-files.ts`) compiles this into the
+ * demo engine, and because the caller already inspects `m.index` for its
+ * plugin-rooted test.
+ *
+ * ## Comments are prose in every language, not only in shell
+ *
+ * `stripShellComments` had the right idea and too narrow a domain: a full-line
+ * `#` in a `.sh` file is prose, and so is a full-line `//` or a JSDoc `*` in a
+ * `.js` file. Both remaining corpus false accusations in this detector came out
+ * of JSDoc — `* It is deliberately not registered in hooks/hooks.json:` and
+ * "`git log --grep=.env -- hooks/x.mjs` is refused …". Neither is a file
+ * operation; both were reported as broken references.
+ *
+ * FULL-LINE ONLY, the same rule the shell version already held. A trailing
+ * comment on a real code line is left alone, so a genuine reference sharing a
+ * line with code is never dropped. The cost is stated rather than hidden: a
+ * path mentioned ONLY in a trailing comment still counts as a reference.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCRIPT_REF_EXTENSIONS = exports.INTRA_REF_EXTENSIONS = void 0;
+exports.startsAtSeparator = startsAtSeparator;
+exports.intraRefPattern = intraRefPattern;
+exports.scriptWordPattern = scriptWordPattern;
+exports.scriptRefPattern = scriptRefPattern;
+exports.stripFullLineComments = stripFullLineComments;
+// ---------------------------------------------------------------------------
+// Boundaries — the two assertions no pattern here may be built without
+// ---------------------------------------------------------------------------
+/**
+ * The right boundary: the matched extension must be the END of the token.
+ * A negative lookahead over the characters an extension is drawn from, so `js`
+ * cannot claim the head of `json` / `jsonl` and `py` cannot claim `pyc`. `.` is
+ * deliberately NOT in the class, which preserves the prior `\b` behaviour on
+ * `bundle.js.map`.
+ */
+const ENDS_TOKEN = "(?![A-Za-z0-9_])";
+/**
+ * Characters a path SEGMENT is made of. A match preceded by one of these landed
+ * in the middle of a longer name (`claude-agents/`), which is not a reference
+ * to the surface dir it happens to end with.
+ */
+const SEGMENT_CHAR = /[A-Za-z0-9._-]/;
+/**
+ * Whether a match at `idx` begins at a path boundary rather than inside a
+ * longer name. Position 0 counts as a boundary.
+ *
+ * `/` is a boundary on purpose: `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` is the
+ * standard spelling, and the caller's plugin-rooted test decides whether the
+ * segment before that slash roots the path inside the plugin or outside it.
+ */
+function startsAtSeparator(content, idx) {
+    if (idx <= 0)
+        return true;
+    return !SEGMENT_CHAR.test(content[idx - 1] ?? "");
+}
+// ---------------------------------------------------------------------------
+// Extension vocabularies
+// ---------------------------------------------------------------------------
+/**
+ * Extensions an intra-plugin reference may carry — the file kinds a plugin's
+ * own hook / helper source legitimately points at.
+ */
+exports.INTRA_REF_EXTENSIONS = [
+    "md",
+    "sh",
+    "cmd",
+    "mjs",
+    "cjs",
+    "js",
+    "ts",
+    "py",
+    "rb",
+    "txt",
+    "json",
+];
+/**
+ * Extensions a RUNNABLE script carries. Shared by the hook scanner and the
+ * coverage twins, which each declared their own copy before.
+ */
+exports.SCRIPT_REF_EXTENSIONS = [
+    "sh",
+    "mjs",
+    "cjs",
+    "js",
+    "ts",
+    "py",
+    "rb",
+];
+/**
+ * A plugin-relative path under one of `dirs`, carrying a known extension — the
+ * pattern for scanning a plugin's own SOURCE TEXT.
+ *
+ * The left boundary is not baked into the returned regex (see
+ * {@link startsAtSeparator}): a caller scanning raw text must apply that
+ * predicate at `m.index`, which both the disk detector and its browser twin do
+ * inside their plugin-rooted test.
+ */
+function intraRefPattern(dirs) {
+    const exts = exports.INTRA_REF_EXTENSIONS.join("|");
+    return new RegExp(`(?:${dirs.join("|")})/[A-Za-z0-9._/-]+\\.(?:${exts})${ENDS_TOKEN}`, "g");
+}
+/**
+ * A script path occupying a WHOLE shell WORD.
+ *
+ * ⚠️ ANCHORING IS NOT WHAT FIXES THE `node -e` DEFECT, and saying so would be
+ * wrong twice over — the payload
+ * `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`
+ * contains no whitespace and ends in `.mjs`, so it satisfies this pattern
+ * perfectly (asserted in source-refs.test.ts, so the claim cannot drift back).
+ * That defect is fixed one level up, by `commandWords` refusing to hand the
+ * argument of `-e` to anyone.
+ *
+ * What anchoring buys is narrower and worth stating exactly: the reported name
+ * is always a word a shell could hand to `execve`, never a fragment cut out of
+ * a longer one. `echo "see hooks/x.sh"` is one word containing a path; before,
+ * `hooks/x.sh` was lifted out of it and checked as though the hook ran it.
+ *
+ * The cost, stated rather than discovered later: a path bundled into a flag
+ * (`--require=hooks/x.js`) is no longer seen. Measured across the 32-repo
+ * dogfood corpus, that costs zero findings.
+ */
+function scriptWordPattern() {
+    const exts = exports.SCRIPT_REF_EXTENSIONS.join("|");
+    return new RegExp(`^[^\\s*?]+\\.(?:${exts})$`);
+}
+/**
+ * A script path appearing anywhere inside a string — for the one caller with no
+ * shell parse to hand (the coverage twins scan a serialized settings blob).
+ * Carries the right boundary; it cannot carry the left one, and its callers
+ * gate every hit on the file existing, so a stray match is dropped rather than
+ * reported.
+ */
+function scriptRefPattern() {
+    const exts = exports.SCRIPT_REF_EXTENSIONS.join("|");
+    return new RegExp("[\\w./$" + "{}@-]+\\." + `(?:${exts})${ENDS_TOKEN}`, "g");
+}
+// ---------------------------------------------------------------------------
+// Comments (prose inside an executable source)
+// ---------------------------------------------------------------------------
+/** Source kinds whose full-line comments this module knows how to drop. */
+const HASH_COMMENT = /\.(?:sh|bash|zsh|cmd|py|rb|pl)$/i;
+const SLASH_COMMENT = /\.(?:m|c)?[jt]s$/i;
+/**
+ * A line that is ENTIRELY a comment in a `//`-style language: a `//` line, a
+ * block-comment delimiter, or a JSDoc continuation `*` followed by whitespace
+ * or end of line.
+ *
+ * A bare `*name` does NOT count — `*run() {}` is a generator method, and
+ * dropping that line would silently delete a real reference from code.
+ */
+const SLASH_COMMENT_LINE = /^(?:\/\/|\/\*|\*\/|\*(?:\s|$))/;
+/**
+ * Drop FULL-LINE comments (including a shebang, which also starts with `#`)
+ * from an executable source before it is scanned for path references.
+ *
+ * A file of unknown kind is returned unchanged: guessing a comment syntax is
+ * how a real reference gets deleted, and this detector's contract is that it
+ * under-reports rather than accuses.
+ */
+function stripFullLineComments(path, content) {
+    const isHash = HASH_COMMENT.test(path);
+    const isSlash = SLASH_COMMENT.test(path);
+    if (!isHash && !isSlash)
+        return content;
+    return content
+        .split("\n")
+        .filter((line) => {
+        const t = line.trimStart();
+        return isHash ? !t.startsWith("#") : !SLASH_COMMENT_LINE.test(t);
+    })
+        .join("\n");
+}
+//# sourceMappingURL=source-refs.js.map

package/dist/coverage-artifact.d.ts

@@ -12,6 +12,26 @@ export declare const COVERAGE_ARTIFACT_FILE = "coverage.json";
  * silence "nothing ever measured whether this fires".
  */
 export type CoverageTierName = "harness" | "eval";
+/**
+ * How a RECORD came to name its surface.
+ *
+ * The three {@link ProbeOrigin} values are what the run REPORTED about itself
+ * from inside its own process — a command line it executed, a transcript it got
+ * back. `colocated` is the fourth and is different in kind: nothing inside the
+ * test said it. The RUNNER observed that the script it just executed is the
+ * surface's colocated test, by the same {@link isColocatedTest} rule that is
+ * already willing to credit that file for merely existing.
+ *
+ * 🔴 THE SPLIT IS THE POINT, AND IT IS WHY THIS IS NOT ON {@link ProbeOrigin}.
+ * `ProbeOrigin` is the wire vocabulary: `parseCheckReport` reads it out of a
+ * scratch file the CHILD writes. Putting `colocated` there would let a harness
+ * hand-write `{"how":"colocated","ref":"…"}` and mint execution coverage for a
+ * surface by declaring it — which is `vigiles:covers` returning through the back
+ * door, the tier this file's header records being deleted for exactly that. Kept
+ * off `ProbeOrigin`, a script cannot spell it at all: `toProbe` has no branch
+ * that produces it, so the only producer in the program is {@link recordsFrom}.
+ */
+export type RunAttribution = ProbeOrigin | "colocated";
 /** One surface, exercised by one script, at one moment, against one version. */
 export interface CoverageRun {
     readonly kind: SurfaceKind;
@@ -19,8 +39,8 @@ export interface CoverageRun {
     readonly path: string;
     readonly name: string;
     readonly tier: CoverageTierName;
-    /** How the run named it — see {@link ProbeOrigin}. */
-    readonly how: ProbeOrigin;
+    /** How the run named it — see {@link RunAttribution}. */
+    readonly how: RunAttribution;
     /** The script file that did the exercising. */
     readonly by: string;
     /** ISO-8601 timestamp of the run. */
@@ -192,6 +212,18 @@ export interface ScriptRunRecord {
     /** The script file that ran. */
     readonly file: string;
     readonly probes: readonly SurfaceProbe[];
+    /**
+     * How many checks the run REPORTED, or `undefined` when it reported nothing.
+     *
+     * The distinction is load-bearing and is not this file's invention — see
+     * `statusFor` in run-scripts.ts. `undefined` means the script never imported
+     * vigiles and therefore *could not* report; that silence is the legacy branch
+     * and is never a verdict. A positive number is the script saying, through the
+     * library, that it made an observation. Only the second is evidence, which is
+     * why {@link recordsFrom} attributes colocation on `> 0` rather than on
+     * "it exited 0".
+     */
+    readonly checks?: number;
 }
 /**
  * The runs worth recording, out of a whole `vigiles test` / `vigiles eval`.
@@ -226,10 +258,26 @@ export interface ScriptRunRecord {
  * CLI would destroy a real result. A skip must not write, because it did not
  * finish. Both follow from "a skip is not an execution"; only the direction of
  * the conclusion differs.
+ *
+ * ## 🔴 A RUN WITH NO PROBES IS NO LONGER DISCARDED
+ *
+ * The second clause used to be `surfaces.length > 0`: a passing run that named no
+ * surface contributed nothing. That threw away the ordinary case. MEASURED on a
+ * 52-surface consumer repo, 23 of its 27 covered surfaces were carried by a
+ * colocated `*.harness.mjs` that `vigiles test` RUNS on every push — and every one
+ * of them reported `colocated` evidence, *"this says the file EXISTS, not that it
+ * ran"*, because a harness asserting through `node:assert` reports a CHECK COUNT
+ * and no probe. The run happened, the runner watched it happen, and the metric
+ * described it as a directory listing.
+ *
+ * So a passing run that reported at least one CHECK is kept even with no probes:
+ * {@link recordsFrom} can attribute it by where the script sits. `checks` travels
+ * with it because "exited 0" is not the bar — see {@link ScriptRunRecord.checks}.
  */
 export declare function runsFromResults(results: readonly {
     readonly file: string;
     readonly status: string;
+    readonly checks?: number;
     readonly surfaces?: readonly SurfaceProbe[];
 }[]): ScriptRunRecord[];
 /**
@@ -238,6 +286,12 @@ export declare function runsFromResults(results: readonly {
  * run); a surface it cannot read is skipped — an unhashable record could never
  * be checked for staleness and would therefore be permanent, unfalsifiable
  * coverage.
+ *
+ * Two sources of attribution, in one pass: the probes a run reported, and — for a
+ * run that reported a check — the surface its own script is colocated with
+ * ({@link colocatedSurface}). The dedupe key already carries `how`, so a run that
+ * BOTH probed a surface and sits beside it records once per attribution and the
+ * report can still say which kinds of evidence exist.
  */
 export declare function recordsFrom(opts: ResolveOptions & {
     readonly runs: readonly ScriptRunRecord[];

package/dist/coverage-artifact.js

@@ -57,10 +57,26 @@ exports.indexRuns = indexRuns;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const coverage_evidence_js_1 = require("./coverage-evidence.js");
 /** Bumped when the record shape changes in a non-additive way. */
 exports.COVERAGE_ARTIFACT_VERSION = 1;
 /** The artifact filename under `.vigiles/`. */
 exports.COVERAGE_ARTIFACT_FILE = "coverage.json";
+/**
+ * Every {@link RunAttribution}, as data — the artifact's validator reads it, so
+ * the accepted set and the type cannot drift apart into a record shape the
+ * program can produce and the reader silently discards. The `satisfies` is the
+ * lock: drop a member and this stops compiling.
+ */
+const ATTRIBUTIONS = new Set([
+    "command",
+    "fired",
+    "dispatched",
+    "colocated",
+]);
+function isAttribution(value) {
+    return typeof value === "string" && ATTRIBUTIONS.has(value);
+}
 /** Content hash of a surface file — the staleness key. */
 function surfaceSha(content) {
     return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex").slice(0, 16);
@@ -347,11 +363,83 @@ function only(matches) {
  * CLI would destroy a real result. A skip must not write, because it did not
  * finish. Both follow from "a skip is not an execution"; only the direction of
  * the conclusion differs.
+ *
+ * ## 🔴 A RUN WITH NO PROBES IS NO LONGER DISCARDED
+ *
+ * The second clause used to be `surfaces.length > 0`: a passing run that named no
+ * surface contributed nothing. That threw away the ordinary case. MEASURED on a
+ * 52-surface consumer repo, 23 of its 27 covered surfaces were carried by a
+ * colocated `*.harness.mjs` that `vigiles test` RUNS on every push — and every one
+ * of them reported `colocated` evidence, *"this says the file EXISTS, not that it
+ * ran"*, because a harness asserting through `node:assert` reports a CHECK COUNT
+ * and no probe. The run happened, the runner watched it happen, and the metric
+ * described it as a directory listing.
+ *
+ * So a passing run that reported at least one CHECK is kept even with no probes:
+ * {@link recordsFrom} can attribute it by where the script sits. `checks` travels
+ * with it because "exited 0" is not the bar — see {@link ScriptRunRecord.checks}.
  */
 function runsFromResults(results) {
     return results
-        .filter((r) => r.status === "pass" && (r.surfaces?.length ?? 0) > 0)
-        .map((r) => ({ file: r.file, probes: r.surfaces ?? [] }));
+        .filter((r) => r.status === "pass" &&
+        ((r.surfaces?.length ?? 0) > 0 || (r.checks ?? 0) > 0))
+        .map((r) => ({
+        file: r.file,
+        probes: r.surfaces ?? [],
+        ...(r.checks === undefined ? {} : { checks: r.checks }),
+    }));
+}
+/**
+ * The surface a RUN's own script is the colocated test of, or `null`.
+ *
+ * This is the fourth attribution ({@link RunAttribution}), and the only one the
+ * script does not report about itself. The runner knows two facts the script
+ * cannot: which file it just executed, and which surfaces this repo has. Put
+ * together by {@link isColocatedTest} — the SAME predicate that already grants
+ * `colocated` evidence for that file merely existing — they say which surface the
+ * run was about.
+ *
+ * ## The bar is a REPORTED CHECK, not exit zero
+ *
+ * 🔴 WITHOUT THAT, THIS WOULD BE THE ORIGINAL DEFECT WEARING THE STRONGER LABEL.
+ * Measured 2026-08-17 on a two-skill fixture: `touch
+ * .claude/skills/argument-arc/argument-arc.harness.mjs` — a ZERO-BYTE file —
+ * drops the untested count by one, and `vigiles test` then RUNS it and prints
+ * `✓ … passed`. An empty script exits 0. Attributing on "it ran and exited 0"
+ * would promote that file from `colocated` ("the file EXISTS, not that it ran")
+ * to "MEASURED BY A RUN", which is strictly worse than the hole being closed:
+ * the same emptiness, now wearing execution's name.
+ *
+ * A zero-byte file cannot report a check — it never imports vigiles — so its
+ * `checks` is `undefined` and it earns nothing here, falling back to colocation
+ * exactly as before. This is `statusFor`'s distinction reused, not a new one:
+ * silence is the legacy branch, `0` is `vacuous` (never a `pass`, so it never
+ * reaches this function), and a positive count is the script saying through the
+ * library that it observed something.
+ *
+ * ⚠️ WHAT THIS STILL CANNOT SEE, stated rather than implied: a harness that
+ * asserts entirely on its own and never imports vigiles reports nothing, so it is
+ * indistinguishable here from the empty file. It keeps its colocated credit and
+ * gains no execution credit. That is deliberate and it is `check-count.ts`'s
+ * standing decision — force-loading the counter into every child was considered
+ * and rejected there, because it would report `0` for a blameless hand-rolled
+ * harness. The cost is a missed upgrade; the alternative was a false one.
+ *
+ * 🔴 AMBIGUITY RESOLVES TO NOTHING, the same rule {@link only} applies to probes.
+ * Two surfaces in one directory can both claim a script when one name prefixes
+ * the other (`foo` and `foo.bar` both match `foo.bar.harness.mjs`, since
+ * colocation asks only that the basename START with `<name>.`). Exactly one of
+ * them is what the test is about, and nothing here can say which — so crediting
+ * both would INVENT a record, which is the failure the rest of this file spends
+ * its length refusing.
+ */
+function colocatedSurface(run, surfaces, alreadyProbed) {
+    if ((run.checks ?? 0) <= 0)
+        return null;
+    const matches = surfaces.filter((s) => s.path !== run.file &&
+        !alreadyProbed.has(s.path) &&
+        (0, coverage_evidence_js_1.isColocatedTest)(s, run.file));
+    return matches.length === 1 ? (matches[0] ?? null) : null;
 }
 /**
  * Turn resolved probes into records. `readSurface` supplies the current content
@@ -359,15 +447,45 @@ function runsFromResults(results) {
  * run); a surface it cannot read is skipped — an unhashable record could never
  * be checked for staleness and would therefore be permanent, unfalsifiable
  * coverage.
+ *
+ * Two sources of attribution, in one pass: the probes a run reported, and — for a
+ * run that reported a check — the surface its own script is colocated with
+ * ({@link colocatedSurface}). The dedupe key already carries `how`, so a run that
+ * BOTH probed a surface and sits beside it records once per attribution and the
+ * report can still say which kinds of evidence exist.
  */
 function recordsFrom(opts) {
     const out = [];
     const seen = new Set();
-    const pairs = opts.runs.flatMap((run) => run.probes.flatMap((probe) => resolveProbe(probe, opts.surfaces, opts).map((surface) => ({
-        run,
-        probe,
-        surface,
-    }))));
+    const pairs = [];
+    for (const run of opts.runs) {
+        const probed = new Set();
+        for (const probe of run.probes)
+            for (const surface of resolveProbe(probe, opts.surfaces, opts)) {
+                pairs.push({ run, probe, surface });
+                probed.add(surface.path);
+            }
+        // 🔴 COLOCATION IS THE FALLBACK ATTRIBUTION, NOT AN ADDITIONAL ONE, and
+        // skipping what this run already named is what keeps it from DOWNGRADING the
+        // record. MEASURED 2026-08-17 on a 52-surface repo the first time this tier
+        // ran: `.claude/hooks/paper-lint.mjs` went from `command` — the harness
+        // literally executed that path — to `colocated`, and three `fired` skill
+        // activations went the same way. The cause is one key: `mergeRuns` dedupes on
+        // (surface, tier, script) and does NOT include `how`, so a second attribution
+        // of the same pair does not sit beside the first, it REPLACES it — and with
+        // both records stamped the same `at`, `held.at <= run.at` hands the win to
+        // whichever was pushed last.
+        //
+        // The ordering is the same one this file already applies one level up: a
+        // direct observation of the surface being exercised outranks an inference
+        // from where a file sits. Emitting both and teaching the merge to keep the
+        // stronger was the alternative; it costs a wider key, a second record per
+        // pair, and a ranking function — to store a fact that adds nothing, since
+        // both resolve to the same `executed` evidence.
+        const beside = colocatedSurface(run, opts.surfaces, probed);
+        if (beside)
+            pairs.push({ run, probe: { how: "colocated" }, surface: beside });
+    }
     for (const { run, probe, surface } of pairs) {
         const key = `${surface.path}\u0000${run.file}\u0000${probe.how}`;
         if (seen.has(key))
@@ -492,7 +610,7 @@ function isCoverageRun(value) {
         typeof r.path === "string" &&
         typeof r.name === "string" &&
         (r.tier === "harness" || r.tier === "eval") &&
-        (r.how === "command" || r.how === "fired" || r.how === "dispatched") &&
+        isAttribution(r.how) &&
         typeof r.by === "string" &&
         typeof r.at === "string" &&
         typeof r.sha === "string");

package/dist/coverage-evidence.d.ts

@@ -27,6 +27,39 @@ export interface CoverableSurface {
 export interface PreparedTest {
     readonly path: string;
 }
+/**
+ * Is `testPath` the colocated test OF this surface — NAMED after it, SITTING
+ * BESIDE it?
+ *
+ * 🔴 THIS USED TO BE WRITTEN TWICE, and the second copy said so in its own
+ * comment: `test-coverage-files.ts` carried a function whose docstring was
+ * *"Mirror of test-coverage.ts `isColocated`"*. A mirror is a promise that two
+ * bodies stay equal, kept by whoever remembers — and this file already documents
+ * three separate occasions where a change landed in one report builder and not
+ * the other ({@link declaredSurfaceName}, {@link hookScriptRefs}). The rule now
+ * has ONE body and three callers: the disk detector, the browser twin, and the
+ * runner that turns an executed script into an execution record
+ * (`coverage-artifact.ts`). There is nothing left to mirror wrong.
+ *
+ * That third caller is why this became shared rather than merely deduplicated.
+ * Colocation and execution were answering the same question — *which surface is
+ * this test about?* — with two different pieces of code, so a script vigiles had
+ * just RUN could not be attributed by the very rule that was already willing to
+ * credit it for existing.
+ *
+ * SEPARATORS ARE NORMALISED FIRST, then POSIX semantics apply. The disk detector
+ * feeds paths from `globSync`, which yields `\` on Windows; the browser twin
+ * feeds file-map keys, which are always `/`. Folding `\` to `/` makes one body
+ * correct for both instead of asking each caller to bring its own path module —
+ * which is exactly the seam the mirror lived in.
+ *
+ * ⚠️ THE COST, STATED: a POSIX file whose NAME literally contains a backslash is
+ * now read as a directory boundary. That is not reachable for either input here —
+ * a skill directory or a test filename with a `\` in it does not survive the glob
+ * patterns that discover it in the first place — and it is the same trade
+ * `hookScriptRefs` already makes one function up.
+ */
+export declare function isColocatedTest(surface: Pick<CoverableSurface, "name" | "path">, testPath: string): boolean;
 /** Wrap a discovered path. Kept as a function so both twins share one shape. */
 export declare function prepareTest(path: string): PreparedTest;
 /** @param filename a BASENAME — callers strip the directory with their own path

package/dist/coverage-evidence.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isColocatedTest = isColocatedTest;
 exports.prepareTest = prepareTest;
 exports.isEvalScript = isEvalScript;
 exports.hookScriptRefs = hookScriptRefs;
@@ -91,13 +92,71 @@ exports.declaredSurfaceName = declaredSurfaceName;
  * impossible there and its count is 0 — see `test-coverage-files.ts`.
  */
 const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
+const posix_path_js_1 = require("./posix-path.js");
+const source_refs_js_1 = require("./core/source-refs.js");
+/**
+ * Is `testPath` the colocated test OF this surface — NAMED after it, SITTING
+ * BESIDE it?
+ *
+ * 🔴 THIS USED TO BE WRITTEN TWICE, and the second copy said so in its own
+ * comment: `test-coverage-files.ts` carried a function whose docstring was
+ * *"Mirror of test-coverage.ts `isColocated`"*. A mirror is a promise that two
+ * bodies stay equal, kept by whoever remembers — and this file already documents
+ * three separate occasions where a change landed in one report builder and not
+ * the other ({@link declaredSurfaceName}, {@link hookScriptRefs}). The rule now
+ * has ONE body and three callers: the disk detector, the browser twin, and the
+ * runner that turns an executed script into an execution record
+ * (`coverage-artifact.ts`). There is nothing left to mirror wrong.
+ *
+ * That third caller is why this became shared rather than merely deduplicated.
+ * Colocation and execution were answering the same question — *which surface is
+ * this test about?* — with two different pieces of code, so a script vigiles had
+ * just RUN could not be attributed by the very rule that was already willing to
+ * credit it for existing.
+ *
+ * SEPARATORS ARE NORMALISED FIRST, then POSIX semantics apply. The disk detector
+ * feeds paths from `globSync`, which yields `\` on Windows; the browser twin
+ * feeds file-map keys, which are always `/`. Folding `\` to `/` makes one body
+ * correct for both instead of asking each caller to bring its own path module —
+ * which is exactly the seam the mirror lived in.
+ *
+ * ⚠️ THE COST, STATED: a POSIX file whose NAME literally contains a backslash is
+ * now read as a directory boundary. That is not reachable for either input here —
+ * a skill directory or a test filename with a `\` in it does not survive the glob
+ * patterns that discover it in the first place — and it is the same trade
+ * `hookScriptRefs` already makes one function up.
+ */
+function isColocatedTest(surface, testPath) {
+    const test = posixly(testPath);
+    const home = posixly(surface.path);
+    if (!(0, posix_path_js_1.basename)(test).startsWith(`${surface.name}.`))
+        return false;
+    // A root `SKILL.md` (single-skill-dir target) lives at ".", and discovery
+    // returns top-level files without a "./" prefix — so `dirname` is "." on both
+    // sides and the comparison holds without a special case.
+    return (0, posix_path_js_1.dirname)(test) === (0, posix_path_js_1.dirname)(home);
+}
+function posixly(p) {
+    return p.replaceAll("\\", "/");
+}
 /** Wrap a discovered path. Kept as a function so both twins share one shape. */
 function prepareTest(path) {
     return { path };
 }
-/** A path that looks like a script, inside a `command` string. Both twins used
- * to declare this separately; it lives here now so they cannot drift on it. */
-const SCRIPT_RE = /[\w./${}@-]+\.(?:sh|mjs|cjs|js|ts|py|rb)/g;
+/**
+ * A path that looks like a script, inside a `command` string. Both twins used to
+ * declare this separately; the extension vocabulary and the trailing boundary
+ * now live in `core/source-refs.ts`, shared with the hook scanner, so the three
+ * cannot drift and none can omit the boundary (without it, `hooks.json` matched
+ * as `hooks.js`).
+ *
+ * ⚠️ This one scans a SERIALIZED settings blob rather than a shell parse, so it
+ * cannot tell an operand from inline program text the way `commandWords` can.
+ * It stays a regex because every hit is gated on the file EXISTING before it
+ * becomes a surface — a stray match is dropped, never reported — so the failure
+ * mode here is under-counting, not accusation.
+ */
+const SCRIPT_RE = (0, source_refs_js_1.scriptRefPattern)();
 /**
  * Is this filename one the PAID real-model runner would actually run?
  *

package/dist/coverage-probe.d.ts

@@ -50,12 +50,20 @@
  *    file is named by anyone. That API contract is the feature — it is how you
  *    test a hook you did not write, verbatim as its plugin ships it.
  *
- *  - **The in-process tier CAN, and currently reports nothing.** `loadHook(file)`
- *    resolves the path itself, and `harness-assert.ts` / `load-hook.ts` contain
- *    ZERO `recordSurfaceProbe` calls — so the tier where attribution needs no
- *    parsing at all is the tier that attributes nothing. That is a real gap and a
- *    better source of truth than any parse, but it ADDS a source; it cannot
- *    retire this one while `runHook(command)` remains public.
+ *  - **The in-process tier CAN — and since 2026-08-13 it DOES.** ⚠️ This bullet
+ *    used to read *"`harness-assert.ts` / `load-hook.ts` contain ZERO
+ *    `recordSurfaceProbe` calls — the tier where attribution needs no parsing at
+ *    all is the tier that attributes nothing"*, and that is no longer true:
+ *    `runCountedHookProgram` in harness-assert.ts records a `command` probe for a
+ *    hook it is about to evaluate, when `loadHook` knew the file. Verified by
+ *    count, not by memory — `harness-assert.ts` has the call, `load-hook.ts`
+ *    still does not, and deliberately so (loading a hook is not running it; see
+ *    that function's note). Left corrected rather than deleted because a header
+ *    that advertises a gap somebody already closed sends the next reader to build
+ *    a second recorder.
+ *
+ *    It did not retire this parser, as predicted: it ADDS a source, and
+ *    `runHook(command)` is still public.
  *
  * So parsing stays, and the lesson taken instead is about DIRECTION. The scan was
  * a deny-list — skip what we recognise, attribute what is left — so every gap in

package/dist/coverage-probe.js

@@ -56,12 +56,20 @@ exports.probeTrace = probeTrace;
  *    file is named by anyone. That API contract is the feature — it is how you
  *    test a hook you did not write, verbatim as its plugin ships it.
  *
- *  - **The in-process tier CAN, and currently reports nothing.** `loadHook(file)`
- *    resolves the path itself, and `harness-assert.ts` / `load-hook.ts` contain
- *    ZERO `recordSurfaceProbe` calls — so the tier where attribution needs no
- *    parsing at all is the tier that attributes nothing. That is a real gap and a
- *    better source of truth than any parse, but it ADDS a source; it cannot
- *    retire this one while `runHook(command)` remains public.
+ *  - **The in-process tier CAN — and since 2026-08-13 it DOES.** ⚠️ This bullet
+ *    used to read *"`harness-assert.ts` / `load-hook.ts` contain ZERO
+ *    `recordSurfaceProbe` calls — the tier where attribution needs no parsing at
+ *    all is the tier that attributes nothing"*, and that is no longer true:
+ *    `runCountedHookProgram` in harness-assert.ts records a `command` probe for a
+ *    hook it is about to evaluate, when `loadHook` knew the file. Verified by
+ *    count, not by memory — `harness-assert.ts` has the call, `load-hook.ts`
+ *    still does not, and deliberately so (loading a hook is not running it; see
+ *    that function's note). Left corrected rather than deleted because a header
+ *    that advertises a gap somebody already closed sends the next reader to build
+ *    a second recorder.
+ *
+ *    It did not retire this parser, as predicted: it ADDS a source, and
+ *    `runHook(command)` is still public.
  *
  * So parsing stays, and the lesson taken instead is about DIRECTION. The scan was
  * a deny-list — skip what we recognise, attribute what is left — so every gap in