@opengsd/gsd-core 1.19.0 → 1.20.0

package/gsd-core/bin/lib/capability-validator.cjs

@@ -1874,6 +1874,11 @@ const KNOWN_REVIEWER_FIELDS = new Set([
   // effort", which emits no effort argument at all.
   'effortConfigKey',
   'defaultEffort',
+  // `contextWindowTokens` / `contextWindowConfigKey` added by #4559, same optional/backward-compatible
+  // shape as `promptBudgetKey`: a manifest authored before they existed keeps validating, and an
+  // absent or non-positive window resolves to "no derived prompt cap" at the invocation boundary.
+  'contextWindowTokens',
+  'contextWindowConfigKey',
   'handler',
 ]);
 
@@ -2505,6 +2510,16 @@ function validateReviewerBodyFields(cap) {
     );
   }
 
+  // #4559: optional. Absent or null is "no declared window"; a present key must be a dotted
+  // config key string. The window's VALUE is narrowed (never rejected) by `resolveLaneCap`.
+  if (r.contextWindowConfigKey !== undefined && r.contextWindowConfigKey !== null
+      && (typeof r.contextWindowConfigKey !== 'string' || r.contextWindowConfigKey.length === 0)) {
+    errors.push(
+      ctx + ' reviewer.contextWindowConfigKey must be a dotted config key or null ' +
+      '(got: ' + describeValue(r.contextWindowConfigKey) + ')',
+    );
+  }
+
   // ── handler (D6) — closed first-party enum; null is the default ────────────
   if (r.handler !== null && !VALID_LANE_HANDLERS.has(r.handler)) {
     errors.push(

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

@@ -31,13 +31,13 @@ const coreUtilsMod = require("./core-utils.cjs");
 const { toPosixPath, generateSlugInternal, extractOneLinerFromBody } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, comparePhaseNum, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, renderPhaseBranchName, parsePhaseId, renderPhaseId, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, } = phaseIdMod;
+const { customPhaseQuery, customDirectoryOwner, isCustomPhaseId, normalizePhaseName, comparePhaseNum, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, renderPhaseBranchName, parsePhaseId, renderPhaseId, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdDisplayMod = require("./phase-id-display.cjs");
 const { renderBracketMilestoneDisplay } = phaseIdDisplayMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { getArchivedPhaseDirs, findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, getArchivedPhaseDirs, findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { extractCurrentMilestone, stripShippedMilestones: _stripShippedMilestones, getMilestoneInfo, getRoadmapPhaseInternal } = roadmapParserMod;
@@ -1822,7 +1822,7 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify, filesRemoved) {
             // phase — the phase arm must never branch-mutate for it (isSentinelPhaseId
             // is the invariant's single owner, src/phase-id.cts).
             if (phaseNum && !isSentinelPhaseId(phaseNum)) {
-                const phaseInfo = findPhaseInternal(cwd, phaseNum);
+                const phaseInfo = findPhaseInternal(cwd, phaseNum, undefined, phaseDirectoryOptions(cwd, config));
                 if (phaseInfo) {
                     // #4126: shared with init.cts's cmdInitExecutePhase branch_name field
                     // via the one canonical renderer (src/phase-id.cts) so an undeliverable
@@ -3053,6 +3053,7 @@ function cmdProgressRender(cwd, format, raw) {
         ? renderBracketMilestoneDisplay(milestone?.version, loadConfig(cwd).project_code)
         : null;
     const milestoneVersion = milestoneDisplay ?? milestone?.version ?? null;
+    const directoryContext = phaseDirectoryOptions(cwd);
     const phases = [];
     let totalPlans = 0;
     let totalSummaries = 0;
@@ -3091,9 +3092,11 @@ function cmdProgressRender(cwd, format, raw) {
                 }
             }
             else {
+                const custom = customPhaseQuery(dir, directoryContext);
+                const owner = custom && customDirectoryOwner(dir, custom);
                 const dm = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/);
-                phaseNum = dm ? dm[1] : dir;
-                phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
+                phaseNum = owner ? owner.id : dm ? dm[1] : dir;
+                phaseName = owner ? owner.slug.replace(/-/g, ' ') : dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
             }
             // #3183/#5060: canonical plan/summary counts and lifecycle status
             // (root+nested, superseded-excluded, canonical pairing) from the
@@ -3212,7 +3215,7 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
         .map(w => w.replace(/[^a-z0-9]/g, ''))
         .filter(w => w.length > 2 && !stopWords.has(w)));
     // Find phase directory to get expected file paths
-    const phaseInfoDisk = findPhaseInternal(cwd, phase);
+    const phaseInfoDisk = findPhaseInternal(cwd, phase, undefined, phaseDirectoryOptions(cwd));
     const phasePlans = [];
     if (phaseInfoDisk && phaseInfoDisk['found']) {
         try {
@@ -3394,7 +3397,7 @@ function cmdScaffold(cwd, type, options, raw) {
     const padded = phase ? normalizePhaseName(phase) : '00';
     const today = clock_cjs_1.realClock.localToday();
     // Find phase directory
-    const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
+    const phaseInfo = phase && type !== 'phase-dir' ? findPhaseInternal(cwd, phase, undefined, phaseDirectoryOptions(cwd)) : null;
     const phaseDir = phaseInfo ? node_path_1.default.join(cwd, phaseInfo['directory']) : null;
     if (phase && !phaseDir && type !== 'phase-dir') {
         error(`Phase ${phase} directory not found`);
@@ -3422,14 +3425,14 @@ function cmdScaffold(cwd, type, options, raw) {
             }
             const slug = generateSlugInternal(name);
             // #3287: apply project_code prefix to stay consistent with phase.add/phase.insert
-            const scaffoldConfig = loadConfig(cwd);
-            const scaffoldProjectCode = scaffoldConfig['project_code'] || '';
-            const scaffoldPrefix = scaffoldProjectCode ? `${scaffoldProjectCode}-` : '';
-            const dirName = `${scaffoldPrefix}${padded}-${slug}`;
-            const phasesParent = planningPaths(cwd).phases;
-            (0, shell_command_projection_cjs_1.platformEnsureDir)(phasesParent);
-            const dirPath = node_path_1.default.join(phasesParent, dirName);
-            (0, shell_command_projection_cjs_1.platformEnsureDir)(dirPath);
+            const scaffoldConfig = phaseDirectoryOptions(cwd, undefined, '');
+            const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
+            const roadmap = scaffoldConfig.phaseNaming === 'custom' && node_fs_1.default.existsSync(roadmapPath)
+                ? node_fs_1.default.readFileSync(roadmapPath, 'utf8') : '';
+            const [{ dirPath }] = phaseLocatorMod.createPhaseDirectories(cwd, [{
+                    id: phase, slug: slug || '',
+                    directoryId: scaffoldConfig.phaseNaming === 'custom' && isCustomPhaseId(phase) ? phase : padded,
+                }], { ...scaffoldConfig, roadmap }, false);
             output({ created: true, directory: toPosixPath(node_path_1.default.relative(cwd, dirPath)), path: dirPath }, raw, dirPath);
             return;
         }
@@ -3728,12 +3731,19 @@ function cmdStats(cwd, format, raw) {
  */
 function cmdCheckCommit(cwd, raw) {
     const config = loadConfig(cwd);
-    const stagedResult = (0, shell_command_projection_cjs_1.execGit)(['diff', '--cached', '--name-only', '-z'], { cwd });
+    // #5548: execGit scrubs the repo-location vars, but inside the pre-commit hook git sets them
+    // (GIT_DIR/GIT_WORK_TREE of an explicit --git-dir commit, GIT_INDEX_FILE of a `-a` / `<path>`
+    // commit) to name the repo being committed: hand them back or the guard finds no repo and allows.
+    const hookEnv = {};
+    for (const k of shell_command_projection_cjs_1.GIT_LOCATION_ENV_VARS)
+        if (process.env[k] !== undefined)
+            hookEnv[k] = process.env[k];
+    const stagedResult = (0, shell_command_projection_cjs_1.execGit)(['diff', '--cached', '--name-only', '-z'], { cwd, env: hookEnv });
     if (stagedResult.exitCode === 0) {
         const files = stagedResult.stdout.split('\0').filter(Boolean);
         const planningFiles = files.filter(f => f.startsWith('.planning/'));
         if (planningFiles.length > 0) {
-            const policy = resolveCommitDocsPolicy(config, detectPhaseNumberFromFiles(planningFiles), () => isGitIgnored(cwd, '.planning'));
+            const policy = resolveCommitDocsPolicy(config, detectPhaseNumberFromFiles(planningFiles), () => isGitIgnored(cwd, '.planning', hookEnv));
             if (!policy.resolved) {
                 error(`commit_docs is false but ${planningFiles.length} .planning/ file(s) are staged:\n` +
                     planningFiles.map(f => `  ${f}`).join('\n') +

package/gsd-core/bin/lib/config-loader.cjs

@@ -213,16 +213,16 @@ function _deepMergeConfig(base, overlay) {
 const _warnedUnknownConfigKeys = new Set();
 // ─── Git utilities ────────────────────────────────────────────────────────────
 const _gitIgnoredCache = new Map();
-function isGitIgnored(cwd, targetPath) {
+function isGitIgnored(cwd, targetPath, env) {
     // #2206: strip trailing slashes — `git check-ignore` has a quirk where a
     // CRLF .gitignore with blank lines falsely reports a trailing-slash path
     // (e.g. `.planning/`) as ignored. Normalizing here protects every call site.
     const normalized = targetPath.replace(/\/+$/, '');
-    const key = cwd + '::' + normalized;
+    const key = cwd + '::' + normalized + (env ? '::env:' + JSON.stringify(Object.entries(env).sort()) : '');
     if (_gitIgnoredCache.has(key))
         return _gitIgnoredCache.get(key);
     // --no-index checks .gitignore rules regardless of whether the file is tracked.
-    const result = (0, shell_command_projection_cjs_1.execGit)(['check-ignore', '-q', '--no-index', '--', normalized], { cwd });
+    const result = (0, shell_command_projection_cjs_1.execGit)(['check-ignore', '-q', '--no-index', '--', normalized], { cwd, env });
     const ignored = result.exitCode === 0;
     _gitIgnoredCache.set(key, ignored);
     return ignored;

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

@@ -42,6 +42,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // pattern.cjs is a leaf module (escapeRegex only), so this adds no cycle.
 const pattern_cjs_1 = require("./pattern.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -553,6 +554,15 @@ function planRowPattern(planId, opts = {}) {
     const lead = opts.anchored ? '^(\\s*-\\s*\\[)' : '(-\\s*\\[)';
     return new RegExp(`${lead}${box}(\\]\\s*(?:\\*\\*)?${(0, pattern_cjs_1.escapeRegex)(planId)}${PLAN_ID_ROW_BOUNDARY_SOURCE}(?:\\*\\*)?)`, 'i');
 }
+/**
+ * Tick the first line-anchored unchecked row for `planId` in `text` (the
+ * `phase complete` / `roadmap update-plan-progress` bullet flip): a bullet
+ * mutation through `updateBullet`, so never a fenced line or mid-line match.
+ */
+function tickAnchoredPlanRow(text, planId) {
+    const row = planRowPattern(planId, { anchored: true });
+    return (0, markdown_sectionizer_cjs_1.updateBullet)(text, (_bulletText, rawLine) => row.test(rawLine), (rawLine) => rawLine.replace(row, '$1x$2'));
+}
 module.exports = {
     toPosixPath,
     normalizeLineEndings,
@@ -570,4 +580,5 @@ module.exports = {
     findOrphanSummaries,
     summaryPairsWithAnyPlan,
     planRowPattern,
+    tickAnchoredPlanRow,
 };

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

@@ -851,6 +851,17 @@ function frontmatterListEntries(content, key) {
  * no closed, parseable frontmatter mapping or the key is not an own key of it.
  */
 function rawFrontmatterField(content, key) {
+    const mapping = rawFrontmatterMapping(content);
+    if (!mapping || !Object.prototype.hasOwnProperty.call(mapping, key))
+        return null;
+    return { value: mapping[key] };
+}
+/**
+ * The top-level frontmatter mapping VERBATIM, off `rawFrontmatterField`'s guarded parse path.
+ * Null when the document has no closed, parseable frontmatter mapping — so a caller can tell
+ * "parsed, without that key" (#4998 review) from "no usable frontmatter".
+ */
+function rawFrontmatterMapping(content) {
     const found = frontmatterRegion(content);
     if (!found || !found.terminated)
         return null;
@@ -867,9 +878,7 @@ function rawFrontmatterField(content, key) {
     }
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
-    if (!Object.prototype.hasOwnProperty.call(raw, key))
-        return null;
-    return { value: raw[key] };
+    return raw;
 }
 /**
  * Escape a string for emission inside a YAML double-quoted scalar (#1779). ADR-3473 §8.1
@@ -940,6 +949,14 @@ function scalarNeedsDoubleQuoting(s) {
     // round-trip.
     if (/[\uD800-\uDFFF]/.test(s))
         return true;
+    // #4998: U+2028/U+2029 are not YAML line breaks, so a bare one round-trips
+    // through js-yaml, but every line-anchored reader of a planning document
+    // (`^key:\s*(.+)` with the `m` flag) ends the line there and reads only the
+    // part before it. (A value holding `:` was already quoted by the callers, so
+    // no key could be forged this way.) The quoted path escapes them (`\L`,
+    // `\P`), which no such reader splits on.
+    if (/[\u2028\u2029]/.test(s))
+        return true;
     return false;
 }
 /**
@@ -1806,6 +1823,7 @@ module.exports = {
     // parse path — the decision-coverage gates read `must_haves`/`truths`/`objective` and the
     // SUMMARY `files_modified` list through it instead of a hand-rolled `^key:` scan / regex.
     rawFrontmatterField,
+    rawFrontmatterMapping,
     // #5139: one key's block as unparsed text, for a citation scan that must survive frontmatter
     // the YAML parser refuses.
     frontmatterKeyBlockText,

package/gsd-core/bin/lib/gate-api-coverage-verify-pre.cjs

@@ -39,7 +39,7 @@ const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
+const { phaseDirectoryOptions, findPhaseInternal } = phaseLocatorMod;
 const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapModule = require("./roadmap.cjs");
@@ -171,7 +171,7 @@ function evaluateApiCoverageVerifyPre(input) {
     let resolvedDir = null;
     let phaseNumber = '';
     if (token) {
-        const found = findPhaseInternal(projectDir, token);
+        const found = findPhaseInternal(projectDir, token, undefined, phaseDirectoryOptions(projectDir));
         if (found && found.directory) {
             // findPhaseInternal's `directory` is relative to the project root; anchor it to `projectDir`
             // (not the process cwd) so the gate reads the same files in-process as it does from the CLI.

package/gsd-core/bin/lib/gate-context-drift.cjs

@@ -85,7 +85,7 @@ function runContextDriftGate(cwd, phaseArg) {
     }
     // Same phase-directory resolution rule the schema-drift gate uses (#1571, #2528):
     // matchPhaseDirs, never a naive substring test.
-    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(phasesDir, phaseArg);
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(cwd, phasesDir, phaseArg);
     if (!phaseDir) {
         return unresolvable();
     }

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

@@ -34,10 +34,7 @@ const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs } = phaseIdMod;
+const { phaseDirectoryOptions, findPhaseInternal, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapModule = require("./roadmap.cjs");
 const { getRoadmapPhaseWithFallback } = roadmapModule;
@@ -78,7 +75,7 @@ function unresolvableProbeVerdict(readError) {
 function resolvePhaseDir(projectDir, phase) {
     let result;
     try {
-        result = findPhaseInternal(projectDir, phase);
+        result = findPhaseInternal(projectDir, phase, undefined, phaseDirectoryOptions(projectDir));
     }
     catch (err) {
         return (0, gate_evidence_cjs_1.evidenceFromError)(err, `phase ${phase}`);
@@ -109,11 +106,13 @@ function resolvePhaseDir(projectDir, phase) {
  * `resolvePhaseDir` would widen what those gates inspect, so the two stay apart and each states its
  * scope. Throws when `phasesDir` cannot be listed; both callers sit inside their non-blocking catch.
  */
-function resolvePhaseDirByToken(phasesDir, phaseArg) {
-    const normalizedPhase = normalizePhaseName(phaseArg);
+function resolvePhaseDirByToken(cwd, phasesDir, phaseArg, directoryContext = phaseDirectoryOptions(cwd)) {
+    const lookup = resolvePhaseDirectoryLookup(cwd, phaseArg, undefined, directoryContext);
     const dirEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
     const dirNames = dirEntries.filter((e) => e.isDirectory()).map((e) => e.name);
-    const matched = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
+    // #4304: both drift gates resolve a directory in the current checkout.
+    // Bracket is the only opt-in grammar; all other conventions remain legacy.
+    const matched = matchPhaseDirsForLookup(dirNames, lookup, undefined, directoryContext).matches[0];
     if (matched)
         return node_path_1.default.join(phasesDir, matched);
     const contained = (0, security_cjs_1.tryWithinRoot)(phaseArg, phasesDir);

package/gsd-core/bin/lib/gate-schema-drift.cjs

@@ -68,7 +68,7 @@ function runSchemaDriftGate(cwd, phaseArg, skipFlag) {
     // matching "11-expansion"), making the drift gate inspect the wrong phase.
     // This shares the one selection rule with find-phase / verify
     // phase-completeness rather than restating it. (#1571, #2528)
-    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(phasesDir, phaseArg);
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(cwd, phasesDir, phaseArg);
     if (!phaseDir) {
         // An unresolvable phase is "could not look" (#5170): there is no phase directory to evaluate.
         return schemaDriftUnreadable(`Phase directory not found: ${phaseArg}`);

package/gsd-core/bin/lib/git-info-exclude.cjs

@@ -32,14 +32,9 @@ function excludeFromGit(dir, filename) {
         // gitignore cannot express a newline in a pattern, and git's line output could not be split.
         if (/[\r\n]/.test(dir))
             return;
-        // cwd must pick the repo: drop inherited repository-location variables (e.g. inside a git hook).
-        const env = { GIT_DIR: undefined, GIT_WORK_TREE: undefined, GIT_INDEX_FILE: undefined, GIT_COMMON_DIR: undefined };
         // The prefix goes last: stdout is trimmed, and a non-empty prefix ends in `/`, so only an
         // empty prefix (dir is the git root) loses its line; a leading space survives.
-        const revParse = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-path', 'info/exclude', '--show-prefix'], {
-            cwd: dir,
-            env: env,
-        });
+        const revParse = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-path', 'info/exclude', '--show-prefix'], { cwd: dir });
         const [excludeRel, prefix = ''] = (0, text_lines_cjs_1.splitLines)(String(revParse.stdout));
         if (revParse.exitCode !== 0 || !excludeRel)
             return;

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

@@ -54,7 +54,7 @@ const validateMod = require("../validate.cjs");
 const { isPhaseDirName } = validateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { extractPhaseToken, normalizePhaseName, comparePhaseNum } = phaseIdMod;
+const { extractPhaseToken, normalizePhaseName, phaseKeyFromDir, comparePhaseNum } = phaseIdMod;
 // #5060: the Phase Status Module owns the status-label ladder.
 const phase_status_cjs_1 = require("../phase-status.cjs");
 // #5291: W030 asks whether a raw report status has a known repair. The lookup is
@@ -63,8 +63,11 @@ const verification_cjs_1 = require("../verification.cjs");
 // ─── W005 — phase directory doesn't follow NN-name format (verify.cts:1893-1902) ─
 function checkW005(snapshot) {
     const diagnostics = [];
+    const context = snapshot.directoryContext ?? phaseIdMod.phaseDirectoryContext(snapshot.config.value ?? {}, '', snapshot.roadmapDeclaredPhases.value.map(({ phaseId }) => phaseId));
     for (const name of snapshot.phaseDirs.value) {
-        if (!isPhaseDirName(name, snapshot.phaseIdConvention)) {
+        const custom = snapshot.phaseIdConvention === 'bracket' ? null : phaseIdMod.customPhaseQuery(name, context);
+        const owner = custom && phaseIdMod.customDirectoryOwner(name, custom);
+        if (!owner && !isPhaseDirName(name, snapshot.phaseIdConvention)) {
             diagnostics.push({
                 code: 'W005',
                 severity: SEVERITY.WARNING,
@@ -77,17 +80,18 @@ function checkW005(snapshot) {
 }
 // ─── W023 — phase directories collide on normalized key (verify.cts:1904-1950) ─
 //
-// Groups `snapshot.phaseDirs.value` by `normalizePhaseName(extractPhaseToken(name))`
-// — the exact same two owners (`phase-id.cjs`) the original `verify.cts:1917-1918`
-// call site uses, relocated verbatim rather than reimplemented. Sorted with
-// `comparePhaseNum` + a `localeCompare` tiebreak, mirroring
+// Groups directories by the canonical identity owner, preserving recorded
+// custom IDs instead of collapsing their shared token prefixes. Sorted with
+// contextual `comparePhaseNum` + a `localeCompare` tiebreak, mirroring
 // `verify.cts:1930-1932`'s deterministic-output rationale. See the file-level
 // comment for the disclosed "described" fidelity reduction.
 function checkW023(snapshot) {
+    const context = snapshot.directoryContext;
     const groups = new Map();
     for (const name of snapshot.phaseDirs.value) {
-        const token = extractPhaseToken(name);
-        const key = normalizePhaseName(token);
+        const key = context?.phaseNaming === 'custom'
+            ? phaseKeyFromDir(name, undefined, context)
+            : normalizePhaseName(extractPhaseToken(name));
         const list = groups.get(key);
         if (list)
             list.push(name);
@@ -101,7 +105,7 @@ function checkW023(snapshot) {
             continue;
         const described = dirs
             .slice()
-            .sort((a, b) => comparePhaseNum(a, b) || String(a).localeCompare(String(b)))
+            .sort((a, b) => comparePhaseNum(a, b, context) || String(a).localeCompare(String(b)))
             .map((d) => {
             const phase = phaseByDir.get(d);
             const plans = phase ? phase.planCount : 0;

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

@@ -104,7 +104,7 @@ const planningScopeMod = require("../planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { matchPhaseDirs, normalizePhaseName, extractPhaseToken, isSentinelPhaseId, isSentinelPhaseDir } = phaseIdMod;
+const { matchPhaseDirs, phaseLookupQuery, extractPhaseToken, isSentinelPhaseId, isSentinelPhaseDir } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const validateMod = require("../validate.cjs");
 const { phaseVariants } = validateMod;
@@ -116,7 +116,7 @@ const { phaseVariants } = validateMod;
  * does the roadmap claim, for W007) call this — one matcher, reused, per the
  * file-level comment.
  */
-function dirsForPhase(dirs, phaseId, convention) {
+function dirsForPhase(dirs, phaseId, convention, directoryContext) {
     // #612: `convention` reaches BOTH operands of this pairing or it pairs
     // nothing. The phases come from a bracket-aware heading scan and the dirs
     // from a bracket-aware disk scan, so a convention-less selector here leaves
@@ -125,7 +125,7 @@ function dirsForPhase(dirs, phaseId, convention) {
     // disk" AND every bracket directory reads as unclaimed. `matchPhaseDirs`
     // forwards it to its primary `phaseTokenMatches`; handed nothing it is
     // byte-identical, so no legacy repo's pairing changes.
-    const canonical = matchPhaseDirs(dirs, normalizePhaseName(phaseId), convention).matches;
+    const canonical = matchPhaseDirs(dirs, phaseLookupQuery(phaseId, directoryContext), convention, undefined, directoryContext).matches;
     if (canonical.length > 0)
         return canonical;
     // Bug 2 (#3309 W006/W007 migration cluster, found while fixing the
@@ -187,6 +187,7 @@ function checkW006(snapshot) {
         return [];
     const dirs = snapshot.allPhaseDirNames.value;
     const convention = snapshot.phaseIdConvention;
+    const directoryContext = snapshot.directoryContext ?? phaseIdMod.phaseDirectoryContext(snapshot.config.value ?? {}, '', snapshot.roadmapDeclaredPhases.value.map(({ phaseId }) => phaseId));
     const archivedTokens = new Set(snapshot.archivedPhaseTokens.value);
     // No separate scope guard: `roadmapSentinelPhaseTokens` and
     // `roadmapDeclaredPhases` are produced by ONE builder call
@@ -219,7 +220,7 @@ function checkW006(snapshot) {
         // not change its result.
         if (sentinelTokens.has(phaseId) || isSentinelPhaseId(phaseId))
             continue;
-        if (dirsForPhase(dirs, phaseId, convention).length > 0)
+        if (dirsForPhase(dirs, phaseId, convention, directoryContext).length > 0)
             continue;
         // Bug 1 (#3309 W006/W007 migration cluster): a phase whose ONLY
         // directory lives under a milestone archive
@@ -247,10 +248,10 @@ function checkW006(snapshot) {
 // ─── W007 — an on-disk phase directory has no matching ROADMAP entry ──────
 // (verify.cts:2086-2101)
 /** Every directory in `dirs` that ANY declared roadmap phase resolves to. */
-function computeClaimedDirs(dirs, declaredPhases, convention) {
+function computeClaimedDirs(dirs, declaredPhases, convention, directoryContext) {
     const claimed = new Set();
     for (const { phaseId } of declaredPhases) {
-        for (const dir of dirsForPhase(dirs, phaseId, convention))
+        for (const dir of dirsForPhase(dirs, phaseId, convention, directoryContext))
             claimed.add(dir);
     }
     return claimed;
@@ -261,7 +262,8 @@ function checkW007(snapshot) {
         return [];
     const dirs = snapshot.allPhaseDirNames.value;
     const convention = snapshot.phaseIdConvention;
-    const claimedDirs = computeClaimedDirs(dirs, snapshot.roadmapDeclaredPhases.value, convention);
+    const directoryContext = snapshot.directoryContext ?? phaseIdMod.phaseDirectoryContext(snapshot.config.value ?? {}, '', snapshot.roadmapDeclaredPhases.value.map(({ phaseId }) => phaseId));
+    const claimedDirs = computeClaimedDirs(dirs, snapshot.roadmapDeclaredPhases.value, convention, directoryContext);
     const diagnostics = [];
     for (const dirName of dirs) {
         // `extractPhaseToken` is the phase-id.cts owner `PHASE_TOKEN_FROM_DIR_RE`

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

@@ -46,7 +46,7 @@ const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
 const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { getMilestoneFromPhaseId, matchPhaseDirs, normalizePhaseName, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+const { getMilestoneFromPhaseId, matchPhaseDirs, phaseLookupQuery, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- the single owner of the persisted status vocabulary
 const stateDocumentMod = require("../state-document.cjs");
 const { normalizeStateStatus } = stateDocumentMod;
@@ -332,8 +332,8 @@ const RULE_W026 = {
         // field's own doc comment on `PlanningSnapshot` for why
         // `roadmapDeclaredPhases`'s `milestone` attribution is the wrong fit).
         const unstarted = [];
+        const directoryContext = snapshot.directoryContext ?? phaseIdMod.phaseDirectoryContext(snapshot.config.value ?? {}, '', snapshot.currentMilestoneRoadmapPhaseIds.value);
         for (const phaseId of snapshot.currentMilestoneRoadmapPhaseIds.value) {
-            const normalized = normalizePhaseName(phaseId);
             // `allPhaseDirNames` — every directory under `phases/`, UNWINDOWED by
             // ROADMAP-declaration membership — mirrors the original's own
             // unwindowed `phaseDirNames2` (`verify.cts:2372-2382`, a direct
@@ -346,7 +346,7 @@ const RULE_W026 = {
             // moved the read onto the shared selector; the convention rides along,
             // since the selector's primary match IS the `phaseTokenMatches` call this
             // line used to make directly.
-            const hasDirectory = matchPhaseDirs(snapshot.allPhaseDirNames.value, normalized, snapshot.phaseIdConvention).matches.length > 0;
+            const hasDirectory = matchPhaseDirs(snapshot.allPhaseDirNames.value, phaseLookupQuery(phaseId, directoryContext), snapshot.phaseIdConvention, undefined, directoryContext).matches.length > 0;
             if (!hasDirectory)
                 unstarted.push(phaseId);
         }