@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/bin/lib/plan-document.cjs

@@ -143,6 +143,7 @@ function parseXmlTasks(content) {
                 acceptanceCriteria: [],
                 done: null,
                 trackerId: null,
+                tdd: null,
             };
         }
         return {
@@ -154,6 +155,7 @@ function parseXmlTasks(content) {
             acceptanceCriteria: splitCriteria(elementBody(block, 'acceptance_criteria')),
             done: collapseWhitespace(elementBody(block, 'done')),
             trackerId: tagAttribute(openTag, 'tracker-id'),
+            tdd: tagAttribute(openTag, 'tdd'),
         };
     });
 }
@@ -172,6 +174,7 @@ function parseMarkdownTasks(content) {
         acceptanceCriteria: [],
         done: null,
         trackerId: null,
+        tdd: null,
     }));
 }
 // ─── Objective ────────────────────────────────────────────────────────────────
@@ -247,8 +250,15 @@ function parsePlanDocument(content, planPath = '') {
         const hintStr = String(fmAgentHint).trim();
         agentHint = hintStr !== '' ? hintStr : null;
     }
+    let planType = null;
+    const fmType = fm['type'];
+    if (fmType !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+        planType = String(fmType);
+    }
     return {
         objective: extractObjective(content) || fm['objective'] || null,
+        type: planType,
         declaredWave,
         dependsOn,
         autonomous,

package/gsd-core/bin/lib/planning-inspect.cjs

@@ -94,6 +94,9 @@ const { parseMarkdownTable, matchTableSchema } = markdownTable;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtilsMod = require("./core-utils.cjs");
 const { normalizeLineEndings } = coreUtilsMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const securityMod = require("./security.cjs");
+const { tryWithinRoot, PathAcceptance, isContainedIn } = securityMod;
 /**
  * The wire schema version. A consumer MUST reject any value other than this
  * one rather than best-effort-parsing an unknown shape.
@@ -184,32 +187,45 @@ function toPosix(value) {
  * directory like `.planning-evil/` that merely shares a string prefix. Pure
  * string comparison, no I/O — callers own their own `fs.realpathSync` call
  * (and its own not-found/broken-symlink handling).
+ *
+ * NOT an independent containment implementation — it is the comparison step
+ * of one, and that comparison now comes from `security.cts`'s exported
+ * `isContainedIn` rather than being redeclared here. `readDocument` below
+ * realpaths target and root itself (to keep its own exists-vs-escaped
+ * tri-state) and calls `isContainedIn` directly; `isPathContained` gets its
+ * containment DECISION from the canonical `tryWithinRoot` predicate instead
+ * (ADR-4650 decision 6) and never called this comparison directly. Every
+ * caller owns its own resolution.
  */
-function isWithinRoot(resolvedTarget, resolvedRoot) {
-    return resolvedTarget === resolvedRoot || resolvedTarget.startsWith(resolvedRoot + node_path_1.default.sep);
-}
 /**
- * Containment check for a path (file OR directory) that resolves its own
- * `fs.realpathSync`, then delegates the actual boundary comparison to
- * `isWithinRoot`. Used where the caller does not need to distinguish "target
- * vanished / broken symlink" from "target resolved but escapes root" — both
- * degrade the same way at every call site that uses this (an escaped or
- * unresolvable phase directory is treated identically to an unreadable one).
- * `readDocument` below needs that distinction for its own exists/readable
- * tri-state, so it keeps its own inline `realpathSync` calls and calls
- * `isWithinRoot` directly instead of this wrapper.
+ * Containment check for a path (file OR directory), used where the caller
+ * does not need to distinguish "target vanished / broken symlink" from
+ * "target resolved but escapes root" — both degrade the same way at every
+ * call site that uses this (an escaped or unresolvable phase directory is
+ * treated identically to an unreadable one). `readDocument` below needs
+ * that distinction for its own exists/readable tri-state, so it keeps its
+ * own inline `realpathSync` calls and calls `isContainedIn` directly instead
+ * of this wrapper.
+ *
+ * The containment DECISION comes from the canonical `tryWithinRoot`
+ * predicate (ADR-4650 decision 6: a wrapper may decide HOW to degrade,
+ * never WHETHER a path is contained). Must-exist stays this module's OWN
+ * degradation condition, applied after: `tryWithinRoot` deliberately accepts
+ * a not-yet-created path under the root (ancestor-walk realpath), but every
+ * caller of `isPathContained` guards an `fs` read that is about to happen
+ * against an already-existing directory, so a vanished/unresolvable path
+ * must still degrade the same as an escaped one.
  */
 function isPathContained(target, root) {
-    let realTarget;
-    let realRoot;
+    if (tryWithinRoot(target, root, PathAcceptance.AbsoluteInsideRoot) === null)
+        return false;
     try {
-        realTarget = node_fs_1.default.realpathSync(target);
-        realRoot = node_fs_1.default.realpathSync(root);
+        node_fs_1.default.realpathSync(target);
     }
     catch {
         return false;
     }
-    return isWithinRoot(realTarget, realRoot);
+    return true;
 }
 function readDocument(filePath, root) {
     let stat;
@@ -234,7 +250,7 @@ function readDocument(filePath, root) {
         // here — the same non-answer `readDocument` already gives "not exists".
         return { text: null, exists: false, readable: false };
     }
-    if (!isWithinRoot(realTarget, realRoot)) {
+    if (!isContainedIn(realTarget, realRoot)) {
         return { text: null, exists: true, readable: false };
     }
     try {

package/gsd-core/bin/lib/planning-snapshot.cjs

@@ -37,7 +37,19 @@ const { isPhaseComplete } = verificationMod;
 const scanPhasePlans = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningPaths, planningRoot } = planningWorkspace;
+// #612: `resolvePhaseIdConvention` is the federated (workstream -> root)
+// `phase_id_convention` reader, from the same §7 owner module `planningPaths`
+// comes from. Resolved once in `buildPlanningSnapshot` — see the
+// `phaseIdConvention` field's comment for why one resolution point matters.
+// #4257: `resolveEnvWorkstream` is that same module's ONE owner of the env
+// workstream discriminator `planningDir` applies — the name W002's scope
+// clause prints comes from the same resolution point that scoped the reads.
+const { planningPaths, planningRoot, resolvePhaseIdConvention, resolveEnvWorkstream } = planningWorkspace;
+// #4257: canonical CommonMark code strippers (markdown-sectionizer is the
+// repo's T0 structural seam, adopted per the #2365 composition order — fenced
+// blocks first, then inline spans) so the `statePhaseTokens` harvest sees
+// PROSE, not quoted literals.
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterMod = require("./frontmatter.cjs");
@@ -64,7 +76,15 @@ const configLoaderMod = require("./config-loader.cjs");
 const { isGitIgnored } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { PHASE_NUMBER_TOKEN_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, stripProjectCodePrefix, scopeToPhase } = phaseIdMod;
+// #612: `phaseHeadingPrefixSrcFor`/`PHASE_HEADING_BASELINE` SELECT a heading
+// intro by convention (a convention-less call compiles the byte-identical base
+// source the literal it replaced spelled); `isSentinelPhaseId` gets its bracket
+// reading only when handed the convention explicitly.
+const { PHASE_NUMBER_TOKEN_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, stripProjectCodePrefix, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, isSentinelPhaseId, scopeToPhase, } = phaseIdMod;
+// #612: `phaseTokenFromDir` is the convention-SELECTED counterpart of
+// `PHASE_TOKEN_FROM_DIR_RE` — handed no convention it delegates to that very
+// regex, so a legacy repo's tokenization is unchanged. `checkBracketCoherence`
+// re-homed into `validate.cts` when #3309 deleted its `verify.cts` neighbours.
 const validate_cjs_1 = require("./validate.cjs");
 // ─── worstScope — the one new piece of coordination logic ───────────────────
 /**
@@ -97,9 +117,12 @@ function worstScope(...scopes) {
  * uncorrelated (isPhaseComplete's readability check never re-derives or
  * requires scanPhasePlans, and vice versa).
  */
-function buildPhaseSnapshot(phasesDir, dir) {
+function buildPhaseSnapshot(phasesDir, dir, convention) {
     const fullPhaseDir = node_path_1.default.join(phasesDir, dir);
-    const completionResult = isPhaseComplete(fullPhaseDir);
+    // #612: the snapshot's single federated convention resolution rides into
+    // completion, so a bracket phase dir resolves and scopes its verification
+    // report exactly like its legacy twin.
+    const completionResult = isPhaseComplete(fullPhaseDir, { convention });
     const scanResult = scanPhasePlans(fullPhaseDir);
     return {
         dir,
@@ -148,9 +171,11 @@ function buildPhaseSnapshot(phasesDir, dir) {
  *   a whole-body fallback, together.
  * - `statePhaseTokens` scans the WHOLE document (`verify.cts`'s exact
  *   `PHASE_NUMBER_TOKEN_SOURCE` regex, relocated verbatim from
- *   `verify.cts:1731-1735`), not just the Current Position section, so it is
- *   NOT degraded to `TRUNCATED` by a missing section header — it stays
- *   `COMPLETE` whenever the file itself was read successfully.
+ *   `verify.cts:1731-1735`; #4257 adds the left word boundary and the
+ *   fenced-block/inline-span strip — see the harvest site's comment), not
+ *   just the Current Position section, so it is NOT degraded to `TRUNCATED`
+ *   by a missing section header — it stays `COMPLETE` whenever the file
+ *   itself was read successfully.
  */
 function buildStateFields(statePath) {
     let content;
@@ -210,7 +235,30 @@ function buildStateFields(statePath) {
         scope: currentPositionScope,
     });
     const statePhaseTokens = {
-        value: [...content.matchAll(new RegExp(`[Pp]hase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})`, 'g'))].map((m) => m[1]),
+        // #4257: harvest PROSE phase references, not every literal token match.
+        // Two precisions over the pre-#4257 verbatim relocation of verify.cts's
+        // scan (which was `[Pp]hase\s+(TOKEN)`, unanchored, over the raw file):
+        //
+        // 1. Strip fenced code blocks, then inline code spans (the #2365
+        //    composition order, via the canonical markdown-sectionizer seam) —
+        //    a token inside backticks is a QUOTED LITERAL (a ledger row quoting
+        //    `` `/gsd-execute-phase 5` `` or `` `- [ ] **Phase 40:` `` from a
+        //    sibling roadmap), not a reference. Pinned tradeoff: a GENUINE
+        //    reference written in backticks stops counting too — a quoted
+        //    literal and a reference are indistinguishable inside a code span.
+        // 2. Left word boundary `(?<![-\w])` — the `-phase 5` tail of GSD's own
+        //    command names (`/gsd-execute-phase 5`, bare or in prose) is a
+        //    command mention, not a reference, and word-suffixed carriers
+        //    (`myphase 5`) never were references. `Phase 5` at line start,
+        //    `**Phase 5:**`, `(Phase 5)`, `[Phase 5]`, and `### Phase 5:` all
+        //    still harvest — the char before `Phase` is not in `[-\w]`.
+        //
+        // Still scans the WHOLE document (frontmatter included — the `Phase: 3`
+        // field syntax never matched, `phase` is followed by a colon, not `\s`),
+        // still `COMPLETE` whenever the file itself was read successfully.
+        value: [
+            ...(0, markdown_sectionizer_cjs_1.stripInlineCode)((0, markdown_sectionizer_cjs_1.stripFencedCode)(content).text).matchAll(new RegExp(`(?<![-\\w])[Pp]hase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})`, 'g')),
+        ].map((m) => m[1]),
         scope: SCOPE.COMPLETE,
     };
     return { currentPhaseLabel, statePhaseTokens, stateStatus };
@@ -462,18 +510,31 @@ function buildProjectSectionsField(cwd) {
  * only the mismatches" to "record every attribution" — this field exposes
  * the parsed fact; the future W021/W026 rules make the mismatch judgment.
  */
-function buildRoadmapDeclaredPhasesField(roadmapPath) {
+function buildRoadmapDeclaredPhasesField(roadmapPath, convention) {
     if (!node_fs_1.default.existsSync(roadmapPath)) {
-        return { value: [], scope: SCOPE.UNREADABLE };
+        return {
+            declared: { value: [], scope: SCOPE.UNREADABLE },
+            sentinelTokens: { value: [], scope: SCOPE.UNREADABLE },
+        };
     }
     let content;
     try {
         content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
     }
     catch {
-        return { value: [], scope: SCOPE.UNREADABLE };
+        return {
+            declared: { value: [], scope: SCOPE.UNREADABLE },
+            sentinelTokens: { value: [], scope: SCOPE.UNREADABLE },
+        };
     }
-    const { roadmapPhases } = (0, validate_cjs_1.buildRoadmapPhaseVariants)(content);
+    // #612: the declared-phase scan is SELECTED by the resolved convention — a
+    // non-bracket repo compiles the byte-identical pattern sources this call
+    // compiled before, so its declared set is unchanged. `sentinelPhases` is the
+    // same call's third output (empty off the bracket convention) and is surfaced
+    // rather than filtered in place: `roadmapPhases` feeds both a membership check
+    // (W002's valid-phase set) and a missing-directory warning (W006), and only
+    // the latter should ignore an icebox item.
+    const { roadmapPhases, sentinelPhases } = (0, validate_cjs_1.buildRoadmapPhaseVariants)(content, convention);
     const milestoneByPhase = new Map();
     const sectionRx = /^#{1,3}\s+(?:\[[^\]]{1,200}\]\s*)?.*v(\d+\.\d+)/gim;
     const sections = [];
@@ -497,7 +558,10 @@ function buildRoadmapDeclaredPhasesField(roadmapPath) {
         phaseId,
         milestone: milestoneByPhase.get(phaseId) ?? null,
     }));
-    return { value, scope: SCOPE.COMPLETE };
+    return {
+        declared: { value, scope: SCOPE.COMPLETE },
+        sentinelTokens: { value: [...sentinelPhases], scope: SCOPE.COMPLETE },
+    };
 }
 /**
  * Resolve `roadmapPhaseCheckboxes` — parsed `[x]`/`[ ]` checkbox state per
@@ -518,7 +582,7 @@ function buildRoadmapDeclaredPhasesField(roadmapPath) {
  * diagnostic (W011) whose entire purpose is flagging when the two DISAGREE —
  * reading the data is not re-litigating who is authoritative.
  */
-function buildRoadmapPhaseCheckboxesField(roadmapPath) {
+function buildRoadmapPhaseCheckboxesField(roadmapPath, convention) {
     if (!node_fs_1.default.existsSync(roadmapPath)) {
         return { value: {}, scope: SCOPE.UNREADABLE };
     }
@@ -529,7 +593,15 @@ function buildRoadmapPhaseCheckboxesField(roadmapPath) {
     catch {
         return { value: {}, scope: SCOPE.UNREADABLE };
     }
-    const checkboxRe = new RegExp(`-\\s*\\[([xX ])\\].*?Phase\\s+0*(${PHASE_NUMBER_TOKEN_SOURCE})${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'gi');
+    // #612: the `Phase\s+` label intro is SELECTED, exactly as
+    // `buildNotStartedPhaseVariants` (`validate.cts`) selects it for the same
+    // ROADMAP checklist shape — this field is what W006's not-started exclusion
+    // now reads instead of that helper, so the two must recognize the same
+    // checklist lines or a bracket repo's `- [ ] **[GSD.02] 05: Name**` entries
+    // vanish from the exclusion set and every unstarted bracket phase gains a
+    // W006. NON-capturing (`capturing` defaults false), so the phase token stays
+    // group 2 and the legacy repo compiles a byte-identical source.
+    const checkboxRe = new RegExp(`-\\s*\\[([xX ])\\].*?${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}0*(${PHASE_NUMBER_TOKEN_SOURCE})${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'gi');
     const value = {};
     let m;
     while ((m = checkboxRe.exec(content)) !== null) {
@@ -537,6 +609,42 @@ function buildRoadmapPhaseCheckboxesField(roadmapPath) {
     }
     return { value, scope: SCOPE.COMPLETE };
 }
+/**
+ * Resolve `roadmapBracketIncoherences` — W021's bracket half (#612). Delegates
+ * wholly to `checkBracketCoherence` (`validate.cjs`), which is pure and owns
+ * both sub-checks; this builder only supplies the ROADMAP text and the
+ * convention gate.
+ *
+ * GATED, not merely filtered downstream: off the bracket convention the ROADMAP
+ * is never parsed for this at all and the field is a `COMPLETE`-scoped empty
+ * list. Inferring 'bracket' from the SHAPE of a matched heading would run a
+ * repo-failing check against a repo that never opted in — a legacy ROADMAP
+ * containing `### [RFC.2119] 5:` is legal legacy content, and that is the exact
+ * regression PR-2's round 1 killed the original ungated design over.
+ */
+function buildRoadmapBracketIncoherencesField(roadmapPath, convention) {
+    // File-readability is decided FIRST, so `scope` means the same thing on every
+    // repo: UNREADABLE iff ROADMAP.md could not be read, never "this convention
+    // was skipped." Ordering the convention gate first would have made an absent
+    // ROADMAP.md report COMPLETE on a legacy repo and UNREADABLE on a bracket one
+    // — the same "empty, nothing to say" state wearing two different scopes, which
+    // is precisely the non-answer/answer distinction ADR-3180 §8.1 gives `scope`
+    // to carry.
+    if (!node_fs_1.default.existsSync(roadmapPath))
+        return { value: [], scope: SCOPE.UNREADABLE };
+    // A non-bracket repo has no bracket incoherences BY DEFINITION — a real,
+    // COMPLETE answer, not a skipped read.
+    if (convention !== 'bracket')
+        return { value: [], scope: SCOPE.COMPLETE };
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    }
+    catch {
+        return { value: [], scope: SCOPE.UNREADABLE };
+    }
+    return { value: (0, validate_cjs_1.checkBracketCoherence)(content), scope: SCOPE.COMPLETE };
+}
 /**
  * Resolve `researchValidationStatus` — per phase directory, whether its
  * `*-RESEARCH.md` contains the literal heading `## Validation Architecture`,
@@ -560,7 +668,7 @@ function buildRoadmapPhaseCheckboxesField(roadmapPath) {
  * deliberate fail-open match to the pre-migration behavior, not a scope
  * degradation, since the original never surfaced these failures either.
  */
-function buildResearchValidationStatusField(phasesDir, phaseDirNames, enumerationScope) {
+function buildResearchValidationStatusField(phasesDir, phaseDirNames, enumerationScope, convention) {
     const value = phaseDirNames.map((dir) => {
         const fullPhaseDir = node_path_1.default.join(phasesDir, dir);
         let files;
@@ -574,7 +682,9 @@ function buildResearchValidationStatusField(phasesDir, phaseDirNames, enumeratio
         // phase-numbered-artifact predicates, so a stray cross-phase
         // -RESEARCH.md/-VALIDATION.md sitting in the wrong directory cannot flip
         // this phase's flags — mirrors core-utils.cts's getPhaseFileStats.
-        const scopedFiles = scopeToPhase(files, dir);
+        // #612: the snapshot's federated convention threaded, so a bracket dir
+        // scopes by its real token instead of the include-everything fail-safe.
+        const scopedFiles = scopeToPhase(files, dir, convention);
         const researchFile = scopedFiles.find((f) => f.endsWith('-RESEARCH.md'));
         const hasValidationMd = scopedFiles.some((f) => f.endsWith('-VALIDATION.md'));
         let hasValidationArchitecture = false;
@@ -699,7 +809,7 @@ function buildAllPhaseDirNamesField(phasesDir) {
  * present-but-unreadable per-archive-dir entry is silently skipped, mirroring
  * `forEachArchivedPhaseToken`'s own per-directory `catch { /* absent/unreadable *\/ }`.
  */
-function buildArchivedPhaseTokensField(planBase) {
+function buildArchivedPhaseTokensField(planBase, convention) {
     const milestonesDir = node_path_1.default.join(planBase, 'milestones');
     let archiveDirs;
     try {
@@ -720,9 +830,19 @@ function buildArchivedPhaseTokensField(planBase) {
             for (const e of entries) {
                 if (!e.isDirectory())
                     continue;
-                const m = e.name.match(validate_cjs_1.PHASE_TOKEN_FROM_DIR_RE);
-                if (m)
-                    value.push(stripProjectCodePrefix(m[1]));
+                // #612: composed, not chosen. The convention-aware extractor decides
+                // WHICH directory shapes are recognized (so an archived
+                // `{CODE}.{MM}-{PP}-slug` is seen at all — `PHASE_TOKEN_FROM_DIR_RE`
+                // rejects it outright, which is why every archived bracket phase used
+                // to still draw a W006/W002); `stripProjectCodePrefix` then normalizes
+                // the token it returns. The strip is a no-op on every bracket token
+                // (`01`, `01.02` — the `{CODE}.{MM}` prefix is not part of the token)
+                // and does the #2528 work on legacy ones (`MEM-05` -> `05`), so neither
+                // side loses its case. Handed no convention, `phaseTokenFromDir`
+                // delegates to `PHASE_TOKEN_FROM_DIR_RE` itself — legacy is unchanged.
+                const token = (0, validate_cjs_1.phaseTokenFromDir)(e.name, convention);
+                if (token)
+                    value.push(stripProjectCodePrefix(token));
             }
         }
         catch {
@@ -740,7 +860,7 @@ function buildArchivedPhaseTokensField(planBase) {
  * ROADMAP.md degrades to an empty list, mirroring every other
  * ROADMAP-sourced field's absent-file handling.
  */
-function buildCurrentMilestoneRoadmapPhaseIdsField(cwd, roadmapPath) {
+function buildCurrentMilestoneRoadmapPhaseIdsField(cwd, roadmapPath, convention) {
     if (!node_fs_1.default.existsSync(roadmapPath))
         return { value: [], scope: SCOPE.UNREADABLE };
     let content;
@@ -753,8 +873,32 @@ function buildCurrentMilestoneRoadmapPhaseIdsField(cwd, roadmapPath) {
     const scoped = extractCurrentMilestone(content, cwd);
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal
     // mirror of OPTIONAL_PHASE_TAG_SOURCE) — verbatim from `verify.cts:2366`.
-    const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
-    const value = [...scoped.matchAll(phasePattern)].map((m) => m[1]);
+    //
+    // #612: this scan is convention-AGNOSTIC in POSTURE — W026 is ungated, and
+    // bug-557 pins it with an empty config so it fires on every repo — but its
+    // heading grammar is still SELECTED, never widened. Under bracket the intro
+    // CAPTURES, so the phase token moves to group 2 and `bracketGroup` carries
+    // that offset; off bracket the source is byte-identical to the literal above
+    // and `bracketGroup` is 0. Inferring the convention from a matched bracket's
+    // shape would run a repo-failing check against a repo that never opted in.
+    const bracketGroup = convention === 'bracket' ? 1 : 0;
+    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, Boolean(bracketGroup))}(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
+    const value = [];
+    for (const m of scoped.matchAll(phasePattern)) {
+        const bracketId = bracketGroup ? m[1] : undefined;
+        const phaseNum = m[1 + bracketGroup];
+        // A bracket sentinel is an ICEBOX item, not an unstarted phase — it
+        // legitimately has no directory, so leaving it in this list makes W026
+        // ("STATE says milestone complete but ROADMAP lists an unstarted phase")
+        // fire on every bracket repo that keeps an icebox. Filtered here rather
+        // than in `RULE_W026` because the bracket id is only visible at the match:
+        // the emitted token is `07`, and sentinel-ness lives in the `[GSD.999]`
+        // milestone this scan just discarded. This field's only consumer is W026
+        // (see its own doc comment above).
+        if (bracketId && isSentinelPhaseId(`${bracketId}-${phaseNum}`, 'bracket'))
+            continue;
+        value.push(phaseNum);
+    }
     return { value, scope: SCOPE.COMPLETE };
 }
 /**
@@ -853,11 +997,39 @@ function buildPerPhasePlanScanFields(phasesDir, phaseDirNames, enumerationScope)
  */
 function buildPlanningSnapshot(cwd) {
     const paths = planningPaths(cwd);
+    // #612: ONE federated (workstream -> root) resolution for the whole snapshot.
+    // See the `phaseIdConvention` field's comment for why one resolution point is
+    // load-bearing rather than a micro-optimisation.
+    const phaseIdConvention = resolvePhaseIdConvention(cwd) ?? null;
+    // #4257: the workstream `planningPaths(cwd)` just scoped every read to
+    // (its `planningDir` call applies this exact discriminator when handed no
+    // `ws`), resolved through the same owner so W002's scope clause names the
+    // scope the valid set was ACTUALLY built from.
+    const workstream = resolveEnvWorkstream();
     const milestone = getMilestoneInfo(cwd);
+    // #612: deliberately LEFT to `listMilestonePhaseDirs`'s own lazy resolve —
+    // this call is byte-identical to upstream's.
+    //
+    // Passing `phaseIdConvention` here would NOT be a no-op, which is exactly why
+    // it is not passed. The lazy path resolves `resolvePhaseIdConvention(cwd, ws)`
+    // with this call's `ws`, which defaults to `null` — the PROJECT-only reading,
+    // with no root fallback. The field above is resolved with `ws` undefined,
+    // i.e. the FEDERATED workstream -> root reading. On a workstream repo whose
+    // root opts into bracket while the workstream config does not, the two answers
+    // genuinely differ, and substituting one for the other would silently re-scope
+    // `phaseDirs` — a change this PR does not need and no test covers. The
+    // federation guarantee PR-2 exists to deliver is delivered where it is
+    // observable: in the rules that read `snapshot.phaseIdConvention`. Per-phase
+    // completion and the research/validation scoping below deliberately use the
+    // FEDERATED `phaseIdConvention` (the same value `snapshot.phaseIdConvention`
+    // publishes), while `phaseDirs` keeps `listMilestonePhaseDirs`'s lazy
+    // PROJECT-only resolve — the divergence documented above is unchanged by
+    // this thread. No behavior change.
     const phaseDirs = listMilestonePhaseDirs(paths.phases, { cwd });
-    const phasesValue = phaseDirs.value.map((dir) => buildPhaseSnapshot(paths.phases, dir));
+    const phasesValue = phaseDirs.value.map((dir) => buildPhaseSnapshot(paths.phases, dir, phaseIdConvention));
     const stateFields = buildStateFields(paths.state);
     const allPhaseDirNames = buildAllPhaseDirNamesField(paths.phases);
+    const roadmapDeclared = buildRoadmapDeclaredPhasesField(paths.roadmap, phaseIdConvention);
     const perPhasePlanScanFields = buildPerPhasePlanScanFields(paths.phases, allPhaseDirNames.value, allPhaseDirNames.scope);
     return {
         cwd: node_path_1.default.resolve(cwd),
@@ -875,17 +1047,21 @@ function buildPlanningSnapshot(cwd) {
         projectSections: buildProjectSectionsField(cwd),
         statePhaseTokens: stateFields.statePhaseTokens,
         stateStatus: stateFields.stateStatus,
-        roadmapDeclaredPhases: buildRoadmapDeclaredPhasesField(paths.roadmap),
-        roadmapPhaseCheckboxes: buildRoadmapPhaseCheckboxesField(paths.roadmap),
-        researchValidationStatus: buildResearchValidationStatusField(paths.phases, phaseDirs.value, phaseDirs.scope),
+        roadmapDeclaredPhases: roadmapDeclared.declared,
+        roadmapPhaseCheckboxes: buildRoadmapPhaseCheckboxesField(paths.roadmap, phaseIdConvention),
+        researchValidationStatus: buildResearchValidationStatusField(paths.phases, phaseDirs.value, phaseDirs.scope, phaseIdConvention),
         milestoneArchiveStatus: buildMilestoneArchiveStatusField(cwd),
         planningRootFiles: buildPlanningRootFilesField(cwd),
         allPhaseDirNames,
-        archivedPhaseTokens: buildArchivedPhaseTokensField(paths.planning),
-        currentMilestoneRoadmapPhaseIds: buildCurrentMilestoneRoadmapPhaseIdsField(cwd, paths.roadmap),
+        archivedPhaseTokens: buildArchivedPhaseTokensField(paths.planning, phaseIdConvention),
+        currentMilestoneRoadmapPhaseIds: buildCurrentMilestoneRoadmapPhaseIdsField(cwd, paths.roadmap, phaseIdConvention),
         perPhasePlanNumbering: perPhasePlanScanFields.perPhasePlanNumbering,
         perPhaseOrphanSummaries: perPhasePlanScanFields.perPhaseOrphanSummaries,
         perPhaseWaveMissingPlans: perPhasePlanScanFields.perPhaseWaveMissingPlans,
+        phaseIdConvention,
+        roadmapSentinelPhaseTokens: roadmapDeclared.sentinelTokens,
+        roadmapBracketIncoherences: buildRoadmapBracketIncoherencesField(paths.roadmap, phaseIdConvention),
+        workstream,
     };
 }
 module.exports = {