@event4u/agent-config 16.3.0 → 16.5.0

package/dist/scripts/_lib/svg_urls.js

@@ -0,0 +1,67 @@
+/**
+ * How a browser reads the URLs and names in an SVG, for the safety rules in
+ * `svg_rules.ts`: references decoded, controls stripped, CSS escapes resolved,
+ * and an element prefix stripped only where it is bound to the SVG namespace.
+ * Its own module so `svg_rules.ts` stays under the source-size ceiling.
+ */
+/** Prefixes the document binds to the SVG namespace (`xmlns:svg="…/2000/svg"`). */
+export function svgPrefixes(content) {
+    const out = new Set();
+    const re = /xmlns:([\w.-]+)\s*=\s*["']http:\/\/www\.w3\.org\/2000\/svg["']/gi;
+    let m;
+    while ((m = re.exec(content)) !== null)
+        out.add((m[1] ?? '').toLowerCase());
+    return out;
+}
+/** The SVG local name: `svg:script` is a `script` where `svg` is bound to SVG; `foo:script` is not. */
+export function localName(name, prefixes) {
+    const colon = name.indexOf(':');
+    return colon !== -1 && prefixes.has(name.slice(0, colon)) ? name.slice(colon + 1) : name;
+}
+/** Attributes read from the raw tag, unquoted values included — HTML parses those. */
+export function rawAttrs(raw) {
+    const out = {};
+    const re = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"'`=]+))/g;
+    let m;
+    while ((m = re.exec(raw)) !== null)
+        out[(m[1] ?? '').toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? '';
+    return out;
+}
+/** Attributes whose value is followed as a URL. */
+export const URL_ATTRS = new Set(['href', 'xlink:href', 'src']);
+/** A URL that executes or opens a document when followed. */
+export const isActiveUrl = (raw) => /^(javascript:|data:text\/html)/i.test(resolvedUrl(raw));
+const NAMED_URL_ENTITIES = {
+    colon: ':', sol: '/', tab: '\t', newline: '\n', period: '.', lpar: '(', rpar: ')', amp: '&',
+};
+/**
+ * The URL a browser would actually resolve from an attribute value: character
+ * references decoded, leading/trailing C0 controls and spaces stripped, tab and
+ * newline removed anywhere. The trailing `;` of a reference is optional on
+ * purpose: an `.svg` parsed as XML needs it, but the same graphic inlined in an
+ * HTML host is parsed by the HTML tokenizer, which decodes `&#106avascript:`
+ * too — over-reading XML here costs precision, under-reading HTML costs a miss.
+ * The raw value is attacker-chosen, so a scheme test
+ * against it is a test of one spelling — ` https:`, `ht\ttps:`, `javascript:`
+ * all load, and all passed.
+ */
+export function resolvedUrl(raw) {
+    const decoded = raw.replace(/&(?:#x([0-9a-f]+)|#(\d+)|([a-z]+));?/gi, (m, hex, dec, name) => {
+        const cp = hex ? parseInt(hex, 16) : dec ? parseInt(dec, 10) : NaN;
+        if (!Number.isNaN(cp))
+            return cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+        return NAMED_URL_ENTITIES[name.toLowerCase()] ?? m;
+    });
+    return decoded.replace(/^[\u0000- ]+|[\u0000- ]+$/g, '').replace(/[\t\n\r]/g, '');
+}
+/** CSS escapes decoded: `\\68 ` and `\\h` both read `h`. */
+export function cssUnescape(raw) {
+    return raw.replace(/\\([0-9a-f]{1,6})\s?|\\(.)/gi, (m, hex, ch) => {
+        if (hex) {
+            const cp = parseInt(hex, 16);
+            return cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+        }
+        return ch;
+    });
+}
+//# sourceMappingURL=svg_urls.js.map

package/dist/scripts/_lib/thin_rules.js

@@ -255,13 +255,90 @@ function _title(s) {
  * 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.
+ * fails to recognise reads as a complete rule body. Two gates had done exactly
+ * that until step 2.1 of `road-to-a-thinned-layer-measured-in-one-unit`; both
+ * import this now.
+ *
+ * SHORTENED 2026-10-06 from 47 characters to 27 (step 2.2). It is paid once per
+ * stub and there were 89 stubs on the measured layer, so the sentence cost
+ * 4,183 characters of a 97,496-character standing total; at 27 it costs 2,403,
+ * a saving of 1,780 = 20 x 89.
+ *
+ * WHAT THE SHORTENING WAS NOT ALLOWED TO DO: drop the instruction. This is the
+ * only standing text in the whole layer that says what a stub is FOR — "load
+ * the body" occurs in no kernel rule and in neither root instruction file — so
+ * a bare token like `> thin` would have saved more and left nothing that could
+ * be followed. The decision record (D2, K6) rejected that explicitly: nothing
+ * in this repository can check whether an instruction nobody states is still
+ * obeyed.
+ *
+ * WHY IT MUST STAY LONG ENOUGH TO BE UNIQUE: {@link is_thin_entry} is a
+ * substring test over the whole file, so a marker short or generic enough to
+ * occur inside ordinary rule prose would make that rule read as a stub — and
+ * nine rule files carry blockquote lines. `thin_marker_unique_in_corpus.test.ts`
+ * runs the constant against every rule body in `src/rules/` and against every
+ * entry `build_thin` emits, in both directions, which is the check that bounds
+ * any further shortening.
  */
-export const THIN_ENTRY_MARKER = '> Routed rule — load the body on trigger-match.';
+export const THIN_ENTRY_MARKER = '> Load the body on a 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);
 }
+/**
+ * What introduces a stub's body pointer. One writer, one reader.
+ *
+ * A BARE PATH SINCE 2026-10-06 (step 2.3 of
+ * `road-to-a-thinned-layer-measured-in-one-unit`). The pointer used to be a
+ * markdown link, ``Body: [`<id>`](<prefix><id>.md)``, whose link TEXT repeated
+ * the rule id the target already ends in. That cost `6 + len(id)` per stub over
+ * the bare form — 2,359 characters across the 89 stubs of the measured layer,
+ * 534 of it pure syntax and the rest the id written a second time.
+ *
+ * Nothing followed the link as a link. Under `delivery` the hook loads the body
+ * and never reads the pointer at all; under `thin` an agent reads the path. A
+ * markdown link renders in neither case, so the syntax bought rendering nobody
+ * was doing.
+ */
+export const THIN_BODY_POINTER_PREFIX = 'Body: ';
+/**
+ * The pointer, as the WRITER emits it — exported so a detector cannot re-spell
+ * it, which is the same drift {@link THIN_ENTRY_MARKER} documents one screen up
+ * and which two gates had already committed there.
+ *
+ * WHAT IT CAPTURES is the whole tail of the line from `Body: ` to its end, and
+ * that is the intended semantic rather than an accident of greediness: the
+ * writer emits the pointer LAST on its line, so the tail IS the path. A review
+ * round proposed a lazy `(.+?\.md)` to stop at the first `.md`; measured, it
+ * changes nothing, because `\s*$` forces the match to reach end of line either
+ * way and a lazy quantifier simply backtracks forward to the same place. The
+ * greedy form is kept and the property is pinned by a test, so the next reader
+ * meets the measurement instead of repeating the proposal.
+ *
+ * ANCHORED TO END OF LINE, NOT `\S+`. The pointer is the last thing on its
+ * line, and a package root may contain spaces; `\S+` would silently stop at the
+ * first one and report a well-formed pointer as missing.
+ *
+ * COMPOSED FROM {@link THIN_BODY_POINTER_PREFIX} rather than re-spelling it.
+ * The constant exists so a reader cannot hold its own copy, and a pattern six
+ * lines below it holding a literal `Body: ` would have broken that invariant in
+ * the file that states it.
+ */
+export const THIN_BODY_POINTER_RE = (() => {
+    const lit = THIN_BODY_POINTER_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // THE LAST PREFIX ON THE LINE, NOT THE FIRST. `thin_entry` puts the rule's
+    // own `description` on the SAME line ahead of the pointer, so a description
+    // containing the literal `Body: ` used to start the match inside the
+    // description and capture it as part of the path — `has_body_pointer` stayed
+    // true while the extraction was wrong, which is a wrong assertion rather
+    // than a visible failure. Forbidding a second prefix inside the capture
+    // makes the first viable start the last occurrence, which is the pointer.
+    return new RegExp(`${lit}((?:(?!${lit}).)+\\.md)\\s*$`, 'm');
+})();
+/** Does this entry carry a body pointer the writer would recognise? */
+export function has_body_pointer(text) {
+    return THIN_BODY_POINTER_RE.test(text);
+}
 /**
  * Where a stub tells a reader the body actually is.
  *
@@ -318,7 +395,7 @@ export function thin_entry(rule_id, text, bodyLinkPrefix = BODY_LINK_PREFIX) {
     const fires = hint ? ` Fires on: ${hint}.` : '';
     return (`## ${title}\n` +
         `${THIN_ENTRY_MARKER}${fires} ${desc} ` +
-        `Body: [\`${rule_id}\`](${bodyLinkPrefix}${rule_id}.md)\n`);
+        `${THIN_BODY_POINTER_PREFIX}${bodyLinkPrefix}${rule_id}.md\n`);
 }
 /**
  * The marker that opens a stub's copied law block, and the one that closes it

package/dist/scripts/lint_svg_asset.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * lint_svg_asset — the command-line surface over the SVG rule set.
+ *
+ * The rules live in `_lib/svg_rules.ts`, because the design pass imports them
+ * into the hook bundle and must not drag a CLI in with them (see that file's
+ * header for the measurement). Everything this module adds is the part only a
+ * command needs: argument parsing, the directory walk, the project config, the
+ * scanned-nothing refusal, and the step 1.2 preservation readout.
+ *
+ * Inline-ignore (same shape as `lint_design_quality`, works in XML comments):
+ *   svg-asset-disable <rule-id> [-- reason]            (file scope)
+ *   svg-asset-disable-next-line <rule-id> [-- reason]
+ *   svg-asset-disable-line <rule-id> [-- reason]
+ *
+ * Per-project config (`.svg-asset.json` in the project root):
+ *   { "ignoreRules": ["svg-a11y-generic-id"], "ignoreFiles": ["vendor/**"] }
+ *
+ * Usage:
+ *   lint_svg_asset --dir <path> [--delivery inline|img|css-bg|document]
+ *   lint_svg_asset --file <a.svg> [--file <b.svg>] [--delivery …]
+ *   lint_svg_asset --file <after.svg> --baseline <before.svg> --allow id,id
+ *
+ * Exit codes: 0 = clean, 2 = findings, 1 = internal error (including the
+ * scanned-nothing refusal — a gate that scanned no file is not a clean gate).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { DELIVERY_MODES, parseElements, scanHostHtml, scanSvg, } from './_lib/svg_rules.js';
+export * from './_lib/svg_rules.js';
+/**
+ * Canonicalised attribute map — number formatting, attribute order and
+ * whitespace normalised away, so a re-serialisation that changed nothing reads
+ * as nothing changed.
+ */
+export function canonicalAttrs(attrs) {
+    const out = {};
+    for (const key of Object.keys(attrs).sort()) {
+        const v = (attrs[key] ?? '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            // Numbers only where a number is what it is. A hex color is a
+            // TOKEN, not a quantity: normalising inside `#00ff00` collapses it
+            // onto `#0ff0`, and the readout then reports no change for a color
+            // edit outside the allowed ids — a surgical-edit witness that
+            // cannot see a recolour.
+            .replace(/#[0-9a-fA-F]+|-?\d+\.?\d*(?:[eE][-+]?\d+)?/g, (tok) => {
+            if (tok.startsWith('#'))
+                return tok.toLowerCase();
+            const num = Number(tok);
+            return Number.isFinite(num) ? String(Number(num.toFixed(4))) : tok;
+        });
+        out[key] = v;
+    }
+    return out;
+}
+/**
+ * Every element outside the allowed set that changed between two revisions.
+ *
+ * NO PIXEL DIFF decides this. Anti-aliasing and font metrics would make a
+ * pixel comparison a per-machine verdict, and the discipline this witnesses —
+ * `design-fidelity-mechanics.md` § surgical edits — is about which elements
+ * the edit was allowed to touch, which is an attribute fact.
+ */
+export function preservationReadout(beforeContent, afterContent, allowedIds) {
+    const allow = new Set(allowedIds.map((s) => s.trim()).filter(Boolean));
+    /**
+     * A stable key per element, and the id chain above it.
+     *
+     * An element WITHOUT an id is keyed by its nearest id-bearing ancestor plus
+     * its tag and its ordinal INSIDE that ancestor — never by a document-wide
+     * index. A document-wide index shifts for every element after an allowed
+     * deletion, so removing one child of the allowed group reported every
+     * un-idded element after it as changed. Measured on the `grouped-transforms`
+     * triple: the correct edit reported `rect#7 (element)` and the readout could
+     * not tell a clean surgical edit from a dirty one.
+     */
+    const index = (content) => {
+        const map = new Map();
+        const stack = [];
+        const ordinals = new Map();
+        for (const el of parseElements(content)) {
+            if (el.closing) {
+                if (stack[stack.length - 1]?.name === el.name)
+                    stack.pop();
+                continue;
+            }
+            const chain = stack.map((f) => f.id).filter((x) => x !== null);
+            const ownerId = [...stack].reverse().find((f) => f.id !== null)?.id ?? '';
+            const own = el.attrs['id'] ?? null;
+            let key;
+            if (own) {
+                key = own;
+            }
+            else {
+                const bucket = `${ownerId}/${el.name}`;
+                const n = (ordinals.get(bucket) ?? 0) + 1;
+                ordinals.set(bucket, n);
+                key = `${bucket}#${n}`;
+            }
+            map.set(key, { el, chain: own ? [...chain, own] : chain });
+            if (!el.selfClosing)
+                stack.push({ name: el.name, id: own });
+        }
+        return map;
+    };
+    const before = index(beforeContent);
+    const after = index(afterContent);
+    const changes = [];
+    /** An element inside an allowed subtree is itself allowed. */
+    const permitted = (entry) => Boolean(entry && entry.chain.some((id) => allow.has(id)));
+    for (const [key, beforeEntry] of before) {
+        if (permitted(beforeEntry))
+            continue;
+        const afterEntry = after.get(key);
+        if (!afterEntry) {
+            changes.push({
+                id: key,
+                element: beforeEntry.el.name,
+                attribute: '(element)',
+                before: 'present',
+                after: 'removed',
+            });
+            continue;
+        }
+        const a = canonicalAttrs(beforeEntry.el.attrs);
+        const b = canonicalAttrs(afterEntry.el.attrs);
+        for (const attr of new Set([...Object.keys(a), ...Object.keys(b)])) {
+            if ((a[attr] ?? '') === (b[attr] ?? ''))
+                continue;
+            changes.push({
+                id: key,
+                element: beforeEntry.el.name,
+                attribute: attr,
+                before: a[attr] ?? '(absent)',
+                after: b[attr] ?? '(absent)',
+            });
+        }
+    }
+    for (const [key, afterEntry] of after) {
+        if (permitted(afterEntry) || before.has(key))
+            continue;
+        changes.push({
+            id: key,
+            element: afterEntry.el.name,
+            attribute: '(element)',
+            before: 'absent',
+            after: 'added',
+        });
+    }
+    return changes;
+}
+export function loadConfig(dir) {
+    const configPath = path.join(dir, '.svg-asset.json');
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function* walkDir(dir, ext) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.name.startsWith('.') || entry.name === 'node_modules')
+            continue;
+        if (entry.isDirectory())
+            yield* walkDir(full, ext);
+        else if (ext.test(entry.name))
+            yield full;
+    }
+}
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function readFlag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function readAll(args, name) {
+    const out = [];
+    for (let i = 0; i < args.length; i++)
+        if (args[i] === name && args[i + 1])
+            out.push(args[i + 1]);
+    return out;
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = [...argv];
+    const jsonMode = args.includes('--json');
+    const quiet = args.includes('--quiet');
+    const deliveryRaw = readFlag(args, '--delivery');
+    if (deliveryRaw && !DELIVERY_MODES.includes(deliveryRaw)) {
+        process.stderr.write(`[lint_svg_asset] unknown --delivery "${deliveryRaw}"; expected one of ${DELIVERY_MODES.join(', ')}\n`);
+        return 1;
+    }
+    const delivery = deliveryRaw;
+    // --- step 1.2: preservation readout -------------------------------------
+    const baseline = readFlag(args, '--baseline');
+    if (baseline) {
+        const files = readAll(args, '--file');
+        const after = files[0];
+        if (!after) {
+            process.stderr.write('[lint_svg_asset] --baseline needs a --file <after.svg> to compare against\n');
+            return 1;
+        }
+        if (!fs.existsSync(baseline) || !fs.existsSync(after)) {
+            process.stderr.write('[lint_svg_asset] --baseline or --file path not found\n');
+            return 1;
+        }
+        const allow = (readFlag(args, '--allow') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        const changes = preservationReadout(fs.readFileSync(baseline, 'utf-8'), fs.readFileSync(after, 'utf-8'), allow);
+        if (jsonMode) {
+            process.stdout.write(`${JSON.stringify(changes, null, 2)}\n`);
+            return changes.length ? 2 : 0;
+        }
+        if (!changes.length) {
+            if (!quiet) {
+                process.stdout.write(`✅  lint_svg_asset --baseline: nothing changed outside ${allow.length} allowed id(s).\n`);
+            }
+            return 0;
+        }
+        for (const c of changes) {
+            process.stdout.write(`❌ ${after} [svg-preserve-changed-outside-allowed] <${c.element} id="${c.id}"> ` +
+                `${c.attribute}: "${c.before}" → "${c.after}"\n`);
+        }
+        process.stdout.write(`\nlint_svg_asset: ${changes.length} element change(s) outside the allowed set. ` +
+            'A surgical edit touches only what it declared.\n');
+        return 2;
+    }
+    // --- scanning -----------------------------------------------------------
+    const explicit = readAll(args, '--file');
+    const dirArg = readFlag(args, '--dir');
+    const targets = [];
+    let roots = [];
+    if (explicit.length) {
+        targets.push(...explicit.map((f) => path.resolve(f)));
+        roots = targets;
+    }
+    else {
+        const scanDir = dirArg ? path.resolve(dirArg) : path.resolve(process.cwd(), 'src');
+        roots = [scanDir];
+        if (!fs.existsSync(scanDir)) {
+            // The two cases are NOT the same, and collapsing them into exit 0
+            // made a renamed or mistyped `--dir` report success in CI. An
+            // ABSENT DEFAULT root is the opt-in escape — a consumer with no
+            // `src/` has nothing to scan and must not red. An EXPLICIT `--dir`
+            // that does not resolve is a broken invocation, and this module's
+            // own header already says a gate that scanned no file is not a
+            // clean gate.
+            if (!quiet)
+                process.stderr.write(`[lint_svg_asset] scan directory not found: ${scanDir}\n`);
+            if (dirArg)
+                return 1;
+            process.stderr.write('This linter is opt-in. Run with --dir <path> or --file <a.svg> pointing at your assets.\n');
+            return 0;
+        }
+        for (const f of walkDir(scanDir, /\.(svg|html|htm)$/i))
+            targets.push(f);
+    }
+    const config = loadConfig(process.cwd());
+    const ignoreRules = new Set((config.ignoreRules ?? []).map((r) => r.toLowerCase()));
+    const ignoreGlobs = config.ignoreFiles ?? [];
+    const scanned = targets.filter((f) => !ignoreGlobs.some((g) => f.includes(g.replace('**', ''))));
+    try {
+        assertScanned({ gate: 'lint_svg_asset', scanned: scanned.length, units: 'SVG/HTML file(s)', roots });
+    }
+    catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    const all = [];
+    for (const abs of scanned) {
+        const rel = path.relative(process.cwd(), abs);
+        try {
+            const content = fs.readFileSync(abs, 'utf-8');
+            const findings = /\.svg$/i.test(abs)
+                ? scanSvg(content, rel, { delivery })
+                : scanHostHtml(content, rel, { delivery });
+            all.push(...findings.filter((f) => !ignoreRules.has(f.rule.toLowerCase())));
+        }
+        catch (err) {
+            if (!quiet)
+                process.stderr.write(`[lint_svg_asset] error: ${abs}: ${err}\n`);
+        }
+    }
+    if (jsonMode) {
+        process.stdout.write(`${JSON.stringify(all, null, 2)}\n`);
+        return all.length > 0 ? 2 : 0;
+    }
+    if (!all.length) {
+        if (!quiet) {
+            process.stdout.write(`✅  lint_svg_asset: clean — ${scanned.length} file(s) checked, no violations.\n`);
+        }
+        return 0;
+    }
+    const errors = all.filter((f) => f.severity === 'error');
+    const warnings = all.filter((f) => f.severity === 'warning');
+    const inert = all.filter((f) => f.severity === 'inert');
+    for (const f of all) {
+        const icon = f.severity === 'error' ? '❌' : f.severity === 'warning' ? '⚠️ ' : 'ℹ️ ';
+        process.stdout.write(`${icon} ${f.file}:${f.line} [${f.rule}] ${f.snippet}\n`);
+    }
+    process.stdout.write(`\nlint_svg_asset: ${errors.length} error(s), ${warnings.length} warning(s), ${inert.length} inert. ` +
+        'Use svg-asset-disable-next-line <rule> -- reason or .svg-asset.json to suppress; ' +
+        'svg-safety-* findings yield only to .svg-asset.json, never to a marker in the file. ' +
+        'Advisory: an "inert" row is not a clean row — the same file inlined tomorrow is an error.\n');
+    return 2;
+}
+/* c8 ignore start — entrypoint guard, exercised by the CLI not by the tests */
+const invokedDirectly = typeof process !== 'undefined' &&
+    Array.isArray(process.argv) &&
+    /lint_svg_asset\.(ts|js)$/.test(process.argv[1] ?? '');
+if (invokedDirectly)
+    process.exit(main());
+/* c8 ignore stop */
+//# sourceMappingURL=lint_svg_asset.js.map

package/dist/server/app.js

@@ -155,7 +155,7 @@ export async function createApp(opts) {
     await app.register(pingRoute({ writeRoot, projectScopeRoot, mode, dryRun, projectSurface: opts.projectSurface === true }));
     await app.register(discoveryRoute(opts.discoveryManifestPath ? { manifestPath: opts.discoveryManifestPath } : {}));
     await app.register(schemaRoute());
-    await app.register(settingsRoute({ writeRoot, legacyReadRoot, packageRoot, dryRun, userGlobalReadRoot: userGlobalRead }));
+    await app.register(settingsRoute({ writeRoot, legacyReadRoot, packageRoot, dryRun, userGlobalReadRoot: userGlobalRead, userGlobalWrite: mode === 'global' }));
     await app.register(settingsChangesRoute({ writeRoot, userGlobalReadRoot: userGlobalRead, dryRun }));
     await app.register(userMdRoute({ writeRoot, legacyReadRoot, dryRun, userGlobalReadRoot: userGlobalRead }));
     await app.register(installRoute(opts.installRouteOptions ?? {}));
@@ -167,6 +167,7 @@ export async function createApp(opts) {
         dryRun,
         userGlobalReadRoot: userGlobalRead,
         extendedSteps: opts.extendedSteps === true,
+        userGlobalWrite: mode === 'global',
         ...(opts.initialStep !== undefined ? { initialStep: opts.initialStep } : {}),
         ...(opts.wizardMode !== undefined ? { wizardMode: opts.wizardMode } : {}),
     }));

package/dist/server/gitKeysGate.js

@@ -0,0 +1,105 @@
+/**
+ * The settings route's handling of the three `git.*` keys.
+ *
+ * In global mode the route writes the user-global file, and `load_agent_settings`
+ * discards `git.*` keys from that file, so a value saved there has no effect in
+ * any repository. The form is not offered those keys, and a non-default value is
+ * refused with the place a team declares them instead (ADR-283). A template
+ * default is accepted: the form round-trips it, and `upgrade` inserts it too.
+ *
+ * In every mode a value goes through the same check `git:convention show` and
+ * `settings:check` run, so a pattern that would reach a shell is refused here as
+ * well.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { parseYaml } from './io/yamlIO.js';
+import { GIT_CONVENTION_KEYS, invalidReason } from '../scripts/_lib/git_convention.js';
+export const WITHHELD_GIT_KEYS = GIT_CONVENTION_KEYS.map((k) => `git.${k}`);
+export const WITHHELD_REASON = 'This form writes your user-global settings file, which does not carry git.* keys. ' +
+    'A team declares them in .git-convention.yml at the repository root; one checkout can set them in its project settings file.';
+function _gitSection(values) {
+    const git = values['git'];
+    return git !== null && typeof git === 'object' && !Array.isArray(git) ? git : null;
+}
+/** The values and the JSON schema with the `git` section removed. */
+export function withholdGitKeys(values, schema) {
+    const { git: _git, ...rest } = values;
+    const properties = { ...(schema.properties ?? {}) };
+    delete properties['git'];
+    const next = { ...schema, properties };
+    if (Array.isArray(schema.required))
+        next.required = schema.required.filter((k) => k !== 'git');
+    return { values: rest, schema: next };
+}
+/**
+ * Field issues for the `git.*` values of a write. `defaults` is the template's
+ * `git` section; `userGlobal` is true when the write lands in the user-global file.
+ */
+export function gitKeyWriteIssues(values, defaults, userGlobal) {
+    const git = _gitSection(values);
+    if (git === null)
+        return [];
+    const fallback = _gitSection(defaults) ?? {};
+    const issues = [];
+    for (const key of GIT_CONVENTION_KEYS) {
+        const value = git[key];
+        if (typeof value !== 'string')
+            continue;
+        const why = invalidReason(key, value);
+        if (why !== null) {
+            issues.push({ path: `git.${key}`, message: why });
+            continue;
+        }
+        const def = fallback[key];
+        if (userGlobal && !(typeof def === 'string' && def === value)) {
+            issues.push({ path: `git.${key}`, message: WITHHELD_REASON });
+        }
+    }
+    return issues;
+}
+/**
+ * The write candidate with the `git` section the file already holds. In global
+ * mode the form never showed that section, and the schema's `.default({})`
+ * fills template defaults into whatever arrives, so a value the user-global
+ * file carries would otherwise read as a change the user made: a guarded-key
+ * confirmation for a field they never saw, then a silent reset.
+ *
+ * `fileValues` is that file alone, never the merged view: the merge carries
+ * the template defaults and any project layer, and copying a project value
+ * here would write it into the user-global file without passing the gate.
+ */
+export function keepWithheldGit(candidate, fileValues) {
+    const { git: _sent, ...rest } = candidate;
+    return 'git' in fileValues ? { ...rest, git: fileValues['git'] } : rest;
+}
+/**
+ * The before-side of a global-mode diff: the merged view with its `git` section
+ * swapped for the file's own, or dropped when the file has none. The candidate
+ * from `keepWithheldGit` carries exactly that section, so comparing it against
+ * the merged view would report template defaults and project values as edits
+ * to a section the form never showed.
+ */
+export function gitDiffBase(merged, fileValues) {
+    return keepWithheldGit(merged, fileValues);
+}
+/**
+ * The wizard's finish write through the same gate: a 422 is sent and true
+ * returned when a `git.*` value is refused. The template's `git` section holds
+ * no install placeholder, so it is parsed without substitution.
+ */
+export async function refuseGitKeys(reply, values, packageRoot, userGlobal) {
+    let defaults = {};
+    try {
+        defaults = parseYaml(await fs.readFile(join(packageRoot, 'src', 'config', 'agent-settings.template.yml'), 'utf8'));
+    }
+    catch {
+        defaults = {};
+    }
+    const issues = gitKeyWriteIssues(values, defaults, userGlobal);
+    if (issues.length === 0)
+        return false;
+    await reply.code(422).send({ error: { code: 'VALIDATION', message: 'invalid settings', fields: issues } });
+    return true;
+}
+//# sourceMappingURL=gitKeysGate.js.map