@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/lean_projection_mode.ts

@@ -57,9 +57,8 @@
  * 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';
 
 /**
  * The three projection shapes, and the two different defaults they answer to.
@@ -76,6 +75,7 @@ export type LeanProjectionMode = 'eager-all' | 'thin' | 'delivery';
 
 export const DEFAULT_LEAN_PROJECTION_MODE: LeanProjectionMode = 'eager-all';
 
+
 /** Map a raw settings value onto a mode. Unrecognised → `eager-all`. */
 export function normalizeLeanProjectionMode(raw: unknown): LeanProjectionMode {
     const v = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
@@ -265,178 +265,49 @@ export interface ResolveOptions {
 }
 
 /**
- * THE resolver. Every surface that asks "which delivery mode" calls this.
+ * The form the PROJECT tree is built with, and the hosts it applies to.
  *
- * 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.
+ * 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: ResolveOptions = {}): ResolvedLeanProjection {
-    // 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: unknown;
-    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 as Record<string, unknown>;
+    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(): boolean {
-            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.
- */
-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: ResolveOptions = {}): string {
-    const file =
-        opts.settingsPath ?? path.join(opts.projectRoot ?? process.cwd(), '.agent-settings.yml');
-    let lean: unknown;
-    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 as Record<string, unknown>)['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: LeanProjectionMode,
-    opts: ResolveOptions = {},
-): boolean {
-    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:
+ * May the INSTALLER thin this host's rule tree? Never, since ADR-293.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
  */
-export function installerThinsHost(hostId: string, opts: ResolveOptions = {}): boolean {
-    const { mode, hosts, modeExplicit } = resolveLeanProjection({
-        ...opts,
-        settingsPath: opts.settingsPath ?? NO_PROJECT_LAYER,
-    });
-    return modeExplicit && thinsHost(mode, hosts.hosts, hostId);
+export function installerThinsHost(_hostId: string, _opts: ResolveOptions = {}): boolean {
+    return false;
 }
 
-/**
- * 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',
-);

package/src/scripts/_lib/llm_proposer_transport.ts

@@ -1,3 +1,4 @@
+// egress-content: session-content uncovered — the prompt is assembled from repository evidence at run time and is not passed through the engine; the module has made no live call
 /**
  * The metered transport for the LLM proposer arm — one provider, one call shape.
  *

package/src/scripts/_lib/loop_guards.ts

@@ -1,14 +1,12 @@
 /**
  * Guards for a harness-enforced bounded loop.
  *
- * `road-to-skill-ecosystem-runtime-enforcement` Phase 5, Steps 2-4. Three
- * primitives the stop-event loop needs and did not have, each closing a failure
- * that is invisible while it happens.
- *
- * Extracted rather than added to `run_continuation_hook.ts`: that file is 1,504
- * lines and `check_source_size_budget` charges every line above 1,500, so the
- * same code there would cost a budget it does not cost here. The seam also makes
- * all three testable without a host payload.
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 5, Steps 2-4, written for
+ * the stop-event loop of `run_continuation_hook.ts`. That concern was withdrawn
+ * on its pre-registered kill date, and on 2026-10-14 the owner decided to remove
+ * its termination ladder and the guards only it called — the whole-line marker
+ * match and the unavailable-dependency scan. What remains here has callers or a
+ * dated exemption of its own in `src/config/loop-surfaces.yaml`.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -29,7 +27,7 @@ import * as path from 'node:path';
  * Never throws — a budget writer that throws turns an observability concern into
  * a turn-end failure. Returns whether the write landed, and that return is
  * load-bearing: a loop that could not persist its counter must not BLOCK,
- * because there the ladder cannot bound it.
+ * because there nothing can bound it.
  */
 export function atomicWriteJson(file: string, value: unknown): boolean {
     const tmp = `${file}.${String(process.pid)}.tmp`;
@@ -48,92 +46,6 @@ export function atomicWriteJson(file: string, value: unknown): boolean {
     }
 }
 
-/**
- * Whole-LINE match against a marker — never a substring.
- *
- * The hazard is specific and cheap to hit: a transcript contains everything the
- * agent said, INCLUDING quoted examples of the marker. A substring match lets a
- * sentence like *"exit when you print RUN-COMPLETE"* terminate the run, and — the
- * worse direction — lets a quoted marker inside a code fence extend one.
- *
- * Trailing whitespace is trimmed because a terminal or a JSON round-trip adds it;
- * leading whitespace is trimmed for the same reason. Nothing ELSE on the line is
- * tolerated: `RUN-COMPLETE (probably)` is not the marker.
- */
-export function matchesWholeLine(text: string, marker: string): boolean {
-    if (marker === '') return false;
-    for (const line of text.split('\n')) {
-        if (line.trim() === marker) return true;
-    }
-    return false;
-}
-
-/** A dependency the loop cannot obtain, and therefore cannot iterate toward. */
-export interface UnavailableDependency {
-    kind: 'credential' | 'binary' | 'permission' | 'quota' | 'service';
-    evidence: string;
-}
-
-/**
- * Patterns that name a dependency the loop CANNOT close by trying again.
- *
- * Every entry corresponds to a hard-blocker class the rules already name
- * (`context-hygiene` § hard-blocker classes). The list is deliberately short and
- * literal: a general "looks like an error" heuristic would end runs on ordinary
- * test failures, which is the opposite of the intent — those are exactly what a
- * loop SHOULD iterate on.
- */
-const DEPENDENCY_PATTERNS: readonly { kind: UnavailableDependency['kind']; re: RegExp }[] = [
-    { kind: 'binary', re: /\b(?:command not found|is not recognized as an internal or external command)\b/i },
-    { kind: 'credential', re: /\b(?:not (?:authenticated|logged in)|authentication (?:failed|required)|no credentials found)\b/i },
-    { kind: 'credential', re: /\b(?:missing|unset|not set)\b[^\n]{0,40}\b(?:credential|token|api[_ -]?key|secret)\b/i },
-    { kind: 'permission', re: /\b(?:permission denied|forbidden|403 forbidden)\b/i },
-    { kind: 'quota', re: /\b(?:rate limit(?:ed| exceeded| reached)?|quota exceeded|429 too many requests|spend (?:cap|limit) reached)\b/i },
-    { kind: 'service', re: /\b(?:5\d\d (?:internal )?server error|service unavailable|connection refused)\b/i },
-];
-
-/**
- * How much of the transcript tail a caller should read before scanning it.
- *
- * The detector takes text, not a file, so the BYTE bound belongs to the read
- * and the LINE bound (`tailLines`) belongs to the scan. Both exist and they
- * bound different things: 64 KiB keeps an arbitrarily long transcript from
- * being loaded whole, and the line count then keeps a stale failure from
- * halting a run that already recovered.
- *
- * Exported rather than inlined at the one call site so the bound is visible
- * beside the detector it feeds. A caller that reads the whole file and then
- * passes it here is not wrong, only wasteful — the line bound still applies.
- */
-export const DEPENDENCY_SCAN_BYTES = 64 * 1024;
-
-/**
- * Find a dependency the run cannot obtain, from recent transcript text.
- *
- * Returns the FIRST match with the line that produced it, so a halt event can
- * name what is missing instead of saying "blocked". A halt with no named
- * dependency is a report the reader has to reconstruct.
- *
- * Scans the LAST `tailLines` lines only: an authentication failure from an hour
- * ago that was then fixed must not halt the run now, and a transcript is
- * append-only so recency is the whole signal.
- */
-export function detectUnavailableDependency(
-    transcriptTail: string,
-    tailLines = 200,
-): UnavailableDependency | null {
-    const lines = transcriptTail.split('\n');
-    const window = lines.slice(Math.max(0, lines.length - tailLines));
-    for (const line of window) {
-        for (const { kind, re } of DEPENDENCY_PATTERNS) {
-            if (re.test(line)) {
-                return { kind, evidence: line.trim().slice(0, 200) };
-            }
-        }
-    }
-    return null;
-}
-
 /**
  * The machine-readable stall signal, derived from a run's open-step history.
  *
@@ -155,7 +67,7 @@ export function detectUnavailableDependency(
  *     what separates `stagnated` from `exhausted` in the terminal-state
  *     vocabulary.
  *
- * Pure over the history array, so a reader and the ladder cannot disagree.
+ * Pure over the history array, so two readers cannot disagree.
  */
 export type StallLevel = 'progressing' | 'flat' | 'stalled';
 
@@ -192,30 +104,6 @@ export function stallSignal(history: readonly number[], window = 3): StallSignal
     return { level: 'flat', flatRun, minimum, newMinimum };
 }
 
-/**
- * Read the transcript tail and name a dependency the run cannot obtain.
- *
- * Lives here rather than at the call site, beside the detector and the byte
- * bound it uses. EXPORTED so the wiring is testable,
- * which is the half that was actually broken: the inline version referenced a
- * constant that did not exist, and because the read sits inside a `catch`
- * that fail-opens to `null`, the ReferenceError was swallowed on every fire.
- * The rung was dead and every pure `ladder()` test stayed green — a test over
- * the decision function cannot see a caller that never computes the input.
- *
- * Fail-open is deliberate and unchanged: a detector that cannot read must not
- * manufacture a halt. What changed is that "cannot read" is now the only way
- * to reach `null` by accident.
- */
-export function readUnavailableDependency(transcriptPath: string): UnavailableDependency | null {
-    try {
-        const raw = fs.readFileSync(transcriptPath, 'utf8');
-        return detectUnavailableDependency(raw.slice(-DEPENDENCY_SCAN_BYTES));
-    } catch {
-        return null;
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Rejected-tactic repetition
 // ---------------------------------------------------------------------------

package/src/scripts/_lib/major_surface.ts

@@ -0,0 +1,207 @@
+/**
+ * Which of the surfaces `CONTRIBUTING.md` § Versioning policy lists as major a
+ * release span touched, read mechanically from that span's diff.
+ *
+ * `impact_bump` takes `touches_major_surface` and nothing in the tree supplied
+ * it: step 2.2 scored the impact half alone and recorded the surface half as
+ * unscored, because "the record has no surface column, and inferring one would
+ * re-judge history". A diff is not the record — it is the change itself — so
+ * this module reads the axis from the change rather than from prose about it.
+ *
+ * Nothing in `release.ts` calls this, for the same reason nothing calls
+ * `impact_bump`: how releases are numbered is the owner decision the
+ * `impact-numbering-model` blocker holds open. This is measurement apparatus.
+ */
+
+/** The three triggers at `CONTRIBUTING.md:331` that a diff can decide. */
+export const MAJOR_SURFACES = ['installer-layout', 'settings-keys', 'rule-or-skill-removal'] as const;
+export type MajorSurface = (typeof MAJOR_SURFACES)[number];
+
+/**
+ * The fourth trigger, "breaking changes to the condensed content format", is
+ * deliberately absent and is reported as a gap rather than scored as a
+ * non-firing surface. A format break is a property of the emitted content; no
+ * reading of statuses and paths decides it, and the obvious proxy — the
+ * condenser's own filename — fires on every wording fix to that script. A
+ * surface that cannot be decided is not the same as a surface that did not
+ * fire, and scoring it as the latter would overstate the rule's coverage.
+ */
+export const UNDERIVABLE_SURFACES = ['condensed-format'] as const;
+
+/** One `git diff --name-status` record. `status` is the raw letter: A, D, M, R, T, C. */
+export interface DiffEntry {
+    readonly status: string;
+    readonly path: string;
+}
+
+/**
+ * Paths whose creation or removal is an installer-layout change. The list is
+ * historical on purpose: the installer has lived at three roots over the
+ * window this is measured on, and a table naming only today's would score
+ * every release before the last relocation as having touched nothing. The
+ * entry-point row carries an optional `src/` prefix for the same reason — the
+ * entry point moved from a Python script at the repository root to
+ * `src/scripts/install.ts` (ADR-200), and the first version of this table
+ * pinned only the old root. The retired path is described rather than quoted:
+ * `lint_pre_migration_refs` reds on a backtick-quoted citation of it, and it
+ * is right to — a shipped file naming it looks like an instruction to run it.
+ *
+ * `dist/install/` is deliberately absent. It is build output of
+ * `src/scripts/install.*`, which is already covered, so including it would add
+ * no signal and would fire the surface on a regenerated artifact.
+ */
+const INSTALLER_LAYOUT_PATHS: readonly RegExp[] = [
+    /^src\/install\//,
+    /^packages\/core\/installer\//,
+    /^(src\/)?templates\//,
+    /^bin\//,
+    /^(src\/)?scripts\/install\.(py|sh|ts|mjs)$/,
+];
+
+/** Paths whose deletion removes a rule or a skill, in source or in either projection. */
+const RULE_OR_SKILL_PATHS: readonly RegExp[] = [
+    /^src\/(rules|skills)\//,
+    /^\.agent-src\/(rules|skills)\//,
+    /^dist\/agent-src\/(rules|skills)\//,
+];
+
+/**
+ * Files whose removed `key:` lines are settings keys.
+ *
+ * Every row tolerates a leading directory because this table was wrong in its
+ * first form and the measurement reported the resulting blindness as a
+ * finding: the template was renamed `config/agent-settings.template.yml` ->
+ * `src/config/agent-settings.template.yml` in the 6.0.0 span, and a row
+ * anchored at `^config/` matched nothing from 6.0.0 onward — the whole window
+ * the rule is scored on. An anchor that silently stops matching is the shape
+ * this list now refuses.
+ */
+export const SETTINGS_KEY_FILES: readonly RegExp[] = [
+    /(^|\/)config\/agent-settings\.template\.yml$/,
+    /(^|\/)\.agent-settings\.yml/,
+    /(^|\/)schemas\/.*settings/,
+    /(^|\/)install\/.*settings/,
+];
+
+/**
+ * The diff's paths that are settings-key files, for the caller's `git diff -- <paths>`.
+ *
+ * KNOWN OVER-MATCH, recorded 2026-10-21 rather than silently narrowed. The last
+ * two rows above match on a directory plus the word `settings` and take no
+ * extension, so they also select non-YAML files whose contents
+ * `removed_setting_keys` then reads with a YAML key regex: in the scored window
+ * that is `src/server/schemas/settings.ts` (seven spans) and
+ * `tests/install/settings_surface_snapshot.test.ts` (one). A deleted property in
+ * either would be counted as a dropped settings key.
+ *
+ * Measured impact in that window: NONE. All 14 spans were re-run with the paths
+ * filtered to `.yml`/`.yaml`; every span's fire/no-fire outcome and every
+ * removed-key set is byte-identical either way, so no row of the out-of-sample
+ * measurement depends on the over-match.
+ *
+ * Not narrowed here on purpose. The obvious guard — require a YAML extension —
+ * is a change to this exported function's contract, and a committed test
+ * deliberately asserts that a `…schemas/agent-settings.schema.json` path IS
+ * selected. Rewriting that contract on a latent finding, in the change that
+ * merely measured it, is wider than the finding warrants. Whoever wires the
+ * surface clause under blocker option (a) should apply the guard and move that
+ * test with it.
+ */
+export function settings_key_paths(entries: readonly DiffEntry[]): string[] {
+    const seen = new Set<string>();
+    for (const entry of entries) {
+        if (matches(entry.path, SETTINGS_KEY_FILES)) seen.add(entry.path);
+    }
+    return [...seen];
+}
+
+const YAML_KEY = /^([-+])([ \t]*)([A-Za-z_][A-Za-z0-9_]*):/;
+
+/**
+ * Keys a unified patch removes and does not put back.
+ *
+ * A `-` line alone is not a removal: a reindent, a reorder or a move between
+ * files deletes the line and adds it again, and counting that as a dropped
+ * settings key would fire the surface on every reformat. A key is removed only
+ * when no `+` line in the same patch declares it. Indentation is ignored on
+ * purpose — a key that moved under a different parent still exists, and this
+ * function is asked whether the key is gone, not where it lives.
+ *
+ * WHAT IT CANNOT SEE, corrected 2026-10-21 after the R2 round-2 review read
+ * the paragraph above as a promise the code does not keep. This reads the
+ * PATCH, so "no `+` line declares it" is a statement about the diff, not about
+ * the file: a key name that survives unchanged elsewhere in the same file
+ * produces no `+` line at all and is therefore reported as removed. Measured
+ * in the scored window — the 10.0.0 span reports `enabled` removed while that
+ * template still carries 11 `enabled:` keys, and 11.0.0 reports `mode` while
+ * two remain. Deciding it properly needs the file at both ends, not the patch,
+ * which is a different function with a different cost; the name list is
+ * therefore an UPPER BOUND on what was removed.
+ *
+ * It does not bias the surface: `classify_surfaces` asks only whether the list
+ * is non-empty, and in both spans above the list is non-empty for a removal
+ * that is real anyway. A caller that reports the names themselves — as the
+ * out-of-sample measurement does — must say they are an upper bound.
+ */
+export function removed_setting_keys(patch: string): string[] {
+    const removed = new Set<string>();
+    const added = new Set<string>();
+    for (const line of patch.split('\n')) {
+        if (line.startsWith('---') || line.startsWith('+++')) continue;
+        const m = YAML_KEY.exec(line);
+        if (m === null) continue;
+        (m[1] === '-' ? removed : added).add(m[3] as string);
+    }
+    return [...removed].filter((k) => !added.has(k)).sort();
+}
+
+function matches(path: string, patterns: readonly RegExp[]): boolean {
+    return patterns.some((p) => p.test(path));
+}
+
+/** True for a status letter that creates or destroys a path, which is what the two file surfaces turn on. */
+function is_create_or_delete(status: string): boolean {
+    return status === 'A' || status === 'D';
+}
+
+/**
+ * The surfaces a span touched.
+ *
+ * A rename (`R`) counts as neither a creation nor a removal. That is the
+ * conservative reading and it can only under-report: a renamed rule still
+ * exists, and treating every move as a removal would fire this surface on
+ * every span in a tree that reorganises as often as this one. Under-reporting
+ * the surface axis cannot produce a false negative on a consumer-visible
+ * break, because the impact axis decides those on its own — the surface clause
+ * only ever adds a major.
+ *
+ * `removed_setting_keys` is supplied by the caller because deciding it needs
+ * the patch text, not the name-status list; passing it in keeps this pure.
+ */
+export function classify_surfaces(
+    entries: readonly DiffEntry[],
+    removed_keys: readonly string[] = [],
+): Set<MajorSurface> {
+    const out = new Set<MajorSurface>();
+    for (const entry of entries) {
+        if (!is_create_or_delete(entry.status)) continue;
+        if (matches(entry.path, INSTALLER_LAYOUT_PATHS)) out.add('installer-layout');
+        if (entry.status === 'D' && matches(entry.path, RULE_OR_SKILL_PATHS)) out.add('rule-or-skill-removal');
+    }
+    if (removed_keys.length > 0) out.add('settings-keys');
+    return out;
+}
+
+/** `git diff --name-status` output into entries; a rename record keeps its new path. */
+export function parse_name_status(raw: string): DiffEntry[] {
+    const out: DiffEntry[] = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '') continue;
+        const parts = line.split('\t');
+        if (parts.length < 2) continue;
+        const status = (parts[0] as string).charAt(0);
+        const path = parts[parts.length - 1] as string;
+        out.push({ status, path });
+    }
+    return out;
+}