@opengsd/gsd-core 1.13.0 → 1.15.0

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

@@ -59,6 +59,20 @@ const OPTIONAL_PHASE_TAG_SOURCE = '(?:\\s*\\([^)\\n]{0,200}\\))?';
 // (scripts/lint-phase-id-drift.cjs) fails CI if a literal re-derivation is
 // introduced outside this module without a `// phase-id-owner:` justification.
 const PHASE_NUMBER_TOKEN_SOURCE = '\\d+[A-Z]?(?:\\.\\d+)*';
+// #4764: a phase REFERENCE in depends-on PROSE — the token in context, directly
+// following "Phase"/"Phases", with bare-token list continuation ("Phases 1 and 2",
+// "Phase 1, 2, and 3", "Phase 1-3"). Built HERE, beside the token grammar it is
+// anchored on, because two readers consume Depends-on prose (init.manager's
+// dep_phases and planning-inspect's dependencies) and re-deriving the anchored
+// form at each would drift exactly the way PHASE_NUMBER_TOKEN_SOURCE's own
+// anti-divergence rule exists to prevent. A bare digit run is the right shape
+// test for a phase id and the WRONG test for a reference: the whole-field
+// scrape this replaces pulled calendar dates ("2026-09-14" → 2026/09/14), git
+// shas ("8bf403100d" → 8b/403100d/…) and ledger ids (WINDOWS #1843) in as
+// dependencies. The `-` separator deliberately extracts range ENDPOINTS only
+// ("Phase 1-3" → 1, 3) — the pre-#4764 behavior; interior enumeration stays
+// out (a range's middle is not written as a reference).
+const PHASE_DEP_REF_SOURCE = `\\bphases?\\s+(${PHASE_NUMBER_TOKEN_SOURCE}(?:(?:\\s*,\\s*(?:and\\s+)?|\\s+and\\s+|\\s*&\\s*|\\s+(?:to|through)\\s+|\\s*-\\s*)${PHASE_NUMBER_TOKEN_SOURCE})*)`;
 // #2528 review: the CASE-FLEXIBLE renderings of the two sources above, for call
 // sites that scan directory names (where a project code or a variant suffix may
 // legitimately be lowercase) and therefore cannot use a case-sensitive class.
@@ -308,6 +322,30 @@ function phaseHeadingPrefixSrcFor(baseline, convention, capturing = false) {
     const bracketAlt = `\\[${id}\\][ \\t]*(?:Phase\\s+|(?=\\d))`;
     return `(?:${bracketAlt}|${base})`;
 }
+/**
+ * The single owner of the "scan a whole document for every phase heading"
+ * pattern (#4865 / ADR-4910 §8) — anchored (`^ {0,3}#{2,4}`, so indentation up
+ * to 3 spaces is tolerated but a heading is never matched mid-line), global,
+ * multiline, convention-aware via `phaseHeadingPrefixSrcFor`. Returns the
+ * capture-group layout alongside the regex so a caller never re-derives the
+ * bracket-convention offset (`const G = convention === 'bracket' ? 1 : 0`)
+ * itself — a second, independently-computed offset is exactly the kind of
+ * drift `scripts/lint-phase-id-drift.cjs` exists to catch structurally, not
+ * just by pattern text.
+ *
+ * Distinct from `buildPhaseHeadingRegex` (`src/roadmap.cts`), which searches
+ * for ONE already-known phase number (anchored `^`, no `g` flag, phase number
+ * interpolated literally) — a different contract for a different question.
+ * This function answers "which phases exist in this content", not "does this
+ * specific phase exist".
+ */
+function buildPhaseHeadingScanRegex(baseline, convention) {
+    const bracketGroup = convention === 'bracket' ? 1 : null;
+    const phaseNumGroup = bracketGroup ? 2 : 1;
+    const phaseNameGroup = phaseNumGroup + 1;
+    const regex = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(baseline, convention, true)}(${PHASE_NUMBER_TOKEN_SOURCE})${OPTIONAL_PHASE_TAG_SOURCE}:\\s*([^\\n]+)`, 'gim');
+    return { regex, bracketGroup, phaseNumGroup, phaseNameGroup };
+}
 function stripProjectCodePrefix(value, caseInsensitive = true) {
     const input = String(value);
     const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
@@ -451,10 +489,27 @@ function parsePhaseId(input) {
     // tokens unchanged.
     throw new Error(`parsePhaseId: not a bracket phase id: ${JSON.stringify(input)}`);
 }
+function renderMilestoneId(id) {
+    return `[${id.project}.${id.milestone}]`;
+}
 function renderPhaseId(id) {
     const sub = id.subphase ? `.${id.subphase}` : '';
     const plan = id.plan ? `-${id.plan}` : '';
-    return `[${id.project}.${id.milestone}] ${id.phase}${sub}${plan}`;
+    return `${renderMilestoneId(id)} ${id.phase}${sub}${plan}`;
+}
+/** Whether a legacy phase token has a lossless spelling in bracket display grammar. */
+function isBracketPhaseTokenRepresentable(token) {
+    try {
+        const bracketToken = normalizePhaseName(token)
+            .split('.')
+            .map((segment) => segment.padStart(2, '0'))
+            .join('.');
+        parsePhaseId(`[GSD.00] ${bracketToken}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 // PhaseId is a structural type: nothing forces a caller through parsePhaseId,
 // so toDir cannot trust project/milestone/phase/subphase are already
@@ -884,19 +939,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 —
@@ -933,7 +1011,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;
@@ -942,6 +1057,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 expandPhaseTokenCandidates(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.
@@ -949,9 +1080,19 @@ function isPhaseArtifact(fileName, phaseDirName) {
     // sub-phase (`03A`, `03.1`) has no meaningful de-padded form and is left
     // alone, so this only ever ADDS a reading and can never drop one.
     const depad = (t) => (/^\d+$/.test(t) ? String(Number(t)) : t);
-    const candidates = new Set(rawCandidates
+    return new Set(rawCandidates
         .flatMap(t => [t, normalizePhaseName(t), depad(t)])
         .map(t => t.toUpperCase()));
+}
+function matchesPhaseTokenCandidates(fileName, rawCandidates) {
+    const candidates = expandPhaseTokenCandidates(rawCandidates);
+    if (matchPhaseTokenCandidateSpan(fileName, candidates) !== null)
+        return true;
+    // FIX 2: token-less filename (bare "VERIFICATION.md"/"UAT.md") — containment
+    // in this phase's own directory listing is sufficient.
+    return derivePhaseTokenSegments(fileName).tokenSegments.length === 0;
+}
+function matchPhaseTokenCandidateSpan(fileName, candidates) {
     const fileUpper = fileName.toUpperCase();
     for (const candidate of candidates) {
         // A dotted sub-phase segment (e.g. `01.1-CONTEXT.md`) is a legitimate
@@ -977,16 +1118,43 @@ function isPhaseArtifact(fileName, phaseDirName) {
         if (fileUpper.startsWith(`${candidate}-`) ||
             fileUpper.startsWith(`${candidate}.`) ||
             fileUpper.startsWith(`${candidate}_`))
-            return true;
+            return { start: 0, end: candidate.length };
     }
-    // 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 null;
+}
+/**
+ * Return the exact leading token span by which the phase-artifact reader
+ * attributes a phase-qualified filename to `phaseDirName`.
+ *
+ * Membership is first decided by `isPhaseArtifact`, then the span is selected
+ * from the same padded, de-padded, case-folded candidate set used by
+ * `matchesPhaseTokenCandidates`. Token-less containment fallbacks return null
+ * because there is no phase token in the filename to replace.
+ */
+function phaseArtifactTokenSpan(fileName, phaseDirName, convention) {
+    if (!isPhaseArtifact(fileName, phaseDirName, convention))
+        return null;
+    if (convention === 'bracket') {
+        const bracketDir = phaseDirName.match(BRACKET_DIR_TOKEN_RE);
+        if (bracketDir) {
+            const qualified = fileName.match(BRACKET_QUALIFIED_KEY_RE);
+            if (qualified && bracketQualifiedKey(fileName, convention) !== null) {
+                return { start: 0, end: qualified[0].length };
+            }
+            const bracketCandidates = expandPhaseTokenCandidates([bracketDir[1]]);
+            return matchPhaseTokenCandidateSpan(fileName, bracketCandidates);
+        }
+    }
+    const { tokenSegments } = derivePhaseTokenSegments(phaseDirName);
+    if (tokenSegments.length === 0)
+        return null;
+    const literalToken = extractPhaseToken(phaseDirName);
+    const strippedDir = stripProjectCodePrefix(phaseDirName);
+    const strippedToken = strippedDir !== phaseDirName ? extractPhaseToken(strippedDir) : literalToken;
+    const leadingRunMatch = strippedDir.match(LEADING_DIGIT_RUN_RE);
+    const rawCandidates = [literalToken, strippedToken, leadingRunMatch?.[1]].filter((token) => Boolean(token));
+    const candidates = expandPhaseTokenCandidates(rawCandidates);
+    return matchPhaseTokenCandidateSpan(fileName, candidates);
 }
 /**
  * #3511: scope `fileNames` to the subset that passes
@@ -1035,9 +1203,19 @@ 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.
@@ -1386,6 +1564,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);
@@ -1400,6 +1635,7 @@ module.exports = {
     OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
     OPTIONAL_PHASE_TAG_SOURCE,
     PHASE_NUMBER_TOKEN_SOURCE,
+    PHASE_DEP_REF_SOURCE,
     CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE,
     CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE,
     PHASE_CONTINUATION_SEGMENT_SOURCE,
@@ -1416,6 +1652,7 @@ module.exports = {
     BASE_PHASE_LABEL_PREFIX_SRC,
     PHASE_HEADING_BASELINE,
     phaseHeadingPrefixSrcFor,
+    buildPhaseHeadingScanRegex,
     foldBracketId,
     bracketQualifiedKey,
     stripProjectCodePrefix,
@@ -1423,7 +1660,9 @@ module.exports = {
     getMilestoneFromPhaseId,
     getPhaseDirFromPhaseId,
     parsePhaseId,
+    renderMilestoneId,
     renderPhaseId,
+    isBracketPhaseTokenRepresentable,
     toDir,
     SENTINEL_RANGES,
     isSentinelPhaseId,
@@ -1433,6 +1672,7 @@ module.exports = {
     comparePhaseNum,
     extractPhaseToken,
     isPhaseArtifact,
+    phaseArtifactTokenSpan,
     scopeToPhase,
     phaseTokenMatches,
     matchPhaseDirs,
@@ -1445,4 +1685,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);
+}

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

@@ -35,7 +35,7 @@ const frontmatterModule = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatterModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planDependencyGraphModule = require("./plan-dependency-graph.cjs");
-const { computeHaltPropagation, buildSummaryFileIndex, isSummaryFileHalted } = planDependencyGraphModule;
+const { computeHaltPropagation, buildSummaryFileIndex, isSummaryFileHalted, isSummaryFileBlocked } = planDependencyGraphModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserModule = require("./roadmap-parser.cjs");
 const { getMilestonePhaseFilter } = roadmapParserModule;
@@ -146,13 +146,15 @@ function listArchiveVersionDirs(cwd, wsOverride) {
     }
     return out;
 }
-function searchPhaseInDir(baseDir, relBase, normalized) {
+function searchPhaseInDir(baseDir, relBase, normalized, convention) {
     try {
         const dirs = readSubdirectories(baseDir, true);
         // #2528: canonical two-pass selection (exact token match, then the
         // bare-integer leading-digit-run fallback) shared with the find-phase and
         // phase-plan-index scans — see phase-id.cts::matchPhaseDirs.
-        const { matches, usedBareFallback } = matchPhaseDirs(dirs, normalized);
+        // #4801: the convention is threaded (optional) so bracket-convention
+        // consumers get exact token matching here too.
+        const { matches, usedBareFallback } = matchPhaseDirs(dirs, normalized, convention);
         if (matches.length === 0)
             return null;
         // #2237: fail loud when multiple directories match the same bare phase
@@ -176,6 +178,7 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
                 halted_plans: [],
                 blocked_by: {},
                 runnable_plans: [],
+                ready_plans: [],
             };
         }
         const match = matches[0];
@@ -208,12 +211,19 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
         const planIds = plans.map(p => p.replace('-PLAN.md', '').replace('PLAN.md', ''));
         const planIdByLower = new Map(planIds.map(id => [id.toLowerCase(), id]));
         const canonicalToPlanId = new Map(plans.map((p, i) => [extractCanonicalPlanId(p).toLowerCase(), planIds[i]]));
+        // #4628: raw depends_on per plan, so readiness can fail closed on a
+        // DROPPED edge (a dep token that resolves to nothing carries no evidence)
+        // instead of the resolution silently shrinking the dependency list.
+        const rawDeps = plans.map((p) => parsePlanDependsOn(phaseDir, p));
+        // #4628: completion evidence excludes status:blocked summaries (#3345) —
+        // a failure record is not completion, matching cmdPhasePlanIndex's count.
+        const completionEvidence = buildSummaryFileIndex(summaries.filter((f) => !isSummaryFileBlocked(node_path_1.default.join(phaseDir, f))), extractCanonicalPlanId);
         const haltNodes = plans.map((p, i) => {
             const planId = planIds[i];
             const canonical = extractCanonicalPlanId(p);
             const summaryFile = summaryFileByPlanId.get(planId) ?? summaryFileByPlanId.get(canonical);
             const halted = summaryFile !== undefined && isSummaryFileHalted(node_path_1.default.join(phaseDir, summaryFile));
-            const resolvedDependsOn = parsePlanDependsOn(phaseDir, p)
+            const resolvedDependsOn = rawDeps[i]
                 .map((dep) => {
                 const lower = dep.toLowerCase();
                 return planIdByLower.get(lower) ?? canonicalToPlanId.get(lower) ?? null;
@@ -226,6 +236,7 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
         const incompletePlanSet = new Set(incompletePlans);
         const blockedByFiles = {};
         const runnablePlans = [];
+        const readyPlans = [];
         for (let i = 0; i < plans.length; i++) {
             const p = plans[i];
             if (!incompletePlanSet.has(p))
@@ -233,10 +244,16 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
             const causes = blockedBy.get(planIds[i]) ?? [];
             if (causes.length > 0) {
                 blockedByFiles[p] = causes;
+                continue;
             }
-            else {
-                runnablePlans.push(p);
-            }
+            runnablePlans.push(p);
+            // #4628: DAG-ready on top of runnable — every dependency must have
+            // completion evidence (a matching, non-blocked SUMMARY) and no dropped
+            // edge: both readers of this contract fail closed identically.
+            const depsComplete = rawDeps[i].length === haltNodes[i].resolvedDependsOn.length &&
+                haltNodes[i].resolvedDependsOn.every((dep) => completionEvidence.has(dep));
+            if (depsComplete)
+                readyPlans.push(p);
         }
         return {
             found: true,
@@ -259,19 +276,21 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
             halted_plans: haltedPlans,
             blocked_by: blockedByFiles,
             runnable_plans: runnablePlans,
+            ready_plans: readyPlans,
         };
     }
     catch {
         return null;
     }
 }
-function findPhaseInternal(cwd, phase) {
+function findPhaseInternal(cwd, phase, convention) {
     if (!phase)
         return null;
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
     const normalized = normalizePhaseName(phase);
     const relPhasesDir = toPosixPath(node_path_1.default.relative(cwd, phasesDir));
-    const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized);
+    // #4801: convention threaded through to the matcher (see searchPhaseInDir).
+    const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized, convention);
     if (current)
         return current;
     // #2855: scope the archived-milestone fallback to the SAME workstream as the
@@ -285,7 +304,7 @@ function findPhaseInternal(cwd, phase) {
     // getArchivedPhaseDirs via listArchiveVersionDirs (see its doc comment).
     for (const { version, archivePath } of listArchiveVersionDirs(cwd)) {
         const relBase = toPosixPath(node_path_1.default.relative(cwd, archivePath));
-        const result = searchPhaseInDir(archivePath, relBase, normalized);
+        const result = searchPhaseInDir(archivePath, relBase, normalized, convention);
         if (result) {
             result.archived = version;
             return result;