@opengsd/gsd-core 1.13.0 → 1.14.0

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

@@ -884,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 —
@@ -933,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;
@@ -942,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.
@@ -981,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
@@ -1035,9 +1106,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 +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);
@@ -1445,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);
+}

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

@@ -45,10 +45,19 @@ const { normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, matchPhas
 const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal, getArchivedPhaseDirs, listMilestonePhaseDirs } = phaseLocatorMod;
+const { findPhaseInternal, getArchivedPhaseDirs, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap-parser.cjs is an export= CommonJS module
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { stripShippedMilestones, extractCurrentMilestone, currentMilestoneRawRanges, withPhaseSection, findMilestoneScopeHeadingLines } = roadmapParserMod;
+// #4129: the single owner of "count the ROADMAP's milestone Complete rows"
+// (pure computation, no I/O — no cycle on this path) for the intent-first
+// progress counters the phase-complete transaction passes downstream.
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
+const phaseLifecycleMod = require("./phase-lifecycle.cjs");
+const { deriveProgressFromRoadmap: deriveProgressFromRoadmapForIntent, clampPercent: clampPercentForIntent } = phaseLifecycleMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
@@ -287,25 +296,26 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
             const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
             const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
             baseExists = matchPhaseDirs(dirs, normalized).matches.length > 0;
-            const dirPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(normalized)}\\.(\\d+)`);
-            for (const dir of dirs) {
-                const match = dir.match(dirPattern);
-                if (match)
-                    decimalSet.add(parseInt(match[1], 10));
-            }
         }
         const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
         if (node_fs_1.default.existsSync(roadmapPath)) {
             try {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalized)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
-                let pm;
-                while ((pm = phasePattern.exec(roadmapContent)) !== null) {
-                    decimalSet.add(parseInt(pm[1], 10));
+                for (const n of scanExistingDecimalPhaseNumbers(phasesDir, roadmapContent, normalized)) {
+                    decimalSet.add(n);
                 }
             }
             catch {
-                /* ROADMAP.md read failure is non-fatal */
+                // ROADMAP.md read failure is non-fatal — fall back to the directory-only
+                // scan (empty rawContent) so on-disk decimal directories are still counted.
+                for (const n of scanExistingDecimalPhaseNumbers(phasesDir, '', normalized)) {
+                    decimalSet.add(n);
+                }
+            }
+        }
+        else {
+            for (const n of scanExistingDecimalPhaseNumbers(phasesDir, '', normalized)) {
+                decimalSet.add(n);
             }
         }
         const existingDecimals = Array.from(decimalSet)
@@ -1061,12 +1071,24 @@ function assertDescriptionPreservesMilestoneScope(cwd, description, command) {
  * before any directory does; milestone-scoping is wrong here because a number
  * used under any milestone on another branch is still taken).
  *
+ * #4225 — the horizon must track the ALLOCATION scope. When the allocation is
+ * workstream-scoped (`--ws`/`GSD_WORKSTREAM`, resolved into the env before
+ * dispatch), the sibling's copy of the SAME workstream is what carries that
+ * scope's independent numbering; the sibling's ROOT roadmap and phases/
+ * belong to a different numbering universe (docs/FEATURES.md §51 REQ-WS-01 —
+ * workstream state is isolated in `.planning/workstreams/{name}/`) and must
+ * not contribute. `planningDir(wt, ws)` reuses the canonical resolver, so the
+ * sibling scope matches the local scope's own resolution (env workstream plus
+ * env project segment) by construction; `ws === null` (no workstream active)
+ * keeps the #3849 root-scope horizon byte-for-byte.
+ *
  * Widen, never refuse: a missing `.planning/`, an unreadable sibling, a
  * non-git cwd, or an unavailable git binary each leave `used` untouched —
  * allocation then behaves exactly as it did before this horizon existed.
- * Sentinels reuse the canonical `isSentinelPhaseId`; the dir pattern is the
- * same one the on-disk scan uses, so decimal sub-phases (`411.1-foo`) are
- * correctly not integers.
+ * A sibling that simply lacks the active workstream's directory is the same
+ * fail-open case: it contributes nothing. Sentinels reuse the canonical
+ * `isSentinelPhaseId`; the dir pattern is the same one the on-disk scan uses,
+ * so decimal sub-phases (`411.1-foo`) are correctly not integers.
  */
 function collectSiblingWorktreePhaseNums(cwd, used) {
     let porcelain;
@@ -1084,6 +1106,13 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
     catch {
         return; // not a git repo / git unavailable — unchanged behavior
     }
+    // #4225: the env workstream, read once with planningDir's own discriminator
+    // (`?? null` = deliberately no workstream — never re-derived per sibling).
+    // A poisoned value would already have thrown at the local `planningDir(cwd)`
+    // call every allocator makes before reaching this horizon; the per-sibling
+    // try/catch below still keeps any resolution failure fail-open.
+    const ws = process.env['GSD_WORKSTREAM'] ?? null;
+    const siblingPlanningDir = (wt) => planningDir(wt, ws);
     const dirNumPattern = /^(?:[A-Z][A-Z0-9]*-)?(\d+)-/;
     // Same header shape the allocators scan locally (#1729 tag tolerance).
     const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
@@ -1094,7 +1123,7 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
         if (!wt || node_path_1.default.resolve(wt) === node_path_1.default.resolve(cwd))
             continue;
         try {
-            for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(wt, '.planning', 'phases'))) {
+            for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(siblingPlanningDir(wt), 'phases'))) {
                 const match = entry.match(dirNumPattern);
                 if (!match)
                     continue;
@@ -1104,10 +1133,10 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
             }
         }
         catch {
-            /* worktree has no .planning — normal, contributes nothing */
+            /* worktree has no .planning (or no copy of this scope) — normal, contributes nothing */
         }
         try {
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(wt, '.planning', 'ROADMAP.md'), 'utf-8');
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(siblingPlanningDir(wt), 'ROADMAP.md'), 'utf-8');
             let m;
             headerPattern.lastIndex = 0;
             while ((m = headerPattern.exec(content)) !== null) {
@@ -1117,7 +1146,7 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
             }
         }
         catch {
-            /* no roadmap in that worktree — normal, contributes nothing */
+            /* no roadmap in that worktree (or scope) — normal, contributes nothing */
         }
     }
 }
@@ -1343,7 +1372,63 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
     // found')` above, which terminates the process and never reaches here.
     publishStateContract(cwd);
 }
-function cmdPhaseInsert(cwd, afterPhase, description, raw) {
+// #4569: scans all three representations of an existing decimal sub-phase
+// under `base` — on-disk `phases/` directories, `### Phase BASE.N:` headings,
+// and `- [ ] Phase BASE.N:` roadmap SUMMARY CHECKLIST bullets. A bullet-only
+// roadmap with no heading yet and no on-disk directory yet must still be
+// seen, or an allocator can silently reallocate an already-used decimal
+// number. Shared by `cmdPhaseInsert`'s normalized-base scan and its
+// sibling-allocation parent-base scan so the two never drift apart.
+function scanExistingDecimalPhaseNumbers(phasesDir, rawContent, base) {
+    const decimalSet = new Set();
+    // #2245 audit: existsSync-guarded, mirroring cmdPhaseNextDecimal's identical
+    // scan above — a missing phasesDir (no decimal sub-phases yet) is the
+    // expected, silent case (empty decimalSet). A readdirSync failure once the
+    // dir is confirmed to EXIST is a genuine anomaly; swallowing it used to let
+    // `phase insert` proceed with an incomplete decimalSet and risk writing a
+    // decimal phase number that collides with an existing on-disk directory
+    // the scan simply never saw — surfaced loud instead, like the sibling.
+    //
+    // #4634 (lint-phase-enumeration-drift): routed through the canonical
+    // PHYSICAL-set owner (`listAllPhaseDirs`, phase-locator.cts) instead of a
+    // hand-rolled `readdirSync`. This scan — like its sibling `cmdPhaseNextDecimal`
+    // and its caller `cmdPhaseInsert` (both exempted in the drift guard for the
+    // same reason) — must see EVERY on-disk decimal sub-phase directory
+    // regardless of the current milestone window, so `listMilestonePhaseDirs`
+    // (windowed) is the wrong owner here; `includeSentinels: true` preserves this
+    // function's pre-existing behavior of never sentinel-filtering (the decimal
+    // regex below only ever matches `base.N`-shaped names, so sentinel inclusion
+    // is a no-op either way).
+    if (node_fs_1.default.existsSync(phasesDir)) {
+        const { value: dirs, scope } = listAllPhaseDirs(phasesDir, { includeSentinels: true });
+        if (scope === SCOPE.UNREADABLE) {
+            // The dir EXISTS but could not be read (EACCES/EIO) — a genuine anomaly,
+            // not the expected empty-decimalSet case above. Surfaced loud, matching
+            // this function's pre-migration `readdirSync` catch: swallowing it would
+            // let `phase insert` proceed with an incomplete decimalSet and collide
+            // with an existing on-disk decimal directory the scan never saw.
+            error(`Failed to scan phase directories for existing decimal phases: unable to read ${phasesDir}`);
+        }
+        const decimalPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(base)}\\.(\\d+)`);
+        for (const dir of dirs) {
+            const dm = dir.match(decimalPattern);
+            if (dm)
+                decimalSet.add(parseInt(dm[1], 10));
+        }
+    }
+    const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(base)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
+    let rmMatch;
+    while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
+        decimalSet.add(parseInt(rmMatch[1], 10));
+    }
+    const checklistDecimalPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${phaseMarkdownRegexSource(base)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'gi');
+    let clMatch;
+    while ((clMatch = checklistDecimalPattern.exec(rawContent)) !== null) {
+        decimalSet.add(parseInt(clMatch[1], 10));
+    }
+    return decimalSet;
+}
+function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested') {
     if (!afterPhase || !description) {
         error('after-phase and description required for phase insert');
     }
@@ -1373,43 +1458,20 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         }
         const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
         const normalizedBase = normalizePhaseName(afterPhase);
-        const decimalSet = new Set();
-        // #2245 audit: existsSync-guarded, mirroring cmdPhaseNextDecimal's identical
-        // scan above — a missing phasesDir (no decimal sub-phases yet) is the
-        // expected, silent case (empty decimalSet). A readdirSync failure once the
-        // dir is confirmed to EXIST is a genuine anomaly; swallowing it used to let
-        // `phase insert` proceed with an incomplete decimalSet and risk writing a
-        // decimal phase number that collides with an existing on-disk directory
-        // the scan simply never saw — surfaced loud instead, like the sibling.
-        if (node_fs_1.default.existsSync(phasesDir)) {
-            // Initialized (not just declared) so TS's definite-assignment check is
-            // satisfied without relying on control-flow narrowing through error()'s
-            // `never` return, which TS does not propagate through a destructured
-            // module-property function reference — error() still halts the process
-            // before `dirs` below is ever computed from this placeholder value.
-            let entries = [];
-            try {
-                entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                error(`Failed to scan phase directories for existing decimal phases: ${msg}`);
-            }
-            const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-            const decimalPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(normalizedBase)}\\.(\\d+)`);
-            for (const dir of dirs) {
-                const dm = dir.match(decimalPattern);
-                if (dm)
-                    decimalSet.add(parseInt(dm[1], 10));
-            }
-        }
-        const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalizedBase)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
-        let rmMatch;
-        while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
-            decimalSet.add(parseInt(rmMatch[1], 10));
-        }
+        const decimalSet = scanExistingDecimalPhaseNumbers(phasesDir, rawContent, normalizedBase);
         const nextDecimal = decimalSet.size === 0 ? 1 : Math.max(...decimalSet) + 1;
-        const _decimalPhase = `${normalizedBase}.${nextDecimal}`;
+        let _decimalPhase = `${normalizedBase}.${nextDecimal}`;
+        // #4569: sibling allocation joins afterPhase's PARENT level instead of nesting
+        // one level deeper under afterPhase itself. A top-level phase (no existing
+        // decimal segment) has no sibling level to join; nested is the only sensible
+        // allocation, so we silently fall back for that case.
+        const lastDotIndex = normalizedBase.lastIndexOf('.');
+        if (allocation === 'sibling' && lastDotIndex !== -1) {
+            const parentBase = normalizedBase.slice(0, lastDotIndex);
+            const siblingDecimalSet = scanExistingDecimalPhaseNumbers(phasesDir, rawContent, parentBase);
+            const siblingNextDecimal = siblingDecimalSet.size === 0 ? 1 : Math.max(...siblingDecimalSet) + 1;
+            _decimalPhase = `${parentBase}.${siblingNextDecimal}`;
+        }
         const insertConfig = loadConfig(cwd);
         const projectCode = insertConfig.project_code || '';
         const pfx = projectCode ? `${projectCode}-` : '';
@@ -3022,7 +3084,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         // #2617: pass the project's runtime so the blocked-completion error below
         // suggests the command surface this runtime actually installs
         // ($gsd-… on Codex) rather than a hard-coded Claude-style string.
-        const verificationStatus = readVerificationStatus(phaseFullDir, { runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd) });
+        const verificationStatus = readVerificationStatus(phaseFullDir, {
+            runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd),
+            convention: resolvePhaseIdConvention(cwd),
+        });
         // #3057 B3: the staleness check inside readVerificationStatus can itself
         // fail (fs / scanPhasePlans / clock error), in which case `status` above
         // was routed as if nothing were stale (unchanged fail-open routing) — but
@@ -3767,14 +3832,53 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 const fmBody = frontmatterMod.stripFrontmatter(stateContent);
                 const bodyHasPhaseField = stateExtractField(fmBody, 'Current Phase') != null ||
                     stateExtractField(fmBody, 'Phase') != null;
-                const authoritativeFm = nextPhaseDisplayName
-                    ? bodyHasPhaseField || !nextPhaseNum
-                        ? { current_phase_name: nextPhaseDisplayName }
-                        : {
-                            current_phase: String(nextPhaseNum),
-                            current_phase_name: nextPhaseDisplayName,
+                // #4129: the POST-completion progress counters, derived from the very
+                // ROADMAP this transaction just mutated (still in memory — it hits disk
+                // only at writePlanningFileSet, AFTER this content was assembled).
+                // buildStateFrontmatter's disk scan inside syncAndPreserveStateMd
+                // reads the PRE-completion ROADMAP (and any stale-dated sibling
+                // verification), so without this intent the persisted counter failed
+                // to increment on the completing phase's own transaction. Routed
+                // through the #2736 authoritativeFm seam's object direction: the
+                // pre-preservation merge makes it the derived truth the ratchet
+                // compares, and the post-preservation re-assert (completedOnlyRaise)
+                // is a floor no preservation branch can drop below. clampPercent is
+                // completePhaseCore's own percent formula (state-transition.cts),
+                // reused so the frontmatter and the body `Progress:` line agree.
+                const postCompletionRoadmapScope = roadmapContent !== null
+                    ? extractCurrentMilestone(roadmapContent, cwd)
+                    : null;
+                const postCompletionRoadmapProgress = postCompletionRoadmapScope !== null
+                    ? deriveProgressFromRoadmapForIntent(postCompletionRoadmapScope)
+                    : null;
+                const authoritativeProgress = postCompletionRoadmapProgress && postCompletionRoadmapProgress.completedPhases !== null
+                    ? postCompletionRoadmapProgress.totalPhases !== null && postCompletionRoadmapProgress.totalPhases > 0
+                        ? {
+                            completed_phases: postCompletionRoadmapProgress.completedPhases,
+                            percent: clampPercentForIntent(postCompletionRoadmapProgress.completedPhases, postCompletionRoadmapProgress.totalPhases),
                         }
+                        : { completed_phases: postCompletionRoadmapProgress.completedPhases }
                     : undefined;
+                const authoritativeFm = authoritativeProgress
+                    ? {
+                        ...(nextPhaseDisplayName
+                            ? bodyHasPhaseField || !nextPhaseNum
+                                ? { current_phase_name: nextPhaseDisplayName }
+                                : {
+                                    current_phase: String(nextPhaseNum),
+                                    current_phase_name: nextPhaseDisplayName,
+                                }
+                            : {}),
+                        progress: authoritativeProgress,
+                    }
+                    : nextPhaseDisplayName
+                        ? bodyHasPhaseField || !nextPhaseNum
+                            ? { current_phase_name: nextPhaseDisplayName }
+                            : {
+                                current_phase: String(nextPhaseNum),
+                                current_phase_name: nextPhaseDisplayName,
+                            }
+                        : undefined;
                 // ADR-3408 §8.3 / #3469: this deliberately bypasses
                 // readModifyWriteStateMd (STATE.md is committed atomically with
                 // ROADMAP/REQUIREMENTS), so it calls the single write-seam