@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -290,6 +290,56 @@ 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', '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.
+    if (!shadowed.includes('post_planning_gaps')) {
+        const wf = globalDefaults['workflow'];
+        if (wf && typeof wf === 'object' && !Array.isArray(wf) &&
+            Object.prototype.hasOwnProperty.call(wf, 'post_planning_gaps')) {
+            shadowed.push('workflow.post_planning_gaps');
+        }
+    }
+    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 ────────────────────────────────────────
 /**
@@ -751,10 +801,18 @@ 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,
         };
         // ADR-857 phase 3b: federated config overlay
         try {
@@ -776,6 +834,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
@@ -907,6 +981,8 @@ module.exports = {
     _getNestedConfigDefault,
     _deepMergeConfig,
     _warnedUnknownConfigKeys,
+    _warnedShadowedGlobalKeys,
+    GLOBAL_DEFAULTS_RESOLUTION_KEYS,
     _warnUnknownProfileOverrides,
     _resetRuntimeWarningCacheForTests,
     _warnedConfigKeys,

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

@@ -65,7 +65,12 @@ const SCHEMA_DEFAULTS = {
     'context_window': 200000,
     'executor.stall_detect_interval_minutes': 5,
     'executor.stall_threshold_minutes': 10,
+    '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,
@@ -289,10 +294,19 @@ function buildNewProjectConfig(userChoices) {
     const ud = userDefaults;
     const ch = choices;
     const hd = hardcoded;
+    // #2840: `runtime` is host-specific (written by the installer for whichever
+    // runtime's install ran last). On a machine with 2+ runtimes, it poisons every
+    // new project config — e.g. a Codex install's `runtime:"codex"` leaks into
+    // Claude Code projects, resolving agents to wrong model IDs. `resolve_model_ids`
+    // already has a per-install guard (#2297); `runtime` gets the same treatment
+    // by excluding it from the defaults spread. Projects detect the runtime from
+    // the install path / .gsd-runtime marker, not from a copied config key.
+    const safeDefaults = { ...userDefaults };
+    delete safeDefaults['runtime'];
     // Three-level deep merge: hardcoded <- userDefaults <- choices
     const config = {
         ...hardcoded,
-        ...userDefaults,
+        ...safeDefaults,
         ...choices,
         git: {
             ...hd['git'],
@@ -641,7 +655,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;
@@ -725,6 +739,12 @@ 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') {

package/gsd-core/bin/lib/context-composer.cjs

@@ -0,0 +1,278 @@
+"use strict";
+/**
+ * Context Composer — shared budget-trim seam (ADR-1671 Decision item 2).
+ *
+ * Extracted from the five-step trim ladder in `prompt-budget.cts` by issue
+ * #2929 (epic #1671 Phase 2) so a second consumer — per-runtime artifact
+ * emission, in a later phase — can reuse the exact same trimming behavior
+ * without re-deriving it. `prompt-budget.applyBudget` is routed through this
+ * module in a follow-up commit, which asserts byte-identical output against
+ * a committed corpus; the algorithm here is a characterization of that
+ * existing behavior, not a redesign.
+ *
+ * THE COMPOSER DECIDES, THE CALLER RENDERS. `composeWithinBudget` never
+ * joins fragments and never returns a rendered string — it returns a plan of
+ * surviving fragments with their (possibly trimmed) content, plus metadata
+ * describing what happened. Rendering is prompt-specific: the review-prompt
+ * consumer assembles Markdown sections with blank-line separators; the
+ * per-runtime emission consumer renders differently. Keeping the decision
+ * (what survives, in what shape) separate from the render (how it is joined)
+ * is what lets both consumers share this module.
+ *
+ * The budget unit is injected via `measure(text) => number` rather than
+ * hardcoded to a token estimator: `prompt-budget` passes its chars/4
+ * estimator, per-runtime emission passes a byte counter. `charsPerUnit` in
+ * `ComposeOptions` is the inverse of `measure` (4 for chars/4, 1 for a byte
+ * counter) and is what lets `proportional-truncate`'s char-budget math stay
+ * unit-agnostic.
+ *
+ * ADR-1671's literal contract describes "priority + binary-search cutoff"
+ * trimming. That description cannot express this module's actual shape:
+ * head-shrink (structural, line-bounded) and proportional-truncate-with-floor
+ * (per-fragment guaranteed minimum, not a single global cutoff) are not
+ * binary-search cutoffs. `ShrinkStrategy` — not a numeric priority field — is
+ * the core abstraction here, and a `cutoff` strategy is expected to join this
+ * closed set once per-runtime emission needs binary-search behavior. Relatedly,
+ * `verbatim` and `drop` fragments are never reordered by importance: survival
+ * and drop order both follow DECLARATION order (the order fragments appear in
+ * `ComposeInput.fragments`), not a numeric priority.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.headShrink = headShrink;
+exports.tailTruncate = tailTruncate;
+exports.composeWithinBudget = composeWithinBudget;
+/**
+ * Head-shrink a string to at most `maxLines` lines.
+ *
+ * Copied verbatim from `prompt-budget.cts` (formerly private) — do not
+ * "improve" it; a committed corpus depends on this exact behavior.
+ */
+function headShrink(text, maxLines) {
+    if (maxLines <= 0)
+        return '';
+    let idx = -1;
+    let seen = 0;
+    while (seen < maxLines) {
+        idx = text.indexOf('\n', idx + 1);
+        if (idx === -1)
+            return text;
+        seen += 1;
+    }
+    return text.slice(0, idx);
+}
+/**
+ * Tail-truncate a string to at most `maxChars` characters.
+ *
+ * Copied verbatim from `prompt-budget.cts` (formerly private) — do not
+ * "improve" it; a committed corpus depends on this exact behavior.
+ */
+function tailTruncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars);
+}
+const isPresent = (w) => w.required || Boolean(w.content);
+const costOf = (w, measure) => isPresent(w) ? measure(w.wrapper) + measure(w.content) : 0;
+const totalOf = (working, measure) => working.reduce((sum, w) => sum + costOf(w, measure), 0);
+/**
+ * Trim a set of fragments to fit within `budget`, following the exact
+ * five-step ladder characterized from `prompt-budget.applyBudget`:
+ * head-shrink, then group proportional-truncate, then declaration-order
+ * drops — each pass individually guarded by the running total against the
+ * content budget, walked once in declaration order.
+ *
+ * Returns a plan (surviving fragment content + metadata); it never renders.
+ */
+function composeWithinBudget(input) {
+    const { fragments, budget, measure, options = {} } = input;
+    const { safetyMarginPct = 0, reserve = 0, charsPerUnit = 1, minimumFor } = options;
+    const effectiveBudget = Math.floor(budget * (1 - safetyMarginPct / 100));
+    const seenIds = new Set();
+    const working = [];
+    let sawNonIsolate = false;
+    let isolatePrefix = '';
+    for (const f of fragments) {
+        if (seenIds.has(f.id)) {
+            throw new TypeError(`composeWithinBudget: duplicate fragment id "${f.id}"`);
+        }
+        seenIds.add(f.id);
+        const isolate = f.isolate === true;
+        if (isolate) {
+            if (sawNonIsolate) {
+                throw new TypeError(`composeWithinBudget: isolate fragment "${f.id}" declared after a non-isolate fragment; ` +
+                    'isolate fragments must form a leading, contiguous prefix of ComposeInput.fragments');
+            }
+            isolatePrefix += (f.wrapper ?? '') + f.content;
+        }
+        else {
+            sawNonIsolate = true;
+        }
+        working.push({
+            id: f.id,
+            wrapper: f.wrapper ?? '',
+            strategy: f.strategy,
+            required: f.required === true,
+            group: f.group,
+            originalLength: f.content.length,
+            flexReserve: f.flexReserve ?? 0,
+            isolate,
+            content: f.content,
+            shrunk: false,
+            truncated: false,
+        });
+    }
+    // Minimum-set pre-check. Wrappers are deliberately NOT counted here, and
+    // the reserve is deliberately EXCLUDED — this checks the floor, not the
+    // steady-state budget.
+    if (minimumFor) {
+        const minTotal = fragments.reduce((sum, f) => sum + measure(minimumFor(f) ?? ''), 0);
+        if (minTotal > effectiveBudget) {
+            return {
+                fragments: [],
+                metadata: {
+                    budget,
+                    effectiveBudget,
+                    contentBudget: effectiveBudget,
+                    underPressure: false,
+                    omitted: [],
+                    shrunk: [],
+                    floored: [],
+                    truncationPct: 0,
+                    hardFailed: true,
+                    hardFailReason: 'minimum-set',
+                    isolatePrefix,
+                },
+            };
+        }
+    }
+    const total = () => totalOf(working, measure);
+    const baseline = total();
+    const underPressure = baseline > effectiveBudget;
+    // The reserve is deducted ONLY when under pressure — deducting it
+    // unconditionally drops sections `reserve` units early
+    // (CONTEXT.md LEARNING.prompt-budget.boundary-gap, PR #3708).
+    const contentBudget = underPressure ? effectiveBudget - reserve : effectiveBudget;
+    const omitted = [];
+    const shrunk = [];
+    const floored = [];
+    const truncation = { pct: 0 };
+    const processedGroups = new Set();
+    for (const w of working) {
+        // Isolate fragments are the byte-stable canonical prefix (ADR-1671):
+        // never trimmed, shrunk, or dropped, regardless of declared strategy.
+        // They still count toward the budget via total()/costOf above.
+        if (w.isolate) {
+            continue;
+        }
+        switch (w.strategy.kind) {
+            case 'verbatim': {
+                continue;
+            }
+            case 'head-shrink': {
+                if (total() > contentBudget && isPresent(w)) {
+                    const next = headShrink(w.content, w.strategy.maxLines);
+                    if (next !== w.content) {
+                        if (w.flexReserve > 0 && measure(next) < w.flexReserve) {
+                            // Shrinking would undershoot the floor — leave untouched.
+                            floored.push(w.id);
+                        }
+                        else {
+                            w.content = next;
+                            w.shrunk = true;
+                            shrunk.push(w.id);
+                        }
+                    }
+                }
+                continue;
+            }
+            case 'proportional-truncate': {
+                const groupKey = w.group ?? w.id;
+                if (processedGroups.has(groupKey))
+                    continue;
+                processedGroups.add(groupKey);
+                if (total() > contentBudget) {
+                    const members = working.filter((m) => m.strategy.kind === 'proportional-truncate' && (m.group ?? m.id) === groupKey && !m.isolate);
+                    const memberContentTotal = members.reduce((sum, m) => sum + measure(m.content), 0);
+                    const overhead = total() - memberContentTotal;
+                    const groupBudget = contentBudget - overhead;
+                    const groupContentTotal = memberContentTotal;
+                    if (groupBudget > 0 && groupBudget < groupContentTotal) {
+                        const originalChars = members.reduce((sum, m) => sum + m.originalLength, 0);
+                        const charsBudget = groupBudget * charsPerUnit;
+                        for (const m of members) {
+                            const floorChars = m.strategy.kind === 'proportional-truncate' ? m.strategy.floorChars : 0;
+                            const share = originalChars > 0 ? Math.floor((m.originalLength / originalChars) * charsBudget) : 0;
+                            const charsForReserve = m.flexReserve * charsPerUnit;
+                            const capWithoutReserve = Math.max(share, floorChars);
+                            const maxChars = Math.max(capWithoutReserve, charsForReserve);
+                            const beforeTruncate = m.content;
+                            const next = tailTruncate(m.content, maxChars);
+                            if (next !== beforeTruncate) {
+                                m.content = next;
+                                m.truncated = true;
+                            }
+                            // flexReserve raised the cap above what the unreserved cap
+                            // would have allowed, and that raised cap actually mattered
+                            // (the unreserved cap would have cut into the content) —
+                            // this holds whether the reserve prevented a trim outright
+                            // (next === beforeTruncate) or merely shrank the trim below
+                            // what the unreserved cap would have produced. Either way a
+                            // cut was prevented, so it belongs in `floored`.
+                            if (m.flexReserve > 0 &&
+                                maxChars > capWithoutReserve &&
+                                capWithoutReserve < beforeTruncate.length &&
+                                !floored.includes(m.id)) {
+                                floored.push(m.id);
+                            }
+                        }
+                        const newChars = members.reduce((sum, m) => sum + m.content.length, 0);
+                        if (originalChars > 0) {
+                            truncation.pct = ((originalChars - newChars) / originalChars) * 100;
+                        }
+                    }
+                }
+                continue;
+            }
+            case 'drop': {
+                if (total() > contentBudget && isPresent(w) && Boolean(w.content)) {
+                    // Dropping always takes a fragment to 0, and 0 is below any
+                    // positive floor — so ANY flexReserve > 0 disables drop entirely
+                    // for this fragment, not just when its current size already sits
+                    // at/under the floor.
+                    if (w.flexReserve > 0) {
+                        floored.push(w.id);
+                    }
+                    else {
+                        w.content = '';
+                        omitted.push(w.id);
+                    }
+                }
+                continue;
+            }
+        }
+    }
+    const composedFragments = working.map((w) => ({
+        id: w.id,
+        content: w.content,
+        wrapper: w.wrapper,
+        present: isPresent(w),
+        shrunk: w.shrunk,
+        truncated: w.truncated,
+    }));
+    return {
+        fragments: composedFragments,
+        metadata: {
+            budget,
+            effectiveBudget,
+            contentBudget,
+            underPressure,
+            omitted,
+            shrunk,
+            floored,
+            truncationPct: truncation.pct,
+            hardFailed: false,
+            hardFailReason: null,
+            isolatePrefix,
+        },
+    };
+}