@opengsd/gsd-core 1.11.0 → 1.13.0

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

@@ -29,7 +29,7 @@ const roadmapParserMod = require("./roadmap-parser.cjs");
 const { getMilestoneInfo, extractCurrentMilestone } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { listMilestonePhaseDirs } = phaseLocatorMod;
+const { listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete } = verificationMod;
@@ -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`,
@@ -666,21 +738,25 @@ function buildPlanningRootFilesField(cwd) {
  * `phaseDirs` cannot). An absent `phases/` root is a real empty, not a
  * failure (mirrors `listMilestonePhaseDirs`'s own treatment); a present but
  * unreadable root degrades to `UNREADABLE` with an empty list.
+ *
+ * #3882 (ADR-3473 §8.3): delegates the actual disk scan to
+ * `listAllPhaseDirs(phasesDir, {includeSentinels: true})` — that function is
+ * the sole owner of "readdirSync the phases/ root, map to dir names, handle
+ * absent-vs-unreadable"; this field is one more consumer of that scan, not a
+ * second implementation of it. The two functions previously duplicated the
+ * same readdirSync + filter + map + absent/unreadable handling, which is
+ * exactly the defect class ADR-3473 §8.3 forbids.
+ *
+ * The RE-SORT below is deliberate, not leftover duplication:
+ * `listAllPhaseDirs` orders its `value` by `comparePhaseNum` (numeric phase
+ * order — its own documented contract), but `allPhaseDirNames`'s existing,
+ * externally-observable order is plain lexicographic `.sort()`, and W007's
+ * consumers depend on that order today. Re-sorting here preserves that
+ * contract without forking the underlying scan.
  */
 function buildAllPhaseDirNamesField(phasesDir) {
-    if (!node_fs_1.default.existsSync(phasesDir))
-        return { value: [], scope: SCOPE.COMPLETE };
-    try {
-        const value = node_fs_1.default
-            .readdirSync(phasesDir, { withFileTypes: true })
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort();
-        return { value, scope: SCOPE.COMPLETE };
-    }
-    catch {
-        return { value: [], scope: SCOPE.UNREADABLE };
-    }
+    const { value, scope } = listAllPhaseDirs(phasesDir, { includeSentinels: true });
+    return { value: value.slice().sort(), scope };
 }
 /**
  * Resolve `archivedPhaseTokens` — every phase-number token belonging to a
@@ -695,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 {
@@ -716,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 {
@@ -736,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;
@@ -749,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 };
 }
 /**
@@ -849,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),
@@ -871,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.
@@ -120,6 +123,142 @@ function planningDir(cwd, ws, project) {
 function planningRoot(cwd) {
     return node_path_1.default.join(cwd, '.planning');
 }
+/**
+ * #3972: the ONE owner of "is this planning scope opted out of worktrees?" —
+ * the effective `workflow.use_worktrees === false` read every
+ * isolation-deciding surface must share (config-get's merged view is the
+ * contract). Ladder: the scoped config's OWN key wins (planningDir is
+ * project- and workstream-aware); otherwise the flat root's key, but only
+ * under the GSD_WORKSTREAM env gate — config-get deliberately does NOT
+ * inherit root under GSD_PROJECT alone, and this read must not diverge
+ * (#3963). Strict `=== false` (never coerced); any read failure degrades to
+ * "not opted out" (worktrees on — the fail-safe direction: the guard keeps
+ * enforcing). Direct file reads only — never loadConfig, which normalizes
+ * and rewrites config on paths that back sentinel writes.
+ */
+function worktreesOptedOut(cwd) {
+    // #3972 review: the WHOLE body is guarded — planningDir/planningRoot
+    // themselves throw on a GSD_PROJECT/GSD_WORKSTREAM value containing path
+    // separators or `..`, and this contract ("any failure degrades to not
+    // opted out — worktrees on, keep enforcing") must hold for that shape too.
+    try {
+        return worktreesOptedOutUnguarded(cwd);
+    }
+    catch {
+        return false;
+    }
+}
+function worktreesOptedOutUnguarded(cwd) {
+    const readCfg = (p) => {
+        try {
+            return JSON.parse(String(node_fs_1.default.readFileSync(p, 'utf8')));
+        }
+        catch {
+            return null;
+        }
+    };
+    const ownKey = (cfg) => {
+        if (cfg === null || typeof cfg !== 'object')
+            return { present: false, value: undefined };
+        const wf = cfg.workflow;
+        if (wf === null || typeof wf !== 'object' || Array.isArray(wf))
+            return { present: false, value: undefined };
+        const wfRec = wf;
+        return Object.prototype.hasOwnProperty.call(wfRec, 'use_worktrees')
+            ? { present: true, value: wfRec['use_worktrees'] }
+            : { present: false, value: undefined };
+    };
+    const scoped = ownKey(readCfg(node_path_1.default.join(planningDir(cwd), 'config.json')));
+    if (scoped.present)
+        return scoped.value === false;
+    if (process.env['GSD_WORKSTREAM']) {
+        const root = ownKey(readCfg(node_path_1.default.join(planningRoot(cwd), 'config.json')));
+        if (root.present)
+            return root.value === false;
+    }
+    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
@@ -394,49 +533,41 @@ 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 = {
+    worktreesOptedOut,
     createPlanningWorkspace,
     createSharedPointerAdapter,
     createSessionScopedPointerAdapter,
     createMemoryPointerAdapter,
     planningDir,
     planningRoot,
+    resolvePhaseIdConvention,
     listAvailableWorkstreams,
     planningPaths,
     quickDirFrom,

package/gsd-core/bin/lib/probe-core.cjs

@@ -43,6 +43,9 @@ exports.projectTruths = projectTruths;
 exports.dispositionForUnverifiableTruth = dispositionForUnverifiableTruth;
 exports.runProbeCli = runProbeCli;
 const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError } = cliExitModule;
 /** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
 exports.VALID_STATUS = ['resolved', 'dismissed', 'unresolved'];
 function errMessage(e) {
@@ -497,7 +500,7 @@ function runProbeCli(analyze, options) {
     const readFile = options.readFile ?? ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
     const write = options.write ?? ((s) => { process.stdout.write(s); });
     const writeErr = options.writeErr ?? ((s) => { process.stderr.write(s); });
-    const exit = options.exit ?? ((code) => { process.exit(code); });
+    const exit = options.exit ?? ((code) => { throw new ExitError(code); });
     const reqPath = argv[2];
     const resPath = argv[3];
     if (!reqPath) {

package/gsd-core/bin/lib/profile-pipeline-command-router.cjs

@@ -13,12 +13,55 @@
  * Async note: cmdExtractMessages and cmdProfileSample are async functions.
  * dispatchCapabilityCommand (gsd-tools.cjs:366-371) explicitly errors if a
  * router returns a Promise. Therefore these router functions call the async
- * function WITHOUT await and WITHOUT returning the Promise. The async functions
- * end with output() or process.exit() so the process terminates correctly once
- * the event loop drains. Unhandled rejections are caught by the .catch() wrapper
- * to surface errors via the error() callback.
+ * function WITHOUT await and WITHOUT returning the Promise; the event loop
+ * drains once the returned promise settles. Since ADR-3889 (#3910), the
+ * pipeline functions terminate by THROWING ExitError (never process.exit()
+ * directly), so a rejection surfacing here can carry either a genuine error
+ * OR a declared ExitError termination — the `.catch()` below must
+ * distinguish them: an ExitError sets process.exitCode directly (mirroring
+ * cli-exit.cjs's own runMain, the only other place ExitError is caught),
+ * while any other rejection is surfaced via the `error()` callback exactly
+ * as before. Calling `error(exitErr.message)` for an ExitError would be
+ * wrong on two counts: it discards the real exit code (error() always
+ * terminates at 1) and it re-derives a message from ExitError's generic
+ * "process exit N" constructor default rather than the (already emitted, or
+ * intentionally absent) stderr output the throwing call site controls.
  */
-const { ERROR_REASON } = require('./io.cjs');
+const { ERROR_REASON, getJsonErrorMode } = require('./io.cjs');
+const { ExitError } = require('./cli-exit.cjs');
+
+/**
+ * Interpret a rejection from a fire-and-forget async pipeline call: an
+ * ExitError sets process.exitCode (and, for a non-zero code carrying a user
+ * message, writes it to stderr) exactly like runMain does; anything else
+ * reproduces io.cjs's error() stderr output byte-for-byte and sets
+ * process.exitCode directly instead of calling error() itself.
+ *
+ * error() (src/io.cts) is `never`-typed: it always throws ExitError(1) after
+ * writing to stderr. Calling it from inside this `.catch()` callback would
+ * throw from a detached promise chain that nothing awaits or re-catches —
+ * an unhandled promise rejection that Node (>=15, this repo's
+ * engines.node >= 24 default is --unhandled-rejections=throw) dumps as a
+ * raw stack trace on top of the clean line error() already wrote. Writing
+ * the same bytes directly and setting process.exitCode = 1 in place gets
+ * the identical observable stderr + exit code without ever throwing here.
+ */
+function _handlePipelineRejection(e, error) {
+  void error;
+  if (e instanceof ExitError) {
+    if (e.hasUserMessage && e.code !== 0) process.stderr.write(`${e.message}\n`);
+    process.exitCode = e.code;
+    return;
+  }
+  const message = e && e.message ? e.message : String(e);
+  if (getJsonErrorMode()) {
+    const payload = JSON.stringify({ ok: false, reason: ERROR_REASON.UNKNOWN, message }) + '\n';
+    process.stderr.write(payload);
+  } else {
+    process.stderr.write('Error: ' + message + '\n');
+  }
+  process.exitCode = 1;
+}
 
 // ─── Pipeline phase commands ───────────────────────────────────────────────────
 
@@ -51,7 +94,7 @@ function routeExtractMessages({ args, cwd, raw, error, _pipeline }) {
   // The function ends with output() or process.exit(); the event loop will drain.
   void cwd;
   p.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath)
-    .catch(e => { error(e && e.message ? e.message : String(e)); });
+    .catch(e => { _handlePipelineRejection(e, error); });
 }
 
 function routeProfileSample({ args, cwd, raw, error, _pipeline }) {
@@ -67,7 +110,7 @@ function routeProfileSample({ args, cwd, raw, error, _pipeline }) {
   const maxChars = maxCharsIdx !== -1 ? parseInt(args[maxCharsIdx + 1], 10) : 500;
   // cmdProfileSample is async — do NOT return the Promise.
   p.cmdProfileSample(sessionsPath, { limit, maxPerProject, maxChars }, raw)
-    .catch(e => { error(e && e.message ? e.message : String(e)); });
+    .catch(e => { _handlePipelineRejection(e, error); });
 }
 
 // ─── Output phase commands ─────────────────────────────────────────────────────