@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/_lib/design_tolerance.ts

@@ -0,0 +1,281 @@
+/**
+ * Value reconciliation between a provided design artifact and a project's own
+ * tokens — the MEASUREMENT half, shipped; the BEHAVIOURAL half, deliberately
+ * not.
+ *
+ * WHAT THE COUNCIL DECIDED, and why this module is shaped this way.
+ *
+ * `road-to-design-intent-conformance` put `blocker: approximation-tolerance` to
+ * the AI council (anthropic + openai, 2/2, 2026-09-09). Neither member accepted
+ * any of the three options as written. Both split step 3.2 the same way: build
+ * the metric, the collection and the reporting now; ship **no tolerance
+ * constant at all**; defer the behaviour that would let a value change without
+ * being asked about.
+ *
+ * The argument that decided it, and it is the one to re-read before adding a
+ * number here: *"a number in a config file, even flagged unmeasured, shapes
+ * behaviour and creates path dependency."* Zero of seven design-to-code
+ * benchmarks in the evidence set score token conformance, so a shipped
+ * threshold would be a guess acquiring the authority of a default. Both
+ * `design.tolerance.*` keys therefore ship `null`, and `null` means **preserve
+ * and report**, never "reconcile freely".
+ *
+ * THE METRIC IS A PREREQUISITE the roadmap never named.
+ *
+ * The council added it: no colour tolerance is meaningful before the distance
+ * METHOD is fixed, because RGB Euclidean, ΔE LAB, CIEDE2000 and OKLab/ΔEOK give
+ * different numbers for the same pair. `openai` rejected the round's proposed
+ * `±5 per RGB channel` on exactly this ground — RGB channel distance is not
+ * perceptually uniform, so "likely imperceptible" is an unsupported conclusion.
+ *
+ * This module fixes the method as **OKLab ΔEOK** (a plain Euclidean distance in
+ * OKLab, the metric OKLab was designed to make meaningful) and leaves the
+ * threshold empty. Method without threshold is the honest state: the distance
+ * on every row is a real, comparable number, and nothing yet says which
+ * distances are small enough to act on.
+ *
+ * LENGTH CARRIES NO SHIPPED NUMBER either.
+ *
+ * Primer's spacing plugin widens each token's accepted set by ±1px and
+ * autofixes. That is the one real measurement in the evidence set and it is
+ * recorded as an **externally observed candidate**, not adopted:
+ * `OBSERVED_LENGTH_CANDIDATE_PX` exists to be cited, and no code path reads it
+ * as a threshold. The round's other proposal, `max(1px, 2%)`, was rejected for
+ * growing steadily more permissive at large dimensions with no evidence that
+ * this is wanted.
+ *
+ * EVERY ROW CARRIES ITS DISTANCE, even when the value is preserved.
+ *
+ * That is the step's own verify clause and it is the property that makes the
+ * deferred half decidable later: a shadow window over rows that report
+ * distances can produce a distribution, where a window over rows that report
+ * only "kept" or "changed" cannot.
+ */
+
+/** Fixed method. See the header: the threshold is absent, the metric is not. */
+export const COLOR_DISTANCE_METRIC = 'oklab-deltaEOK' as const;
+/** Fixed method for lengths: absolute difference in CSS pixels. */
+export const LENGTH_DISTANCE_METRIC = 'abs-px' as const;
+
+/**
+ * GitHub Primer's spacing plugin widens each token's accepted set by ±1px.
+ * Recorded as an externally observed candidate for a future threshold; **no
+ * code path reads this as one**, and a test pins that it never becomes the
+ * shipped default without a decision.
+ */
+export const OBSERVED_LENGTH_CANDIDATE_PX = 1;
+
+export interface ToleranceConfig {
+    /** Master switch. Ships `false`; `blocker: fidelity-default-flip` → (a). */
+    enabled: boolean;
+    /** ΔEOK below which a colour may be reconciled. `null` ships. */
+    color: number | null;
+    /** Pixels below which a length may be reconciled. `null` ships. */
+    length: number | null;
+}
+
+/** The shipped configuration. Both thresholds absent, mechanism off. */
+export const SHIPPED_TOLERANCE: ToleranceConfig = { enabled: false, color: null, length: null };
+
+export type ReconcileOutcome =
+    /** Inside tolerance: the project token wins, and the change is reported. */
+    | 'reconciled'
+    /** Outside tolerance: the artifact's value is preserved, gap reported. */
+    | 'preserved-outside-tolerance'
+    /** The mechanism is off, or no threshold is configured: preserve, report. */
+    | 'preserved-mechanism-off'
+    /** No project token to compare against: nothing to reconcile onto. */
+    | 'no-candidate';
+
+export interface TokenCandidate {
+    name: string;
+    value: string;
+}
+
+export interface ValueRow {
+    /** The artifact's own value, verbatim. */
+    artifact: string;
+    /** Nearest project token, or null when the project has none of this kind. */
+    nearest: TokenCandidate | null;
+    /** Distance to `nearest` in the metric named below. Null iff no candidate. */
+    distance: number | null;
+    metric: typeof COLOR_DISTANCE_METRIC | typeof LENGTH_DISTANCE_METRIC | null;
+    /** The value actually written. Equals `artifact` unless reconciled. */
+    resolved: string;
+    outcome: ReconcileOutcome;
+}
+
+// ------------------------------------------------------------------ colour
+
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+
+/**
+ * `#rgb` / `#rrggbb` → 0–1 channels, or null when unparseable.
+ *
+ * An 8-digit `#rrggbbaa` returns NULL rather than its opaque prefix. ΔEOK is a
+ * three-channel metric and has nothing to say about alpha, so truncating made
+ * `#ff000080` and `#ff0000` measure distance 0 — "identical" for two values a
+ * designer chose to differ. Found by a blind review. Null is the honest answer:
+ * the row is reported as unmeasured, which is what it is.
+ */
+export function parseHex(value: string): Rgb | null {
+    const m = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(value.trim());
+    if (!m) return null;
+    let hex = m[1] as string;
+    if (hex.length === 3) {
+        hex = hex
+            .split('')
+            .map((c) => c + c)
+            .join('');
+    }
+    return {
+        r: parseInt(hex.slice(0, 2), 16) / 255,
+        g: parseInt(hex.slice(2, 4), 16) / 255,
+        b: parseInt(hex.slice(4, 6), 16) / 255,
+    };
+}
+
+/** sRGB transfer function, inverted — required before the OKLab matrices. */
+function toLinear(c: number): number {
+    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+/** sRGB → OKLab (Björn Ottosson's published matrices). */
+export function srgbToOklab(rgb: Rgb): { L: number; a: number; b: number } {
+    const r = toLinear(rgb.r);
+    const g = toLinear(rgb.g);
+    const b = toLinear(rgb.b);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+
+/**
+ * ΔEOK — Euclidean distance in OKLab. Null when either value is not a hex
+ * colour this module can parse; an unparseable value is reported as unmeasured
+ * rather than assigned a distance of zero, which would read as "identical".
+ */
+export function deltaEOK(a: string, b: string): number | null {
+    const ra = parseHex(a);
+    const rb = parseHex(b);
+    if (!ra || !rb) return null;
+    const la = srgbToOklab(ra);
+    const lb = srgbToOklab(rb);
+    return Math.sqrt((la.L - lb.L) ** 2 + (la.a - lb.a) ** 2 + (la.b - lb.b) ** 2);
+}
+
+// ------------------------------------------------------------------ length
+
+/** `16px` / `1rem` / `0.5rem` → pixels at a 16px root, or null. */
+export function parseLengthPx(value: string, rootPx = 16): number | null {
+    const m = /^(-?\d*\.?\d+)(px|rem|em)$/.exec(value.trim());
+    if (!m) return null;
+    const n = Number(m[1]);
+    if (!Number.isFinite(n)) return null;
+    return m[2] === 'px' ? n : n * rootPx;
+}
+
+/** Absolute pixel difference, or null when either side is unparseable. */
+export function lengthDistancePx(a: string, b: string, rootPx = 16): number | null {
+    const pa = parseLengthPx(a, rootPx);
+    const pb = parseLengthPx(b, rootPx);
+    if (pa === null || pb === null) return null;
+    return Math.abs(pa - pb);
+}
+
+// ------------------------------------------------------------- reconcile
+
+export type ValueKind = 'color' | 'length';
+
+function distanceFor(kind: ValueKind, a: string, b: string): number | null {
+    return kind === 'color' ? deltaEOK(a, b) : lengthDistancePx(a, b);
+}
+
+/** Nearest candidate by the kind's own metric. Ties break on first-listed. */
+export function nearestToken(
+    kind: ValueKind,
+    artifact: string,
+    candidates: readonly TokenCandidate[],
+): { candidate: TokenCandidate; distance: number } | null {
+    let best: { candidate: TokenCandidate; distance: number } | null = null;
+    for (const candidate of candidates) {
+        const d = distanceFor(kind, artifact, candidate.value);
+        if (d === null) continue;
+        if (best === null || d < best.distance) best = { candidate, distance: d };
+    }
+    return best;
+}
+
+/**
+ * Reconcile one artifact value against the project's tokens.
+ *
+ * **The distance is computed and reported on every path**, including every path
+ * that preserves the artifact's value — that is the step's verify clause, and
+ * it is what makes a later shadow distribution possible.
+ */
+export function reconcileValue(
+    kind: ValueKind,
+    artifact: string,
+    candidates: readonly TokenCandidate[],
+    config: ToleranceConfig = SHIPPED_TOLERANCE,
+): ValueRow {
+    const metric = kind === 'color' ? COLOR_DISTANCE_METRIC : LENGTH_DISTANCE_METRIC;
+    const best = nearestToken(kind, artifact, candidates);
+
+    if (best === null) {
+        return {
+            artifact,
+            nearest: null,
+            distance: null,
+            metric: null,
+            resolved: artifact,
+            outcome: 'no-candidate',
+        };
+    }
+
+    const base = {
+        artifact,
+        nearest: best.candidate,
+        distance: best.distance,
+        metric,
+    } as const;
+
+    const threshold = kind === 'color' ? config.color : config.length;
+
+    // Off, or no threshold configured. These are ONE outcome on purpose: a
+    // mechanism with no threshold cannot act, so reporting it as anything but
+    // "off" would imply a decision nobody made.
+    if (!config.enabled || threshold === null) {
+        return { ...base, resolved: artifact, outcome: 'preserved-mechanism-off' };
+    }
+
+    if (best.distance <= threshold) {
+        return { ...base, resolved: best.candidate.value, outcome: 'reconciled' };
+    }
+    return { ...base, resolved: artifact, outcome: 'preserved-outside-tolerance' };
+}
+
+/** One human-readable row. Always names the distance, never only the verdict. */
+export function formatRow(row: ValueRow): string {
+    if (row.nearest === null || row.distance === null) {
+        return `${row.artifact} → kept (no project token of this kind to compare against)`;
+    }
+    const d = `${row.metric ?? '?'} ${row.distance.toFixed(4)}`;
+    switch (row.outcome) {
+        case 'reconciled':
+            return `${row.artifact} → ${row.nearest.name} (${row.nearest.value}); reconciled, distance ${d}`;
+        case 'preserved-outside-tolerance':
+            return `${row.artifact} → kept; nearest ${row.nearest.name} (${row.nearest.value}) is outside tolerance, distance ${d}`;
+        default:
+            return `${row.artifact} → kept; nearest ${row.nearest.name} (${row.nearest.value}), distance ${d} (reconciliation off)`;
+    }
+}

package/src/scripts/_lib/guidelines_lane.ts

@@ -0,0 +1,164 @@
+/**
+ * The `docs/guidelines/` → `dist/agent-src/guidelines/` projection lane.
+ *
+ * Why this exists at all: the projected rules declare `routes_to:
+ * guideline:<slug>` against **22 distinct targets** and link
+ * `../../docs/guidelines/<slug>.md`, and until this lane shipped
+ * `dist/agent-src/` carried no `guidelines/` directory — so every one of those
+ * routes was declared and dead in a consumer install. (The figure is the gate's own reading. An
+ * earlier draft here said "31 rules", which reproduced on nothing: `grep -l`
+ * returns 22 in both trees. A blind review checked it; the number is now the
+ * one `check_projected_rule_routes` prints.) `AUGMENT_SYMLINK_DIRS`
+ * in `condense.ts` has listed `guidelines` since before the lane existed; the
+ * symlink simply had nothing to point at.
+ *
+ * Shape, and why it is a lane rather than a source root: the multi-root
+ * resolver in `agent_src.ts` derives an artefact's *identity* from
+ * `_root_specs()`, and everything that scans the artefact estate — the
+ * discovery manifest, the skill linter, the size and count ratchets — walks
+ * that same list. Adding `docs/guidelines` there would reclassify 119
+ * guidelines as estate artefacts and move every one of those numbers. So the
+ * lane is appended only where the *projection* reads (`iter_all_sources` and
+ * `resolve_logical`), exactly as `_iter_domains_commands` already is, and the
+ * estate view is left alone.
+ *
+ * Identity: `docs/guidelines/<subpath>.md` is logical `guidelines/<subpath>.md`
+ * — one directory deep in the projection, the same depth as `rules/` and
+ * `skills/`, which is what makes the existing `../guidelines/…` rewrite in
+ * `condense.ts::_rewrite_body_links` resolve from a projected rule.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Logical-path prefix every guideline is projected under. */
+export const GUIDELINES_LOGICAL_PREFIX = 'guidelines/';
+
+/** Physical source directory, relative to the repo root. */
+export const GUIDELINES_SOURCE_REL = path.join('docs', 'guidelines');
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** Recursive, name-sorted at every level so the walk order is deterministic. */
+function* _walkSorted(dir: string): Generator<string> {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir).sort();
+    } catch {
+        return;
+    }
+    for (const name of entries) {
+        const full = path.join(dir, name);
+        if (_isDir(full)) {
+            yield* _walkSorted(full);
+        } else if (_isFile(full)) {
+            yield full;
+        }
+    }
+}
+
+/**
+ * Yield `[physical_path, logical_relpath]` for every file under
+ * `<root>/docs/guidelines/`. Deterministic order; yields nothing when the
+ * directory is absent, which is the normal state of a consumer checkout.
+ */
+export function* iter_guidelines(root: string): Generator<[string, string]> {
+    const base = path.join(root, GUIDELINES_SOURCE_REL);
+    if (!_isDir(base)) {
+        return;
+    }
+    for (const p of _walkSorted(base)) {
+        const rel = path.relative(base, p).split(path.sep).join('/');
+        yield [p, GUIDELINES_LOGICAL_PREFIX + rel];
+    }
+}
+
+/**
+ * Physical path backing a logical `guidelines/<subpath>`, or `null` when the
+ * logical path is not a guideline or the file does not exist.
+ */
+export function resolve_guideline(root: string, logical_rel: string): string | null {
+    const rel = logical_rel.replaceAll('\\', '/').replace(/^\/+/, '');
+    if (!rel.startsWith(GUIDELINES_LOGICAL_PREFIX)) {
+        return null;
+    }
+    const suffix = rel.slice(GUIDELINES_LOGICAL_PREFIX.length);
+    if (suffix.length === 0 || suffix.split('/').includes('..')) {
+        return null;
+    }
+    const candidate = path.join(root, GUIDELINES_SOURCE_REL, suffix);
+    return _isFile(candidate) ? candidate : null;
+}
+
+/**
+ * Rewrite a projected body's relative `.md` links onto the projection.
+ *
+ * Lives here rather than in `condense.ts` for two reasons, and the second is
+ * the load-bearing one. It is this lane's own subject: every rule it applies is
+ * a statement about which source trees project where, which is what this module
+ * exists to know. And `condense.ts` sits ~1,200 lines past the 1,500-line
+ * ceiling `check_source_size_budget` ratchets, so every line there costs one
+ * unit of excess while every line here costs zero — the doctrine that file's
+ * own baseline note prescribes for exactly this case.
+ *
+ * `prefix` is the caller's depth prefix (`../` per level below
+ * `dist/agent-src/`), so a rule at depth 1 and a guideline at depth 2 both
+ * resolve.
+ */
+export function rewriteProjectedBodyLinks(body: string, prefix: string): string {
+    return body
+        .replace(BODY_DOCS_RE, (_m, t: string) => prefix + t.replace(/^docs\/guidelines\//, 'guidelines/'))
+        .replace(BODY_SRC_FLAT_RE, (_m, t: string) => prefix + t)
+        .replace(BODY_SRC_AGENT_RE, (_m, t: string) => prefix + t);
+}
+
+/**
+ * `docs/guidelines/` is projected and loses its `docs/` segment;
+ * `docs/contracts/` is NOT projected and keeps its path unchanged.
+ *
+ * One-or-more `../` rather than a literal `../../`: the dominant convention in
+ * `src/rules/` is a single `../` — 26 sites across 18 rules — so a literal
+ * two-level pattern matched only the minority spelling.
+ */
+const BODY_DOCS_RE = /(?:\.\.\/)+(docs\/(?:guidelines|contracts)\/[^)\s]+\.md)/g;
+
+/**
+ * Source trees that project into `dist/agent-src/`, losing their `src/` (and
+ * `agent-src/`) segment.
+ *
+ * Until the guidelines lane shipped, no PROJECTED file linked into `src/`, so
+ * this rewrite had nothing to do and did not exist. A guideline does it 209
+ * times — a blind review measured 253 of 268 links under
+ * `dist/agent-src/guidelines/` resolving to nothing before this was added.
+ *
+ * TWO patterns, not one, and the difference is load-bearing. `rules` and
+ * `skills` are FLAT library roots directly under `src/`; `commands`,
+ * `contexts`, `personas`, `user-types`, `templates` and `scripts` exist only
+ * under `src/agent-src/`. A single pattern with an optional `agent-src/` group
+ * conflates them, and the conflation is not theoretical: it folded
+ * `../../src/scripts/media/lib/adapter-contract.md` — a real link in
+ * `provider-lifecycle-discipline.md` — onto `../scripts/…`, which resolves to
+ * `dist/agent-src/scripts/`, a projection of `src/agent-src/scripts/` and a
+ * different tree entirely. `check_condensed_paths` caught it; the first version
+ * of this regex turned one resolving link into a broken one.
+ *
+ * `src/domains` is deliberately absent from both: a domains command projects to
+ * `commands/<subpath>.md`, which is a re-shaping rather than a prefix strip,
+ * and guessing it would produce a link that looks right and is wrong.
+ */
+const BODY_SRC_FLAT_RE = /(?:\.\.\/)+src\/((?:rules|skills)\/[^)\s]+\.md)/g;
+const BODY_SRC_AGENT_RE =
+    /(?:\.\.\/)+src\/agent-src\/((?:commands|contexts|personas|user-types|templates|scripts)\/[^)\s]+\.md)/g;

package/src/scripts/_lib/hook_settings.ts

@@ -110,3 +110,88 @@ export function leanProjectionModeRaw(root: string): string {
     }
     return '';
 }
+
+/**
+ * Raw `lean_projection.hosts` list out of `.agent-settings.yml`, or `[]`.
+ *
+ * Same indentation-shaped discipline as `leanProjectionModeRaw` above and for
+ * the same reason — a hook must never fail a tool call because a YAML parser
+ * could not load — extended to the three list shapes a human writes:
+ *
+ *     lean_projection:
+ *       hosts: [claude-code]          # inline
+ *     lean_projection:
+ *       hosts:                        # block, indented under the key
+ *         - claude-code
+ *     lean_projection:
+ *       hosts:                        # block, at the key's own indent
+ *       - claude-code
+ *
+ * All three are legal YAML and `js-yaml` loads them identically; the third was
+ * read as `[]` until 2026-09-08 (R2 finding 2) and is covered by three fixtures
+ * in `tests/scripts/lean_projection_hosts.test.ts`.
+ *
+ * Interpretation is NOT done here. `[]` means "nothing was written", and
+ * `_lib/lean_projection_mode.ts::resolveLeanProjectionHosts` decides that this
+ * means the default rather than "no host" — keeping that decision in one place
+ * is what stops the projector and the delivery concern from disagreeing, which
+ * is the whole reason the mode reader is split this way.
+ */
+export function leanProjectionHostsRaw(root: string): string[] {
+    const file = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(file).isFile()) return [];
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const strip = (s: string): string => s.trim().replace(/^["']|["']$/g, '');
+    let inSection = false;
+    let inBlock = false;
+    let blockIndent = -1;
+    const out: string[] = [];
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inSection = /^lean_projection\s*:\s*$/.test(line);
+            inBlock = false;
+            continue;
+        }
+        if (!inSection) continue;
+        const indent = (/^\s*/.exec(line) as RegExpExecArray)[0].length;
+        if (inBlock) {
+            const item = /^\s*-\s*(\S.*)$/.exec(line);
+            // `>=`, not `>`: YAML lets a block sequence sit at its KEY's own
+            // indent, and `js-yaml` — the parser `condense` uses on this same
+            // file — loads that shape identically to the deeper-indented one.
+            // With `>` the same-indent form parsed as `[]`, which
+            // `resolveLeanProjectionHosts` reads as "nothing was written" and
+            // answers with the default `[claude-code]` while the projector
+            // thins whatever the file actually says. Two readers disagreeing
+            // about the delivery-host set is the one failure this split exists
+            // to prevent (R2 finding 2). A SHALLOWER item still ends the block:
+            // it belongs to a different mapping level, never to `hosts`.
+            if (item !== null && indent >= blockIndent) {
+                const v = strip(item[1] ?? '');
+                if (v !== '') out.push(v);
+                continue;
+            }
+            inBlock = false;
+        }
+        const inline = /^\s+hosts\s*:\s*\[([^\]]*)\]\s*$/.exec(line);
+        if (inline !== null) {
+            for (const part of (inline[1] ?? '').split(',')) {
+                const v = strip(part);
+                if (v !== '') out.push(v);
+            }
+            continue;
+        }
+        if (/^\s+hosts\s*:\s*$/.test(line)) {
+            inBlock = true;
+            blockIndent = indent;
+        }
+    }
+    return out;
+}

package/src/scripts/_lib/lean_projection_mode.ts

@@ -42,3 +42,130 @@ export function writesThinFiles(mode: LeanProjectionMode): boolean {
 export function deliversBodies(mode: LeanProjectionMode): boolean {
     return mode === 'delivery';
 }
+
+/**
+ * The hosts a thinning mode may actually thin.
+ *
+ * Deliberately NOT "every host id the package knows". `condense`'s `TOOL_DIRS`
+ * writes a per-rule tree for exactly three hosts, so those are the only ids for
+ * which `lean_projection.hosts` can mean anything: naming `windsurf` there would
+ * be a request to thin a single concatenated file that has no per-rule stub
+ * shape, and naming `codex` a request to thin a tree the installer writes and
+ * `condense` never touches. Accepting such an id silently would leave the
+ * operator believing a host was scoped when nothing reads the entry.
+ */
+export const THINNABLE_HOSTS: readonly string[] = ['claude-code', 'cursor', 'cline'];
+
+/**
+ * The shipped default host set for a thinning mode.
+ *
+ * One host, and it is the one host that both binds `pre_tool_use` and honours a
+ * deny (`docs/enforcement-by-host.md:18-28`) — i.e. the only host where the
+ * delivery concern's verdict is acted on. Widening this is a decision, never a
+ * default: see `resolveLeanProjectionHosts`, which never widens implicitly.
+ */
+export const DEFAULT_LEAN_PROJECTION_HOSTS: readonly string[] = ['claude-code'];
+
+/** Why an id in a configured `hosts:` list was not kept. */
+export type DroppedHostReason = 'unknown' | 'not-thinnable';
+
+export interface LeanProjectionHosts {
+    /** The ids that survived, sorted and de-duplicated. */
+    readonly hosts: readonly string[];
+    /** Ids that were dropped, with the reason — reported, never silently discarded. */
+    readonly dropped: ReadonlyArray<{ readonly id: string; readonly reason: DroppedHostReason }>;
+    /** True when nothing was configured and the default was applied. */
+    readonly usedDefault: boolean;
+}
+
+/**
+ * Resolve a configured `lean_projection.hosts` list.
+ *
+ * Three properties, each of which is a failure this repository has seen in a
+ * neighbouring config surface:
+ *
+ * 1. **Absent means the default, never "all".** An empty or missing list
+ *    resolves to `DEFAULT_LEAN_PROJECTION_HOSTS`. A key nobody set must not
+ *    thin every host — that is D1, the defect this axis exists to repair.
+ * 2. **The set never widens implicitly.** Every id is checked against
+ *    `THINNABLE_HOSTS`; anything else is dropped. A typo cannot enrol a host,
+ *    and neither can a real host id that has no per-rule tree.
+ * 3. **A drop is reported, not swallowed.** The caller gets the ids and the
+ *    reason so it can print them. Silently ignoring an entry an operator wrote
+ *    is how a setting comes to mean nothing while looking configured.
+ *
+ * A configured list that resolves to NOTHING keeps `usedDefault: false` and an
+ * empty `hosts` — that is "thin no host", which is a legitimate and safe answer
+ * and must not fall back to the default. Falling back there would turn a
+ * fully-typo'd list into a Claude Code flip the operator never asked for.
+ *
+ * WHICH FILES REACH THIS AT ALL, stated because R2 finding 6 read the drop path
+ * as unreachable: `agent-settings.schema.json` and the wizard's Zod schema both
+ * constrain the items to an `enum`, so an out-of-vocabulary id written through
+ * either surface is a hard validation FAILURE and never arrives here. What
+ * arrives here is a HAND-EDITED `.agent-settings.yml` — the file
+ * `condense._lean_projection_settings` and `hooks/rule_inject_hook.gateOpen`
+ * both read directly, with no validation step in between. The two layers are
+ * defence in depth, not one contract stated twice: the schema is the authoring
+ * gate, this function is the read-time gate, and the drop wording below exists
+ * for the file the schema never saw.
+ */
+export function resolveLeanProjectionHosts(raw: unknown): LeanProjectionHosts {
+    const known = new Set(THINNABLE_HOSTS);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { hosts: [...DEFAULT_LEAN_PROJECTION_HOSTS], dropped: [], usedDefault: true };
+    }
+    const hosts: string[] = [];
+    const dropped: Array<{ id: string; reason: DroppedHostReason }> = [];
+    for (const entry of raw) {
+        const id = typeof entry === 'string' ? entry.trim().toLowerCase() : '';
+        if (id === '') {
+            dropped.push({ id: String(entry), reason: 'unknown' });
+            continue;
+        }
+        if (!known.has(id)) {
+            // `not-thinnable` is reserved for an id this package genuinely knows
+            // as a host but which owns no per-rule tree. Everything else is a
+            // typo or an invention, and the two deserve different wording
+            // because the operator's next action differs: fix the spelling, or
+            // learn that the host cannot be thinned at all.
+            dropped.push({ id, reason: KNOWN_NON_THINNABLE_HOSTS.has(id) ? 'not-thinnable' : 'unknown' });
+            continue;
+        }
+        if (!hosts.includes(id)) hosts.push(id);
+    }
+    hosts.sort();
+    return { hosts, dropped, usedDefault: false };
+}
+
+/**
+ * Host ids the package ships surfaces for that own no per-rule rule tree.
+ *
+ * Only used to word a drop precisely; it grants nothing. Sourced from
+ * `condense._ALL_TOOLS` plus the two hosts outside it that the host table
+ * carries (`codex`, `cowork`).
+ */
+const KNOWN_NON_THINNABLE_HOSTS: ReadonlySet<string> = new Set([
+    'claude-desktop', 'augment', 'copilot', 'windsurf', 'gemini', 'codex', 'cowork',
+]);
+
+/** One line per dropped id, for a caller that prints warnings. Empty when nothing was dropped. */
+export function describeDroppedHosts(res: LeanProjectionHosts): string[] {
+    return res.dropped.map(({ id, reason }) =>
+        reason === 'not-thinnable'
+            ? `lean_projection.hosts: "${id}" is a known host but has no per-rule rule tree — dropped`
+            : `lean_projection.hosts: "${id}" is not a thinnable host id — dropped`,
+    );
+}
+
+/**
+ * Does the projector write stubs for this host, under this mode and host set?
+ *
+ * The single predicate `condense` calls. Mode is checked FIRST and on purpose:
+ * with `mode` unset the answer is `false` for every host regardless of what
+ * `hosts` says, so a `hosts:` list left behind after a rollback to `eager-all`
+ * thins nothing.
+ */
+export function thinsHost(mode: LeanProjectionMode, hosts: readonly string[], hostId: string): boolean {
+    return writesThinFiles(mode) && hosts.includes(hostId);
+}

package/src/scripts/_lib/obligation_frequency.ts

@@ -241,9 +241,8 @@ export type Slot =
  * Default firing period per slot, before per-platform native-event corrections.
  *
  * `stop` is per-turn, NOT session end. On Claude Code the native `Stop` event
- * fires after every assistant reply — `hook_manifest.yaml` says so itself,
- * describing the `stop` write as a "deterministic … overwrite of hot-context.md",
- * i.e. a working-memory refresh per reply. True session end is the separate
+ * fires after every assistant reply, so a concern bound there runs once per
+ * reply rather than once per session. True session end is the separate
  * `session_end` slot.
  */
 const SLOT_FREQUENCY_DEFAULT: Record<Slot, Frequency> = {