@opengsd/gsd-core 1.11.0 → 1.13.0

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

@@ -23,7 +23,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
-const { output, error } = io;
+const { output, error, formatDiagnosticToken } = io;
 const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.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.
  *
@@ -54,6 +57,17 @@ function parseRequirements(reqMd) {
     // The **ID** is extracted from the bullet text caller-side — the seam provides
     // the raw text; we parse the bold-ID prefix from it here.
     const boldIdRe = new RegExp(`^\\*\\*(${ID_PATTERN})\\*\\*\\s*(.*)$`);
+    // The shipped template (gsd-core/templates/requirements.md) writes
+    // `- [ ] **AUTH-01**: User can sign up` — a single separator delimiter
+    // between the bold ID and the description. Strip AT MOST ONE leading
+    // delimiter (plus its surrounding whitespace) before the final `.trim()`,
+    // mirroring roadmap-parser.cts's `stripLeadingDelimiter` delimiter set
+    // (em dash, en dash, colon, hyphen) — that helper is not exported, and its
+    // own `+`-quantified strip removes an entire delimiter RUN, which would
+    // also eat a second, meaningful marker (`**X-01**: -- weird` must keep the
+    // `--`), so the set is mirrored here with a single-occurrence match instead
+    // of reused verbatim.
+    const ONE_LEADING_DELIMITER_RE = /^\s*[—–:-]\s*/;
     for (const bullet of (0, markdown_sectionizer_cjs_1.iterateBullets)(reqMd)) {
         if (bullet.marker !== 'checkbox-unchecked' && bullet.marker !== 'checkbox-checked')
             continue;
@@ -65,7 +79,8 @@ function parseRequirements(reqMd) {
             continue;
         if (!seen.has(id)) {
             seen.add(id);
-            out.push({ id, text: (m[2] || '').trim() });
+            const rawText = m[2] || '';
+            out.push({ id, text: rawText.replace(ONE_LEADING_DELIMITER_RE, '').trim() });
         }
     }
     // Pipe-table-row path and separator-row skip stay caller-side
@@ -290,6 +305,8 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: '',
             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);
@@ -312,12 +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 = [];
-    try {
-        if (node_fs_1.default.existsSync(absPhaseDir))
-            phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
-    }
-    catch { /* unreadable */ }
+    //
+    // #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
@@ -384,6 +409,8 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
                 table: formatGapTable(rows) + '\n' + coverageSummary + '\n\n' + mismatchMsg,
                 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 {
@@ -392,6 +419,8 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: mismatchMsg,
             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.
@@ -408,6 +437,8 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n',
             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([
@@ -425,6 +456,8 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
         table: formatGapTable(rows) + '\n' + summary + '\n',
         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

@@ -34,57 +34,138 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readConfigBaseBranch = readConfigBaseBranch;
+exports._readGitNested = _readGitNested;
+exports._readGitKey = _readGitKey;
 exports.trySymbolicRef = trySymbolicRef;
 exports.tryRemoteShow = tryRemoteShow;
 exports.tryLocalBranch = tryLocalBranch;
 exports.resolveBaseBranchDiagnostics = resolveBaseBranchDiagnostics;
 exports.resolveBaseBranch = resolveBaseBranch;
+exports.resolveProtectedBranchStatus = resolveProtectedBranchStatus;
 exports.gitWorktreeInfoInternal = gitWorktreeInfoInternal;
 exports.phaseStartCommit = phaseStartCommit;
 exports.changedFilesSince = changedFilesSince;
 exports.cmdGitBaseBranch = cmdGitBaseBranch;
-const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const configuration_cjs_1 = require("./configuration.cjs");
+const security_cjs_1 = require("./security.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
-// ─── Helpers ──────────────────────────────────────────────────────────────────
+const { error, ERROR_REASON } = io;
+const { loadConfig: loadConfigSeam } = configLoader;
+/** Render a rejected config value for a diagnostic without throwing on exotic input. */
+function renderRejected(value) {
+    try {
+        return (0, security_cjs_1.sanitizeLabel)(JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        return (0, security_cjs_1.sanitizeLabel)(String(value));
+    }
+}
+/** Nested-only read of `git.<field>`, mirroring `loadConfigResolved`'s `getNested`. */
+function _readGitNested(config, field) {
+    const git = config['git'];
+    if (git !== null && typeof git === 'object' && !Array.isArray(git)) {
+        return git[field];
+    }
+    return undefined;
+}
+/**
+ * Flat-then-nested read, mirroring `loadConfigResolved`'s own `get()`.
+ *
+ * Used for `base_branch` ONLY, and only because it HAS a legacy flat spelling:
+ * `normalizeLegacyKeys` normally hoists it away, so a flat key that SURVIVED
+ * normalization is one the migration refused (a non-object `git` section,
+ * #3760) and is the user's last remaining expression of intent.
+ *
+ * `protected_branches` deliberately does NOT use this. It is new in #3552 with
+ * no legacy form, so honouring a top-level spelling would invent an
+ * undocumented alias that silently outranks the canonical nested key
+ * (round-4 external review).
+ */
+function _readGitKey(config, field) {
+    if (config[field] !== undefined)
+        return config[field];
+    return _readGitNested(config, field);
+}
 /**
- * Safely look up `git.base_branch` from the project's config.json.
- * Returns the configured value (a non-empty, non-null string) or null.
+ * Read the effective root/workstream configuration once for branch policy.
+ *
+ * Production takes the `loadConfig` branch, with `persist: false` — this is a
+ * PREDICATE, invoked on every `execute-phase` and every `ship` run, and a
+ * question must not rewrite the file it is asking about. Without it, any project
+ * carrying a legacy flat key (`base_branch`, `branching_strategy`, `depth`, …)
+ * has `.planning/config.json` silently normalized and rewritten by a call whose
+ * entire contract is to answer a boolean (#3648 review Blocker 1).
+ *
+ * The `readFile` branch is a unit-test seam, NOT a second production path, and
+ * it is deliberately narrower than `loadConfig`. It covers exactly two of
+ * production's steps — `normalizeLegacyKeys`, then the flat-then-nested lookup
+ * — over a single `<cwd>/.planning/config.json`. It does NOT apply
+ * root/workstream `_deepMergeConfig`, builtin or `~/.gsd/defaults.json`
+ * defaults, or `mergeFederatedConfig`. Tests that assert on any of those must
+ * drive `loadConfig` instead; the seam's own tests are scoped to normalization
+ * and shape validation, which is all it reproduces (#3648 review Major 3).
  */
-function readConfigBaseBranch(planningDir, deps) {
-    const readFile = deps?.readFile ??
-        ((p) => { try {
-            return node_fs_1.default.readFileSync(p, 'utf8');
+function readEffectiveGitConfig(cwd, deps) {
+    let config = {};
+    if (deps?.readFile && !deps.loadConfig) {
+        const raw = deps.readFile(node_path_1.default.join(cwd, '.planning', 'config.json'));
+        if (raw) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    const { parsed: normalized } = (0, configuration_cjs_1.normalizeLegacyKeys)(parsed);
+                    config = {
+                        base_branch: _readGitKey(normalized, 'base_branch'),
+                        protected_branches: _readGitNested(normalized, 'protected_branches'),
+                        allow_default_branch_commits: _readGitNested(normalized, 'allow_default_branch_commits'),
+                    };
+                }
+            }
+            catch { /* malformed direct edit contributes no policy values */ }
         }
-        catch {
-            return null;
-        } });
-    const configPath = node_path_1.default.join(planningDir, 'config.json');
-    const raw = readFile(configPath);
-    if (!raw)
-        return null;
-    let cfg;
-    try {
-        cfg = JSON.parse(raw);
     }
-    catch {
-        return null;
+    else {
+        try {
+            config = (deps?.loadConfig ?? loadConfigSeam)(cwd, { persist: false });
+        }
+        catch { /* configuration loading is fail-soft for branch resolution */ }
     }
-    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
-        return null;
-    const top = cfg;
-    // Support both "git.base_branch" (nested) and "base_branch" (flat legacy)
-    const gitSection = top.git;
-    if (gitSection && typeof gitSection === 'object' && !Array.isArray(gitSection)) {
-        const nested = gitSection.base_branch;
-        if (typeof nested === 'string' && nested.trim())
-            return nested.trim();
+    const rawBaseBranch = config.base_branch;
+    const baseBranch = typeof rawBaseBranch === 'string' && rawBaseBranch.trim()
+        ? rawBaseBranch.trim()
+        : null;
+    // A protection predicate must not fail OPEN. `config-set` validation is
+    // bypassable by a direct edit of .planning/config.json, so one bad element
+    // discarding the whole list would silently answer "not protected" for names
+    // the user believes are protected — the exact failure #3552 exists to close,
+    // reintroduced through a different door (#3648 review Blocker 3). Drop only
+    // the bad elements, and report every rejection so it cannot pass unnoticed.
+    const rawProtectedBranches = config.protected_branches;
+    const protectedBranches = [];
+    const rejectedProtectedBranches = [];
+    if (Array.isArray(rawProtectedBranches)) {
+        for (const branch of rawProtectedBranches) {
+            if (typeof branch === 'string' && branch.trim() !== '') {
+                protectedBranches.push(branch.trim());
+            }
+            else {
+                rejectedProtectedBranches.push(renderRejected(branch));
+            }
+        }
+    }
+    else if (rawProtectedBranches !== undefined && rawProtectedBranches !== null) {
+        // Not a list at all — contributes no names, but is still a misconfiguration.
+        rejectedProtectedBranches.push(renderRejected(rawProtectedBranches));
     }
-    const flat = top.base_branch;
-    if (typeof flat === 'string' && flat.trim())
-        return flat.trim();
-    return null;
+    // #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).
@@ -170,7 +251,7 @@ function tryLocalBranch(cwd, execGit) {
  * Consults the full precedence ladder and always returns a non-empty string.
  * Never throws.
  */
-function resolveBaseBranchDiagnostics(cwd, deps) {
+function resolveBaseBranchDiagnosticsWithConfig(cwd, configured, deps) {
     const rawExecGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     // A genuine execGit failure (timeout, or the call could not even spawn —
     // e.g. git missing, surfaced as exitCode 127 with `error` set) is distinct
@@ -186,10 +267,7 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
             anyGitFailure = true;
         return r;
     };
-    // Derive .planning dir relative to cwd (mirrors planningDir() in planning-workspace.cjs)
-    const planningDir = node_path_1.default.join(cwd, '.planning');
     // 1. Config override
-    const configured = readConfigBaseBranch(planningDir, deps);
     if (configured)
         return { branch: configured, verified: true };
     // 2. symbolic-ref (fast, no network)
@@ -210,6 +288,10 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
     // not answer (#3057 B4).
     return { branch: 'main', verified: !anyGitFailure };
 }
+function resolveBaseBranchDiagnostics(cwd, deps) {
+    const { baseBranch } = readEffectiveGitConfig(cwd, deps);
+    return resolveBaseBranchDiagnosticsWithConfig(cwd, baseBranch, deps);
+}
 /**
  * Resolve the default/base branch for the repository at `cwd`.
  *
@@ -220,6 +302,23 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
 function resolveBaseBranch(cwd, deps) {
     return resolveBaseBranchDiagnostics(cwd, deps).branch;
 }
+/** Resolve the base branch plus configured protected-branch extensions. */
+function resolveProtectedBranchStatus(cwd, currentBranch, deps) {
+    const effectiveConfig = readEffectiveGitConfig(cwd, deps);
+    const { branch: baseBranch, verified } = resolveBaseBranchDiagnosticsWithConfig(cwd, effectiveConfig.baseBranch, deps);
+    const protectedBranches = [...new Set([
+            ...(effectiveConfig.allowDefaultBranchCommits ? [] : [baseBranch]),
+            ...effectiveConfig.protectedBranches,
+        ])];
+    return {
+        baseBranch,
+        protectedBranches,
+        rejectedProtectedBranches: effectiveConfig.rejectedProtectedBranches,
+        isProtected: protectedBranches.includes(currentBranch),
+        verified,
+        allowDefaultBranchCommits: effectiveConfig.allowDefaultBranchCommits,
+    };
+}
 /**
  * Detect whether `cwd` sits inside a git worktree, and if so, return the
  * absolute path of the worktree root.
@@ -352,7 +451,51 @@ function changedFilesSince(cwd, sinceRef, execGit) {
  * Resolves the default branch and writes it to stdout (raw string, newline-terminated).
  * Called by workflows via `gsd_run query git.base-branch`.
  */
-function cmdGitBaseBranch(cwd, _args, deps) {
+function cmdGitBaseBranch(cwd, args, deps) {
+    if (args[0] === '--is-protected') {
+        if (args.length > 2) {
+            error('Usage: git base-branch --is-protected [<branch>]', ERROR_REASON.USAGE);
+        }
+        const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));
+        // `git branch --show-current` prints nothing on a detached HEAD, so the
+        // call sites legitimately pass an explicit empty string: no protected
+        // branch is named '', the answer is false, and that is not a fault worth
+        // reporting. The flag with NO argument is a different thing — a caller bug
+        // that `args[1] ?? ''` used to collapse into the detached-HEAD case. Same
+        // handling, but said out loud so the two can be told apart.
+        //
+        // This diagnostic deliberately does NOT state the answer. The empty branch
+        // matches no protected name, but the fail-closed guard below still renders
+        // `true` when the base branch could not be verified — so promising "false"
+        // here would contradict what this same call prints on stdout (#3648 review).
+        if (args.length < 2) {
+            writeDiagnostic(`⚠ git-base-branch: --is-protected was called without a branch argument; ` +
+                `treating it as an empty branch name. Pass the branch to test, ` +
+                `e.g. --is-protected "$CURRENT_BRANCH".\n`);
+        }
+        const status = resolveProtectedBranchStatus(cwd, args[1] ?? '', deps);
+        if (status.rejectedProtectedBranches.length > 0) {
+            writeDiagnostic(`⚠ git-base-branch: ignoring ${status.rejectedProtectedBranches.length} unusable ` +
+                `git.protected_branches entr${status.rejectedProtectedBranches.length === 1 ? 'y' : 'ies'} ` +
+                `(${status.rejectedProtectedBranches.join(', ')}) — each must be a non-empty branch name. ` +
+                `The remaining names are still enforced. See #3552.\n`);
+        }
+        // A protection guard must fail closed: if the base branch could not be
+        // verified against this repository (a git query timed out or failed to
+        // run — #3057 B4), report "protected" rather than silently trusting an
+        // unverified guess that might happen to not match the current branch.
+        const rendered = String(status.verified ? status.isProtected : true);
+        if (!status.verified) {
+            writeDiagnostic(`⚠ git-base-branch: --is-protected could not verify repository branch metadata; ` +
+                `defaulting to protected (fail-closed). See #3057.\n`);
+        }
+        const write = deps?.write ?? ((s) => process.stdout.write(s));
+        write(rendered + '\n');
+        return rendered;
+    }
+    if (args.length > 0) {
+        error(`Unknown flag for git.base-branch: ${args[0]}`, ERROR_REASON.USAGE);
+    }
     const { branch, verified } = resolveBaseBranchDiagnostics(cwd, deps);
     if (!verified) {
         const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));

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

@@ -35,7 +35,7 @@ const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
 const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { isSentinelPhaseId } = phaseIdMod;
+const { isSentinelPhaseDir } = phaseIdMod;
 // ─── C001 — gap in disk phase numbering (integer sequence) ────────────────
 // (verify.cts:1504-1519)
 function checkC001(snapshot) {
@@ -47,8 +47,12 @@ function checkC001(snapshot) {
         return [];
     const integerPhases = snapshot.allPhaseDirNames.value
         // #3225: exclude sentinel phase ids (999.x/0.x) — never part of the
-        // sequential numbering, mirrors verify.cts:1510 verbatim.
-        .filter((p) => !p.includes('.') && !isSentinelPhaseId(p))
+        // sequential numbering, mirrors verify.cts:1510 verbatim. The dot filter
+        // already drops every code-prefixed (bracket) name before the sentinel
+        // test, so the dir-aware recognizer below is defense-in-depth for the
+        // dotless legacy forms — kept so this guard cannot regress if the dot
+        // filter is ever loosened (#3639).
+        .filter((p) => !p.includes('.') && !isSentinelPhaseDir(p))
         .map((p) => parseInt(p, 10))
         .filter((n) => !Number.isNaN(n))
         .sort((a, b) => a - b);

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

@@ -104,7 +104,7 @@ const planningScopeMod = require("../planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { matchPhaseDirs, normalizePhaseName, extractPhaseToken, isSentinelPhaseId } = phaseIdMod;
+const { matchPhaseDirs, normalizePhaseName, extractPhaseToken, isSentinelPhaseId, isSentinelPhaseDir } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const validateMod = require("../validate.cjs");
 const { phaseVariants } = validateMod;
@@ -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,17 +260,25 @@ 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.
-        if (isSentinelPhaseId(token))
+        // never-on-roadmap; it must not trigger W007. #3639: judged on the DIR
+        // NAME via the dir-aware recognizer — the extracted token is
+        // milestone-stripped, so a bracket sentinel (GSD.999-07-icebox) was
+        // invisible to the id predicate and false-fired as an orphan.
+        if (isSentinelPhaseDir(dirName))
             continue;
         if (claimedDirs.has(dirName))
             continue;