@event4u/agent-config 9.22.0 → 9.23.0

package/src/scripts/lint_token_budget_discipline.ts

@@ -10,6 +10,27 @@
  * 2. JUSTIFICATION — every `rich`-tagged skill carries a
  *    `## Why this skill is rich` section explaining the irreducible
  *    complexity.
+ * 3. SIZE — a `rich`-tagged skill stays under the declared ceiling
+ *    (3,500 tokens, ADR-217). Measured with the exact BPE tokenizer
+ *    where `js-tiktoken` resolves and with the character proxy where it does
+ *    not; the gate says which. A proxy measurement sitting within its own
+ *    error margin of the ceiling is reported UNRESOLVED rather than silently
+ *    classified — the proxy runs ~5 % off per file IN EITHER DIRECTION, and a
+ *    reading whose error band straddles the ceiling has not decided anything.
+ *
+ * The band was documentation until ADR-217: the ceiling described no artifact
+ * that existed (measured max 3,331 of a declared 5,000), so nothing ever
+ * noticed that its top half was unused. An unused permission costs nothing
+ * until someone uses it.
+ *
+ * The band's FLOOR is documented and deliberately NOT gated. Running the check
+ * once found `accessibility-auditor` at 1,931 tokens — under the 2,000 floor
+ * while legitimately holding the class, because `rich` buys exemption from
+ * condensation and that is a claim about what compression would LOSE, not
+ * about how large the file is. The published measurement supplies a
+ * degradation threshold, which is a ceiling; nothing measures a minimum. A
+ * floor gate would have forced a WCAG-criteria skill out of the exemption on a
+ * number with no evidence behind it.
  *
  * Additionally, any `token_budget_class` value outside
  * `lean | standard | rich` is a finding (schema drift).
@@ -20,6 +41,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { gpt_tokens } from './_lib/token_count.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -32,6 +55,17 @@ export const VALID_CLASSES = ['lean', 'standard', 'rich'] as const;
 
 export const RICH_SECTION_HEADING = '## Why this skill is rich';
 
+/** Declared band for the rich class (ADR-217). Floor unchanged; ceiling 5,000 → 3,500. */
+export const RICH_MIN_TOKENS = 2000;
+export const RICH_MAX_TOKENS = 3500;
+
+/**
+ * Worst-case per-file error of the character proxy, measured over the four
+ * rich artifacts on 2026-08-06 (−5.3 % on the largest). A proxy measurement
+ * inside this margin of a boundary is not a verdict.
+ */
+export const PROXY_ERROR_MARGIN = 0.06;
+
 export interface Finding {
     /** repo-relative path */
     file: string;
@@ -44,6 +78,45 @@ export interface ScanResult {
     scanned: number;
     /** Skills declaring token_budget_class: rich. */
     richCount: number;
+    /** Per-rich-skill size measurements, for the report line. */
+    sizes: RichSize[];
+    /** True when every size came from the exact BPE tokenizer. */
+    exactThroughout: boolean;
+}
+
+export interface RichSize {
+    file: string;
+    tokens: number;
+    exact: boolean;
+    /** Set when a proxy measurement lands inside its own error margin of a boundary. */
+    unresolved: boolean;
+}
+
+/**
+ * Measure one artifact, exact where the tokenizer resolved.
+ *
+ * Split out so the size rule is testable without a filesystem: the boundary
+ * cases that matter (exactly at the cap, one token over, a proxy reading a
+ * hair under) are the ones a fixture tree makes awkward and a function call
+ * makes trivial.
+ */
+export function classify_size(tokens: number, exact: boolean): { over: boolean; unresolved: boolean } {
+    if (exact) {
+        return { over: tokens > RICH_MAX_TOKENS, unresolved: false };
+    }
+    // A proxy reading is a band around the truth, and the band is SYMMETRIC.
+    // The first version applied the margin upward only — guarding a proxy that
+    // reads low — while the measured error on the largest artifact runs the
+    // other way: 3,518 by proxy against 3,331 exact, reading 5.3 % HIGH. That
+    // version therefore hard-failed the one artifact ADR-217 rules in-band,
+    // on any machine without the tokenizer (`js-tiktoken` is a devDependency).
+    //
+    // So: a proxy verdict counts only when the WHOLE band falls on one side of
+    // the ceiling. A band straddling it is `unresolved` — which is a finding,
+    // but one that says "measure properly" rather than "this is too big".
+    const margin = Math.ceil(tokens * PROXY_ERROR_MARGIN);
+    const straddles = tokens - margin <= RICH_MAX_TOKENS && tokens + margin > RICH_MAX_TOKENS;
+    return { over: !straddles && tokens - margin > RICH_MAX_TOKENS, unresolved: straddles };
 }
 
 /** `token_budget_class` value from a SKILL.md's YAML frontmatter, or null. */
@@ -63,6 +136,7 @@ export function frontmatter_class(content: string): string | null {
 /** Scan one skills root (directory of `<skill>/SKILL.md`). */
 export function scan_skills(skillsRoot: string): ScanResult {
     const findings: Finding[] = [];
+    const sizes: RichSize[] = [];
     let scanned = 0;
     let richCount = 0;
     const entries = fs
@@ -97,6 +171,28 @@ export function scan_skills(skillsRoot: string): ScanResult {
                     message: `rich-tagged skill missing the '${RICH_SECTION_HEADING}' justification section`,
                 });
             }
+            const measured = gpt_tokens(content);
+            const verdict = classify_size(measured.tokens, measured.exact);
+            sizes.push({ file: rel, tokens: measured.tokens, exact: measured.exact, unresolved: verdict.unresolved });
+            const how = measured.exact ? 'exact BPE' : 'chars/4 proxy';
+            if (verdict.over) {
+                findings.push({
+                    file: rel,
+                    message:
+                        `rich-class size band exceeded: ${String(measured.tokens)} tokens (${how}) > ` +
+                        `${String(RICH_MAX_TOKENS)} (ADR-217). Split by responsibility, or argue the ` +
+                        'ceiling in a decision record — not in this file.',
+                });
+            } else if (verdict.unresolved) {
+                findings.push({
+                    file: rel,
+                    message:
+                        `rich-class size UNRESOLVED: ${String(measured.tokens)} tokens (${how}) sits within the ` +
+                        `${String(PROXY_ERROR_MARGIN * 100)} % proxy margin of a band boundary. Install the exact ` +
+                        'tokenizer (js-tiktoken is a declared dependency) and re-run — a proxy reading this ' +
+                        'close has not decided anything.',
+                });
+            }
         }
     }
     if (scanned > 0 && richCount > scanned * RICH_RATIO_CAP) {
@@ -108,7 +204,7 @@ export function scan_skills(skillsRoot: string): ScanResult {
                 `max ${String(Math.floor(scanned * RICH_RATIO_CAP))})`,
         });
     }
-    return { findings, scanned, richCount };
+    return { findings, scanned, richCount, sizes, exactThroughout: sizes.every((s) => s.exact) };
 }
 
 export function main(argv?: readonly string[]): number {
@@ -134,9 +230,21 @@ export function main(argv?: readonly string[]): number {
         process.stdout.write(`❌  ${f.file}  ${f.message}\n`);
     }
     if (result.findings.length === 0 && !quiet) {
+        const how = result.exactThroughout ? 'exact BPE' : 'chars/4 proxy (js-tiktoken did not resolve)';
+        const largest = result.sizes.reduce((max, s) => (s.tokens > max ? s.tokens : max), 0);
         process.stdout.write(
             `✅  token-budget discipline: ${String(result.richCount)} rich of ${String(result.scanned)} skills within the ${String(RICH_RATIO_CAP * 100)} % cap; every rich skill justifies itself\n`,
         );
+        // Publish the sizes on the GREEN path too. A band nobody sees the
+        // numbers for is how this one spent months describing no artifact
+        // that existed.
+        process.stdout.write(
+            `    size ceiling ${String(RICH_MAX_TOKENS)} (ADR-217; the ${String(RICH_MIN_TOKENS)} floor is documented, not gated), ` +
+                `measured ${how}; largest ${String(largest)}\n`,
+        );
+        for (const s of result.sizes) {
+            process.stdout.write(`    ${String(s.tokens).padStart(5)}  ${s.file}\n`);
+        }
     }
     // gate-coverage contract (src/config/gate-coverage.yml): files inspected.
     process.stdout.write(`scanned: ${String(result.scanned)}\n`);

package/src/scripts/report_imperative_density.ts

@@ -0,0 +1,229 @@
+#!/usr/bin/env tsx
+/**
+ * report_imperative_density.ts — an advisory number whose direction is unknown.
+ *
+ * Prints the ratio of imperative-marker lines to prose lines across the
+ * authored rules and skills. **It gates on nothing, and it must not acquire a
+ * threshold without the measurement that would justify one.**
+ *
+ * WHY THIS IS NOT A GATE, AND MUST NOT BECOME ONE
+ * -----------------------------------------------
+ * Three external sources disagree about which direction is better. One asserts
+ * reasoning-based phrasing outperforms rigid directives. One ships a metric
+ * that scores instruction files HIGHER for imperative-marker density — the
+ * opposite ranking from the same observation. A third sits between them and
+ * supplies the only part all three can live with: a rule the agent consistently
+ * fails to follow needs structural enforcement or deletion, not a louder rule.
+ *
+ * This suite's house style sits at the imperative end and has no measurement
+ * either way. A gate would prejudge exactly the question the sweep left open
+ * (`skill-ecosystem-sweep-2026-08.md` § R2). An advisory number is the input a
+ * future decision needs; a target is the thing that would corrupt it, because
+ * the moment a number is optimised it stops measuring what it measured.
+ *
+ * So: no exit-2, no baseline entry, no `gate-coverage.yml` row, and the header
+ * of every run says the direction is unsettled. Read it as a description, not
+ * as a score.
+ *
+ * Exit: 0 always (except a usage/IO error, which is 1). That is deliberate.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const RULES_ROOT = 'src/rules';
+export const SKILLS_ROOT = 'src/skills';
+
+/**
+ * Lines counted as imperative markers.
+ *
+ * Deliberately narrow and stated: an all-caps directive line, a bullet opening
+ * with a modal or a bare imperative verb, and the fenced Iron-Law blocks this
+ * suite uses. A broader net would inflate the number without making it mean
+ * more, and the number's meaning is already the open question.
+ */
+const IMPERATIVE_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
+    ['all-caps directive', /^[^a-z]*\b(NEVER|ALWAYS|MUST|DO NOT|STOP|REFUSE|FORBIDDEN)\b[^a-z]*$/],
+    ['inline modal', /\b(MUST|NEVER|ALWAYS|DO NOT|SHALL)\b/],
+    ['imperative bullet', /^\s*[-*]\s+(Always|Never|Do not|Don't|Use|Run|Check|Verify|Refuse|Stop|Add|Remove|Keep|Prefer|Avoid)\b/],
+];
+
+export interface FileDensity {
+    file: string;
+    prose: number;
+    imperative: number;
+    ratio: number;
+}
+
+export interface DensityReport {
+    files: FileDensity[];
+    totalProse: number;
+    totalImperative: number;
+    /** Ratio over the whole corpus, or null when nothing was counted. */
+    ratio: number | null;
+}
+
+/**
+ * Lines that carry prose. Fenced code, frontmatter, table rows, and blanks are
+ * excluded — counting them would make the ratio a function of how much YAML a
+ * file happens to carry.
+ */
+export function proseLines(text: string): string[] {
+    const lines = text.split('\n');
+
+    // Frontmatter only when the opening `---` actually CLOSES. A file whose
+    // first line is a horizontal rule used to swallow everything to the next
+    // `---`, and a file with an unterminated opener swallowed all of it.
+    let start = 0;
+    if (lines[0]?.trim() === '---') {
+        const close = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+        // …and only when the block LOOKS like YAML. `---` opening a document
+        // that then reads as prose is a horizontal rule, and treating it as
+        // frontmatter silently ate everything up to the next one.
+        const looksYaml = close > 0 && lines.slice(1, close).some((l) => /^\s*[\w.-]+:\s/.test(l));
+        if (close !== -1 && looksYaml) start = close + 1;
+    }
+
+    // Fences are matched BY CHARACTER, so `~~~` cannot close a ```-opened
+    // block, and an opener that never closes is treated as though it never
+    // opened — dropping the rest of a file silently is worse than counting a
+    // few code lines as prose, because the denominator is the thing this
+    // report publishes.
+    const openers: Array<{ index: number; marker: string }> = [];
+    const fenced = new Set<number>();
+    let open: { index: number; marker: string } | null = null;
+    for (let i = start; i < lines.length; i++) {
+        const m = /^\s*(`{3,}|~{3,})/.exec(lines[i] ?? '');
+        if (m === null) continue;
+        const marker = (m[1] as string)[0] as string;
+        if (open === null) {
+            open = { index: i, marker };
+            openers.push(open);
+        } else if (open.marker === marker) {
+            for (let j = open.index; j <= i; j++) fenced.add(j);
+            open = null;
+        }
+    }
+
+    const out: string[] = [];
+    for (let i = start; i < lines.length; i++) {
+        if (fenced.has(i)) continue;
+        const line = (lines[i] ?? '').trimEnd();
+        if (line.trim() === '') continue;
+        if (/^\s*\|/.test(line)) continue;
+        out.push(line);
+    }
+    return out;
+}
+
+export function countImperative(lines: readonly string[]): number {
+    let n = 0;
+    for (const line of lines) {
+        if (IMPERATIVE_PATTERNS.some(([, re]) => re.test(line))) n += 1;
+    }
+    return n;
+}
+
+function _walkMarkdown(dir: string): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const out: string[] = [];
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) out.push(..._walkMarkdown(full));
+        else if (e.name.endsWith('.md')) out.push(full);
+    }
+    return out.sort();
+}
+
+export function buildReport(root: string): DensityReport {
+    const files: FileDensity[] = [];
+    let totalProse = 0;
+    let totalImperative = 0;
+    for (const dir of [RULES_ROOT, SKILLS_ROOT]) {
+        for (const abs of _walkMarkdown(path.join(root, dir))) {
+            const lines = proseLines(fs.readFileSync(abs, 'utf-8'));
+            if (lines.length === 0) continue;
+            const imperative = countImperative(lines);
+            totalProse += lines.length;
+            totalImperative += imperative;
+            files.push({
+                file: path.relative(root, abs).split(path.sep).join('/'),
+                prose: lines.length,
+                imperative,
+                ratio: imperative / lines.length,
+            });
+        }
+    }
+    return {
+        files,
+        totalProse,
+        totalImperative,
+        ratio: totalProse === 0 ? null : totalImperative / totalProse,
+    };
+}
+
+const HEADER = [
+    'imperative-density report — ADVISORY, and the direction of this number is UNSETTLED.',
+    '',
+    'Three sources disagree on whether higher is better. One prefers reasoning-based',
+    'phrasing; one scores instruction files higher for imperative density; the third',
+    'declines the question and supplies the operational fork instead. This suite has',
+    'no measurement either way — see skill-ecosystem-sweep-2026-08.md § R2.',
+    '',
+    'Do not read this as a score, and do not optimise it. It gates nothing on purpose:',
+    'a threshold here would prejudge the open question, and a number that gets',
+    'optimised stops measuring what it measured.',
+].join('\n');
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const top = argv.includes('--top') ? Number.parseInt(argv[argv.indexOf('--top') + 1] ?? '10', 10) : 10;
+    const json = argv.includes('--json');
+
+    const report = buildReport(REPO_ROOT);
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ note: 'advisory; direction unsettled (§ R2)', ...report }, null, 2)}\n`);
+        return 0;
+    }
+
+    process.stdout.write(`${HEADER}\n\n`);
+    if (report.ratio === null) {
+        // `renderShare`'s rule, applied by hand: an empty denominator renders as
+        // "not measured", never as 0.0 %.
+        process.stdout.write('corpus ratio: not measured — zero prose lines found under the scanned roots\n');
+        process.stdout.write(`files: ${String(report.files.length)}\n`);
+        return 0;
+    }
+    process.stdout.write(
+        `corpus ratio: ${(report.ratio * 100).toFixed(1)} % ` +
+            `(${String(report.totalImperative)} imperative lines of ${String(report.totalProse)} prose lines, ` +
+            `${String(report.files.length)} files)\n\n`,
+    );
+    const ranked = [...report.files].sort((a, b) => b.ratio - a.ratio).slice(0, top);
+    process.stdout.write(`densest ${String(ranked.length)}:\n`);
+    for (const f of ranked) {
+        process.stdout.write(
+            `  ${(f.ratio * 100).toFixed(1).padStart(5)} %  ${String(f.imperative).padStart(4)}/${String(f.prose).padEnd(5)}  ${f.file}\n`,
+        );
+    }
+    // `files:` and not `scanned:` on purpose. The latter is the machine-read
+    // coverage signal `check_gate_coverage` parses, and emitting it would
+    // enlist an advisory report as a gate with a coverage floor — the exact
+    // promotion this report must not undergo.
+    process.stdout.write(`\nfiles: ${String(report.files.length)}\n`);
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}
+
+export { REPO_ROOT };

package/src/scripts/verify_physical_move.ts

@@ -179,7 +179,16 @@ export function _diff_tree(
 
 export function _diff_manifest(before: Obj | null, after: Obj | null): string[] {
     if (before === null && after === null) {
-        return [];
+        // Equality without validity — the literal `diff a b` where NEITHER side
+        // exists and the answer comes back "equal". An empty issue list means
+        // clean to every caller, so both-absent used to certify a move that was
+        // never compared. Two absent sides are the absence of a comparison, not
+        // the presence of a match. (Audited estate-wide in
+        // `docs/guidelines/agent-infra/false-green.md § The audited sync/parity gates`.)
+        return [
+            '  manifest: BOTH the pre-move snapshot and the post-move manifest are missing — ' +
+                'nothing was compared, so nothing is verified',
+        ];
     }
     if (before === null) {
         return ['  manifest: pre-move snapshot missing'];

package/src/server/io/yamlIO.ts

@@ -0,0 +1,173 @@
+/**
+ * YAML round-trip helpers for `.agent-settings.yml`.
+ *
+ * Important contract: the template ships with comments that explain
+ * every key — we MUST NOT discard them when the wizard writes back.
+ * `js-yaml.dump` cannot preserve comments, so we use a key-level
+ * replace strategy that mirrors `scripts/install.py::_replace_template_value`:
+ * scan the rendered template line-by-line, replace only the scalar
+ * value at each dotted path, leave comments and indentation alone.
+ *
+ * For arrays and nested objects we fall back to re-serializing the
+ * subtree (`js-yaml.dump`) because line-level replace can't safely
+ * splice multi-line blocks. The form renderer keeps depth ≤ 2, so
+ * the subtree footprint is small.
+ */
+
+import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
+
+export interface ReadResult {
+    values: Record<string, unknown>;
+    raw: string;
+}
+
+export function parseYaml(raw: string): Record<string, unknown> {
+    const parsed = yamlLoad(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('settings file did not parse to an object');
+    }
+    return parsed as Record<string, unknown>;
+}
+
+function formatScalar(value: unknown): string {
+    if (typeof value === 'string') {
+        // js-yaml safely quotes strings that need it; trim the trailing newline.
+        return yamlDump(value, { lineWidth: -1 }).replace(/\n$/, '').trim();
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+    if (value === null || value === undefined) return '""';
+    // Arrays / nested objects: dump inline. Form keeps depth ≤ 2 so this is rare.
+    return yamlDump(value, { lineWidth: -1, flowLevel: 0 }).replace(/\n$/, '').trim();
+}
+
+interface FlatEntry {
+    path: string[];
+    value: unknown;
+}
+
+function flatten(value: unknown, prefix: string[] = []): FlatEntry[] {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return [{ path: prefix, value }];
+    }
+    const entries: FlatEntry[] = [];
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        entries.push(...flatten(v, [...prefix, k]));
+    }
+    return entries;
+}
+
+/**
+ * Replace the scalar at `dottedPath` in `template` with `value`.
+ * Comments and unrelated keys are preserved verbatim. Returns the
+ * template unchanged when the path cannot be located (matches the
+ * Python installer's tolerant behaviour).
+ */
+export function replaceScalar(template: string, dottedPath: string[], value: unknown): string {
+    if (dottedPath.length === 0) return template;
+    const sections = dottedPath.slice(0, -1);
+    const key = dottedPath[dottedPath.length - 1];
+    const targetIndent = '  '.repeat(sections.length);
+
+    const lines = template.split('\n');
+    const currentPath: (string | null)[] = new Array<string | null>(sections.length).fill(null);
+    const formatted = formatScalar(value);
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined) continue;
+        const stripped = line.trim();
+        if (stripped === '' || stripped.startsWith('#')) continue;
+        const indentLen = line.length - line.trimStart().length;
+        if (indentLen % 2 !== 0) continue;
+        const level = indentLen / 2;
+        if (level > sections.length) continue;
+
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(stripped);
+        if (!m) continue;
+        const lineKey = m[1];
+        if (lineKey === undefined) continue;
+        if (level < sections.length) {
+            if (lineKey === sections[level]) {
+                currentPath[level] = lineKey;
+                for (let j = level + 1; j < currentPath.length; j++) currentPath[j] = null;
+            } else if (currentPath[level] !== null && lineKey !== currentPath[level]) {
+                currentPath[level] = null;
+            }
+            continue;
+        }
+        // level === sections.length → leaf candidate
+        const parentsMatch = sections.every((s, idx) => currentPath[idx] === s);
+        if (!parentsMatch) continue;
+        if (lineKey !== key) continue;
+        lines[i] = `${targetIndent}${key}: ${formatted}`;
+        return lines.join('\n');
+    }
+    return template;
+}
+
+/**
+ * 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.
+ */
+export function mergeIntoTemplate(templateBody: string, newValues: Record<string, unknown>): string {
+    let body = templateBody;
+    const appended: string[] = [];
+    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)}`);
+        }
+    }
+    if (appended.length > 0) {
+        if (!body.endsWith('\n')) body += '\n';
+        body += `\n# Wizard-added keys (no template entry)\n${appended.join('\n')}\n`;
+    }
+    return body;
+}
+
+export function diffValues(
+    before: Record<string, unknown>,
+    after: Record<string, unknown>,
+): Array<{ path: string; from: unknown; to: unknown }> {
+    const out: Array<{ path: string; from: unknown; to: unknown }> = [];
+    const bMap = new Map(flatten(before).map((e) => [e.path.join('.'), e.value]));
+    const aMap = new Map(flatten(after).map((e) => [e.path.join('.'), e.value]));
+    const paths = new Set<string>([...bMap.keys(), ...aMap.keys()]);
+    for (const path of paths) {
+        const fromV = bMap.get(path);
+        const toV = aMap.get(path);
+        if (JSON.stringify(fromV) !== JSON.stringify(toV)) out.push({ path, from: fromV, to: toV });
+    }
+    return out;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Recursive dict merge — overlay wins, nested dicts are merged, lists
+ * are replaced (not concatenated). Mirrors `scripts/install.py::deep_merge`
+ * so the Python installer and the Fastify server produce the same
+ * three-layer settings tree (`defaults < global < project`).
+ */
+export function deepMerge(
+    base: Record<string, unknown>,
+    overlay: Record<string, unknown>,
+): Record<string, unknown> {
+    const result: Record<string, unknown> = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const existing = result[key];
+        if (isPlainObject(existing) && isPlainObject(value)) {
+            result[key] = deepMerge(existing, value);
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}