@opengsd/gsd-core 1.14.0 → 1.15.0

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

@@ -123,7 +123,13 @@ function resolveTierEntry({ runtime, tier, overrides }) {
  */
 function _resolveRuntimeTier(config, tier) {
     return resolveTierEntry({
-        runtime: config['runtime'],
+        // #4505/#4495: TIER SELECTION follows the runtime that is actually
+        // resolving, not whatever the config file happens to say. `config.runtime`
+        // is frequently absent (the runtime is normally known from GSD_RUNTIME or
+        // the per-install marker), and reading it raw made
+        // `model_profile_overrides.<runtime>.<tier>` silently inert for every
+        // install that did not also write the key by hand.
+        runtime: resolveActiveRuntime(config),
         tier,
         overrides: config['model_profile_overrides'],
     });
@@ -142,10 +148,19 @@ function _resolveRuntimeTier(config, tier) {
  *
  * This helper reads ONLY the user's override entry for the effective claude
  * runtime and tier — never the builtin claude tier map — so an install with no
- * override is byte-identical to before the fix. The runtime is resolved the
- * same way steps 1-3 resolve it (config['runtime'], defaulting to 'claude'),
- * NOT via resolveActiveRuntime (GSD_RUNTIME/marker): the value policy must
- * key off the config the operator wrote, matching mapClaudeOverrideForRuntime.
+ * override is byte-identical to before the fix.
+ *
+ * #4505 CHANGED how the runtime reaches here. #4192 originally passed
+ * `config['runtime']` and recorded that the value policy "must key off the
+ * config the operator wrote, NOT resolveActiveRuntime". That reading turned out
+ * to defeat #4192's own stated principle — that an explicit pin must not be
+ * silently UNPINNED. With `config.runtime` absent and GSD_RUNTIME=opencode, the
+ * config-keyed read treated the session as claude and collapsed an explicit
+ * `claude-opus-4-8` pin to the bare alias `opus`, which is a Claude-only token
+ * the actual runtime cannot spawn. The runtime is now the ACTIVE one, so the
+ * claude value policy applies exactly when claude is what is running. No test
+ * pinned the previous behaviour; the ones covering #4192's pins and the
+ * alias-native posture all still pass.
  *
  * Value policy mirrors the model_overrides path (#2041/#4192): an override
  * value that maps to a current tier alias collapses to that alias
@@ -155,10 +170,12 @@ function _resolveRuntimeTier(config, tier) {
  * Malformed entries (no usable `model` string) return null so the caller falls
  * through to normal alias resolution (ADR-443 D1: invalid values fall through).
  */
-function resolveClaudeTierOverrideModel(configRuntime, tier, overrides) {
+function resolveClaudeTierOverrideModel(
+// The ACTIVE runtime (#4505), not the raw config key — see docblock.
+activeRuntime, tier, overrides) {
     if (!tier || tier === 'inherit')
         return null;
-    const effectiveRuntime = configRuntime || 'claude';
+    const effectiveRuntime = activeRuntime || 'claude';
     if (effectiveRuntime !== 'claude')
         return null; // non-claude runtimes resolve at step 3
     const overridesMap = overrides;
@@ -264,13 +281,18 @@ function _resetModelOverrideWarningCacheForTests() {
  * `Object.hasOwn` lookup defeats `__proto__`/`constructor` lookups on the plain
  * object literal so those reserved keys cannot return a truthy non-string.
  */
-function mapClaudeOverrideForRuntime(override, configRuntime, agentType) {
+function mapClaudeOverrideForRuntime(override, 
+// The ACTIVE runtime (#4505). Previously the raw `config['runtime']`, which
+// made an explicit claude pin collapse to a bare alias whenever the runtime
+// was declared via GSD_RUNTIME or the install marker rather than the config —
+// handing a Claude-only token to a runtime that cannot spawn it.
+activeRuntime, agentType) {
     // Defensive: model_overrides is typed Record<string,string> but a malformed
     // config could surface a non-string; pass through verbatim (preserving the
     // pre-fix no-crash behaviour) and let the downstream Agent tool reject it.
     if (typeof override !== 'string')
         return override;
-    const onClaude = !configRuntime || configRuntime === 'claude';
+    const onClaude = !activeRuntime || activeRuntime === 'claude';
     if (!onClaude)
         return override;
     // Object.hasOwn guards against __proto__/constructor returning a truthy
@@ -480,7 +502,7 @@ function resolveModelInternal(cwd, agentType) {
         ? modelOverrides[agentType]
         : undefined;
     if (override) {
-        const mapped = mapClaudeOverrideForRuntime(override, config['runtime'], agentType);
+        const mapped = mapClaudeOverrideForRuntime(override, resolveActiveRuntime(config), agentType);
         if (mapped !== null)
             return mapped;
         // Unmappable Claude ID — fall through to tier resolution (matches model_policy).
@@ -497,10 +519,19 @@ function resolveModelInternal(cwd, agentType) {
     const agentModels = Object.hasOwn(modelProfilesMapForModel, agentType) ? modelProfilesMapForModel[agentType] : undefined;
     const tier = computeProfileTier(config, agentType);
     // 2.5. model_policy preset (#49, #1133)
+    // `configRuntime` is retained ONLY as the EXPLICIT-OPT-IN signal for step 3's
+    // precedence over the omit gate (see the note there). Every actual runtime
+    // question — which tier map to read, which value policy applies — now uses
+    // the active runtime (#4505).
     const configRuntime = config['runtime'];
+    // #4505/#4495: GSD_RUNTIME -> config.runtime -> per-install marker -> 'claude'.
+    // Never undefined, so the "no runtime declared anywhere" case still resolves
+    // 'claude' and step 3's deliberate claude skip (#1156/#2297/#4192) is
+    // unchanged for every existing install.
+    const activeRuntime = resolveActiveRuntime(config);
     if (tier && tier !== 'inherit') {
-        const onClaude = !configRuntime || configRuntime === 'claude';
-        const effectiveRuntime = configRuntime || 'claude';
+        const onClaude = activeRuntime === 'claude';
+        const effectiveRuntime = activeRuntime;
         const mergedPolicy = config['model_policy']
             ? { ...config['model_policy'], runtime: effectiveRuntime }
             : null;
@@ -525,8 +556,49 @@ function resolveModelInternal(cwd, agentType) {
             warnModelPolicyUnmappable(agentType, policyModel, tier);
         }
     }
-    // 3. Runtime-aware resolution (#2517)
-    if (configRuntime && configRuntime !== 'claude' && tier && tier !== 'inherit') {
+    // #4505: the omit DECISION is computed here, ahead of step 3, though the
+    // return still happens at step 4 below.
+    //
+    // Step 3 was previously unreachable unless the operator had written `runtime`
+    // into the config. Keying it off the ACTIVE runtime — the #4495 fix — makes it
+    // reachable for env- and marker-declared runtimes too, which newly exposes an
+    // ordering the corpus already decided, in two places that only coexisted
+    // because step 3 could not fire:
+    //
+    //   #2517  `runtime:"codex"` + resolve_model_ids:"omit"  -> the codex tier
+    //          model. "Explicit non-Claude opt-in wins" — the operator naming a
+    //          runtime in the project config outranks an omit.
+    //   #4717 (user-sanctioned decision a — supersedes #2297 acceptance #4):
+    //          a DETECTED runtime now constitutes that opt-in too. The identity
+    //          fill in config-loader materializes GSD_RUNTIME / the per-install
+    //          marker into `config.runtime` when it is empty, so a genuinely
+    //          installed non-Claude runtime resolves its own tier map instead of
+    //          the omit's "". The shared "omit" remains a Claude protection:
+    //          marker/env = claude still ignores it (native aliases), and
+    //          garbage runtime values still fail safe to "" (guard below).
+    //
+    // So the opt-in signal is the `runtime` KEY — written by the operator or
+    // materialized by the #4717 fill: step 3 reads the active runtime's tier
+    // map, but only outranks the omit gate when that key canonicalizes to a
+    // recognised non-Claude runtime.
+    const omitApplies = config['resolve_model_ids'] === 'omit'
+        && (projectExplicitlySetsOmit(cwd) || !RUNTIMES_WITH_NATIVE_ALIASES.has(activeRuntime));
+    // CANONICALIZED, not the raw field. Comparing the raw value against the literal
+    // 'claude' made every spelling that is not exactly that string count as a
+    // non-Claude opt-in and outrank the omit gate: `runtime:"Claude"`,
+    // `runtime:"claude-code"` and even `runtime:5` each emitted a model id where
+    // origin/next returned "". That is the #2297 acceptance-#4 case this very
+    // block claims to preserve, failing OPEN. (Security review of #4505.)
+    //
+    // null covers both "not a string" and "not a runtime we recognise", and both
+    // must read as NOT an opt-in: an unrecognised value is not evidence the
+    // operator deliberately chose a non-Claude runtime, so it must not buy an
+    // escalation past an explicit omit.
+    const configRuntimeCanonical = (0, runtime_name_policy_cjs_1.canonicalizeRuntimeName)(configRuntime);
+    const explicitNonClaudeOptIn = configRuntimeCanonical !== null && configRuntimeCanonical !== 'claude';
+    // 3. Runtime-aware resolution (#2517), keyed off the ACTIVE runtime (#4505).
+    if (activeRuntime !== 'claude' && tier && tier !== 'inherit'
+        && (explicitNonClaudeOptIn || !omitApplies)) {
         const entry = _resolveRuntimeTier(config, tier);
         if (entry?.model)
             return entry.model;
@@ -541,8 +613,7 @@ function resolveModelInternal(cwd, agentType) {
     // 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)))) {
+    if (omitApplies) {
         return '';
     }
     // 4.5. Claude-runtime tier override (#4192 Finding 1). Sits AFTER the omit
@@ -554,10 +625,30 @@ function resolveModelInternal(cwd, agentType) {
     // `model_profile_overrides.claude.<tier>` entry for this tier — see
     // resolveClaudeTierOverrideModel for why the builtin map stays out.
     if (tier && tier !== 'inherit') {
-        const claudeOverrideModel = resolveClaudeTierOverrideModel(configRuntime, tier, config['model_profile_overrides']);
+        const claudeOverrideModel = resolveClaudeTierOverrideModel(activeRuntime, tier, config['model_profile_overrides']);
         if (claudeOverrideModel !== null)
             return claudeOverrideModel;
     }
+    // 4.75 dynamic_routing.tier_models (#4505 / #3024).
+    //
+    // Position is the documented composition, not a convenience:
+    //   docs/features/dynamic-routing-with-failure-tier-escalation.md —
+    //   "model_overrides always wins; dynamic_routing.tier_models[<tier>] resolves
+    //    above models.<phase_type> and model_profile."
+    // So it sits BELOW model_overrides (step 1), the model_policy preset (2.5),
+    // the runtime tier map (3), the resolve_model_ids:"omit" gate (4) and the
+    // claude tier override (4.5) — and ABOVE the profile lookup (5).
+    //
+    // An earlier cut of this fix routed every call site through resolveModelForTier
+    // instead, which returns the tier model directly and therefore skipped steps 3,
+    // 4 and 4.5 entirely: with `resolve_model_ids:"omit"` and a non-Claude runtime
+    // it handed out a model id where the gate had returned "". Putting the step
+    // here keeps every higher-precedence layer reachable.
+    if (tier !== 'inherit') {
+        const routed = dynamicRoutingModel(config, agentType, 0);
+        if (routed !== null)
+            return routed;
+    }
     // 5. Profile lookup (Claude-native default).
     if (!agentModels) {
         return profile === 'quality' ? 'opus'
@@ -614,6 +705,50 @@ function assertValidGranularityOverride(override, fail) {
         fail(`invalid granularity '${override}' (valid: ${[...VALID_GRANULARITIES].join(', ')})`);
     }
 }
+/**
+ * #4505 — the ONE implementation of `dynamic_routing.tier_models` lookup.
+ *
+ * Returns the configured model for this agent's routing tier at `attempt`, or
+ * null when dynamic routing does not apply (disabled, absent, no tier table, an
+ * agent with no default routing tier, or no entry for the tier). Both entry
+ * points call it, so the first-spawn value and the escalated value can never
+ * drift apart — the "Generative Fix Divergence" this repo names by name.
+ *
+ * `attempt` 0 means "no escalation yet", which is the documented FIRST-SPAWN
+ * case, NOT "skip dynamic routing":
+ *   docs/features/dynamic-routing-with-failure-tier-escalation.md —
+ *   "enabled: true — the resolver picks tier_models[default_tier] for the first
+ *    spawn and escalates one tier up on orchestrator-detected soft failure."
+ */
+function dynamicRoutingModel(config, agentType, attempt) {
+    const dr = config['dynamic_routing'];
+    if (!dr || typeof dr !== 'object' || dr['enabled'] !== true)
+        return null;
+    const tierModels = dr['tier_models'];
+    if (!tierModels || typeof tierModels !== 'object')
+        return null;
+    const defaultTier = (AGENT_DEFAULT_TIERS)[agentType];
+    if (!defaultTier || !(VALID_AGENT_TIERS).has(defaultTier))
+        return null;
+    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(attempt, maxEscalations) : 0;
+    let tier = defaultTier;
+    for (let i = 0; i < effectiveAttempt; i += 1) {
+        const next = (nextTier)(tier);
+        if (!next || next === tier)
+            break;
+        tier = next;
+    }
+    // Own-property guard: `tier_models` is a config-supplied plain object, so a
+    // prototype-chain key must not resolve an inherited member.
+    const alias = Object.hasOwn(tierModels, tier) ? tierModels[tier] : undefined;
+    if (typeof alias !== 'string' || alias.length === 0)
+        return null;
+    return alias;
+}
 /**
  * #3024 — Resolve a model for a specific dynamic-routing attempt.
  */
@@ -629,45 +764,19 @@ function resolveModelForTier(cwd, agentType, attempt) {
         ? modelOverrides[agentType]
         : undefined;
     if (override) {
-        const mapped = mapClaudeOverrideForRuntime(override, config['runtime'], agentType);
+        const mapped = mapClaudeOverrideForRuntime(override, resolveActiveRuntime(config), agentType);
         if (mapped !== null)
             return mapped;
         // Unmappable Claude ID — fall through to dynamic_routing / model_policy resolution.
     }
-    if (config['model_policy'] && config['runtime'] && config['runtime'] !== 'claude') {
+    // #4505: same active-runtime rule as resolveModelInternal step 3.
+    if (config['model_policy'] && resolveActiveRuntime(config) !== '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;
+    const alias = dynamicRoutingModel(config, agentType, attemptN);
+    if (alias !== null)
+        return alias;
+    return resolveModelInternal(cwd, agentType);
 }
 /**
  * Keep only usable model ids: non-empty strings. A malformed config can put

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

@@ -186,11 +186,16 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
             },
             'uat-passed': (_ctx) => {
                 let requireVerification = false;
+                let uatOnly = false;
                 const positional = [];
                 for (const token of args.slice(2)) {
                     if (token === '--require-verification') {
                         requireVerification = true;
                     }
+                    else if (token === '--uat-only') {
+                        // #4663: evaluate UAT rows only (verification-status blockers skipped).
+                        uatOnly = true;
+                    }
                     else if (token === '--raw') {
                         // --raw is handled by the outer CLI layer; accepted here silently
                     }
@@ -201,7 +206,10 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
                         positional.push(token);
                     }
                 }
-                phase.cmdPhaseUatPassed(cwd, positional[0], raw, { policy: { requireVerification } });
+                if (requireVerification && uatOnly) {
+                    return makeInvalidArgs('--uat-only', '--uat-only and --require-verification are mutually exclusive');
+                }
+                phase.cmdPhaseUatPassed(cwd, positional[0], raw, { policy: { requireVerification, uatOnly } });
                 return { ok: true, data: null };
             },
             // #1437 — list plan files for a phase

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

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Canonical bracket convention card (#3638 / ADR-612 PR-5).
+ *
+ * This module is the sole editable source of the compact grammar diagram.
+ * Render sites import phaseIdCard(); generated documentation is held to the
+ * same bytes by tests/phase-id-card.test.cjs. PR-6 can therefore inject the
+ * card broadly without inventing another copy.
+ */
+const PHASE_ID_CARD = [
+    '[GSD.02] 05.03-01',
+    ' │   │   │  │   │',
+    ' │   │   │  │   └── plan        01',
+    ' │   │   │  └────── subphase    03',
+    ' │   │   └───────── phase       05',
+    ' │   └───────────── milestone   02',
+    ' └───────────────── project     GSD',
+].join('\n');
+const PHASE_ID_LEGEND = "milestone = bracket integer; dots = phase-levels; one hyphen = plan; "
+    + "no 'Phase' word, no vX.Y";
+function phaseIdCard(options = {}) {
+    const parts = [];
+    if (options.title)
+        parts.push(options.title, '');
+    parts.push(PHASE_ID_CARD, '', PHASE_ID_LEGEND);
+    return parts.join('\n');
+}
+module.exports = {
+    phaseIdCard,
+    PHASE_ID_CARD,
+    PHASE_ID_LEGEND,
+};

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

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Phase-ID display adapters (#3638 / ADR-612 PR-5).
+ *
+ * STATE.md and milestone metadata still expose the legacy `vN.0` marker on
+ * this stacked base. Display surfaces need to translate that metadata into a
+ * bracket identity without growing another renderer. These pure adapters do
+ * only the boundary normalization, then delegate identity parsing/rendering to
+ * phase-id.cts's canonical pair.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseId = require("./phase-id.cjs");
+const { parsePhaseId, renderMilestoneId, renderPhaseId } = phaseId;
+function canonicalNumeric(value) {
+    let offset = 0;
+    while (offset < value.length - 1 && value[offset] === '0')
+        offset++;
+    const stripped = value.slice(offset);
+    return stripped.length < 2 ? stripped.padStart(2, '0') : stripped;
+}
+function isDigits(value) {
+    return value.length > 0
+        && [...value].every(char => char >= '0' && char <= '9');
+}
+function milestoneToken(value) {
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return null;
+    const raw = String(value).replace(/^v/i, '');
+    const parts = raw.split('.');
+    if (parts.length > 2 || parts.some(part => !isDigits(part)))
+        return null;
+    return canonicalNumeric(parts[0]);
+}
+function phaseToken(value) {
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return null;
+    const raw = String(value);
+    const parts = raw.split('.');
+    if (parts.length > 2 || parts.some(part => !isDigits(part)))
+        return null;
+    return parts.map(canonicalNumeric).join('.');
+}
+/**
+ * Render a bracket phase display from legacy milestone metadata.
+ * Returns null for incomplete or invalid metadata so cosmetic callers can
+ * degrade without breaking a command/statusline render.
+ */
+function renderBracketPhaseDisplay(milestone, phase, projectCode) {
+    const project = typeof projectCode === 'string' ? projectCode : '';
+    const mm = milestoneToken(milestone);
+    const pp = phaseToken(phase);
+    if (!project || mm === null || pp === null)
+        return null;
+    try {
+        return renderPhaseId(parsePhaseId(`${project}.${mm}-${pp}`));
+    }
+    catch {
+        return null;
+    }
+}
+/** Render only the bracket milestone label, still through canonical parsing. */
+function renderBracketMilestoneDisplay(milestone, projectCode) {
+    const project = typeof projectCode === 'string' ? projectCode : '';
+    const mm = milestoneToken(milestone);
+    if (!project || mm === null)
+        return null;
+    try {
+        // The sentinel phase is a validation vehicle, not a rendering artifact.
+        return renderMilestoneId(parsePhaseId(`${project}.${mm}-00`));
+    }
+    catch {
+        return null;
+    }
+}
+module.exports = {
+    renderBracketPhaseDisplay,
+    renderBracketMilestoneDisplay,
+};

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

@@ -59,6 +59,20 @@ 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+)*';
+// #4764: a phase REFERENCE in depends-on PROSE — the token in context, directly
+// following "Phase"/"Phases", with bare-token list continuation ("Phases 1 and 2",
+// "Phase 1, 2, and 3", "Phase 1-3"). Built HERE, beside the token grammar it is
+// anchored on, because two readers consume Depends-on prose (init.manager's
+// dep_phases and planning-inspect's dependencies) and re-deriving the anchored
+// form at each would drift exactly the way PHASE_NUMBER_TOKEN_SOURCE's own
+// anti-divergence rule exists to prevent. A bare digit run is the right shape
+// test for a phase id and the WRONG test for a reference: the whole-field
+// scrape this replaces pulled calendar dates ("2026-09-14" → 2026/09/14), git
+// shas ("8bf403100d" → 8b/403100d/…) and ledger ids (WINDOWS #1843) in as
+// dependencies. The `-` separator deliberately extracts range ENDPOINTS only
+// ("Phase 1-3" → 1, 3) — the pre-#4764 behavior; interior enumeration stays
+// out (a range's middle is not written as a reference).
+const PHASE_DEP_REF_SOURCE = `\\bphases?\\s+(${PHASE_NUMBER_TOKEN_SOURCE}(?:(?:\\s*,\\s*(?:and\\s+)?|\\s+and\\s+|\\s*&\\s*|\\s+(?:to|through)\\s+|\\s*-\\s*)${PHASE_NUMBER_TOKEN_SOURCE})*)`;
 // #2528 review: the CASE-FLEXIBLE renderings of the two sources above, for call
 // sites that scan directory names (where a project code or a variant suffix may
 // legitimately be lowercase) and therefore cannot use a case-sensitive class.
@@ -308,6 +322,30 @@ function phaseHeadingPrefixSrcFor(baseline, convention, capturing = false) {
     const bracketAlt = `\\[${id}\\][ \\t]*(?:Phase\\s+|(?=\\d))`;
     return `(?:${bracketAlt}|${base})`;
 }
+/**
+ * The single owner of the "scan a whole document for every phase heading"
+ * pattern (#4865 / ADR-4910 §8) — anchored (`^ {0,3}#{2,4}`, so indentation up
+ * to 3 spaces is tolerated but a heading is never matched mid-line), global,
+ * multiline, convention-aware via `phaseHeadingPrefixSrcFor`. Returns the
+ * capture-group layout alongside the regex so a caller never re-derives the
+ * bracket-convention offset (`const G = convention === 'bracket' ? 1 : 0`)
+ * itself — a second, independently-computed offset is exactly the kind of
+ * drift `scripts/lint-phase-id-drift.cjs` exists to catch structurally, not
+ * just by pattern text.
+ *
+ * Distinct from `buildPhaseHeadingRegex` (`src/roadmap.cts`), which searches
+ * for ONE already-known phase number (anchored `^`, no `g` flag, phase number
+ * interpolated literally) — a different contract for a different question.
+ * This function answers "which phases exist in this content", not "does this
+ * specific phase exist".
+ */
+function buildPhaseHeadingScanRegex(baseline, convention) {
+    const bracketGroup = convention === 'bracket' ? 1 : null;
+    const phaseNumGroup = bracketGroup ? 2 : 1;
+    const phaseNameGroup = phaseNumGroup + 1;
+    const regex = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(baseline, convention, true)}(${PHASE_NUMBER_TOKEN_SOURCE})${OPTIONAL_PHASE_TAG_SOURCE}:\\s*([^\\n]+)`, 'gim');
+    return { regex, bracketGroup, phaseNumGroup, phaseNameGroup };
+}
 function stripProjectCodePrefix(value, caseInsensitive = true) {
     const input = String(value);
     const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
@@ -451,10 +489,27 @@ function parsePhaseId(input) {
     // tokens unchanged.
     throw new Error(`parsePhaseId: not a bracket phase id: ${JSON.stringify(input)}`);
 }
+function renderMilestoneId(id) {
+    return `[${id.project}.${id.milestone}]`;
+}
 function renderPhaseId(id) {
     const sub = id.subphase ? `.${id.subphase}` : '';
     const plan = id.plan ? `-${id.plan}` : '';
-    return `[${id.project}.${id.milestone}] ${id.phase}${sub}${plan}`;
+    return `${renderMilestoneId(id)} ${id.phase}${sub}${plan}`;
+}
+/** Whether a legacy phase token has a lossless spelling in bracket display grammar. */
+function isBracketPhaseTokenRepresentable(token) {
+    try {
+        const bracketToken = normalizePhaseName(token)
+            .split('.')
+            .map((segment) => segment.padStart(2, '0'))
+            .join('.');
+        parsePhaseId(`[GSD.00] ${bracketToken}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 // PhaseId is a structural type: nothing forces a caller through parsePhaseId,
 // so toDir cannot trust project/milestone/phase/subphase are already
@@ -1017,7 +1072,7 @@ function isPhaseArtifact(fileName, phaseDirName, convention) {
  * whichever path produced the candidates, which is what makes a bracket dir
  * read exactly what its legacy twin reads.
  */
-function matchesPhaseTokenCandidates(fileName, rawCandidates) {
+function expandPhaseTokenCandidates(rawCandidates) {
     // Each reading is compared in BOTH its padded and de-padded form: files are
     // written padded by `normalizePhaseName` (`cmdScaffold`) while directories
     // are often not (`1-unpadded`), and legacy trees carry the reverse pairing.
@@ -1025,9 +1080,19 @@ function matchesPhaseTokenCandidates(fileName, rawCandidates) {
     // sub-phase (`03A`, `03.1`) has no meaningful de-padded form and is left
     // alone, so this only ever ADDS a reading and can never drop one.
     const depad = (t) => (/^\d+$/.test(t) ? String(Number(t)) : t);
-    const candidates = new Set(rawCandidates
+    return new Set(rawCandidates
         .flatMap(t => [t, normalizePhaseName(t), depad(t)])
         .map(t => t.toUpperCase()));
+}
+function matchesPhaseTokenCandidates(fileName, rawCandidates) {
+    const candidates = expandPhaseTokenCandidates(rawCandidates);
+    if (matchPhaseTokenCandidateSpan(fileName, candidates) !== null)
+        return true;
+    // FIX 2: token-less filename (bare "VERIFICATION.md"/"UAT.md") — containment
+    // in this phase's own directory listing is sufficient.
+    return derivePhaseTokenSegments(fileName).tokenSegments.length === 0;
+}
+function matchPhaseTokenCandidateSpan(fileName, candidates) {
     const fileUpper = fileName.toUpperCase();
     for (const candidate of candidates) {
         // A dotted sub-phase segment (e.g. `01.1-CONTEXT.md`) is a legitimate
@@ -1053,11 +1118,43 @@ function matchesPhaseTokenCandidates(fileName, rawCandidates) {
         if (fileUpper.startsWith(`${candidate}-`) ||
             fileUpper.startsWith(`${candidate}.`) ||
             fileUpper.startsWith(`${candidate}_`))
-            return true;
+            return { start: 0, end: candidate.length };
     }
-    // FIX 2: token-less filename (bare "VERIFICATION.md"/"UAT.md") — containment
-    // in this phase's own directory listing is sufficient.
-    return derivePhaseTokenSegments(fileName).tokenSegments.length === 0;
+    return null;
+}
+/**
+ * Return the exact leading token span by which the phase-artifact reader
+ * attributes a phase-qualified filename to `phaseDirName`.
+ *
+ * Membership is first decided by `isPhaseArtifact`, then the span is selected
+ * from the same padded, de-padded, case-folded candidate set used by
+ * `matchesPhaseTokenCandidates`. Token-less containment fallbacks return null
+ * because there is no phase token in the filename to replace.
+ */
+function phaseArtifactTokenSpan(fileName, phaseDirName, convention) {
+    if (!isPhaseArtifact(fileName, phaseDirName, convention))
+        return null;
+    if (convention === 'bracket') {
+        const bracketDir = phaseDirName.match(BRACKET_DIR_TOKEN_RE);
+        if (bracketDir) {
+            const qualified = fileName.match(BRACKET_QUALIFIED_KEY_RE);
+            if (qualified && bracketQualifiedKey(fileName, convention) !== null) {
+                return { start: 0, end: qualified[0].length };
+            }
+            const bracketCandidates = expandPhaseTokenCandidates([bracketDir[1]]);
+            return matchPhaseTokenCandidateSpan(fileName, bracketCandidates);
+        }
+    }
+    const { tokenSegments } = derivePhaseTokenSegments(phaseDirName);
+    if (tokenSegments.length === 0)
+        return null;
+    const literalToken = extractPhaseToken(phaseDirName);
+    const strippedDir = stripProjectCodePrefix(phaseDirName);
+    const strippedToken = strippedDir !== phaseDirName ? extractPhaseToken(strippedDir) : literalToken;
+    const leadingRunMatch = strippedDir.match(LEADING_DIGIT_RUN_RE);
+    const rawCandidates = [literalToken, strippedToken, leadingRunMatch?.[1]].filter((token) => Boolean(token));
+    const candidates = expandPhaseTokenCandidates(rawCandidates);
+    return matchPhaseTokenCandidateSpan(fileName, candidates);
 }
 /**
  * #3511: scope `fileNames` to the subset that passes
@@ -1538,6 +1635,7 @@ module.exports = {
     OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
     OPTIONAL_PHASE_TAG_SOURCE,
     PHASE_NUMBER_TOKEN_SOURCE,
+    PHASE_DEP_REF_SOURCE,
     CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE,
     CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE,
     PHASE_CONTINUATION_SEGMENT_SOURCE,
@@ -1554,6 +1652,7 @@ module.exports = {
     BASE_PHASE_LABEL_PREFIX_SRC,
     PHASE_HEADING_BASELINE,
     phaseHeadingPrefixSrcFor,
+    buildPhaseHeadingScanRegex,
     foldBracketId,
     bracketQualifiedKey,
     stripProjectCodePrefix,
@@ -1561,7 +1660,9 @@ module.exports = {
     getMilestoneFromPhaseId,
     getPhaseDirFromPhaseId,
     parsePhaseId,
+    renderMilestoneId,
     renderPhaseId,
+    isBracketPhaseTokenRepresentable,
     toDir,
     SENTINEL_RANGES,
     isSentinelPhaseId,
@@ -1571,6 +1672,7 @@ module.exports = {
     comparePhaseNum,
     extractPhaseToken,
     isPhaseArtifact,
+    phaseArtifactTokenSpan,
     scopeToPhase,
     phaseTokenMatches,
     matchPhaseDirs,