@event4u/agent-config 16.3.0 → 16.4.0

package/dist/scripts/_lib/settings_removed_keys.js

@@ -0,0 +1,168 @@
+/**
+ * The registry of DELETED settings keys, and the once-per-run notice a leftover
+ * value gets. Extracted from `agent_settings.ts`, which sits at the 1500-line
+ * source ceiling — every retirement batch adds entries here, and here they cost
+ * no ratchet. `agent_settings.ts` re-exports `REMOVED_KEYS` so existing
+ * importers (the loader, `lint_settings_classes`) are unchanged.
+ */
+/**
+ * Settings keys this package has DELETED. A leftover value from an older
+ * install is ignored — never applied by any reader — and surfaced with ONE
+ * deprecation line per key per process run (stderr; the exit code never
+ * changes).
+ *
+ * The map carries a per-key REASON rather than one shared sentence, because
+ * the list now spans more than one deletion doctrine and a single blanket
+ * phrase would mis-attribute every future entry. A reader who hits the line
+ * should learn why the key went, not just that it did.
+ *
+ * `subagents.*` — the always-on-orchestration doctrine
+ * (road-to-always-on-orchestration Phase 1): the layer has no per-layer
+ * on/off setting any more. `ai_team.enabled` joined in Step 1.3 — the
+ * `/team` family's availability is a codex-CLI/auth FACT
+ * (`src/scripts/ai_team/availability.ts`), not a flag; the `ai_team` config
+ * loader (`src/scripts/ai_team/config.ts`) separately accepts a leftover
+ * `enabled` key without failing closed, so this warning is the only surfaced
+ * signal of that deletion.
+ *
+ * `hooks.turn_end_gate.*` — the turn-end gate is always armed (2026-08-12).
+ * A default-off safety gate cannot soak, so the switch protecting the soak
+ * made the soak impossible; whether the gate fires is now decided by each
+ * detector's own trigger conditions. See `turn_end_gate_hook.ts` § "Always
+ * armed".
+ *
+ * The five `derivable` leaves below (2026-08-12, road-to-zero-settings Phase
+ * 2.1) are a different case from every entry above them, and the difference is
+ * the whole safety argument: no code path ever *consulted* them. Each appeared
+ * in the template, the schema and the reference page, and several in the setup
+ * wizard, while the decision they looked like they governed was taken
+ * elsewhere. A key nothing reads cannot change a default by leaving — so this
+ * is the one deletion batch that needs no replacement mechanism, only the
+ * per-key statement of what already decides.
+ *
+ * A sixth unread key, `screenshots.data_bearing_gate`, was found in the same
+ * pass and deliberately NOT deleted — it is `consent`, and the open question is
+ * whether the repair is to build its missing reader or to delete a promise a
+ * Hard Floor can never honour. See `settings-classes.md` § The six unread keys.
+ *
+ * `worktrees.mode` (2026-08-13, ADR-229) is a third doctrine again: not
+ * always-on, not unread. It WAS read, and the reader honoured all three values —
+ * the deletion says the decision was never the agent's to make. `ask` bought a
+ * round trip per spawn, `on` let the agent start parallel work unprompted, and
+ * `off` described the wanted behavior, so `off` became the hardcoded rule and
+ * the switch went. What decides instead is the user's own sentence in the chat.
+ *
+ * The 2026-10-09 batch (road-to-settings-classes-derivable-surface-stagnation
+ * Phase 2) is a fourth doctrine: `derivable` keys whose shipped default is the
+ * only behavior the package supports. Each WAS read — by code or by rule and
+ * command prose — and every reader was rewritten to state the old default as
+ * fixed behavior in the same change, so retiring the key changes no effective
+ * default; what a consumer who had set a non-default value loses is named by
+ * the reason.
+ *
+ * Every reason string must name what decides INSTEAD, never just "removed".
+ * Exported so `lint_settings_classes` can check the deletion side of the
+ * surface: a reason that names no replacement, or an entry whose key is live in
+ * the template again, is a contradiction the loader itself cannot notice.
+ */
+export const REMOVED_KEYS = new Map([
+    ['subagents.enabled', 'always-on orchestration'],
+    ['subagents.auto', 'always-on orchestration'],
+    ['subagents.host_capabilities', 'always-on orchestration'],
+    ['subagents.budget_routing', 'always-on orchestration'],
+    ['ai_team.enabled', 'always-on orchestration'],
+    ['hooks.turn_end_gate.enabled', 'the turn-end gate is always armed'],
+    ['hooks.turn_end_gate.promissory', 'the turn-end gate is always armed'],
+    ['hooks.turn_end_gate.language', 'the turn-end gate is always armed'],
+    ['hooks.turn_end_gate.verification', 'the turn-end gate is always armed'],
+    ['telegraph.speak_scope', 'the rule body states its own scope; compile_time_toggles decides whether the rule ships'],
+    ['chat_history.max_size_kb', 'the rotate command takes --max-kb from argv; session-count pruning bounds the file'],
+    ['chat_history.on_overflow', 'the overflow mode comes from the rotate command --mode argv'],
+    ['quality.wait_for_remote_ci', 'whether to poll follows from the push plus a detectable remote pipeline'],
+    ['legal_review_prep.consented_at', 'the provenance sidecar settings:set writes and consentVerdict reads'],
+    ['worktrees.mode', 'the user asking for a worktree in the chat; creation is instruction-only and hardcoded'],
+    // 2026-10-09 — output and tone
+    ['personal.minimal_output', 'direct-answers Iron Law 3 mandates terse replies; there is no verbose mode'],
+    ['personal.play_by_play', 'direct-answers: no narration unless the user asks for it in the turn'],
+    ['personal.pr_comment_bot_icon', 'no-decorative-emojis-in-git-surfaces forbids the 🤖 prefix'],
+    ['verbosity.intent_announcements', 'direct-answers: act and emit the result, no "Let me…" openers'],
+    ['verbosity.preview_artifacts', 'generated content is used directly; preview-on-error and the Iron-Law gates decide when a preview shows'],
+    ['verbosity.routine_confirmations', 'the no-cheap-questions Pre-Send Self-Check; Iron-Law gates always ask'],
+    ['verbosity.post_action_reports', 'direct-answers Iron Law 3: a one-line confirmation and one end-summary'],
+    ['telegraph.speak', 'the telegraph-speak predicate in compile_time_toggles.ts; the bench verdict is package-level (ADR telegraph/0002)'],
+    ['tokens.rich_skills', "the skill's own token_budget_class: rich plus the lint_token_budget_discipline ceiling"],
+    // 2026-10-09 — reasoning protocol switches
+    ['reasoning.auto_gate', 'the RDP gate task signal plus the host self-assessment in rdp-gate.md'],
+    ['reasoning.components.orchestrator', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.notes_first', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.grounding', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.intent', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.complexity_first', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.verifier_default', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.prediction_tracking', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.decision_ledger', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.uncertainty_budget', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    // 2026-10-09 — roadmap cadence
+    ['roadmap.skip_pre_run_gate', 'the command name names the scope; only an ambiguous roadmap or an unresolvable conflict shows the gate'],
+    ['roadmap.dashboard_regen_cadence', 'a fixed cadence: every 5th closed step, every phase boundary, reply end and any file-shape touch'],
+    // 2026-10-09 — command suggestion and PR creation
+    ['commands.auto_detect', "an orchestrator's own auto_detect front-matter and the --no-auto-detect flag"],
+    ['commands.suggestion.enabled', 'the suggester match-score floor and cooldown; /command-suggestion-off silences one conversation'],
+    ['commands.suggestion.confidence_floor', "the suggester's fixed 0.6 floor; a command's own suggestion frontmatter can tighten it"],
+    ['commands.suggestion.cooldown_seconds', "the suggester's fixed 600-second cooldown; a command's own suggestion frontmatter can lengthen it"],
+    ['commands.suggestion.max_options', 'the fixed cap of 4 suggestions plus the always-present as-is option'],
+    ['commands.create_pr.api_examples', "/create-pr's grounding rule: an example only from a real source, otherwise a one-line pointer"],
+    ['commands.create_pr.ui_paths', "/create-pr's light frontend heuristic, which fails open"],
+    ['commands.create_pr.api_paths', "/create-pr's light API-endpoint heuristic, which fails open"],
+    // 2026-10-09 — memory and knowledge sharing
+    ['memory.cadence', 'a fixed cadence: the memory line renders whenever a memory type was asked; memory.visibility: off still silences it'],
+    ['memory.review_threshold', "/memory load's fixed preview threshold of 10 unreviewed intake signals"],
+    ['knowledge.global_sharing.redaction.enabled', 'the write-time redaction scan, which always runs before a card goes global'],
+    ['knowledge.global_sharing.redaction.halt_on_trigger', 'the redaction gate, which always halts on a confidential-pattern hit'],
+    ['knowledge.global_sharing.auto_promote_threshold', 'the fixed two-repo sighting count that triggers a promotion suggestion'],
+    ['knowledge.global_sharing.freshness.hypothesis_after_days', "the card's age over last_verified against the fixed 90-day lead-only window"],
+    ['knowledge.global_sharing.freshness.stale_after_days', "the card's age over last_verified against the fixed 180-day skip window"],
+    // 2026-10-09 — hooks and engine
+    ['hooks.concern_budget.max_per_event', "the concern-budget gate's own constant of 8 per (platform, event) cell"],
+    ['hooks.concern_budget.hard_fail', "the concern-budget gate's --strict argv; without it the gate warns"],
+    ['decision_engine.surface_traces', 'nothing: the per-phase decision trace stays off, the old default'],
+    ['decision_engine.on_block_fallback', 'the fail-safe: an on_block ask that times out always stops'],
+    ['explain.enable_last', 'the presence of a work-state trace; explain last always renders it'],
+    // 2026-10-09 — remaining
+    ['project.pr_template', '/create-pr, which reads .github/pull_request_template.md'],
+    ['pipelines.skill_improvement', 'the skill-improvement-trigger rule; the capture is a proposal the user confirms'],
+    ['consistency.cross_source', 'the cross-source-consistency rule, always on; batching and the no-cheap-questions floor bound the noise'],
+    ['subagents.downshift', 'the model_tier each sub-task declares; downshift is always on'],
+    ['ai_team.suppress_setup_hint', 'nothing: the one-line team-mode setup hint is always shown'],
+]);
+/** Keys already warned about in THIS process — the "once per run" dedupe. */
+const _warnedRemovedKeys = new Set();
+/** Read one dotted path out of a merged settings tree; `undefined` when absent. */
+function _readDotted(root, dotted) {
+    let node = root;
+    for (const part of dotted.split('.')) {
+        if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+            return undefined;
+        }
+        node = node[part];
+    }
+    return node;
+}
+/**
+ * Warn once per process, on stderr, for every {@link REMOVED_KEYS} entry still
+ * present in a resolved settings tree. Never throws, never changes what the
+ * caller does with `merged` — a pure notification side effect.
+ */
+export function warnRemovedKeys(merged) {
+    for (const [key, reason] of REMOVED_KEYS) {
+        if (_warnedRemovedKeys.has(key)) {
+            continue;
+        }
+        if (_readDotted(merged, key) === undefined) {
+            continue;
+        }
+        _warnedRemovedKeys.add(key);
+        process.stderr.write(`${key} was removed (${reason}); ignored.\n`);
+    }
+}
+//# sourceMappingURL=settings_removed_keys.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/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;