@opengsd/gsd-core 1.4.4 → 1.5.0-rc.2

package/gsd-core/bin/lib/model-resolver.cjs

@@ -0,0 +1,426 @@
+"use strict";
+/**
+ * Model Resolver — Model and effort resolution policy
+ *
+ * ADR-857 rollout phase 2f: extracted from core.cts (issue #888).
+ * Owns model and effort resolution policy: resolves the model, runtime tier,
+ * planning granularity, reasoning effort, and fast-mode for a given agent by
+ * reading project config and resolving against the model profiles and catalog.
+ * Behaviour is preserved byte-for-behaviour from the prior location; only
+ * the module boundary moved. core.cjs re-exports the resolvers for back-compat.
+ *
+ * New imports should pull resolvers from model-resolver.cjs directly.
+ *
+ * Dependencies (leaf modules only — no core.cjs):
+ *   - node:fs / node:path (stdlib, not currently needed — included for future use)
+ *   - ./config-loader.cjs    (loadConfig)
+ *   - ./configuration.cjs    (CONFIG_DEFAULTS as CANONICAL_CONFIG_DEFAULTS)
+ *   - ./model-profiles.cjs   (MODEL_PROFILES, AGENT_TO_PHASE_TYPE, AGENT_DEFAULT_TIERS, VALID_AGENT_TIERS, nextTier)
+ *   - ./model-catalog.cjs    (MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, PROVIDER_PRESETS)
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderModule = require("./config-loader.cjs");
+const { loadConfig } = configLoaderModule;
+// ─── Configuration Module (for CANONICAL_CONFIG_DEFAULTS used by effort/fast_mode resolvers) ─
+const configuration_cjs_1 = require("./configuration.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const modelProfiles = require("./model-profiles.cjs");
+const { MODEL_PROFILES, AGENT_TO_PHASE_TYPE, AGENT_DEFAULT_TIERS, VALID_AGENT_TIERS, nextTier } = modelProfiles;
+const model_catalog_cjs_1 = require("./model-catalog.cjs");
+/**
+ * #2517 — Resolve the runtime-aware tier entry for (runtime, tier).
+ */
+function resolveTierEntry({ runtime, tier, overrides }) {
+    if (!runtime || !tier)
+        return null;
+    const runtimeMap = model_catalog_cjs_1.RUNTIME_PROFILE_MAP;
+    const builtin = runtimeMap[runtime]?.[tier] || null;
+    const overridesMap = overrides;
+    const userRaw = overridesMap?.[runtime]?.[tier];
+    let userEntry = null;
+    if (userRaw) {
+        userEntry = typeof userRaw === 'string' ? { model: userRaw } : userRaw;
+    }
+    if (!builtin && !userEntry)
+        return null;
+    return { ...(builtin || {}), ...(userEntry || {}) };
+}
+/**
+ * Convenience wrapper used by resolveModelInternal.
+ */
+function _resolveRuntimeTier(config, tier) {
+    return resolveTierEntry({
+        runtime: config['runtime'],
+        tier,
+        overrides: config['model_profile_overrides'],
+    });
+}
+/**
+ * #49 — Provider-neutral model policy preset resolution.
+ */
+function resolveModelPolicy(policy, tier) {
+    if (!policy || typeof policy !== 'object')
+        return null;
+    if (!tier)
+        return null;
+    const runtime = policy['runtime'];
+    const rtOverrides = policy['runtime_tiers'];
+    if (runtime && typeof runtime === 'string' && rtOverrides && typeof rtOverrides === 'object') {
+        const rtOverridesMap = rtOverrides;
+        if (Object.hasOwn(rtOverridesMap, runtime)) {
+            const runtimeEntry = rtOverridesMap[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'];
+                }
+            }
+        }
+    }
+    const provider = policy['provider'];
+    if (!provider || typeof provider !== 'string')
+        return null;
+    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;
+    }
+    const presetsMap = model_catalog_cjs_1.PROVIDER_PRESETS;
+    if (!Object.hasOwn(presetsMap, provider))
+        return null;
+    const presetForProvider = presetsMap[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;
+    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;
+    return budgetEntry.model;
+}
+function resolveModelInternal(cwd, agentType) {
+    const config = loadConfig(cwd);
+    // 1. Per-agent override
+    const modelOverrides = config['model_overrides'];
+    const override = modelOverrides?.[agentType];
+    if (override) {
+        return override;
+    }
+    // 2. Compute the tier
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const profile = String(config['model_profile'] || 'balanced').toLowerCase();
+    const agentModels = MODEL_PROFILES[agentType];
+    const phaseType = (AGENT_TO_PHASE_TYPE)[agentType];
+    const configModels = config['models'];
+    const phaseTypeTier = (phaseType && configModels && typeof configModels === 'object')
+        ? configModels[phaseType]
+        : undefined;
+    const VALID_TIERS = new Set(['opus', 'sonnet', 'haiku', 'inherit']);
+    const tier = (phaseTypeTier && VALID_TIERS.has(phaseTypeTier))
+        ? phaseTypeTier
+        : (profile === 'inherit'
+            ? 'inherit'
+            : (agentModels ? (agentModels[profile] || agentModels['balanced']) : null));
+    // 2.5. model_policy preset (#49)
+    const configRuntime = config['runtime'];
+    if (configRuntime && configRuntime !== 'claude' && tier && tier !== 'inherit') {
+        const mergedPolicy = config['model_policy']
+            ? { ...config['model_policy'], runtime: configRuntime }
+            : null;
+        const policyModel = resolveModelPolicy(mergedPolicy, tier);
+        if (policyModel)
+            return policyModel;
+    }
+    // 3. Runtime-aware resolution (#2517)
+    if (configRuntime && configRuntime !== 'claude' && tier && tier !== 'inherit') {
+        const entry = _resolveRuntimeTier(config, tier);
+        if (entry?.model)
+            return entry.model;
+    }
+    // 4. resolve_model_ids: "omit"
+    if (config['resolve_model_ids'] === 'omit') {
+        return '';
+    }
+    // 5. Profile lookup (Claude-native default).
+    if (!agentModels) {
+        return profile === 'quality' ? 'opus'
+            : profile === 'budget' ? 'haiku'
+                : profile === 'inherit' ? 'inherit'
+                    : 'sonnet';
+    }
+    if (tier === 'inherit')
+        return 'inherit';
+    const alias = tier;
+    if (config['resolve_model_ids']) {
+        return model_catalog_cjs_1.MODEL_ALIAS_MAP[alias] || alias;
+    }
+    return alias;
+}
+const VALID_GRANULARITIES = new Set(['coarse', 'standard', 'fine']);
+/**
+ * Resolve the planning granularity for a phase type (#68).
+ */
+function resolveGranularityInternal(cwd, phaseType, override) {
+    if (override !== undefined && override !== null && override !== '') {
+        if (VALID_GRANULARITIES.has(override)) {
+            return override;
+        }
+    }
+    const config = loadConfig(cwd);
+    const configGranularities = config['granularities'];
+    const perPhase = (phaseType && configGranularities && typeof configGranularities === 'object')
+        ? configGranularities[phaseType]
+        : undefined;
+    if (perPhase && VALID_GRANULARITIES.has(perPhase)) {
+        return perPhase;
+    }
+    if (config['granularity'] !== undefined && config['granularity'] !== null && config['granularity'] !== '') {
+        return config['granularity'];
+    }
+    const planning = config['planning'];
+    const planningGran = planning && planning['granularity'];
+    if (planningGran !== undefined && planningGran !== null && planningGran !== '') {
+        return planningGran;
+    }
+    return 'standard';
+}
+/**
+ * Validate a CLI granularity override at the command boundary. Empty/null/undefined
+ * are treated as "no override" (no-op). An invalid non-empty value calls `fail`.
+ */
+function assertValidGranularityOverride(override, fail) {
+    if (override !== undefined && override !== null && override !== '' && !VALID_GRANULARITIES.has(override)) {
+        fail(`invalid granularity '${override}' (valid: ${[...VALID_GRANULARITIES].join(', ')})`);
+    }
+}
+/**
+ * #3024 — Resolve a model for a specific dynamic-routing attempt.
+ */
+function resolveModelForTier(cwd, agentType, attempt) {
+    const config = loadConfig(cwd);
+    const attemptN = Number.isInteger(attempt) && attempt > 0 ? attempt : 0;
+    const modelOverrides = config['model_overrides'];
+    const override = modelOverrides?.[agentType];
+    if (override)
+        return override;
+    if (config['model_policy'] && config['runtime'] && config['runtime'] !== 'claude') {
+        return resolveModelInternal(cwd, agentType);
+    }
+    const dr = config['dynamic_routing'];
+    if (!dr || typeof dr !== 'object' || dr['enabled'] !== true) {
+        return resolveModelInternal(cwd, agentType);
+    }
+    const tierModels = dr['tier_models'];
+    if (!tierModels || typeof tierModels !== 'object') {
+        return resolveModelInternal(cwd, agentType);
+    }
+    const defaultTier = (AGENT_DEFAULT_TIERS)[agentType];
+    if (!defaultTier || !(VALID_AGENT_TIERS).has(defaultTier)) {
+        return resolveModelInternal(cwd, agentType);
+    }
+    const maxEscalations = Number.isInteger(dr['max_escalations']) && dr['max_escalations'] >= 0
+        ? dr['max_escalations']
+        : 1;
+    const escalationEnabled = dr['escalate_on_failure'] !== false;
+    const effectiveAttempt = escalationEnabled
+        ? Math.min(attemptN, maxEscalations)
+        : 0;
+    let tier = defaultTier;
+    for (let i = 0; i < effectiveAttempt; i += 1) {
+        const next = (nextTier)(tier);
+        if (!next || next === tier)
+            break;
+        tier = next;
+    }
+    const alias = tierModels[tier];
+    if (typeof alias !== 'string' || alias.length === 0) {
+        return resolveModelInternal(cwd, agentType);
+    }
+    return alias;
+}
+// ─── #443 — Unified effort + fast_mode resolvers ─────────────────────────────
+const VALID_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+const EFFORT_SET = new Set(VALID_EFFORTS);
+/**
+ * Walk one step up the effort ladder from `e`.
+ */
+function nextEffort(e) {
+    const i = VALID_EFFORTS.indexOf(e);
+    if (i < 0)
+        return null;
+    return VALID_EFFORTS[Math.min(i + 1, VALID_EFFORTS.length - 1)];
+}
+/**
+ * #443 — Resolve a universal effort string for (cwd, agentType).
+ */
+function resolveEffortInternal(cwd, agentType, opts) {
+    // Step 1: invocation override
+    if (opts && typeof opts.override === 'string' && EFFORT_SET.has(opts.override)) {
+        return opts.override;
+    }
+    const config = loadConfig(cwd);
+    const effortCfg = (config['effort'] && typeof config['effort'] === 'object' && !Array.isArray(config['effort']))
+        ? config['effort']
+        : null;
+    // Step 2: agent_overrides
+    if (effortCfg) {
+        const ao = effortCfg['agent_overrides'];
+        if (ao && typeof ao === 'object' && !Array.isArray(ao)) {
+            const v = ao[agentType];
+            if (typeof v === 'string' && EFFORT_SET.has(v))
+                return v;
+        }
+    }
+    else {
+        const canonicalEffort = (configuration_cjs_1.CONFIG_DEFAULTS)['effort'];
+        const mao = canonicalEffort && typeof canonicalEffort === 'object'
+            ? canonicalEffort['agent_overrides']
+            : undefined;
+        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.
+    const agentTier = (AGENT_DEFAULT_TIERS)[agentType];
+    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' && EFFORT_SET.has(v))
+                return v;
+        }
+        else if (!effortCfg) {
+            const canonicalEffort = (configuration_cjs_1.CONFIG_DEFAULTS)['effort'];
+            const manifestDefaults = canonicalEffort && typeof canonicalEffort === 'object'
+                ? canonicalEffort['routing_tier_defaults']
+                : undefined;
+            if (manifestDefaults && typeof manifestDefaults === 'object') {
+                const v = manifestDefaults[agentTier];
+                if (typeof v === 'string' && EFFORT_SET.has(v))
+                    return v;
+            }
+        }
+    }
+    // Step 4: effort.default
+    if (effortCfg) {
+        const d = effortCfg['default'];
+        if (typeof d === 'string' && EFFORT_SET.has(d))
+            return d;
+    }
+    else {
+        const canonicalEffort = (configuration_cjs_1.CONFIG_DEFAULTS)['effort'];
+        const d = canonicalEffort && typeof canonicalEffort === 'object'
+            ? canonicalEffort['default']
+            : undefined;
+        if (typeof d === 'string' && EFFORT_SET.has(d))
+            return d;
+    }
+    // Step 5: hardcoded default
+    return 'high';
+}
+/**
+ * #443 — Resolve fast_mode boolean for (cwd, agentType).
+ */
+function resolveFastModeInternal(cwd, agentType, opts) {
+    // Step 1: invocation override
+    if (opts && typeof opts.override === 'boolean') {
+        return opts.override;
+    }
+    const config = loadConfig(cwd);
+    const fmCfg = (config['fast_mode'] && typeof config['fast_mode'] === 'object' && !Array.isArray(config['fast_mode']))
+        ? config['fast_mode']
+        : null;
+    // Step 2: agent_overrides
+    if (fmCfg) {
+        const ao = fmCfg['agent_overrides'];
+        if (ao && typeof ao === 'object' && !Array.isArray(ao)) {
+            const v = ao[agentType];
+            if (typeof v === 'boolean')
+                return v;
+        }
+    }
+    // Step 3: routing_tier_defaults by agent's default tier.
+    const agentTier = (AGENT_DEFAULT_TIERS)[agentType];
+    if (agentTier) {
+        if (fmCfg && fmCfg['routing_tier_defaults'] &&
+            typeof fmCfg['routing_tier_defaults'] === 'object' &&
+            !Array.isArray(fmCfg['routing_tier_defaults'])) {
+            const v = fmCfg['routing_tier_defaults'][agentTier];
+            if (typeof v === 'boolean')
+                return v;
+        }
+        else if (!fmCfg) {
+            const canonicalFm = (configuration_cjs_1.CONFIG_DEFAULTS)['fast_mode'];
+            const manifestDefaults = canonicalFm && typeof canonicalFm === 'object'
+                ? canonicalFm['routing_tier_defaults']
+                : undefined;
+            if (manifestDefaults && typeof manifestDefaults === 'object') {
+                const v = manifestDefaults[agentTier];
+                if (typeof v === 'boolean')
+                    return v;
+            }
+        }
+    }
+    // Step 4: fast_mode.enabled
+    if (fmCfg && typeof fmCfg['enabled'] === 'boolean') {
+        return fmCfg['enabled'];
+    }
+    // Step 5: hardcoded default
+    return false;
+}
+/**
+ * #443 — Resolve effort for a dynamic-routing attempt (with escalation).
+ */
+function resolveEffortForTier(cwd, agentType, attempt) {
+    const base = resolveEffortInternal(cwd, agentType);
+    const config = loadConfig(cwd);
+    const dr = config['dynamic_routing'];
+    if (!dr || typeof dr !== 'object' || dr['enabled'] !== true) {
+        return base;
+    }
+    if (dr['escalate_on_failure'] === false) {
+        return base;
+    }
+    const maxEscalations = Number.isInteger(dr['max_escalations']) && dr['max_escalations'] >= 0
+        ? dr['max_escalations']
+        : 1;
+    const attemptN = Number.isInteger(attempt) && attempt > 0 ? attempt : 0;
+    const effectiveAttempt = Math.min(attemptN, maxEscalations);
+    let current = base;
+    for (let i = 0; i < effectiveAttempt; i++) {
+        const next = nextEffort(current);
+        if (!next || next === current)
+            break;
+        current = next;
+    }
+    return current;
+}
+module.exports = {
+    resolveTierEntry,
+    resolveModelPolicy,
+    resolveModelInternal,
+    VALID_GRANULARITIES,
+    resolveGranularityInternal,
+    assertValidGranularityOverride,
+    resolveModelForTier,
+    VALID_EFFORTS,
+    EFFORT_SET,
+    nextEffort,
+    resolveEffortInternal,
+    resolveFastModeInternal,
+    resolveEffortForTier,
+};

package/gsd-core/bin/lib/phase-command-router.cjs

@@ -140,6 +140,26 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
                 phase.cmdPhaseComplete(cwd, args[2], raw);
                 return { ok: true, data: null };
             },
+            'uat-passed': (_ctx) => {
+                let requireVerification = false;
+                const positional = [];
+                for (const token of args.slice(2)) {
+                    if (token === '--require-verification') {
+                        requireVerification = true;
+                    }
+                    else if (token === '--raw') {
+                        // --raw is handled by the outer CLI layer; accepted here silently
+                    }
+                    else if (token.startsWith('--')) {
+                        return makeInvalidArgs(token, `phase uat-passed does not support ${token}`);
+                    }
+                    else {
+                        positional.push(token);
+                    }
+                }
+                phase.cmdPhaseUatPassed(cwd, positional[0], raw, { policy: { requireVerification } });
+                return { ok: true, data: null };
+            },
         },
     };
     // ── Build manifest (available subcommands for UnknownCommand detection) ─────

package/gsd-core/bin/lib/phase-id.cjs

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Pure phase-id parsing/matching helpers — normalize, token match,
+ * milestone/phase-dir id parsing, phase-markdown regex builders.
+ *
+ * Extracted from core.cts (ADR-857 rollout phase 2a / issue #865).
+ * The hand-written bodies are preserved byte-for-behaviour; only the module
+ * boundary moved. core.cts re-exports every symbol here under its own
+ * `export =` object so existing consumers are unaffected.
+ *
+ * New imports should pull phase-id helpers from phase-id.cjs directly.
+ *
+ * Dependencies: none (pure string/regex, no Node built-ins required).
+ */
+// ─── Phase-id helpers ─────────────────────────────────────────────────────────
+function escapeRegex(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+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).
+    const milestoneMatch = stripped.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
+    if (milestoneMatch) {
+        const major = milestoneMatch[1].padStart(2, '0');
+        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) {
+        const padded = match[1].padStart(2, '0');
+        // Preserve original case of letter suffix (#1962).
+        const letter = match[2] || '';
+        const decimal = match[3] || '';
+        return padded + letter + decimal;
+    }
+    // Custom phase IDs (e.g. PROJ-42, AUTH-101): return as-is
+    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.
+ */
+function phaseMarkdownRegexSource(phaseNum) {
+    const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    // Milestone-prefixed IDs: M-NN or M-N-N (deep).
+    const milestoneSegments = stripped.match(/^(\d+)((?:-\d+)*)([A-Z]?(?:\.\d+)*)$/i);
+    if (milestoneSegments && milestoneSegments[2]) {
+        const majorUnpadded = milestoneSegments[1].replace(/^0+/, '') || '0';
+        const subParts = milestoneSegments[2].slice(1).split('-');
+        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);
+    const integer = match[1].replace(/^0+/, '') || '0';
+    const letter = match[2] ? escapeRegex(match[2]) : '';
+    const decimal = match[3] ? escapeRegex(match[3]) : '';
+    return `0*${escapeRegex(integer)}${letter}${decimal}`;
+}
+/**
+ * #3599: when the caller passed a project-code-prefixed ID like `PROJ-42`,
+ * return the exact-escaped form.
+ */
+function phaseMarkdownRegexSourceExact(phaseNum) {
+    const raw = String(phaseNum);
+    if (!/^[A-Z]{1,6}-(?=\d)/i.test(raw))
+        return null;
+    return escapeRegex(raw);
+}
+function comparePhaseNum(a, b) {
+    // Strip optional project_code prefix before comparing
+    const sa = String(a).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const sb = String(b).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    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;
+        }
+        const sufA = milestoneA[3] || '';
+        const sufB = milestoneB[3] || '';
+        if (sufA !== sufB)
+            return sufA < sufB ? -1 : 1;
+        return 0;
+    }
+    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 (!pa || !pb)
+        return String(a).localeCompare(String(b));
+    const intDiff = parseInt(pa[1], 10) - parseInt(pb[1], 10);
+    if (intDiff !== 0)
+        return intDiff;
+    const la = (pa[2] || '').toUpperCase();
+    const lb = (pb[2] || '').toUpperCase();
+    if (la !== lb) {
+        if (!la)
+            return -1;
+        if (!lb)
+            return 1;
+        return la < lb ? -1 : 1;
+    }
+    const aDecParts = pa[3] ? pa[3].slice(1).split('.').map(p => parseInt(p, 10)) : [];
+    const bDecParts = pb[3] ? pb[3].slice(1).split('.').map(p => parseInt(p, 10)) : [];
+    const maxLen = Math.max(aDecParts.length, bDecParts.length);
+    if (aDecParts.length === 0 && bDecParts.length > 0)
+        return -1;
+    if (bDecParts.length === 0 && aDecParts.length > 0)
+        return 1;
+    for (let i = 0; i < maxLen; i++) {
+        const av = Number.isFinite(aDecParts[i]) ? aDecParts[i] : 0;
+        const bv = Number.isFinite(bDecParts[i]) ? bDecParts[i] : 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    return 0;
+}
+/**
+ * Extract the phase token from a directory name.
+ */
+function extractPhaseToken(dirName) {
+    const codePrefixMatch = dirName.match(/^([A-Z]{1,6})-(\d.*)/i);
+    let prefix = '';
+    let rest = dirName;
+    if (codePrefixMatch) {
+        prefix = codePrefixMatch[1] + '-';
+        rest = codePrefixMatch[2];
+    }
+    const segments = rest.split('-');
+    const tokenSegments = [];
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (/^\d/.test(seg)) {
+            tokenSegments.push(seg);
+        }
+        else {
+            break;
+        }
+    }
+    if (tokenSegments.length === 0) {
+        return dirName;
+    }
+    return prefix + tokenSegments.join('-');
+}
+/**
+ * Check if a directory name's phase token matches the normalized phase exactly.
+ */
+function phaseTokenMatches(dirName, normalized) {
+    const token = extractPhaseToken(dirName);
+    if (token.toUpperCase() === normalized.toUpperCase())
+        return true;
+    const stripped = dirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    if (stripped !== dirName) {
+        const strippedToken = extractPhaseToken(stripped);
+        if (strippedToken.toUpperCase() === normalized.toUpperCase())
+            return true;
+    }
+    return false;
+}
+module.exports = {
+    escapeRegex,
+    normalizePhaseName,
+    getMilestoneFromPhaseId,
+    getPhaseDirFromPhaseId,
+    phaseMarkdownRegexSource,
+    phaseMarkdownRegexSourceExact,
+    comparePhaseNum,
+    extractPhaseToken,
+    phaseTokenMatches,
+};