@opengsd/gsd-core 1.11.0 → 1.13.0

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

@@ -32,6 +32,9 @@ exports.analyzeCoverage = analyzeCoverage;
 exports.proposeElements = proposeElements;
 exports.autoResolve = autoResolve;
 const probe_core_cjs_1 = require("./probe-core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { runMain } = cliExitModule;
 /**
  * Word-boundary cues mapping element prose -> UI element kind.
  * Heuristic and intentionally lossy; an authored `elements` array overrides it. Every pattern is a
@@ -245,5 +248,10 @@ function autoResolve(items) {
  * so it runs only when the compiled `.cjs` is executed directly.
  */
 if (require.main === module) {
-    (0, probe_core_cjs_1.runProbeCli)((elements, resolutions) => analyzeCoverage(elements, resolutions), { usage: 'ui-consideration-probe.cjs <elements.json> [resolutions.json]' });
+    // runProbeCli's default `exit` now throws ExitError (src/probe-core.cts) rather
+    // than calling process.exit directly, so this entry point must run under
+    // runMain to translate that throw into process.exitCode.
+    runMain(() => {
+        (0, probe_core_cjs_1.runProbeCli)((elements, resolutions) => analyzeCoverage(elements, resolutions), { usage: 'ui-consideration-probe.cjs <elements.json> [resolutions.json]' });
+    });
 }

package/gsd-core/bin/lib/ui-safety-gate.cjs

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * UI Safety Gate — shell-free implementation (ADR-457 build-at-publish: the
- * hand-written bin/lib/ui-safety-gate.cjs collapsed to a TypeScript source of
+ * hand-written root copy of this file collapsed to a TypeScript source of
  * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
  * .cjs; only types are added.
  *
@@ -22,13 +22,17 @@
  *
  * CLI usage — reads phase-section text from STDIN to avoid ARG_MAX limits:
  *   echo "$PHASE_SECTION" | node gsd-core/bin/lib/ui-safety-gate.cjs
- *   echo $?   → 0 if UI tokens found, 1 if not, 2 on usage error
+ *   echo $?   → 0 if UI tokens found, 1 if not (real input, none found),
+ *              NO_INPUT (registry, src/cli-exit.cts) if stdin was empty or
+ *              whitespace-only, UNAVAILABLE (registry) if stdin read failed
+ *              (ADR-3889 Phase 3, #3907)
  *
- * Exit codes mirror grep: 0 = match found, 1 = no match, 2 = usage error.
  *
  * Canonical location: gsd-core/bin/lib/ui-safety-gate.cjs (#448)
  * This path is deployed by the GSD installer to $RUNTIME_DIR/gsd-core/bin/lib/.
- * bin/lib/ui-safety-gate.cjs (root) is retained for source-repo and npm usage.
+ * The former root-level copy of this file (outside gsd-core/) was removed in
+ * #3907 as dead code: no installer reference, no workflow invocation, and no
+ * fallback chain in shipped content ever pointed at it. Do not re-create it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UI_TOKENS = void 0;
@@ -111,19 +115,45 @@ function checkUiPresence(text) {
 // ── CLI entry point ─────────────────────────────────────────────────────────
 // Reads phase-section text from STDIN (not argv) to avoid OS ARG_MAX limits.
 // Invoked by workflow .md bash blocks as: echo "$PHASE_SECTION" | node .../ui-safety-gate.cjs
-// Exit 0 = UI found, 1 = no UI, 2 = startup error.
+//
+// Exit codes (ADR-3889 Phase 3, #3907): 0 = UI found, 1 = no UI (real input,
+// examined, nothing found), NO_INPUT (registry — see src/cli-exit.cts) = stdin
+// closed with zero bytes (or whitespace-only), UNAVAILABLE (registry) = stdin
+// read failed. The prior single "2 = startup error" arm conflated "I was
+// handed nothing" with "the phase says it has no UI" — those are different
+// answers; only the former is new here. `hint === 'no'` on REAL input still
+// exits 1 — that is the author's own declaration, not an empty-input
+// artifact.
+//
+// Terminates via terminateNow (src/cli-exit.cts), not raw process.exit: these
+// exits fire from inside a stdin event handler, which is exactly what
+// terminateNow (write-then-terminate) exists for, and it is total (cannot
+// throw or return). This module never emits --json, so every payload here is
+// `undefined` — terminateNow's JSON.stringify(undefined) is not a valid
+// Buffer source and is swallowed by its own emission-failure guard, so
+// nothing is written to stdout, preserving this CLI's historical contract of
+// silence.
 if (require.main === module) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const cliExit = require('./cli-exit.cjs');
     // Collect stdin chunks asynchronously.
     const chunks = [];
     process.stdin.setEncoding('utf-8');
     process.stdin.on('data', (chunk) => chunks.push(chunk));
     process.stdin.on('end', () => {
         const input = chunks.join('');
+        // Whitespace-only counts as empty (ADR-3889 §1's NO_INPUT: "zero units
+        // were in scope, and that emptiness is known to be genuine"). Real input
+        // — including a lone NUL byte, which .trim() does not strip — always
+        // falls through to the detector.
+        if (input.trim().length === 0) {
+            cliExit.terminateNow('NO_INPUT', undefined);
+        }
         const result = checkUiPresence(input);
-        process.exit(result.hasUI ? 0 : 1);
+        cliExit.terminateNow(result.hasUI ? 'PASS' : 'FAIL', undefined);
     });
     process.stdin.on('error', (err) => {
         process.stderr.write(`ERROR: ui-safety-gate.cjs stdin read failed: ${err.message}\n`);
-        process.exit(2);
+        cliExit.terminateNow('UNAVAILABLE', undefined);
     });
 }

package/gsd-core/bin/lib/unusable-input.cjs

@@ -79,6 +79,18 @@ const UNUSABLE_REASON = Object.freeze({
      * planning-snapshot's projectSections field)
      */
     PROJECT_UNREADABLE: 'project_unreadable',
+    /**
+     * A config.json parsed cleanly, but a section that a legacy-key migration needed to write
+     * into (`git`, `planning`) holds something that is not an object — a string, number, boolean
+     * or array. Distinct from the section being absent: absence is the ordinary path and the
+     * migration simply creates the section. Only a PRESENT non-object is corruption, and it is
+     * exactly the ADR-227 "shape, not just parseability" class one level down from the top-level
+     * document check `_readConfigFile` already performs. The migration is refused rather than
+     * applied — spreading the value would enumerate a string into character keys, and a number
+     * or boolean into nothing at all — so the section, the legacy key, and the file on disk are
+     * all left exactly as the user wrote them. (#3760, tenth #1879 site)
+     */
+    CONFIG_SECTION_NOT_OBJECT: 'config_section_not_object',
 });
 /** One human-readable clause per reason. Prose lives here, never in a test assertion. */
 const REASON_PROSE = Object.freeze({
@@ -88,6 +100,7 @@ const REASON_PROSE = Object.freeze({
     [UNUSABLE_REASON.STATE_UNREADABLE]: 'STATE.md exists but could not be read; the current-phase label fell back to unavailable',
     [UNUSABLE_REASON.CONFIG_UNREADABLE]: 'config.json exists but could not be read or parsed; the config field fell back to unavailable',
     [UNUSABLE_REASON.PROJECT_UNREADABLE]: 'PROJECT.md exists but could not be read; the projectSections field fell back to unavailable',
+    [UNUSABLE_REASON.CONFIG_SECTION_NOT_OBJECT]: 'a config section that a legacy-key migration targets holds a non-object value; the migration was SKIPPED and both the section and the legacy key were left unchanged — fix the section by hand, or the legacy key will never migrate',
 });
 // ─── Dedup state ──────────────────────────────────────────────────────────────
 /**

package/gsd-core/bin/lib/update-context.cjs

@@ -80,6 +80,10 @@ function inferPreferredRuntime({ fs, env, preferredConfigDir }) {
             return 'opencode';
         if (fs.exists(node_path_1.default.join(preferredConfigDir, exports.CODEX_CONFIG_MARKER)))
             return 'codex';
+        const resolved = node_path_1.default.resolve(preferredConfigDir);
+        const known = exports.RUNTIME_DIRS.find(([, reldir]) => resolved.endsWith(node_path_1.default.sep + reldir.split('/').join(node_path_1.default.sep)));
+        if (known)
+            return known[0];
     }
     if (env['CODEX_HOME'])
         return 'codex';
@@ -91,7 +95,7 @@ function inferPreferredRuntime({ fs, env, preferredConfigDir }) {
         return 'opencode';
     if (env['CLAUDE_CONFIG_DIR'])
         return 'claude';
-    return 'claude';
+    return '';
 }
 // Absolute env-override candidates, mirroring the bash ENV_RUNTIME_DIRS block.
 function envRuntimeDirs({ env, home }) {
@@ -196,7 +200,7 @@ function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = ''
     if (globalRuntime) {
         return { installedVersion: '0.0.0', scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir };
     }
-    return { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: 'claude', gsdDir: '' };
+    return { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: '', gsdDir: '' };
 }
 /**
  * CLI wiring: resolve against the real filesystem.

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

@@ -47,7 +47,7 @@ function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error
             // context: CJS-only — complex inline logic using classifyContextUtilization
             // with custom output formatting that has no direct SDK counterpart.
             context: () => {
-                const opts = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['tokens-used', 'context-window']);
+                const opts = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['tokens-used', 'context-window'], booleanFlags: ['json'], positionals: 2 }, error);
                 if (opts['tokens-used'] === null) {
                     error('--tokens-used <integer> is required for `validate context`');
                     return;
@@ -73,7 +73,7 @@ function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error
                     return;
                 }
                 const result = { ...classified, recommendation: RECOMMENDATIONS[classified.state] };
-                if (args.includes('--json')) {
+                if (opts['json'] === true) {
                     outputFn(result, raw);
                 }
                 else {

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

@@ -32,11 +32,14 @@
  *   - PR #156 (issue #6) — validate.ts generator that #26 extends
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MILESTONE_ARCHIVE_DIR_RE = exports.PHASE_TOKEN_FROM_DIR_RE = exports.phaseDirNameRe = void 0;
+exports.BRACKET_PHASE_DIR_RE = exports.MILESTONE_ARCHIVE_DIR_RE = exports.PHASE_TOKEN_FROM_DIR_RE = exports.phaseDirNameRe = void 0;
+exports.isPhaseDirName = isPhaseDirName;
+exports.phaseTokenFromDir = phaseTokenFromDir;
 exports.canonicalPlanStem = canonicalPlanStem;
 exports.phaseVariants = phaseVariants;
 exports.buildRoadmapPhaseVariants = buildRoadmapPhaseVariants;
 exports.buildNotStartedPhaseVariants = buildNotStartedPhaseVariants;
+exports.checkBracketCoherence = checkBracketCoherence;
 exports.textEncodingError = textEncodingError;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
@@ -45,7 +48,17 @@ const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
 // `replaceAll('A-Z', 'A-Za-z')` — that derivation silently no-ops (and narrows
 // this module to uppercase-only) the day phase-id.cts renders the class any
 // other way. See the constants' doc comment in phase-id.cts.
-CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE, CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE, PHASE_CONTINUATION_SEGMENT_SOURCE, } = phaseIdMod;
+CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE, CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE, PHASE_CONTINUATION_SEGMENT_SOURCE, BRACKET_DIR_PREFIX_SRC, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, extractPhaseToken, isSentinelPhaseId, 
+// #612 / #3309 re-homing: `checkBracketCoherence` (below) moved into this
+// module when #3309 migrated `cmdValidateHealth` onto the rule table and
+// deleted every local helper it used to sit beside in `verify.cts`. These
+// four are the grammar owners it consumes, imported unchanged — nothing about
+// the check is widened by the relocation.
+BRACKET_ID_SRC, PHASE_NUMBER_TOKEN_SOURCE, 
+// #2761 M3: canonical bracket milestone intro, re-homed here with
+// checkBracketCoherence when health diagnostics moved to the rule table.
+BRACKET_MILESTONE_INTRO_CAPTURING_SRC, foldBracketId, } = phaseIdMod;
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
 // Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
 // deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
@@ -72,6 +85,64 @@ exports.phaseDirNameRe = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}\\d{
 exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^(${CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE}` +
     `\\d+[A-Za-z]?(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?)*(?:\\.\\d+)*)(?:-|$)`);
 exports.MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
+// ── #612: bracket phase-directory recognition (convention-gated) ────────────
+// `{CODE}.{MM}-{PP}[.{SS}][-slug]`, built from the one bracket identity grammar.
+//
+// This lives BESIDE phaseDirNameRe / PHASE_TOKEN_FROM_DIR_RE rather than being
+// folded into them. The `{CODE}.{MM}-` prefix is string-indistinguishable from
+// the legacy letter-prefixed-decimal family this repo documents as "ambiguous
+// with a padded bracket dir", and folding a bracket branch in changes those
+// constants' answers on exactly that family: `P0.34-56-name` goes null -> "56",
+// and phaseDirNameRe goes false -> true, silencing a W005 that fires today. A
+// RegExp constant has nowhere to attach a convention gate, so the gate goes on
+// the functions and the constants stay byte-identical for every consumer.
+//
+// The numeric run mirrors the EMIT grammar rather than accepting any digit run:
+// CANONICAL_NUMERIC_RE (what toDir enforces) is digits-only with at most one
+// sub-phase, so `GSD.02-12A-hotfix` and `GSD.02-05.03.07-x` are not bracket
+// directories. Admitting them would make this recognizer disagree with
+// extractPhaseToken, which the milestone-complete check resolves through — and
+// then W006/W007 would resolve a directory that W021 simultaneously reported
+// unstarted, inside one `validate health` run.
+exports.BRACKET_PHASE_DIR_RE = new RegExp(`^(?:${BRACKET_DIR_PREFIX_SRC})\\d+(?:\\.\\d+)?(?:-[\\w-]+)?$`, 'i');
+// The constants these functions wrap are consumed as `e.name.match(RE)`, which
+// throws on a non-string. Coercing instead would invent a phase token out of a
+// number (`42` -> `"42"`), so the contract is preserved rather than softened.
+function assertDirName(value, fn) {
+    if (typeof value !== 'string') {
+        throw new TypeError(`${fn}: directory name must be a string, received ${typeof value}`);
+    }
+    return value;
+}
+/**
+ * True when `dirName` is a recognizable phase directory under `convention`.
+ * Under 'bracket' the `{CODE}.{MM}-{PP}` form is additionally accepted, so W005
+ * stops reporting every bracket phase directory as malformed. Every other
+ * convention value delegates to the unchanged `phaseDirNameRe`.
+ */
+function isPhaseDirName(dirName, convention) {
+    const name = assertDirName(dirName, 'isPhaseDirName');
+    if (convention === 'bracket' && exports.BRACKET_PHASE_DIR_RE.test(name))
+        return true;
+    return exports.phaseDirNameRe.test(name);
+}
+/**
+ * Extract a phase token from a directory name under `convention`, or null when
+ * the name is not a phase directory — the same contract as
+ * `PHASE_TOKEN_FROM_DIR_RE.exec()[1]`.
+ *
+ * Under 'bracket' the SHAPE is recognized here and the TOKEN is delegated to the
+ * canonical owner, so this and every other bracket directory reader resolve
+ * identically by construction rather than by two regexes agreeing today.
+ */
+function phaseTokenFromDir(dirName, convention) {
+    const name = assertDirName(dirName, 'phaseTokenFromDir');
+    if (convention === 'bracket' && exports.BRACKET_PHASE_DIR_RE.test(name)) {
+        return extractPhaseToken(name, 'bracket');
+    }
+    const legacy = name.match(exports.PHASE_TOKEN_FROM_DIR_RE);
+    return legacy ? legacy[1] : null;
+}
 // ── Issue #26: I001 canonicalization ────────────────────────────────────────
 function canonicalPlanStem(stem) {
     // #2043: the plan component (after the phase number) must be zero-padded,
@@ -116,35 +187,72 @@ function phaseVariants(phase) {
     variants.add(`${numericHead.padStart(2, '0')}${letterSuffix}${tail}`);
     return variants;
 }
-function buildRoadmapPhaseVariants(roadmapContent) {
+function buildRoadmapPhaseVariants(roadmapContent, convention) {
     const roadmapPhases = new Set();
     const roadmapPhaseVariants = new Set();
+    const sentinelOnly = new Set();
+    const realTokens = new Set();
     // Matches both legacy numeric (Phase 1:), decimal (Phase 2.1:), milestone-prefixed (Phase 2-01:),
     // and bracket-prefixed (### [GSD] Phase 2-01:) headings.
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-    const phasePattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/gi;
+    // #612: SELECTED by the resolved convention. This capture class is
+    // letter-tolerant, which makes it the site where an ungated widening does the
+    // most damage — `### [RFC.2119] 5:` enters roadmapPhases as a phantom and
+    // becomes a W007 "in ROADMAP.md but no directory on disk" on a repo that never
+    // opted in. A non-bracket repo compiles the base source unchanged.
+    const capturing = convention === 'bracket';
+    const g = capturing ? 1 : 0;
+    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, capturing)}([\\w][\\w.-]*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
     let m;
     while ((m = phasePattern.exec(roadmapContent)) !== null) {
-        roadmapPhases.add(m[1]);
-        for (const variant of phaseVariants(m[1]))
+        const token = m[1 + g];
+        const bracketId = g ? m[1] : undefined;
+        if (bracketId && isSentinelPhaseId(`${bracketId}-${token}`, 'bracket'))
+            sentinelOnly.add(token);
+        else
+            realTokens.add(token);
+        roadmapPhases.add(token);
+        for (const variant of phaseVariants(token))
             roadmapPhaseVariants.add(variant);
     }
     // Also matches checklist-style entries (checked or unchecked):
     //   - [x] **Phase 01: name**   - [X] **Phase 2-01: name**   - [ ] **Phase 3: name**
     // This is a supported ROADMAP format (parallel to buildNotStartedPhaseVariants).
-    const checklistPattern = /-\s*\[[ xX]\]\s*\*{0,2}Phase\s+([\w][\w.-]*)\s*:/gi;
+    // #612: CAPTURING, exactly as the sibling checklist scan in roadmap.cts does
+    // and for the same stated reason — "the bracket id rides along so the sentinel
+    // filter below is not blind to `- [ ] **[GSD.999] 01: Icebox**`". Left
+    // un-capturing here, this scan called every checklist token REAL, and the
+    // occurrence-aware un-suppression loop below then deleted the icebox token that
+    // the HEADING scan had correctly marked sentinel — so `validate consistency`
+    // warned that a bracket ICEBOX phase had no directory, in the house ROADMAP
+    // shape (bold bullet index + detail headings) where the icebox appears as both.
+    // `validate health` stayed silent on the same repo, so the two verbs disagreed
+    // — the disagreement `sentinelPhases` exists to close.
+    const checklistPattern = new RegExp(`-\\s*\\[[ xX]\\]\\s*\\*{0,2}${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, capturing)}([\\w][\\w.-]*)\\s*:`, 'gi');
     let cm;
     while ((cm = checklistPattern.exec(roadmapContent)) !== null) {
-        roadmapPhases.add(cm[1]);
-        for (const variant of phaseVariants(cm[1]))
+        const cBracketId = g ? cm[1] : undefined;
+        const cToken = cm[1 + g];
+        if (cBracketId && isSentinelPhaseId(`${cBracketId}-${cToken}`, 'bracket'))
+            sentinelOnly.add(cToken);
+        else
+            realTokens.add(cToken);
+        roadmapPhases.add(cToken);
+        for (const variant of phaseVariants(cToken))
             roadmapPhaseVariants.add(variant);
     }
-    return { roadmapPhases, roadmapPhaseVariants };
+    // A token borne by BOTH a sentinel and a real heading is not suppressed.
+    for (const t of realTokens)
+        sentinelOnly.delete(t);
+    return { roadmapPhases, roadmapPhaseVariants, sentinelPhases: sentinelOnly };
 }
-function buildNotStartedPhaseVariants(roadmapContent) {
+function buildNotStartedPhaseVariants(roadmapContent, convention) {
     const notStartedPhases = new Set();
     // Also matches milestone-prefixed and bracket-prefixed checklist items.
-    const uncheckedPattern = /-\s*\[\s\]\s*\*{0,2}Phase\s+([\w][\w.-]*)[:\s*]/gi;
+    // Trailing class is `[:\s*]` — a SPACE terminates the token here, not only a
+    // colon — so this site is the loosest of the three and the one where a
+    // retro-granted bracket tolerance would suppress a live W006.
+    const uncheckedPattern = new RegExp(`-\\s*\\[\\s\\]\\s*\\*{0,2}${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}([\\w][\\w.-]*)[:\\s*]`, 'gi');
     let um;
     while ((um = uncheckedPattern.exec(roadmapContent)) !== null) {
         for (const variant of phaseVariants(um[1]))
@@ -152,6 +260,116 @@ function buildNotStartedPhaseVariants(roadmapContent) {
     }
     return notStartedPhases;
 }
+/**
+ * Bracket-coherence check (#612). ADVISORY, and consumed ONLY under
+ * `phase_id_convention === 'bracket'`. Two sub-checks, both surfaced as W021:
+ *   (1) a phase whose in-bracket milestone differs from its enclosing section's;
+ *   (2) a phase heading not in bracket form under a repo that opted into bracket.
+ * Sentinel milestones are exempt — they have no real milestone to cohere with.
+ *
+ * Anchored to tokenizeHeadings(): the tokenizer strips fenced code blocks, so a
+ * bracket heading inside a ```markdown example cannot raise a warning, and it
+ * yields the heading LEVEL so section-vs-phase is structural rather than a
+ * hash-counting regex.
+ *
+ * SCOPE RULES, all three load-bearing:
+ *   - Only a genuine MILESTONE heading opens or closes a section. A `### Notes`
+ *     is not a section boundary; treating any non-phase heading as one meant a
+ *     single prose heading silently disabled both sub-checks for every phase
+ *     after it.
+ *   - A legacy `## v3.0` milestone heading CLOSES the bracket section, so a
+ *     phase under it is out of scope rather than compared against — and reported
+ *     against — a section it is not in.
+ *   - An M-NN or letter-suffixed phase heading (`### Phase 2-01:`, `### Phase 12A:`)
+ *     raises missing-bracket AND CONTINUES. Treating it as a section reset let a
+ *     single M-NN heading — the exact mid-migration content this epic targets —
+ *     silently disable the whole check.
+ *
+ * A bare `### 2026:` with no `Phase` label and no bracket is NOT a phase heading
+ * and raises nothing; the previous rule flagged year and version headings as
+ * phases needing migration.
+ *
+ * #3309 RE-HOMING NOTE: this function lived in `verify.cts` beside
+ * `checkMilestonePrefixMismatches`, its legacy-convention sibling, and was
+ * called inline from `cmdValidateHealth`'s W021 block. #3309 migrated
+ * `cmdValidateHealth` onto the rule table and relocated
+ * `checkMilestonePrefixMismatches`'s section walk into
+ * `planning-snapshot.cts`'s `roadmapDeclaredPhases` builder. This check follows
+ * its sibling: the body is byte-identical to the reviewed original, it moves
+ * into this pure no-I/O module (the owner of the other three ROADMAP-content
+ * scanners W006/W007 consume), `planning-snapshot.cts` calls it to produce the
+ * `roadmapBracketIncoherences` field, and `RULE_W021`
+ * (`health-diagnostic-rules/state-consistency.cts`) renders the messages. A
+ * `Rule.check(snapshot)` may not read raw `.planning/` text (ADR-3180 §8.1
+ * rule 2), so the read must happen in the snapshot layer either way.
+ */
+function checkBracketCoherence(roadmapContent) {
+    const incoherences = [];
+    // #3185: routed through the owner's predicate rather than reaching into its
+    // exported `SENTINEL_RANGES` array. `n` is an already-parsed, safe,
+    // non-negative milestone integer, so `String(n)` is a bare integer token and
+    // `isSentinelPhaseId`'s convention-less leading-int rule reduces to exactly
+    // `SENTINEL_RANGES.includes(n)` — same answer, one owner.
+    const isSentinel = (n) => isSentinelPhaseId(String(n));
+    const pad2 = (n) => (Number.isSafeInteger(n) ? String(n).padStart(2, '0') : 'unknown');
+    // A bracket PHASE heading: `### [CODE.MM] 05:` or `### [CODE.MM] Phase 5:`.
+    const bracketPhaseRe = new RegExp(`^\\[(${BRACKET_ID_SRC})\\][ \\t]*(?:Phase\\s+)?(${PHASE_NUMBER_TOKEN_SOURCE})\\s*:`, 'i');
+    // A NON-bracket phase heading — requires the literal `Phase` label, so a bare
+    // `2026:` year heading is not a phase. Token is the full phase-number grammar
+    // so M-NN and letter-suffixed ids are RECOGNIZED (and flagged), not skipped.
+    const legacyPhaseRe = new RegExp(`^Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE}|\\d+(?:-\\d+)+[A-Z]?(?:\\.\\d+)*)\\s*:`, 'i');
+    // A bracket MILESTONE section heading.
+    const bracketSectionRe = new RegExp(`^${BRACKET_MILESTONE_INTRO_CAPTURING_SRC}`, 'i');
+    // A legacy milestone section heading (`## v2.0 — Name`).
+    const legacyMilestoneRe = /^v\d+(?:\.\d+)*\b/i;
+    let sectionMilestone = null;
+    for (const heading of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(roadmapContent)) {
+        const text = heading.text.trim();
+        const bracketPhase = text.match(bracketPhaseRe);
+        const legacyPhase = bracketPhase ? null : text.match(legacyPhaseRe);
+        const isPhaseHeading = Boolean(bracketPhase || legacyPhase);
+        if (!isPhaseHeading && heading.level <= 3) {
+            const bracketSection = text.match(bracketSectionRe);
+            if (bracketSection) {
+                const mm = parseInt(bracketSection[1], 10);
+                sectionMilestone = Number.isSafeInteger(mm) ? mm : null;
+                continue;
+            }
+            // Only a MILESTONE heading closes the section. Any other heading (`### Notes`,
+            // `## Backlog`) leaves the scope exactly as it was.
+            if (legacyMilestoneRe.test(text.replace(/^\[[^\]]{0,200}\][ \t]*/, '')))
+                sectionMilestone = null;
+            continue;
+        }
+        if (!isPhaseHeading)
+            continue;
+        if (sectionMilestone === null || isSentinel(sectionMilestone))
+            continue;
+        if (bracketPhase) {
+            const folded = foldBracketId(bracketPhase[1]);
+            const dot = folded.lastIndexOf('.');
+            const phaseMilestone = parseInt(folded.slice(dot + 1), 10);
+            if (!Number.isSafeInteger(phaseMilestone) || isSentinel(phaseMilestone))
+                continue;
+            if (phaseMilestone !== sectionMilestone) {
+                incoherences.push({
+                    kind: 'mismatch',
+                    phaseId: bracketPhase[2],
+                    sectionMilestone: pad2(sectionMilestone),
+                    phaseMilestone: pad2(phaseMilestone),
+                });
+            }
+            continue;
+        }
+        incoherences.push({
+            kind: 'missing-bracket',
+            phaseId: legacyPhase[1],
+            sectionMilestone: pad2(sectionMilestone),
+            phaseMilestone: pad2(sectionMilestone),
+        });
+    }
+    return incoherences;
+}
 /**
  * Detect binary corruption (embedded NUL bytes) in a text artifact's bytes.
  *

package/gsd-core/bin/lib/vendor/README.md

@@ -21,17 +21,55 @@ in-tree instead of depending on it being installed as an npm package.
   `gsd-core/bin/lib/pattern.cjs`) for linear-time RE2 pattern compilation.
 - `re2js.d.cts` — verbatim copy of `node_modules/re2js/build/index.d.cts`,
   so TypeScript resolves types for the relative import from `src/pattern.cts`.
+- `js-yaml.cjs` — verbatim copy of `node_modules/js-yaml/dist/js-yaml.js`
+  (upstream package `js-yaml`, pinned version see `package.json`
+  `devDependencies.js-yaml`). ADR-3473 §8.1 (#3881): the single YAML parser
+  this repo standardizes on. The `dist` UMD bundle is the vendorable
+  artifact — js-yaml's `exports.require` entry (`index.js`) is *not*
+  self-contained; `dist/js-yaml.js` loads under `require()`, contains zero
+  `require()` calls of its own, and exposes `load`/`dump`/`FAILSAFE_SCHEMA`/
+  `YAMLException`.
+
+## Two kinds of type twin
+
+Each vendored package needs a `.d.cts` under `src/vendor/` so TypeScript can
+resolve types for a relative `./vendor/<pkg>.cjs` import from `src/**`
+(module resolution for a `.cts` source is relative to `src/`, not the
+compiled output dir). There are two kinds:
+
+- **upstream-verbatim** (`re2js.d.cts`) — a byte-for-byte copy of an
+  upstream `.d.cts`/`.d.ts` that ships with the package. Both the
+  `gsd-core/bin/lib/vendor/` copy and the `src/vendor/` copy are checked by
+  `scripts/lint-vendored-deps.cjs` against `node_modules` and against each
+  other.
+- **hand-authored** (`js-yaml.d.cts`) — js-yaml ships **no** type
+  declarations upstream and `@types/js-yaml` is not installed, so there is
+  nothing to copy verbatim. `src/vendor/js-yaml.d.cts` is written by hand,
+  declares only the symbols actually used (`load`, `dump`,
+  `FAILSAFE_SCHEMA`, `YAMLException`), and is **excluded** from
+  `lint-vendored-deps.cjs`'s byte-compare — there is no upstream file to
+  compare it against. The narrowness is deliberate: anchors, aliases,
+  custom types and `loadAll` are unreachable from typed code, which is a
+  compile-time enforcement of ADR-3473 §8.1's refusal to expand them.
 
 ## Do not hand-edit
 
-These files are **verbatim** copies of the upstream build output. Never
-edit them directly — refresh them from `node_modules` instead:
+These files are **verbatim** copies of upstream build output. Never edit
+them directly — refresh them from `node_modules` instead:
 
 ```
 cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs
 cp node_modules/re2js/build/index.d.cts gsd-core/bin/lib/vendor/re2js.d.cts
+cp node_modules/re2js/build/index.d.cts src/vendor/re2js.d.cts
+
+cp node_modules/js-yaml/dist/js-yaml.js gsd-core/bin/lib/vendor/js-yaml.cjs
+# js-yaml.d.cts has no upstream counterpart — update src/vendor/js-yaml.d.cts
+# by hand if the js-yaml API surface this repo depends on changes.
 ```
 
-`node scripts/lint-vendored-deps.cjs` fails CI if the vendored copy drifts
-byte-for-byte from `node_modules/re2js/build/` or from the `re2js` version
-pinned in `package.json` `devDependencies`.
+`node scripts/lint-vendored-deps.cjs` fails CI if any vendored copy drifts
+byte-for-byte from its `node_modules` upstream, from its own source-side
+type twin (upstream-verbatim twins only), or from the version pinned in
+`package.json` `devDependencies`. It is table-driven (`VENDORED` in that
+script) — adding a third vendored package means adding a row, not a second
+hardcoded check block (ADR-3473 §8.3, "one implementation per rule").