@event4u/agent-config 14.22.0 → 15.0.0

package/dist/scripts/project_thin_rules.js

@@ -19,7 +19,7 @@
  * `.augment/` projections.
  *
  * NOTE (faithful literal): the thin-entry pointer keeps the verbatim
- * `Body: [`{rule_id}`](../../.agent-src.uncondensed/rules/{rule_id}.md)`
+ * `Body: [`{rule_id}`](../../dist/agent-src/rules/{rule_id}.md)`
  * Markdown link from the retired Python implementation. The same-basename `.py` twin
  * carries that literal, so the ADR-051 legacy-path guard exempts this `.ts`
  * file by twin-parity.
@@ -34,6 +34,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pathOnlyRuleIds, triggerlessRuleIds, } from './_lib/rule_injection.js';
 import * as token_count from './_lib/token_count.js';
 const _HERE = fileURLToPath(import.meta.url);
 // REPO_ROOT = Path(__file__).resolve().parent.parent.parent — three dirs up
@@ -72,21 +73,85 @@ export function kernel_ids() {
  * visible instead of being absorbed into the pointer count
  * (road-to-trigger-delivered-rule-bodies 1.3).
  */
+/**
+ * Rules whose ONLY triggers are path-shaped — reachable from `pre_tool_use`
+ * and from no other slot (road-to-delivery-for-every-host 3.2).
+ *
+ * They must never be thinned while the delivery concern is NOT bound on
+ * `pre_tool_use`, because a stub plus a slot nobody listens on is a rule that
+ * reaches the model at no scope at all. This is the same failure the
+ * `no_trigger_ids` exemption prevents, one step out: there the rule has nothing
+ * to match on, here it has nothing to match ON.
+ *
+ * Stated as a PROPERTY rather than a list of ids. If the concern is ever bound
+ * on `pre_tool_use` again, this exemption is what should be reconsidered — not
+ * three names someone has to remember.
+ *
+ * WHAT THIS EXEMPTION DOES **NOT** COVER — recorded 2026-09-08, R2 finding 1,
+ * because the silence read as coverage. The predicate is `every` trigger
+ * path-shaped. A rule with BOTH path and non-path triggers is therefore THINNED,
+ * and its path-shaped half then has no carrier at all: the stub carries no
+ * frontmatter (`condense.ts` writes it with `_writeText`, bypassing
+ * `_emit_claude_rule`'s host-native `paths:` key), `pre_tool_use` lost the
+ * binding under owner ruling E2, and `user_prompt_submit` never populates
+ * `openFiles`. Measured over the current `dist/router.json`: **18 such rules**,
+ * all non-kernel and all thinned — augment-edit-discipline, design-fidelity,
+ * doc-screenshot-hygiene, domain-adoption-policy,
+ * framework-neutrality-in-generic-skills, image-likeness-and-rights,
+ * laravel-translations, lethal-trifecta-guard, linked-projects-onboarding-gate,
+ * low-impact-corpus-privacy-floor, markdown-safe-codeblocks, onboarding-gate,
+ * persona-governance, php-coding, provider-lifecycle-discipline,
+ * roadmap-ci-steps-policy, roadmap-progress-sync, settings-ask-protocol.
+ *
+ * They do NOT reach the model at no scope: every non-path route
+ * (keyword / phrase / command) still delivers the body through the concern, and
+ * on `claude-code` they never had a separate host-native path route to lose —
+ * `_claude_paths_plan` emits no `paths:` for a mixed-trigger rule on purpose, so
+ * under `eager-all` they loaded UNCONDITIONALLY. What is lost is the difference
+ * between unconditional and prompt-triggered: a session that touches a matching
+ * file and says nothing that matches gets nothing.
+ *
+ * The labelled corpus cannot see this and the endpoint says so rather than
+ * implying otherwise — `model_rule_injection --endpoints` (b) now publishes the
+ * shipped `user_prompt_submit` reach beside the pre-registered reading, and
+ * every one of these 18 has at least one prompt-matching positive, so none
+ * appears in its "reachable only via a path trigger" column.
+ *
+ * WHY THIS IS NOT WIDENED TO `some` HERE. Measured: exempting all 18 moves the
+ * thin rule layer 23,592 -> 39,921 GPT tok (+16,329, +69 %), which is a budget
+ * move of a magnitude no agent may take, and it would erase most of the saving
+ * the flip is licensed on. Restoring a path route needs either that exemption
+ * under a re-anchored baseline or a `pre_tool_use` binding under a raised slot
+ * cap — both owner-reserved, so the closure is tracked rather than taken here.
+ * ADR-267's Consequences section names the receiver.
+ */
+/**
+ * ONE spelling of the router-derived sets, shared with the injector (R2
+ * finding 11).
+ *
+ * `path_only_ids` and `no_trigger_ids` were each a second, hand-rolled
+ * implementation of `_lib/rule_injection.ts::pathOnlyRuleIds` /
+ * `triggerlessRuleIds` — verified identical over the current router at the time
+ * (symmetric difference empty), so drift risk rather than a live defect. It is
+ * exactly the hazard `THIN_ENTRY_MARKER`'s own comment argues against one
+ * screen below ("a gate that re-spelled this string would drift from the writer
+ * silently"), and the two consumers here are the PROJECTOR's exemption set and
+ * the INJECTOR's reachability set: they must not be able to disagree about which
+ * rules the delivery path can reach.
+ *
+ * The finding named `path_only_ids`. The defect-pattern sweep found the SECOND
+ * instance one function down — `no_trigger_ids` against `triggerlessRuleIds` —
+ * and it is delegated in the same change. Count: 2 of 2 duplicated
+ * router-derived sets in this file, 0 remaining.
+ */
+function _router() {
+    return JSON.parse(fs.readFileSync(ROUTER, 'utf-8'));
+}
+export function path_only_ids() {
+    return pathOnlyRuleIds(_router());
+}
 export function no_trigger_ids() {
-    const data = JSON.parse(fs.readFileSync(ROUTER, 'utf-8'));
-    const out = new Set();
-    for (const tier of ['tier_1', 'tier_2']) {
-        const entries = data[tier];
-        if (!Array.isArray(entries))
-            continue;
-        for (const e of entries) {
-            const obj = e;
-            const t = obj.triggers;
-            if (!Array.isArray(t) || t.length === 0)
-                out.add(String(obj.id));
-        }
-    }
-    return out;
+    return new Set(triggerlessRuleIds(_router()));
 }
 /**
  * id → workspaces for every non-kernel router entry (router.json schema v2,
@@ -179,6 +244,42 @@ function _trigger_hint(fm) {
 function _title(s) {
     return s.replace(/[A-Za-z]+/g, (w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
 }
+/**
+ * The marker that makes a projected entry recognisable as a stub.
+ *
+ * Exported so the WRITER and every DETECTOR share one definition. A gate that
+ * re-spelled this string would drift from the writer silently, and the failure
+ * would be invisible in exactly the direction that matters: a stub the gate
+ * fails to recognise reads as a complete rule body.
+ */
+export const THIN_ENTRY_MARKER = '> Routed rule — load the body on trigger-match.';
+/** Is this projected entry a pointer stub rather than a rule body? */
+export function is_thin_entry(text) {
+    return text.includes(THIN_ENTRY_MARKER);
+}
+/**
+ * Where a stub tells a reader the body actually is.
+ *
+ * FIXED 2026-09-07: this pointed into the uncondensed source tree ADR-051
+ * retired — the literal path is deliberately NOT reproduced here, because
+ * `check_no_uncondensed_refs` matches the string and cannot tell a repair
+ * record from a live reference; `git log -S` on this file finds the old value.
+ * It exists in no checkout, so EVERY stub's fallback pointer
+ * resolved to nothing — invisible under `delivery`, where the hook loads the
+ * body from `dist/agent-src/rules` and never follows this link, and total under
+ * `thin`, where the pointer is the only path to the body there is.
+ *
+ * KNOWN LIMIT, stated rather than discovered later: one relative prefix cannot
+ * be right for every tree, because they sit at different depths — `.claude/rules`
+ * and `.cursor/rules` are two levels below the repo root and `.clinerules` is
+ * one. `../../` is correct for the first two, which are the only trees the
+ * shipped `lean_projection.hosts` default can thin. A stub in `.clinerules`
+ * needs an operator to have added `cline` to that list, and its pointer is off
+ * by one level. That is strictly better than the previous state, where the
+ * pointer was dead in all three, and it is recorded here so the remaining case
+ * is a known limit rather than a surprise.
+ */
+const BODY_LINK_PREFIX = '../../dist/agent-src/rules/';
 /** Build the minimal progressive-disclosure pointer for a non-kernel rule. */
 export function thin_entry(rule_id, text) {
     const [fm] = split_frontmatter(text);
@@ -187,13 +288,25 @@ export function thin_entry(rule_id, text) {
     const title = _title(rule_id.replace(/-/g, ' '));
     const fires = hint ? ` Fires on: ${hint}.` : '';
     return (`## ${title}\n` +
-        `> Routed rule — load the body on trigger-match.${fires} ${desc} ` +
-        `Body: [\`${rule_id}\`](../../.agent-src.uncondensed/rules/${rule_id}.md)\n`);
+        `${THIN_ENTRY_MARKER}${fires} ${desc} ` +
+        `Body: [\`${rule_id}\`](${BODY_LINK_PREFIX}${rule_id}.md)\n`);
 }
 /** Map {filename: thin_or_full_text} for every rule. Kernel stays full. */
-export function build_thin(rules_dir = RULES_SOURCE, scope = null) {
+export function build_thin(rules_dir = RULES_SOURCE, scope = null, 
+/**
+ * Optional sink for the D3 diagnostic
+ * (road-to-delivery-for-every-host 2.2).
+ *
+ * An `auto` rule the router gives NO trigger is already kept full-bodied by
+ * `noTrigger` below, which is the substantive protection and predates this
+ * roadmap. What did not exist is any way to SEE it happen: the rule is
+ * silently exempted, so an author who removes a rule's last trigger gets a
+ * silently eager rule and no signal. The line makes the exemption audible.
+ */
+announce = null) {
     const kernel = kernel_ids();
     const noTrigger = no_trigger_ids();
+    const pathOnly = path_only_ids();
     const wsMap = scope !== null ? rule_workspaces_map() : new Map();
     const out = new Map();
     for (const p of _globSortedMd(rules_dir)) {
@@ -202,7 +315,14 @@ export function build_thin(rules_dir = RULES_SOURCE, scope = null) {
         if (!id_in_scope(stem, scope, kernel, wsMap, fm_workspaces(text))) {
             continue; // out of workspace scope — no body, no pointer line
         }
-        const full = kernel.has(stem) || noTrigger.has(stem);
+        const full = kernel.has(stem) || noTrigger.has(stem) || pathOnly.has(stem);
+        if (announce !== null && noTrigger.has(stem) && !kernel.has(stem)) {
+            announce(`D3: trigger-less auto rule ${path.basename(p)} — kept full-bodied, never thinned`);
+        }
+        if (announce !== null && pathOnly.has(stem) && !kernel.has(stem) && !noTrigger.has(stem)) {
+            announce(`E2: path-only auto rule ${path.basename(p)} — kept full-bodied; its only triggers ` +
+                `are path-shaped and the delivery concern is not bound on pre_tool_use`);
+        }
         out.set(path.basename(p), full ? text : thin_entry(stem, text));
     }
     return out;

package/dist/server/io/yamlIO.js

@@ -33,6 +33,24 @@ function formatScalar(value) {
     // Arrays / nested objects: dump inline. Form keeps depth ≤ 2 so this is rare.
     return yamlDump(value, { lineWidth: -1, flowLevel: 0 }).replace(/\n$/, '').trim();
 }
+/**
+ * A NESTED mapping key, as both the presence probe and the insertion walk read
+ * one. Shared so the writer and its own existence-probe cannot drift apart —
+ * that drift is the shape this file has now hit four times.
+ *
+ * `-` is in the class because a dashed key is ordinary YAML (`first-name`,
+ * `dry-run`, `retry-count`) and `detectIndentWidth` already accepted one.
+ * While this pattern did not, `findScalarLine` could never find such a key:
+ * `mergeIntoTemplate` then wrote a bogus top-level `x.first-principles:` line
+ * beside the real nested one and the intended value was never written — a save
+ * that silently did nothing — and `upsertScalar` appended another child line on
+ * EVERY call, growing without bound until the file stopped parsing.
+ *
+ * `.` stays OUT, deliberately. A dotted key is the FLAT form, which
+ * `replaceFlatDottedKey` owns; letting this pattern match `a.b:` would make the
+ * nested probe claim a line that is one key literally named "a.b".
+ */
+const NESTED_KEY_RE = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:/;
 function flatten(value, prefix = []) {
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {
         return [{ path: prefix, value }];
@@ -55,6 +73,25 @@ export function replaceScalar(template, dottedPath, value) {
     const sections = dottedPath.slice(0, -1);
     const key = dottedPath[dottedPath.length - 1];
     const lines = template.split('\n');
+    const at = findScalarLine(lines, sections, key);
+    if (at === -1)
+        return template;
+    const width = detectIndentWidth(lines);
+    lines[at] = `${' '.repeat(width * sections.length)}${key}: ${formatScalar(value)}`;
+    return lines.join('\n');
+}
+/**
+ * Index of the line holding the scalar at `sections`/`key`, or -1.
+ *
+ * Split out of `replaceScalar` so that "is this path present?" is answerable
+ * WITHOUT writing. `mergeIntoTemplate` used to infer presence from
+ * `replaceScalar` returning a changed string, which conflates "absent" with
+ * "present and already equal to the value being written" — under that test a
+ * no-op write reads as a miss and the caller appends a duplicate mapping key.
+ * A presence question answered by a mutation's side effect is the shape to
+ * look for here; the file already carries two earlier rounds of it.
+ */
+function findScalarLine(lines, sections, key) {
     // The document's own width, the same read `upsertScalar` performs.
     //
     // R2 round 5, finding 1, and it is the second half of round 4's finding 7.
@@ -71,9 +108,7 @@ export function replaceScalar(template, dottedPath, value) {
     // A writer and its own existence-probe disagreeing about the format is the
     // shape to look for whenever one of a pair is taught something new.
     const width = detectIndentWidth(lines);
-    const targetIndent = ' '.repeat(width * sections.length);
     const currentPath = new Array(sections.length).fill(null);
-    const formatted = formatScalar(value);
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (line === undefined)
@@ -87,7 +122,7 @@ export function replaceScalar(template, dottedPath, value) {
         const level = indentLen / width;
         if (level > sections.length)
             continue;
-        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(stripped);
+        const m = NESTED_KEY_RE.exec(stripped);
         if (!m)
             continue;
         const lineKey = m[1];
@@ -110,10 +145,9 @@ export function replaceScalar(template, dottedPath, value) {
             continue;
         if (lineKey !== key)
             continue;
-        lines[i] = `${targetIndent}${key}: ${formatted}`;
-        return lines.join('\n');
+        return i;
     }
-    return template;
+    return -1;
 }
 /**
  * The indent width this document actually uses, or 2 when it has no nesting.
@@ -181,11 +215,19 @@ export function detectIndentWidth(lines) {
 export function upsertScalar(template, dottedPath, value) {
     if (dottedPath.length === 0)
         return template;
-    const replaced = replaceScalar(template, dottedPath, value);
-    if (replaced !== template)
-        return replaced;
     const sections = dottedPath.slice(0, -1);
     const key = dottedPath[dottedPath.length - 1];
+    // Presence is asked, never inferred from the write changing the text. The
+    // string compare that used to stand here read "key already holds this
+    // value" as "key absent" and fell through to the append below — so saving
+    // the wizard's council page twice WITHOUT changing a toggle wrote a second
+    // `api_on_quota:` into the same block, over two `{ok: true}` responses, and
+    // left `.ai-council.yml` rejected by a strict parser. Third instance of one
+    // shape in this file; `findScalarLine` exists to end it, and a fix that
+    // taught only `mergeIntoTemplate` would have left the live path here.
+    if (findScalarLine(template.split('\n'), sections, key) !== -1) {
+        return replaceScalar(template, dottedPath, value);
+    }
     const formatted = formatScalar(value);
     const lines = template.split('\n');
     // The document's OWN indent width, not an assumed two.
@@ -229,7 +271,7 @@ export function upsertScalar(template, dottedPath, value) {
             const indentLen = line.length - line.trimStart().length;
             if (indentLen !== indent.length)
                 continue;
-            const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(line.trim());
+            const m = NESTED_KEY_RE.exec(line.trim());
             if (m !== null && m[1] === want) {
                 found = i;
                 break;
@@ -271,23 +313,89 @@ export function upsertScalar(template, dottedPath, value) {
     lines.splice(insertAt, 0, ...block);
     return lines.join('\n');
 }
+/**
+ * Rewrite an existing top-level `a.b.c: value` line — the FLAT form
+ * `mergeIntoTemplate` itself appends when a path has no template entry.
+ * Returns the template unchanged when no such line exists.
+ *
+ * `replaceScalar` cannot see this line: its key pattern is
+ * `[A-Za-z_][A-Za-z0-9_]*`, with no dot, so a path this module appended on
+ * one pass is invisible to the probe on the next and `mergeIntoTemplate`
+ * appends a SECOND copy. Two wizard saves therefore produce a file carrying
+ * duplicate mapping keys — a strict parser rejects it outright, which is what
+ * wedged `task release`: its `sync` step exits 2 with "Map keys must be
+ * unique" before the release does any git work.
+ *
+ * A pre-existing duplicate run is COLLAPSED, not merely updated: the first
+ * occurrence keeps its position and takes the new value, every later one is
+ * dropped. Collapsing is value-neutral — a lenient reader already resolved
+ * such a run last-wins — and it is the only way a file corrupted by the old
+ * behaviour becomes parseable again through the ordinary write path.
+ *
+ * Deliberately NOT folded into `replaceScalar`: `upsertScalar` calls that
+ * probe and documents the flat form as the WRONG shape for a nested key (a
+ * reader sees one key literally named "a.b"). Teaching the shared probe to
+ * match it would make `upsertScalar` write into that broken line instead of
+ * creating the nesting. The flat form is legitimate only here, where this
+ * function is the one that wrote it.
+ */
+function replaceFlatDottedKey(template, dottedPath, value) {
+    if (dottedPath.length < 2)
+        return { found: false, body: template };
+    const flat = dottedPath.join('.');
+    const lines = template.split('\n');
+    const hits = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        // Top level only — an indented `a.b:` is somebody else's child key.
+        if (line.length !== line.trimStart().length)
+            continue;
+        const m = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*:/.exec(line);
+        if (m === null || m[1] !== flat)
+            continue;
+        hits.push(i);
+    }
+    if (hits.length === 0)
+        return { found: false, body: template };
+    lines[hits[0]] = `${flat}: ${formatScalar(value)}`;
+    // Drop the later copies back-to-front so the earlier indices stay valid.
+    for (let i = hits.length - 1; i >= 1; i--)
+        lines.splice(hits[i], 1);
+    return { found: true, body: lines.join('\n') };
+}
 /**
  * Apply every leaf change from `newValues` to `templateBody`. Paths that
  * are not present in the template are appended at the end. Comments are
  * preserved for every key that already exists in the template.
+ *
+ * Idempotent: applying the same values twice yields the same document, so a
+ * second wizard save re-writes the flat block instead of duplicating it.
  */
 export function mergeIntoTemplate(templateBody, newValues) {
     let body = templateBody;
     const appended = [];
     for (const entry of flatten(newValues)) {
-        const before = body;
-        body = replaceScalar(body, entry.path, entry.value);
-        if (body === before) {
-            // Path is not in the template — append a flat key=value at EOF.
-            // Form coverage is asserted by parity test, so this branch only
-            // fires on hand-edited templates.
-            appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
+        const sections = entry.path.slice(0, -1);
+        const leaf = entry.path[entry.path.length - 1];
+        // Presence is asked, never inferred from the write changing the text —
+        // see `findScalarLine`. Writing the value it already holds is a hit.
+        if (findScalarLine(body.split('\n'), sections, leaf) !== -1) {
+            body = replaceScalar(body, entry.path, entry.value);
+            continue;
+        }
+        // Not in the template's nested form. It may still be here as a flat
+        // dotted line this function appended on an earlier pass.
+        const flat = replaceFlatDottedKey(body, entry.path, entry.value);
+        if (flat.found) {
+            body = flat.body;
+            continue;
         }
+        // Genuinely absent — append a flat key=value at EOF. Form coverage is
+        // asserted by parity test, so this branch only fires on hand-edited
+        // templates.
+        appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
     }
     if (appended.length > 0) {
         if (!body.endsWith('\n'))

package/dist/server/schemas/settings.js

@@ -29,7 +29,8 @@ const confidenceBand = z.enum(['off', 'low', 'medium', 'high']);
 const onBlock = z.enum(['stop', 'ask', 'warn']);
 const onBlockFallback = z.enum(['stop', 'warn']);
 const modelAutoSwitch = z.enum(['auto', 'suggest', 'off']);
-const leanProjectionMode = z.enum(['eager-all', 'thin']);
+const leanProjectionMode = z.enum(['eager-all', 'thin', 'delivery']);
+const leanProjectionHost = z.enum(['claude-code', 'cursor', 'cline']);
 const projectionMode = z.enum(['legacy-all', 'scoped']);
 const memoryCadence = z.enum(['auto', 'always', 'never']);
 const projectAudience = z.enum(['self', 'internal', 'client', 'public']);
@@ -46,8 +47,16 @@ export const settingsSchema = z.object({
     rule_loading_tier: ruleLoadingTier.default('balanced').describe('Master switch for which rule tiers load and how cautiously the agent spends tokens. minimal = only the 9 kernel rules (cheapest, fewest guardrails). balanced = kernel + tier-1 (recommended default). full = kernel + tier-1 + tier-2 (most guardrails, highest token cost). custom = roll your own in agents/overrides/. LEGACY: superseded by discipline_profile — when that key is set it wins (mapping: minimal→off, balanced→essential, full→full).'),
     discipline_profile: disciplineProfile.optional().describe('The ONE runtime knob for the discipline-rule tier (successor of rule_loading_tier; council 2026-07-07). off = kernel only (~1x tokens). essential = kernel + the measured lift-carrying rules (~3.3x, keeps the weak-host discipline lift). full = everything (~11.7x, EXPERIMENTAL — residual lift over essential not established). auto = resolve per session against the evidence-gated NULL-lift disable-list in src/config/host-capabilities.yml (measured-null host → off, otherwise → essential). Optional and opt-in until the P1/P2 evidence gates pass (agents/roadmaps/road-to-discipline-profile-tiering.md); absent = legacy rule_loading_tier applies.'),
     lean_projection: z.object({
-        mode: leanProjectionMode.default('eager-all').describe('How the per-tool projector emits the rule layer. eager-all = every rule body inlined into every projection (default, safe). thin = kernel rules full-bodied + non-kernel rules as router-resolved pointers (~45k GPT-tok lighter per session). EXPERIMENTAL: validate with the live A/B before flipping; one-flip revert to eager-all.'),
-    }).default({ mode: 'eager-all' }),
+        mode: leanProjectionMode.default('eager-all').describe('How the per-tool projector emits the rule layer. eager-all = every rule body inlined into every projection (safe; what an ABSENT key still resolves to, per ADR-267 decision point 4). thin = kernel rules full-bodied + non-kernel rules as router-resolved pointers (~45k GPT-tok lighter per session), with no delivery mechanism. delivery = thin stubs PLUS the rule-inject hook concern, which delivers a body back on a trigger match; this is the value the SHIPPED TEMPLATE carries for Claude Code since ADR-267, and the activation charge for it is paid in src/config/hook-token-budget.json (user_prompt_submit slot sum 4,096 -> 16,384).'),
+        hosts: z.array(leanProjectionHost).default(['claude-code']).describe('Which hosts a thinning mode may thin (ADR-267). Absent resolves to [claude-code]. '
+            + 'Only the three hosts with a per-rule rule tree are accepted, and this enum is the '
+            + 'AUTHORING layer: an id outside it is a hard validation FAILURE here and under '
+            + 'validate_agent_settings, never a warning. resolveLeanProjectionHosts is the '
+            + 'READ-TIME backstop for a hand-edited .agent-settings.yml that passed neither, and '
+            + 'THERE the id is dropped with a warning (R2 finding 6 — the two layers answer '
+            + 'differently and neither said so). Every host outside this list receives exactly '
+            + 'what eager-all writes, asserted byte-for-byte by check_host_tree_parity.'),
+    }).default({ mode: 'eager-all', hosts: ['claude-code'] }),
     cost: z.object({
         budgets: z.object({
             daily: z.number().min(0).default(0).describe('Daily USD ceiling across all model calls. The agent warns at 50% / 75% / 90% and either stops or warns at 100% depending on cost.enforcement. Set 0 to disable the daily budget entirely.'),
@@ -92,7 +101,7 @@ export const settingsSchema = z.object({
         access_style: accessStyle.default('getters_setters').describe('How the agent writes Laravel Eloquent property access. getters_setters = explicit getName() / setName() methods (most refactor-safe). get_attribute = $model->getAttribute("name") (verbose but explicit). magic_properties = $model->name (idiomatic but harder to grep).'),
     }),
     chat_history: z.object({
-        enabled: z.boolean().default(true).describe('Persist a structured log of every chat turn to .agent-config/chat-history/ so /chat-history:show, :import, and :learn can replay sessions. Turn off if you never want chat transcripts on disk.'),
+        enabled: z.boolean().default(true).describe('Persist a structured log of every chat turn to agents/runtime/.agent-chat-history (JSONL). Recording only — no command in this package replays a session from the file; it is a record on disk that a human or a later tool can read. Turn off if you never want chat transcripts on disk.'),
         frequency: chatFreq.default('per_turn').describe('How often the chat-history writer flushes to disk. per_turn = after every user / agent exchange (default, lowest data loss on crash). per_phase = at phase boundaries (cheaper I/O). per_tool = after every tool call (highest fidelity, noisiest log).'),
         text_limits: z.object({
             user: z.number().int().min(0).default(0).describe('Per-message character cap for user inputs in the chat-history log. 0 = log verbatim (default). Raise above 0 only if your prompts contain large pasted artefacts you do not want stored.'),
@@ -131,7 +140,21 @@ export const settingsSchema = z.object({
     }),
     design: z.object({
         fidelity_mode: fidelityMode.default('strict').describe('How strictly the agent must follow a user-provided prototype / mockup / design system (consumed by the design-fidelity rule). strict = build 1:1, every visible deviation needs confirmation; structural = structure locked, silent gaps fillable with a stated assumption; hard-floor = any deviation is never autonomous.'),
-    }).default({ fidelity_mode: 'strict' }),
+        approximation: z
+            .object({
+            enabled: z.boolean().default(false).describe('Whether a value INSIDE the configured tolerance may be replaced by the project\'s own token without a per-value confirmation. Ships false. The distance from the artifact\'s value to the nearest project token is computed and REPORTED on every value row regardless of this switch — what it decides is whether the agent may act on it without asking. Turning it on for a whole install is a consumer-facing default flip and is owner-reserved (agents/roadmaps/stubs/road-to-frontend-power-default-flip.md); design.fidelity_mode: hard-floor overrides it to off.'),
+            tolerance: z
+                .object({
+                color: z.number().nullable().default(null).describe('Colour distance below which a value may be reconciled, in OKLab ΔEOK. Ships null, and null means "preserve and report" rather than "reconcile freely". No number is set because none is supported: zero of seven design-to-code benchmarks in the evidence set score token conformance, and a number in a config file — even flagged unmeasured — shapes behavior and acquires the authority of a default. Not an RGB channel delta: RGB distance is not perceptually uniform.'),
+                length: z.number().nullable().default(null).describe('Length distance below which a value may be reconciled, in absolute CSS pixels. Ships null, same reasoning as color. GitHub Primer\'s ±1px spacing widening is recorded as an externally observed candidate in src/scripts/_lib/design_tolerance.ts and is deliberately not the shipped value; max(1px, 2%) was rejected for growing more permissive at large dimensions with no evidence that this is wanted.'),
+            })
+                .default({ color: null, length: null }),
+        })
+            .default({ enabled: false, tolerance: { color: null, length: null } }),
+    }).default({
+        fidelity_mode: 'strict',
+        approximation: { enabled: false, tolerance: { color: null, length: null } },
+    }),
     consistency: z.object({
         cross_source: crossSourceMode.default('on').describe('Consumed by the cross-source-consistency rule. When the agent works from multiple sources (ticket text, an attached image/mockup, the spec, the codebase) it checks them against each other and asks before proceeding on a discrepancy — instead of silently guessing. on (default) = surface every real cross-source contradiction / silent-scope-expansion as one question; auto = surface only high-confidence contradictions, state low-confidence as an assumption; off = no cross-source checking.'),
     }).default({ cross_source: 'on' }),
@@ -229,6 +252,10 @@ export const settingsSchema = z.object({
             api_paths: z.array(z.string()).default([]).describe('Optional glob list that makes API-endpoint detection explicit instead of heuristic (e.g. ["app/Http/Controllers/Api/**", "src/pages/api/**"]). Empty (default) = a light path/extension heuristic that fails open.'),
         }),
     }),
+    continuity: z.object({
+        auto_record: z.enum(['on', 'off']).default('on').describe('Deterministic continuity-record writer at session end (road-to-continuity-writer-activation Phase 1). on (default since 2026-09-10) = the session-eol concern writes the continuity_record capsule variant on Stop for a substantive session that has claimed a roadmap; every field is computed from on-disk state, with no model spend and no subprocess. off = no automatic record, and only the explicit agent-config session:recycle writes one. The default flipped once the parity evidence landed, so the normal path carries an automatic writer rather than a remembered command; session:recycle is retained because the automatic writer skips a session that claimed no roadmap and omits the git-status anchors.'),
+        run_checkpoints: z.enum(['on', 'off']).default('on').describe('Deterministic run-checkpoint production at session end (road-to-continuity-writer-activation Phase 1.4). on (default) = a session above the recycle threshold and inside a running roadmap contract leaves agents/runtime/state/checkpoints/<run>.json, so a killed run resumes from a derived checkpoint rather than from bookkeeping. off = no checkpoint; continuity writing, the recycle advisory and the context-fill surface are unaffected. Default ON because it is the behavior the tree already had — the switch exists to make the three session-end handlers independently disableable, not to change what ships.'),
+    }),
     memory: z.object({
         cadence: memoryCadence.default('always').describe('Cadence of the 🧠 memory-visibility line after a memory-consulting step. always (default) = show whenever a memory type was asked; auto = show only when 3+ types were consulted (less noise); never = suppress. Distinct from rule_loading_tier — owns its own key since the 2026-06-01 untangle.'),
         review_threshold: z.number().int().min(0).default(10).describe('Maximum number of memory entries /memory:load surfaces inline before falling back to a summary view. Default 10 keeps the chat readable. Raise to see more candidates, lower to keep the context tight.'),

package/dist/shared/settingsSurface.js

@@ -77,7 +77,12 @@ export function computeSurfaceDelta(oldS, newS) {
             continue;
         }
         const o = oldS.entries[key];
-        if (o.type !== n.type) {
+        // `sameJson`, not `!==`: `type` is an array for a nullable key, and two
+        // structurally equal arrays are never `===`. Left as a strict compare
+        // it reported `type_changed` on EVERY version bump for every nullable
+        // key, forever — caught by the identical-surface test the moment the
+        // first one shipped (`design.approximation.tolerance.*`).
+        if (!sameJson(o.type, n.type)) {
             changes.push({ key, kind: 'type_changed', old: o, new: n });
         }
         if (!sameJson(o.default, n.default)) {

package/docs/MIGRATION.md

@@ -42,6 +42,62 @@ reason, which no arithmetic can.
 or that promises a future breaking removal, gets a row here in the same commit
 that makes the promise. A promise with no row is not tracked and will be missed.
 
+## 14.22.x — the code-graph engine gets readers, and the MCP install hint changes
+
+💡 advisory · 🔄 automatic — **one exception, below.**
+
+The 14.21.x entry above shipped the engine to consumers. This one ships the
+things that read it (`road-to-a-graph-that-is-shipped`, Phases 3 and 4).
+
+### Additive — nothing to do
+
+- **Four new `code-graph` subcommands**, all answering questions about a DIFF
+  rather than a symbol: `impact --diff <rev>`, `tests-for <symbol>`,
+  `untested --diff <rev>`, `dead`. Each prints the resolution mechanisms it
+  accepted, the mechanisms it refused, and the graph's three-state staleness.
+  No existing subcommand changed, and no new top-level verb was added.
+- **Five new MCP tools** on the existing stdio server — `graph_impact`,
+  `graph_tests_for`, `graph_dead`, `graph_query`, `graph_path` — taking the
+  catalogue from 31 tools to 36. Four are read-only; `graph_impact` runs
+  `git diff --name-only` to resolve its rev and declares `side_effect: shell`
+  for that reason.
+- **A new `tests` edge relation**, derived in the build pass from a test file's
+  imports. `SCHEMA_VERSION` 3 → 4 and `GRAPH_STORE_VERSION` 3 → 4, so an
+  existing cache and its SQLite twin are refused and rebuilt on the next
+  `code-graph build`. The cache is derived and disposable
+  (ADR-129) — there is nothing to migrate, and a rebuild takes seconds.
+
+### The one thing to check — `dead` refuses by default
+
+`agent-config code-graph dead` exits **1** with an empty list unless you either
+supply an entry-point list (`--entry-points <file>`) or accept the gap
+(`--accept-missing-exports`). That is deliberate: this engine records no
+exportedness, so without a supplied list an exported-but-not-yet-imported public
+symbol is indistinguishable from a dead one, and a confident false "dead" invites
+a deletion the graph cannot justify. If you wire `dead` into a script, handle the
+refusal — an exit 1 here is not a crash, and treating it as an empty dead list
+is the false negative the refusal exists to prevent.
+
+### One consumer-visible string changed
+
+`install_hint_stdio` in the published MCP tool catalogue was
+`npx -y @event4u/agent-config mcp-server` and is now **`agent-config mcp-server`**
+— the installed-binary form the setup docs already lead with. It resolves no
+dist-tag, so the server you run is the version you installed rather than
+whatever the registry served most recently. **It assumes `agent-config` is on
+PATH.** If you read that field programmatically and rely on `npx`, keep using
+the pinned form from [`mcp-server.md`](mcp-server.md) —
+`npx -y @event4u/agent-config@<version> mcp-server` — which is unchanged and
+still the documented client configuration.
+
+### Standing context cost
+
+Registering the stdio MCP server now costs **4,876 tokens** of standing context
+per session, up from 3,886 — the five graph tools measure 993 between them. It
+remains roughly 4x under the ~20,000-token Tool Search deferral threshold at a
+200k window, so the surface still loads upfront. Measured, with the prior reading
+kept: `agents/evidence/metrics/mcp-tool-standing-cost.jsonl`.
+
 ## 14.21.x — the code-graph engine ships to consumers
 
 💡 advisory · 🔄 automatic — no action required.