@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/config-loader.cjs

@@ -13,7 +13,8 @@
  *
  * Dependencies (leaf modules only):
  *   - node:fs / node:os / node:path (stdlib)
- *   - ./configuration.cjs    (normalizeLegacyKeys, CONFIG_DEFAULTS as CANONICAL_CONFIG_DEFAULTS)
+ *   - ./configuration.cjs    (normalizeLegacyKeys, isConfigSection, CONFIG_DEFAULTS as CANONICAL_CONFIG_DEFAULTS)
+ *   - ./unusable-input.cjs   (warnUnusableInput, UNUSABLE_REASON — #3760)
  *   - ./config-schema.cjs    (VALID_CONFIG_KEYS, DYNAMIC_KEY_PATTERNS)
  *   - ./planning-workspace.cjs (planningDir, planningRoot)
  *   - ./shell-command-projection.cjs (execGit, platformWriteSync, platformReadSync)
@@ -39,6 +40,12 @@ const configuration_cjs_1 = require("./configuration.cjs");
 const configSchema = require("./config-schema.cjs");
 const { VALID_CONFIG_KEYS, DYNAMIC_KEY_PATTERNS, isCentralConfigKey: _isCentralConfigKeyFn } = configSchema;
 const model_catalog_cjs_1 = require("./model-catalog.cjs");
+// #3760: the ADR-1411 out-of-band diagnostic seam. loadConfig returns `.config`
+// alone, so an in-band `skipped` record would be unreachable to nearly every
+// caller — "a reason no caller reads is an unreachable field" (ADR-1411).
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const unusableInputModule = require("./unusable-input.cjs");
+const { UNUSABLE_REASON: _UNUSABLE_REASON, warnUnusableInput: _warnUnusableInput } = unusableInputModule;
 // ─── Federated Config (ADR-857 phase 3b) ─────────────────────────────────────
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const federatedConfigModule = require("./federated-config.cjs");
@@ -77,6 +84,7 @@ function _resetFederatedRegistryForTests() {
  *  - git.*               → flat git keys (branching_strategy, templates)
  *  - workflow.*          → flat names (research, verifier, …)
  *  - planning.sub_repos  → sub_repos
+ *  - planning.pr_strict  → pr_strict
  *  - planning.commit_docs / search_gitignored → top-level flat keys
  */
 // CANONICAL_CONFIG_DEFAULTS is typed as Record<string, unknown> from configuration.cjs;
@@ -91,6 +99,23 @@ function _getNestedConfigDefault(section, field) {
     }
     return undefined;
 }
+/** Shared flat-then-nested config lookup; exported for parity tests. */
+function _getConfigValue(parsed, key, nested) {
+    if (parsed[key] !== undefined)
+        return parsed[key];
+    if (nested && parsed[nested.section] && typeof parsed[nested.section] === 'object' && parsed[nested.section] !== null) {
+        return parsed[nested.section][nested.field];
+    }
+    return undefined;
+}
+/** Shared nested-only config lookup; exported for parity tests. */
+function _getConfigNested(parsed, section, field) {
+    const sec = parsed[section];
+    if (sec !== null && typeof sec === 'object' && !Array.isArray(sec)) {
+        return sec[field];
+    }
+    return undefined;
+}
 const CONFIG_DEFAULTS = {
     model_profile: _getConfigDefault('model_profile'),
     commit_docs: _getConfigDefault('commit_docs'),
@@ -111,6 +136,7 @@ const CONFIG_DEFAULTS = {
     exa_search: _getConfigDefault('exa_search'),
     text_mode: _getNestedConfigDefault('workflow', 'text_mode'),
     sub_repos: _getNestedConfigDefault('planning', 'sub_repos'),
+    pr_strict: _getNestedConfigDefault('planning', 'pr_strict'),
     resolve_model_ids: _getConfigDefault('resolve_model_ids'),
     context_window: _getConfigDefault('context_window'),
     phase_naming: _getConfigDefault('phase_naming'),
@@ -120,7 +146,10 @@ const CONFIG_DEFAULTS = {
     security_asvs_level: _getNestedConfigDefault('workflow', 'security_asvs_level'),
     security_block_on: _getNestedConfigDefault('workflow', 'security_block_on'),
     post_planning_gaps: _getNestedConfigDefault('workflow', 'post_planning_gaps'),
+    research_before_questions: _getNestedConfigDefault('workflow', 'research_before_questions'), // #3894
     smart_zone_tokens: _getNestedConfigDefault('workflow', 'smart_zone_tokens'),
+    inline_plan_threshold: _getNestedConfigDefault('workflow', 'inline_plan_threshold'), // #3801
+    max_prompt_tokens: _getNestedConfigDefault('review', 'max_prompt_tokens'),
 };
 /**
  * Deep-merge two plain config objects. `overlay` wins on key conflict.
@@ -290,6 +319,59 @@ function _resetRuntimeWarningCacheForTests() {
     _warnedConfigKeys.clear();
     _warnedUnknownConfigKeys.clear();
     _warnedUnusableConfig.clear();
+    _warnedShadowedGlobalKeys.clear();
+}
+// ─── #3532 (10b): shadowed global-defaults diagnostic ────────────────────────
+// The keys Branch D's `_globalBaseCfg` demonstrably honors from
+// ~/.gsd/defaults.json when no project config exists. Under a project
+// .planning/config.json (Branch A — every real project) the global file is
+// never opened, so each of these set globally is silently inert for resolution.
+// `effort` is in Branch D's honored set but is EXCLUDED from the shadow warning:
+// the install-time effort sync (readGsdEffectiveEffortConfig) DOES merge the
+// global file, so warning on it would be false for the channel users actually
+// control via `effort sync`. Keep this list in lockstep with `_globalBaseCfg`
+// below — the per-key canary in tests/config-loader.test.cjs fails first on
+// drift in either direction.
+const GLOBAL_DEFAULTS_RESOLUTION_KEYS = [
+    'model_profile', 'commit_docs', 'research', 'plan_checker', 'verifier',
+    'nyquist_validation', 'post_planning_gaps', 'research_before_questions', 'parallelization', 'text_mode',
+    'resolve_model_ids', 'context_window', 'subagent_timeout', 'model_overrides',
+    'models', 'granularity', 'granularities', 'planning', 'dynamic_routing',
+    'effort', 'fast_mode', 'agent_skills', 'response_language', 'runtime',
+    'model_profile_overrides', 'model_policy',
+];
+// Module-level dedup keyed on the SORTED shadowed-key set: a later call with
+// the same shadowed set stays quiet, while a config that grows a new shadowed
+// key re-arms the warning. Stronger than _warnedUnknownConfigKeys (which keys
+// on insertion order) — same discipline, order-independent key.
+const _warnedShadowedGlobalKeys = new Set();
+function _warnShadowedGlobalDefaults(globalDefaults, globalPath) {
+    const shadowed = GLOBAL_DEFAULTS_RESOLUTION_KEYS.filter(k => k !== 'effort' && Object.prototype.hasOwnProperty.call(globalDefaults, k));
+    // Branch D also honors the nested alias workflow.post_planning_gaps (the
+    // `?? globalDefaults['workflow']?.['post_planning_gaps']` fallback in
+    // _globalBaseCfg) — a global file using only the nested form is equally
+    // shadowed, so it reports under its dotted name.
+    // #3894: research_before_questions gets the same nested-alias reporting.
+    const nestedAliasKeys = ['post_planning_gaps', 'research_before_questions'];
+    const wf = globalDefaults['workflow'];
+    if (wf && typeof wf === 'object' && !Array.isArray(wf)) {
+        for (const k of nestedAliasKeys) {
+            if (!shadowed.includes(k) && Object.prototype.hasOwnProperty.call(wf, k)) {
+                shadowed.push(`workflow.${k}`);
+            }
+        }
+    }
+    if (shadowed.length === 0)
+        return;
+    const dedupKey = shadowed.slice().sort().join(',');
+    if (_warnedShadowedGlobalKeys.has(dedupKey))
+        return;
+    _warnedShadowedGlobalKeys.add(dedupKey);
+    try {
+        process.stderr.write(`gsd-tools: warning: ${globalPath} sets ${shadowed.join(', ')} but a project config ` +
+            `takes precedence here — those global keys are ignored for model resolution. (#3532)\n`);
+    }
+    catch { /* stderr might be closed in some test harnesses */ }
 }
 // ─── FIX 2: Federated overlay helpers ────────────────────────────────────────
 /**
@@ -510,8 +592,18 @@ function _warnUnusableConfig(fault) {
  * diagnostic names the file. Before this, a trailing comma in config.json was
  * byte-identical to the file not existing: builtin defaults, degraded:false,
  * and the user's entire configuration silently discarded.
+ *
+ * `options.persist: false` (#3648) suppresses the two normalize-then-write-back
+ * side effects below. Resolution is otherwise identical — same precedence, same
+ * returned object — the migrated shape simply stays in memory. Callers that only
+ * ASK the config something (a predicate, a status readout) pass it so that a read
+ * cannot dirty the working tree; the ~30 callers that omit it keep persisting, so
+ * a legacy config is still migrated exactly once by ordinary use.
  */
 function loadConfigResolved(cwd, options = {}) {
+    // Opt-OUT, not opt-in: omitting the option must preserve the historical
+    // write-back for every existing caller.
+    const persist = options['persist'] !== false;
     // NOTE: loadConfigResolved resolves from cwd AS-IS (no walk-up).
     // Callers that need ancestor-anchoring (e.g. cmdAgentSkills) must do so
     // themselves via findProjectRoot() before calling this function.
@@ -564,24 +656,37 @@ function loadConfigResolved(cwd, options = {}) {
             if (rootRead.kind !== 'ok')
                 throw new Error('root config absent or unusable');
             rootParsed = rootRead.data;
-            const { parsed: rootNormalized, normalizations: rootNorms } = (0, configuration_cjs_1.normalizeLegacyKeys)(rootParsed);
+            const { parsed: rootNormalized, normalizations: rootNorms, skipped: rootSkipped } = (0, configuration_cjs_1.normalizeLegacyKeys)(rootParsed);
+            if (rootSkipped.length > 0) {
+                _warnUnusableInput({ reason: _UNUSABLE_REASON.CONFIG_SECTION_NOT_OBJECT, source: rootConfigPath });
+            }
             if (rootNorms.length > 0) {
                 for (const norm of rootNorms) {
                     if (norm.requiresFilesystem && !rootNormalized.planning?.['sub_repos']) {
                         const detected = getDetectedSubRepos();
                         if (detected.length > 0) {
-                            if (!rootNormalized.planning)
+                            // #3760: `if (!planning) planning = {}` treated a non-empty STRING as an
+                            // already-present section, and the next line then assigned onto a
+                            // primitive — a strict-mode TypeError the enclosing catch swallowed,
+                            // discarding the user's whole config. `requiresFilesystem` now only
+                            // reaches here when the section is absent or an object (configuration.cts
+                            // block 3 refuses otherwise and reports it via `skipped`), so this
+                            // narrowing chooses between merge and create and never discards.
+                            if (!(0, configuration_cjs_1.isConfigSection)(rootNormalized.planning)) {
                                 rootNormalized.planning = {};
+                            }
                             rootNormalized.planning['sub_repos'] = detected;
                             rootNormalized.planning['commit_docs'] = false;
                         }
                     }
                 }
                 rootParsed = rootNormalized;
-                try {
-                    (0, shell_command_projection_cjs_1.platformWriteSync)(rootConfigPath, JSON.stringify(rootParsed, null, 2));
+                if (persist) {
+                    try {
+                        (0, shell_command_projection_cjs_1.platformWriteSync)(rootConfigPath, JSON.stringify(rootParsed, null, 2));
+                    }
+                    catch { /* ignore */ }
                 }
-                catch { /* ignore */ }
             }
             else {
                 rootParsed = rootNormalized;
@@ -608,7 +713,10 @@ function loadConfigResolved(cwd, options = {}) {
         const fileHadKeys = Object.keys(read.data).length > 0;
         let configDirty = false;
         {
-            const { parsed: normalized, normalizations } = (0, configuration_cjs_1.normalizeLegacyKeys)(fileData);
+            const { parsed: normalized, normalizations, skipped } = (0, configuration_cjs_1.normalizeLegacyKeys)(fileData);
+            if (skipped.length > 0) {
+                _warnUnusableInput({ reason: _UNUSABLE_REASON.CONFIG_SECTION_NOT_OBJECT, source: configPath });
+            }
             if (normalizations.length > 0) {
                 Object.keys(fileData).forEach(k => delete fileData[k]);
                 Object.assign(fileData, normalized);
@@ -617,7 +725,8 @@ function loadConfigResolved(cwd, options = {}) {
                     if (norm.requiresFilesystem && !fileData.planning?.['sub_repos']) {
                         const detected = getDetectedSubRepos();
                         if (detected.length > 0) {
-                            if (!fileData.planning)
+                            // #3760 — see the identical guard on the root-config path above.
+                            if (!(0, configuration_cjs_1.isConfigSection)(fileData.planning))
                                 fileData.planning = {};
                             fileData.planning['sub_repos'] = detected;
                             fileData.planning['commit_docs'] = false;
@@ -632,14 +741,17 @@ function loadConfigResolved(cwd, options = {}) {
             if (detected.length > 0) {
                 const sorted = [...currentSubRepos].sort();
                 if (JSON.stringify(sorted) !== JSON.stringify(detected)) {
-                    if (!fileData.planning)
+                    // #3760 — reachable only when `planning` already yielded a non-empty
+                    // sub_repos array, so it is an object here; the narrowing keeps the
+                    // assignment total rather than relying on that from three frames away.
+                    if (!(0, configuration_cjs_1.isConfigSection)(fileData.planning))
                         fileData.planning = {};
                     fileData.planning['sub_repos'] = detected;
                     configDirty = true;
                 }
             }
         }
-        if (configDirty) {
+        if (configDirty && persist) {
             try {
                 (0, shell_command_projection_cjs_1.platformWriteSync)(configPath, JSON.stringify(fileData, null, 2));
             }
@@ -684,17 +796,19 @@ function loadConfigResolved(cwd, options = {}) {
             }
         }
         _warnUnknownProfileOverrides(parsed, '.planning/config.json');
-        const get = (key, nested) => {
-            if (parsed[key] !== undefined)
-                return parsed[key];
-            if (nested && parsed[nested.section] && typeof parsed[nested.section] === 'object' && parsed[nested.section] !== null) {
-                const sec = parsed[nested.section];
-                if (sec[nested.field] !== undefined) {
-                    return sec[nested.field];
-                }
-            }
-            return undefined;
-        };
+        const get = (key, nested) => _getConfigValue(parsed, key, nested);
+        /**
+         * Nested-ONLY read — no top-level fallback (#3648).
+         *
+         * `get()`'s flat-then-nested order exists for keys that have a legacy flat
+         * spelling `normalizeLegacyKeys` migrates (`branching_strategy`,
+         * `base_branch`, …); for those, honouring the flat key is back-compat. A key
+         * introduced with no legacy form has nothing to be compatible WITH, so
+         * routing it through `get()` would invent an undocumented top-level alias
+         * that silently outranks the canonical nested key. Use this instead for new
+         * `<section>.<field>` keys (round-4 external review).
+         */
+        const getNested = (section, field) => _getConfigNested(parsed, section, field);
         const parallelization = (() => {
             const val = get('parallelization');
             if (typeof val === 'boolean')
@@ -715,6 +829,8 @@ function loadConfigResolved(cwd, options = {}) {
             })(),
             search_gitignored: get('search_gitignored', { section: 'planning', field: 'search_gitignored' }) ?? defaults.search_gitignored,
             branching_strategy: get('branching_strategy', { section: 'git', field: 'branching_strategy' }) ?? defaults.branching_strategy,
+            base_branch: get('base_branch', { section: 'git', field: 'base_branch' }),
+            protected_branches: getNested('git', 'protected_branches'),
             phase_branch_template: get('phase_branch_template', { section: 'git', field: 'phase_branch_template' }) ?? defaults.phase_branch_template,
             milestone_branch_template: get('milestone_branch_template', { section: 'git', field: 'milestone_branch_template' }) ?? defaults.milestone_branch_template,
             quick_branch_template: get('quick_branch_template', { section: 'git', field: 'quick_branch_template' }) ?? defaults.quick_branch_template,
@@ -733,6 +849,7 @@ function loadConfigResolved(cwd, options = {}) {
             _auto_chain_active: get('_auto_chain_active', { section: 'workflow', field: '_auto_chain_active' }) ?? false,
             mode: get('mode') ?? 'interactive',
             sub_repos: get('sub_repos', { section: 'planning', field: 'sub_repos' }) ?? defaults.sub_repos,
+            pr_strict: get('pr_strict', { section: 'planning', field: 'pr_strict' }) ?? defaults.pr_strict,
             resolve_model_ids: get('resolve_model_ids') ?? defaults.resolve_model_ids,
             context_window: get('context_window') ?? defaults.context_window,
             phase_naming: get('phase_naming') ?? defaults.phase_naming,
@@ -751,11 +868,25 @@ function loadConfigResolved(cwd, options = {}) {
             fast_mode: (parsed['fast_mode']) || null,
             agent_skills: (parsed['agent_skills']) || {},
             agent_skills_security: (parsed['agent_skills_security']) || null,
+            // #3587: phase_commit_docs.<phase-id> — a dynamic-key family shaped like
+            // agent_skills above (`{ "<phase-id>": boolean }`). Must be threaded here
+            // explicitly: `_baseConfig` is a hand-maintained allowlist, so a key that
+            // is only in config-schema.manifest.json's dynamicKeyPatterns (and not
+            // projected here) is silently dropped on read — the exact `features`-key
+            // failure mode this module's own A3 test guards against.
+            phase_commit_docs: (parsed['phase_commit_docs']) || {},
             manager: (parsed['manager']) || {},
             response_language: get('response_language') || null,
             claude_md_path: get('claude_md_path') || null,
             claude_md_assembly: (parsed['claude_md_assembly']) || null,
             phase_id_convention: get('phase_id_convention') ?? null,
+            // #3691: the documented central review key. Declared here (not federated —
+            // it is central, see config-schema.manifest.json validKeys) so the existing
+            // `review.*` per-lane keys the federated overlay below adds land as SIBLINGS
+            // on this same object rather than being clobbered by it.
+            review: {
+                max_prompt_tokens: get('max_prompt_tokens', { section: 'review', field: 'max_prompt_tokens' }) ?? defaults.max_prompt_tokens,
+            },
         };
         // ADR-857 phase 3b: federated config overlay
         try {
@@ -777,6 +908,22 @@ function loadConfigResolved(cwd, options = {}) {
         // A1 vs A2: disambiguate by whether a real workstream was requested.
         // Fix 4: empty-string ws ('') resolves the root path → source:'root'.
         const source = wsRequested ? 'workstream' : 'root';
+        // #3532 (10b): a parsed project config means Branch D never runs, so every
+        // key ~/.gsd/defaults.json sets that Branch D would honor is silently inert
+        // here. Observation only — one deduped stderr warning; precedence is
+        // untouched. Faults in the global file stay silent in this branch (the
+        // project config governs; the nearer file is the actionable one).
+        try {
+            const shadowHome = process.env['GSD_HOME'] || node_os_1.default.homedir();
+            const shadowPath = node_path_1.default.join(shadowHome, '.gsd', 'defaults.json');
+            const shadowRead = _readConfigFile(shadowPath);
+            if (shadowRead.kind === 'ok') {
+                _warnShadowedGlobalDefaults(shadowRead.data, shadowPath);
+            }
+        }
+        catch {
+            // Observation only — never let the diagnostic perturb resolution.
+        }
         // This config parsed — but a DIFFERENT file on the resolution path may not
         // have. A workstream config that loads cleanly while the root config it
         // inherits from is corrupt is still a degraded resolution: the root's
@@ -800,8 +947,15 @@ function loadConfigResolved(cwd, options = {}) {
         // Fix 2: Early intercept — workstream requested but ws config.json absent (or dir absent)
         // AND root config was loaded. Covers BOTH "dir exists, no config.json" AND "dir absent".
         // This delivers the #1366 acceptance criterion: nonexistent GSD_WORKSTREAM yields root, degraded.
+        //
+        // Both fallback recursions below forward `options` and override ONLY `workstream`.
+        // A bare `{ workstream: null }` silently dropped every other option, so a caller's
+        // `persist: false` was discarded on exactly this path and the root config was
+        // rewritten by a read (#3648, found by external review). The explicit
+        // `workstream: null` still wins the `hasOwnProperty` check at the top of this
+        // function, so spreading cannot let `workstreamContext` reintroduce a workstream.
         if (wsRequested && rootParsed) {
-            const fb = loadConfigResolved(cwd, { workstream: null });
+            const fb = loadConfigResolved(cwd, { ...options, workstream: null });
             return fallback({ config: fb.config, source: 'root', degraded: true });
         }
         // Branch B, C, D, E
@@ -809,7 +963,7 @@ function loadConfigResolved(cwd, options = {}) {
             if (rootParsed) {
                 // Branch B: workstream requested but ws config.json absent; root config present.
                 // (Only reached when wsRequested is false — e.g. ws='' with .planning/workstreams//config.json)
-                const fb = loadConfigResolved(cwd, { workstream: null });
+                const fb = loadConfigResolved(cwd, { ...options, workstream: null });
                 return fallback({ config: fb.config, source: 'root', degraded: true });
             }
             // Branch C: .planning/ exists but no config.json and no root config — federated/builtin defaults
@@ -847,6 +1001,12 @@ function loadConfigResolved(cwd, options = {}) {
                 post_planning_gaps: (globalDefaults['post_planning_gaps'])
                     ?? globalDefaults['workflow']?.['post_planning_gaps']
                     ?? defaults.post_planning_gaps,
+                // #3894: same nested-alias shape as post_planning_gaps above — the key
+                // was silently dropped from global defaults, so it was unavailable at
+                // user scope AND inert at project scope on the /gsd-quick path.
+                research_before_questions: (globalDefaults['research_before_questions'])
+                    ?? globalDefaults['workflow']?.['research_before_questions']
+                    ?? defaults.research_before_questions,
                 parallelization: (globalDefaults['parallelization']) ?? defaults.parallelization,
                 text_mode: (globalDefaults['text_mode']) ?? defaults.text_mode,
                 resolve_model_ids: (globalDefaults['resolve_model_ids']) ?? defaults.resolve_model_ids,
@@ -906,8 +1066,12 @@ module.exports = {
     CONFIG_DEFAULTS,
     _getConfigDefault,
     _getNestedConfigDefault,
+    _getConfigValue,
+    _getConfigNested,
     _deepMergeConfig,
     _warnedUnknownConfigKeys,
+    _warnedShadowedGlobalKeys,
+    GLOBAL_DEFAULTS_RESOLUTION_KEYS,
     _warnUnknownProfileOverrides,
     _resetRuntimeWarningCacheForTests,
     _warnedConfigKeys,

package/gsd-core/bin/lib/config.cjs

@@ -16,6 +16,9 @@ const node_os_1 = __importDefault(require("node:os"));
 const io = require("./io.cjs");
 const { output, error, ERROR_REASON } = io;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitMod = require("./cli-exit.cjs");
+const { ExitError } = cliExitMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoader = require("./config-loader.cjs");
 const { CONFIG_DEFAULTS } = configLoader;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
@@ -31,6 +34,13 @@ const { VALID_CONFIG_KEYS, isValidConfigKey, getCapabilityConfigSchema } = confi
 const secrets_cjs_1 = require("./secrets.cjs");
 const review_reviewer_selection_cjs_1 = require("./review-reviewer-selection.cjs");
 const configuration_cjs_1 = require("./configuration.cjs");
+// #3760: the ADR-1411 out-of-band diagnostic. It lives here rather than inside
+// `migrateOnDisk` because `configuration.cjs` must stay loadable from an install
+// layout holding only itself plus its manifests (#3571) — see the note at the top
+// of configuration.cts.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const unusableInputModule = require("./unusable-input.cjs");
+const { UNUSABLE_REASON, warnUnusableInput } = unusableInputModule;
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CONFIG_KEY_SUGGESTIONS = {
     'workflow.nyquist_validation_enabled': 'workflow.nyquist_validation',
@@ -68,9 +78,21 @@ const SCHEMA_DEFAULTS = {
     'planner.stall_detect_interval_minutes': 5,
     'planner.stall_threshold_minutes': 10,
     'git.create_tag': true,
+    // #1689: per-plan agent_hint executor routing — default-on. A no-op for plans
+    // without an agent_hint field, so existing dispatch is byte-identical.
+    'workflow.agent_hint_routing': true,
     // Derived from the defaults manifest rather than restated, so the manifest
     // stays the single source of truth for the smart-zone budget (#2630).
     'workflow.smart_zone_tokens': CONFIG_DEFAULTS.smart_zone_tokens,
+    // #2971: /gsd:pr-branch reads this key directly; an absent key must resolve to the
+    // manifest default rather than "Key not found". Derived from the defaults manifest so
+    // the manifest stays the single source of truth.
+    'planning.pr_strict': CONFIG_DEFAULTS.pr_strict,
+    // #3801: execute-plan reads this key on every run; an absent key must resolve
+    // to the manifest default (2) rather than "Key not Found" — previously the
+    // effective default existed only as the workflow's shell fallback and the
+    // docs disagreed (settings-advanced said 3). Manifest stays the one owner.
+    'workflow.inline_plan_threshold': CONFIG_DEFAULTS.inline_plan_threshold,
 };
 /**
  * Resolve a schema-level default for an absent key (#2256). Checks the legacy
@@ -118,6 +140,35 @@ function validateKnownConfigKeyPath(keyPath) {
         error(`Unknown config key: ${keyPath}. Did you mean ${suggested}?`, ERROR_REASON.CONFIG_INVALID_KEY);
     }
 }
+/**
+ * Is `value` an acceptable `git.protected_branches` list (#3552)?
+ *
+ * A non-empty array whose every element is a string with non-whitespace
+ * content. Exported so a property test can pin this predicate against the
+ * resolver's own per-entry filter in `git-base-branch.cts` — `config-set` must
+ * only accept lists the resolver will honour in full, with nothing rejected.
+ * The two are deliberately different shapes (all-or-nothing here, per-entry
+ * there, because a direct file edit bypasses this check), so nothing keeps them
+ * agreeing except a test that asks both.
+ */
+function isValidProtectedBranches(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return false;
+    const entries = value;
+    // Index, do NOT use `.every()`. `.every()` SKIPS holes, so a sparse array
+    // (`["main", , "develop"]`) passed this check while the resolver's `for...of`
+    // — which yields `undefined` for a hole — rejected that element. The two
+    // surfaces then disagreed about the same value. JSON cannot express a hole,
+    // so neither surface meets one in production, but "unreachable" is not a
+    // reason to leave two definitions of the same predicate contradicting each
+    // other (round-4 external review).
+    for (let i = 0; i < entries.length; i += 1) {
+        const branch = entries[i];
+        if (typeof branch !== 'string' || branch.trim().length === 0)
+            return false;
+    }
+    return true;
+}
 function validateShipPrBodySections(value) {
     if (!Array.isArray(value)) {
         error('Invalid ship.pr_body_sections value. Expected a JSON array of section objects.');
@@ -652,7 +703,7 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     const val = value;
     validateKnownConfigKeyPath(kp);
     if (!isValidConfigKey(kp, cwd)) {
-        error(`Unknown config key: "${kp}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.<agent-type>, features.<feature_name>`, ERROR_REASON.CONFIG_INVALID_KEY);
+        error(`Unknown config key: "${kp}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.<agent-type>, features.<feature_name>, phase_commit_docs.<phase-id>`, ERROR_REASON.CONFIG_INVALID_KEY);
     }
     // Parse value (handle booleans, numbers, and JSON arrays/objects)
     let parsedValue = val;
@@ -736,12 +787,23 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
             error(`Invalid workflow.post_planning_gaps '${val}'. Must be a boolean (true or false).`);
         }
     }
+    // Per-plan executor routing via agent_hint frontmatter (#1689)
+    if (kp === 'workflow.agent_hint_routing') {
+        if (typeof parsedValue !== 'boolean') {
+            error(`Invalid workflow.agent_hint_routing '${val}'. Must be a boolean (true or false).`);
+        }
+    }
     // #3086 — git.create_tag: boolean only
     if (kp === 'git.create_tag') {
         if (typeof parsedValue !== 'boolean') {
             error(`Invalid git.create_tag '${val}'. Must be a boolean (true or false).`);
         }
     }
+    if (kp === 'git.protected_branches') {
+        if (!isValidProtectedBranches(parsedValue)) {
+            error(`Invalid git.protected_branches '${val}'. Must be a non-empty array of non-empty branch names.`);
+        }
+    }
     if (kp === 'ship.pr_body_sections') {
         validateShipPrBodySections(parsedValue);
     }
@@ -917,6 +979,16 @@ function cmdConfigGet(cwd, keyPath, raw, defaultValue) {
         }
     }
     catch (err) {
+        // ADR-3889: error() now throws ExitError (carries no message) instead of
+        // calling process.exit() directly. The message-sniffing check below
+        // (`.startsWith('No config.json')`) can never match an ExitError raised
+        // by the "no config.json" error() call above it — ExitError.message
+        // defaults to `process exit ${code}` when no message is passed — so
+        // without this unconditional guard that ExitError falls through and gets
+        // re-wrapped as a WRONG reason (CONFIG_PARSE_FAILED instead of
+        // CONFIG_NO_FILE) with a nonsense message, plus a duplicate stderr write.
+        if (err instanceof ExitError)
+            throw err;
         if (err.message.startsWith('No config.json'))
             throw err;
         error('Failed to read config.json: ' + err.message, ERROR_REASON.CONFIG_PARSE_FAILED);
@@ -1111,16 +1183,42 @@ function cmdConfigPath(cwd, _raw, workstreamContext = null) {
  */
 function cmdMigrateConfig(cwd, raw) {
     const ws = process.env['GSD_WORKSTREAM'] || null;
-    const report = (0, configuration_cjs_1.migrateOnDisk)(cwd, ws || undefined);
+    // #3749: resolve the migration target through the project-aware resolver so
+    // GSD_PROJECT scopes the write; migrateOnDisk itself cannot (see its
+    // configPathOverride note).
+    const scopedConfigPath = node_path_1.default.join(planningDir(cwd, ws || undefined), 'config.json');
+    const report = (0, configuration_cjs_1.migrateOnDisk)(cwd, ws || undefined, scopedConfigPath);
+    // #3760: deduplicated on (path, reason), so a repeated invocation stays quiet.
+    if (report.skipped.length > 0) {
+        warnUnusableInput({
+            reason: UNUSABLE_REASON.CONFIG_SECTION_NOT_OBJECT,
+            source: node_path_1.default.join(planningDir(cwd, ws || undefined), 'config.json'),
+        });
+    }
     if (raw) {
-        if (!report.migrated) {
+        // #3760: a refused migration is NOT an already-canonical config. Reporting
+        // "no legacy keys found" when a legacy key was found and declined would send
+        // the user away believing there is nothing to fix — and the thing to fix is
+        // the one thing only they can fix, by hand.
+        const declined = report.skipped;
+        const declinedLines = declined.map(s => `  ${s.from} → ${s.to}  SKIPPED: '${s.section}' holds a ${s.sectionType}, not an object`);
+        if (!report.migrated && declined.length === 0) {
             const msg = 'No legacy keys found — config is already canonical.';
             output(msg, true, msg);
         }
+        else if (!report.migrated) {
+            const lines = [
+                'Not migrated — every legacy key found was left in place:',
+                ...declinedLines,
+                'Fix the section by hand, then re-run. Nothing was written.',
+            ].join('\n');
+            output(lines, true, lines);
+        }
         else {
             const lines = [
                 `Migrated: ${String(report.wrote)}`,
                 ...report.normalizations.map(n => `  ${n.from} → ${n.to}`),
+                ...declinedLines,
             ].join('\n');
             output(lines, true, lines);
         }
@@ -1142,4 +1240,5 @@ module.exports = {
     // Exported for programmatic use by capability-writer and tests
     setConfigValue,
     setConfigValues,
+    isValidProtectedBranches,
 };