@event4u/agent-config 16.2.0 → 16.3.0

package/dist/scripts/_lib/agent_settings.js

@@ -266,6 +266,17 @@ export const MERGEABLE_KEYS = [
     // GUI; whitelisting decides only whether the value SURVIVES the merge
     // (ADR-271, road-to-design-intent-conformance 2.3).
     'design.fidelity_mode',
+    // `lean_projection.*` is a per-MACHINE setting and the install it governs is
+    // a user-scope one: the layer being thinned is `~/.claude/rules`, which
+    // belongs to the machine and not to any checkout. Without these two rows a
+    // consumer who wrote the opt-in into the user-global file got no error, no
+    // warning and no effect — the same silent-filter defect the two entries
+    // above repair, reaching a third key, and unsatisfiable-by-construction on
+    // an ADR-020 global-only install, where no project layer exists to carry it.
+    // Whitelisting decides only whether a value SURVIVES the merge: it sets
+    // nothing, and `installerThinsHost` still refuses a template-only value.
+    'lean_projection.mode',
+    'lean_projection.hosts',
 ];
 /** The shipped template, relative to the package root. */
 const TEMPLATE_RELATIVE = path.join('src', 'config', 'agent-settings.template.yml');

package/dist/scripts/_lib/claude_settings_hooks.js

@@ -70,17 +70,19 @@ export function build_claude_hook_matrix(manifest_path) {
     const claude_events = (platforms['claude'] ?? {}) || {};
     const aliasesAll = (manifest['native_event_aliases'] ?? {});
     const aliases = (aliasesAll['claude'] ?? {}) || {};
-    const ac_to_native = {};
-    for (const [native, ac] of Object.entries(aliases)) {
-        ac_to_native[String(ac)] = native;
-    }
+    // Iterating the ALIAS map, not the event map, because the relation is
+    // many-natives-to-one-event and the inversion this replaced silently lost
+    // every native but the last. `PostToolUse` and `PostToolUseFailure` both
+    // lower to `post_tool_use`; building `ac_to_native` would have kept one of
+    // them and UNBOUND the other, turning a routing fix into a routing
+    // regression that no existing test could see. Pinned by
+    // `before_complete_failure_envelope.test.ts` ("both natives stay bound").
     const matrix = {};
-    for (const [ac_event, concerns] of Object.entries(claude_events)) {
+    for (const [native, ac_raw] of Object.entries(aliases)) {
+        const ac_event = String(ac_raw);
+        const concerns = claude_events[ac_event];
         if (!concerns || (Array.isArray(concerns) && concerns.length === 0))
             continue;
-        const native = ac_to_native[ac_event];
-        if (native === undefined)
-            continue;
         // Bundle fast path (road-to-hook-latency-repair Phase 2): invoke the
         // precompiled dispatcher bundle directly — no bash shim, no CLI boot
         // (measured ~450-500 ms CLI vs ~110 ms bundle per event on a 1-vCPU

package/dist/scripts/_lib/installed_layer.js

@@ -0,0 +1,378 @@
+/**
+ * What a host actually loads, measured in the host's own unit (step 0.1 of
+ * `road-to-a-rule-carrier-that-works-outside-the-repo`).
+ *
+ * THE QUESTION NOTHING IN THIS TREE COULD ANSWER. Every existing figure for the
+ * installed layer counts raw bytes of whole files: `censusRuleDir` sums
+ * `statSync().size`, `charsAtRoot` does the same for a directory, and
+ * `check_preamble_payload_budget` reads both. A host does not load frontmatter
+ * as instruction — it is the routing surface, which the router has already
+ * read — and it does not render HTML comments, which are authoring scaffolding.
+ * So the number a reader wants when they ask "how much instruction is this
+ * consumer under" has never been computed here.
+ *
+ * THE NUMBER IS THEREFORE NOT COMPARABLE WITH ANY PUBLISHED BASELINE, and that
+ * is stated here rather than discovered by someone holding the two side by
+ * side. `chars` below is strictly smaller than the byte figures in
+ * `budgets.yml`, `rule-activation-census.json` or the payload ratchet, and the
+ * gap is not a constant — it is whatever that particular corpus spends on
+ * frontmatter and comments.
+ *
+ * ONE LIBRARY, FOUR CONSUMERS. The report CLI is the only one wired in this
+ * change (Phase 0 makes no behavior change), and the shape is the reason the
+ * other three named in step 0.1 — CI, `doctor`, the upgrade receipt — can use
+ * it without a second reader: every input is a PARAMETER. `home`, `projectRoot`
+ * and `manifestPath` are supplied by the caller, never read off the process, so
+ * a test, a temporary `HOME` and a real machine are the same call with
+ * different arguments. That is also what makes the step's "install into a
+ * temporary HOME" reachable at all, and it is the fact that refutes
+ * `check_standing_rule_delivery`'s header: a user-scope install IS observable
+ * from CI, because the installer takes `HOME` from the environment.
+ *
+ * WHAT `package_owned` AND `foreign` MEAN, because the honest answer is three
+ * valued and the report has two columns. `recordedOwnership` distinguishes
+ * `recorded-unchanged`, `recorded-modified` and `unknown`, where `unknown` is
+ * explicitly "this tree cannot say" rather than "foreign". The report folds the
+ * first two into `package_owned` — both are files the manifest claims — and
+ * reports the third as `foreign`, which therefore reads "not claimed by this
+ * install", never "written by someone else". A machine with no manifest reports
+ * every file foreign, which is the correct reading of no evidence and is why
+ * {@link InstalledLayerReport.manifest_present} is in the output.
+ */
+import * as fs from 'node:fs';
+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';
+/** How many files the per-directory ranking carries. Step 0.1 fixes it at 20. */
+export const TOP_FILES = 20;
+/**
+ * The fraction of a published limit at which the report warns.
+ *
+ * 0.8 is step 1.4's number, not a tuned one. It is a WARNING threshold and
+ * never a gate: crossing it changes what the report says and nothing else, so
+ * no install fails here.
+ */
+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.
+ *
+ * SOURCE-SIDE CLASSIFICATION IS A DIFFERENT QUESTION and deliberately not used.
+ * `classify_rule` reads `alwaysApply` and `type: always` to tell `always` from
+ * `unconditional`, which matters when you are deciding what to emit. This
+ * reads what WAS emitted, where the distinction has already been spent: an
+ * Iron-Law rule and an untriggered tier-2 rule both arrive without `paths:` and
+ * both load every session, which is the only property the host acts on.
+ */
+export function isUnconditional(text) {
+    return !/^paths:/m.test(text);
+}
+/**
+ * Measure one directory.
+ *
+ * `.md` only, matching `censusRuleDir` and `topRulesByCost`, so the FILE count
+ * is comparable with the existing byte censuses even though the character count
+ * is not. Cursor's `.mdc` tree is therefore read as zero files, which is the
+ * same blind spot every other census in this tree has and is not fixed here —
+ * fixing it in one reader and not the others would make two counts that
+ * disagree, which is worse than one that is openly partial.
+ */
+export function readLayer(host, scope, dir, recorded) {
+    const empty = {
+        files: 0,
+        unconditional: 0,
+        chars: 0,
+        package_owned: 0,
+        foreign: 0,
+        package_owned_chars: 0,
+        foreign_chars: 0,
+        top: [],
+    };
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return { host, scope, dir, present: false, ...empty };
+    }
+    const readings = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith('.md'))
+            continue;
+        const abs = path.join(dir, name);
+        let text;
+        try {
+            const st = fs.statSync(abs);
+            if (!st.isFile())
+                continue;
+            text = fs.readFileSync(abs, 'utf-8');
+        }
+        catch {
+            continue; // a file that cannot be read is not a file the host loads
+        }
+        // RECORDED-BUT-MODIFIED IS STILL RECORDED. The report's two columns
+        // answer "does this install claim the file"; `classifyOwnership` answers
+        // the finer question the upgrade path needs — whether the bytes still
+        // match — and folding that in here would give a column three meanings.
+        const owned = recorded.has(abs);
+        readings.push({
+            file: name,
+            // THE STRIP IS THE PROJECTOR'S OWN. `ruleBody` is what
+            // `project_thin_rules` and the delivery carrier both call, so "what
+            // a host loads" and "what a delivery carries" cannot drift into two
+            // spellings of the same measurement.
+            chars: ruleBody(text).length,
+            unconditional: isUnconditional(text),
+            package_owned: owned,
+        });
+    }
+    const top = [...readings]
+        // RANKED BY THE SAME MEASURE AS THE TOTAL, which is why
+        // `preamble_byte_census.topRulesByCost` is not reused here: it ranks by
+        // `statSync().size`, so its list and this total would be in different
+        // units and the largest file by one could be absent from the other.
+        .sort((a, b) => b.chars - a.chars || a.file.localeCompare(b.file))
+        .slice(0, TOP_FILES);
+    return {
+        host,
+        scope,
+        dir,
+        present: true,
+        files: readings.length,
+        unconditional: readings.filter((r) => r.unconditional).length,
+        chars: readings.reduce((n, r) => n + r.chars, 0),
+        package_owned: readings.filter((r) => r.package_owned).length,
+        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),
+        top,
+    };
+}
+/**
+ * Where the limits live, derived from this module rather than from `cwd`.
+ *
+ * The two `..` hops climb from `src/scripts/_lib` to `src/`, which is where
+ * `config/` lives — NOT to the package root, though the comment said so until
+ * 2026-10-05. The result is correct and the arithmetic stated for it was not,
+ * which is the half a future reader would trust when changing the hops.
+ *
+ * `fileURLToPath`, NOT `new URL(...).pathname` — the claimed parity with
+ * `default_template_path()` was only half true until 2026-10-05. A `pathname`
+ * percent-encodes, so a package under a directory with a space resolved to
+ * `/Users/x/My%20Projects/...`, and on Windows it yields a leading-slash drive
+ * path. Either way the read fails, `loadHostInstructionLimits` swallows it and
+ * returns an empty map, and EVERY host then reads `unpublished` with `warn`
+ * false — the budget measurement degrading to "not measured" with no signal,
+ * which is the one failure mode this file's own limit table was written to
+ * avoid.
+ */
+export function defaultHostLimitsPath() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'config', 'host-instruction-limits.json');
+}
+/**
+ * Read the published-limit table.
+ *
+ * TOLERANT IN ONE DIRECTION ONLY. An unreadable or malformed file yields an
+ * EMPTY table, so every host reads `unpublished` and nothing warns — a reading
+ * this tree cannot stand behind must never become a warning it can. A present
+ * entry whose `limit` is not a positive finite number is treated the same way,
+ * because a `0` or a string would otherwise make every install look saturated.
+ */
+export function loadHostInstructionLimits(file = defaultHostLimitsPath()) {
+    const out = new Map();
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return out; // no table ⇒ no limits ⇒ no warnings
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return out;
+    for (const [host, v] of Object.entries(raw)) {
+        if (host.startsWith('_'))
+            continue; // `_comment` and friends are not hosts
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            continue;
+        const e = v;
+        const n = e.limit;
+        const limit = typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : null;
+        const k = e.kind;
+        const kind = limit === null
+            ? 'unpublished'
+            : k === 'vendor-published' || k === 'reported'
+                ? k
+                : 'reported'; // a cited figure with no stated kind is the weaker one
+        out.set(host, { limit, kind });
+    }
+    return out;
+}
+/**
+ * Fold the per-directory readings into one row per host, against its limit.
+ *
+ * Exported so a caller holding layers it built itself — the install receipt,
+ * which measures before and after — can produce the same rows without
+ * re-reading the tree.
+ */
+export function buildHostLimitRows(layers, limits) {
+    const byHost = new Map();
+    for (const l of layers) {
+        if (!l.present)
+            continue;
+        const acc = byHost.get(l.host) ?? { chars: 0, owned: 0, foreign: 0 };
+        acc.chars += l.chars;
+        acc.owned += l.package_owned_chars;
+        acc.foreign += l.foreign_chars;
+        byHost.set(l.host, acc);
+    }
+    // EVERY host that has a directory gets a row, present or not — a host whose
+    // layer is absent reads 0 against its limit, which is a real answer and the
+    // one step 3.5 asks for ("one row per host with a published limit").
+    for (const l of layers)
+        if (!byHost.has(l.host))
+            byHost.set(l.host, { chars: 0, owned: 0, foreign: 0 });
+    // AND every host the LIMITS table knows, whether or not a layer reached it.
+    // Rows were layer-driven while the requirement is limit-driven, so a limit
+    // recorded for a host the layer map does not list disappeared silently —
+    // the two sources agree today, which means they can only diverge in the
+    // direction the code did not cover.
+    for (const [host, e] of limits)
+        if (e.limit !== null && !byHost.has(host)) {
+            byHost.set(host, { chars: 0, owned: 0, foreign: 0 });
+        }
+    const rows = [];
+    for (const host of [...byHost.keys()].sort()) {
+        const a = byHost.get(host);
+        const e = limits.get(host) ?? { limit: null, kind: 'unpublished' };
+        const fraction = e.limit === null ? null : a.chars / e.limit;
+        rows.push({
+            host,
+            limit: e.limit,
+            kind: e.kind,
+            chars: a.chars,
+            package_owned_chars: a.owned,
+            foreign_chars: a.foreign,
+            fraction,
+            warn: fraction !== null && fraction >= LIMIT_WARN_FRACTION,
+        });
+    }
+    return rows;
+}
+/**
+ * Read every host rule directory in both scopes.
+ *
+ * BOTH SCOPES, BECAUSE THE HOST UNIONS THEM. A reading of the global layer
+ * alone would understate a consumer whose project carries its own rules, and
+ * the carrier's own scope filter reads the union for the same reason
+ * (`rule_layer_overlap.hostRuleLayerIds`).
+ */
+export function buildInstalledLayerReport(opts) {
+    const manifestPath = opts.manifestPath ?? null;
+    const recorded = manifestPath === null
+        ? NO_RECORDED_HASHES
+        : readRecordedHashes(manifestPath, opts.projectRoot);
+    const layers = [];
+    for (const host of Object.keys(GLOBAL_RULE_DIRS).sort()) {
+        const dir = globalRuleLayerPath(host, opts.home);
+        if (dir === null)
+            continue;
+        layers.push(readLayer(host, 'global', dir, recorded));
+    }
+    for (const rel of Object.keys(PROJECT_RULE_DIRS).sort()) {
+        const host = PROJECT_RULE_DIRS[rel];
+        layers.push(readLayer(host, 'project', path.join(opts.projectRoot, rel), recorded));
+    }
+    const totals = layers.reduce((acc, l) => ({
+        files: acc.files + l.files,
+        unconditional: acc.unconditional + l.unconditional,
+        chars: acc.chars + l.chars,
+        package_owned: acc.package_owned + l.package_owned,
+        foreign: acc.foreign + l.foreign,
+        package_owned_chars: acc.package_owned_chars + l.package_owned_chars,
+        foreign_chars: acc.foreign_chars + l.foreign_chars,
+    }), {
+        files: 0,
+        unconditional: 0,
+        chars: 0,
+        package_owned: 0,
+        foreign: 0,
+        package_owned_chars: 0,
+        foreign_chars: 0,
+    });
+    const limits = buildHostLimitRows(layers, loadHostInstructionLimits(opts.hostLimitsPath ?? defaultHostLimitsPath()));
+    return {
+        home: opts.home,
+        project_root: opts.projectRoot,
+        host_version: opts.hostVersion ?? 'unknown',
+        manifest_present: manifestPath !== null && fs.existsSync(manifestPath),
+        layers,
+        limits,
+        totals,
+    };
+}
+/** 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');
+    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, ` +
+            `${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(...renderHostLimitRows(report.limits));
+    return out;
+}
+/**
+ * The budget block — one row per host, against its published limit.
+ *
+ * Extracted so the REPORT and the INSTALL RECEIPT print the same bytes. They
+ * answer the same question at two moments, and a consumer comparing a receipt
+ * against a later report must not have to decide whether a wording difference
+ * means a measurement difference.
+ */
+export function renderHostLimitRows(rows) {
+    // ONE ROW PER HOST, against its published limit — steps 1.4 and 3.5. The
+    // combined figure is what the row is about: a consumer's own instruction
+    // files sit in the same budget as this package's, so a package-owned number
+    // alone would understate what the host is actually holding.
+    const out = [
+        'host instruction budgets — package-owned + foreign against the published limit',
+    ];
+    for (const r of rows) {
+        const split = `${String(r.package_owned_chars)} package-owned + ` +
+            `${String(r.foreign_chars)} foreign = ${String(r.chars)} chars`;
+        if (r.limit === null) {
+            out.push(`  ${r.host} — ${split}; no published limit recorded — not measured`);
+            continue;
+        }
+        const pct = (r.fraction * 100).toFixed(1);
+        out.push(`  ${r.host} — ${split}; ${pct}% of ${String(r.limit)} (${r.kind})` +
+            (r.warn
+                ? ` — WARNING: at or past ${String(Math.round(LIMIT_WARN_FRACTION * 100))}% of the published limit`
+                : ''));
+    }
+    return out;
+}
+//# sourceMappingURL=installed_layer.js.map

package/dist/scripts/_lib/lean_projection_mode.js

@@ -1,20 +1,64 @@
 /**
- * `lean_projection.mode` — ONE definition of what the three modes mean.
- *
- * The projector (`condense.ts`) resolves the value with a real YAML parse; the
- * delivery concern (`hooks/rule_inject_hook.ts`) resolves it with an
- * indentation-shaped read, because a hook must never fail a tool call because a
- * parser could not load. Two readers is unavoidable. Two *normalisations* is
- * not, and would be the defect worth preventing: a projector that writes thin
- * files while the concern believes the mode is off delivers pointers and no
- * bodies, which is exactly the 36.2 % arm the delivery mode exists to replace.
- *
- * So each side supplies the raw string from its own reader and this module
- * decides what it means. Anything unrecognised — absent key, typo, `null`,
- * a non-string — is `eager-all`: the parser fallback, which is NOT the value
- * the template ships (see the type below), because a mode nobody can spell
- * must never silently thin the standing corpus.
+ * `lean_projection.mode` — ONE definition of what the three modes mean, and
+ * since step 1.2 of `road-to-a-rule-carrier-that-works-outside-the-repo`, ONE
+ * reader that produces it.
+ *
+ * ── What this module used to be, and why that was not enough ──
+ *
+ * It owned the NORMALISATION and left each caller its own READER: the projector
+ * (`condense.ts`) resolved the value with a real YAML parse over the full
+ * settings cascade; the delivery concern (`hooks/rule_inject_hook.ts`) resolved
+ * it with an indentation-shaped read of `<cwd>/.agent-settings.yml` alone. The
+ * header argued that two readers were unavoidable and that two *normalisations*
+ * were the only thing worth preventing.
+ *
+ * Measured on 2026-10-02, that split was not a stylistic difference — it was a
+ * disagreement about WHICH FILE. The installer writes settings to
+ * `<root>/agents/settings/.agent-settings.yml` (`agent_settings.ts`'s canonical
+ * write target; `install.ts:4108`). The concern read `<root>/.agent-settings.yml`,
+ * the LEGACY location, and nothing else. On a normal install the concern
+ * therefore read a file that does not exist, got `''`, normalised it to
+ * `eager-all`, and closed its own gate — while the projector, reading the
+ * canonical file, had written thin stubs. That is the pointer arm the delivery
+ * mode exists to replace, reached by configuration rather than by choice, and
+ * it is a SECOND independent cause of the silence step 1.1 repaired: a consumer
+ * that fixed the package root alone would still have received nothing.
+ *
+ * The user-global layer was invisible to the concern for the same reason, which
+ * matters more than it sounds: ADR-020 installs are global-only, so for those
+ * consumers the ONLY layer carrying a mode is one the concern never opened.
+ *
+ * ── D3: one resolver, not a parity test between three ──
+ *
+ * The roadmap's D3 records the choice and the reason — a parity test keeps
+ * three readers that can drift again, and this module already existed to be the
+ * one. `resolveLeanProjection` below is that resolver. It reads the layers in
+ * the order `load_agent_settings` defines (template base, user-global,
+ * project), through `project_settings_path`, which prefers the canonical file
+ * and falls back to the legacy one, so a hand-edited root file still works.
+ *
+ * ── Why the template path is passed in rather than resolved ──
+ *
+ * `agent_settings.default_template_path()` derives the package root from
+ * `import.meta.url` three directories up. That is correct for a module at
+ * `<pkg>/src/scripts/_lib/`; inside the composed hook bundle `import.meta.url`
+ * is `<pkg>/dist/hooks/dispatch.js`, so the same arithmetic yields the PARENT
+ * of the package and the template read misses. Verified in the built bundle,
+ * not inferred. With no template the base layer is `{}` and an unconfigured
+ * consumer resolves to `eager-all` — the silence again, one layer lower. So a
+ * caller that knows the real package root (the carrier does: the dispatcher
+ * passes it) hands it over, and the resolver reads the template from there.
+ *
+ * ── What has NOT changed ──
+ *
+ * Anything unrecognised — absent key, typo, `null`, a non-string — is still
+ * `eager-all`: the parser fallback, which is NOT the value the template ships
+ * (see the type below), because a mode nobody can spell must never silently
+ * thin the standing corpus. That fallback now fires only when no layer carried
+ * a value at all, rather than whenever the concern looked in the wrong place.
  */
+import * as path from 'node:path';
+import { load_agent_settings } from './agent_settings.js';
 export const DEFAULT_LEAN_PROJECTION_MODE = 'eager-all';
 /** Map a raw settings value onto a mode. Unrecognised → `eager-all`. */
 export function normalizeLeanProjectionMode(raw) {
@@ -146,4 +190,163 @@ export function describeDroppedHosts(res) {
 export function thinsHost(mode, hosts, hostId) {
     return writesThinFiles(mode) && hosts.includes(hostId);
 }
+/**
+ * THE resolver. Every surface that asks "which delivery mode" calls this.
+ *
+ * Tolerant like everything else on a hook path: `load_agent_settings` answers
+ * with defaults on an unreadable or malformed file and never throws, and the
+ * normalisers above turn anything unrecognised into the safe value. A caller
+ * on a hot path pays ONE cascade read per prompt; `modeExplicit` is a lazy
+ * getter, so the second, template-isolated read happens only for a caller that
+ * actually reads provenance — which today is the installer and nothing else.
+ */
+export function resolveLeanProjection(opts = {}) {
+    // The LEGACY root path, deliberately, and not `project_settings_path`'s
+    // either-or pick. `load_agent_settings` expands whatever it is given into
+    // `[the file, <its dir>/agents/settings/.agent-settings.yml, <its dir>/
+    // agents/settings/.agent-settings.local.yml]` and merges them deepest-wins,
+    // so handing it the root path reads BOTH the legacy and the canonical file
+    // — which is strictly more than picking one, and is what a tree carrying
+    // both should resolve to. It also keeps one export out of this module's
+    // import list, which is runtime bytes in the composed hook bundle.
+    const file = opts.settingsPath ?? path.join(opts.projectRoot ?? process.cwd(), '.agent-settings.yml');
+    const tpl = opts.packageRoot == null
+        ? null
+        : path.join(opts.packageRoot, 'src', 'config', 'agent-settings.template.yml');
+    let lean;
+    try {
+        lean = load_agent_settings(tpl === null ? { project_path: file } : { project_path: file, template_path: tpl })['lean_projection'];
+    }
+    catch {
+        /* a settings layer nothing can read must never fail a turn */
+    }
+    const obj = typeof lean === 'object' && lean !== null && !Array.isArray(lean) ? lean : {};
+    const o = obj;
+    return {
+        mode: normalizeLeanProjectionMode(o['mode'] ?? ''),
+        hosts: resolveLeanProjectionHosts(o['hosts']),
+        // LAZY, and the hot path is the reason. Provenance needs a SECOND,
+        // template-isolated cascade, and only the installer reads it — the
+        // delivery concern on `user_prompt_submit` destructures `{ mode, hosts }`
+        // and discards this field, so computing it eagerly doubled the per-prompt
+        // settings read for an answer nobody asked for. A getter keeps the
+        // field's shape (`readonly modeExplicit: boolean`) and charges only the
+        // caller that touches it.
+        get modeExplicit() {
+            return rawExplicitLeanProjectionMode(opts) !== '';
+        },
+    };
+}
+/**
+ * A path no tree contains, so `template_defaults` contributes nothing.
+ *
+ * This is the mechanism `load_agent_settings` documents for the purpose —
+ * "a test or tool that pins every other input can pin the defaults base too,
+ * and point it at a nonexistent file to isolate the cascade" — used here for a
+ * tool rather than a test. It is a reserved device filename on every platform
+ * this package runs on and is never created, so the read fails and the loader's
+ * own tolerance turns it into `{}`.
+ *
+ * The alternative — re-reading the YAML layers by hand — was rejected because
+ * it would be a SECOND reader of the same key, which is the precise defect step
+ * 1.2 of the carrier roadmap existed to remove. Isolating the base keeps one
+ * reader and changes only which layers it is given.
+ */
+const NO_TEMPLATE_LAYER = path.join(path.sep, 'dev', 'null', 'agent-config-absent-template.yml');
+/**
+ * The RAW `lean_projection.mode` string from the user-controlled layers only,
+ * or `''` when no such layer carries it.
+ *
+ * Raw and un-normalised on purpose: {@link normalizeLeanProjectionMode} maps
+ * everything unrecognised — `''` included — onto `eager-all`, so a normalised
+ * answer cannot tell "the user chose eager-all" from "the user chose nothing".
+ * Provenance needs exactly that distinction, so it has to be read before the
+ * normaliser runs.
+ */
+export function rawExplicitLeanProjectionMode(opts = {}) {
+    const file = opts.settingsPath ?? path.join(opts.projectRoot ?? process.cwd(), '.agent-settings.yml');
+    let lean;
+    try {
+        lean = load_agent_settings({ project_path: file, template_path: NO_TEMPLATE_LAYER })['lean_projection'];
+    }
+    catch {
+        return ''; // a layer nothing can read states no preference
+    }
+    if (typeof lean !== 'object' || lean === null || Array.isArray(lean))
+        return '';
+    const m = lean['mode'];
+    return typeof m === 'string' ? m.trim() : '';
+}
+/**
+ * Did a human ask for this mode, and is it the one the caller is gated on?
+ *
+ * The question an installer actually has. `modeExplicit` alone is not enough —
+ * a consumer who explicitly set `eager-all` has set the key explicitly and must
+ * NOT be thinned — so the two conditions are folded here rather than left to
+ * every caller to remember to combine.
+ */
+export function leanProjectionModeChosen(mode, opts = {}) {
+    const raw = rawExplicitLeanProjectionMode(opts);
+    return raw !== '' && normalizeLeanProjectionMode(raw) === mode;
+}
+/**
+ * May the INSTALLER thin this host's rule tree?
+ *
+ * The host-aware sibling of {@link leanProjectionModeChosen}, and the predicate
+ * `road-to-an-installed-layer-that-is-thinned` step 1.1 keys on. It folds the
+ * three conditions that must hold together, once, so no caller has to remember
+ * to combine them:
+ *
+ * 1. **A human asked.** `modeExplicit` — false whenever the only layer carrying
+ *    the key is the shipped template, which already says `delivery`. Reading the
+ *    template as consent would thin every consumer's `~/.claude/rules` as a side
+ *    effect of wiring a reader, which is the owner-reserved default flip (that
+ *    roadmap's blocker, decision D4).
+ * 2. **The chosen mode actually writes stubs.** A consumer who explicitly chose
+ *    `eager-all` has set the key and must NOT be thinned on the strength of
+ *    having an opinion.
+ * 3. **This host is in scope.** The same `hosts:` list the projector honours, so
+ *    installer and projector cannot disagree about which trees are thinned.
+ *
+ * ONE `resolveLeanProjection` call, which is why this is not two
+ * {@link leanProjectionModeChosen} calls: that one answers "is the chosen mode
+ * exactly X" and knows nothing about `hosts`, so a caller combining it with a
+ * host check by hand would re-create the fold this function exists to own.
+ *
+ * That is one CALL and two cascade READS here, because reading `modeExplicit`
+ * triggers its lazy getter and a second, template-isolated load. The installer
+ * runs once per deploy and does not care; the cost is named rather than rounded
+ * down because the same resolver serves the per-prompt delivery concern, which
+ * does NOT read provenance and therefore does not pay it.
+ */
+export function installerThinsHost(hostId, opts = {}) {
+    const { mode, hosts, modeExplicit } = resolveLeanProjection({
+        ...opts,
+        settingsPath: opts.settingsPath ?? NO_PROJECT_LAYER,
+    });
+    return modeExplicit && thinsHost(mode, hosts.hosts, hostId);
+}
+/**
+ * A path no tree contains, so the PROJECT cascade contributes nothing.
+ *
+ * The same device {@link NO_TEMPLATE_LAYER} uses, pointed at the other end of
+ * the cascade, and the reason is scope rather than isolation: the thing
+ * {@link installerThinsHost} gates is a mutation of `~/.claude/rules`, which
+ * belongs to the MACHINE. A per-checkout value must not decide it, in either
+ * direction — a project saying `delivery` would thin the layer every other
+ * project on that machine reads, and a project saying `eager-all` would
+ * suppress an opt-in the user wrote user-globally, because the project cascade
+ * merges last and wins.
+ *
+ * `load_agent_settings` reads `user_global_settings_paths()` regardless of what
+ * `project_path` it is given, so pointing the project layer at nothing leaves
+ * exactly the machine-global layers — which is the scope the installer's
+ * sibling `_resolve_global_rule_scope` already resolves for the same deploy.
+ * A caller may still pass an explicit `settingsPath` (tests pin one). A
+ * `projectRoot` handed to {@link installerThinsHost} is DISCARDED — the `??`
+ * chain terminates at `settingsPath` before `projectRoot` is consulted — which
+ * is the intended behaviour and is stated here because a caller passing it and
+ * expecting it honoured would otherwise get no signal.
+ */
+const NO_PROJECT_LAYER = path.join(path.sep, 'dev', 'null', 'agent-config-absent-project-settings.yml');
 //# sourceMappingURL=lean_projection_mode.js.map