@opengsd/gsd-core 1.19.0 → 1.20.0

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

@@ -21,84 +21,25 @@
  *   - Issue #4 (open-gsd/gsd-core)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.locateProgressTable = locateProgressTable;
-exports.normalizeMilestoneToken = normalizeMilestoneToken;
-exports.milestoneVersionOf = milestoneVersionOf;
 exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
 exports.clampPercentFromFraction = clampPercentFromFraction;
 exports.clampPercent = clampPercent;
 exports.progressBarFilledCells = progressBarFilledCells;
 exports.renderProgressBar = renderProgressBar;
-const markdown_table_cjs_1 = require("./markdown-table.cjs");
+// #5761: the Progress table and its milestone slice have one owner.
+const roadmap_progress_cjs_1 = require("./roadmap-progress.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
 const { isSentinelPhaseId } = phaseIdMod;
 // #5060: `phase-status.cjs` is a load-time leaf (no top-level requires), safe
 // to import here for the ROADMAP Status-cell reader.
 const phase_status_cjs_1 = require("./phase-status.cjs");
-/**
- * #3227: the single owner of "where is this ROADMAP's Progress table".
- * Lifted verbatim out of deriveProgressFromRoadmap so `state-contract.cts`
- * enumerates phases from THE SAME table this module derives its counts from.
- * A second copy of this locator is the DEFECT.GENERATIVE-FIX shape.
- *
- * ADR-2143 §3 ("addressed by NAME, never ordinal"): the Progress table is
- * located via the markdown-table seam's `findTableWithColumns`, which is
- * column-NAME/order/count-invariant — it matches the first table whose header
- * is a SUPERSET of the canonical `Phase` / `Plans Complete` / `Status` /
- * `Completed` names, in any order, tolerating extra/injected unrelated
- * columns (#2137's fast-check property test shuffles headers and injects
- * columns and asserts the derived counts never change). This supersedes the
- * earlier `findTableBySchema` exact-schema lookup, which required an exact
- * canonical column SET+ORDER and returned all-null on any reordering or
- * injection.
- *
- * Scoped to the `## Progress` section when the document has one (#2012 decoy
- * avoidance — a differently-headed table sharing the same column names must
- * not be picked up instead); a headingless milestone slice (#1445) falls back
- * to scanning the whole input, preserving the "Progress table not under a
- * `## Progress` heading, or not the first table in the document, still
- * resolves" behaviour.
- */
-function locateProgressTable(roadmapContent) {
-    const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
-    let scoped = roadmapContent;
-    if (progressMatch && progressMatch.index !== undefined) {
-        const afterHeading = roadmapContent.slice(progressMatch.index);
-        const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
-        scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
-    }
-    return (0, markdown_table_cjs_1.findTableWithColumns)(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
-}
-/**
- * #5165: a milestone token compared by identity, not spelling — `v1.1`, `V1.1`
- * and ` 1.1 ` name one milestone. A hand-decorated Progress cell
- * (`**v1.1**`, `` `v1.1` ``, `v1.1 (current)`) still names its first
- * whitespace-separated token. Absent/blank tokens normalize to `''`.
- */
-function normalizeMilestoneToken(value) {
-    // `[v1.1](ROADMAP.md#v11)` names its link text.
-    const unlinked = (milestoneVersionOf(value) ?? '').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
-    const first = unlinked.split(/\s+/)[0] ?? '';
-    return first.replace(/^[*_`]+|[*_`:,;]+$/g, '').replace(/^v/i, '').toLowerCase();
-}
-/**
- * #5165: a STATE.md `milestone:` frontmatter value as a trimmed version string,
- * or null when it is absent, blank or not scalar text.
- */
-function milestoneVersionOf(value) {
-    if (typeof value !== 'string' && typeof value !== 'number')
-        return null;
-    const text = String(value).trim();
-    return text === '' ? null : text;
-}
 /**
  * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
  * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
  *
- * The Progress table itself is located by `locateProgressTable` (ADR-2143 §3,
- * lifted out as #3227's single-owner extraction) — this function consumes
- * that table.
+ * The Progress table itself is located by `locateRoadmapProgress` (the Roadmap
+ * Progress Module, ADR-2143 §3) — this function consumes that table's slice.
  *
  * Cells are read by column NAME (`r['Status']`, `r['Plans Complete']`,
  * `r['Phase']`), fixing #2137 (the old position-based regex assumed "Status"
@@ -117,18 +58,12 @@ function deriveProgressFromRoadmap(roadmapContent, milestoneFilter) {
     // `{ ok: false, reason }`, not an exception — so the catch was masking
     // nothing but dead code paths. Removed per ADR-2143 §5; the public
     // `RoadmapProgress` contract (nulls = absent) is unchanged.
-    const table = locateProgressTable(roadmapContent);
+    // #5165: the milestone-grouped Progress table keeps every milestone's rows,
+    // shipped ones included; the owner returns only the named milestone's slice.
+    // A named milestone that matches no row yields nulls (nothing countable)
+    // rather than a foreign count.
+    const { table, rows: scopedRows } = (0, roadmap_progress_cjs_1.locateRoadmapProgress)(roadmapContent, { milestone: milestoneFilter });
     if (table) {
-        // #5165: the milestone-grouped Progress table (templates/roadmap.md) keeps
-        // every milestone's rows, shipped ones included. When the caller names the
-        // milestone and the table carries a `Milestone` column, count only that
-        // milestone's rows. A table without the column (or a caller without a
-        // milestone) keeps the whole-table behavior; a named milestone that matches
-        // no row yields nulls (nothing countable) rather than a foreign count.
-        const wantMilestone = normalizeMilestoneToken(milestoneFilter);
-        const scopedRows = wantMilestone !== '' && table.columns.includes('Milestone')
-            ? table.rows.filter((r) => normalizeMilestoneToken(r['Milestone']) === wantMilestone)
-            : table.rows;
         // Data rows only (exclude sentinel phases 0 and 999.x).
         // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
         const dataRows = scopedRows.filter((r) => {

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

@@ -6,15 +6,25 @@
  * Owns active-phase discovery against the `.planning/phases/` tree
  * (`searchPhaseInDir`, `findPhaseInternal`) and archived-phase-dir
  * enumeration (`getArchivedPhaseDirs`), matching phase ids/tokens against
- * the filesystem. Behaviour is preserved byte-for-behaviour from the prior
- * location; only the module boundary moved. The core.cjs re-export spine
+ * the filesystem. Also owns the silent naming projection and shared writer
+ * tail (preflight, containment, directory creation, identity markers).
+ * The core.cjs re-export spine
  * was retired in epic #1267; callers import phase-locator helpers directly.
  *
- * Dependencies (leaf modules only — no loadConfig):
+ * Dependencies:
  *   - node:fs / node:path (stdlib)
- *   - ./phase-id.cjs       (normalizePhaseName, matchPhaseDirs, phaseNumberForMatch)
+ *   - ./phase-id.cjs       (phaseDirectoryContext, customPhaseQuery, customPhaseDirectoryParts,
+ *                           normalizePhaseName, matchPhaseDirs, phaseNumberForMatch)
+ *   - ./phase-id-display.cjs (milestone numeric canonicalization)
  *   - ./core-utils.cjs     (readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath)
- *   - ./planning-workspace.cjs (planningDir)
+ *   - ./planning-workspace.cjs (planningDir, resolvePhaseIdConvention)
+ *   - ./config-loader.cjs (CONFIG_DEFAULTS, _deepMergeConfig, _getConfigValue;
+ *                          silent file-selection projection; loadConfig for the
+ *                          active bracket project code)
+ *   - ./runtime-homes.cjs (resolveGsdHome)
+ *   - ./frontmatter.cjs / ./plan-dependency-graph.cjs (plan dependency evidence)
+ *   - ./roadmap-parser.cjs / ./planning-scope.cjs (milestone membership/scope)
+ *   - ./io.cjs / ./shell-command-projection.cjs (typed write errors and files)
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -22,14 +32,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { error, ERROR_REASON } = ioMod;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs, phaseNumberForMatch, isSentinelPhaseId, comparePhaseNum } = phaseIdModule;
+const { BRACKET_DIR_PREFIX_SRC, CUSTOM_PHASE_ID_FILE, comparePhaseNum, customPhaseDirectoryParts, customPhaseQuery, foldBracketId, isSentinelPhaseId, matchPhaseDirs, normalizePhaseName, parsePhaseId, phaseDirectoryContext, phaseNumberForMatch, } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtilsModule = require("./core-utils.cjs");
 const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath, findUnsummarizedPlans } = coreUtilsModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir, planningRoot } = planningWorkspace;
+const { planningDir, planningRoot, resolveEnvWorkstream, resolvePhaseIdConvention } = planningWorkspace;
+// Naming readers and writers share the loader's scoped-key precedence and defaults.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderModule = require("./config-loader.cjs");
+const { CONFIG_DEFAULTS, _deepMergeConfig, _getConfigValue, loadConfig } = configLoaderModule;
+const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterModule = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatterModule;
@@ -38,10 +57,17 @@ const planDependencyGraphModule = require("./plan-dependency-graph.cjs");
 const { computeHaltPropagation, buildSummaryFileIndex, isSummaryFileHalted, isSummaryFileBlocked } = planDependencyGraphModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserModule = require("./roadmap-parser.cjs");
-const { getMilestonePhaseFilter } = roadmapParserModule;
+const { getMilestoneInfo, getMilestonePhaseFilter } = roadmapParserModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdDisplayModule = require("./phase-id-display.cjs");
+const { milestoneToken, phaseToken } = phaseIdDisplayModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
+// #4304: result shaping must distinguish a canonical bracket directory from a
+// legacy directory that matchPhaseDirs deliberately still admits during a
+// bracket migration. Derive that distinction from the exported owner grammar.
+const BRACKET_DIRECTORY_PREFIX_RE = new RegExp(`^${BRACKET_DIR_PREFIX_SRC}`);
 /**
  * #2830: parse a plan file's `depends_on` frontmatter. Returns [] — never
  * throws — on a missing/unreadable/malformed plan or absent field, matching
@@ -64,6 +90,75 @@ function parsePlanDependsOn(phaseDir, planFile) {
         return [];
     }
 }
+/**
+ * Resolve the convention and active bracket identity once for every current-
+ * checkout phase-directory lookup. A caller-provided convention takes priority
+ * over config resolution. Legacy callers receive the exact historical
+ * normalization and no context. A partially configured bracket repo degrades
+ * to the ambiguity-safe unqualified matcher rather than inventing an identity.
+ */
+function resolvePhaseDirectoryLookup(cwd, phase, conventionOverride, directoryContext) {
+    const legacyNormalized = normalizePhaseName(phase);
+    const resolvedConvention = conventionOverride ?? resolvePhaseIdConvention(cwd);
+    // Custom ids have no padding form: the id is looked up as written.
+    if (directoryContext?.phaseNaming === 'custom' && resolvedConvention !== 'bracket') {
+        return {
+            normalized: typeof phase === 'string' ? phase : legacyNormalized,
+            legacyNormalized: undefined,
+            convention: undefined,
+            bracketContext: undefined,
+        };
+    }
+    if (resolvedConvention !== 'bracket') {
+        return {
+            normalized: legacyNormalized,
+            legacyNormalized: undefined,
+            convention: undefined,
+            bracketContext: undefined,
+        };
+    }
+    // The bracket writers canonicalize both numeric segments through phaseToken
+    // (`1.1` -> `01.01`). Finish the convention-only query normalization at
+    // this shared locator boundary while retaining normalizePhaseName's legacy
+    // decimal spelling (`01.1`) as the second-pass migration fallback. Every
+    // other convention and already-canonical bracket form remains single-pass.
+    const normalized = phaseToken(legacyNormalized) ?? legacyNormalized;
+    let bracketContext;
+    try {
+        const config = loadConfig(cwd);
+        const project = typeof config['project_code'] === 'string' ? config['project_code'].trim() : '';
+        const version = getMilestoneInfo(cwd).value?.version ?? '';
+        const milestone = milestoneToken(version);
+        if (project && milestone !== null)
+            bracketContext = { project, milestone };
+    }
+    catch {
+        // Read-side lookup remains non-throwing when config/milestone state is
+        // incomplete; matchPhaseDirs will surface ambiguity rather than guess.
+    }
+    return {
+        normalized,
+        legacyNormalized: normalized === legacyNormalized ? undefined : legacyNormalized,
+        convention: 'bracket',
+        bracketContext,
+    };
+}
+/**
+ * Apply one resolved lookup to a directory set. Bracket queries try the writer-
+ * canonical spelling first, then the pre-bracket `normalizePhaseName` spelling
+ * only when the canonical pass finds nothing. `matchPhaseDirs` remains the
+ * single selection owner for both passes, including its migration-window legacy
+ * fallback and ambiguity behavior. Non-bracket lookups have no second spelling.
+ */
+function matchPhaseDirsForLookup(dirs, lookup, bracketContextOverride, directoryContext) {
+    const bracketContext = bracketContextOverride === undefined
+        ? lookup.bracketContext
+        : bracketContextOverride;
+    const primary = matchPhaseDirs(dirs, lookup.normalized, lookup.convention, bracketContext, directoryContext);
+    if (primary.matches.length > 0 || lookup.legacyNormalized === undefined)
+        return primary;
+    return matchPhaseDirs(dirs, lookup.legacyNormalized, lookup.convention, bracketContext, directoryContext);
+}
 // ─── Phase search helpers ─────────────────────────────────────────────────────
 /**
  * #2855: single source of truth for resolving and enumerating a project's
@@ -146,7 +241,190 @@ function listArchiveVersionDirs(cwd, wsOverride) {
     }
     return out;
 }
-function searchPhaseInDir(baseDir, relBase, normalized, convention) {
+/** Effective naming is a silent projection; roadmap and marker reads are bounded. */
+function phaseDirectoryOptions(cwd, config, roadmap, ws) {
+    // These two flat keys have no legacy aliases and are not inherited from
+    // global defaults by loadConfig. Mirror only its file-selection branches,
+    // reusing its merge, value and default owners without warnings or write-back.
+    // Replace this projection if the loader gains a quiet option; parity tests
+    // guard workstream, project, corrupt-file and global-default precedence.
+    let naming = config;
+    let configError;
+    if (naming === undefined) {
+        const readConfig = (file) => {
+            try {
+                const value = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+                if (value && typeof value === 'object' && !Array.isArray(value))
+                    return value;
+                configError = { path: file, message: 'configuration must be a JSON object' };
+                return null;
+            }
+            catch (cause) {
+                if (cause.code !== 'ENOENT')
+                    configError = { path: file, message: cause.message };
+                return null;
+            }
+        };
+        const activeWs = ws === undefined ? resolveEnvWorkstream() : ws?.trim() || null;
+        const root = activeWs ? readConfig(node_path_1.default.join(planningRoot(cwd), 'config.json')) : null;
+        const scoped = readConfig(node_path_1.default.join(planningDir(cwd, activeWs), 'config.json'));
+        // A missing/broken workstream with a usable root recurses with ws:null in
+        // loadConfig, including GSD_PROJECT's own config rather than the flat root.
+        const parsed = scoped ? (root ? _deepMergeConfig(root, scoped) : scoped)
+            : root ? readConfig(node_path_1.default.join(planningDir(cwd, null), 'config.json')) : null;
+        naming = {
+            phase_naming: _getConfigValue(parsed ?? {}, 'phase_naming') ?? CONFIG_DEFAULTS.phase_naming,
+            project_code: _getConfigValue(parsed ?? {}, 'project_code') ?? CONFIG_DEFAULTS.project_code,
+        };
+    }
+    const context = phaseDirectoryContext(naming, roadmap ?? '');
+    if (configError)
+        context.configError = configError;
+    if (context.phaseNaming !== 'custom')
+        return context;
+    // Load directory-owned IDs once for this scope, including archive fallback.
+    // Old directories retain known heading hints. Mutations accept a unique
+    // owner and refuse ambiguous candidates before any deletion or rename.
+    context.directoryIdsByRoot = Object.create(null);
+    const unmarkedDirectories = [];
+    context.unmarkedDirectories = unmarkedDirectories;
+    const roots = [node_path_1.default.join(planningDir(cwd, ws), 'phases'), ...listArchiveVersionDirs(cwd, ws).map(entry => entry.archivePath)];
+    for (const root of roots) {
+        const ids = Object.create(null);
+        context.directoryIdsByRoot[root] = ids;
+        const directories = readSubdirectories(root, true);
+        for (const dir of directories) {
+            let identityFd;
+            try {
+                const markerPath = node_path_1.default.join(root, dir, CUSTOM_PHASE_ID_FILE);
+                const marker = node_fs_1.default.lstatSync(markerPath);
+                if (!marker.isFile() || marker.size > 1024)
+                    continue;
+                // Nonblocking/no-follow open also bounds a replacement between lstat and
+                // open; fstat validates the actual descriptor before reading at most 1 KiB.
+                // Windows may omit these flags: lstat/fstat still require a regular file,
+                // but the open is not atomically no-follow there. Adopt Windows no-follow
+                // flags here if Node exposes them; no caller should weaken these checks.
+                identityFd = node_fs_1.default.openSync(markerPath, node_fs_1.default.constants.O_RDONLY | node_fs_1.default.constants.O_NONBLOCK | node_fs_1.default.constants.O_NOFOLLOW);
+                const opened = node_fs_1.default.fstatSync(identityFd);
+                if (!opened.isFile() || opened.size > 1024)
+                    continue;
+                const buffer = Buffer.alloc(opened.size);
+                const count = node_fs_1.default.readSync(identityFd, buffer, 0, buffer.length, 0);
+                const id = buffer.toString('utf8', 0, count).trim();
+                if (id) {
+                    phaseIdModule.phaseDirectoryName(id, '');
+                    ids[dir] = id;
+                }
+            }
+            catch { /* An absent or unusable marker supplies no ownership proof. */ }
+            finally {
+                if (identityFd !== undefined)
+                    node_fs_1.default.closeSync(identityFd);
+            }
+        }
+        unmarkedDirectories.push(...directories.filter(dir => ids[dir] === undefined));
+    }
+    // Basenames can repeat across milestones with different ID/slug boundaries.
+    // Identity hints span the scope; authoritative records belong to one pool.
+    context.directoryIds = context.directoryIdsByRoot[roots[0]];
+    context.knownIds = [...new Set(Object.values(context.directoryIdsByRoot).flatMap(ids => Object.values(ids)))];
+    if (roadmap !== undefined)
+        return context;
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(node_path_1.default.join(planningDir(cwd, ws), 'ROADMAP.md'), 'r');
+        const buffer = Buffer.alloc(Math.min(node_fs_1.default.fstatSync(fd).size, 1024 * 1024));
+        const count = node_fs_1.default.readSync(fd, buffer, 0, buffer.length, 0);
+        return { ...context, roadmap: buffer.toString('utf8', 0, count) };
+    }
+    catch {
+        return context;
+    }
+    finally {
+        if (fd !== undefined)
+            node_fs_1.default.closeSync(fd);
+    }
+}
+const directoryPoolContexts = new WeakMap();
+/** Select records for this physical pool, reusing its context across queries. */
+function phaseDirectoryContextForRoot(context, root) {
+    const ids = context.directoryIdsByRoot?.[root];
+    if (!ids || ids === context.directoryIds)
+        return context;
+    let pools = directoryPoolContexts.get(context);
+    if (!pools) {
+        pools = new Map();
+        directoryPoolContexts.set(context, pools);
+    }
+    let selected = pools.get(root);
+    if (!selected) {
+        selected = { ...context, directoryIds: ids };
+        pools.set(root, selected);
+    }
+    return selected;
+}
+/** Usage guidance for every custom-ID writer, using the resolved naming policy. */
+function customPhaseNamingUsage(cwd, context) {
+    if (context.phaseNaming === 'custom')
+        return null;
+    if (context.configError)
+        return `Cannot read phase naming from ${context.configError.path}: ${context.configError.message}. Repair the project config before using a custom ID`;
+    let message = 'phase_naming is not custom for this project; configure phase_naming as "custom" before using a custom ID';
+    try {
+        const defaultsPath = node_path_1.default.join((0, runtime_homes_cjs_1.resolveGsdHome)(), '.gsd', 'defaults.json');
+        const defaults = JSON.parse(node_fs_1.default.readFileSync(defaultsPath, 'utf8'));
+        if (typeof defaults.phase_naming === 'string' && defaults.phase_naming.toLowerCase() === 'custom' && node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'config.json'))) {
+            message += `; project config shadows phase_naming from ${defaultsPath}`;
+        }
+    }
+    catch { /* Missing/unusable defaults do not change effective naming. */ }
+    return message;
+}
+/** Preflight the complete write set, then create directories and identity records. */
+function createPhaseDirectories(cwd, entries, context, gitkeep = true) {
+    const phasesRoot = node_path_1.default.resolve(planningDir(cwd), 'phases');
+    let prepared;
+    try {
+        const recorded = entries.filter(entry => entry.recordIdentity ?? context.phaseNaming === 'custom');
+        if (recorded.length > 0)
+            phaseIdModule.validateCustomPhaseIds(recorded.map(entry => entry.id), context);
+        const pendingPaths = new Set();
+        prepared = entries.map(entry => {
+            // Validate the raw ID before legacy scaffold normalization can discard it.
+            phaseIdModule.phaseDirectoryName(entry.id, '', context.projectCode);
+            const dirName = phaseIdModule.phaseDirectoryName(entry.directoryId ?? entry.id, entry.slug, context.projectCode);
+            const dirPath = node_path_1.default.resolve(phasesRoot, dirName);
+            if (node_path_1.default.dirname(dirPath) !== phasesRoot)
+                error('Phase directory escapes the phases directory', ERROR_REASON.USAGE);
+            const recordIdentity = entry.recordIdentity ?? context.phaseNaming === 'custom';
+            // An occupied target is a collision only where a custom writer would
+            // record an identity into it. Numeric writers keep the idempotent
+            // ensure-directory they always had.
+            if (recordIdentity && (pendingPaths.has(dirPath) || node_fs_1.default.lstatSync(dirPath, { throwIfNoEntry: false }) !== undefined)) {
+                throw new phaseIdModule.PhaseDirectoryNameError(`Phase directory ${dirName} already exists or is claimed by another pending entry; choose a distinct ID or title`, 'collision');
+            }
+            pendingPaths.add(dirPath);
+            return { ...entry, dirName, dirPath, recordIdentity };
+        });
+    }
+    catch (cause) {
+        if (cause instanceof phaseIdModule.PhaseDirectoryNameError) {
+            error(cause.message, cause.kind === 'collision' ? ERROR_REASON.PHASE_ID_COLLISION : ERROR_REASON.USAGE);
+        }
+        throw cause;
+    }
+    for (const entry of prepared) {
+        (0, shell_command_projection_cjs_1.platformEnsureDir)(entry.dirPath);
+        if (gitkeep)
+            (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(entry.dirPath, '.gitkeep'), '');
+        if (entry.recordIdentity)
+            (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(entry.dirPath, CUSTOM_PHASE_ID_FILE), entry.id);
+    }
+    return prepared;
+}
+function searchPhaseInDir(baseDir, relBase, normalized, convention, bracketContext, legacyNormalized, context = phaseDirectoryContext({})) {
+    context = phaseDirectoryContextForRoot(context, baseDir);
     try {
         const dirs = readSubdirectories(baseDir, true);
         // #2528: canonical two-pass selection (exact token match, then the
@@ -154,7 +432,12 @@ function searchPhaseInDir(baseDir, relBase, normalized, convention) {
         // phase-plan-index scans — see phase-id.cts::matchPhaseDirs.
         // #4801: the convention is threaded (optional) so bracket-convention
         // consumers get exact token matching here too.
-        const { matches, usedBareFallback } = matchPhaseDirs(dirs, normalized, convention);
+        const { matches, usedBareFallback } = matchPhaseDirsForLookup(dirs, {
+            normalized,
+            legacyNormalized,
+            convention: convention === 'bracket' ? 'bracket' : undefined,
+            bracketContext: bracketContext ?? undefined,
+        }, bracketContext, context);
         if (matches.length === 0)
             return null;
         // #2237: fail loud when multiple directories match the same bare phase
@@ -182,10 +465,26 @@ function searchPhaseInDir(baseDir, relBase, normalized, convention) {
             };
         }
         const match = matches[0];
-        const phaseToken = phaseNumberForMatch(match, usedBareFallback);
+        const isBracketDirectory = convention === 'bracket'
+            && BRACKET_DIRECTORY_PREFIX_RE.test(foldBracketId(match));
+        const resultConvention = isBracketDirectory ? 'bracket' : undefined;
+        const custom = convention === 'bracket' ? null : customPhaseQuery(normalized, context);
+        const parts = custom ? customPhaseDirectoryParts(match, custom) : null;
+        const phaseToken = parts?.id || phaseNumberForMatch(match, usedBareFallback, resultConvention);
         const phaseNumber = phaseToken || normalized;
-        const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
-        const phaseName = afterToken || null;
+        let afterToken;
+        if (isBracketDirectory) {
+            const id = parsePhaseId(match);
+            const idToken = `${id.phase}${id.subphase ? `.${id.subphase}` : ''}`;
+            const bracketPrefix = `${id.project}.${id.milestone}-${idToken}`;
+            afterToken = match.slice(bracketPrefix.length).replace(/^-/, '');
+        }
+        else {
+            // Exact pre-#4304 legacy shaping, including project-prefixed and bare
+            // fallback matches. Bracket mode changes selection, not these bytes.
+            afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
+        }
+        const phaseName = parts?.slug || afterToken || null;
         const phaseDir = node_path_1.default.join(baseDir, match);
         const { plans: unsortedPlans, summaries: unsortedSummaries, hasResearch, hasContext, hasVerification, hasReviews } = getPhaseFileStats(phaseDir);
         const plans = unsortedPlans.sort();
@@ -283,14 +582,16 @@ function searchPhaseInDir(baseDir, relBase, normalized, convention) {
         return null;
     }
 }
-function findPhaseInternal(cwd, phase, convention) {
+function findPhaseInternal(cwd, phase, convention, context) {
     if (!phase)
         return null;
+    // Existing callers may omit context; multi-phase readers supply one reusable context.
+    context ??= phaseDirectoryOptions(cwd);
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
-    const normalized = normalizePhaseName(phase);
+    const { normalized, legacyNormalized, convention: lookupConvention, bracketContext, } = resolvePhaseDirectoryLookup(cwd, phase, convention, context);
     const relPhasesDir = toPosixPath(node_path_1.default.relative(cwd, phasesDir));
     // #4801: convention threaded through to the matcher (see searchPhaseInDir).
-    const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized, convention);
+    const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized, lookupConvention, bracketContext, legacyNormalized, context);
     if (current)
         return current;
     // #2855: scope the archived-milestone fallback to the SAME workstream as the
@@ -304,7 +605,7 @@ function findPhaseInternal(cwd, phase, convention) {
     // getArchivedPhaseDirs via listArchiveVersionDirs (see its doc comment).
     for (const { version, archivePath } of listArchiveVersionDirs(cwd)) {
         const relBase = toPosixPath(node_path_1.default.relative(cwd, archivePath));
-        const result = searchPhaseInDir(archivePath, relBase, normalized, convention);
+        const result = searchPhaseInDir(archivePath, relBase, normalized, lookupConvention, null, legacyNormalized, context);
         if (result) {
             result.archived = version;
             return result;
@@ -366,10 +667,12 @@ function listMilestonePhaseDirs(phasesDir, opts = {}) {
     // Without a cwd there is nothing to scope AGAINST — the caller asked for an
     // unscoped read, which is a real answer (mirrors extractCurrentMilestoneScoped's
     // row 1). Sentinels are still refused: they are never milestone phases.
+    let directoryContext;
     let inWindow = () => true;
     let scope = SCOPE.COMPLETE;
     if (cwd) {
-        const filter = getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws);
+        directoryContext = phaseDirectoryOptions(cwd, undefined, undefined, ws);
+        const filter = getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws, directoryContext);
         inWindow = filter;
         scope = filter.scope;
     }
@@ -392,7 +695,7 @@ function listMilestonePhaseDirs(phasesDir, opts = {}) {
     }
     const value = names
         .filter((name) => inWindow(name) && !isSentinelPhaseId(name, phaseIdConvention ?? undefined))
-        .sort((a, b) => comparePhaseNum(a, b));
+        .sort((a, b) => comparePhaseNum(a, b, directoryContext));
     return { value, scope };
 }
 /**
@@ -497,7 +800,13 @@ function getAllArchivedPhaseDirs(cwd) {
     return out;
 }
 module.exports = {
+    createPhaseDirectories,
+    phaseDirectoryOptions,
+    phaseDirectoryContextForRoot,
+    customPhaseNamingUsage,
     searchPhaseInDir,
+    resolvePhaseDirectoryLookup,
+    matchPhaseDirsForLookup,
     findPhaseInternal,
     getArchivedPhaseDirs,
     getAllArchivedPhaseDirs,