@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.6

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

@@ -63,9 +63,9 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { findPhaseInternal } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix } = phaseId;
+const { escapeRegex, normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;
-const { planningPaths, planningDir, planningRoot, getActiveWorkstream, findContextMdIn, } = planningWorkspace;
+const { planningPaths, planningDir, planningRoot, listAvailableWorkstreams, getActiveWorkstream, findContextMdIn, } = planningWorkspace;
 const { determinePhaseStatus } = commandsMod;
 const { extractFrontmatter } = frontmatterMod;
 const { readVerificationStatus } = verificationMod;
@@ -74,6 +74,37 @@ const { evaluateUatPassed } = uatPredicateMod;
 void stripShippedMilestones;
 // Accept all bold/colon variants of the Requirements header (#2769)
 const REQUIREMENTS_HEADER_RE = /^\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]*)$/m;
+// #2056/#2104: isForeignPrefixedPhaseQuery is imported from phase-id.cts
+// (the canonical predicate). parsePhasePrefix is no longer needed locally.
+// phaseInfoMatchesExactPrefix and roadmapPhaseMatchesExactPrefix are local
+// helpers that post-filter the lookup results for foreign-prefix queries.
+function phaseInfoMatchesExactPrefix(phaseInfo, phase) {
+    const num = phaseInfo?.['phase_number'];
+    const numStr = typeof num === 'string' ? num : (typeof num === 'number' ? String(num) : '');
+    return numStr.toUpperCase() === phase.toUpperCase();
+}
+function roadmapPhaseMatchesExactPrefix(roadmapPhase, phase) {
+    const sectionRaw = roadmapPhase?.['section'];
+    const section = typeof sectionRaw === 'string' ? sectionRaw : '';
+    return new RegExp(`^#{2,4}\\s*Phase\\s+${escapeRegex(phase)}(?:\\b|\\s|:)`, 'i').test(section);
+}
+// #2104: shared helpers that wrap findPhaseInternal / getRoadmapPhaseInternal
+// with the #2056 foreign-prefix guard, so every init command gets the same
+// protection without duplicating the guard logic at each call site.
+function guardedFindPhase(cwd, phase, projectCode) {
+    let phaseInfo = findPhaseInternal(cwd, phase);
+    if (isForeignPrefixedPhaseQuery(phase, projectCode) && !phaseInfoMatchesExactPrefix(phaseInfo, phase)) {
+        phaseInfo = null;
+    }
+    return phaseInfo;
+}
+function guardedGetRoadmapPhase(cwd, phase, projectCode) {
+    let roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    if (isForeignPrefixedPhaseQuery(phase, projectCode) && !roadmapPhaseMatchesExactPrefix(roadmapPhase, phase)) {
+        roadmapPhase = null;
+    }
+    return roadmapPhase;
+}
 function listPhaseSummaryFiles(phaseDir) {
     return scanPhasePlans(phaseDir)['summaryFiles'];
 }
@@ -229,9 +260,9 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
         error('phase required for init execute-phase');
     }
     const config = loadConfig(cwd);
-    let phaseInfo = findPhaseInternal(cwd, phase);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
     const milestone = getMilestoneInfo(cwd);
-    const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived'] && roadmapPhase?.['found']) {
         phaseInfo = null;
     }
@@ -332,8 +363,9 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
         error('phase required for init plan-phase');
     }
     const config = loadConfig(cwd);
-    let phaseInfo = findPhaseInternal(cwd, phase);
-    const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    // #2056/#2104: foreign-prefixed queries must not collapse to numeric phases.
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived'] && roadmapPhase?.['found']) {
         phaseInfo = null;
     }
@@ -573,6 +605,9 @@ function cmdInitQuick(cwd, description, raw) {
         executor_model: resolveModelInternal(cwd, 'gsd-executor'),
         checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
         verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
+        // #2072: the quick review step spawns gsd-code-reviewer; resolve its own model
+        // so model_overrides / models.verification apply (was reusing executor_model).
+        reviewer_model: resolveModelInternal(cwd, 'gsd-code-reviewer'),
         commit_docs: config.commit_docs,
         branch_name: quickBranchName,
         quick_id: quickId,
@@ -637,15 +672,15 @@ function cmdInitVerifyWork(cwd, phase, raw) {
     }
     const config = loadConfig(cwd);
     const _slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
-    let phaseInfo = findPhaseInternal(cwd, phase);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived']) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             phaseInfo = null;
         }
     }
     if (!phaseInfo) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -694,9 +729,9 @@ function cmdInitVerifyWork(cwd, phase, raw) {
 }
 function cmdInitPhaseOp(cwd, phase, raw) {
     const config = loadConfig(cwd);
-    let phaseInfo = findPhaseInternal(cwd, phase);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived']) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -717,7 +752,7 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         }
     }
     if (!phaseInfo) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -874,8 +909,8 @@ function cmdInitMilestoneOp(cwd, raw) {
         const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
         const roadmapRaw = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const currentSection = extractCurrentMilestone(roadmapRaw, cwd);
-        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:/gi;
+        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
         let m;
         while ((m = phasePattern.exec(currentSection)) !== null) {
             if (/^999(?:\.|$)/.test(m[1]))
@@ -896,7 +931,7 @@ function cmdInitMilestoneOp(cwd, raw) {
         for (const e of entries) {
             if (!e.isDirectory())
                 continue;
-            const m = stripProjectCodePrefix(e.name).match(/^(\d+[A-Z]?(?:\.\d+)*)/);
+            const m = stripProjectCodePrefix(e.name).match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`));
             if (!m)
                 continue;
             diskPhaseDirs.set(canonicalizePhase(m[1]), e.name);
@@ -1024,13 +1059,13 @@ function cmdInitManager(cwd, raw) {
         }
     })();
     const _checkboxStates = new Map();
-    const _cbPattern = /-\s*\[(x| )\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
+    const _cbPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
     let _cbMatch;
     while ((_cbMatch = _cbPattern.exec(content)) !== null) {
         _checkboxStates.set(_cbMatch[2], _cbMatch[1].toLowerCase() === 'x');
     }
-    // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-    const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
+    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
     const phases = [];
     let match;
     while ((match = phasePattern.exec(content)) !== null) {
@@ -1148,7 +1183,7 @@ function cmdInitManager(cwd, raw) {
         .filter((p) => p['phase_complete'] === true)
         .map((p) => normalizePhaseNumber(p['number'])));
     const phaseMap = new Map(phases.map((p) => [normalizePhaseNumber(p['number']), p]));
-    const _allCompletedPattern = /-\s*\[x\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
+    const _allCompletedPattern = new RegExp(`-\\s*\\[x\\]\\s*.*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
     let _allMatch;
     while ((_allMatch = _allCompletedPattern.exec(rawContent)) !== null) {
         const phaseNum = normalizePhaseNumber(_allMatch[1]);
@@ -1180,7 +1215,7 @@ function cmdInitManager(cwd, raw) {
             phase['deps_satisfied'] = true;
         }
         else {
-            const depNums = phase['depends_on'].match(/\d+[A-Z]?(?:\.\d+)*/gi) || [];
+            const depNums = phase['depends_on'].match(new RegExp(`${PHASE_NUMBER_TOKEN_SOURCE}`, 'gi')) || [];
             phase['deps_satisfied'] = depNums.every((n) => completedNums.has(normalizePhaseNumber(n)));
             phase['dep_phases'] = depNums;
         }
@@ -1319,18 +1354,7 @@ function cmdInitProgress(cwd, raw) {
     // reporting a stale root milestone. Require an explicit workstream instead.
     // Mirror planningDir's resolution (GSD_WORKSTREAM env > stored active pointer) so
     // an explicit --ws (which sets GSD_WORKSTREAM) satisfies the check.
-    const _wsRoot = node_path_1.default.join(planningRoot(cwd), 'workstreams');
-    let _availableWorkstreams = [];
-    try {
-        _availableWorkstreams = node_fs_1.default
-            .readdirSync(_wsRoot, { withFileTypes: true })
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort();
-    }
-    catch {
-        /* no workstreams dir → flat mode */
-    }
+    const _availableWorkstreams = listAvailableWorkstreams(cwd);
     const _resolvedWorkstream = process.env['GSD_WORKSTREAM'] || getActiveWorkstream(cwd);
     if (_availableWorkstreams.length > 0 && !_resolvedWorkstream) {
         error(`init.progress requires a workstream in workstream mode — no active workstream is set, so root STATE.md (likely stale) would be reported. ` +
@@ -1346,14 +1370,14 @@ function cmdInitProgress(cwd, raw) {
     const roadmapCheckboxStates = new Map();
     try {
         const roadmapContent = extractCurrentMilestone(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd);
-        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
+        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const headingPattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
         let hm;
         while ((hm = headingPattern.exec(roadmapContent)) !== null) {
             roadmapPhaseNums.add(hm[1]);
             roadmapPhaseNames.set(hm[1], hm[2].replace(/\(INSERTED\)/i, '').trim());
         }
-        const cbPattern = /-\s*\[(x| )\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
+        const cbPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
         let cbm;
         while ((cbm = cbPattern.exec(roadmapContent)) !== null) {
             roadmapCheckboxStates.set(cbm[2], cbm[1].toLowerCase() === 'x');
@@ -1371,14 +1395,14 @@ function cmdInitProgress(cwd, raw) {
             .map((e) => e.name)
             .filter(isDirInMilestone)
             .sort((a, b) => {
-            const pa = a.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
-            const pb = b.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+            const pa = a.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
+            const pb = b.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
             if (!pa || !pb)
                 return a.localeCompare(b);
             return parseInt(pa[1], 10) - parseInt(pb[1], 10);
         });
         for (const dir of dirs) {
-            const dirMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i);
+            const dirMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})-?(.*)`, 'i'));
             const phaseNumber = dirMatch ? dirMatch[1] : dir;
             const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
             seenPhaseNums.add(phaseNumber.replace(/^0+/, '') || '0');
@@ -1870,11 +1894,24 @@ function buildSkillManifest(cwd, skillsDir = null) {
                 kind: 'skills',
             },
             {
-                root: '~/.codex/skills',
+                // ADR-1239 upgrade 3 (#2088): Codex's canonical skill root is
+                // $HOME/.agents/skills (per codex core-skills loader.rs), resolved via
+                // the skills-kind `home` override in getGlobalSkillsBase.
+                root: '~/.agents/skills',
                 path: (0, runtime_homes_cjs_1.getGlobalSkillsBase)('codex'),
                 scope: 'global',
                 kind: 'skills',
             },
+            {
+                // Codex's deprecated fallback skill root ($CODEX_HOME/skills). Kept as a
+                // discovery-only legacy root so pre-move installs remain inventoried;
+                // GSD no longer installs here (#2088).
+                root: '~/.codex/skills',
+                path: node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)('codex'), 'skills'),
+                scope: 'global',
+                kind: 'skills',
+                deprecated: true,
+            },
             {
                 root: '.claude/gsd-core/skills',
                 path: node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'gsd-core', 'skills'),

package/gsd-core/bin/lib/install-effort-resolver.cjs

@@ -0,0 +1,213 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * install-effort-resolver — install-time effort resolution (#443), extracted from
+ * the package-root `bin/install.js` (#2071).
+ *
+ * `gsd-tools effort sync` (src/commands.cts `cmdEffortSync`) must mirror what the
+ * installer writes — home `~/.gsd/defaults.json` merged with the project's
+ * `.planning/config.json` — which the runtime resolver (`resolveEffortInternal`
+ * via `loadConfig`) does NOT do. It previously reached those two functions via
+ * `require('../../../bin/install.js')`, but the installer never copies the
+ * package-root `bin/install.js` into a runtime home, so `effort sync` crashed with
+ * MODULE_NOT_FOUND in every installed runtime (#2071). Moving the logic here — a
+ * `src/*.cts` module compiled into the shipped `gsd-core/bin/lib/` tree — lets both
+ * the installer AND `effort sync` require it from a location that is always present,
+ * keeping a single source of truth (no duplication / drift).
+ *
+ * Pure with respect to config: `readGsdEffectiveEffortConfig` performs the config
+ * reads; `resolveInstallTimeEffort` is pure given a pre-merged effort object.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- model-resolver.cjs is an export= CommonJS module
+const modelResolver = require("./model-resolver.cjs");
+const { EFFORT_SET: GSD_EFFORT_SET } = modelResolver;
+/**
+ * #2517 — Read a single GSD config file (defaults.json or per-project
+ * config.json) into a plain object, returning null on missing/empty files
+ * and warning to stderr on JSON parse failures so silent corruption can't
+ * mask broken configs (review finding #5).
+ */
+function _readGsdConfigFile(absPath, label) {
+    if (!node_fs_1.default.existsSync(absPath))
+        return null;
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(absPath, 'utf-8');
+    }
+    catch (err) {
+        process.stderr.write(`gsd: warning — could not read ${label} (${absPath}): ${err.message}\n`);
+        return null;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`gsd: warning — invalid JSON in ${label} (${absPath}): ${err.message}\n`);
+        return null;
+    }
+}
+// #443 — model-catalog and config-defaults.manifest.json exports needed only
+// by effort-resolution code paths (resolveInstallTimeEffort /
+// generateCodexAgentToml / Claude .md effort injection).  Loaded lazily the
+// first time they are needed so that requiring this module in test contexts that
+// never trigger an install does NOT produce module-load-time side effects (the
+// manifest read + hard throw) that could alter subprocess exit codes or stderr.
+let _gsdEffortCatalogCache = null;
+function _getGsdEffortCatalog() {
+    if (_gsdEffortCatalogCache)
+        return _gsdEffortCatalogCache;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports -- model-catalog.cjs is an export= CommonJS module
+    const { AGENT_DEFAULT_TIERS, renderEffortForRuntime } = require('./model-catalog.cjs');
+    // This module lives in gsd-core/bin/lib/, so the shared manifest is one level
+    // up in gsd-core/bin/shared/ (bin/lib → bin → shared). (In bin/install.js this
+    // path was `.., gsd-core, bin, shared` relative to the package-root bin/.)
+    const manifestPath = node_path_1.default.join(__dirname, '..', 'shared', 'config-defaults.manifest.json');
+    let manifestData;
+    try {
+        manifestData = JSON.parse(node_fs_1.default.readFileSync(manifestPath, 'utf-8'));
+    }
+    catch (_err) {
+        // Fail loudly — a missing manifest is a broken install, not a soft degradation.
+        throw new Error(`gsd install: cannot load config-defaults.manifest.json at ${manifestPath}: ${_err.message}`);
+    }
+    const tierDefaults = (manifestData.effort &&
+        manifestData.effort.routing_tier_defaults &&
+        typeof manifestData.effort.routing_tier_defaults === 'object' &&
+        !Array.isArray(manifestData.effort.routing_tier_defaults))
+        ? manifestData.effort.routing_tier_defaults
+        : { light: 'low', standard: 'high', heavy: 'xhigh' }; // guard: unreachable if manifest is valid
+    const effortDefault = (manifestData.effort && typeof manifestData.effort.default === 'string')
+        ? manifestData.effort.default
+        : 'high'; // guard: unreachable if manifest is valid
+    _gsdEffortCatalogCache = {
+        AGENT_DEFAULT_TIERS,
+        renderEffortForRuntime,
+        EFFORT_MANIFEST_TIER_DEFAULTS: tierDefaults,
+        EFFORT_MANIFEST_DEFAULT: effortDefault,
+    };
+    return _gsdEffortCatalogCache;
+}
+/**
+ * #443 — Read the merged `effort` config block for install-time effort resolution.
+ *
+ * Probes the same config sources as readGsdRuntimeProfileResolver (per-project
+ * `.planning/config.json` wins over `~/.gsd/defaults.json`) but extracts the
+ * `effort` object instead of the model-profile fields.
+ *
+ * Returns the merged `effort` object or null when neither source defines one.
+ * The caller can pass this to resolveInstallTimeEffort() which is pure and
+ * requires no filesystem access beyond what this helper already performs.
+ *
+ * @param targetDir  Runtime install root (walks up to find .planning/).
+ */
+function readGsdEffectiveEffortConfig(targetDir = null) {
+    const homeDefaults = _readGsdConfigFile(node_path_1.default.join(node_os_1.default.homedir(), '.gsd', 'defaults.json'), '~/.gsd/defaults.json');
+    let projectConfig = null;
+    if (targetDir) {
+        let probeDir = node_path_1.default.resolve(targetDir);
+        for (let depth = 0; depth < 8; depth += 1) {
+            const candidate = node_path_1.default.join(probeDir, '.planning', 'config.json');
+            if (node_fs_1.default.existsSync(candidate)) {
+                projectConfig = _readGsdConfigFile(candidate, '.planning/config.json');
+                break;
+            }
+            const parent = node_path_1.default.dirname(probeDir);
+            if (parent === probeDir)
+                break;
+            probeDir = parent;
+        }
+    }
+    const homeEffort = (homeDefaults && homeDefaults.effort && typeof homeDefaults.effort === 'object' && !Array.isArray(homeDefaults.effort))
+        ? homeDefaults.effort
+        : null;
+    const projectEffort = (projectConfig && projectConfig.effort && typeof projectConfig.effort === 'object' && !Array.isArray(projectConfig.effort))
+        ? projectConfig.effort
+        : null;
+    if (!homeEffort && !projectEffort)
+        return null;
+    // Per-project wins on conflict within each sub-field. Merge field-by-field so
+    // a project config that only sets agent_overrides still inherits global
+    // routing_tier_defaults and default.
+    return {
+        ...(homeEffort || {}),
+        ...(projectEffort || {}),
+        // Deep-merge agent_overrides (project wins per-key)
+        agent_overrides: {
+            ...((homeEffort && homeEffort.agent_overrides) || {}),
+            ...((projectEffort && projectEffort.agent_overrides) || {}),
+        },
+    };
+}
+/**
+ * #443 — Resolve install-time effort for a given agent, using the same
+ * precedence chain as resolveEffortInternal() in core.cjs, but operating
+ * on a pre-loaded effortCfg object (no loadConfig side-effects at install).
+ *
+ * Precedence (mirrors resolveEffortInternal):
+ *   1. effortCfg.agent_overrides[agentName]
+ *   2. effortCfg.routing_tier_defaults[agentTier]  (if effortCfg present)
+ *      — OR manifest tier defaults when effortCfg is null
+ *   3. effortCfg.default
+ *   4. 'high' (hardcoded fallback)
+ *
+ * @param effortCfg   Result of readGsdEffectiveEffortConfig().
+ * @param agentName   e.g. 'gsd-planner'
+ * @returns           Universal effort string (low/medium/high/xhigh/max/minimal)
+ */
+function resolveInstallTimeEffort(effortCfg, agentName) {
+    // Validates each candidate against the canonical EFFORT_SET (sourced once
+    // from model-resolver.cjs) before accepting it, mirroring resolveEffortInternal
+    // exactly. Invalid values fall through to the next precedence layer; final
+    // fallback 'high'.
+    // Step 1: agent_overrides
+    if (effortCfg) {
+        const ao = effortCfg.agent_overrides;
+        if (ao && typeof ao === 'object' && !Array.isArray(ao)) {
+            const v = ao[agentName];
+            if (typeof v === 'string' && GSD_EFFORT_SET.has(v))
+                return v;
+        }
+    }
+    // Step 2: routing_tier_defaults keyed by the agent's catalog tier
+    const { AGENT_DEFAULT_TIERS, EFFORT_MANIFEST_TIER_DEFAULTS, EFFORT_MANIFEST_DEFAULT } = _getGsdEffortCatalog();
+    const agentTier = AGENT_DEFAULT_TIERS[agentName];
+    if (agentTier) {
+        if (effortCfg && effortCfg.routing_tier_defaults &&
+            typeof effortCfg.routing_tier_defaults === 'object' &&
+            !Array.isArray(effortCfg.routing_tier_defaults)) {
+            const v = effortCfg.routing_tier_defaults[agentTier];
+            if (typeof v === 'string' && GSD_EFFORT_SET.has(v))
+                return v;
+        }
+        else if (!effortCfg) {
+            // No effort config — use manifest tier defaults
+            const v = EFFORT_MANIFEST_TIER_DEFAULTS[agentTier];
+            if (typeof v === 'string' && GSD_EFFORT_SET.has(v))
+                return v;
+        }
+        // effortCfg exists but has no routing_tier_defaults — fall through
+    }
+    // Step 3: effort.default
+    if (effortCfg) {
+        const d = effortCfg.default;
+        if (typeof d === 'string' && GSD_EFFORT_SET.has(d))
+            return d;
+    }
+    // Step 4: manifest default (sourced from config-defaults.manifest.json effort.default)
+    // If even the manifest default is invalid, fall back to 'high'.
+    if (typeof EFFORT_MANIFEST_DEFAULT === 'string' && GSD_EFFORT_SET.has(EFFORT_MANIFEST_DEFAULT)) {
+        return EFFORT_MANIFEST_DEFAULT;
+    }
+    return 'high';
+}
+module.exports = {
+    readGsdEffectiveEffortConfig,
+    resolveInstallTimeEffort,
+    _getGsdEffortCatalog,
+    _readGsdConfigFile,
+};