@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/bin/lib/phase-id.cjs

@@ -158,7 +158,156 @@ const BRACKET_PHASE_TOKEN_SOURCE = `\\d+[A-Z]?` +
 // followed by a `Phase ` label) or a bare `Phase ` label; a bare number is NOT
 // a phase-heading intro. The `[^\]]{1,200}` bound mirrors the existing
 // roadmap-parser heading regexes (ReDoS-safe: a header is one short line).
+//
+// Retained as PR-1 shipped it. PR-2 does not consume it — see the gated
+// selector below, which supersedes it — and it is left byte-identical so an
+// already-merged epic export does not change its accepted language.
 const PHASE_HEADING_PREFIX_SRC = '(?:\\[[^\\]]{1,200}\\]\\s*(?:Phase\\s+)?|Phase\\s+)';
+// ── #612 PR-2: the ONE bracket identity grammar ─────────────────────────────
+// A bracket phase-ID prefix is `{CODE}.{MM}`. Before this, three spellings of
+// that shape lived in this file and disagreed: extractPhaseToken's bracket
+// branch (`\d+`, case-sensitive), bracketQualifiedKey (`\d+`, mixed-case), and
+// the dir prefix (`\d{2,}`). `GSD.2-05-feature` was simultaneously "not a phase
+// directory" and "phase 05", depending on which one a caller reached. They are
+// now one source.
+//
+// The milestone width mirrors the EMIT grammar rather than accepting any digit
+// run: pad2() emits at least two digits, so two digits — or three-plus with no
+// leading zero — is what toDir can produce. A bare `0` is NOT admitted: the
+// padded `00` is the backlog sentinel's canonical identity and `\d{2}` already
+// covers it, so nothing needs the unpadded spelling. (An earlier revision of
+// this comment claimed the opposite; the constant below has always rejected it
+// — #2867 review, Minor 2.) `[GSD.2] 05:` is therefore NOT a bracket id —
+// which is the point: it is the shape that made the three spellings disagree.
+// Reconciled with BRACKET_CANONICAL_NUMERIC_SOURCE above — the width toDir
+// actually emits (pad2: 2 digits, or 3+ with no leading zero). The earlier
+// `(?:\d{2,}|0)` diverged from it in both directions: it admitted `002`, which
+// the emit validator rejects, and a bare `0` that pad2 never produces. Every
+// bracket-milestone recognizer now derives from this one constant — the section
+// recognizers previously spelled `0*N` or `\d+` and accepted `[GSD.2]`, which
+// SCOPED a milestone no phase heading could then resolve into, recreating the
+// on-disk-count fallback this PR exists to remove.
+//
+// An unpadded bracket is therefore MALFORMED, uniformly: it scopes nothing,
+// bounds nothing, sections nothing, and is not a phase id. W005 on its
+// directories is the signal that surfaces it.
+const BRACKET_MILESTONE_NUMERIC_SRC = BRACKET_CANONICAL_NUMERIC_SOURCE;
+// #2761 M3 (trek-e review): the bracket PROJECT-CODE class, as a named source
+// rather than a class this file (and three readers outside it) each re-typed.
+// The re-typed copies were the exact drift #2761's own gate forbids — "no token
+// literal outside src/phase-id.cts" — and `check:phase-id-drift` did not see
+// them, because its detector only knew the phase-NUMBER token grammar. The
+// guard now carries a bracket rule too (scripts/lint-phase-id-drift.cjs).
+const BRACKET_PROJECT_CODE_SRC = '[A-Z][A-Z0-9_]*';
+const BRACKET_ID_SRC = `${BRACKET_PROJECT_CODE_SRC}\\.${BRACKET_MILESTONE_NUMERIC_SRC}`;
+// The bracket MILESTONE INTRO — `[CODE.MM]` — in the two shapes its readers
+// need. Both were re-typed verbatim outside this module before #2761 M3:
+//
+//   * PINNED, to one already-resolved milestone integer. This owns the pad2
+//     spelling rule as well as the grammar, so "canonical spelling only, not
+//     `0*N`" (the rule that keeps `[GSD.2]` from scoping a milestone no phase
+//     heading can resolve into) lives in ONE place instead of being restated
+//     beside every regex. `roadmap-parser`'s bracket-fallback selector and
+//     `state`'s `isMilestoneBounded` both consume this.
+//
+//   * CAPTURING, over any milestone, putting the milestone digits in a group.
+//     `validate`'s `checkBracketCoherence` consumes this.
+//
+// The milestone argument is expected to be a safe integer — every caller
+// resolves it through `Number.isSafeInteger` first. A non-integer yields a
+// regex source that is still well-formed and simply matches nothing, which is
+// the same safe degrade the callers' own guards produce.
+function bracketMilestoneIntroSrcFor(milestone) {
+    return `\\[${BRACKET_PROJECT_CODE_SRC}\\.${String(milestone).padStart(2, '0')}\\]`;
+}
+const BRACKET_MILESTONE_INTRO_CAPTURING_SRC = `\\[${BRACKET_PROJECT_CODE_SRC}\\.(${BRACKET_MILESTONE_NUMERIC_SRC})\\]`;
+// Recognition is case-INSENSITIVE (every reader compiles `/i`), but the identity
+// helpers this file owns — isSentinelPhaseId, getMilestoneFromPhaseId,
+// bracketQualifiedKey — match `[A-Z]` case-SENSITIVELY. A lowercase bracket id
+// captured by a reader and handed straight to them silently fails every identity
+// test, which is how `### [gsd.999] 07:` leaked into phase counts as a real
+// phase. Fold before any identity operation; never fold for display.
+function foldBracketId(bracketId) {
+    return String(bracketId).toUpperCase();
+}
+// The identity recognizers every bracket helper in this file shares.
+// `BRACKET_ID_PREFIX_RE` is applied to an ALREADY-FOLDED string, so it needs no
+// `/i`; the other two see raw dir names and carry it.
+// The milestone field must END at the phase separator. Without the boundary the
+// width alternation matched a PREFIX of a malformed run — `GSD.002-01` matched
+// its leading `00` and read as a sentinel.
+const BRACKET_ID_PREFIX_RE = new RegExp(`^${BRACKET_PROJECT_CODE_SRC}\\.(${BRACKET_MILESTONE_NUMERIC_SRC})(?=-|$)`);
+const BRACKET_DIR_PREFIX_SRC = `${BRACKET_ID_SRC}-`;
+// The trailing `(?=-|$)` is what makes the recognizer and the resolver agree on
+// REJECTED input, not just accepted input. Without it `GSD.02-12A-hotfix`
+// resolves to token `12` here while the directory recognizer calls the name
+// malformed — so W005 reports it malformed in the same run that the
+// milestone-complete check treats it as a real phase directory.
+const BRACKET_DIR_TOKEN_RE = new RegExp(`^${BRACKET_DIR_PREFIX_SRC}(\\d+(?:\\.\\d+)?)(?=-|$)`, 'i');
+// Same width rule, same `(?=-|$)` boundary and same single-sub-phase shape as
+// BRACKET_DIR_TOKEN_RE. Without them a qualified query `GSD.02-12` matched the
+// directory `GSD.02-12A-hotfix` — which isPhaseDirName calls malformed — and
+// phaseTokenMatches returns UNCONDITIONALLY on a qualified hit, so that
+// disagreement would have been final rather than a fall-through.
+const BRACKET_QUALIFIED_KEY_RE = new RegExp(`^(${BRACKET_PROJECT_CODE_SRC})\\.(${BRACKET_MILESTONE_NUMERIC_SRC})-(\\d+(?:\\.\\d+)?)(?=-|$)`, 'i');
+// ── #612 PR-2: gated heading-intro selection ────────────────────────────────
+// The two intro spellings that exist upstream TODAY, transcribed verbatim from
+// the call sites. A repo that has not opted into the bracket convention
+// compiles exactly these — not a superset of them, THEM — so its reads are
+// structurally identical to the base build rather than argued equivalent.
+// tests/adr-612-bracket-heading-selection.test.cjs asserts that byte-equality
+// against its own independently transcribed copies of the call-site literals.
+const BASE_ANY_BRACKET_HEADING_PREFIX_SRC = '(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+';
+const BASE_PHASE_LABEL_PREFIX_SRC = 'Phase\\s+';
+// Which of those two a site spells at base. Passed explicitly rather than
+// inferred, because the choice is a fact about the call site's history that no
+// amount of looking at the widened pattern can recover.
+const PHASE_HEADING_BASELINE = Object.freeze({
+    /** Site already tolerates `[anything] Phase N` — roadmap headings, validate's heading scanner. */
+    ANY_BRACKET: 'any-bracket',
+    /** Site spells a bare `Phase N` with no bracket tolerance — checklist bullets, the counters. */
+    LABEL_ONLY: 'label-only',
+});
+/**
+ * The heading-intro source a site should compile, given the resolved
+ * `phase_id_convention`.
+ *
+ * NON-bracket conventions (null, undefined, 'milestone-prefixed', or any
+ * unrecognized value) return the site's BASE spelling unchanged. This is the
+ * whole design: PR-2 originally widened these reads ungated and argued the new
+ * shape "cannot occur in a legacy ROADMAP", which is false — `### [RFC.2119] 5:`,
+ * `### [v1.0] 2024:` and `### [ADR.612] 3:` are all legal legacy headings that
+ * the widened form claims as phases, moving phase_count, total_phases and W006
+ * on repos that never opted in. Selection at construction time removes the
+ * argument entirely: there is nothing to reason about, because a non-bracket
+ * repo compiles the same source string it compiled before.
+ *
+ * `capturing` adds EXACTLY ONE group, at position 1, holding the bracket id —
+ * `undefined` whenever a non-bracket alternative matched. Sites that filter
+ * sentinels need it: READING-B puts the sentinel milestone in the bracket, so
+ * testing the phase token alone is blind to `### [GSD.999] 01:`.
+ *
+ * Pure: takes the resolved convention, never reads config.
+ */
+function phaseHeadingPrefixSrcFor(baseline, convention, capturing = false) {
+    const base = baseline === PHASE_HEADING_BASELINE.ANY_BRACKET
+        ? BASE_ANY_BRACKET_HEADING_PREFIX_SRC
+        : BASE_PHASE_LABEL_PREFIX_SRC;
+    if (convention !== 'bracket')
+        return base;
+    const id = capturing ? `(${BRACKET_ID_SRC})` : BRACKET_ID_SRC;
+    // `[ \t]*` not `\s*`: `\s` spans newlines, so a bracket-terminated heading
+    // followed by a blank line and a digit-leading prose line read as one phase.
+    // BOTH bracket forms are admitted at both baselines, and both CAPTURE. The
+    // any-bracket base already matches `[GSD.999] Phase 07:` on its own — but
+    // through the base alternative, which captures nothing, so the reader saw
+    // `bracketId === undefined`, fell back to the legacy leading-integer rule, and
+    // counted a labeled icebox heading as a real phase while the label-less form
+    // beside it was excluded. Two derivations of one ROADMAP disagreed. The
+    // bracket alternative is tried FIRST so it wins the capture.
+    const bracketAlt = `\\[${id}\\][ \\t]*(?:Phase\\s+|(?=\\d))`;
+    return `(?:${bracketAlt}|${base})`;
+}
 function stripProjectCodePrefix(value, caseInsensitive = true) {
     const input = String(value);
     const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
@@ -200,10 +349,10 @@ function getMilestoneFromPhaseId(phaseId, convention) {
     // pure (no config read) and backward-compatible: every existing single-arg
     // caller resolves to the unchanged READING-A body.
     if (convention === 'bracket') {
-        const b = String(phaseId).match(/^([A-Z][A-Z0-9_]*)\.(\d+)/);
+        const b = foldBracketId(phaseId).match(BRACKET_ID_PREFIX_RE);
         if (!b)
             return null;
-        const mm = parseInt(b[2], 10);
+        const mm = parseInt(b[1], 10);
         if (SENTINEL_RANGES.includes(mm))
             return null; // sentinel milestones have no real milestone
         return `v${mm}.0`;
@@ -383,9 +532,36 @@ function isSentinelPhaseId(phaseId, convention) {
     // convention-less caller uses the legacy/bare leading-int rule below, so no
     // existing reader gains a false positive; the bracket reading is opt-in.
     if (convention === 'bracket') {
-        const bracket = s.match(/^[A-Z][A-Z0-9_]*\.(\d+)/); // bracket: milestone in the prefix
+        // #612 PR-2: fold before matching. Readers recognize headings under `/i`, so
+        // a lowercase `[gsd.999]` arrives verbatim; the case-sensitive class below
+        // then failed to match and an icebox item counted as a real phase.
+        const bracket = foldBracketId(s).match(BRACKET_ID_PREFIX_RE);
         if (bracket)
             return SENTINEL_RANGES.includes(parseInt(bracket[1], 10));
+        // #2761 round-12: NO bracket tag matched — a bare/untagged id under
+        // bracket convention (`0-bootstrap`, a directory with no `{CODE}.{MM}-`
+        // prefix, or a legacy-spelled `### Phase 0:` heading routed here without
+        // its own bracketId guard). Falling through to the LEGACY leading-int rule
+        // below would read this bare `0` as sentinel milestone 0 — but under
+        // bracket convention milestone 0 is expressed ONLY via an explicit
+        // bracket tag, so an untagged leading `0` is a real phase token, not a
+        // sentinel. This mirrors the two HEADING-side counters that already carry
+        // this exact carve-out: state.cts's `countRoadmapPhaseHeadings` guards its
+        // bare-0 exclusion with `bracketId &&` (so an untagged `Phase 0:` heading
+        // is counted), and roadmap-parser.cts's `scanMilestonePhaseIds` composes
+        // the bare-token rule as 999-only, deliberately NOT this predicate, for
+        // the identical reason (#3185: the leading-int rule also swallows the
+        // #2554 decimal ids — `0.5-bootstrap` is a real phase, not milestone 0).
+        // The 999/icebox reading stays universal either way — an untagged `999`
+        // is still backlog under every convention — so only that half of
+        // SENTINEL_RANGES applies here.
+        //
+        // `isSentinelPhaseDir` remains deliberately convention-blind for its
+        // warning-only disk guards and may conservatively classify a bare `0`
+        // directory as sentinel. This branch has an explicit resolved convention
+        // and feeds counts/archives, so it must retain the more precise reading.
+        const bare = stripProjectCodePrefix(s).match(/^0*(\d+)/);
+        return bare !== null && parseInt(bare[1], 10) === 999;
     }
     const legacy = stripProjectCodePrefix(s).match(/^0*(\d+)/); // legacy/bare: leading int
     if (!legacy)
@@ -599,7 +775,10 @@ function extractPhaseToken(dirName, convention) {
     // config read). The captured token is dot-only (`PP[.SS]`); the milestone↔phase
     // hyphen and any trailing plan/slug are excluded.
     if (convention === 'bracket') {
-        const bracketDir = dirName.match(/^[A-Z][A-Z0-9_]*\.\d+-(\d+(?:\.\d+)?)/);
+        // #612 PR-2: built from the ONE bracket identity grammar, not a private
+        // spelling. Case-insensitive to match how the readers recognize headings and
+        // directories; the milestone width is the emit grammar's.
+        const bracketDir = dirName.match(BRACKET_DIR_TOKEN_RE);
         if (bracketDir)
             return bracketDir[1];
     }
@@ -705,19 +884,42 @@ function extractPhaseToken(dirName, convention) {
  * cannot resolve a genuinely different phase's artifact (`02.1-...` still
  * fails every `01`-rooted candidate).
  *
- * BRACKET CONVENTION (review item 7): a letter-prefixed-decimal dir
- * (`P0.3-2-slug`) is string-INDISTINGUISHABLE from a bracket-dir token
- * (`extractPhaseToken` above, gated on `convention === 'bracket'`) without an
- * explicit convention signal — and this predicate is never given one: none
- * of its 9 call sites thread `convention`/config through today. Rather than
- * guess a reading it cannot know is active and risk excluding the phase's OWN
- * artifact (the exact defect class this rework exists to fix), this family
- * (`firstLetterPrefixed` dirs) falls into the same include-everything
- * fail-safe as the zero-segment case below — a documented, deliberate
- * widening (it also stops excluding a genuine stray from a DIFFERENT
- * letter-prefixed-decimal phase, narrowly) accepted in trade for never
- * dropping the phase's own report. Convention-aware scoping for this family
- * is deferred to whenever a call site actually threads `convention` through.
+ * BRACKET CONVENTION (review item 7; reworked by #612/#2761): a
+ * letter-prefixed-decimal dir (`P0.3-2-slug`) is string-INDISTINGUISHABLE
+ * from a bracket-dir token (`extractPhaseToken` above, gated on
+ * `convention === 'bracket'`) without an explicit convention signal. This
+ * predicate now takes the same optional trailing `convention` its sibling
+ * helpers do (ADR-2121 additive shape): when a call site threads
+ * `'bracket'` and the dir is a WELL-FORMED bracket dir
+ * (`BRACKET_DIR_TOKEN_RE` — the one grammar owner, shared with
+ * `extractPhaseToken`'s bracket branch), the dir's real phase token is
+ * readable and membership is scoped through the identical candidate
+ * comparison its legacy twin gets — so `GSD.02-02-two` reads exactly what
+ * `02-two` reads, which is PR-2's core invariant. Convention-less calls,
+ * bracket-MALFORMED names (1-digit milestone, letter-suffixed token — the
+ * shapes W005 reports), and legacy-shaped dirs inside a bracket repo all
+ * resolve to the unchanged body below.
+ *
+ * A filename carrying its own bracket-qualified stem is compared on the
+ * qualified key — see the branch body. An M-NN-stem artifact name
+ * (`02-01-VERIFICATION.md` in `GSD.02-01-one`) is excluded under the bracket
+ * convention, deliberately: that is exactly what the legacy twin does with
+ * the same file, twin-parity is this PR's contract, and migration-window
+ * artifact renaming belongs to the migrator slice per ADR-612 — the trade is
+ * pinned in tests/adr-612-bracket-phase-counting.test.cjs.
+ *
+ * For those unthreaded/unparseable cases the include-everything trade
+ * stands: rather than guess a reading it cannot know is active and risk
+ * excluding the phase's OWN artifact (the exact defect class this rework
+ * exists to fix), the ambiguous families widen to include-everything,
+ * accepted in trade for never dropping the phase's own report. Note the
+ * bracket family splits across BOTH fail-safes, not just one: a short
+ * digit-bearing project code (`A1.02-…`) lands in `firstLetterPrefixed`,
+ * but a 3+-letter code (`GSD.02-…`) derives ZERO token segments —
+ * `PROJECT_CODE_PREFIX_CAPTURE_RE_I` strips `{CODE}-`, not `{CODE}.` — so
+ * the zero-token fail-safe fires first. A fixer patching only the
+ * `firstLetterPrefixed` branch covers neither; the convention gate above
+ * covers both.
  *
  * FAIL-SAFE (#3511, unchanged): when dirName's own leading segment carries no
  * phase-number token at all (`derivePhaseTokenSegments` finds zero segments —
@@ -754,7 +956,44 @@ function extractPhaseToken(dirName, convention) {
  * the original pre-#3357 "alphabetically first of ALL dashed candidates"
  * behavior, exactly as it always did for that directory shape.
  */
-function isPhaseArtifact(fileName, phaseDirName) {
+function isPhaseArtifact(fileName, phaseDirName, convention) {
+    // #612/#2761: the bracket branch — see "BRACKET CONVENTION" in the docblock.
+    // Gated on the same explicit signal AND the same grammar
+    // (`BRACKET_DIR_TOKEN_RE`) as `extractPhaseToken`'s bracket branch, so the
+    // two surfaces can never disagree about which names are bracket dirs. A
+    // name that fails the grammar falls through to the unchanged body below.
+    if (convention === 'bracket') {
+        const bracketDir = phaseDirName.match(BRACKET_DIR_TOKEN_RE);
+        if (bracketDir) {
+            // The convention must gate the FILENAME reading, not just the directory
+            // reading — a milestone-qualified artifact name (the layout the
+            // read-tolerance suite models) derives zero legacy token segments, so
+            // without this it enters FIX 2's token-less containment and any bracket
+            // dir admits it. Compared on the qualified key: the phase's own
+            // qualified artifact stays included — the exact key, and the dotted
+            // sub-phase continuation (`GSD.02-05.1-…` is `GSD.02-05`'s own file,
+            // the same dash-OR-dot rule matchesPhaseTokenCandidates applies; a
+            // dash-continuation never reaches this comparison, the phase group's
+            // `(?=-|$)` boundary already stopped the key before it) — while a
+            // WELL-FORMED qualified stem naming a different phase or milestone is
+            // excluded. A qualified-SHAPED but grammar-malformed stem (letter
+            // suffix, 1-digit milestone, 2-level dot — the W005 shapes) yields a
+            // null fileKey and keeps the module's documented include-everything
+            // fail-safe via FIX 2 below, same as every other undecidable name.
+            const fileKey = bracketQualifiedKey(fileName, convention);
+            if (fileKey !== null) {
+                const dirKey = bracketQualifiedKey(phaseDirName, convention);
+                if (dirKey !== null)
+                    return fileKey === dirKey || fileKey.startsWith(`${dirKey}.`);
+            }
+            // Reached when the filename carries no well-formed qualified stem (the
+            // common case — every unqualified name), or when the DIR's own key is
+            // null despite matching the dir grammar (an unsafe-integer milestone or
+            // phase — bracketQualifiedKey refuses both rather than collide).
+            // Either way the candidate path decides, deliberately.
+            return matchesPhaseTokenCandidates(fileName, [bracketDir[1]]);
+        }
+    }
     const { tokenSegments, firstLetterPrefixed } = derivePhaseTokenSegments(phaseDirName);
     if (tokenSegments.length === 0)
         return true;
@@ -763,6 +1002,22 @@ function isPhaseArtifact(fileName, phaseDirName) {
     const strippedToken = strippedDir !== phaseDirName ? extractPhaseToken(strippedDir) : literalToken;
     const leadingRunMatch = strippedDir.match(LEADING_DIGIT_RUN_RE);
     const rawCandidates = [literalToken, strippedToken, leadingRunMatch?.[1]].filter((t) => Boolean(t));
+    if (matchesPhaseTokenCandidates(fileName, rawCandidates))
+        return true;
+    // Bracket-convention ambiguity fail-safe — see docblock above.
+    if (firstLetterPrefixed)
+        return true;
+    return false;
+}
+/**
+ * Candidate-comparison core shared by `isPhaseArtifact`'s two entry paths —
+ * the legacy segment-derived readings and the #612 bracket-dir token. One
+ * comparison rule, not two that agree today and drift tomorrow: the padded/
+ * de-padded expansion, the separator class, and FIX 2 apply identically
+ * whichever path produced the candidates, which is what makes a bracket dir
+ * read exactly what its legacy twin reads.
+ */
+function matchesPhaseTokenCandidates(fileName, rawCandidates) {
     // Each reading is compared in BOTH its padded and de-padded form: files are
     // written padded by `normalizePhaseName` (`cmdScaffold`) while directories
     // are often not (`1-unpadded`), and legacy trees carry the reverse pairing.
@@ -802,12 +1057,7 @@ function isPhaseArtifact(fileName, phaseDirName) {
     }
     // FIX 2: token-less filename (bare "VERIFICATION.md"/"UAT.md") — containment
     // in this phase's own directory listing is sufficient.
-    if (derivePhaseTokenSegments(fileName).tokenSegments.length === 0)
-        return true;
-    // Bracket-convention ambiguity fail-safe — see docblock above.
-    if (firstLetterPrefixed)
-        return true;
-    return false;
+    return derivePhaseTokenSegments(fileName).tokenSegments.length === 0;
 }
 /**
  * #3511: scope `fileNames` to the subset that passes
@@ -856,14 +1106,66 @@ function isPhaseArtifact(fileName, phaseDirName) {
  * re-derived per site (CLAUDE.md's Generative Fix Divergence class).
  * `isPhaseArtifact` stays exported for single-item membership questions and
  * its own unit tests.
+ *
+ * #612/#2761: both helpers take the same optional trailing `convention` their
+ * sibling primitives (`extractPhaseToken`, `phaseTokenMatches`) do — the
+ * ADR-2121 additive shape, so every existing two-argument call resolves to
+ * the unchanged legacy body. A call site that already holds the resolved
+ * convention threads it and bracket dirs scope exactly like their legacy
+ * twins; convention-less call sites keep the documented include-everything
+ * fail-safes and are the follow-up-slice work (they cannot scope a bracket
+ * dir until they can resolve the convention, and guessing is the one thing
+ * this predicate must never do).
  */
-function scopeToPhase(fileNames, phaseDirName) {
-    return fileNames.filter((f) => isPhaseArtifact(f, phaseDirName));
+function scopeToPhase(fileNames, phaseDirName, convention) {
+    return fileNames.filter((f) => isPhaseArtifact(f, phaseDirName, convention));
+}
+/**
+ * Canonical comparable key for a milestone-qualified bracket id or dir name.
+ * Lifts the milestone out of the `{CODE}.{MM}-` prefix so a flat multi-milestone
+ * layout disambiguates: `CK.03-02` resolves to its OWN milestone's directory,
+ * never the first same-numbered directory of another milestone.
+ *
+ * Returns null for UNQUALIFIED ids (`02`, `HQ-11`, `11.01`) so callers fall back
+ * to bare-token matching unchanged, and GATED on convention === 'bracket' for
+ * the same reason as extractPhaseToken: the qualified key is padding-
+ * INSENSITIVE where the legacy token path is padding-SENSITIVE, so ungated it
+ * silently widens matching on legacy repos.
+ */
+function bracketQualifiedKey(s, convention) {
+    if (convention !== 'bracket')
+        return null;
+    const m = String(s).match(BRACKET_QUALIFIED_KEY_RE);
+    if (!m)
+        return null;
+    const milestone = parseInt(m[2], 10);
+    // A milestone integer past Number's exact range collapses to Infinity, and
+    // every such id would then share one key. Refuse rather than collide.
+    if (!Number.isSafeInteger(milestone))
+        return null;
+    const phase = m[3].split('.').map(n => parseInt(n, 10));
+    if (phase.some(n => !Number.isSafeInteger(n)))
+        return null;
+    return `${foldBracketId(m[1])}.${milestone}-${phase.join('.')}`;
 }
 /**
  * Check if a directory name's phase token matches the normalized phase exactly.
+ *
+ * The optional `convention` is the ADR-2121 additive shape: every existing
+ * two-argument call site resolves to the unchanged legacy body.
  */
-function phaseTokenMatches(dirName, normalized) {
+function phaseTokenMatches(dirName, normalized, convention) {
+    if (convention === 'bracket') {
+        // A milestone-qualified query compares on the full qualified key, and
+        // returns unconditionally: falling through on a miss would re-admit the
+        // cross-milestone match the qualification exists to prevent.
+        const qKey = bracketQualifiedKey(normalized, convention);
+        if (qKey)
+            return bracketQualifiedKey(dirName, convention) === qKey;
+        const bracketToken = extractPhaseToken(dirName, convention);
+        if (bracketToken.toUpperCase() === normalized.toUpperCase())
+            return true;
+    }
     const token = extractPhaseToken(dirName);
     if (token.toUpperCase() === normalized.toUpperCase())
         return true;
@@ -960,8 +1262,8 @@ const unpad = (digits) => digits.replace(/^0+(?=\d)/, '');
  * the directory's leading digit run instead of `extractPhaseToken` (whose
  * token for these dirs is the mis-absorbed multi-segment form).
  */
-function matchPhaseDirs(dirs, normalized) {
-    const primary = dirs.filter(d => phaseTokenMatches(d, normalized));
+function matchPhaseDirs(dirs, normalized, convention) {
+    const primary = dirs.filter(d => phaseTokenMatches(d, normalized, convention));
     if (primary.length > 0)
         return { matches: primary, usedBareFallback: false };
     const bare = String(normalized);
@@ -1021,9 +1323,18 @@ function phaseKeyFromToken(token) {
 /**
  * Canonical key for a phase DIRECTORY name (`"05-schedule-8"` → `"05"`,
  * `"PROJ-5-x"` → `"05"`, `"30.1-follow-up"` → `"30.1"`).
+ *
+ * #612: `convention` is forwarded to `extractPhaseToken`, which needs that signal
+ * to read a bracket directory (`"GSD.02-05-delta"` → `"05"`) — a bracket dir is
+ * string-indistinguishable from the legacy letter-prefixed-decimal family, so the
+ * extractor refuses to guess. Optional and defaulted-absent, so every pre-#612
+ * call site resolves byte-identically to prior behaviour. Without it a bracket dir
+ * yields its whole name as the key and never matches the ROADMAP entry it names —
+ * #2562's own defect class reached from the other side: both sides of a comparison
+ * must be derived not merely by the same function but under the same convention.
  */
-function phaseKeyFromDir(dirName) {
-    return phaseKeyFromToken(extractPhaseToken(dirName));
+function phaseKeyFromDir(dirName, convention) {
+    return phaseKeyFromToken(extractPhaseToken(dirName, convention));
 }
 /**
  * Canonical key for a phase referenced in PROSE — a ROADMAP `## Progress` table
@@ -1156,6 +1467,63 @@ function isForeignPrefixedPhaseQuery(phase, projectCode) {
  * form so a canonical heading (`### Phase 117:`) is preferred over a drifted
  * prefixed one (`### Phase MANIFOLD-117:`) when both exist in one ROADMAP.
  */
+// Separator characters a branch-name template may plausibly use to join
+// `{slug}` to its neighbours — the four this repo's shipped templates and
+// docs/CONFIGURATION.md's custom-template examples use (`/`, `-`, `_`, `.`).
+const BRANCH_TEMPLATE_SEP_RE = /[-_./]/;
+const BRANCH_TEMPLATE_SEP_RUN_RE = /([-_./])\1+/g;
+const BRANCH_TEMPLATE_EDGE_SEP_RE = /^[-_./]+|[-_./]+$/g;
+/**
+ * #4126: the ONE branch-name-template renderer for the `phase` branching
+ * strategy, shared by `cmdCommit` (src/commands.cts) and
+ * `cmdInitExecutePhase` (src/init.cts) so the two call sites cannot diverge
+ * on how an undeliverable `phaseSlug` degrades (they previously each
+ * independently substituted the literal word `phase`, producing a
+ * non-identifying branch name like `gsd/phase-08-phase` that contradicts an
+ * honestly-reported `phase_slug: null`).
+ *
+ * `{project}` is deliberately NOT handled here — init.cts substitutes it
+ * separately, before calling this, because it is a config-level field with
+ * its own fallback (`''`), not a phase-derived one.
+ *
+ * When `phaseSlug` is a non-empty string, `{slug}` substitutes normally
+ * (unchanged from prior behavior). When it is empty or not a string (e.g.
+ * `null`, `undefined`, a number), the `{slug}` token is DROPPED — along with
+ * one adjacent separator character — rather than replaced with a placeholder
+ * word: a dropped token keeps the branch name honest about what it does not
+ * know, where a placeholder reads as a real (but wrong) name. The result is
+ * always a syntactically plausible git-ref fragment: no leading, trailing, or
+ * doubled separator, for both the shipped default template
+ * (`gsd/phase-{phase}-{slug}`) and a differently-shaped custom one (this
+ * field is user-configurable per docs/CONFIGURATION.md).
+ */
+function renderPhaseBranchName(template, phaseNumber, phaseSlug) {
+    const withPhase = template.replace('{phase}', normalizePhaseName(phaseNumber));
+    const slug = typeof phaseSlug === 'string' ? phaseSlug : '';
+    if (slug)
+        return withPhase.replace('{slug}', slug);
+    const at = withPhase.indexOf('{slug}');
+    if (at === -1)
+        return withPhase;
+    let before = withPhase.slice(0, at);
+    let after = withPhase.slice(at + '{slug}'.length);
+    // Drop exactly ONE adjacent separator — preferring the one immediately
+    // before the token — so `a-{slug}` and `{slug}-a` both degrade to `a`
+    // rather than leaving a dangling `a-` / `-a`.
+    if (before && BRANCH_TEMPLATE_SEP_RE.test(before[before.length - 1])) {
+        before = before.slice(0, -1);
+    }
+    else if (after && BRANCH_TEMPLATE_SEP_RE.test(after[0])) {
+        after = after.slice(1);
+    }
+    // Collapse any doubled separator the drop can leave behind (e.g. a
+    // `feature//{slug}` template dropping to `feature/`→`feature`), then trim
+    // a resulting leading/trailing separator — valid for the shipped default
+    // template AND any user-configured shape, not just the one this repo ships.
+    const joined = before + after;
+    const collapsed = joined.replace(BRANCH_TEMPLATE_SEP_RUN_RE, '$1').replace(BRANCH_TEMPLATE_EDGE_SEP_RE, '');
+    return collapsed || null;
+}
 function roadmapPhaseLookupSources(phaseNum) {
     const sources = [];
     const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
@@ -1176,6 +1544,18 @@ module.exports = {
     isPhaseContinuationSegment,
     BRACKET_PHASE_TOKEN_SOURCE,
     PHASE_HEADING_PREFIX_SRC,
+    BRACKET_ID_SRC,
+    BRACKET_PROJECT_CODE_SRC,
+    bracketMilestoneIntroSrcFor,
+    BRACKET_MILESTONE_INTRO_CAPTURING_SRC,
+    BRACKET_MILESTONE_NUMERIC_SRC,
+    BRACKET_DIR_PREFIX_SRC,
+    BASE_ANY_BRACKET_HEADING_PREFIX_SRC,
+    BASE_PHASE_LABEL_PREFIX_SRC,
+    PHASE_HEADING_BASELINE,
+    phaseHeadingPrefixSrcFor,
+    foldBracketId,
+    bracketQualifiedKey,
     stripProjectCodePrefix,
     normalizePhaseName,
     getMilestoneFromPhaseId,
@@ -1203,4 +1583,5 @@ module.exports = {
     stripConfiguredProjectCodePrefix,
     isForeignPrefixedPhaseQuery,
     roadmapPhaseLookupSources,
+    renderPhaseBranchName,
 };

package/gsd-core/bin/lib/phase-lifecycle.cjs

@@ -25,6 +25,8 @@ exports.locateProgressTable = locateProgressTable;
 exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
 exports.clampPercentFromFraction = clampPercentFromFraction;
 exports.clampPercent = clampPercent;
+exports.progressBarFilledCells = progressBarFilledCells;
+exports.renderProgressBar = renderProgressBar;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
@@ -140,3 +142,62 @@ function clampPercent(completed, total) {
         return 0;
     return clampPercentFromFraction(completed / total);
 }
+/**
+ * How many cells of a `width`-cell progress bar are filled for `percent`.
+ *
+ * #4294: the RENDER half's kernel — the counterpart of `clampPercentFromFraction`
+ * one layer down. That function owns `fraction -> integer percent`; this one
+ * owns `integer percent -> filled cells`, and is the single place that rounding
+ * is expressed. Five inline copies of the rounding carried it before this
+ * change — three in `commands.cts`, and one each in `gsd2-import.cts` and
+ * `formatProgressMachineSegment` here; the latter two used `/ 10` with the
+ * width already substituted (`pct` in `gsd2-import.cts`, `clamped` in the
+ * formatter). (#4294 counts SIX call sites because it counts
+ * `cmdStateUpdateProgress` and `syncCore` separately; #4231 had already routed
+ * both through `formatProgressMachineSegment` — as it does
+ * `applyPostSyncPreservation` — so by this branch's base they share one copy.)
+ * Every copy saturated: at width 10 that rounds to a full bar from 95 up, at
+ * width 20 from 98 up, so a project at 19/20 plans drew the same bar as a
+ * shipped one beside a number that said otherwise.
+ *
+ * Contract:
+ *   - A FULL bar is reserved for an actual 100. Below 100 the fill is held one
+ *     cell short of the width. This is the only departure from the old formula:
+ *     at width 10 exactly 95-99 move (10 -> 9), at width 20 exactly 98-99
+ *     (20 -> 19); every other percent in 0-100 rounds as before.
+ *   - `null` / `undefined` / non-finite renders an empty bar, matching the
+ *     `percent === null ? 0 : ...` guard the `progress` renderers already carried.
+ *   - Out-of-range input is clamped to 0-100 before rounding, so the count is
+ *     always within `[0, width]` and a `'░'.repeat(width - filled)` can never
+ *     be handed a negative count (the old inline form threw `RangeError` at
+ *     120%). A non-positive width yields 0.
+ *
+ * Callers wanting the glyph run call `renderProgressBar`; this is exported so
+ * the rounding rule can be pinned directly against the legacy curve.
+ */
+function progressBarFilledCells(percent, width) {
+    const cells = Number.isFinite(width) && width > 0 ? Math.floor(width) : 0;
+    if (cells === 0)
+        return 0;
+    if (typeof percent !== 'number' || !Number.isFinite(percent))
+        return 0;
+    const clamped = Math.max(0, Math.min(100, percent));
+    if (clamped >= 100)
+        return cells;
+    // Scale by the WIDTH, not by 100 — this is cells-from-percent, not the
+    // completion-ratio derivation lint-completion-ratio-drift.cjs guards.
+    const rounded = Math.round((clamped / 100) * cells);
+    return Math.min(rounded, cells - 1);
+}
+/**
+ * Render the glyph run of a `width`-cell progress bar for `percent` —
+ * `'█'` for each filled cell, `'░'` for the rest, always exactly `width`
+ * glyphs (an empty string for a non-positive width). Brackets, the printed
+ * percent and any suffix stay with the caller; the fill rule is
+ * `progressBarFilledCells` (#4294).
+ */
+function renderProgressBar(percent, width) {
+    const filled = progressBarFilledCells(percent, width);
+    const cells = Number.isFinite(width) && width > 0 ? Math.floor(width) : 0;
+    return '█'.repeat(filled) + '░'.repeat(cells - filled);
+}