@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/bin/lib/file-overlap-partitioner.cjs

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * File-overlap partitioner — shared greedy first-fit stage assignment (#3674).
+ *
+ * Extracted from `claude-orchestration.cts`'s `partitionStages` (#1143), which
+ * emits sequential Workflow `parallel()` stage barriers so that no two plans
+ * sharing a `files_modified` entry ever cohabit a stage. This module is the
+ * SAME algorithm, generalized: it depends on no `Plan`/`Wave` interface from
+ * `claude-orchestration.cts` (or any other caller-specific shape), so a future
+ * consumer (quick-batch, #3675 / ADR-1239 "Quick-batch binding") can partition
+ * its own planned-path items without pulling in orchestration internals.
+ *
+ * This is a pure, behavior-preserving extraction (#3674's acceptance bar is
+ * byte-identical output for `claude-orchestration.cts`'s existing callers —
+ * not an improvement). Explicitly OUT of scope, per the #3674 design lock:
+ *   - dependency-DAG ordering — this module only ever sees a flat item list
+ *     and file-overlap; a caller resolves dependency order before calling in
+ *     (same contract `partitionStages` already had);
+ *   - path normalization — file entries are compared by exact string equality
+ *     only. `Foo.ts` vs `foo.ts`, or `src/a.ts` vs `src\a.ts`, are treated as
+ *     DISTINCT files. This is deliberate, not a gap to "fix" during extraction;
+ *   - filesystem access — this module never reads a path off disk.
+ *
+ * Zero external dependencies. Pure function. Never throws on well-typed input.
+ */
+/**
+ * Partition `items` into a near-minimal number of sequential stages (via
+ * greedy first-fit — not guaranteed optimal for arbitrary overlap graphs, but
+ * correct: no two items sharing a file ever cohabit a stage) such that no two
+ * items in the same stage share a file. Each item goes into the earliest
+ * stage where it does not overlap any item already there, in input order.
+ *
+ * An item with an EMPTY `files` array declares no files; it overlaps nothing
+ * and coalesces into stage 0 (mirrors `partitionStages`' original behavior —
+ * this module cannot guard against undeclared concurrent writes; a caller
+ * must declare `files` accurately).
+ *
+ * File comparison is EXACT STRING EQUALITY — no path normalization, no
+ * case-folding, no separator canonicalization. Duplicate `id`s in the input
+ * are NOT deduplicated; each item is placed independently, in input order.
+ *
+ * Deterministic: identical input (including input order) always yields an
+ * identical partition.
+ */
+function partitionByFileOverlap(items) {
+    const stages = [];
+    for (const item of items) {
+        const fileSet = new Set(item.files);
+        let placed = false;
+        for (const stage of stages) {
+            let overlap = false;
+            for (const f of fileSet) {
+                if (stage.files.has(f)) {
+                    overlap = true;
+                    break;
+                }
+            }
+            if (!overlap) {
+                stage.items.push(item);
+                for (const f of fileSet)
+                    stage.files.add(f);
+                placed = true;
+                break;
+            }
+        }
+        if (!placed) {
+            stages.push({ items: [item], files: new Set(fileSet) });
+        }
+    }
+    return stages.map((s) => s.items.map((i) => i.id));
+}
+module.exports = {
+    partitionByFileOverlap,
+};

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

@@ -652,46 +652,137 @@ function countTopLevelKeyShapedLines(region) {
  *   key its deduplication. Optional because this function has 50-odd call sites and several
  *   hold only an in-memory string; those dedup on a content digest instead.
  */
-function extractFrontmatter(content, sourcePath) {
+/**
+ * The frontmatter REGION of a document: the text between the opening `---`
+ * fence at byte 0 and its closing fence.
+ *
+ * One fence parser, not two (#3850 review round 2, B1). `extractFrontmatter`
+ * and `frontmatterListEntries` need the identical answer to "where does the
+ * frontmatter start and stop" — same BOM tolerance (#2977), same byte-0-only
+ * fence rule, same CR handling before the closing fence — and differ only in
+ * what they do with the region text afterwards. A second copy of this logic is
+ * the `DEFECT.GENERATIVE-FIX` shape: it silently stops agreeing the first time
+ * either is taught something.
+ *
+ * `terminated: false` is the fence-opened-but-never-closed case. It is not an
+ * error here because the two callers disagree about it: `extractFrontmatter`
+ * runs the #1882 truncation probe over the region and may warn, while
+ * `frontmatterListEntries` has no array to return and gives up. So the shape
+ * is reported and the decision is left to them.
+ *
+ * `content` is returned alongside because it is the BOM-STRIPPED text, and a
+ * caller reporting on the document (the truncation diagnostic) must describe
+ * the same bytes the offsets were computed against.
+ */
+function frontmatterRegion(content) {
     // #2977: tolerate a single leading UTF-8 BOM (U+FEFF), which Windows tooling
-    // (PowerShell `>`/`Out-File` on PS 5.1, several editors) writes by default. Without this
-    // strip, the byte-0 `startsWith('---')` fence check below fails on the BOM and the whole
-    // parse collapses to {} — every frontmatter field silently disappears, and the engine
-    // proceeds as though the file had no frontmatter at all. The BOM is a single codepoint;
-    // stripping it here restores byte-0 alignment so the rest of the function is unchanged.
-    // Scope: BOM only. Arbitrary non-BOM content before the fence (leading whitespace/blank
-    // line/comment) is a separate product-intent decision (tolerate vs diagnose) left to a
-    // future change — this fix does not broaden the byte-0 fence rule beyond the BOM.
-    if (content.charCodeAt(0) === 0xFEFF) {
+    // (PowerShell `>`/`Out-File` on PS 5.1, several editors) writes by default.
+    // Without this strip, the byte-0 `startsWith('---')` fence check below fails
+    // on the BOM and the whole parse collapses — every frontmatter field silently
+    // disappears, and the engine proceeds as though the file had no frontmatter
+    // at all. The BOM is a single codepoint; stripping it here restores byte-0
+    // alignment. Scope: BOM only. Arbitrary non-BOM content before the fence
+    // (leading whitespace/blank line/comment) is a separate product-intent
+    // decision (tolerate vs diagnose) left to a future change.
+    if (content.charCodeAt(0) === 0xFEFF)
         content = content.slice(1);
-    }
-    // Match frontmatter only at byte 0 — a `---` block later in the document
-    // body (YAML examples, horizontal rules) must never be treated as frontmatter.
+    // Match frontmatter only at byte 0 — a `---` block later in the document body
+    // (YAML examples, horizontal rules) must never be treated as frontmatter.
     const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
     if (headerEnd === -1)
-        return {};
+        return null;
     const closingLineStart = content.indexOf('\n---', headerEnd);
     if (closingLineStart === -1) {
-        const region = content.slice(headerEnd);
-        const keyCount = countKeysBeforeTruncation(region);
-        if (keyCount >= UNTERMINATED_KEY_THRESHOLD && isFrontmatterShaped(region)) {
+        return { region: content.slice(headerEnd), terminated: false, content };
+    }
+    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
+    return { region: content.slice(headerEnd, yamlEnd), terminated: true, content };
+}
+function extractFrontmatter(content, sourcePath) {
+    // Fence location (BOM strip, byte-0 rule, CR handling) lives in
+    // `frontmatterRegion` so this and `frontmatterListEntries` cannot drift
+    // apart on where the frontmatter is.
+    const found = frontmatterRegion(content);
+    if (!found)
+        return {};
+    if (!found.terminated) {
+        const keyCount = countKeysBeforeTruncation(found.region);
+        if (keyCount >= UNTERMINATED_KEY_THRESHOLD && isFrontmatterShaped(found.region)) {
             warnUnusableInput({
                 reason: UNUSABLE_REASON.FRONTMATTER_UNTERMINATED,
                 source: sourcePath,
-                content,
+                content: found.content,
             });
         }
         return {};
     }
-    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
-    const region = content.slice(headerEnd, yamlEnd);
     try {
-        return parseGuardedYamlRegion(region);
+        return parseGuardedYamlRegion(found.region);
     }
     catch {
         return unparseableResult();
     }
 }
+/**
+ * The entries of a top-level frontmatter ARRAY key, VERBATIM — as the values
+ * YAML actually describes rather than the display-flattened strings
+ * `extractFrontmatter` returns (#3850).
+ *
+ * `extractFrontmatter` renders each object entry for HUMANS —
+ * `normalizeParsedValue` maps `{test, resolution}` to `"test: …, resolution: …"`
+ * via `flattenObjectListItem`. That is the right contract for a reader printing
+ * a list, and the wrong one for a reader that needs to branch on a specific
+ * field: `status`, `resolution` and `reason` are recoverable from that string
+ * only by re-parsing prose, which cannot distinguish a real `resolution:` field
+ * from the same text inside a quoted `truth:`.
+ *
+ * This returns the same entries BEFORE that display step, off the same
+ * `extractFrontmatter` parse path — same BOM strip (#2977), same byte-0 fence
+ * rule (shared via `frontmatterRegion`), same anchor/alias and sentinel guards,
+ * same ambiguous-colon repair. It is deliberately NOT a second parser: a
+ * hand-rolled fence regex or entry slicer re-loses whatever the real one
+ * learned, which is the `DEFECT.GENERATIVE-FIX` shape.
+ *
+ * EVERY element is returned, at its own index, whatever its type (#3850 review
+ * round 3, Blocker). An earlier revision filtered to objects, which compacted
+ * the array: a caller numbering entries by array position then numbered the
+ * SURVIVORS, so a list mixing object and non-object entries lost rows outright
+ * and mis-numbered the rest — the same silently-vanishing-row defect this whole
+ * issue exists to close, triggered by entry shape instead of file status.
+ * Deciding what a non-object entry MEANS is a caller's judgement (the two
+ * readers in `uat.cts` answer it differently and both are right for their own
+ * vocabulary); dropping it is nobody's.
+ *
+ * Returns `null` when the document has no frontmatter, the frontmatter is
+ * unterminated or unparseable, the key is absent, or the key is not an array —
+ * "nothing to iterate" cases the caller should not have to tell apart.
+ */
+function frontmatterListEntries(content, key) {
+    const found = frontmatterRegion(content);
+    if (!found || !found.terminated)
+        return null;
+    let raw;
+    try {
+        refuseAnchorsAndAliases(found.region);
+        refuseIfSentinelPresent(found.region);
+        raw = restoreNullBytesDeep(loadWithAmbiguousColonRepair(escapeNullBytesForParse(found.region)));
+    }
+    catch {
+        // Same posture as `extractFrontmatter`: an unparseable region is "no
+        // frontmatter", never a throw into a caller that was only reading a field.
+        return null;
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const value = raw[key];
+    // `Array.isArray` narrows an `unknown` to `any[]`, and returning that
+    // unchecked is how `any` escapes a guarded parser into every caller. The
+    // element type genuinely IS unknown here — that is the point of this
+    // function — so say so.
+    if (!Array.isArray(value))
+        return null;
+    return value;
+}
 /**
  * Escape a string for emission inside a YAML double-quoted scalar (#1779). ADR-3473 §8.1
  * (#3881): routed through the vendored js-yaml's `dump()` (forced double-quoted style) rather
@@ -816,6 +907,22 @@ function agentScalarNeedsDoubleQuoting(s) {
         return true;
     return false;
 }
+/**
+ * #4053 — Quote a numeric-looking scalar that is not all-digit (`22.10`,
+ * `1.0`, `1e3`, `0x1F`) so a spec YAML reader keeps it a string: bare `22.10`
+ * reloads as the float 22.1 and collides with `22.1`, a different phase.
+ *
+ * All-digit strings stay bare as a deliberate, scoped trade-off — not a
+ * safety guarantee. A leading-zero value (`02`, `017`) also mis-parses under
+ * a spec reader (to 2, 17). It is left unquoted because zero-padded ids
+ * (`plan: 01`, `phase: 02`) are the pervasive GSD convention, quoting them
+ * all is the blanket quoting #4053 asked to avoid, and the loss is padding
+ * rather than identity: `02` and `2` normalize to the same phase; `22.1` and
+ * `22.10` do not.
+ */
+function generalScalarNeedsNumericQuoting(s) {
+    return YAML_NUMERIC_RE.test(s) && !/^\d+$/.test(s);
+}
 function reconstructFrontmatter(obj) {
     const lines = [];
     // #3257: read the full-line-comment channel (set by parseGuardedYamlRegion when comments
@@ -899,13 +1006,13 @@ function reconstructFrontmatter(obj) {
                 else {
                     // eslint-disable-next-line @typescript-eslint/no-base-to-string
                     const sv = String(subval);
-                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') || scalarNeedsDoubleQuoting(sv) ? `"${escapeDoubleQuotedScalar(sv)}"` : sv}`);
+                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') || scalarNeedsDoubleQuoting(sv) || generalScalarNeedsNumericQuoting(sv) ? `"${escapeDoubleQuotedScalar(sv)}"` : sv}`);
                 }
             }
         }
         else {
             const sv = String(value);
-            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{') || scalarNeedsDoubleQuoting(sv)) {
+            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{') || scalarNeedsDoubleQuoting(sv) || generalScalarNeedsNumericQuoting(sv)) {
                 lines.push(`${key}: "${escapeDoubleQuotedScalar(sv)}"`);
             }
             else {
@@ -1529,6 +1636,13 @@ module.exports = {
     stripFrontmatter,
     noOpObjectListSetError,
     parseMustHavesBlock,
+    // #3850: an array key's entries as parsed OBJECTS, for a caller that must
+    // branch on an entry's `status:`/`resolution:` rather than print it. Off the
+    // same parse path as `extractFrontmatter`, minus only the display flattening.
+    frontmatterListEntries,
+    // #3850: the display rendering itself, so a caller deriving a name from those
+    // objects produces the byte-identical string `extractFrontmatter` would have.
+    flattenObjectListItem,
     FRONTMATTER_SCHEMAS,
     cmdFrontmatterGet,
     cmdFrontmatterSet,

package/gsd-core/bin/lib/gap-checker.cjs

@@ -36,6 +36,9 @@ const { scanPhasePlans } = planScanMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
 const { scopeToPhase } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 /**
  * Parse REQ-IDs from REQUIREMENTS.md content.
  *
@@ -303,6 +306,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: null,
+            phase_dir_scope: SCOPE.COMPLETE,
         };
     }
     const absPhaseDir = node_path_1.default.isAbsolute(phaseDir) ? phaseDir : node_path_1.default.join(cwd, phaseDir);
@@ -325,19 +329,20 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     }
     // Read the phase directory once; reuse the listing for both context detection
     // and plan-file enumeration (avoids redundant readdirSync calls).
-    let phaseDirFiles = [];
-    // #3885 (ADR-3473 §8.5): the existsSync guard above already means a catch
-    // here is NEVER "genuinely absent" (ENOENT) — this directory exists, so any
-    // failure to list it is a real read error (EACCES/EIO/...) and must be
-    // named, not folded into the same `[]` an absent directory produces.
-    let phaseDirReadError = null;
-    try {
-        if (node_fs_1.default.existsSync(absPhaseDir))
-            phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
-    }
-    catch (err) {
-        phaseDirReadError = `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}: ${formatDiagnosticToken(err?.message ?? String(err))}`;
-    }
+    //
+    // #4014 (epic #3473 B4): findContextMdIn's directory-string form now owns
+    // the listing + ENOENT-vs-other discrimination, retiring the local
+    // existsSync-guarded readdirSync try/catch — ENOENT (genuinely absent)
+    // and a successful-but-empty read both resolve to SCOPE.COMPLETE with an
+    // empty listing, exactly like the existsSync guard's short-circuit did.
+    const { files: phaseDirFiles, scope: phaseDirScope } = findContextMdIn(absPhaseDir);
+    // #3885 (ADR-3473 §8.5): `phaseDirReadError` stays additive for the
+    // shipped `phase_dir_read_error` JSON field — derived from `phaseDirScope`
+    // rather than from its own caught error, since findContextMdIn's
+    // directory-string form reports SCOPE, not the raw errno message.
+    const phaseDirReadError = phaseDirScope === SCOPE.UNREADABLE
+        ? `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}`
+        : null;
     // #3511-class: scope the raw listing to this phase dir before the
     // phase-numbered -CONTEXT.md predicate. `phaseDirFiles` itself stays raw —
     // it is also reused below only as a `.length > 0` guard ahead of
@@ -405,6 +410,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
                 summary: coverageSummary + '; extracted 0 of N — possible format mismatch',
                 counts: { total: rows.length, covered, uncovered },
                 phase_dir_read_error: phaseDirReadError,
+                phase_dir_scope: phaseDirScope,
             };
         }
         return {
@@ -414,6 +420,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             summary: 'extracted 0 of N — possible format mismatch',
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: phaseDirReadError,
+            phase_dir_scope: phaseDirScope,
         };
     }
     // #1365: if no items at all, surface a clean no-check message.
@@ -431,6 +438,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             summary: 'no requirements or decisions to check',
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: phaseDirReadError,
+            phase_dir_scope: phaseDirScope,
         };
     }
     const rows = sortRows([
@@ -449,6 +457,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
         summary,
         counts: { total: rows.length, covered, uncovered },
         phase_dir_read_error: phaseDirReadError,
+        phase_dir_scope: phaseDirScope,
     };
 }
 function cmdGapAnalysis(cwd, args, raw) {

package/gsd-core/bin/lib/git-base-branch.cjs

@@ -122,6 +122,7 @@ function readEffectiveGitConfig(cwd, deps) {
                     config = {
                         base_branch: _readGitKey(normalized, 'base_branch'),
                         protected_branches: _readGitNested(normalized, 'protected_branches'),
+                        allow_default_branch_commits: _readGitNested(normalized, 'allow_default_branch_commits'),
                     };
                 }
             }
@@ -161,7 +162,10 @@ function readEffectiveGitConfig(cwd, deps) {
         // Not a list at all — contributes no names, but is still a misconfiguration.
         rejectedProtectedBranches.push(renderRejected(rawProtectedBranches));
     }
-    return { baseBranch, protectedBranches, rejectedProtectedBranches };
+    // #3819: nested-only read (mirrors protected_branches — new key, no legacy
+    // flat form, so a top-level spelling must not become an undocumented alias).
+    const allowDefaultBranchCommits = config.allow_default_branch_commits === true;
+    return { baseBranch, protectedBranches, rejectedProtectedBranches, allowDefaultBranchCommits };
 }
 /**
  * Try `git symbolic-ref --short refs/remotes/origin/HEAD` (no network).
@@ -302,13 +306,17 @@ function resolveBaseBranch(cwd, deps) {
 function resolveProtectedBranchStatus(cwd, currentBranch, deps) {
     const effectiveConfig = readEffectiveGitConfig(cwd, deps);
     const { branch: baseBranch, verified } = resolveBaseBranchDiagnosticsWithConfig(cwd, effectiveConfig.baseBranch, deps);
-    const protectedBranches = [...new Set([baseBranch, ...effectiveConfig.protectedBranches])];
+    const protectedBranches = [...new Set([
+            ...(effectiveConfig.allowDefaultBranchCommits ? [] : [baseBranch]),
+            ...effectiveConfig.protectedBranches,
+        ])];
     return {
         baseBranch,
         protectedBranches,
         rejectedProtectedBranches: effectiveConfig.rejectedProtectedBranches,
         isProtected: protectedBranches.includes(currentBranch),
         verified,
+        allowDefaultBranchCommits: effectiveConfig.allowDefaultBranchCommits,
     };
 }
 /**

package/gsd-core/bin/lib/gsd2-import.cjs

@@ -307,8 +307,7 @@ function buildStateMd(phaseMap) {
     const currentPhaseNum = currentEntry ? zeroPad(currentEntry.phaseNum) : zeroPad(totalPhases);
     const currentSlug = currentEntry ? slugify(currentEntry.slice.title) : 'complete';
     const status = currentEntry ? 'Ready to plan' : 'All phases complete';
-    const filled = Math.round(pct / 10);
-    const bar = `[${'█'.repeat(filled)}${'░'.repeat(10 - filled)}]`;
+    const bar = `[${(0, phase_lifecycle_cjs_1.renderProgressBar)(pct, 10)}]`;
     const today = clock_cjs_1.realClock.localToday();
     return [
         '# Project State',

package/gsd-core/bin/lib/health-diagnostic-rules/phase-structure.cjs

@@ -56,7 +56,13 @@ const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
 const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const validateMod = require("../validate.cjs");
-const { phaseDirNameRe } = validateMod;
+// #612: `isPhaseDirName` is the convention-SELECTED shape test wrapping
+// `phaseDirNameRe`. Handed no convention it delegates to that very regex, so a
+// legacy repo's W005 reading is byte-identical; handed 'bracket' it also
+// recognizes `{CODE}.{MM}-{PP}-slug`, which `phaseDirNameRe` rejects outright —
+// left un-threaded, W005 fires on EVERY phase directory of a repo that opted
+// into the convention, i.e. the check inverts on exactly the repos PR-2 widens.
+const { isPhaseDirName } = validateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
 const { extractPhaseToken, normalizePhaseName, comparePhaseNum } = phaseIdMod;
@@ -64,7 +70,7 @@ const { extractPhaseToken, normalizePhaseName, comparePhaseNum } = phaseIdMod;
 function checkW005(snapshot) {
     const diagnostics = [];
     for (const name of snapshot.phaseDirs.value) {
-        if (!name.match(phaseDirNameRe)) {
+        if (!isPhaseDirName(name, snapshot.phaseIdConvention)) {
             diagnostics.push({
                 code: 'W005',
                 severity: SEVERITY.WARNING,

package/gsd-core/bin/lib/health-diagnostic-rules/roadmap-disk-consistency.cjs

@@ -116,8 +116,16 @@ const { phaseVariants } = validateMod;
  * does the roadmap claim, for W007) call this — one matcher, reused, per the
  * file-level comment.
  */
-function dirsForPhase(dirs, phaseId) {
-    const canonical = matchPhaseDirs(dirs, normalizePhaseName(phaseId)).matches;
+function dirsForPhase(dirs, phaseId, convention) {
+    // #612: `convention` reaches BOTH operands of this pairing or it pairs
+    // nothing. The phases come from a bracket-aware heading scan and the dirs
+    // from a bracket-aware disk scan, so a convention-less selector here leaves
+    // W006's existence check and W007's `claimedDirs` empty on exactly the repos
+    // both scans just widened — every bracket phase reads as "no directory on
+    // disk" AND every bracket directory reads as unclaimed. `matchPhaseDirs`
+    // forwards it to its primary `phaseTokenMatches`; handed nothing it is
+    // byte-identical, so no legacy repo's pairing changes.
+    const canonical = matchPhaseDirs(dirs, normalizePhaseName(phaseId), convention).matches;
     if (canonical.length > 0)
         return canonical;
     // Bug 2 (#3309 W006/W007 migration cluster, found while fixing the
@@ -139,7 +147,12 @@ function dirsForPhase(dirs, phaseId) {
     // alone misses without re-deriving a second matcher.
     const variants = phaseVariants(phaseId);
     return dirs.filter((d) => {
-        const token = extractPhaseToken(d).toUpperCase();
+        // #612: the same convention the primary matcher above got. This fallback
+        // compares a DIRECTORY-derived token against phase-id variants, so left
+        // convention-less it reads `GSD.02-05-slug` with the legacy grammar and can
+        // never agree with a bracket phase id — the fallback would then be dead on
+        // precisely the convention it is reached for.
+        const token = extractPhaseToken(d, convention).toUpperCase();
         for (const variant of variants) {
             if (token === variant.toUpperCase())
                 return true;
@@ -173,15 +186,40 @@ function checkW006(snapshot) {
     if (snapshot.roadmapDeclaredPhases.scope !== SCOPE.COMPLETE)
         return [];
     const dirs = snapshot.allPhaseDirNames.value;
+    const convention = snapshot.phaseIdConvention;
     const archivedTokens = new Set(snapshot.archivedPhaseTokens.value);
+    // No separate scope guard: `roadmapSentinelPhaseTokens` and
+    // `roadmapDeclaredPhases` are produced by ONE builder call
+    // (`buildRoadmapDeclaredPhasesField`) from ONE `buildRoadmapPhaseVariants`
+    // result, so their scopes are yoked by construction — the COMPLETE check
+    // above covers both. Stated rather than left implicit, because reading the
+    // sentinel set unconditionally would be a latent bug the day the two fields
+    // acquire independent builders: an UNREADABLE sentinel set silently degrades
+    // to "nothing is a sentinel," which ADDS W006 warnings rather than dropping
+    // them.
+    const sentinelTokens = new Set(snapshot.roadmapSentinelPhaseTokens.value);
     const checkboxes = snapshot.roadmapPhaseCheckboxes.value;
     const diagnostics = [];
     for (const { phaseId } of snapshot.roadmapDeclaredPhases.value) {
-        // #3225: sentinel phase ids (999.x/0.x) are never-on-roadmap by
-        // convention; a sentinel heading shouldn't demand a directory.
-        if (isSentinelPhaseId(phaseId))
+        // A backlog/icebox phase legitimately has no directory. The two guards are
+        // DISJOINT, which is why both are needed and neither subsumes the other:
+        //
+        //   #612  `roadmapSentinelPhaseTokens` — bracket sentinels. Under the
+        //         bracket convention the sentinel-ness lives in the MILESTONE, not
+        //         the token: the heading `### [GSD.999] 07:` yields phase id `07`,
+        //         so a bare-token test cannot see it. The snapshot's
+        //         `buildRoadmapPhaseVariants` call carries the bracket id alongside
+        //         and reports the token here. Empty unless the bracket convention
+        //         is active, so no legacy repo's reading changes.
+        //   #3225 `isSentinelPhaseId` — the legacy/bare leading-int rule (999.x/0.x),
+        //         which sees `### Phase 999:` and is blind to `[GSD.999] 07`.
+        //
+        // Upstream's call is kept one-arg verbatim: every `phaseId` here is a bare
+        // token, never a `{CODE}.{MM}`-qualified id, so a convention argument could
+        // not change its result.
+        if (sentinelTokens.has(phaseId) || isSentinelPhaseId(phaseId))
             continue;
-        if (dirsForPhase(dirs, phaseId).length > 0)
+        if (dirsForPhase(dirs, phaseId, convention).length > 0)
             continue;
         // Bug 1 (#3309 W006/W007 migration cluster): a phase whose ONLY
         // directory lives under a milestone archive
@@ -209,10 +247,10 @@ function checkW006(snapshot) {
 // ─── W007 — an on-disk phase directory has no matching ROADMAP entry ──────
 // (verify.cts:2086-2101)
 /** Every directory in `dirs` that ANY declared roadmap phase resolves to. */
-function computeClaimedDirs(dirs, declaredPhases) {
+function computeClaimedDirs(dirs, declaredPhases, convention) {
     const claimed = new Set();
     for (const { phaseId } of declaredPhases) {
-        for (const dir of dirsForPhase(dirs, phaseId))
+        for (const dir of dirsForPhase(dirs, phaseId, convention))
             claimed.add(dir);
     }
     return claimed;
@@ -222,14 +260,19 @@ function checkW007(snapshot) {
     if (snapshot.roadmapDeclaredPhases.scope !== SCOPE.COMPLETE)
         return [];
     const dirs = snapshot.allPhaseDirNames.value;
-    const claimedDirs = computeClaimedDirs(dirs, snapshot.roadmapDeclaredPhases.value);
+    const convention = snapshot.phaseIdConvention;
+    const claimedDirs = computeClaimedDirs(dirs, snapshot.roadmapDeclaredPhases.value, convention);
     const diagnostics = [];
     for (const dirName of dirs) {
         // `extractPhaseToken` is the phase-id.cts owner `PHASE_TOKEN_FROM_DIR_RE`
         // (`src/validate.cts:73-76`) is documented to match exactly
         // (verify.cts's original `p` key from `collectDiskPhaseEntries`,
         // `verify.cts:1373-1397`) — same token, relocated read, not reinvented.
-        const token = extractPhaseToken(dirName);
+        // #612: `collectDiskPhaseEntries` keyed that map through the
+        // convention-aware extractor, so the token this message names must be
+        // derived the same way — otherwise a bracket repo's unclaimed
+        // `GSD.02-05-slug` is reported as phase `GSD.02` rather than `05`.
+        const token = extractPhaseToken(dirName, convention);
         // #3225: a sentinel dir on disk (999-interim, 0-drafts) is defined as
         // never-on-roadmap; it must not trigger W007. #3639: judged on the DIR
         // NAME via the dir-aware recognizer — the extracted token is