@opengsd/gsd-core 1.19.0 → 1.20.0

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

@@ -15,6 +15,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+const phase_entry_grammar_cjs_1 = require("./phase-entry-grammar.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- io.cjs is an export= CommonJS module
 const io = require("./io.cjs");
@@ -33,6 +34,8 @@ const roadmapParser = require("./roadmap-parser.cjs");
 const coreUtils = require("./core-utils.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseId = require("./phase-id.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id-display.cjs is an export= CommonJS module
+const phaseIdDisplayMod = require("./phase-id-display.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- worktree-safety.cjs is an export= CommonJS module
 const worktreeSafety = require("./worktree-safety.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
@@ -93,10 +96,11 @@ const { harvestPriorVerifyCommands } = verifyCommandGrounding;
 const { output, error, ERROR_REASON, formatDiagnosticToken } = io;
 const { loadConfig, loadConfigResolved } = configLoader;
 const { resolveModelInternal, resolveGranularityInternal, assertValidGranularityOverride } = modelResolver;
-const { findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocator;
+const { phaseDirectoryOptions, findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs, } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { comparePhaseNum, normalizePhaseName, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, PHASE_DEP_REF_SOURCE, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase, renderPhaseBranchName, parsePhaseId, renderPhaseId, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, buildPhaseHeadingScanRegex, } = phaseId;
+const { comparePhaseNum, phaseDirectoryName, customPhaseQuery, customDirectoryOwner, phaseScanTokenSource, phaseKeyFromToken, phaseDirectoryContext, normalizePhaseName, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, PHASE_DEP_REF_SOURCE, extractPhaseDependencyTokens, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase, renderPhaseBranchName, parsePhaseId, renderPhaseId, bracketQualifiedKey, phaseHeadingPrefixSrcFor, parsePhaseChecklistLine, PHASE_HEADING_BASELINE, buildPhaseHeadingScanRegex, } = phaseId;
+const { phaseToken } = phaseIdDisplayMod;
 const { pruneOrphanedWorktrees } = worktreeSafety;
 const { planningPaths, planningDir, planningRoot, todosDir, listAvailableWorkstreams, peekActiveWorkstream, resolveEnvWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, findContextMdIn, findPhaseSpecIn, resolvePhaseIdConvention, worktreesOptedOut, } = planningWorkspace;
 const { extractFrontmatter, frontmatterBlock } = frontmatterMod;
@@ -134,8 +138,8 @@ function roadmapPhaseMatchesExactPrefix(roadmapPhase, phase) {
 // #2104: shared helpers that wrap findPhaseInternal / getRoadmapPhaseInternal
 // with the #2056 foreign-prefix guard, so every init command gets the same
 // protection without duplicating the guard logic at each call site.
-function guardedFindPhase(cwd, phase, projectCode) {
-    let phaseInfo = findPhaseInternal(cwd, phase);
+function guardedFindPhase(cwd, phase, projectCode, phaseNaming) {
+    let phaseInfo = findPhaseInternal(cwd, phase, undefined, phaseDirectoryOptions(cwd, { phase_naming: phaseNaming, project_code: projectCode }));
     if (isForeignPrefixedPhaseQuery(phase, projectCode) && !phaseInfoMatchesExactPrefix(phaseInfo, phase)) {
         phaseInfo = null;
     }
@@ -902,7 +906,7 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
         error('phase required for init execute-phase');
     }
     const config = loadConfig(cwd);
-    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code, config.phase_naming);
     // #3216: getMilestoneInfo now returns a ScopedResult — `.value` carries the
     // MilestoneInfo (or null on any non-COMPLETE scope). NOT display-only: when
     // `branching_strategy === 'milestone'`, `milestone['version']`/`['name']`
@@ -1077,7 +1081,7 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     }
     const config = loadConfig(cwd);
     // #2056/#2104: foreign-prefixed queries must not collapse to numeric phases.
-    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code, config.phase_naming);
     const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     phaseInfo = applyRoadmapFallback(phaseInfo, roadmapPhase, (rp) => {
         const phaseName = rp['phase_name'];
@@ -1111,12 +1115,14 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     const phaseNamePlan = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     const rawProjectCodePlan = config.project_code || '';
     let expectedPhaseDirPlan = null;
-    if (!phaseDirPlan && phaseNumberPlan && phaseNamePlan) {
+    const namingContextPlan = phaseDirectoryContext(config);
+    const customNamingPlan = customPhaseQuery(phase, namingContextPlan) !== null;
+    if ((!phaseDirPlan || customNamingPlan) && phaseNumberPlan && phaseNamePlan) {
         const paddedNum = normalizePhaseName(phaseNumberPlan);
-        const slug = (generateSlugInternal(phaseNamePlan) || '').substring(0, 60);
+        const expectedName = roadmapPhase?.['phase_name'] || phaseNamePlan;
+        const slug = (generateSlugInternal(expectedName) || '').substring(0, 60);
         if (slug) {
-            const prefix = rawProjectCodePlan ? `${rawProjectCodePlan}-` : '';
-            const dirName = `${prefix}${paddedNum}-${slug}`;
+            const dirName = phaseDirectoryName(customPhaseQuery(phaseNumberPlan, namingContextPlan) ? phaseNumberPlan : paddedNum, slug, rawProjectCodePlan);
             // #2376: absolute — see comment on phase_dir below.
             expectedPhaseDirPlan = toPosixPath(node_path_1.default.join(planningPaths(cwd).phases, dirName));
         }
@@ -1707,7 +1713,7 @@ function cmdInitVerifyWork(cwd, phase, raw) {
     }
     const config = loadConfig(cwd);
     const _slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
-    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code, config.phase_naming);
     const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     phaseInfo = applyRoadmapFallback(phaseInfo, roadmapPhase, (rp) => {
         const phaseName = rp['phase_name'];
@@ -1814,7 +1820,7 @@ function cmdInitVerifyWork(cwd, phase, raw) {
  */
 function cmdInitCodeReview(cwd, phase, raw, options = {}) {
     const config = loadConfig(cwd);
-    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code, config.phase_naming);
     const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     phaseInfo = applyRoadmapFallback(phaseInfo, roadmapPhase, (rp) => {
         const rpName = rp['phase_name'];
@@ -1880,7 +1886,7 @@ function cmdInitCodeReview(cwd, phase, raw, options = {}) {
  */
 function cmdInitReview(cwd, phase, raw, options = {}) {
     const config = loadConfig(cwd);
-    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code, config.phase_naming);
     const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     phaseInfo = applyRoadmapFallback(phaseInfo, roadmapPhase, (rp) => ({
         found: true,
@@ -1939,7 +1945,7 @@ function cmdInitReview(cwd, phase, raw, options = {}) {
  */
 function cmdInitDiscussPhaseAssumptions(cwd, phase, raw, options = {}) {
     const config = loadConfig(cwd);
-    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code, config.phase_naming);
     const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     phaseInfo = applyRoadmapFallback(phaseInfo, roadmapPhase, (rp) => {
         const rpName = rp['phase_name'];
@@ -1995,7 +2001,7 @@ function cmdInitDiscussPhaseAssumptions(cwd, phase, raw, options = {}) {
 }
 function cmdInitPhaseOp(cwd, phase, raw) {
     const config = loadConfig(cwd);
-    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code, config.phase_naming);
     // #2237: surface ambiguous phase-directory collisions instead of silently
     // taking the first match when unrelated projects share a .planning/phases/ tree.
     if (phaseInfo?.['ambiguous_matches']) {
@@ -2598,37 +2604,37 @@ function cmdInitManager(cwd, raw) {
     }
     const rawContent = node_fs_1.default.readFileSync(paths.roadmap, 'utf-8');
     const content = extractCurrentMilestone(rawContent, cwd);
+    const directoryContext = phaseDirectoryOptions(cwd, config, rawContent);
     // #3185 (ADR-3180 Decision 1): "which phase directories belong to the
     // CURRENT milestone" is the scoped question listMilestonePhaseDirs owns —
     // routed through it instead of a hand-rolled readdirSync + a separate
     // getMilestonePhaseFilter window check (which also never excluded
     // sentinels, unlike the owner).
     const _checkboxStates = new Map();
-    // #4982: anchored (`^`, `m`) so the phase label must be the FIRST thing
-    // after the checkbox (tolerating only an optional `**` bold marker) —
-    // the prior unanchored `\s*.*` let the greedy `.*` bind to the LAST
-    // "Phase N" mentioned anywhere in the line's prose instead of the line's
-    // own phase. First-match-wins (`if (!_checkboxStates.has(...))` below)
+    // #4982: parsePhaseChecklistLine is line-anchored, so the phase label must
+    // be the FIRST thing after the checkbox (tolerating only an optional `**`
+    // bold marker), and a later "Phase N" in the line's prose cannot bind the
+    // checkbox. First-match-wins (`if (!_checkboxStates.has(...))` below)
     // additionally guards against a later anchored line (e.g. a per-plan
     // sub-entry self-titled "Phase N ...") overwriting an already-recorded
-    // phase's own (first) checkbox — anchoring alone does not fully close
-    // that "last-match-wins" composition defect.
-    const _cbPattern = new RegExp(`^[ \\t]*-[ \\t]*\\[(x| )\\][ \\t]*(?:\\*\\*)?${phaseHeadingPrefix}(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gim');
-    let _cbMatch;
-    while ((_cbMatch = _cbPattern.exec(content)) !== null) {
-        const phaseGroup = capturesBracketId ? 3 : 2;
-        const _cbKey = _cbMatch[phaseGroup];
-        if (!_checkboxStates.has(_cbKey)) {
-            _checkboxStates.set(_cbKey, _cbMatch[1].toLowerCase() === 'x');
+    // phase's own (first) checkbox; anchoring alone does not fully close that
+    // "last-match-wins" composition defect.
+    for (const line of content.split(/\r?\n/)) {
+        const checkbox = parsePhaseChecklistLine(line, phaseIdConvention, directoryContext);
+        if (checkbox && !_checkboxStates.has(checkbox.phaseToken)) {
+            _checkboxStates.set(checkbox.phaseToken, checkbox.checked);
         }
     }
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefix}(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
+    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefix}(${phaseScanTokenSource(directoryContext)})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
     const phases = [];
+    const bracketIdsByPhaseNumber = new Map();
     let match;
     while ((match = phasePattern.exec(content)) !== null) {
         const bracketId = capturesBracketId ? match[1] : undefined;
         const phaseNum = capturesBracketId ? match[2] : match[1];
+        if (bracketId)
+            bracketIdsByPhaseNumber.set(phaseNum, bracketId);
         const phaseName = (capturesBracketId ? match[3] : match[2])
             .replace(/\(INSERTED\)/i, '')
             .trim();
@@ -2644,7 +2650,7 @@ function cmdInitManager(cwd, raw) {
         }
         const sectionStart = match.index;
         const restOfContent = content.slice(sectionStart);
-        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixNoCapture}\\d[\\d.]*`, 'i'));
+        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixNoCapture}${phaseScanTokenSource(directoryContext)}`, 'i'));
         const sectionEnd = nextHeader
             ? sectionStart + nextHeader.index
             : content.length;
@@ -2674,7 +2680,7 @@ function cmdInitManager(cwd, raw) {
             // of reporting no_directory/phase_complete:false. Five other init
             // commands already route through this same primitive; this was the
             // holdout private copy (#4793-family declared-owner drift).
-            const located = findPhaseInternal(cwd, phaseNum, phaseIdConvention);
+            const located = findPhaseInternal(cwd, phaseNum, phaseIdConvention, directoryContext);
             const dirMatch = located && located['found']
                 ? node_path_1.default.posix.basename(String(located['directory']))
                 : null;
@@ -2785,15 +2791,83 @@ function cmdInitManager(cwd, raw) {
         .filter((p) => p['phase_complete'] === true)
         .map((p) => normalizePhaseNumber(p['number'])));
     const phaseMap = new Map(phases.map((p) => [normalizePhaseNumber(p['number']), p]));
-    const _allCompletedPattern = new RegExp(`-\\s*\\[x\\]\\s*.*${phaseHeadingPrefixNoCapture}(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
-    let _allMatch;
-    while ((_allMatch = _allCompletedPattern.exec(rawContent)) !== null) {
-        const phaseNum = normalizePhaseNumber(_allMatch[1]);
-        const phase = phaseMap.get(phaseNum);
-        if (!phase || phase['phase_complete'] === true) {
-            completedNums.add(phaseNum);
+    const bracketIdentityKey = (value) => {
+        try {
+            const id = parsePhaseId(value);
+            const subphase = id.subphase ? `.${id.subphase}` : '';
+            return bracketQualifiedKey(`${id.project}.${id.milestone}-${id.phase}${subphase}`, 'bracket');
+        }
+        catch {
+            return null;
+        }
+    };
+    const phaseByBracketIdentity = new Map();
+    const bracketIdentityByPhaseNumber = new Map();
+    const completedBracketIdentities = new Set();
+    if (phaseIdConvention === 'bracket') {
+        for (const phase of phases) {
+            const phaseNumber = phase['number'];
+            const bracketId = bracketIdsByPhaseNumber.get(phaseNumber);
+            const canonicalPhaseToken = phaseToken(phaseNumber);
+            // #4304: key each heading on the reader's canonical
+            // token, not on a strict parse of its rendered display. An accepted
+            // unpadded heading (`### [CK.02] 1:`) gets no display_id, because
+            // parsePhaseId rejects `CK.02-1`, so it had no identity at all and a
+            // checked `[CK.02] 01` row completed it while phase_complete was false.
+            // phaseToken pads the number to `01`, and `CK.02-01` is the form
+            // parsePhaseId accepts; canonical headings key exactly as before.
+            const key = bracketId && canonicalPhaseToken
+                ? bracketIdentityKey(`${bracketId}-${canonicalPhaseToken}`)
+                : null;
+            if (!key)
+                continue;
+            bracketIdentityByPhaseNumber.set(normalizePhaseNumber(phaseNumber), key);
+            phaseByBracketIdentity.set(key, phase);
+            if (phase['phase_complete'] === true)
+                completedBracketIdentities.add(key);
+        }
+    }
+    if (phaseIdConvention === 'bracket') {
+        // A checked historical row satisfies only its own qualified identity. In
+        // particular, `[CK.01] 01` must not complete bare/current `[CK.02] 01`.
+        for (const line of rawContent.split(/\r?\n/)) {
+            const checkbox = parsePhaseChecklistLine(line, phaseIdConvention);
+            if (!checkbox?.checked || !checkbox.bracketId)
+                continue;
+            const identity = `[${checkbox.bracketId}] ${checkbox.phaseToken}`;
+            const key = bracketIdentityKey(identity);
+            if (!key)
+                continue;
+            const current = phaseMap.get(normalizePhaseNumber(checkbox.phaseToken));
+            const currentKey = current
+                ? bracketIdentityByPhaseNumber.get(normalizePhaseNumber(current['number'])) ?? null
+                : null;
+            if (!current || currentKey !== key || current['phase_complete'] === true) {
+                completedBracketIdentities.add(key);
+            }
         }
     }
+    else {
+        // Preserve the historical greedy non-bracket fallback byte-for-byte.
+        const _allCompletedPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`.*${phaseHeadingPrefixNoCapture}(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
+        let _allMatch;
+        while ((_allMatch = _allCompletedPattern.exec(rawContent)) !== null) {
+            if (!(0, phase_entry_grammar_cjs_1.isPhaseEntryChecked)(_allMatch[0]))
+                continue;
+            const phaseNum = normalizePhaseNumber(_allMatch[1]);
+            const phase = phaseMap.get(phaseNum);
+            if (!phase || phase['phase_complete'] === true) {
+                completedNums.add(phaseNum);
+            }
+        }
+    }
+    const currentDependencyNumber = (dependency) => {
+        const identity = bracketIdentityKey(dependency);
+        if (!identity)
+            return normalizePhaseNumber(dependency);
+        const current = phaseByBracketIdentity.get(identity);
+        return current ? normalizePhaseNumber(current['number']) : null;
+    };
     function reaches(from, to, visited = new Set()) {
         const normalizedFrom = normalizePhaseNumber(from);
         const normalizedTo = normalizePhaseNumber(to);
@@ -2803,15 +2877,18 @@ function cmdInitManager(cwd, raw) {
         const p = phaseMap.get(normalizedFrom);
         if (!p || !p['dep_phases'] || p['dep_phases'].length === 0)
             return false;
-        if (p['dep_phases'].some((dep) => normalizePhaseNumber(dep) === normalizedTo)) {
+        if (p['dep_phases'].some((dep) => currentDependencyNumber(dep) === normalizedTo)) {
             return true;
         }
-        return p['dep_phases'].some((dep) => reaches(dep, to, visited));
+        return p['dep_phases'].some((dep) => {
+            const dependencyNumber = currentDependencyNumber(dep);
+            return dependencyNumber === null ? false : reaches(dependencyNumber, to, visited);
+        });
     }
     function hasDepRelationship(numA, numB) {
         return reaches(numA, numB) || reaches(numB, numA);
     }
-    // #4764: a phase reference in depends_on prose is a PHASE-SHAPED token in
+    // #4764/#4304: a phase reference in depends_on prose is a PHASE-SHAPED token in
     // context — directly following "Phase"/"Phases" — never a bare digit run.
     // The previous whole-field scrape matched the token grammar against every
     // digit run, so calendar dates ("2026-09-14" → 2026, 09, 14), git shas
@@ -2824,9 +2901,27 @@ function cmdInitManager(cwd, raw) {
     // "Phase 1-3") — silently dropping a REAL dependency would clear
     // deps_satisfied prematurely, the dangerous direction. Negation prose
     // ("dropped the dependency on Phase 654") is NOT detected: the issue's own
-    // minimum keeps such tokens.
-    const depPhaseRefRe = new RegExp(`${PHASE_DEP_REF_SOURCE}`, 'gi');
-    const depTokenRe = new RegExp(`${PHASE_NUMBER_TOKEN_SOURCE}`, 'gi');
+    // minimum keeps such tokens. Bracket repositories route through the same
+    // phase-id owner so `[CK.02] 01` retains its complete qualified identity;
+    // bare `01` still resolves against the active milestone. This prevents a
+    // checked historical `[CK.01] 01` from satisfying incomplete `[CK.02] 01`.
+    // Non-bracket extraction remains this manager surface's exact #4764 code
+    // path below, including its case-insensitive token regex. Planning-inspect's
+    // old token regex was case-sensitive, so forcing both through one widened
+    // helper changed its `Phase 1a` bytes from `1` to `1a`.
+    const legacyManagerDependencyTokens = (prose) => {
+        const depPhaseRefRe = new RegExp(`${PHASE_DEP_REF_SOURCE}`, 'gi');
+        const depTokenRe = new RegExp(`${PHASE_NUMBER_TOKEN_SOURCE}`, 'gi');
+        const tokens = [];
+        let refMatch;
+        while ((refMatch = depPhaseRefRe.exec(prose)) !== null) {
+            let tokenMatch;
+            depTokenRe.lastIndex = 0;
+            while ((tokenMatch = depTokenRe.exec(refMatch[1])) !== null)
+                tokens.push(tokenMatch[0]);
+        }
+        return tokens;
+    };
     for (const phase of phases) {
         if (!phase['depends_on'] ||
             /^none$/i.test(phase['depends_on'].trim())) {
@@ -2835,24 +2930,39 @@ function cmdInitManager(cwd, raw) {
         else {
             const prose = phase['depends_on'];
             const ownNumber = normalizePhaseNumber(phase['number']);
+            const ownIdentity = typeof phase['display_id'] === 'string'
+                ? bracketIdentityKey(phase['display_id'])
+                : null;
             const depNums = [];
             const seen = new Set();
-            let refMatch;
-            depPhaseRefRe.lastIndex = 0;
-            while ((refMatch = depPhaseRefRe.exec(prose)) !== null) {
-                let tok;
-                depTokenRe.lastIndex = 0;
-                while ((tok = depTokenRe.exec(refMatch[1])) !== null) {
-                    const normalized = normalizePhaseNumber(tok[0]);
-                    if (normalized === ownNumber)
-                        continue; // #4764: never the row's own phase
-                    if (seen.has(normalized))
+            const dependencyTokens = phaseIdConvention === 'bracket'
+                ? extractPhaseDependencyTokens(prose, phaseIdConvention)
+                : legacyManagerDependencyTokens(prose);
+            for (const token of dependencyTokens) {
+                const identity = bracketIdentityKey(token);
+                if (identity) {
+                    if (identity === ownIdentity)
+                        continue;
+                    if (seen.has(identity))
                         continue;
-                    seen.add(normalized);
-                    depNums.push(tok[0]);
+                    seen.add(identity);
+                    depNums.push(token);
+                    continue;
                 }
+                const normalized = normalizePhaseNumber(token);
+                if (normalized === ownNumber)
+                    continue; // #4764: never the row's own phase
+                if (seen.has(normalized))
+                    continue;
+                seen.add(normalized);
+                depNums.push(token);
             }
-            phase['deps_satisfied'] = depNums.every((n) => completedNums.has(normalizePhaseNumber(n)));
+            phase['deps_satisfied'] = depNums.every((dependency) => {
+                const identity = bracketIdentityKey(dependency);
+                return identity
+                    ? completedBracketIdentities.has(identity)
+                    : completedNums.has(normalizePhaseNumber(dependency));
+            });
             phase['dep_phases'] = depNums;
         }
     }
@@ -3316,6 +3426,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
             `Available workstreams: ${_availableWorkstreams.join(', ')}`, ERROR_REASON.WORKSTREAM_MODE_NONE_ACTIVE);
     }
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
+    const directoryContext = phaseDirectoryOptions(cwd, config);
     const phases = [];
     let currentPhase = null;
     let nextPhase = null;
@@ -3328,7 +3439,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
         // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag, owned by
         // buildPhaseHeadingScanRegex (phase-id.cts) so this scan also recognizes
         // bracket-convention headings instead of hand-rolling a literal `Phase\s+`.
-        const { regex: headingPattern, phaseNumGroup: hNumGroup, phaseNameGroup: hNameGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, progressConvention);
+        const { regex: headingPattern, phaseNumGroup: hNumGroup, phaseNameGroup: hNameGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, progressConvention, directoryContext);
         let hm;
         while ((hm = headingPattern.exec(roadmapContent)) !== null) {
             roadmapPhaseNums.add(hm[hNumGroup]);
@@ -3361,12 +3472,12 @@ function cmdInitProgress(cwd, raw, options = {}) {
         // matched (by absorbing the bracket text). This does NOT migrate the site
         // onto phaseHeadingPrefixSrcFor / the bracket convention — that stays
         // out of scope per the comment above (#4984 revert, pinned census).
-        const cbPattern = new RegExp(`^[ \\t]*-[ \\t]*\\[(x| )\\][ \\t]*(?:\\*\\*)?(?:\\[[^\\]\\n]{0,200}\\]\\s*)?Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gim');
+        const cbPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`(?:\\[[^\\]\\n]{0,200}\\]\\s*)?Phase\\s+(${phaseScanTokenSource(directoryContext)})[:\\s]`, 'gim', { state: 'captured' });
         let cbm;
         while ((cbm = cbPattern.exec(roadmapContent)) !== null) {
             const cbKey = cbm[2];
             if (!roadmapCheckboxStates.has(cbKey)) {
-                roadmapCheckboxStates.set(cbKey, cbm[1].toLowerCase() === 'x');
+                roadmapCheckboxStates.set(cbKey, (0, phase_entry_grammar_cjs_1.isBoxCharChecked)(cbm[1]));
             }
         }
     }
@@ -3383,10 +3494,12 @@ function cmdInitProgress(cwd, raw, options = {}) {
         // behavior-preserving).
         const dirs = listMilestonePhaseDirs(phasesDir, { cwd }).value;
         for (const dir of dirs) {
-            const dirMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})-?(.*)`, 'i'));
-            const phaseNumber = dirMatch ? dirMatch[1] : dir;
-            const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
-            seenPhaseNums.add(phaseNumber.replace(/^0+/, '') || '0');
+            const dirMatch = dir.match(new RegExp(`^(${phaseScanTokenSource(directoryContext)})-?(.*)`, 'i'));
+            const query = customPhaseQuery(dir, directoryContext);
+            const owner = query && customDirectoryOwner(dir, query);
+            const phaseNumber = owner ? owner.id : dirMatch ? dirMatch[1] : dir;
+            const phaseName = owner ? owner.slug : dirMatch && dirMatch[2] ? dirMatch[2] : null;
+            seenPhaseNums.add((phaseKeyFromToken(phaseNumber, directoryContext) ?? phaseNumber).toLowerCase());
             const phasePath = node_path_1.default.join(phasesDir, dir);
             const phaseFiles = node_fs_1.default.readdirSync(phasePath);
             // #5060: Phase Status Module — the single owner of "what state is
@@ -3431,7 +3544,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
         /* otherwise intentionally empty */
     }
     for (const [num, name] of roadmapPhaseNames) {
-        const stripped = num.replace(/^0+/, '') || '0';
+        const stripped = (phaseKeyFromToken(num, directoryContext) ?? num).toLowerCase();
         if (!seenPhaseNums.has(stripped)) {
             const checkboxComplete = roadmapCheckboxStates.get(num) === true ||
                 roadmapCheckboxStates.get(stripped) === true;
@@ -3461,7 +3574,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
             }
         }
     }
-    phases.sort((a, b) => comparePhaseNum(a['number'], b['number']));
+    phases.sort((a, b) => comparePhaseNum(a['number'], b['number'], directoryContext));
     // #3581: the frontier is ROADMAP ORDER, not artifact presence. The disk loop
     // above could claim nextPhase from a stray out-of-order artifact directory
     // (a phase-9 UAT evidence dir while roadmap phase 8 was pending and

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

@@ -339,6 +339,9 @@ const ERROR_REASON = Object.freeze({
     SDK_MISSING_ARG: 'sdk_missing_arg',
     // workflow / phase
     PHASE_NOT_FOUND: 'phase_not_found',
+    PHASE_ID_COLLISION: 'phase_id_collision',
+    AMBIGUOUS_PHASE_OWNER: 'ambiguous_phase_owner',
+    PHASE_NAMING_NOT_CUSTOM: 'phase_naming_not_custom',
     PHASE_VERIFICATION_INCOMPLETE: 'phase_verification_incomplete',
     PHASE_PLAN_COVERAGE_INCOMPLETE: 'phase_plan_coverage_incomplete',
     SUMMARY_NO_PLANNING: 'summary_no_planning',
@@ -471,6 +474,9 @@ const REASON_TO_OUTCOME = Object.freeze({
     [ERROR_REASON.SDK_MISSING_ARG]: 'USAGE',
     [ERROR_REASON.GRAPHIFY_INVALID_QUERY]: 'USAGE',
     [ERROR_REASON.USAGE]: 'USAGE',
+    [ERROR_REASON.PHASE_ID_COLLISION]: 'USAGE',
+    [ERROR_REASON.AMBIGUOUS_PHASE_OWNER]: 'USAGE',
+    [ERROR_REASON.PHASE_NAMING_NOT_CUSTOM]: 'USAGE',
     // A specific, named thing does not exist / nothing was there to find —
     // genuine, known emptiness rather than a broken prerequisite.
     [ERROR_REASON.CONFIG_KEY_NOT_FOUND]: 'NO_INPUT',

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -30,6 +30,8 @@ exports.maskFences = maskFences;
 exports.editOutsideFences = editOutsideFences;
 exports.replaceSection = replaceSection;
 exports.withSection = withSection;
+exports.headingSliceRange = headingSliceRange;
+exports.editHeadingSlice = editHeadingSlice;
 exports.deleteSection = deleteSection;
 exports.extractXmlTagBodies = extractXmlTagBodies;
 const pattern_cjs_1 = require("./pattern.cjs");
@@ -1035,6 +1037,29 @@ function withSection(content, target, edit, opts = {}) {
         return content;
     return replaceSection(content, section, newBody);
 }
+/**
+ * Range of the slice that starts at `headings[index]` and runs to the next
+ * heading of level <= `maxLevel` (fence-aware: `headings` comes from
+ * `tokenizeHeadings`). Unlike `collectSection` it keeps the heading line and
+ * every trailing byte, so a caller that edits the slice can splice it back
+ * byte-exact (#5762).
+ */
+function headingSliceRange(content, headings, index, maxLevel = 2) {
+    const next = headings.slice(index + 1).find((h) => h.level <= maxLevel);
+    return { start: headings[index].offset, end: next ? next.offset : content.length };
+}
+/**
+ * Run `edit` on `content.slice(range.start, end)` and splice the result back,
+ * where `end` excludes the single newline that precedes the next heading — the
+ * slice the pre-owner writers cut with `search(/\n#{1,2}[ \t]/)` — so a row
+ * inserted at the end of a table keeps the blank line before that heading.
+ */
+function editHeadingSlice(content, range, edit) {
+    const end = range.end < content.length && range.end > range.start && content[range.end - 1] === '\n'
+        ? range.end - 1
+        : range.end;
+    return content.slice(0, range.start) + edit(content.slice(range.start, end)) + content.slice(end);
+}
 // ─── deleteSection ────────────────────────────────────────────────────────────
 /**
  * Delete an entire section — the matching heading line ITSELF plus its body —
@@ -1065,6 +1090,8 @@ function withSection(content, target, edit, opts = {}) {
  * double-blank gap accumulates where the section used to sit. Content
  * elsewhere in the document is never touched.
  *
+ * `endOffset` adds an optional caller-owned maximum boundary. It never widens
+ * the heading-level range, and callers that omit it retain the legacy bytes.
  * Returns `content` unchanged when no heading matches `headingPredicate`
  * (bounded no-op, mirroring `withSection`'s miss behaviour).
  */
@@ -1103,7 +1130,13 @@ function deleteSection(content, headingPredicate, opts = {}) {
     }
     const eofOffset = acc;
     const sectionStart = lineOffsets[target.line - 1]; // start of the target heading LINE itself
-    const sectionEnd = stopLine <= lines.length ? lineOffsets[stopLine - 1] : eofOffset;
+    const headingBoundedEnd = stopLine <= lines.length ? lineOffsets[stopLine - 1] : eofOffset;
+    const explicitEnd = typeof opts.endOffset === 'number' && Number.isFinite(opts.endOffset)
+        ? Math.max(0, Math.min(content.length, opts.endOffset))
+        : headingBoundedEnd;
+    const sectionEnd = Math.min(headingBoundedEnd, explicitEnd);
+    if (sectionEnd <= sectionStart)
+        return content;
     const before = content.slice(0, sectionStart);
     const after = content.slice(sectionEnd);
     // Collapse a resulting blank-line seam to at most one blank line (2 newlines).

package/gsd-core/bin/lib/markdown-table.cjs

@@ -25,6 +25,7 @@ exports.escapeCell = escapeCell;
 exports.appendQuickTaskRow = appendQuickTaskRow;
 exports.migrateQuickTasksTable = migrateQuickTasksTable;
 exports.resetQuickTaskRows = resetQuickTaskRows;
+exports.updateTraceabilityCell = updateTraceabilityCell;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Schema registry ──────────────────────────────────────────────────────────
 /**
@@ -978,5 +979,27 @@ function resetQuickTaskRows(stateContent) {
     const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
     return { ok: true, value: { content, cleared, variant: match.label } };
 }
+/**
+ * `updateTableCell` scoped to REQUIREMENTS.md's `## Traceability` (or
+ * `## Traceability Status`) section (#2245 F1, #5762): `updateTableCell` binds
+ * to the first table it finds, and the shipped template puts an `## Out of
+ * Scope` table (`Feature | Reason`, no `Status` column) before Traceability, so
+ * an unscoped call never reaches the real rows. The ONE copy of this slice
+ * (it used to live in both milestone.cts and phase.cts); the heading rule is
+ * the Progress owner's — first level-2 heading outside fenced code, running to
+ * the next level-1/2 heading. No such heading: the whole text, as before.
+ */
+function updateTraceabilityCell(text, match, column, newValue) {
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(text);
+    const index = headings.findIndex((h) => h.level === 2 && /^Traceability(?:[ \t]+Status)?\b/i.test(h.text));
+    if (index === -1)
+        return updateTableCell(text, match, column, newValue);
+    let result = { ok: false, reason: 'no matching row' };
+    const edited = (0, markdown_sectionizer_cjs_1.editHeadingSlice)(text, (0, markdown_sectionizer_cjs_1.headingSliceRange)(text, headings, index, 2), (scoped) => {
+        result = updateTableCell(scoped, match, column, newValue);
+        return result.ok ? result.value : scoped;
+    });
+    return result.ok ? { ok: true, value: edited } : result;
+}
 // Consumers: require('../gsd-core/bin/lib/markdown-table.cjs')
 // Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).

package/gsd-core/bin/lib/mcp-server.cjs

@@ -109,10 +109,10 @@ const TOOLS = [
             type: 'object',
             properties: {
                 family: { type: 'string', description: 'Command family (e.g. "query", "state", "phase").' },
-                subcommand: { type: 'string', description: 'Subcommand name.' },
+                subcommand: { type: 'string', description: 'Subcommand name, if the command takes one. Omit or leave empty for family-only commands.' },
                 args: { type: 'array', items: {}, description: 'Positional args.' },
             },
-            required: ['family', 'subcommand'],
+            required: ['family'],
         },
     },
     {
@@ -182,10 +182,13 @@ function callTool(name, args, ctx) {
         if (name === 'gsd_invoke_command') {
             const family = asString(a.family);
             const subcommand = asString(a.subcommand);
-            if (!family || !subcommand) {
-                return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "family" and "subcommand".' }] };
+            if (!family) {
+                return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires a non-empty string "family".' }] };
             }
-            const res = dispatchGsdCommand({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd });
+            if (a.subcommand !== undefined && subcommand === null) {
+                return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "subcommand" when provided.' }] };
+            }
+            const res = dispatchGsdCommand({ family, subcommand: subcommand ?? undefined, args: Array.isArray(a.args) ? a.args : [], cwd });
             if (!res.ok) {
                 return { isError: true, content: [{ type: 'text', text: res.stderr || res.stdout || `dispatch failed (exit ${res.code})` }] };
             }