@opengsd/gsd-core 1.2.0 → 1.3.0-rc.1

package/get-shit-done/bin/lib/core.cjs

@@ -7,7 +7,7 @@ const os = require('os');
 const path = require('path');
 const { execGit, platformWriteSync, platformReadSync, platformEnsureDir } = require('./shell-command-projection.cjs');
 const { MODEL_PROFILES, AGENT_TO_PHASE_TYPE, VALID_PHASE_TYPES, AGENT_DEFAULT_TIERS, VALID_AGENT_TIERS, nextTier } = require('./model-profiles.cjs');
-const { MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, KNOWN_RUNTIMES, RUNTIMES_WITH_REASONING_EFFORT, renderEffortForRuntime, RUNTIMES_WITH_FAST_MODE } = require('./model-catalog.cjs');
+const { MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, KNOWN_RUNTIMES, RUNTIMES_WITH_REASONING_EFFORT, renderEffortForRuntime, RUNTIMES_WITH_FAST_MODE, PROVIDER_PRESETS, KNOWN_PROVIDERS } = require('./model-catalog.cjs');
 const {
   resolveWorktreeContext,
   parseWorktreePorcelain: parseWorktreePorcelainPolicy,
@@ -514,6 +514,11 @@ function loadConfig(cwd, options = {}) {
       // unknown runtime/tier names at load time, not silently (review finding #10).
       runtime: parsed.runtime || null,
       model_profile_overrides: parsed.model_profile_overrides || null,
+      // #49 — provider-neutral model policy presets.
+      // model_policy is read flat (not via get()) for the same reason as
+      // model_profile_overrides: it is a top-level config key per CONFIGURATION.md,
+      // and nested resolution would introduce edge cases without benefit.
+      model_policy: parsed.model_policy || null,
       // #443 — effort/fast_mode: pass through from config.json; resolvers handle
       // defaults + tier lookups internally.
       effort: parsed.effort || null,
@@ -668,6 +673,18 @@ function normalizePhaseName(phase) {
   const str = String(phase);
   // Strip optional project_code prefix (e.g., 'CK-01' → '01')
   const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/, '');
+  // Milestone-prefixed phase IDs: M-NN or M-N-N (deep decomposition).
+  // Examples: '2-01', '02-01', '2-4-1', '02-04-01'.
+  // Must be tested BEFORE the plain numeric path so '2-01' → '02-01', not '02'.
+  // Pattern: at least two dash-separated all-digit segments (letter/decimal suffix on last).
+  const milestoneMatch = stripped.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
+  if (milestoneMatch) {
+    const major = milestoneMatch[1].padStart(2, '0');
+    // Each sub-segment gets zero-padded to at least 2 digits.
+    const subSegments = milestoneMatch[2].slice(1).split('-').map(s => s.padStart(2, '0'));
+    const suffix = milestoneMatch[3] || '';
+    return `${major}-${subSegments.join('-')}${suffix}`;
+  }
   // Standard numeric phases: 1, 01, 12A, 12.1
   const match = stripped.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
   if (match) {
@@ -683,6 +700,32 @@ function normalizePhaseName(phase) {
   return str;
 }
 
+function getMilestoneFromPhaseId(phaseId) {
+  const str = String(phaseId);
+  const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+  const m = stripped.match(/^0*(\d+)-\d/);
+  if (!m) return null;
+  const major = parseInt(m[1], 10);
+  if (major === 0 || major === 999) return null;
+  return `v${major}.0`;
+}
+
+function getPhaseDirFromPhaseId(phaseId, phaseName, projectCode) {
+  const str = String(phaseId);
+  const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+  const m = stripped.match(/^0*(\d+)-(0*(\d+(?:-\d+)*))$/);
+  if (!m) return null;
+  const milestone = String(parseInt(m[1], 10)).padStart(2, '0');
+  const subParts = m[2].split('-').map(p => String(parseInt(p, 10)).padStart(2, '0'));
+  const sub = subParts.join('-');
+  const slug = phaseName
+    ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+    : '';
+  const parts = [milestone, sub, slug].filter(Boolean);
+  const base = parts.join('-');
+  return projectCode ? `${projectCode}-${base}` : base;
+}
+
 /**
  * Render a regex source fragment matching a phase number against ROADMAP/STATE
  * prose regardless of zero-padding on either side. Skills pass the resolved
@@ -699,6 +742,24 @@ function normalizePhaseName(phase) {
  */
 function phaseMarkdownRegexSource(phaseNum) {
   const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+
+  // Milestone-prefixed IDs: M-NN or M-N-N (deep). Each numeric segment is padding-tolerant.
+  // Pattern: one or more dash-separated all-digit groups (last may have letter/decimal suffix).
+  const milestoneSegments = stripped.match(/^(\d+)((?:-\d+)*)([A-Z]?(?:\.\d+)*)$/i);
+  if (milestoneSegments && milestoneSegments[2]) {
+    // Has at least one dash-separated segment — treat as milestone-prefixed
+    const majorUnpadded = milestoneSegments[1].replace(/^0+/, '') || '0';
+    const subParts = milestoneSegments[2].slice(1).split('-'); // drop leading '-'
+    const subFragments = subParts.map(s => {
+      const unpadded = s.replace(/^0+/, '') || '0';
+      return `0*${escapeRegex(unpadded)}`;
+    });
+    const suffix = milestoneSegments[3] || '';
+    const suffixFragment = suffix ? escapeRegex(suffix) : '';
+    return `0*${escapeRegex(majorUnpadded)}-${subFragments.join('-')}${suffixFragment}`;
+  }
+
+  // Plain numeric phase: 1, 01, 12A, 12.1
   const match = stripped.match(/^0*(\d+)([A-Z])?((?:\.\d+)*)$/i);
   if (!match) return escapeRegex(phaseNum);
 
@@ -729,8 +790,35 @@ function phaseMarkdownRegexSourceExact(phaseNum) {
 
 function comparePhaseNum(a, b) {
   // Strip optional project_code prefix before comparing (e.g., 'CK-01-name' → '01-name')
-  const sa = String(a).replace(/^[A-Z]{1,6}-/, '');
-  const sb = String(b).replace(/^[A-Z]{1,6}-/, '');
+  const sa = String(a).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+  const sb = String(b).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+
+  // Milestone-prefixed IDs: one or more dash-separated all-digit segments.
+  // e.g. '02-10', '2-01', '02-04-01'. Compare segment by segment numerically.
+  // A string matches this form when it starts with digits and has at least one '-digit' group.
+  const milestoneA = sa.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
+  const milestoneB = sb.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
+
+  if (milestoneA && milestoneB) {
+    const segsA = [parseInt(milestoneA[1], 10), ...milestoneA[2].slice(1).split('-').map(s => parseInt(s, 10))];
+    const segsB = [parseInt(milestoneB[1], 10), ...milestoneB[2].slice(1).split('-').map(s => parseInt(s, 10))];
+    const maxSegs = Math.max(segsA.length, segsB.length);
+    for (let i = 0; i < maxSegs; i++) {
+      const av = segsA[i] !== undefined ? segsA[i] : 0;
+      const bv = segsB[i] !== undefined ? segsB[i] : 0;
+      if (av !== bv) return av - bv;
+    }
+    // Segments equal — compare any trailing letter/decimal suffix
+    const sufA = milestoneA[3] || '';
+    const sufB = milestoneB[3] || '';
+    if (sufA !== sufB) return sufA < sufB ? -1 : 1;
+    return 0;
+  }
+
+  // If one is milestone-prefixed and the other is not, milestone-prefixed sorts first
+  // (they come from different conventions; preserve caller's intent by string comparison).
+  if (milestoneA || milestoneB) return String(a).localeCompare(String(b));
+
   const pa = sa.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
   const pb = sb.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
   // If either is non-numeric (custom ID), fall back to string comparison
@@ -761,20 +849,59 @@ function comparePhaseNum(a, b) {
 
 /**
  * Extract the phase token from a directory name.
- * Supports: '01-name', '1009A-name', '999.6-name', 'CK-01-name', 'PROJ-42-name'.
- * Returns the token portion (e.g. '01', '1009A', '999.6', 'PROJ-42') or the full name if no separator.
+ * A token is the leading all-numeric (or project-code-prefixed) run of dash-separated
+ * segments, up to but not including the first segment that starts with a letter after the
+ * optional code prefix. The last numeric segment may carry a letter suffix (e.g. 12A) or
+ * decimal suffix (e.g. 999.6).
+ *
+ * Examples:
+ *   '01-name'           → '01'
+ *   '02-01-setup'       → '02-01'      (milestone-prefixed 2-segment)
+ *   '02-04-01-deep'     → '02-04-01'   (deep 3-segment)
+ *   'CK-01-name'        → 'CK-01'      (project-code-prefixed)
+ *   'GSD-02-01-setup'   → 'GSD-02-01'  (code-prefixed milestone)
+ *   'GSD-02-04-01-deep' → 'GSD-02-04-01'
+ *   '1009A-name'        → '1009A'
+ *   '999.6-name'        → '999.6'
+ *   'PROJ-42-name'      → 'PROJ-42'    (custom ID)
  */
 function extractPhaseToken(dirName) {
-  // Try project-code-prefixed numeric: CK-01-name → CK-01, CK-01A.2-name → CK-01A.2
-  const codePrefixed = dirName.match(/^([A-Z]{1,6}-\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i);
-  if (codePrefixed) return codePrefixed[1];
-  // Try plain numeric: 01-name, 1009A-name, 999.6-name
-  const numeric = dirName.match(/^(\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i);
-  if (numeric) return numeric[1];
-  // Custom IDs: PROJ-42-name → everything before the last segment that looks like a name
-  const custom = dirName.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)(?:-[a-z]|$)/i);
-  if (custom) return custom[1];
-  return dirName;
+  // Optional project-code prefix: 1–6 uppercase letters followed by a digit segment.
+  const codePrefixMatch = dirName.match(/^([A-Z]{1,6})-(\d.*)/i);
+  let prefix = '';
+  let rest = dirName;
+  if (codePrefixMatch) {
+    // Distinguish code prefix (e.g. GSD-, CK-) from purely numeric-looking start.
+    // The prefix must be all-uppercase-letter (already guaranteed by [A-Z]{1,6}) and
+    // the first char after '-' must be a digit so we don't swallow PROJ-42-name prematurely.
+    prefix = codePrefixMatch[1] + '-';
+    rest = codePrefixMatch[2];
+  }
+
+  // Greedily consume all leading all-digit segments (possibly with A-Z letter or .N suffix on the last).
+  // Stop when a segment starts with a letter (that is not a continuation of the last digit segment).
+  const segments = rest.split('-');
+  const tokenSegments = [];
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (/^\d/.test(seg)) {
+      // Numeric segment (possibly trailing letter or .N suffix on last) — always include
+      tokenSegments.push(seg);
+    } else {
+      // First letter-start segment after digits → name portion starts here
+      break;
+    }
+  }
+
+  if (tokenSegments.length === 0) {
+    // No leading numeric segment — could be a custom ID like PROJ-42
+    // If we stripped a code prefix, return the full original (prefix stripped the code but rest is numeric handled above)
+    // For purely letter-start directory with no code prefix (shouldn't normally happen), return as-is
+    return dirName;
+  }
+
+  // The last numeric segment may have a letter suffix (1009A) or decimal (.6) already included.
+  return prefix + tokenSegments.join('-');
 }
 
 /**
@@ -811,13 +938,13 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
     const match = dirs.find(d => phaseTokenMatches(d, normalized));
     if (!match) return null;
 
-    // Extract phase number and name — supports numeric (01-name), project-code-prefixed (CK-01-name), and custom (PROJ-42-name)
-    const dirMatch = match.match(/^(?:[A-Z]{1,6}-)(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
-      || match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
-      || match.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-(.+)/i)
-      || [null, match, null];
-    const phaseNumber = dirMatch ? dirMatch[1] : normalized;
-    const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
+    // Extract phase number and name using extractPhaseToken for correctness with all ID forms
+    // including deep milestone-prefixed (02-04-01-deep → 02-04-01 / deep) and code-prefixed.
+    const phaseToken = extractPhaseToken(match);
+    const phaseNumber = phaseToken || normalized;
+    // phase_name is everything after the token (strip leading '-')
+    const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
+    const phaseName = afterToken || null;
     const phaseDir = path.join(baseDir, match);
     const { plans: unsortedPlans, summaries: unsortedSummaries, hasResearch, hasContext, hasVerification, hasReviews } = getPhaseFileStats(phaseDir);
     const plans = unsortedPlans.sort();
@@ -973,8 +1100,8 @@ function extractCurrentMilestone(content, cwd) {
 
   // 2. Fallback: derive version from getMilestoneInfo pattern in ROADMAP.md itself
   if (!version) {
-    // Check for 🚧 in-progress marker
-    const inProgressMatch = content.match(/🚧\s*\*\*v(\d+\.\d+)\s/);
+    // Check for 🚧 or 🔄 in-progress marker in bold version line
+    const inProgressMatch = content.match(/(?:🚧|🔄)\s*\*\*v(\d+\.\d+)\s/);
     if (inProgressMatch) {
       version = 'v' + inProgressMatch[1];
     }
@@ -984,19 +1111,57 @@ function extractCurrentMilestone(content, cwd) {
 
   // 3. Find the section matching this version
   // Match headings like: ## Roadmap v3.0: Name, ## v3.0 Name, etc.
+  // Also match <summary> tags that contain the version (milestone in <details open>).
+  // Exclude phase headings (e.g. "### Phase 1: v1.3 migration") so that a phase title
+  // that mentions the milestone version does not bypass the <summary> fallback.
   const escapedVersion = escapeRegex(version);
   const sectionPattern = new RegExp(
-    `(^#{1,3}\\s+.*${escapedVersion}\\b[^\\n]*)`,
+    `(^#{1,3}\\s+(?!Phase\\s+\\S).*${escapedVersion}\\b[^\\n]*)`,
     'gmi'
   );
-  const allMatches = [...content.matchAll(sectionPattern)];
+  const summaryPattern = new RegExp(
+    `<summary[^>]*>([^<]*${escapedVersion}[^<]*)<\\/summary>`,
+    'i'
+  );
+  const headingMatches = [...content.matchAll(sectionPattern)];
+
+  // If the version appears only inside a <summary> tag (not in a heading),
+  // locate the enclosing <details open> block and treat its content as the
+  // current milestone section instead of falling through to stripShippedMilestones().
+  if (headingMatches.length === 0) {
+    const summaryMatch = content.match(summaryPattern);
+    if (summaryMatch) {
+      // Find the <details ...> opening tag that precedes this <summary>
+      const summaryIdx = content.indexOf(summaryMatch[0]);
+      const beforeSummary = content.slice(0, summaryIdx);
+      const detailsOpenIdx = beforeSummary.lastIndexOf('<details');
+      if (detailsOpenIdx !== -1) {
+        // Find the matching </details> closing tag
+        const afterDetails = content.slice(detailsOpenIdx);
+        const closingMatch = afterDetails.match(/<\/details>/i);
+        const detailsEnd = closingMatch
+          ? detailsOpenIdx + closingMatch.index + '</details>'.length
+          : content.length;
+        // Preamble: everything before the first milestone-level section
+        const anyMilestoneOrDetails = /^#{1,3}\s+(?!Phase\s+\S)(?:.*v\d+\.\d+|✅|📋|🚧|🔄)|<details/im;
+        const firstMilestoneMatch = content.match(anyMilestoneOrDetails);
+        const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : detailsOpenIdx;
+        const preamble = content.slice(0, preambleCutoff)
+          .replace(/<details>[\s\S]*?<\/details>/gi, '')
+          .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+          .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
+        return preamble + content.slice(detailsOpenIdx, detailsEnd);
+      }
+    }
+    return stripShippedMilestones(content);
+  }
 
-  if (allMatches.length === 0) return stripShippedMilestones(content);
+  const allMatches = headingMatches;
 
   // Select the first non-closed heading; fall back to first match if all are closed.
   // A heading is "closed" only if it carries a closed marker AND no active marker.
   const closedMarkerPattern = /\b(?:CLOSED|ARCHIVED|ABANDONED|SHIPPED|FAILED)\b|✅|🗄/i;
-  const activeMarkerPattern = /\b(?:STARTED|ACTIVE|WIP)\b|in\s+progress|🚧/i;
+  const activeMarkerPattern = /\b(?:STARTED|ACTIVE|WIP)\b|in\s+progress|🚧|🔄/i;
   const isClosed = (h) => closedMarkerPattern.test(h) && !activeMarkerPattern.test(h);
   const firstMatch = allMatches[0];
   const selected = allMatches.find((m) => !isClosed(m[1])) || firstMatch;
@@ -1102,8 +1267,9 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
     // #3537: route through canonical padding-tolerant fragment. The prior
     // hand-rolled `isNumeric` branch only stripped padding on integer-only
     // ids and missed decimal padding (`02.7` against `Phase 2.7:` headings).
+    // Also tolerate optional [bracket-token] scope prefix on phase headings.
     const phasePattern = new RegExp(
-      `#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}:\\s*([^\\n]+)`,
+      `#{2,4}\\s*(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${phaseMarkdownRegexSource(phaseNum)}:\\s*([^\\n]+)`,
       'i'
     );
     const headerMatch = content.match(phasePattern);
@@ -1112,7 +1278,8 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
     const phaseName = headerMatch[1].trim();
     const headerIndex = headerMatch.index;
     const restOfContent = content.slice(headerIndex);
-    const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+[\w]/i);
+    // Boundary: next phase heading — also matches bracket-prefixed form.
+    const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i);
     const sectionEnd = nextHeaderMatch ? headerIndex + nextHeaderMatch.index : content.length;
     const section = content.slice(headerIndex, sectionEnd).trim();
 
@@ -1222,35 +1389,91 @@ function _warnUnknownProfileOverrides(parsed, configLabel) {
   }
 
   const overrides = parsed.model_profile_overrides;
-  if (!overrides || typeof overrides !== 'object') return;
-  for (const [overrideRuntime, tierMap] of Object.entries(overrides)) {
-    if (!KNOWN_RUNTIMES.has(overrideRuntime)) {
-      const key = `${configLabel}::override-runtime::${overrideRuntime}`;
-      if (!_warnedConfigKeys.has(key)) {
-        _warnedConfigKeys.add(key);
-        try {
-          process.stderr.write(
-            `gsd: warning — model_profile_overrides.${overrideRuntime}.* uses ` +
-            `unknown runtime "${overrideRuntime}". Known runtimes: ` +
-            `${[...KNOWN_RUNTIMES].sort().join(', ')}. (#2517)\n`
-          );
-        } catch { /* ok */ }
-      }
-    }
-    if (!tierMap || typeof tierMap !== 'object') continue;
-    for (const tierName of Object.keys(tierMap)) {
-      if (!RUNTIME_OVERRIDE_TIERS.has(tierName)) {
-        const key = `${configLabel}::override-tier::${overrideRuntime}.${tierName}`;
+  if (overrides && typeof overrides === 'object') {
+    for (const [overrideRuntime, tierMap] of Object.entries(overrides)) {
+      if (!KNOWN_RUNTIMES.has(overrideRuntime)) {
+        const key = `${configLabel}::override-runtime::${overrideRuntime}`;
         if (!_warnedConfigKeys.has(key)) {
           _warnedConfigKeys.add(key);
           try {
             process.stderr.write(
-              `gsd: warning — model_profile_overrides.${overrideRuntime}.${tierName} ` +
-              `uses unknown tier "${tierName}". Allowed tiers: opus, sonnet, haiku. (#2517)\n`
+              `gsd: warning — model_profile_overrides.${overrideRuntime}.* uses ` +
+              `unknown runtime "${overrideRuntime}". Known runtimes: ` +
+              `${[...KNOWN_RUNTIMES].sort().join(', ')}. (#2517)\n`
             );
           } catch { /* ok */ }
         }
       }
+      if (!tierMap || typeof tierMap !== 'object') continue;
+      for (const tierName of Object.keys(tierMap)) {
+        if (!RUNTIME_OVERRIDE_TIERS.has(tierName)) {
+          const key = `${configLabel}::override-tier::${overrideRuntime}.${tierName}`;
+          if (!_warnedConfigKeys.has(key)) {
+            _warnedConfigKeys.add(key);
+            try {
+              process.stderr.write(
+                `gsd: warning — model_profile_overrides.${overrideRuntime}.${tierName} ` +
+                `uses unknown tier "${tierName}". Allowed tiers: opus, sonnet, haiku. (#2517)\n`
+              );
+            } catch { /* ok */ }
+          }
+        }
+      }
+    }
+  }
+
+  const policy = parsed.model_policy;
+  if (policy && typeof policy === 'object') {
+    const provider = policy.provider;
+    // 'generic' and 'custom' are sentinel values for the manual model-ID path — not catalog entries.
+    const _POLICY_SENTINEL_PROVIDERS = new Set(['generic', 'custom']);
+    if (provider && typeof provider === 'string' &&
+        !KNOWN_PROVIDERS.has(provider) && !_POLICY_SENTINEL_PROVIDERS.has(provider)) {
+      const pkey = `${configLabel}::model_policy::provider::${provider}`;
+      if (!_warnedConfigKeys.has(pkey)) {
+        _warnedConfigKeys.add(pkey);
+        try {
+          process.stderr.write(
+            `gsd: warning — model_policy.provider has unknown value "${provider}". ` +
+            `Known providers: ${[...KNOWN_PROVIDERS].sort().join(', ')}. ` +
+            `For manual model IDs use provider="custom". (#49)\n`
+          );
+        } catch { /* ok */ }
+      }
+    }
+
+    const rtOverrides = policy.runtime_tiers;
+    if (rtOverrides && typeof rtOverrides === 'object') {
+      for (const [pruntime, tierMap] of Object.entries(rtOverrides)) {
+        if (!KNOWN_RUNTIMES.has(pruntime)) {
+          const key = `${configLabel}::model_policy.runtime_tiers::${pruntime}`;
+          if (!_warnedConfigKeys.has(key)) {
+            _warnedConfigKeys.add(key);
+            try {
+              process.stderr.write(
+                `gsd: warning — model_policy.runtime_tiers.${pruntime}.* uses ` +
+                `unknown runtime "${pruntime}". Known runtimes: ` +
+                `${[...KNOWN_RUNTIMES].sort().join(', ')}. (#49)\n`
+              );
+            } catch { /* ok */ }
+          }
+        }
+        if (!tierMap || typeof tierMap !== 'object') continue;
+        for (const tierName of Object.keys(tierMap)) {
+          if (!RUNTIME_OVERRIDE_TIERS.has(tierName)) {
+            const key = `${configLabel}::model_policy.runtime_tiers::${pruntime}.${tierName}`;
+            if (!_warnedConfigKeys.has(key)) {
+              _warnedConfigKeys.add(key);
+              try {
+                process.stderr.write(
+                  `gsd: warning — model_policy.runtime_tiers.${pruntime}.${tierName} ` +
+                  `uses unknown tier "${tierName}". Allowed: opus, sonnet, haiku. (#49)\n`
+                );
+              } catch { /* ok */ }
+            }
+          }
+        }
+      }
     }
   }
 }
@@ -1314,6 +1537,85 @@ function _resolveRuntimeTier(config, tier) {
   });
 }
 
+/**
+ * #49 — Provider-neutral model policy preset resolution.
+ *
+ * Signature: resolveModelPolicy(policy, tier) → string | null
+ *
+ * Resolves a model ID string from a model_policy object. Two resolution sub-paths:
+ *
+ *   A. runtime_tiers sub-block (explicit per-runtime entries):
+ *      policy.runtime_tiers[policy.runtime][tier] → model string
+ *      The active runtime is read from policy.runtime (the caller merges
+ *      config.runtime into the policy object before calling).
+ *
+ *   B. provider + budget preset lookup (catalog-backed):
+ *      PROVIDER_PRESETS[provider][tier][budget] → model string
+ *      budget defaults to 'medium' if absent from policy.
+ *
+ * Returns a string model ID on a hit, null on miss.
+ * Never throws — unknown provider/tier/budget degrades gracefully to null
+ * so the caller falls through to model_profile_overrides.
+ *
+ * Precedence: runtime_tiers wins over provider presets when both are present
+ * for the same runtime+tier combination.
+ */
+function resolveModelPolicy(policy, tier) {
+  if (!policy || typeof policy !== 'object') return null;
+  if (!tier) return null;
+
+  // Sub-path A: explicit runtime_tiers override (highest precedence within policy).
+  // The active runtime is read from policy.runtime — the caller is responsible for
+  // merging config.runtime into the policy object (see step 2.5 in resolveModelInternal).
+  const runtime = policy.runtime;
+  const rtOverrides = policy.runtime_tiers;
+  if (runtime && typeof runtime === 'string' && rtOverrides && typeof rtOverrides === 'object') {
+    if (Object.hasOwn(rtOverrides, runtime)) {
+      const runtimeEntry = rtOverrides[runtime];
+      if (runtimeEntry && typeof runtimeEntry === 'object' && Object.hasOwn(runtimeEntry, tier)) {
+        const raw = runtimeEntry[tier];
+        if (raw != null) {
+          const entry = typeof raw === 'string' ? { model: raw } : raw;
+          if (entry && entry.model) return entry.model;
+        }
+      }
+    }
+  }
+
+  // Sub-path B: catalog-backed provider preset.
+  const provider = policy.provider;
+  if (!provider || typeof provider !== 'string') return null;
+
+  // Sub-path B1: generic provider — model IDs supplied directly via model_policy.high/medium/low.
+  // 'generic' and 'custom' are sentinel values meaning "user-supplied IDs, no catalog lookup".
+  // The tier-to-key mapping: 'opus' → high, 'sonnet' → medium, 'haiku' → low.
+  if (provider === 'generic' || provider === 'custom') {
+    const TIER_TO_POLICY_KEY = { opus: 'high', sonnet: 'medium', haiku: 'low' };
+    const policyKey = TIER_TO_POLICY_KEY[tier];
+    if (!policyKey) return null;
+    const v = policy[policyKey];
+    return (v && typeof v === 'string') ? v : null;
+  }
+
+  // Object.hasOwn guards prevent __proto__ / constructor key escalation from
+  // user-controlled policy.provider / policy.budget reaching inherited slots.
+  if (!Object.hasOwn(PROVIDER_PRESETS, provider)) return null;
+  const presetForProvider = PROVIDER_PRESETS[provider];
+  if (!presetForProvider || typeof presetForProvider !== 'object') return null;
+
+  if (!Object.hasOwn(presetForProvider, tier)) return null;
+  const tierPresets = presetForProvider[tier];
+  if (!tierPresets || typeof tierPresets !== 'object') return null;
+
+  // Budget defaults to 'medium' — mirrors the existing 'balanced' default bias.
+  const budget = (policy.budget && typeof policy.budget === 'string') ? policy.budget : 'medium';
+  if (!Object.hasOwn(tierPresets, budget)) return null;
+  const budgetEntry = tierPresets[budget];
+  if (!budgetEntry || !budgetEntry.model) return null; // Missing or null budget slot.
+
+  return budgetEntry.model;
+}
+
 function resolveModelInternal(cwd, agentType) {
   const config = loadConfig(cwd);
 
@@ -1356,6 +1658,22 @@ function resolveModelInternal(cwd, agentType) {
       ? 'inherit'
       : (agentModels ? (agentModels[profile] || agentModels['balanced']) : null));
 
+  // 2.5. model_policy preset (#49) — higher precedence than model_profile_overrides.
+  // Fires when config.model_policy is set AND runtime is a non-Claude runtime with
+  // tier !== 'inherit'. The provider preset catalog (Sub-path B) and any
+  // runtime_tiers overrides (Sub-path A) are checked here before falling through to
+  // the existing model_profile_overrides chain in step 3.
+  if (config.runtime && config.runtime !== 'claude' && tier && tier !== 'inherit') {
+    // Merge config.runtime into the policy object so resolveModelPolicy can use
+    // it for Sub-path A (runtime_tiers) lookup without needing a separate argument.
+    const mergedPolicy = config.model_policy
+      ? { ...config.model_policy, runtime: config.runtime }
+      : null;
+    const policyModel = resolveModelPolicy(mergedPolicy, tier);
+    if (policyModel) return policyModel;
+    // No policy hit → fall through to step 3 (model_profile_overrides).
+  }
+
   // 3. Runtime-aware resolution (#2517) — only when `runtime` is explicitly set
   // to a non-Claude runtime. `runtime: "claude"` is the implicit default and is
   // treated as a no-op here so it does not silently override `resolve_model_ids:
@@ -1437,6 +1755,14 @@ function resolveModelForTier(cwd, agentType, attempt) {
   const override = config.model_overrides?.[agentType];
   if (override) return override;
 
+  // model_policy beats dynamic_routing (#49 Codex adversarial HIGH finding).
+  // Delegate to resolveModelInternal which handles step 2.5 (policy) correctly
+  // and falls through to runtimeTierDefaults on a miss. Gate on non-Claude
+  // runtime to match the same condition in resolveModelInternal step 2.5.
+  if (config.model_policy && config.runtime && config.runtime !== 'claude') {
+    return resolveModelInternal(cwd, agentType);
+  }
+
   const dr = config.dynamic_routing;
   // Disabled / missing / non-object → fall back to the existing resolver.
   if (!dr || typeof dr !== 'object' || dr.enabled !== true) {
@@ -1544,6 +1870,12 @@ function resolveEffortInternal(cwd, agentType, opts) {
       const v = ao[agentType];
       if (typeof v === 'string' && EFFORT_SET.has(v)) return v;
     }
+  } else {
+    const mao = CANONICAL_CONFIG_DEFAULTS.effort && CANONICAL_CONFIG_DEFAULTS.effort.agent_overrides;
+    if (mao && typeof mao === 'object' && !Array.isArray(mao)) {
+      const v = mao[agentType];
+      if (typeof v === 'string' && EFFORT_SET.has(v)) return v;
+    }
   }
 
   // Step 3: routing_tier_defaults by agent's default tier.
@@ -1575,6 +1907,9 @@ function resolveEffortInternal(cwd, agentType, opts) {
   if (effortCfg) {
     const d = effortCfg.default;
     if (typeof d === 'string' && EFFORT_SET.has(d)) return d;
+  } else {
+    const d = CANONICAL_CONFIG_DEFAULTS.effort && CANONICAL_CONFIG_DEFAULTS.effort.default;
+    if (typeof d === 'string' && EFFORT_SET.has(d)) return d;
   }
 
   // Step 5: hardcoded default
@@ -1888,16 +2223,56 @@ function getMilestonePhaseFilter(cwd, versionOverride) {
     if (roadmapContent === null) throw new Error('missing');
     let roadmap = extractCurrentMilestone(roadmapContent, cwd);
 
+    // Emit a deprecation warning for "free-form" roadmaps: those that have
+    // Phase headings but no versioned milestone sections (## vX.Y / ## Roadmap vX.Y).
+    // This is non-fatal — the roadmap continues to work via legacy behaviour.
+    const hasVersionedMilestonesGlobal = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
+    const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
+    if (!hasVersionedMilestonesGlobal && hasPhaseHeadings) {
+      console.warn(
+        '[gsd] Deprecated: free-form ROADMAP.md detected (no versioned milestone headings). ' +
+        'Set phase_id_convention in config.json to suppress this warning.'
+      );
+    }
+
     if (versionOverride) {
       const escapedVersion = escapeRegex(versionOverride);
-      const sectionPattern = new RegExp(`(^#{1,3}\\s+.*${escapedVersion}[^\\n]*)`, 'mi');
-      const sectionMatch = roadmapContent.match(sectionPattern);
+      // Exclude phase headings (e.g. "### Phase 1: v1.3 migration") that mention
+      // the version but are not milestone-level headings. Same guard as sectionPattern
+      // in extractCurrentMilestone().
+      const sectionPattern = new RegExp(`(^#{1,3}\\s+(?!Phase\\s+\\S).*${escapedVersion}[^\\n]*)`, 'mi');
+      let sectionMatch = roadmapContent.match(sectionPattern);
+
+      // If no heading match, check whether the version lives in a <summary> tag
+      // (milestone wrapped in <details open>). If so, extract that block's heading
+      // so the phase-filter can scope correctly.
       if (!sectionMatch) {
-        // Only treat this as an error case when the roadmap is milestone-versioned.
+        const summaryPat = new RegExp(`<summary[^>]*>[^<]*${escapedVersion}[^<]*<\\/summary>`, 'i');
+        const summaryHit = roadmapContent.match(summaryPat);
+        if (summaryHit) {
+          // Treat the <summary> content as a synthetic heading match so the code
+          // below can extract the section boundaries from it.
+          // We fabricate a match object pointing at the <details> block start.
+          const beforeSummary = roadmapContent.slice(0, summaryHit.index);
+          const detailsIdx = beforeSummary.lastIndexOf('<details');
+          if (detailsIdx !== -1) {
+            // Use extractCurrentMilestone (already called above) which now handles
+            // <summary> correctly — roadmap is already scoped. Skip the override
+            // re-scoping: roadmap is already the current milestone content.
+            // Do nothing: keep roadmap as-is from extractCurrentMilestone.
+            sectionMatch = null; // fall through without setting missingExplicitVersion
+          }
+        }
+      }
+
+      if (!sectionMatch) {
+        // Only treat this as an error case when the roadmap is milestone-versioned
+        // AND the version is genuinely absent (not in a <summary> tag handled above).
         // Older/flat roadmap formats without vX.Y milestone headings should keep
         // legacy pass-through behavior for milestone.complete.
-        const hasVersionedMilestones = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
-        if (hasVersionedMilestones) {
+        const hasVersionedMilestones = /^#{1,3}\s+(?!Phase\s+\S).*v\d+\.\d+/mi.test(roadmapContent);
+        const versionInSummary = new RegExp(`<summary[^>]*>[^<]*${escapedVersion}[^<]*<\\/summary>`, 'i').test(roadmapContent);
+        if (hasVersionedMilestones && !versionInSummary) {
           roadmap = '';
           missingExplicitVersion = true;
         }
@@ -1936,8 +2311,9 @@ function getMilestonePhaseFilter(cwd, versionOverride) {
       }
     }
 
-    // Match both numeric phases (Phase 1:) and custom IDs (Phase PROJ-42:)
-    const phasePattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+    // Match both numeric phases (Phase 1:) and custom IDs (Phase PROJ-42:).
+    // Also tolerate optional [bracket-token] scope prefix (e.g., ### [GSD] Phase 2-01:).
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
     let m;
     while ((m = phasePattern.exec(roadmap)) !== null) {
       milestonePhaseNums.add(m[1]);
@@ -1952,13 +2328,25 @@ function getMilestonePhaseFilter(cwd, versionOverride) {
   }
 
   const normalized = new Set(
-    [...milestonePhaseNums].map(n => (n.replace(/^0+(?=\d)/, '') || '0').toLowerCase())
+    [...milestonePhaseNums].map(n => n.split('-').map(seg => (seg.replace(/^0+(?=\d)/, '') || '0')).join('-').toLowerCase())
   );
 
+  function normalizePhaseIdSegments(id) {
+    return id.split('-').map(seg => seg.replace(/^0+(?=\d)/, '') || '0').join('-');
+  }
+
+  // Only capture hyphenated M-NN segments when the ROADMAP itself uses that convention.
+  // Legacy ROADMAPs with phase IDs like '1' must use the simple first-segment regex or
+  // a legacy dir like '01-02-setup' (phase 1, slug '02-setup') would match as '1-02'.
+  const roadmapUsesHyphenedIds = [...normalized].some(n => n.includes('-'));
+  const numericRe = roadmapUsesHyphenedIds
+    ? /^0*(\d+(?:-0*\d+)*[A-Za-z]?(?:\.\d+)*)/
+    : /^0*(\d+[A-Za-z]?(?:\.\d+)*)/;
+
   function isDirInMilestone(dirName) {
     // Try numeric match first
-    const m = dirName.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
-    if (m && normalized.has(m[1].toLowerCase())) return true;
+    const m = dirName.match(numericRe);
+    if (m && normalized.has(normalizePhaseIdSegments(m[1]).toLowerCase())) return true;
     // Try custom ID match (e.g. PROJ-42-description → PROJ-42)
     const customMatch = dirName.match(/^([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*)/);
     if (customMatch && normalized.has(customMatch[1].toLowerCase())) return true;
@@ -1971,8 +2359,8 @@ function getMilestonePhaseFilter(cwd, versionOverride) {
     // milestone is keyed on the bare numeric form.
     const stripped = dirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
     if (stripped !== dirName) {
-      const sm = stripped.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
-      if (sm && normalized.has(sm[1].toLowerCase())) return true;
+      const sm = stripped.match(numericRe);
+      if (sm && normalized.has(normalizePhaseIdSegments(sm[1]).toLowerCase())) return true;
     }
     return false;
   }
@@ -2061,6 +2449,8 @@ module.exports = {
   isGitIgnored,
   escapeRegex,
   normalizePhaseName,
+  getMilestoneFromPhaseId,
+  getPhaseDirFromPhaseId,
   phaseMarkdownRegexSource,
   phaseMarkdownRegexSourceExact,
   comparePhaseNum,
@@ -2084,6 +2474,8 @@ module.exports = {
   KNOWN_RUNTIMES,
   RUNTIME_OVERRIDE_TIERS,
   resolveTierEntry,
+  resolveModelPolicy,
+  KNOWN_PROVIDERS,
   _resetRuntimeWarningCacheForTests,
   pathExistsInternal,
   gitWorktreeInfoInternal,