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

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

@@ -10,7 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_RENDERING = exports.KNOWN_PROVIDERS = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
+exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_RENDERING = exports.KNOWN_PROVIDERS = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.ADAPTIVE_TIER_VALUES = exports.VALID_TIERS = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
 exports.nextTier = nextTier;
 exports.formatAgentToModelMapAsTable = formatAgentToModelMapAsTable;
 exports.getAgentToModelMapForProfile = getAgentToModelMapForProfile;
@@ -23,11 +23,19 @@ const _require = require;
 // works in every layout:
 //
 //   1. Co-located install path — gsd-core/bin/shared/model-catalog.json
-//   2. Source-repo dev path — sdk/shared/model-catalog.json
-//   3. GSD_MODEL_CATALOG env override
+//   2. GSD_MODEL_CATALOG env override
+//
+// A third candidate — `sdk/shared/model-catalog.json`, three levels up — used to
+// sit between them. It was the legacy source-repo path kept as a fallback by the
+// #3288 fix, whose contract was "check the co-located path FIRST, before the
+// legacy source-repo path". ADR-0174 then retired the `@opengsd/gsd-sdk` package
+// boundary and deleted the `sdk/` tree outright, so that candidate can no longer
+// resolve in any layout: in a source repo there is no `sdk/`, and in an install
+// layout it points at `~/.claude/sdk/shared/`, which the installer never writes
+// (the original #3288 bug). It is removed rather than left as dead weight that
+// implies a package boundary this repo no longer has.
 const _catalogCandidates = [
     node_path_1.default.resolve(__dirname, '..', 'shared', 'model-catalog.json'),
-    node_path_1.default.resolve(__dirname, '..', '..', '..', 'sdk', 'shared', 'model-catalog.json'),
     ...(process.env['GSD_MODEL_CATALOG'] ? [node_path_1.default.resolve(process.env['GSD_MODEL_CATALOG'])] : []),
 ];
 let catalog = null;
@@ -54,6 +62,13 @@ exports.catalog = _catalog;
 exports.VALID_PROFILES = [..._catalog.profiles];
 exports.VALID_PHASE_TYPES = new Set(_catalog.phaseTypes);
 exports.VALID_AGENT_TIERS = new Set(Object.keys(_catalog.adaptiveTierMap));
+// Catalog-derived so this can never drift from the resolver's tier gate:
+// Object.values(adaptiveTierMap) === ['opus', 'sonnet', 'haiku'] today, plus 'inherit'.
+exports.VALID_TIERS = new Set([...Object.values(_catalog.adaptiveTierMap), 'inherit']);
+// Same catalog-derived tier values as VALID_TIERS but WITHOUT 'inherit' — used
+// by config-loader's runtime-override validation (model_profile_overrides /
+// model_policy.runtime_tiers), which does not accept 'inherit' as a tier.
+exports.ADAPTIVE_TIER_VALUES = new Set(Object.values(_catalog.adaptiveTierMap));
 exports.MODEL_PROFILES = Object.fromEntries(Object.entries(_catalog.agents).map(([agent, meta]) => [agent, {
         quality: meta.golden,
         balanced: meta.balanced,

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

@@ -11,12 +11,17 @@
  * epic #1267; callers import resolvers from model-resolver.cjs directly.
  *
  * Dependencies (leaf modules only):
- *   - node:fs / node:path (stdlib, not currently needed — included for future use)
+ *   - node:fs / node:path (read the per-install .gsd-runtime marker + project config for the #2297 omit gate)
+ *   - ./runtime-name-policy.cjs (resolveRuntimeNameFromCandidates — canonicalize the active runtime)
+ *   - ./planning-workspace.cjs  (planningDir — workstream/project-aware project-config path)
  *   - ./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)
+ *   - ./model-catalog.cjs    (MODEL_ALIAS_MAP, RUNTIME_PROFILE_MAP, PROVIDER_PRESETS, VALID_TIERS)
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderModule = require("./config-loader.cjs");
 const { loadConfig } = configLoaderModule;
@@ -26,6 +31,92 @@ const configuration_cjs_1 = require("./configuration.cjs");
 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");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspaceMod;
+// ─── #2297: per-install runtime identity for the resolve_model_ids:"omit" gate ─
+//
+// The installer writes `resolve_model_ids:"omit"` into the SHARED
+// ~/.gsd/defaults.json for every runtime that lacks native model aliases (#1156).
+// Because that file is machine-wide, a non-Claude install would otherwise poison
+// a Claude no-project resolution into returning '' — silently defeating Claude's
+// adaptive tier aliases. The "omit" must therefore apply only when a runtime that
+// genuinely lacks native aliases is the one resolving.
+//
+// In a no-project session there is no `.planning/config.json` (so config.runtime
+// is null) and GSD_RUNTIME is not exported by gsd-core, so the only reliable
+// current-runtime signal is the per-install marker the installer co-locates next
+// to VERSION at <install>/gsd-core/.gsd-runtime (this file's dir is
+// <install>/gsd-core/bin/lib). Precedence for the gate: project config.runtime →
+// GSD_RUNTIME env (manual/CI override + test seam) → install marker → 'claude'.
+//
+// `claude` is currently the ONLY runtime with nativeModelAliases:true; a
+// registry-parity test guards this set so a future alias-capable runtime fails
+// loudly here instead of silently omitting.
+const RUNTIMES_WITH_NATIVE_ALIASES = new Set(['claude']);
+let _installMarkerCache;
+function readInstallRuntimeMarker() {
+    if (_installMarkerCache !== undefined)
+        return _installMarkerCache;
+    try {
+        const markerPath = node_path_1.default.join(__dirname, '..', '..', '.gsd-runtime');
+        const raw = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+        _installMarkerCache = raw || null;
+    }
+    catch {
+        // No marker: dev/source tree, or an install predating #2297. Fall through to
+        // the 'claude' default (keeps tier aliases — never worse than the bug).
+        _installMarkerCache = null;
+    }
+    return _installMarkerCache;
+}
+// Test seams for the install-marker rung (the dev/source tree has no marker, so
+// the file read always bottoms out at 'claude' — these let tests exercise the
+// third precedence rung and reset the module-level cache between cases).
+function _setInstallRuntimeMarkerForTests(value) {
+    _installMarkerCache = value;
+}
+function _resetInstallRuntimeMarkerCacheForTests() {
+    _installMarkerCache = undefined;
+}
+// The runtime whose install is actually resolving, canonicalized so an alias or
+// case variant (e.g. "claude-code"/"Claude") cannot defeat the native-alias
+// check below (#2297 review). Precedence mirrors resolveRuntime()
+// (runtime-slash.cts): GSD_RUNTIME env → project config.runtime → per-install
+// .gsd-runtime marker → 'claude'.
+function resolveActiveRuntime(config) {
+    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime'], readInstallRuntimeMarker()) || 'claude';
+}
+// Did the PROJECT's own config (root `.planning/config.json` or the active
+// workstream/project override) explicitly set resolve_model_ids to "omit"?
+// Project config takes precedence over the shared ~/.gsd/defaults.json (#2297
+// out-of-scope guard + #2517 finding #4): an explicit project "omit" is honored
+// regardless of runtime, whereas an "omit" that came only from the global
+// defaults is ignored by native-alias runtimes. Workstream/project-scope aware
+// via planningDir (mirrors loadConfig's precedence: workstream value wins over
+// root); a plain read avoids loadConfig's normalization side effects.
+function projectExplicitlySetsOmit(cwd) {
+    const wsDir = planningDir(cwd);
+    const rootDir = node_path_1.default.join(cwd, '.planning');
+    const layers = wsDir === rootDir ? [rootDir] : [wsDir, rootDir]; // workstream > root
+    for (const dir of layers) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, 'config.json'), 'utf8'));
+            const value = parsed?.['resolve_model_ids'];
+            // First layer that sets the key wins (matches loadConfig's deep-merge
+            // precedence). A layer that omits the key falls through to the next.
+            if (value !== undefined)
+                return value === 'omit';
+        }
+        catch {
+            // Absent/unreadable layer — try the next.
+        }
+    }
+    return false;
+}
 /**
  * #2517 — Resolve the runtime-aware tier entry for (runtime, tier).
  */
@@ -209,8 +300,7 @@ function resolveModelInternal(cwd, agentType) {
     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))
+    const tier = (phaseTypeTier && model_catalog_cjs_1.VALID_TIERS.has(phaseTypeTier))
         ? phaseTypeTier
         : (profile === 'inherit'
             ? 'inherit'
@@ -248,8 +338,18 @@ function resolveModelInternal(cwd, agentType) {
         if (entry?.model)
             return entry.model;
     }
-    // 4. resolve_model_ids: "omit"
-    if (config['resolve_model_ids'] === 'omit') {
+    // 4. resolve_model_ids: "omit" — runtime-aware (#2297). Honor "omit" when the
+    // PROJECT explicitly set it (user intent — project config wins, #2517 finding
+    // #4) OR when the active runtime genuinely lacks native model aliases. Only a
+    // native-alias runtime (Claude) ignores an "omit" that came solely from the
+    // SHARED ~/.gsd/defaults.json — the #2297 poisoning fix — and falls through to
+    // its tier aliases below. Active runtime: GSD_RUNTIME → config.runtime → the
+    // per-install .gsd-runtime marker → 'claude' (canonicalized).
+    // NOTE: a non-Claude runtime that HAS a populated runtime-tier map already
+    // returned its own model id at step 3 above, before this gate — for those the
+    // explicit-project-omit honoring here is moot (step 3 wins, by #2517 design).
+    if (config['resolve_model_ids'] === 'omit'
+        && (projectExplicitlySetsOmit(cwd) || !RUNTIMES_WITH_NATIVE_ALIASES.has(resolveActiveRuntime(config)))) {
         return '';
     }
     // 5. Profile lookup (Claude-native default).
@@ -262,7 +362,11 @@ function resolveModelInternal(cwd, agentType) {
     if (tier === 'inherit')
         return 'inherit';
     const alias = tier;
-    if (config['resolve_model_ids']) {
+    // Only the explicit `true` opt-in materializes full model IDs (#1569). Guard
+    // against the loose-truthy check catching a "omit" that a native-alias runtime
+    // ignored above (#2297): "omit" must fall through to the tier ALIAS here, not
+    // be materialized into a full ID Claude's Agent tool cannot spawn.
+    if (config['resolve_model_ids'] === true) {
         return model_catalog_cjs_1.MODEL_ALIAS_MAP[alias] || alias;
     }
     return alias;
@@ -353,6 +457,80 @@ function resolveModelForTier(cwd, agentType, attempt) {
     }
     return alias;
 }
+/**
+ * Keep only usable model ids: non-empty strings. A malformed config can put
+ * anything in here (nulls, numbers, blank strings), and a blank model id would
+ * resolve to an unusable agent invocation rather than failing visibly. Invalid
+ * entries are dropped and the surviving order is preserved, so the ladder stays
+ * predictable (ADR 227 — validate shape, not just type).
+ */
+function sanitizeProviderEscalation(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}
+/**
+ * #2296 — Resolve the model for one attempt of the PROVIDER escalation ladder.
+ *
+ * The tier ladder (`resolveModelForTier`) escalates within one provider's
+ * `tier_models`, which does not help when that provider is the thing that is
+ * throttled. This walks `dynamic_routing.provider_escalation` instead: an
+ * ordered list of alternative model ids, capped by
+ * `min(max_escalations, list length)`.
+ *
+ * `applicable` is the caller's policy decision (only a quota-exceeded
+ * classification should consult this ladder). It is a parameter rather than a
+ * class check here so this module keeps depending only on leaf modules, per
+ * CONTEXT.md's Model Resolution module contract.
+ *
+ * Attempt 0 — and every non-applicable call — stays on the source model.
+ * `exhausted` reports that the ladder is spent so the caller can fail loudly
+ * naming every model it tried.
+ */
+function resolveProviderEscalation(cwd, agentType, attempt, applicable) {
+    // The model that would be used with no provider escalation at all.
+    const from = resolveModelForTier(cwd, agentType, 0);
+    const stay = (exhausted = false) => ({
+        from,
+        to: from,
+        escalated: false,
+        exhausted,
+        attempted: [from],
+        index: 0,
+    });
+    if (!applicable)
+        return stay();
+    const config = loadConfig(cwd);
+    const dr = config['dynamic_routing'];
+    if (!dr || typeof dr !== 'object' || dr['enabled'] !== true)
+        return stay();
+    if (dr['escalate_on_failure'] === false)
+        return stay();
+    const list = sanitizeProviderEscalation(dr['provider_escalation']);
+    if (list.length === 0)
+        return stay();
+    // Same default and same validity rule as the tier ladder above — a negative or
+    // non-integer max_escalations is invalid config, not a request for zero.
+    const maxEscalations = Number.isInteger(dr['max_escalations']) && dr['max_escalations'] >= 0
+        ? dr['max_escalations']
+        : 1;
+    const cap = Math.min(maxEscalations, list.length);
+    // An explicit cap of 0 means the ladder exists but is spent before it starts.
+    if (cap === 0)
+        return stay(true);
+    const attemptN = Number.isInteger(attempt) && attempt > 0 ? attempt : 0;
+    if (attemptN === 0)
+        return stay();
+    const index = Math.min(attemptN, cap);
+    return {
+        from,
+        to: list[index - 1],
+        escalated: true,
+        exhausted: attemptN > cap,
+        attempted: [from, ...list.slice(0, index)],
+        index,
+    };
+}
 // ─── #443 — Unified effort + fast_mode resolvers ─────────────────────────────
 const VALID_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
 const EFFORT_SET = new Set(VALID_EFFORTS);
@@ -515,14 +693,18 @@ function resolveEffortForTier(cwd, agentType, attempt) {
 }
 module.exports = {
     resolveTierEntry,
+    CLAUDE_AGENT_ALIASES,
     resolveModelPolicy,
     resolveModelInternal,
     _resetModelPolicyWarningCacheForTests,
     _resetModelOverrideWarningCacheForTests,
+    _setInstallRuntimeMarkerForTests,
+    _resetInstallRuntimeMarkerCacheForTests,
     VALID_GRANULARITIES,
     resolveGranularityInternal,
     assertValidGranularityOverride,
     resolveModelForTier,
+    resolveProviderEscalation,
     VALID_EFFORTS,
     EFFORT_SET,
     nextEffort,

package/gsd-core/bin/lib/onboard-projection.cjs

@@ -269,7 +269,9 @@ function buildOnboardProjection(cwd, options) {
             projectExists,
             mapReadiness: mapReadinessValue,
             onboardingSummaryExists,
-            onboardingSummaryPath: toPosixPath(node_path_1.default.relative(cwd, onboardingSummaryPath)),
+            // #2376: absolute (anchored on cwd/project_root), not orchestrator-cwd-relative —
+            // a spawned subagent's own cwd may differ from the orchestrator's.
+            onboardingSummaryPath: toPosixPath(onboardingSummaryPath),
             hasPlanningArtifacts,
             missingPlanningFiles,
             handoffCommands,
@@ -289,13 +291,14 @@ function buildOnboardProjection(cwd, options) {
         doc_candidate_count: docCandidates.length,
         doc_candidates: docCandidates,
         onboarding_summary_exists: onboardingSummaryExists,
-        onboarding_summary_path: toPosixPath(node_path_1.default.relative(cwd, onboardingSummaryPath)),
-        project_path: toPosixPath(node_path_1.default.relative(cwd, node_fs_1.default.existsSync(projectRootPath) ? projectRootPath : projectScopedPath)),
-        requirements_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'REQUIREMENTS.md'))),
-        roadmap_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'))),
-        state_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'STATE.md'))),
-        codebase_dir: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningRoot(cwd), 'codebase'))),
-        onboarding_dir: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningRoot(cwd), 'onboarding'))),
+        // #2376: absolute — see comment on onboardingSummaryPath above.
+        onboarding_summary_path: toPosixPath(onboardingSummaryPath),
+        project_path: toPosixPath(node_fs_1.default.existsSync(projectRootPath) ? projectRootPath : projectScopedPath),
+        requirements_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'REQUIREMENTS.md')),
+        roadmap_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
+        state_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
+        codebase_dir: toPosixPath(node_path_1.default.join(planningRoot(cwd), 'codebase')),
+        onboarding_dir: toPosixPath(node_path_1.default.join(planningRoot(cwd), 'onboarding')),
     };
 }
 module.exports = {

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

@@ -137,7 +137,32 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
                 return { ok: true, data: null };
             },
             complete: (_ctx) => {
-                phase.cmdPhaseComplete(cwd, args[2], raw);
+                // #2201: accept --phase N as well as the positional form (the state
+                // family already accepts --phase). An unrecognized flag is a usage
+                // error, not "Phase --phase not found".
+                let phaseNum = null;
+                for (let i = 2; i < args.length; i++) {
+                    if (args[i] === '--phase') {
+                        phaseNum = args[++i];
+                        if (!phaseNum || phaseNum.startsWith('--'))
+                            return makeInvalidArgs('--phase', '--phase requires a value');
+                    }
+                    else if (args[i].startsWith('--phase=')) {
+                        phaseNum = args[i].slice(8);
+                    }
+                    else if (args[i] === '--raw') {
+                        continue;
+                    }
+                    else if (args[i].startsWith('--')) {
+                        return makeInvalidArgs(args[i], `phase complete does not support ${args[i]}`);
+                    }
+                    else {
+                        phaseNum = args[i];
+                    }
+                }
+                if (!phaseNum)
+                    return makeInvalidArgs('--phase', 'phase number required (positional or --phase N)');
+                phase.cmdPhaseComplete(cwd, phaseNum, raw);
                 return { ok: true, data: null };
             },
             'uat-passed': (_ctx) => {
@@ -162,7 +187,30 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
             },
             // #1437 — list plan files for a phase
             'list-plans': (_ctx) => {
-                phase.cmdPhaseListPlans(cwd, args[2], raw);
+                // #2201: accept --phase N as well as positional.
+                let phaseNum = null;
+                for (let i = 2; i < args.length; i++) {
+                    if (args[i] === '--phase') {
+                        phaseNum = args[++i];
+                        if (!phaseNum || phaseNum.startsWith('--'))
+                            return makeInvalidArgs('--phase', '--phase requires a value');
+                    }
+                    else if (args[i].startsWith('--phase=')) {
+                        phaseNum = args[i].slice(8);
+                    }
+                    else if (args[i] === '--raw') {
+                        continue;
+                    }
+                    else if (args[i].startsWith('--')) {
+                        return makeInvalidArgs(args[i], `phase list-plans does not support ${args[i]}`);
+                    }
+                    else {
+                        phaseNum = args[i];
+                    }
+                }
+                if (!phaseNum)
+                    return makeInvalidArgs('--phase', 'phase number required (positional or --phase N)');
+                phase.cmdPhaseListPlans(cwd, phaseNum, raw);
                 return { ok: true, data: null };
             },
         },

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

@@ -48,6 +48,24 @@ const OPTIONAL_PHASE_TAG_SOURCE = '(?:\\s*\\([^)\\n]{0,200}\\))?';
 // (scripts/lint-phase-id-drift.cjs) fails CI if a literal re-derivation is
 // introduced outside this module without a `// phase-id-owner:` justification.
 const PHASE_NUMBER_TOKEN_SOURCE = '\\d+[A-Z]?(?:\\.\\d+)*';
+// #2232: the canonical CONTINUATION-segment grammar — a dash-separated segment
+// that extends a phase token (a zero-padded sub-phase or plan number, e.g. the
+// "01" in "02-01-setup"). getPhaseDirFromPhaseId writes these zero-padded to
+// exactly 2 digits, so the digit RUN of a genuine continuation is exactly 2:
+// #2043's `\d{2,}` (2-or-more) over-collected a slug word that merely leads
+// with ≥2 digits (a year: "14-2026-photos-…" yielded token "14-2026", so every
+// phase-locating verb reported the phase as missing). The `(?!\d)` guard caps
+// the run at 2 without anchoring what may follow, so call sites keep their own
+// trailing grammar (letter suffixes, dotted sub-phases, segment boundaries).
+// POLICY (locked by boundary tests): sub-phase/plan numbers ≥100 are out of the
+// dir-token grammar — the LEADING phase number stays unbounded (`\d+`), only
+// continuation segments are width-capped. Shared from here so the five #2043
+// call sites cannot drift independently (see scripts/lint-phase-id-drift.cjs).
+const PHASE_CONTINUATION_SEGMENT_SOURCE = '\\d{2}(?!\\d)';
+const PHASE_CONTINUATION_SEGMENT_PREFIX_RE = new RegExp(`^${PHASE_CONTINUATION_SEGMENT_SOURCE}`);
+function isPhaseContinuationSegment(seg) {
+    return PHASE_CONTINUATION_SEGMENT_PREFIX_RE.test(seg);
+}
 function stripProjectCodePrefix(value, caseInsensitive = true) {
     const input = String(value);
     const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
@@ -211,9 +229,11 @@ function extractPhaseToken(dirName) {
     }
     const segments = rest.split('-');
     const tokenSegments = [];
-    // #2043: distinguish a real (zero-padded, ≥2-digit) phase/sub-phase segment
-    // from a single-digit slug word. A pure-numeric leading segment ("46") only
-    // continues with ≥2-digit segments, so "46-6-rs-…" yields "46" (the "6" is the
+    // #2043: distinguish a real (zero-padded) phase/sub-phase segment from a
+    // single-digit slug word. A pure-numeric leading segment ("46") only
+    // continues with exactly-2-digit segments (#2232: a ≥3-digit run is a slug
+    // word such as a year — "14-2026-photos-…" yields "14", not "14-2026"), so
+    // "46-6-rs-…" yields "46" (the "6" is the
     // slug's first word), not "46-6". Milestone-prefixed ids like "M1-2" reach here
     // with "M1-" already stripped as a project-code prefix (see
     // PROJECT_CODE_PREFIX_CAPTURE_RE_I), so "2" is the leading segment and the same
@@ -236,7 +256,7 @@ function extractPhaseToken(dirName) {
                 break;
             }
         }
-        else if (/^\d{2,}/.test(seg) || (firstLetterPrefixed && /^\d/.test(seg))) {
+        else if (isPhaseContinuationSegment(seg) || (firstLetterPrefixed && /^\d/.test(seg))) {
             tokenSegments.push(seg);
         }
         else {
@@ -358,6 +378,8 @@ module.exports = {
     OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
     OPTIONAL_PHASE_TAG_SOURCE,
     PHASE_NUMBER_TOKEN_SOURCE,
+    PHASE_CONTINUATION_SEGMENT_SOURCE,
+    isPhaseContinuationSegment,
     stripProjectCodePrefix,
     normalizePhaseName,
     getMilestoneFromPhaseId,

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

@@ -23,53 +23,79 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
 exports.clampPercent = clampPercent;
+const markdown_table_cjs_1 = require("./markdown-table.cjs");
 /**
  * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
  * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ *
+ * ADR-2143 §3 ("addressed by NAME, never ordinal"): the Progress table is
+ * located via the markdown-table seam's `findTableWithColumns`, which is
+ * column-NAME/order/count-invariant — it matches the first table whose header
+ * is a SUPERSET of the canonical `Phase` / `Plans Complete` / `Status` /
+ * `Completed` names, in any order, tolerating extra/injected unrelated
+ * columns (#2137's fast-check property test shuffles headers and injects
+ * columns and asserts the derived counts never change). This supersedes the
+ * earlier `findTableBySchema` exact-schema lookup, which required an exact
+ * canonical column SET+ORDER and returned all-null on any reordering or
+ * injection.
+ *
+ * Scoped to the `## Progress` section when the document has one (#2012 decoy
+ * avoidance — a differently-headed table sharing the same column names must
+ * not be picked up instead); a headingless milestone slice (#1445) falls back
+ * to scanning the whole input, preserving the "Progress table not under a
+ * `## Progress` heading, or not the first table in the document, still
+ * resolves" behaviour.
+ *
+ * Cells are read by column NAME (`r['Status']`, `r['Plans Complete']`,
+ * `r['Phase']`), fixing #2137 (the old position-based regex assumed "Status"
+ * was always the 3rd cell and "Plans Complete" the 2nd, which broke for the
+ * 5-column milestone-grouped variant that inserts a `Milestone` column ahead
+ * of them).
  */
 function deriveProgressFromRoadmap(roadmapContent) {
     let completedPhases = null;
     let totalPhases = null;
     let totalPlans = null;
-    try {
-        // Count Complete rows in the progress table (Status column = "Complete").
-        // Pattern: row where the phase cell starts with a digit (data row, not header),
-        // followed by any cell content, then a "Complete" status cell.
-        // Handles both short form ("| 4. |") and long form ("| 01. Foundation |").
-        // See phase-lifecycle.ts ~line 1655 for the original SDK pattern.
-        const tableCompletePattern = /\|\s*\d+[^|]*\|\s*[^|]*\|\s*Complete\s*\|/gi;
-        const completeMatches = roadmapContent.match(tableCompletePattern);
-        completedPhases = completeMatches ? completeMatches.length : null;
-        // Count total phase rows in the progress table.
-        // Identify the table by looking for Phase|...|Status|...|Completed header.
-        const progressTableMatch = roadmapContent.match(
-        // allow-adhoc-markdown: table-scoped regex with heading lookahead as stop; table parsing, out of seam scope; pending #1372
-        /\|\s*Phase\s*\|[^|]*\|[^|]*Status[^|]*\|[^|]*Completed[^|]*\|[\s\S]*?(?=\n\n|\n##|$)/i);
-        if (progressTableMatch) {
-            const tableText = progressTableMatch[0];
-            // Count data rows (rows starting with pipe then a phase number),
-            // excluding 999.x backlog phases. Mirrors init.cts /^999(?:\.|$)/ filter.
-            const dataRowPattern = /^\|\s*(\d+[^|]*)\|/gm;
-            let dataRowCount = 0;
-            let drm;
-            while ((drm = dataRowPattern.exec(tableText)) !== null) {
-                if (/^999\b/.test(drm[1].trim()))
-                    continue;
-                dataRowCount++;
-            }
-            totalPhases = dataRowCount > 0 ? dataRowCount : null;
-        }
-        // Sum plan counts from M/N columns in progress table
+    // ADR-2143 §5 (fail-loud, no null-swallow): this used to be wrapped in a
+    // try/catch that silently fell through to the existing (null) values on any
+    // thrown error. `findTableWithColumns`/`parseMarkdownTable` never throw —
+    // an unparseable or absent table resolves to `null` /
+    // `{ ok: false, reason }`, not an exception — so the catch was masking
+    // nothing but dead code paths. Removed per ADR-2143 §5; the public
+    // `RoadmapProgress` contract (nulls = absent) is unchanged.
+    //
+    // ADR-2143 §3: read the Progress table by column NAME (order/injection-invariant),
+    // via the markdown-table seam. Scope to the `## Progress` section when present
+    // (#2012 decoy avoidance); a headingless milestone slice (#1445) falls back to the
+    // whole input. Requires the canonical Phase/Plans Complete/Status/Completed columns
+    // in any order (extra columns ignored) — supersedes findTableBySchema's exact-schema lookup.
+    const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
+    let scoped = roadmapContent;
+    if (progressMatch && progressMatch.index !== undefined) {
+        const afterHeading = roadmapContent.slice(progressMatch.index);
+        const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
+        scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
+    }
+    const table = (0, markdown_table_cjs_1.findTableWithColumns)(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
+    if (table) {
+        const allRows = table.rows;
+        const completed = allRows.filter((r) => /^complete$/i.test((r['Status'] ?? '').trim())).length;
+        completedPhases = completed > 0 ? completed : null;
+        // Data rows only (exclude 999.x backlog phases). Mirrors init.cts /^999(?:\.|$)/ filter.
+        const dataRows = allRows.filter((r) => {
+            const phase = (r['Phase'] ?? '').trim();
+            return /^\d/.test(phase) && !/^999\b/.test(phase);
+        });
+        totalPhases = dataRows.length > 0 ? dataRows.length : null;
         let totalPlansSum = 0;
-        const planCellPattern = /\|\s*\d+[^|]*\|\s*(\d+)\/(\d+)\s*\|/gi;
-        let pm;
-        while ((pm = planCellPattern.exec(roadmapContent)) !== null) {
-            totalPlansSum += parseInt(pm[2], 10);
+        for (const r of allRows) {
+            const cell = (r['Plans Complete'] ?? '').trim();
+            const m = /(\d+)\s*\/\s*(\d+)/.exec(cell);
+            if (m)
+                totalPlansSum += parseInt(m[2], 10);
         }
-        if (totalPlansSum > 0)
-            totalPlans = totalPlansSum;
+        totalPlans = totalPlansSum > 0 ? totalPlansSum : null;
     }
-    catch { /* intentionally empty — fall through to existing values */ }
     return { completedPhases, totalPhases, totalPlans };
 }
 /**

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

@@ -34,9 +34,30 @@ const { planningDir } = planningWorkspace;
 function searchPhaseInDir(baseDir, relBase, normalized) {
     try {
         const dirs = readSubdirectories(baseDir, true);
-        const match = dirs.find(d => phaseTokenMatches(d, normalized));
-        if (!match)
+        const matches = dirs.filter(d => phaseTokenMatches(d, normalized));
+        if (matches.length === 0)
             return null;
+        // #2237: fail loud when multiple directories match the same bare phase
+        // number — this happens when unrelated projects share a .planning/phases/
+        // tree. Silently taking the first match risks cross-project file writes.
+        if (matches.length > 1) {
+            return {
+                found: false,
+                directory: '',
+                phase_number: normalized,
+                phase_name: null,
+                phase_slug: null,
+                plans: [],
+                summaries: [],
+                incomplete_plans: [],
+                has_research: false,
+                has_context: false,
+                has_verification: false,
+                has_reviews: false,
+                ambiguous_matches: matches,
+            };
+        }
+        const match = matches[0];
         const phaseToken = extractPhaseToken(match);
         const phaseNumber = phaseToken || normalized;
         const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');