@opengsd/gsd-core 1.7.0 → 1.8.0

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-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.cjs

@@ -106,6 +106,19 @@ function updateTraceabilityCell(text, match, column, newValue) {
         return result;
     return { ok: true, value: before + result.value + after };
 }
+/**
+ * Extract the MAJOR version segment from a version-ish string: "v1", "v1.3",
+ * "V1.0", and "1.0" all yield "1"; "v2" yields "2". Used (#2334 BLOCKER fix)
+ * to compare a `## v<N> ...` REQUIREMENTS.md heading against the current
+ * milestone's version at MAJOR-version granularity only — "v1" heading vs
+ * milestone "v1.3" is the SAME major version and must not be treated as a
+ * version mismatch. Returns null when `raw` has no leading digit run (not a
+ * version-shaped string), which the caller treats as "cannot resolve".
+ */
+function extractMajorVersion(raw) {
+    const m = raw.trim().match(/^v?(\d+)/i);
+    return m ? m[1] : null;
+}
 function describeNonCanonicalPlans(dirFiles, matchedFiles) {
     const matched = new Set(matchedFiles);
     const offenders = dirFiles.filter((f) => looksLikePlanFile(f) && !matched.has(f));
@@ -127,8 +140,13 @@ function extractCanonicalPlanId(filename) {
     // or a single-digit-plus-letter id ("3A"); a *bare* single digit is a slug word,
     // so "46-6-rs-…" is not paired into a "46-6" id while "3A-01" stays intact.
     const tokenRe = /^(?:\d{2,}[A-Z]?|\d[A-Z])(?:\.\d+)*$/i;
+    // #2232: the PAIRED plan component is a zero-padded continuation segment
+    // (exactly 2 digits), so a ≥3-digit slug word (a year) is not paired into a
+    // bogus "14-2026" id. The leading phase component keeps tokenRe's unbounded
+    // \d{2,} — phase numbers ≥100 are legitimate; only continuations are capped.
+    const planTokenRe = new RegExp(`^(?:${phaseIdMod.PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?|\\d[A-Z])(?:\\.\\d+)*$`, 'i');
     const phaseIdx = parts.findIndex((p) => tokenRe.test(p));
-    if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && tokenRe.test(parts[phaseIdx + 1])) {
+    if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && planTokenRe.test(parts[phaseIdx + 1])) {
         return `${parts[phaseIdx]}-${parts[phaseIdx + 1]}`;
     }
     return base;
@@ -603,6 +621,29 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         result['warnings'] = warnings;
     output(result, raw);
 }
+// #2390 — phase.add title-shape heuristic. A description at or under this many
+// characters, and with no sentence-ending punctuation followed by more text,
+// reads as a short Title. Anything longer or multi-sentence reads as a Goal,
+// not a Title. phase.add still writes the phase verbatim (it never mangles
+// ROADMAP.md), but when the description looks goal-shaped the JSON result
+// gains a `warning` key naming the gap, so the caller — or the orchestrating
+// add-phase workflow — can split title vs. goal instead of the whole paragraph
+// landing silently in the `### Phase N:` header.
+const PHASE_ADD_TITLE_MAX_LEN = 80;
+const PHASE_ADD_MULTI_SENTENCE_RE = /[.!?]['")\]]?\s+\S/;
+function describeGoalShapedTitle(description) {
+    const trimmed = description.trim();
+    const tooLong = trimmed.length > PHASE_ADD_TITLE_MAX_LEN;
+    const multiSentence = PHASE_ADD_MULTI_SENTENCE_RE.test(trimmed);
+    if (!tooLong && !multiSentence)
+        return null;
+    const reasons = [
+        tooLong ? `${trimmed.length} chars (over the ${PHASE_ADD_TITLE_MAX_LEN}-char title threshold)` : null,
+        multiSentence ? 'multiple sentences' : null,
+    ].filter(Boolean).join(', ');
+    return (`description looks goal-shaped, not title-shaped (${reasons}). It was written verbatim ` +
+        `as the phase title; consider a short title with the detail moved to **Goal:**.`);
+}
 function cmdPhaseAdd(cwd, description, raw, customId) {
     if (!description) {
         error('description required for phase add');
@@ -690,6 +731,7 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent);
         return { newPhaseId: _newPhaseId, dirName: _dirName };
     });
+    const titleWarning = describeGoalShapedTitle(description);
     const result = {
         phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
         padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId),
@@ -698,7 +740,9 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         directory: toPosixPath(node_path_1.default.join(node_path_1.default.relative(cwd, planningDir(cwd)), 'phases', dirName)),
         naming_mode: config.phase_naming,
     };
-    output(result, raw, result.padded);
+    if (titleWarning)
+        result['warning'] = titleWarning;
+    output(result, raw, result['padded']);
 }
 function cmdPhaseAddBatch(cwd, descriptions, raw) {
     if (!Array.isArray(descriptions) || descriptions.length === 0) {
@@ -1553,13 +1597,43 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     const reqMatch = sectionText.match(/\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]+)/i);
                     const originalReqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
                     let reqContent = originalReqContent;
+                    // #2316: `citedReqIds` — the REQ-IDs ROADMAP's own **Requirements:**
+                    // line for this phase actually cites — is hoisted out of the
+                    // `if (reqMatch)` block (previously scoped only inside it) so the
+                    // ghost-ID cross-check below (~#2316-1) can consult it. `TBD` is the
+                    // literal placeholder `phase.add`/`-batch`/`-insert` seed
+                    // (`**Requirements**: TBD`, src/phase.cts:833,920,1078) — never a
+                    // real REQ-ID, so it is filtered out wherever a cited-ID list feeds
+                    // a warning (#2316-7 boundary).
+                    const isPlaceholderReqId = (id) => id.toUpperCase() === 'TBD';
+                    let citedReqIds = [];
+                    // #2316-1: Traceability-row writes that matched NO row (ghost or
+                    // otherwise) — the `if (reqUpdate.ok)` below previously had no
+                    // `else`, discarding this fact silently instead of surfacing it.
+                    const traceabilityWriteMisses = [];
                     if (reqMatch) {
-                        const reqIds = reqMatch[1]
+                        // #2334 HIGH 3: filter the tokenized capture to the REQ-ID SHAPE —
+                        // the SAME shape bodyReqIds (`\*\*([A-Z][A-Z0-9]*-\d+)\*\*`, below)
+                        // and tableReqIds (`([A-Z][A-Z0-9]*-\d+)`, below) already require —
+                        // so the ghost-ID / unregistered comparisons stay shape-symmetric.
+                        // Without this, `[^\n]+` split on `[,\s]+` turned EVERY word after
+                        // the ID list into a "cited REQ-ID": the shipped
+                        // `templates/roadmap.md:32` line
+                        // `**Requirements**: [REQ-01, REQ-02]  <!-- brackets optional, ... -->`
+                        // warned to register `<!--`, `brackets`, `optional`, `-->`, etc., and
+                        // `**Requirements:** None` warned to register the literal word
+                        // `None`. This subsumes the `TBD` placeholder special-case (`TBD`
+                        // does not match the REQ-ID shape either); `isPlaceholderReqId` is
+                        // kept below as a defensive no-op for any caller that still hands
+                        // it a raw token.
+                        const REQ_ID_SHAPE_RE = /^[A-Z][A-Z0-9]*-\d+$/i;
+                        citedReqIds = reqMatch[1]
                             .replace(/[\[\]]/g, '')
                             .split(/[,\s]+/)
                             .map((r) => r.trim())
-                            .filter(Boolean);
-                        for (const reqId of reqIds) {
+                            .filter(Boolean)
+                            .filter((r) => REQ_ID_SHAPE_RE.test(r));
+                        for (const reqId of citedReqIds) {
                             const reqEscaped = escapeRegex(reqId);
                             reqContent = reqContent.replace(new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'), '$1x$2');
                             // Traceability row: | <REQ-ID> | Phase N | Pending|In Progress | ->
@@ -1578,14 +1652,19 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             // Complete" gate is folded into the newValue callback so one
                             // updateTableCell call both probes and writes.
                             const reqUpdate = updateTraceabilityCell(reqContent, reqRowMatch, 'Status', (current) => /^(?:pending|in progress)$/i.test(current.trim()) ? ' Complete ' : current);
-                            if (reqUpdate.ok)
+                            if (reqUpdate.ok) {
                                 reqContent = reqUpdate.value;
+                            }
+                            else if (!isPlaceholderReqId(reqId)) {
+                                traceabilityWriteMisses.push(reqId);
+                            }
                         }
                     }
                     // #1159 (Defect B): collect requirement IDs only from ACTIVE sections.
                     // Requirements under headings whose text contains "deferred", "backlog",
-                    // "future", or "v2" (case-insensitive) are explicitly out of current scope
-                    // and must not be flagged as missing from the Traceability table.
+                    // "future", or an OFF-milestone `v<N>` (case-insensitive) are explicitly
+                    // out of current scope and must not be flagged as missing from the
+                    // Traceability table.
                     //
                     // Strategy: walk lines, track heading depth, and toggle a "deferred" flag
                     // when a heading matching the pattern is encountered.  A sub-heading (higher
@@ -1593,7 +1672,47 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // opens a same-or-shallower heading that does NOT match the pattern.
                     // Lines inside fenced code blocks (``` or ~~~) are treated as content, not
                     // headings, to avoid false deferred-section detection from code examples.
-                    const DEFERRED_HEADING_RE = /\b(?:deferred|backlog|future|v\d+)\b/i;
+                    //
+                    // #2334 BLOCKER fix (regresses closed bug #1159 against GSD's OWN
+                    // shipped template): #2316-4a dropped the bare `v\d+` alternative
+                    // entirely to stop it over-matching an ACTIVE heading like "## v1
+                    // Requirements" — but the shipped `templates/requirements.md:35`
+                    // scaffold ships `## v2 Requirements` / "Deferred to future release"
+                    // as its ONLY deferred marker, and `v\d+` was the ONLY alternative
+                    // that ever matched a bare version heading (the deferred-ness lives
+                    // in body prose, not the heading text). Dropping it regressed #1159
+                    // for every project scaffolded from the shipped template.
+                    //
+                    // Fix: make the `v<N>` alternative MILESTONE-AWARE instead of
+                    // deleting it. A `## v<N> ...` heading is deferred ONLY when `<N>`
+                    // (MAJOR version only — "v1" vs milestone "v1.3" is the SAME major
+                    // version) does not match the CURRENT milestone's major version,
+                    // resolved via `stateExtractField` against STATE.md's `milestone:`
+                    // frontmatter field (the same seam `getMilestoneInfo`/state.cts's
+                    // frontmatter builder already use — no bespoke frontmatter parsing).
+                    // "## v1 Requirements" while the milestone is v1.x is the ACTIVE
+                    // milestone's own section (#2316's original ask) and must NOT be
+                    // swallowed; "## v2 Requirements" while the milestone is v1.x is a
+                    // genuinely future milestone (#1159's ask, and the literal shipped-
+                    // template shape) and MUST stay suppressed. `deferred`/`backlog`/
+                    // `future` are unaffected by milestone resolution — a genuinely
+                    // deferred heading always spells one of those words too (see
+                    // #2316-5 regression guard: "## Deferred v2 Requirements", "##
+                    // Future Backlog", "## Deferred", "## Backlog", "## Future").
+                    //
+                    // Fail-safe: when the milestone version cannot be resolved at all
+                    // (no STATE.md, or no `milestone:` field), fall back to the OLD
+                    // pre-#2316-4a behavior and treat every `v\d+` heading as deferred.
+                    // A false "deferred" here only ever SUPPRESSES a warning — strictly
+                    // safer than spamming a warning on every v\d+-headed scaffold when
+                    // we cannot tell whether it names the active milestone.
+                    const DEFERRED_KEYWORD_RE = /\b(?:deferred|backlog|future)\b/i;
+                    const HEADING_VERSION_RE = /\bv(\d+)(?:\.\d+)*\b/i;
+                    const stateRawForMilestone = node_fs_1.default.existsSync(statePath) ? node_fs_1.default.readFileSync(statePath, 'utf-8') : null;
+                    const currentMilestoneRaw = stateRawForMilestone
+                        ? stateExtractField(stateRawForMilestone, 'milestone')
+                        : null;
+                    const currentMilestoneMajor = currentMilestoneRaw ? extractMajorVersion(currentMilestoneRaw) : null;
                     const bodyReqIds = [];
                     // deferredDepth: the heading level that opened the current deferred block,
                     // or 0 when we are in an active section.
@@ -1617,11 +1736,21 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             }
                             // Heading at same level or shallower than current deferred opener,
                             // or no active deferred block yet.
-                            if (DEFERRED_HEADING_RE.test(text)) {
+                            if (DEFERRED_KEYWORD_RE.test(text)) {
                                 deferredDepth = depth; // enter a deferred block
                             }
                             else {
-                                deferredDepth = 0; // back in an active section
+                                const versionMatch = text.match(HEADING_VERSION_RE);
+                                if (versionMatch) {
+                                    const headingMajor = versionMatch[1];
+                                    deferredDepth =
+                                        currentMilestoneMajor === null || headingMajor !== currentMilestoneMajor
+                                            ? depth // unresolved milestone (fail-safe) or off-milestone version -> deferred
+                                            : 0; // same major version as the current milestone -> active
+                                }
+                                else {
+                                    deferredDepth = 0; // back in an active section
+                                }
                             }
                             continue;
                         }
@@ -1654,8 +1783,68 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     if (unregistered.length > 0) {
                         warnings.push(`REQUIREMENTS.md: ${unregistered.length} REQ-ID(s) found in body but missing from Traceability table: ${unregistered.join(', ')} — add them manually to keep traceability in sync`);
                     }
+                    // #2316-1: ghost REQ-IDs — cited by ROADMAP's own **Requirements:**
+                    // line for this phase, but registered NOWHERE in REQUIREMENTS.md
+                    // (neither its body nor its Traceability table). The `unregistered`
+                    // check above only ever compares REQUIREMENTS.md's own body against
+                    // its own Traceability table; it never consults `citedReqIds`, so an
+                    // ID that ROADMAP cites but REQUIREMENTS.md never defines at all was
+                    // previously invisible to every guard. `TBD` (the phase.add/-batch/
+                    // -insert placeholder) is excluded — see #2316-7 boundary.
+                    //
+                    // #2334 HIGH 2: classify "ghost" by PROBING THE ACTUAL WRITE
+                    // SURFACES this same function just wrote to (:1947 checkbox,
+                    // :1967 Traceability row) — case-insensitively — mirroring
+                    // milestone.cts's `notFound`/`hasRow`/`doneCheckbox` classification
+                    // (src/milestone.cts:117-141,209-215), instead of set-differencing
+                    // `bodyReqIds` (deferred-filtered, case-sensitive, bold-only) and
+                    // `tableReqIds` (case-sensitive) against `citedReqIds`. Those two
+                    // indexes can disagree with the writes: an ID under a `##
+                    // Deferred` heading gets its checkbox ticked by the write loop
+                    // above but is deliberately EXCLUDED from `bodyReqIds` by the
+                    // deferred-heading filter (#1159), so the old set-diff reported it
+                    // as an unregistered ghost in the SAME response that just ticked
+                    // its checkbox; a case-mismatched citation (`known-01` vs
+                    // `**KNOWN-01**`) lands its write via the writes' case-insensitive
+                    // regexes but failed the old set-diff's case-SENSITIVE
+                    // `Array.includes`/`Set.has`. An ID whose checkbox OR Traceability
+                    // row actually matched is registered — not a ghost — regardless of
+                    // which section (deferred or not) it lives under.
+                    const reqIsRegisteredAnywhere = (id) => {
+                        const reqEscaped = escapeRegex(id);
+                        // Surface 1 — checkbox, EITHER state (`[ ]` or `[x]`), case-
+                        // insensitive: existence check, not the write's space-only match.
+                        if (new RegExp(`-\\s*\\[[ xX]\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent)) {
+                            return true;
+                        }
+                        // Surface 2 — Traceability row exists at all (any Status value),
+                        // via the SAME no-op-probe-through-updateTraceabilityCell
+                        // technique milestone.cts's `hasRow` uses (:210-214): a case-
+                        // insensitive first-cell match, regardless of current Status.
+                        const rowProbeMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === id.toLowerCase();
+                        return updateTraceabilityCell(reqContent, rowProbeMatch, 'Status', (current) => current).ok;
+                    };
+                    const ghostReqIds = citedReqIds.filter((id) => !isPlaceholderReqId(id) && !reqIsRegisteredAnywhere(id));
+                    if (ghostReqIds.length > 0) {
+                        warnings.push(`ROADMAP Phase ${phaseNum} cites REQ-ID(s) not registered anywhere in REQUIREMENTS.md (neither body nor Traceability table): ${ghostReqIds.join(', ')} — add them to REQUIREMENTS.md or correct the ROADMAP citation`);
+                    }
+                    // #2316-1 cont.: a cited ID whose Traceability-row write matched no
+                    // row for a reason OTHER than being a ghost (e.g. a malformed table)
+                    // still deserves a warning instead of a silent discard — but skip
+                    // IDs already reported above as ghosts to avoid a duplicate message
+                    // for the same root cause.
+                    const traceabilityWriteFailures = traceabilityWriteMisses.filter((id) => !ghostReqIds.includes(id));
+                    if (traceabilityWriteFailures.length > 0) {
+                        warnings.push(`REQUIREMENTS.md: Traceability row write skipped for REQ-ID(s) cited by ROADMAP (no matching row found): ${traceabilityWriteFailures.join(', ')}`);
+                    }
                     writes.push({ filePath: reqPath, before: originalReqContent, after: reqContent });
-                    requirementsUpdated = true;
+                    // #2316-3: `requirements_updated` must reflect whether REQUIREMENTS.md
+                    // content actually CHANGED, not merely that the file existed in the
+                    // transaction — mirrors the `writes.push({filePath,before,after})`
+                    // diff-tracking pattern used for the ROADMAP write above. A phase
+                    // whose citations match nothing (ghost REQ-IDs only) must report
+                    // `false`, not a bare "the file was present" `true`.
+                    requirementsUpdated = reqContent !== originalReqContent;
                 }
             }
             try {