@event4u/agent-config 16.3.0 → 16.5.0

package/dist/scripts/_lib/installed_layer.js

@@ -40,11 +40,14 @@
  * {@link InstalledLayerReport.manifest_present} is in the output.
  */
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { GLOBAL_RULE_DIRS, PROJECT_RULE_DIRS, globalRuleLayerPath, } from '../../install/globalRuleLayers.js';
 import { NO_RECORDED_HASHES, readRecordedHashes } from '../../install/recordedOwnership.js';
-import { ruleBody } from './rule_law_section.js';
+import { INVENTORY_BASENAME, inventory_path, load_inventory, recorded_absolute_files, } from './global_deploy_inventory.js';
+import { DEFAULT_EVENT4U_ROOT_RELATIVE } from './user_global_paths.js';
+import { ruleBody, splitFrontmatter } from './rule_law_section.js';
 /** How many files the per-directory ranking carries. Step 0.1 fixes it at 20. */
 export const TOP_FILES = 20;
 /**
@@ -58,12 +61,33 @@ export const LIMIT_WARN_FRACTION = 0.8;
 /**
  * Whether the host loads this file on every session rather than on a path match.
  *
- * `paths:` at the start of a line is the whole test, and it is the host's own
- * convention rather than this package's: `claudeRuleRewrite.ts` states it from
- * the emitting side — "with it a rule loads on a path match, without it the
- * rule loads unconditionally". `rule_activation_census.projection_reading` asks
- * the installed tree the same question with the same regex, so a file counted
- * unconditional here is counted unconditional there.
+ * `paths:` at the start of a line IN THE FRONTMATTER is the whole test, and it
+ * is the host's own convention rather than this package's: `claudeRuleRewrite`
+ * states it from the emitting side — "with it a rule loads on a path match,
+ * without it the rule loads unconditionally".
+ *
+ * SCOPED TO THE FRONTMATTER, which it was not until 2026-10-06. The predicate
+ * tested the whole unstripped file while the characters it partitions come
+ * from `ruleBody` — predicate and measure read different strings. That was
+ * survivable while it only moved a file COUNT; since the when-loaded character
+ * split it decides which bucket a whole file's characters land in, and
+ * `unconditional_chars` is the figure the ceiling argument is read in. One body
+ * line beginning `paths:` — a YAML trigger example quoted inside a kernel or
+ * `no_stub` rule, which is ordinary prose — would have moved that rule's entire
+ * character count from standing to path-scoped, silently.
+ *
+ * Measured before the change: of the 105 files on a real opted-in install, two
+ * are path-scoped by either reading and none carries a body-only mention, so
+ * the fix moves no published figure. It is hardening against a case that does
+ * not exist yet rather than a correction of one that does, and it is worth
+ * making precisely because the failure would be silent.
+ *
+ * `check_single_delivery` already slices the frontmatter before this test, so
+ * this now AGREES with it. `rule_activation_census.projection_reading` still
+ * scans the whole file; that reader counts files rather than characters, so the
+ * divergence costs it nothing today, and changing a census's reading belongs to
+ * that census rather than here. Named so the next reader finds a known
+ * difference instead of discovering an unexplained one.
  *
  * SOURCE-SIDE CLASSIFICATION IS A DIFFERENT QUESTION and deliberately not used.
  * `classify_rule` reads `alwaysApply` and `type: always` to tell `always` from
@@ -73,7 +97,48 @@ export const LIMIT_WARN_FRACTION = 0.8;
  * both load every session, which is the only property the host acts on.
  */
 export function isUnconditional(text) {
-    return !/^paths:/m.test(text);
+    // THE SAME FUNCTION that produces the characters being partitioned, not the
+    // same arithmetic re-implemented. An earlier version scanned for
+    // `'\n---'` while `ruleBody` -> `splitFrontmatter` scans for `'\n---\n'`,
+    // so the two disagreed about where the frontmatter stops, and the
+    // predicate's early stop could hide a later `paths:` key.
+    const [frontmatter] = splitFrontmatter(text);
+    // AND THE BLIND SPOT THAT SCOPING OPENS, CLOSED HERE. `splitFrontmatter`
+    // returns `''` for anything that does not begin exactly `---\n` — a BOM, a
+    // leading blank line, CRLF, a block that never closes — and scoping to `''`
+    // reads every such file as unconditional even when its frontmatter carries
+    // `paths:`. `readLayer` measures every `.md` in a host directory, foreign
+    // user-authored rules included, so that would inflate `unconditional_chars`
+    // silently, which is the figure the whole ceiling argument is read in.
+    //
+    // A file that CLAIMS a block `splitFrontmatter` could not parse falls back
+    // to the whole-text test. The claim test is the one `installThinLayer`
+    // already uses for the same blind spot, and is a regex rather than
+    // `startsWith('---')` for the reason stated there.
+    //
+    // WHICH WAY THE FALLBACK ERRS, SAID PLAINLY RATHER THAN CALLED
+    // "CONSERVATIVE". It can only move characters OUT of the standing bucket,
+    // never into it. That is conservative about the claim "this rule stands
+    // every session" — it never asserts one it cannot support. It is the
+    // FLATTERING direction for the ceiling argument, which reads the standing
+    // figure against a limit: a misfire here makes the layer look smaller than
+    // it is. Both halves are true and the second is the one a reader checking
+    // the overage needs, so it is stated rather than left to the word.
+    //
+    // AND THE STATE THAT IS NOT AN UNPARSEABLE BLOCK. `splitFrontmatter`
+    // returns '' for a WELL-FORMED EMPTY block too — `---\n---\n` has no
+    // `\n---\n` after index 4, so its own parse fails — and such a file has no
+    // `paths:` key by construction. Without the second test it fell to the
+    // whole-text scan and a body line beginning `paths:` (a quoted trigger
+    // example, which is exactly what a rule about triggers contains) moved the
+    // file's entire character count out of the standing figure. Measured
+    // before the exclusion: `---\n---\npaths: not a key, just prose\n` read
+    // path-scoped.
+    const emptyBlock = /^---\n---(\n|$)/.test(text);
+    if (frontmatter === '' && !emptyBlock && /^\uFEFF?[\s]*---/.test(text)) {
+        return !/^paths:/m.test(text);
+    }
+    return !/^paths:/m.test(frontmatter);
 }
 /**
  * Measure one directory.
@@ -94,6 +159,8 @@ export function readLayer(host, scope, dir, recorded) {
         foreign: 0,
         package_owned_chars: 0,
         foreign_chars: 0,
+        unconditional_chars: 0,
+        scoped_chars: 0,
         top: [],
     };
     let names;
@@ -153,6 +220,8 @@ export function readLayer(host, scope, dir, recorded) {
         foreign: readings.filter((r) => !r.package_owned).length,
         package_owned_chars: readings.reduce((n, r) => n + (r.package_owned ? r.chars : 0), 0),
         foreign_chars: readings.reduce((n, r) => n + (r.package_owned ? 0 : r.chars), 0),
+        unconditional_chars: readings.reduce((n, r) => n + (r.unconditional ? r.chars : 0), 0),
+        scoped_chars: readings.reduce((n, r) => n + (r.unconditional ? 0 : r.chars), 0),
         top,
     };
 }
@@ -266,6 +335,227 @@ export function buildHostLimitRows(layers, limits) {
     }
     return rows;
 }
+/**
+ * Where `deployed-files.json` lives FOR A STATED HOME.
+ *
+ * `global_deploy_inventory.inventory_path()` answers for the process asking,
+ * honouring `AGENT_CONFIG_DEPLOY_INVENTORY` and `EVENT4U_CONFIG_HOME`. That is
+ * right for the installer, which is running the install it is recording, and
+ * WRONG for a reader measuring some other home: a report about a staged install
+ * under a temporary HOME would read the maintainer's own inventory and claim
+ * ownership of files that install never wrote.
+ *
+ * SO AN EXPLICITLY SUPPLIED HOME WINS, AND THE ENV OVERRIDES DECIDE ONLY THE
+ * HOME-LESS CASE. A caller that says which home it is measuring has already
+ * answered the question those variables would answer for it, and letting the
+ * asking process's environment override that is exactly the hazard named above.
+ * An intermediate draft of this function had the precedence the other way round
+ * while this paragraph said what it says now; the code is what changed.
+ *
+ * THE CONSEQUENCE, STATED RATHER THAN IMPLIED: `ReportOptions.home` is
+ * REQUIRED, so every caller of {@link buildInstalledLayerReport} supplies one
+ * and neither env override reaches this reader through that path. That is
+ * correct — those variables describe the asking process's own install, which is
+ * not what a report about another home is measuring — but it means "honours the
+ * env override" is not a true sentence about the report, and saying so here is
+ * cheaper than leaving the next reader to discover it.
+ *
+ * The layout is COMPOSED from the modules that own it rather than re-spelled,
+ * so a layout change moves this reader with it instead of leaving it looking in
+ * a directory nobody writes.
+ */
+export function defaultInventoryPath(home) {
+    // NO HOME STATED — the asking process is the subject, so the env-aware
+    // resolver is the right answer.
+    if (home === undefined || home === null || home === '')
+        return inventory_path();
+    // THE STATED HOME IS THE ASKING PROCESS'S OWN. `ReportOptions.home` is
+    // required, so `buildInstalledLayerReport` ALWAYS states one — including
+    // when it is simply measuring the machine it is running on. Treating that
+    // as "a different home" sent it to the hardcoded layout, found nothing
+    // under `EVENT4U_CONFIG_HOME` or `AGENT_CONFIG_DEPLOY_INVENTORY`, and
+    // printed "NO manifest and NO deploy inventory resolved" — the
+    // `0 package-owned` reading step 1.2 exists to remove, and it put the
+    // report and the receipt in disagreement about one install.
+    //
+    // The precedence argument only ever covered a home that is NOT this
+    // process's, so that is the case the branch now tests for.
+    try {
+        // BOTH SPELLINGS, for the reason `recorded_absolute_files` states at
+        // length: a lexical compare alone calls a symlinked or alternate
+        // spelling of the SAME home "a different home", takes the hardcoded
+        // layout, and reproduces the 0 package-owned reading this branch
+        // exists to prevent. macOS `/var` -> `/private/var` is the standing
+        // example.
+        const real = (q) => {
+            try {
+                return fs.realpathSync(q);
+            }
+            catch {
+                return path.resolve(q);
+            }
+        };
+        const mine = os.homedir();
+        if (path.resolve(home) === path.resolve(mine) || real(home) === real(mine)) {
+            return inventory_path();
+        }
+    }
+    catch {
+        // `homedir()` can throw on an exotic environment; fall through to the
+        // layout, which is the answer for a home that is not ours anyway.
+    }
+    return path.join(home, DEFAULT_EVENT4U_ROOT_RELATIVE, INVENTORY_BASENAME);
+}
+/**
+ * The ONE place that answers "which of these installed files are ours".
+ *
+ * Two readers ask it — the installed-layer report and the install receipt's
+ * budget lines — and until step 1.2 they asked different things. Both called
+ * `manifest_path(...)` and read a project-scoped `agents/installed-tools.lock`.
+ * A global-only install writes nothing into a project, so on exactly the
+ * install shape the thinned-layer roadmap's AC-1 is about, both reported
+ * `0 package-owned / N foreign` and AC-1's figure could not be produced at all.
+ *
+ * The global install DOES record what it wrote: `deployed-files.json` lists,
+ * per tool, the anchor and every file the installer maintains there —
+ * "the ownership proof that makes reaping safe". This reads it.
+ *
+ * IT IS A UNION, AND THE PATH SPACES ARE WHY. An earlier shape let the project
+ * manifest win OUTRIGHT whenever its file existed, on the reasoning that it
+ * carries hashes an inventory does not. That reasoning does not survive the
+ * observation that the two sources describe DISJOINT sets of paths: the
+ * manifest records project-relative entries resolved against `projectRoot`,
+ * the inventory records paths under the user's home. Exclusivity therefore
+ * bought nothing and cost everything — any `agents/installed-tools.lock` on
+ * disk, a gitignored file a single project-scoped install creates, restored
+ * the exact `0 package-owned` reading for the global layer that step 1.2
+ * exists to fix, while the report printed "read from the installed-tools
+ * manifest" with no evidence behind it for those paths.
+ *
+ * So every source contributes, and the MANIFEST IS MERGED LAST: on the paths
+ * it names its hash overwrites a hashless entry, which preserves the
+ * `recorded-unchanged` / `recorded-modified` distinction that motivated the
+ * precedence in the first place, without discarding evidence about paths it
+ * says nothing about.
+ *
+ * {@link OwnershipResolution.sources} lists every source that contributed at
+ * least one path, because one word cannot describe two path spaces — a report
+ * reading global and project layers together may have manifest evidence for
+ * one and inventory evidence for the other, and saying only one of them is
+ * wrong about half the files it is describing.
+ *
+ * A FILE THE USER EDITED AND THE INSTALLER PRESERVED STILL COUNTS AS
+ * MAINTAINED. The inventory records what the installer MAINTAINS at a path, not
+ * what the bytes currently are, so a preserved rule stays package-owned. That
+ * is the correct reading — the package is still responsible for the path — and
+ * it is why this function returns `null` hashes rather than fabricating one.
+ */
+export function resolveLayerOwnership(opts) {
+    const recorded = new Map();
+    const sources = [];
+    // HASHLESS SOURCES FIRST, so the manifest's hashes overwrite a `null` on
+    // any path both happen to name rather than the other way round.
+    if (opts.inventoryPath !== null) {
+        let n = 0;
+        try {
+            const inv = load_inventory(opts.inventoryPath ?? defaultInventoryPath(opts.home));
+            for (const abs of recorded_absolute_files(inv, opts.home ?? null)) {
+                // COUNT PATHS NEWLY CONTRIBUTED, not entries read, so a
+                // source that added nothing is not named as evidence.
+                //
+                // WHAT THIS GUARD DOES NOT DO, since an earlier comment here
+                // claimed it did: it does not collapse the two spellings
+                // `recorded_absolute_files` emits per file. The lexical and the
+                // realpath spelling are distinct Map keys, so wherever they
+                // differ — every path under macOS `/var` — each is newly
+                // contributed and `n` still rises twice for one file. Harmless
+                // only because `n` is read as `> 0` and never as a count; a
+                // future reader wanting a count must not take it from here.
+                if (!recorded.has(abs))
+                    n += 1;
+                recorded.set(abs, null);
+            }
+        }
+        catch {
+            // Defence in depth, and NOT where the documented behaviour lives.
+            // "A corrupt inventory is no evidence, never a failure" is real but
+            // is carried one module down: `load_inventory` swallows its own
+            // read and parse failures and returns an empty shell, and
+            // `recorded_absolute_files` type-guards every field. So this catch
+            // is unreachable for that reason and the fixture case named for it
+            // exercises `load_inventory`, not this guard. Kept because a future
+            // change to either could make it reachable; labelled so it is not
+            // mistaken for tested coverage.
+        }
+        if (n > 0)
+            sources.push('global-inventory');
+    }
+    let fromDeploy = 0;
+    for (const [anchor, rels] of opts.thisDeploy ?? new Map()) {
+        for (const rel of rels) {
+            const abs = path.resolve(anchor, rel);
+            // Same rule as the inventory branch: a source is named only when it
+            // contributes a path nothing else had. On every install after the
+            // first, `thisDeploy`'s paths are already in the inventory, and
+            // naming it there printed "the file set this install just wrote"
+            // for a source that added nothing.
+            if (!recorded.has(abs))
+                fromDeploy += 1;
+            recorded.set(abs, null);
+            // Both spellings, for the reason `recorded_absolute_files` states:
+            // the reader compares against a lexically joined path, and a HOME
+            // behind a symlink makes the two disagree.
+            try {
+                recorded.set(fs.realpathSync(abs), null);
+            }
+            catch {
+                // Not on disk — the lexical spelling is all there is.
+            }
+        }
+    }
+    if (fromDeploy > 0)
+        sources.push('this-deploy');
+    const manifestPath = opts.manifestPath ?? null;
+    if (manifestPath !== null && fs.existsSync(manifestPath)) {
+        let n = 0;
+        // DEGRADE LIKE THE INVENTORY BRANCH, which this function documents
+        // twice. The code this replaced wrapped exactly this call, so a corrupt
+        // `installed-tools.lock` used to read as "no manifest evidence" and the
+        // budget block still printed. Unguarded it threw into the receipt's
+        // outer catch and suppressed the WHOLE block — ownership line, per-host
+        // rows and the 80 % warning — and out of `buildInstalledLayerReport`,
+        // which has no outer catch at all. An unreadable manifest is no
+        // evidence, never a failure; the asymmetry was undeclared.
+        let recordedHashes;
+        try {
+            recordedHashes = readRecordedHashes(manifestPath, opts.projectRoot);
+        }
+        catch {
+            recordedHashes = NO_RECORDED_HASHES;
+        }
+        for (const [abs, hash] of recordedHashes) {
+            // The manifest contributes whenever it names a path at all: it
+            // supplies the HASH even where another source already had the path,
+            // which is evidence the others cannot give.
+            n += 1;
+            recorded.set(abs, hash);
+        }
+        if (n > 0)
+            sources.push('manifest');
+    }
+    if (recorded.size === 0) {
+        return { recorded: NO_RECORDED_HASHES, sources: [], source: 'none' };
+    }
+    // `source` keeps a single word for readers that want one. The manifest is
+    // the most specific evidence, so it leads when it contributed; otherwise
+    // the inventory, otherwise this deploy's own set.
+    const primary = sources.includes('manifest')
+        ? 'manifest'
+        : sources.includes('global-inventory')
+            ? 'global-inventory'
+            : 'this-deploy';
+    return { recorded, sources, source: primary };
+}
 /**
  * Read every host rule directory in both scopes.
  *
@@ -276,9 +566,12 @@ export function buildHostLimitRows(layers, limits) {
  */
 export function buildInstalledLayerReport(opts) {
     const manifestPath = opts.manifestPath ?? null;
-    const recorded = manifestPath === null
-        ? NO_RECORDED_HASHES
-        : readRecordedHashes(manifestPath, opts.projectRoot);
+    const { recorded, source: ownership_source, sources: ownership_sources } = resolveLayerOwnership({
+        manifestPath,
+        projectRoot: opts.projectRoot,
+        home: opts.home,
+        inventoryPath: opts.inventoryPath,
+    });
     const layers = [];
     for (const host of Object.keys(GLOBAL_RULE_DIRS).sort()) {
         const dir = globalRuleLayerPath(host, opts.home);
@@ -298,6 +591,8 @@ export function buildInstalledLayerReport(opts) {
         foreign: acc.foreign + l.foreign,
         package_owned_chars: acc.package_owned_chars + l.package_owned_chars,
         foreign_chars: acc.foreign_chars + l.foreign_chars,
+        unconditional_chars: acc.unconditional_chars + l.unconditional_chars,
+        scoped_chars: acc.scoped_chars + l.scoped_chars,
     }), {
         files: 0,
         unconditional: 0,
@@ -306,6 +601,8 @@ export function buildInstalledLayerReport(opts) {
         foreign: 0,
         package_owned_chars: 0,
         foreign_chars: 0,
+        unconditional_chars: 0,
+        scoped_chars: 0,
     });
     const limits = buildHostLimitRows(layers, loadHostInstructionLimits(opts.hostLimitsPath ?? defaultHostLimitsPath()));
     return {
@@ -313,34 +610,63 @@ export function buildInstalledLayerReport(opts) {
         project_root: opts.projectRoot,
         host_version: opts.hostVersion ?? 'unknown',
         manifest_present: manifestPath !== null && fs.existsSync(manifestPath),
+        ownership_source,
+        ownership_sources,
         layers,
         limits,
         totals,
     };
 }
+/**
+ * One line naming WHICH evidence answered ownership.
+ *
+ * Exported so the report and the install receipt say the same sentence about
+ * the same source — a consumer comparing a receipt against a later report must
+ * not have to decide whether a wording difference means a different reading.
+ */
+export function ownershipLine(sources) {
+    const list = (Array.isArray(sources) ? sources : [sources]).filter((s) => s !== 'none');
+    if (list.length === 0) {
+        return 'ownership: NO manifest and NO deploy inventory resolved — every file reads foreign, which is no evidence rather than a finding';
+    }
+    // EVERY contributor is named, never just one. The sources cover disjoint
+    // path spaces, so a line naming one of two is a true sentence about half
+    // the files and a false one about the rest.
+    const phrases = {
+        manifest: 'the installed-tools manifest',
+        'global-inventory': 'the global deploy inventory (deployed-files.json)',
+        'this-deploy': 'the file set this install just wrote',
+    };
+    const named = list.map((s) => phrases[s]);
+    const joined = named.length === 1
+        ? named[0]
+        : `${named.slice(0, -1).join(', ')} and ${named[named.length - 1]}`;
+    return `ownership: read from ${joined}`;
+}
 /** The report as lines, for a terminal. One directory per block. */
 export function renderInstalledLayerReport(report) {
     const out = [];
     out.push(`installed layer — host ${report.host_version}, HOME ${report.home}`);
     out.push(`project ${report.project_root}`);
-    out.push(report.manifest_present
-        ? 'ownership: read from the installed-tools manifest'
-        : 'ownership: NO manifest resolved — every file reads foreign, which is no evidence rather than a finding');
+    out.push(ownershipLine(report.ownership_sources));
     for (const l of report.layers) {
         if (!l.present) {
             out.push(`  ${l.host} (${l.scope}) — absent: ${l.dir}`);
             continue;
         }
-        out.push(`  ${l.host} (${l.scope}) — ${String(l.files)} files, ` +
-            `${String(l.unconditional)} unconditional, ${String(l.chars)} chars, ` +
+        out.push(`  ${l.host} (${l.scope}) — ${String(l.files)} files ` +
+            `(${String(l.unconditional)} unconditional), ${String(l.chars)} chars ` +
+            `(${String(l.unconditional_chars)} standing + ${String(l.scoped_chars)} path-scoped), ` +
             `${String(l.package_owned)} package-owned / ${String(l.foreign)} foreign`);
         for (const f of l.top) {
             out.push(`      ${String(f.chars).padStart(7)}  ${f.unconditional ? 'uncond' : 'scoped'}  ${f.file}`);
         }
     }
     const t = report.totals;
-    out.push(`  TOTAL — ${String(t.files)} files, ${String(t.unconditional)} unconditional, ` +
-        `${String(t.chars)} chars, ${String(t.package_owned)} package-owned / ${String(t.foreign)} foreign`);
+    out.push(`  TOTAL — ${String(t.files)} files (${String(t.unconditional)} unconditional), ` +
+        `${String(t.chars)} chars ` +
+        `(${String(t.unconditional_chars)} standing + ${String(t.scoped_chars)} path-scoped), ` +
+        `${String(t.package_owned)} package-owned / ${String(t.foreign)} foreign`);
     out.push(...renderHostLimitRows(report.limits));
     return out;
 }

package/dist/scripts/_lib/package_root.js

@@ -0,0 +1,68 @@
+/**
+ * Layout-independent package-root resolution for the `_cli` delegate commands.
+ *
+ * `src/scripts/_cli/*.ts` sits three levels below the package root, so every
+ * delegate command derived the root with three hard-coded parent hops. Then the
+ * delegate precompile (`fa51c5a54`) started bundling those same modules into
+ * `dist/cli-delegate/*.js` — **two** levels below the root. Fixed hop counts are
+ * correct in exactly one of the two layouts, and nothing failed loudly: three
+ * hops from the bundle lands on `<pkg>/..`, which for a scoped install is
+ * `node_modules/@event4u`. `conformance` then reported `dist/router.json` and
+ * `src/scripts/hook_manifest.yaml` as missing — files that ship fine — and the
+ * 9.11.0 release PR's `tarball E2E` went red on both Node majors.
+ *
+ * The fix is to stop counting hops. Anchor on the marker that actually defines
+ * the root: the `package.json` whose `name` is this package. That answer holds
+ * for the source tree, for any bundle depth, for npm-global, npx, and
+ * vendor/bin symlink invocations — and it keeps holding if either directory
+ * ever moves.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** `name` in this package's own package.json — the root marker. */
+export const PACKAGE_NAME = '@event4u/agent-config';
+/**
+ * Bound on the upward walk. Deep enough for any real install path, finite so a
+ * malformed start value can never spin.
+ */
+const MAX_ASCENT = 16;
+/**
+ * Absolute package root for the module at `fromUrlOrPath` (pass
+ * `import.meta.url`).
+ *
+ * Walks up looking for the package.json whose `name` is {@link PACKAGE_NAME}.
+ * A consumer's own package.json encountered on the way is skipped by that name
+ * check, so an install nested under another project resolves correctly.
+ *
+ * `legacyHops` is the pre-existing hop count for the *source* layout and is
+ * used only if no marker is found. Falling back beats throwing during CLI
+ * startup: a wrong path yields one actionable "missing file" message, while an
+ * exception takes down every command in the delegate.
+ */
+export function resolvePackageRoot(fromUrlOrPath, legacyHops = 3) {
+    const start = fromUrlOrPath.startsWith('file:') ? fileURLToPath(fromUrlOrPath) : fromUrlOrPath;
+    const startDir = path.dirname(start);
+    let dir = startDir;
+    for (let i = 0; i < MAX_ASCENT; i++) {
+        const manifest = path.join(dir, 'package.json');
+        if (fs.existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+                if (parsed.name === PACKAGE_NAME) {
+                    return dir;
+                }
+            }
+            catch {
+                // Unreadable / unparseable manifest — not our marker; keep ascending.
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break; // filesystem root
+        }
+        dir = parent;
+    }
+    return path.resolve(startDir, ...Array.from({ length: legacyHops }, () => '..'));
+}
+//# sourceMappingURL=package_root.js.map

package/dist/scripts/_lib/rule_law_section.js

@@ -25,7 +25,7 @@
  * law in bold prose or a bare fence under no heading at all — several of the 35
  * routed rules without a heading match do exactly that. A heading match is a
  * STRUCTURAL property, checkable; "this sentence is the obligation" is not, and
- * `report_obligation_carriers` plus the `# obligation: line N` marker is where
+ * `report_obligation_carriers` plus the ids in `src/config/rule-obligations.json` is where
  * that question already lives.
  */
 import * as fs from 'node:fs';

package/dist/scripts/_lib/scan_scope.js

@@ -0,0 +1,105 @@
+/**
+ * Scan-scope assertions — "a gate that read nothing did not pass".
+ *
+ * WHY THIS EXISTS (audit 2026-07-29, `agents/settings/contexts/gates-that-cannot-fail.md`):
+ * ADR-051 moved the source container and a later commit deleted `packages/`.
+ * Fourteen `lint_*`/`check_*` gates kept a hardcoded literal path, and every
+ * one of them treats a missing directory as "nothing to check" — so they exit 0
+ * and print a green checkmark while scanning zero files. Their own output said
+ * so (`0 file(s) scanned`, `0 name(s) checked`, `0 declarer(s)`); nothing ever
+ * asserted on the number.
+ *
+ * Two shapes cover the whole class:
+ *
+ * - **Corpus gates** walk a root and check N units → {@link assertScanned}.
+ *   Zero units is a failure unless the gate declares a justified `allowEmpty`.
+ * - **Watch-list gates** (diff-based, no corpus to count) name specific files
+ *   they guard → {@link assertWatchlistResolves}. A watch list that resolves to
+ *   nothing on disk means the guard is watching phantoms.
+ *
+ * Both throw {@link DeadScopeError}; callers map it to a non-zero exit. The
+ * point is that the failure is LOUD and names the root, so the next path
+ * migration cannot silently disarm a gate again.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+/** Raised when a gate's scope is empty — it cannot have checked anything. */
+export class DeadScopeError extends Error {
+    gate;
+    constructor(gate, message) {
+        super(message);
+        this.name = 'DeadScopeError';
+        this.gate = gate;
+    }
+}
+/**
+ * Assert a corpus gate examined at least one unit.
+ *
+ * @throws {DeadScopeError} when `scanned === 0` and no `allowEmpty` reason is given.
+ */
+export function assertScanned(opts) {
+    if (opts.scanned > 0) {
+        return;
+    }
+    if (opts.allowEmpty !== undefined && opts.allowEmpty.trim() !== '') {
+        return;
+    }
+    const roots = opts.roots.length > 0 ? opts.roots.join(', ') : '(no root declared)';
+    throw new DeadScopeError(opts.gate, `${opts.gate}: scanned 0 ${opts.units} under ${roots} — the scan scope is ` +
+        'dead or the root moved. A gate that read nothing has not passed. ' +
+        'Repoint the root (prefer the shared resolver in _lib/agent_src.ts), ' +
+        'or declare a justified `allowEmpty` reason if an empty corpus is genuinely expected.');
+}
+/**
+ * Assert a corpus gate's scope AND publish the count it just validated.
+ *
+ * The two halves of scope hardening drifted apart in practice: 14 gates emit
+ * the machine-readable `scanned:` line the coverage guard reads, 12 assert
+ * their scope, and only 8 do both. A gate that publishes a number it never
+ * asserted can print `scanned: 0` and exit green; a gate that asserts without
+ * publishing is invisible to `check_gate_coverage`. Splitting the two also
+ * lets the published number drift from the number that was validated — the
+ * invented-count failure that is mechanically undetectable downstream.
+ *
+ * One call closes both: the emitted number is, by construction, the number the
+ * assertion just accepted. Use this for any gate that should also carry a floor
+ * in `src/config/gate-coverage.yml`; plain {@link assertScanned} stays correct
+ * for a gate that only needs its scope guarded.
+ *
+ * The line goes to stdout unconditionally — a count only visible without
+ * `--quiet` is not a count, since CI passes `--quiet` (the `lint_handoffs`
+ * lesson, preserved here so no caller has to rediscover it).
+ */
+export function reportScanned(opts, write = process.stdout.write.bind(process.stdout)) {
+    assertScanned(opts);
+    write(`scanned: ${String(opts.scanned)}\n`);
+}
+/**
+ * Assert a watch-list gate's targets exist on disk, and return the ones that do.
+ *
+ * A diff-based guard has no corpus to count: it compares changed paths against
+ * a fixed list. If that list resolves to nothing, the guard reports "clean"
+ * forever — the exact shape of the `check_safety_floor_untouched` defect, which
+ * announced `4 rules guarded` while guarding none.
+ *
+ * @returns the subset of `candidates` that exist.
+ * @throws {DeadScopeError} when none of them exist.
+ */
+export function assertWatchlistResolves(opts) {
+    const resolved = opts.candidates.filter((rel) => {
+        try {
+            return fs.statSync(path.join(opts.repoRoot, rel)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+    if (resolved.length === 0) {
+        throw new DeadScopeError(opts.gate, `${opts.gate}: none of its ${opts.candidates.length} guarded path(s) exist ` +
+            `under ${opts.repoRoot} — the guard is watching phantoms and can never fire. ` +
+            `Checked: ${opts.candidates.join(', ')}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=scan_scope.js.map