@event4u/agent-config 16.4.0 → 17.0.0

package/dist/scripts/_lib/lean_projection_mode.js

@@ -57,8 +57,7 @@
  * 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';
+import { shippedProjection } from './project_tree_form.js';
 export const DEFAULT_LEAN_PROJECTION_MODE = 'eager-all';
 /** Map a raw settings value onto a mode. Unrecognised → `eager-all`. */
 export function normalizeLeanProjectionMode(raw) {
@@ -191,162 +190,45 @@ 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.
+ * The form the PROJECT tree is built with, and the hosts it applies to.
+ *
+ * NO SETTINGS READ SINCE ADR-293. The key this resolved is removed from every
+ * shipped surface, and a hand-written leftover is not read either — which is
+ * what makes its tombstone line ("ignored") true for this reader as well as for
+ * the docs. The form comes from the package-owned record in
+ * `project_tree_form.ts`, which carries what the template carried plus the
+ * evidence ADR-267 measured for it, and which an observed layer-form verdict
+ * supersedes. `opts` is kept so no caller changes; only `packageRoot` is read,
+ * because that is where the record lives.
  */
 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;
+    const shipped = opts.packageRoot == null ? null : shippedProjection(opts.packageRoot);
     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) !== '';
-        },
+        mode: shipped?.mode ?? DEFAULT_LEAN_PROJECTION_MODE,
+        hosts: resolveLeanProjectionHosts(shipped === null || shipped.hosts.length === 0 ? undefined : shipped.hosts),
+        // A package-owned record is never a consumer's choice, exactly as the
+        // shipped template never was. Constant since there is no layer left
+        // that could carry one.
+        modeExplicit: false,
     };
 }
 /**
- * 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.
+ * May the INSTALLER thin this host's rule tree? Never, since ADR-293.
+ *
+ * It used to fold three conditions — a human asked, the chosen mode writes
+ * stubs, this host is in scope — over a settings key. The key is gone, so the
+ * first condition can no longer be met by anything, and the honest shape is a
+ * constant rather than a cascade read that can only return one answer.
+ *
+ * THIS IS NOT "thinning is impossible". A fresh install writes the full layer
+ * exactly as today, which is what step 3.3 of
+ * `road-to-a-setup-that-decides-itself` specifies; promotion happens later, in
+ * a session whose arrival record satisfies the decision function, and never at
+ * install time. The function is kept rather than deleted so that the one place
+ * that answer is decided stays named, and so `rule_inject_hook`'s
+ * served-once check keeps reading it when 3.3 gives it a real answer again.
  */
-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() : '';
+export function installerThinsHost(_hostId, _opts = {}) {
+    return false;
 }
-/**
- * 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

package/dist/scripts/_lib/project_tree_form.js

@@ -0,0 +1,118 @@
+/**
+ * Where the PROJECT tree's rule-layer form comes from, now that no settings key
+ * carries it.
+ *
+ * WHY THIS EXISTS. ADR-293 removed `lean_projection.*`, and the shipped
+ * settings template was the last layer of the cascade `resolveLeanProjection`
+ * read — so the project tree on the first host got its `delivery` from a key
+ * that no longer exists. Removing the key with nothing in its place would have
+ * flipped that tree to the full form: a default change for a tree whose form
+ * ADR-267 decided ON EVIDENCE (616/616 byte-equal deliveries, 101/101 labelled
+ * rules reachable, 0 of 212 near-misses fired on the frozen routing-matrix
+ * corpus), with nothing measured against it. That is not a "no worse" move, and
+ * it would also leave Phase 5 with no live arm to compare.
+ *
+ * WHY IT IS NOT THE KEY UNDER ANOTHER NAME. `src/config/project-tree-form.json`
+ * is package-owned and ships in the repository: there is no consumer-writable
+ * layer, no cascade, and no merge. `modeExplicit` stays false for it, exactly as
+ * it did for the template, so nothing here is read as a consumer's consent. And
+ * it carries its own replacement condition rather than a value alone — a row
+ * without the measurement that justifies it is REFUSED, so the file cannot
+ * become a place to write a form someone merely wants.
+ *
+ * PRECEDENCE, WHICH IS THE WHOLE SAFETY ARGUMENT. A valid OBSERVED verdict from
+ * the layer-form decision function supersedes this record for that host, in both
+ * directions — an observed `full` wins over a record saying `delivery`. The
+ * record stands only while that function can answer nothing but
+ * `delivery-unobserved`, which is its state today for every host. Without that
+ * rule this file would be a permanent bypass of the decision function rather
+ * than a stand-in for it, which is the one risk the reviewing seat named.
+ *
+ * WHY ONE SEAT WAS ENOUGH TO BUILD ON, AND NOT ENOUGH TO CLOSE. The choice was
+ * reviewed at a degraded quorum, so step 3.6 stays open and its blocker carries
+ * the confirmation. Acting on it meanwhile is bounded by what the option does:
+ * it changes no behaviour at all — it reproduces what the shipped template
+ * produced — and every alternative did. The record lives with the roadmap.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { DEFAULT_LEAN_PROJECTION_MODE } from './lean_projection_mode.js';
+export const PROJECT_TREE_FORM_REL = path.join('src', 'config', 'project-tree-form.json');
+const FORMS = ['eager-all', 'thin', 'delivery'];
+/**
+ * The reason that means "the function could not look", as opposed to a verdict
+ * it actually reached. Only this one yields to the shipped record.
+ */
+export const UNOBSERVED_REASON = 'delivery-unobserved';
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Every host row the record carries. A row without a `measured` block, or with
+ * a form the projector does not have, is dropped: this file records measured
+ * forms, and a row that records neither is not evidence.
+ */
+export function readProjectTreeForms(packageRoot) {
+    const out = new Map();
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(packageRoot, PROJECT_TREE_FORM_REL), 'utf8'));
+    }
+    catch {
+        return out; // absent or unreadable: every host gets the full form
+    }
+    if (!isRecord(raw) || !isRecord(raw['hosts']))
+        return out;
+    for (const [host, row] of Object.entries(raw['hosts'])) {
+        if (!isRecord(row))
+            continue;
+        const form = row['form'];
+        if (typeof form !== 'string' || !FORMS.includes(form))
+            continue;
+        // At least one measured figure, each a non-empty string: `{}` records no measurement.
+        const measured = row['measured'];
+        if (!isRecord(measured))
+            continue;
+        const figures = Object.values(measured);
+        if (figures.length === 0 || !figures.every((v) => typeof v === 'string' && v.trim() !== ''))
+            continue;
+        out.set(host, { form: form, basis: typeof row['basis'] === 'string' ? row['basis'] : 'unrecorded' });
+    }
+    return out;
+}
+/**
+ * The form the project tree is built with for `host`.
+ *
+ * `verdict` is the layer-form decision for this host where one exists. An
+ * observed verdict — anything whose reason is not {@link UNOBSERVED_REASON} —
+ * decides, and the record is not consulted. A host with no row and no observed
+ * verdict gets the full form, which is what an absent key always meant.
+ */
+export function projectTreeForm(packageRoot, host, verdict) {
+    if (verdict !== null && verdict.reason !== UNOBSERVED_REASON) {
+        return verdict.form === 'full' ? DEFAULT_LEAN_PROJECTION_MODE : (readProjectTreeForms(packageRoot).get(host)?.form ?? DEFAULT_LEAN_PROJECTION_MODE);
+    }
+    return readProjectTreeForms(packageRoot).get(host)?.form ?? DEFAULT_LEAN_PROJECTION_MODE;
+}
+/**
+ * The `{ mode, hosts }` pair the projector asks for, derived from the record.
+ *
+ * The record is per host, the projector's API is one mode plus the host list it
+ * applies to, and this is the one place the two shapes meet. `mode` is the
+ * strongest form any row carries — `delivery` over `thin` over `eager-all` —
+ * and `hosts` is every row carrying exactly that form. A tree with no record,
+ * or with rows the reader refused, gets the full form and no hosts, which is
+ * what an absent key always meant.
+ */
+export function shippedProjection(packageRoot) {
+    const forms = readProjectTreeForms(packageRoot);
+    const rank = { 'eager-all': 0, thin: 1, delivery: 2 };
+    let mode = DEFAULT_LEAN_PROJECTION_MODE;
+    for (const row of forms.values()) {
+        if ((rank[row.form] ?? 0) > (rank[mode] ?? 0))
+            mode = row.form;
+    }
+    const hosts = [...forms.entries()].filter(([, row]) => row.form === mode).map(([host]) => host).sort();
+    return { mode, hosts: mode === DEFAULT_LEAN_PROJECTION_MODE ? [] : hosts };
+}
+//# sourceMappingURL=project_tree_form.js.map

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

package/dist/scripts/_lib/scoped_projection.js

@@ -36,6 +36,46 @@ export const SCOPED_ACTIVE_WORKSPACES = new Set([
     'engineering',
     'agent-config-maintainer',
 ]);
+/**
+ * The workspace this package's OWN rules carry — the one workspace a consumer
+ * install never receives. ADR-293 step 4.6: the consumer workspace list is
+ * DERIVED from the pack vocabulary rather than written into settings, and this
+ * is the single id that derivation subtracts.
+ */
+export const MAINTAINER_WORKSPACE = 'agent-config-maintainer';
+/**
+ * Every workspace a CONSUMER install scopes rules to: the ids `packs.yml`
+ * declares, minus {@link MAINTAINER_WORKSPACE}.
+ *
+ * WHY DERIVED AND NOT CONFIGURED. `projection.rule_workspaces` carried this
+ * list as a settings default — nine ids, re-typed into the template, and
+ * needing a re-type whenever a pack arrived with a new workspace. What the key
+ * actually encoded is a RULE, and the rule is "maintainer-only rules never
+ * project to a consumer". Deriving it from the frontmatter that already decides
+ * the question makes a new workspace reach consumers the day its pack lands,
+ * instead of the day somebody remembers to edit a template.
+ *
+ * Empty when the vocabulary cannot be read, which is the inactive axis — every
+ * rule projects, exactly as an unset key meant. The failure direction is
+ * deliberate: a package that cannot read its own pack list must ship MORE than
+ * it should, never less.
+ */
+export function consumerRuleWorkspaces(packageRoot) {
+    const ids = new Set();
+    let records;
+    try {
+        records = load_packs_registry(packageRoot);
+    }
+    catch {
+        return []; // unreadable vocabulary: the inactive axis, which ships more
+    }
+    for (const rec of records) {
+        for (const ws of rec.workspaces)
+            if (ws !== MAINTAINER_WORKSPACE)
+                ids.add(ws);
+    }
+    return [...ids].sort();
+}
 function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -134,8 +174,15 @@ export function compute_active_pack_ids(packs, runtime_active_packs) {
  * `scoped`. Untagged artefacts (empty `packs:` frontmatter) are core/shared
  * and always kept; a tagged artefact survives iff its tags intersect the
  * active set.
+ *
+ * `kept` is the declared-dependency closure (`declared_skill_closure`): a
+ * skill a surviving artefact declares is never pruned, whatever its tags
+ * (ADR-289 § Decision 2 — a pruned declared dependency is a broken install).
  */
-export function is_pruned_under_scoped(md_path, active_ids) {
+export function is_pruned_under_scoped(md_path, active_ids, kept = new Set()) {
+    if (path.basename(md_path) === 'SKILL.md' && kept.has(path.basename(path.dirname(md_path)))) {
+        return false;
+    }
     const packs = surface_tiers.frontmatter_packs(md_path);
     if (packs.size === 0)
         return false;
@@ -145,6 +192,76 @@ export function is_pruned_under_scoped(md_path, active_ids) {
     }
     return true;
 }
+/** Names in an artefact's `skills:` and `requires_skills:` frontmatter lists. */
+export function declared_skills(md_path) {
+    let text;
+    try {
+        text = fs.readFileSync(md_path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    if (!text.startsWith('---'))
+        return [];
+    const end = text.indexOf('\n---', 3);
+    const fm = yamlSafeLoad(end !== -1 ? text.slice(3, end) : text.slice(3));
+    if (!isPlainObject(fm))
+        return [];
+    const out = [];
+    for (const key of ['skills', 'requires_skills']) {
+        const v = fm[key];
+        if (Array.isArray(v))
+            out.push(...v.filter((s) => typeof s === 'string'));
+    }
+    return out;
+}
+/**
+ * Every skill name a surviving artefact declares, transitively: a declared
+ * skill the pack prune would drop survives, and its own declarations count.
+ * `artefacts` is the SKILL.md and command `.md` population being pruned.
+ */
+export function declared_skill_closure(artefacts, active_ids) {
+    const all = [...artefacts];
+    const skill_md = new Map();
+    for (const p of all) {
+        if (path.basename(p) === 'SKILL.md')
+            skill_md.set(path.basename(path.dirname(p)), p);
+    }
+    const kept = new Set();
+    let frontier = all.filter((p) => !is_pruned_under_scoped(p, active_ids));
+    while (frontier.length > 0) {
+        const next = [];
+        for (const p of frontier) {
+            for (const name of declared_skills(p)) {
+                if (kept.has(name))
+                    continue;
+                kept.add(name);
+                const target = skill_md.get(name);
+                if (target !== undefined && is_pruned_under_scoped(target, active_ids))
+                    next.push(target);
+            }
+        }
+        frontier = next;
+    }
+    return kept;
+}
+/** Every command `.md` the package projects — the declarers beside the skills. */
+export function projected_command_files(package_root) {
+    const out = [];
+    const walk = (dir) => {
+        if (!fs.existsSync(dir))
+            return;
+        for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                walk(full);
+            else if (e.name.endsWith('.md') && e.name !== 'AGENTS.md')
+                out.push(full);
+        }
+    };
+    walk(path.join(package_root, 'dist', 'agent-src', 'commands'));
+    return out;
+}
 /**
  * Sentinel value for `projection.rule_packs`: derive the pack scope from the
  * active-pack set instead of listing ids by hand.
@@ -204,11 +321,13 @@ export function resolve_rule_pack_scope(raw, package_root, runtime_active_packs
  */
 export function scoped_projection_stats(package_root, skills, runtime_active_packs = []) {
     const active = compute_active_pack_ids(load_packs_registry(package_root), runtime_active_packs);
+    const skill_list = [...skills];
+    const kept = declared_skill_closure([...skill_list, ...projected_command_files(package_root)], active);
     let projected = 0;
     let total = 0;
-    for (const skill of skills) {
+    for (const skill of skill_list) {
         total += 1;
-        if (!is_pruned_under_scoped(skill, active)) {
+        if (!is_pruned_under_scoped(skill, active, kept)) {
             projected += 1;
         }
     }
@@ -295,6 +414,17 @@ export function prune_modules_by(deploy_results, is_pruned) {
     }
     return [pruned, adjusted];
 }
+/**
+ * The scoped prune over a completed deploy: pack-pruned skills/commands go,
+ * except the skills a surviving deployed artefact declares.
+ */
+export function prune_scoped_modules(deploy_results, active_ids) {
+    const artefacts = Object.values(deploy_results)
+        .flatMap(([, , , paths]) => paths)
+        .filter((p) => path.basename(p) === 'SKILL.md' || (p.split(path.sep).includes('commands') && path.extname(p) === '.md'));
+    const kept = declared_skill_closure(artefacts, active_ids);
+    return prune_modules_by(deploy_results, (p) => is_pruned_under_scoped(p, active_ids, kept));
+}
 /**
  * Remove lab-tier skills/commands from a completed deploy (core-only).
  *

package/dist/scripts/_lib/settings_removed_keys.js

@@ -60,6 +60,22 @@
  * default; what a consumer who had set a non-default value loses is named by
  * the reason.
  *
+ * The 2026-10-20 batch (ADR-293) is a fifth doctrine: keys that WERE read and
+ * whose decision is now COMPUTED rather than configured. They are not
+ * default-neutral — `lean_projection.mode: delivery` written user-globally
+ * thinned a real machine — which is why they ship in a major and why
+ * `_lib/projection_key_migration.ts` reads the two values that meant "keep the
+ * full layer" one more time and converts them into the install receipt's pin.
+ * Every other prior value is dropped with a line. When that window closes the
+ * migration module goes and these entries are what remains.
+ *
+ * Release class: A settings key may be removed or renamed in a minor release
+ * only when no consumer project can rely on it — default-neutral and
+ * derivable, proven by a named test; any other removal or rename ships only in
+ * a major, and a renamed key's alias is dropped only in a major. An entry here
+ * is what tells a consumer the key went; it is not the licence for a minor —
+ * {@link MINOR_REMOVAL_PROOFS} is, and the cut reads it.
+ *
  * Every reason string must name what decides INSTEAD, never just "removed".
  * Exported so `lint_settings_classes` can check the deletion side of the
  * surface: a reason that names no replacement, or an entry whose key is live in
@@ -134,7 +150,20 @@ export const REMOVED_KEYS = new Map([
     ['consistency.cross_source', 'the cross-source-consistency rule, always on; batching and the no-cheap-questions floor bound the noise'],
     ['subagents.downshift', 'the model_tier each sub-task declares; downshift is always on'],
     ['ai_team.suppress_setup_hint', 'nothing: the one-line team-mode setup hint is always shown'],
+    // 2026-10-20 — the projection keys (ADR-293, road-to-a-setup-that-decides-itself Phase 4)
+    ['lean_projection.mode', 'the computed layer-form decision (_lib/layer_form_decision.ts), plus `install --full` and src/config/layer-form-brakes.json as the two brakes. For one release window an installer converts a leftover `eager-all` into the install receipt pin and drops any other value, saying which (_lib/projection_key_migration.ts); the project tree reads the package-owned src/config/project-tree-form.json, never this key'],
+    ['lean_projection.hosts', 'THINNABLE_HOSTS in _lib/lean_projection_mode.ts and the per-host row in src/config/host-injection-effect.json; no reader of this key remains'],
+    ['projection.rule_workspaces', 'consumerRuleWorkspaces() in _lib/scoped_projection.ts, which derives the consumer workspace set from src/config/discovery/packs.yml — every id minus `agent-config-maintainer` — so a new pack reaches consumers without a settings edit'],
 ]);
+/**
+ * Keys removed or renamed below a major, each mapped to the named test that
+ * proves no consumer project can rely on it, as `<test file>::<it title>`.
+ * The release cut (`release_settings_surface.ts`) refuses a non-major target
+ * whose carried removal has no entry here, or whose entry names a test the
+ * tree does not contain. Empty until a minor needs it: the keys removed before
+ * this map existed shipped under the rule as it was then written.
+ */
+export const MINOR_REMOVAL_PROOFS = new Map();
 /** Keys already warned about in THIS process — the "once per run" dedupe. */
 const _warnedRemovedKeys = new Set();
 /** Read one dotted path out of a merged settings tree; `undefined` when absent. */