@opengsd/gsd-core 1.12.0 → 1.13.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-snapshot.cjs

@@ -37,7 +37,11 @@ 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.
+const { planningPaths, planningRoot, resolvePhaseIdConvention } = planningWorkspace;
 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 +68,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 ───────────────────
 /**
@@ -462,18 +474,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 +522,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 +546,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 +557,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 +573,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`,
@@ -699,7 +771,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 +792,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 +822,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 +835,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 +959,29 @@ 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;
     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`.
     const phaseDirs = listMilestonePhaseDirs(paths.phases, { cwd });
     const phasesValue = phaseDirs.value.map((dir) => buildPhaseSnapshot(paths.phases, dir));
     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 +999,20 @@ function buildPlanningSnapshot(cwd) {
         projectSections: buildProjectSectionsField(cwd),
         statePhaseTokens: stateFields.statePhaseTokens,
         stateStatus: stateFields.stateStatus,
-        roadmapDeclaredPhases: buildRoadmapDeclaredPhasesField(paths.roadmap),
-        roadmapPhaseCheckboxes: buildRoadmapPhaseCheckboxesField(paths.roadmap),
+        roadmapDeclaredPhases: roadmapDeclared.declared,
+        roadmapPhaseCheckboxes: buildRoadmapPhaseCheckboxesField(paths.roadmap, phaseIdConvention),
         researchValidationStatus: buildResearchValidationStatusField(paths.phases, phaseDirs.value, phaseDirs.scope),
         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),
     };
 }
 module.exports = {

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

@@ -21,6 +21,9 @@ const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const activeWorkstreamStore = require("./active-workstream-store.cjs");
 const { createSharedPointerAdapter, createSessionScopedPointerAdapter, createMemoryPointerAdapter, getActiveWorkstream: getStoredActiveWorkstream, peekActiveWorkstream: peekStoredActiveWorkstream, setActiveWorkstream: setStoredActiveWorkstream, clearActiveWorkstream: clearStoredActiveWorkstream, diagnoseUnresolvedActiveWorkstream: diagnoseUnresolvedStoredActiveWorkstream, } = activeWorkstreamStore;
 // Track .planning/.lock files held by this process so they can be removed on exit.
@@ -175,6 +178,87 @@ function worktreesOptedOutUnguarded(cwd) {
     }
     return false;
 }
+/**
+ * #612: resolve `phase_id_convention` with the SAME workstream->root federation
+ * config-loader uses (config-loader.cts:618/:649) — the workstream config wins,
+ * the root config is the fallback.
+ *
+ * Why this exists rather than `loadConfig(cwd)['phase_id_convention']`: as of
+ * #2997 (aa7697fe, in `next`), loadConfig surfaces `phase_id_convention` in
+ * its resolved `_baseConfig` — the "loadConfig drops keys it does not know"
+ * rationale this comment used to give is stale. The surviving reasons for the
+ * direct read are (1) the workstream->root federation below, a standalone
+ * resolution this function needs to run against a GIVEN cwd rather than
+ * whatever base a `loadConfig(cwd)` call elsewhere would federate from, and
+ * (2) convention-ENUM validation, which is still #612 PR-4 work — this
+ * function returns the raw string unvalidated, same as the now-surfaced
+ * resolved key would. #2997 surfacing the key makes consuming it from
+ * resolved config (instead of re-reading config.json here) a natural PR-4
+ * consolidation, not this PR's scope. Cycles were never the obstacle.
+ *
+ * Why federation matters here specifically: the phase-id readers were splitting
+ * on this value from two different bases — one resolving from the workstream
+ * directory, one from the root — so a workstream repo got the widened ROADMAP
+ * read with the narrow directory read, or the reverse, and reported every phase
+ * either missing from disk or malformed on disk. One resolver, one answer.
+ *
+ * The workstream is `planningDir`'s own `ws` parameter, forwarded, so this
+ * shares the canonical resolution (and its GSD_PROJECT/GSD_WORKSTREAM
+ * handling). Root is consulted as a fallback only when a workstream is active,
+ * matching config-loader; a project-scoped directory stands alone. Returns null
+ * when unset, absent, or unreadable — every caller treats null as "not the
+ * bracket convention".
+ *
+ * #2761 B1 (trek-e review): `ws` is a PARAMETER, not read from the environment
+ * here. It was omitted at first on the reasoning that "the active workstream is
+ * whatever planningDir resolves" — true only for the env-driven caller. A
+ * caller that iterates workstreams passes the name as an ARGUMENT (it cannot
+ * set `GSD_WORKSTREAM` per iteration), and `planningDir` falls back to the env
+ * only when `ws` is `undefined`, so an argument-driven call resolved this
+ * convention from the ROOT config while reading that workstream's ROADMAP. Two
+ * consequences, both reproduced: a workstream that explicitly declares its OWN
+ * convention had it ignored — the root's value decided how the workstream's
+ * roadmap was parsed, so flipping ONLY the root config changed which milestone
+ * a workstream extracted; and `--workstream foo` disagreed with
+ * `GSD_WORKSTREAM=foo` on the same repo.
+ *
+ * `undefined` (the default) keeps `planningDir`'s env fallback, so every
+ * pre-#2761 call site is byte-identical; `null` means "explicitly no
+ * workstream". Same discriminator `planningDir` and `getMilestonePhaseFilter`
+ * already carry.
+ *
+ * SCOPE: this governs the #612 bracket-selection reads ONLY. The shipped
+ * milestone-prefixed W021 gate keeps its own root-only read — re-basing a
+ * legacy convention's gate onto a different config is a behaviour change to a
+ * shipped check, in both directions, and is not part of read tolerance.
+ */
+function resolvePhaseIdConvention(cwd, ws) {
+    const readFrom = (dir) => {
+        const configPath = node_path_1.default.join(dir, 'config.json');
+        if (!node_fs_1.default.existsSync(configPath))
+            return null;
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+            const value = parsed['phase_id_convention'];
+            return typeof value === 'string' && value !== '' ? value : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const scoped = planningDir(cwd, ws);
+    const root = planningRoot(cwd);
+    if (scoped === root)
+        return readFrom(root);
+    // Root is a fallback only when a WORKSTREAM is active — config-loader falls
+    // back to the root config under `if (ws)` and not otherwise, so a
+    // project-scoped directory stands alone. Detected by suppressing the
+    // workstream segment rather than re-reading the environment.
+    const projectOnly = planningDir(cwd, null);
+    if (scoped === projectOnly)
+        return readFrom(scoped);
+    return readFrom(scoped) ?? readFrom(root);
+}
 // Sorted list of workstream directory names under `<root>/.planning/workstreams`,
 // or `[]` when the project is flat (no workstreams dir). Single source of truth
 // for the "workstream mode" detection shared by the #1912/#2028 fail-safe guards
@@ -449,40 +533,30 @@ function describeUnresolvedWorkstreamReason(reason) {
         return 'the name is not a valid workstream name';
     return "its workstream directory doesn't exist (it may have been renamed or removed)";
 }
-/**
- * Locate the CONTEXT.md file in a phase directory, handling both the bare
- * form (`CONTEXT.md`) and the padded-prefix convention (`NN-CONTEXT.md`,
- * `NN.N-CONTEXT.md`, etc.) used by gsd-discuss-phase output.
- *
- * Returns the filename (not the full path) of the first match, or null if
- * no CONTEXT.md exists in the directory.
- *
- * Canonical dual-form predicate extracted here to eliminate the 5-site
- * duplication that previously existed across init.cjs, roadmap.cjs,
- * core.cjs, gap-checker.cjs (#3739).
- *
- * @param absDirOrFiles - Absolute path to the phase directory,
- *   OR an already-read files array (avoids a redundant readdirSync at call sites
- *   that already hold a directory listing).
- */
 function findContextMdIn(absDirOrFiles) {
-    try {
-        const files = Array.isArray(absDirOrFiles)
-            ? absDirOrFiles
-            : node_fs_1.default.readdirSync(absDirOrFiles);
+    const matchIn = (files) => {
         if (files.includes('CONTEXT.md'))
             return 'CONTEXT.md';
         return files.find((f) => f.endsWith('-CONTEXT.md')) ?? null;
+    };
+    if (Array.isArray(absDirOrFiles)) {
+        return matchIn(absDirOrFiles);
+    }
+    try {
+        const files = node_fs_1.default.readdirSync(absDirOrFiles);
+        return { file: matchIn(files), files, scope: SCOPE.COMPLETE };
     }
     catch (err) {
-        // #1883: distinguish genuine absence from a permission/I-O failure. ENOENT
-        // ("nothing there") keeps the long-standing null contract the callers rely
-        // on; every other error (EACCES, EIO, …) is a real read failure that must
-        // propagate — otherwise an unreadable phase dir is silently reported as
-        // "no CONTEXT.md" and the discuss/plan gates wrongly skip context.
-        if (err.code === 'ENOENT')
-            return null;
-        throw err;
+        // #1883 / #4014: distinguish genuine absence from a permission/I-O
+        // failure. ENOENT ("nothing there") keeps the long-standing "real empty"
+        // contract callers rely on; every other error (EACCES, EIO, …) is a real
+        // read failure — reported as SCOPE.UNREADABLE rather than thrown, so a
+        // caller no longer needs its own try/catch to keep an unreadable phase
+        // dir from being silently reported the same as "no CONTEXT.md".
+        if (err.code === 'ENOENT') {
+            return { file: null, files: [], scope: SCOPE.COMPLETE };
+        }
+        return { file: null, files: [], scope: SCOPE.UNREADABLE };
     }
 }
 module.exports = {
@@ -493,6 +567,7 @@ module.exports = {
     createMemoryPointerAdapter,
     planningDir,
     planningRoot,
+    resolvePhaseIdConvention,
     listAvailableWorkstreams,
     planningPaths,
     quickDirFrom,