@event4u/agent-config 16.2.0 → 16.4.0

package/dist/scripts/project_thin_rules.js

@@ -18,11 +18,10 @@
  * target dir of your choosing — it never overwrites the live `.claude/` /
  * `.augment/` projections.
  *
- * NOTE (faithful literal): the thin-entry pointer keeps the verbatim
- * `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.
+ * NOTE: the thin-entry pointer literal moved with the mechanism — it is
+ * `BODY_LINK_PREFIX` in `_lib/thin_rules.ts` now, so the twin-parity argument
+ * that exempted it from the ADR-051 legacy-path guard belongs to THAT file and
+ * no longer describes this one, which holds the string nowhere.
  *
  * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
@@ -34,299 +33,20 @@ 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
-// from src/scripts/<file>.
-export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-export const RULES_SOURCE = path.join(REPO_ROOT, 'dist/agent-src', 'rules');
-export const ROUTER = path.join(REPO_ROOT, 'dist', 'router.json');
-/** `sorted(dir.glob("*.md"))` — non-recursive, lexically sorted abs paths. */
-function _globSortedMd(dir) {
-    let names;
-    try {
-        names = fs.readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
-    const out = names.filter((n) => n.endsWith('.md')).map((n) => path.join(dir, n));
-    out.sort();
-    return out;
-}
-/** The always-full-bodied set — authoritative kernel list from the router. */
-export function kernel_ids() {
-    const data = JSON.parse(fs.readFileSync(ROUTER, 'utf-8'));
-    const kernel = data.kernel;
-    if (Array.isArray(kernel)) {
-        return new Set(kernel.map((x) => String(x)));
-    }
-    return new Set();
-}
-/**
- * Tier rules the router gives NO trigger at all.
- *
- * These cannot be delivered on a match, so thinning them would remove a body
- * that nothing can ever put back — a silent hole rather than a saving. They
- * project full-bodied, and `measure` reports them by name so the residue is
- * 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() {
-    return new Set(triggerlessRuleIds(_router()));
-}
-/**
- * id → workspaces for every non-kernel router entry (router.json schema v2,
- * road-to-request-scoped-rule-load Phase 1). Rules absent from the map (or
- * with an empty list) fail safe: they stay in scope.
- */
-export function rule_workspaces_map() {
-    const data = JSON.parse(fs.readFileSync(ROUTER, 'utf-8'));
-    const map = new Map();
-    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 ws = Array.isArray(obj.workspaces) ? obj.workspaces.map((w) => String(w)) : [];
-            map.set(String(obj.id), ws);
-        }
-    }
-    return map;
-}
-/**
- * Whether a rule id survives a workspace scope. Kernel always survives;
- * `scope === null` = legacy-all. An out-of-scope non-kernel rule is dropped
- * entirely — neither body nor pointer line (the pointer floor shrinks with
- * consumer scoping).
- */
-export function id_in_scope(rule_id, scope, kernel, wsMap, fallback_ws = []) {
-    if (scope === null || kernel.has(rule_id)) {
-        return true;
-    }
-    // Router map first (schema v2); `type: manual` rules are reference-only
-    // and never emitted to the router — their frontmatter is the fallback.
-    const ws = wsMap.get(rule_id) ?? fallback_ws;
-    if (ws.length === 0) {
-        return true; // untagged / unknown → fail safe
-    }
-    return ws.some((w) => scope.includes(w));
-}
-/** `workspaces:` list parsed straight from a rule file's frontmatter. */
-export function fm_workspaces(text) {
-    const [fm] = split_frontmatter(text);
-    // Flow style: `workspaces: [a, b, c]`
-    const flow = /^workspaces:[ \t]*\[([^\]]*)\]/m.exec(fm);
-    if (flow) {
-        return flow[1]
-            .split(',')
-            .map((s) => s.trim().replace(/^["']|["']$/g, ''))
-            .filter((s) => s.length > 0);
-    }
-    // Block style; tolerate the list being the LAST frontmatter key.
-    const m = /^workspaces:[ \t]*\n((?:[ \t]+-[ \t]+.*(?:\n|$))+)/m.exec(fm);
-    if (!m) {
-        return [];
-    }
-    return [...m[1].matchAll(/-[ \t]+(\S+)/g)].map((x) => x[1]);
-}
-/** Return [frontmatter_including_fences, body]. Empty fm if none. */
-export function split_frontmatter(text) {
-    if (text.startsWith('---\n')) {
-        const end = text.indexOf('\n---\n', 4);
-        if (end !== -1) {
-            return [text.slice(0, end + 5), text.slice(end + 5)];
-        }
-    }
-    return ['', text];
-}
-function _description(fm) {
-    // re.search(r'^description:\s*"?(.+?)"?\s*$', fm, re.MULTILINE)
-    const m = /^description:\s*"?(.+?)"?\s*$/m.exec(fm);
-    return m ? m[1].trim() : '';
-}
-// How many trigger keywords/phrases to surface as the always-on match hint.
-const _TRIGGER_HINT_LIMIT = 6;
-/** A short, comma-joined sample of the rule's trigger keywords/phrases. */
-function _trigger_hint(fm) {
-    const hits = [];
-    // re.finditer(r'^\s*-\s*(?:keyword|phrase):\s*"?(.+?)"?\s*$', fm, re.MULTILINE)
-    const re = /^\s*-\s*(?:keyword|phrase):\s*"?(.+?)"?\s*$/gm;
-    let m;
-    while ((m = re.exec(fm)) !== null) {
-        hits.push(m[1].trim());
-        if (hits.length >= _TRIGGER_HINT_LIMIT) {
-            break;
-        }
-    }
-    return hits.join(', ');
-}
-/** Python `str.title()` — uppercase first alpha of each run, rest lowercase. */
-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.
+ * The mechanism lives in `_lib/thin_rules.ts`; this file is its CLI.
  *
- * 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.
+ * Re-exported wholesale so every existing importer of
+ * `project_thin_rules.{build_thin,thin_entry,is_thin_entry,RULES_SOURCE,…}`
+ * keeps working unchanged. The split exists because `src/scripts/install.ts` is
+ * a bundle entry and `check_installer_import_purity` forbids it reaching a
+ * module-level `process.exit()` — which this file has, at its foot, by design.
  */
-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);
-    const desc = _description(fm);
-    const hint = _trigger_hint(fm);
-    const title = _title(rule_id.replace(/-/g, ' '));
-    const fires = hint ? ` Fires on: ${hint}.` : '';
-    return (`## ${title}\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, 
-/**
- * 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)) {
-        const text = fs.readFileSync(p, 'utf-8');
-        const stem = path.basename(p).replace(/\.md$/, '');
-        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) || 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;
-}
+export * from './_lib/thin_rules.js';
+import { _globSortedMd, build_thin, fm_workspaces, id_in_scope, kernel_ids, no_trigger_ids, REPO_ROOT, RULES_SOURCE, rule_workspaces_map, } from './_lib/thin_rules.js';
+void REPO_ROOT;
+const _HERE = fileURLToPath(import.meta.url);
 /** Python `round(x, 1)` — round-half-to-even at one decimal. */
 function _python_round1(x) {
     const scaled = x * 10;

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

package/dist/server/routes/settings.js

@@ -1,12 +1,36 @@
 import { promises as fs } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { settingsSchema } from '../schemas/settings.js';
-import { parseYaml, mergeIntoTemplate, diffValues, deepMerge, TEMPLATE_PLACEHOLDER_DEFAULTS } from '../io/yamlIO.js';
+import { parseYaml, mergeIntoTemplate, diffValues, deepMerge, renderSparseSettings, substituteTemplatePlaceholders, TEMPLATE_PLACEHOLDER_DEFAULTS } from '../io/yamlIO.js';
+import { sparseSettingsValues } from './wizard.js';
 import { writeAtomic } from '../io/atomicWrite.js';
+import { WITHHELD_GIT_KEYS, WITHHELD_REASON, gitDiffBase, gitKeyWriteIssues, keepWithheldGit, withholdGitKeys } from '../gitKeysGate.js';
 import { sharedWriteTarget, resolveThroughSymlinks } from '../io/sharedWriteCheck.js';
 import { PACKAGE_ROOT } from '../../cli/paths.js';
 import { buildSettingsClassIndex, guardedChangedKeys, parseSettingsClassRows } from '../../shared/settingsClasses.js';
+/**
+ * A fresh user-global file records decisions, not the defaults: the form posts
+ * every value, and a copy of the template's would freeze each default at today's
+ * value. Only leaves that differ from the template are kept, over the carve-outs.
+ */
+async function freshUserGlobalValues(packageRoot, candidate) {
+    const templateBody = await fs.readFile(join(packageRoot, 'src', 'config', 'agent-settings.template.yml'), 'utf8');
+    const template = parseYaml(substituteTemplatePlaceholders(templateBody));
+    const decided = (value, dflt) => {
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            const base = dflt !== null && typeof dflt === 'object' && !Array.isArray(dflt) ? dflt : {};
+            const kept = Object.entries(value)
+                .map(([k, v]) => [k, decided(v, base[k])])
+                .filter(([, v]) => v !== undefined);
+            return kept.length === 0 ? undefined : Object.fromEntries(kept);
+        }
+        return isDeepStrictEqual(value, dflt) ? undefined : value;
+    };
+    const own = (decided(candidate, template) ?? {});
+    return deepMerge(sparseSettingsValues(templateBody, {}), own);
+}
 /** Sidecar written by `settings:set`, keyed by dotted path. */
 const PROVENANCE_RELATIVE = join('settings', '.agent-settings.provenance.json');
 /**
@@ -217,6 +241,8 @@ async function readLayeredSettings(packageRoot, writeRoot, legacyReadRoot, userG
                 ])],
             project: projectLayer !== null ? dottedLeafPaths(projectLayer.values) : [],
         },
+        writeLayer: globalLayer?.values ?? null,
+        writeLayerRaw: globalLayer?.raw ?? null,
     };
 }
 function zodIssuesToFields(issues) {
@@ -234,6 +260,10 @@ export function settingsRoute(opts) {
         app.get('/api/v1/settings', async (_request, reply) => {
             try {
                 const state = await readLayeredSettings(packageRoot, opts.writeRoot, opts.legacyReadRoot, opts.userGlobalReadRoot);
+                const offered = opts.userGlobalWrite === true
+                    ? withholdGitKeys(state.values, SETTINGS_JSON_SCHEMA)
+                    : { values: state.values, schema: SETTINGS_JSON_SCHEMA };
+                const withheld = opts.userGlobalWrite === true ? { withheld: { keys: WITHHELD_GIT_KEYS, reason: WITHHELD_REASON } } : {};
                 if (!state.hasRealFile) {
                     // No on-disk file yet — the wizard creates it. Surface the
                     // template-defaults values + schema + path in the body so
@@ -242,19 +272,21 @@ export function settingsRoute(opts) {
                     // `{}` and the user's first save fails schema validation).
                     await reply.code(404).send({
                         error: { code: 'NOT_FOUND', message: 'settings file missing' },
-                        defaults: state.values,
+                        defaults: offered.values,
                         lastModified: 0,
                         path: SETTINGS_RELATIVE,
-                        schema: SETTINGS_JSON_SCHEMA,
+                        schema: offered.schema,
+                        ...withheld,
                     });
                     return reply;
                 }
                 const legacyHints = extractLegacyHints(state.values);
                 return {
-                    values: state.values,
+                    values: offered.values,
                     lastModified: state.mtimeMs,
                     path: SETTINGS_RELATIVE,
-                    schema: SETTINGS_JSON_SCHEMA,
+                    schema: offered.schema,
+                    ...withheld,
                     legacyHints,
                     // Phase 5.4 — per-layer provenance for the settings hub's
                     // "set globally / in this project" source badges.
@@ -293,7 +325,13 @@ export function settingsRoute(opts) {
                 });
                 return reply;
             }
-            const changes = diffValues(current.values, parsed.data);
+            const candidate = opts.userGlobalWrite === true
+                ? keepWithheldGit(parsed.data, current.writeLayer ?? {})
+                : parsed.data;
+            const before = opts.userGlobalWrite === true
+                ? gitDiffBase(current.values, current.writeLayer ?? {})
+                : current.values;
+            const changes = diffValues(before, candidate);
             return { changes };
         });
         app.put('/api/v1/settings', async (request, reply) => {
@@ -310,6 +348,11 @@ export function settingsRoute(opts) {
                 });
                 return reply;
             }
+            const gitIssues = gitKeyWriteIssues(parsed.data, await loadDefaultSettings(packageRoot), opts.userGlobalWrite === true);
+            if (gitIssues.length > 0) {
+                await reply.code(422).send({ error: { code: 'VALIDATION', message: 'invalid settings', fields: gitIssues } });
+                return reply;
+            }
             const current = await readLayeredSettings(packageRoot, opts.writeRoot, opts.legacyReadRoot, opts.userGlobalReadRoot);
             if (!current.hasRealFile) {
                 await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'settings file missing' } });
@@ -322,8 +365,22 @@ export function settingsRoute(opts) {
                 });
                 return reply;
             }
+            const candidate = opts.userGlobalWrite === true
+                ? keepWithheldGit(parsed.data, current.writeLayer ?? {})
+                : parsed.data;
             try {
-                const merged = mergeIntoTemplate(current.raw, parsed.data);
+                // In global mode the scaffold may be the project file, whose
+                // git section the candidate does not overwrite; the file being
+                // written is the base, so a section it lacks stays absent. An
+                // absent user-global file is rendered the way the wizard renders
+                // a fresh one: merging into an empty body appends flat dotted
+                // keys, which no reader resolves.
+                const ownRaw = current.writeLayerRaw;
+                const merged = opts.userGlobalWrite !== true
+                    ? mergeIntoTemplate(current.raw, candidate)
+                    : ownRaw !== null
+                        ? mergeIntoTemplate(ownRaw, candidate)
+                        : renderSparseSettings(await freshUserGlobalValues(packageRoot, candidate));
                 if (opts.dryRun === true) {
                     // No disk write, no Last-Modified bump — surface the
                     // rendered body so the maintainer sees what a real
@@ -352,7 +409,9 @@ export function settingsRoute(opts) {
                 // this point and is not gated — it writes nothing.
                 if (body.confirmGuarded !== true) {
                     const classes = await readClassIndex(packageRoot);
-                    const guarded = guardedChangedKeys(classes, diffValues(current.values, parsed.data));
+                    const guarded = guardedChangedKeys(classes, diffValues(opts.userGlobalWrite === true
+                        ? gitDiffBase(current.values, current.writeLayer ?? {})
+                        : current.values, candidate));
                     if (guarded.length > 0) {
                         await reply.code(409).send({
                             error: 'guarded-keys',

package/dist/server/routes/wizard.js

@@ -19,6 +19,7 @@ import { detectAgentSwitch, AGENT_SWITCH_INSTALL_COMMAND, AGENT_SWITCH_REPO } fr
 import { readDismissedRecommendations, dismissRecommendation } from '../../install/wizardDismissals.js';
 import { installCompleted, installDoneSummary } from '../../install/preserve.js';
 import { apiOnQuotaView } from '../../scripts/ai_council/transport_resolver.js';
+import { refuseGitKeys } from '../gitKeysGate.js';
 const STATE_REL = join('state', 'wizard-state.json');
 const SETTINGS_REL = join('settings', '.agent-settings.yml');
 const USER_IDENTITY_REL = join('settings', '.agent-user.yml');
@@ -1198,6 +1199,9 @@ export function wizardRoute(opts) {
             const effectiveWriteRoot = scope === 'project' && projectScopeRoot !== null
                 ? projectScopeRoot
                 : opts.writeRoot;
+            const userGlobalTarget = opts.userGlobalWrite === true && effectiveWriteRoot === opts.writeRoot;
+            if (await refuseGitKeys(reply, settingsParsed.data, opts.packageRoot, userGlobalTarget))
+                return reply;
             try {
                 const template = await readTemplate(opts.packageRoot);
                 const answers = settingsParsed.data;