@opengsd/gsd-core 1.19.0 → 1.20.1

package/gsd-core/bin/lib/install-manifest-record.cjs

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Install manifest per-file hash ownership (#5683).
+ *
+ * `gsd-file-manifest.json` records `sha256(file bytes)` per installed file,
+ * keyed by path relative to the runtime config dir. `effort sync --apply`
+ * rewrites installed agents, so it re-records exactly those files here.
+ * `bin/install.js` fileHash delegates to this module: one hash function.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileHash = fileHash;
+exports.tryFileHash = tryFileHash;
+exports.recordManifestFileHashes = recordManifestFileHashes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const MANIFEST_NAME = 'gsd-file-manifest.json';
+/** SHA256 (lowercase hex) of a file's bytes — the manifest's per-file hash. */
+function fileHash(filePath) {
+    return (0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(filePath)).digest('hex');
+}
+/** fileHash that returns null instead of throwing — for capturing a pre-rewrite hash. */
+function tryFileHash(filePath) {
+    try {
+        return fileHash(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Update ONLY the manifest entries for `rewritten` files (under `configDir`),
+ * and only those that were GSD-owned before the rewrite: `preHash` equal to the
+ * recorded manifest entry. A file the user had already edited keeps its stale
+ * entry so the next install still detects it and backs it up.
+ * Skips silently (returns false) when the manifest is absent, unparseable or
+ * not the documented shape; publishes via tmp + rename.
+ */
+function recordManifestFileHashes(configDir, rewritten) {
+    if (rewritten.length === 0)
+        return false;
+    const manifestPath = (0, node_path_1.join)(configDir, MANIFEST_NAME);
+    let manifest;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        manifest = parsed;
+    }
+    catch {
+        return false;
+    }
+    const files = manifest['files'];
+    if (!files || typeof files !== 'object' || Array.isArray(files))
+        return false;
+    const entries = files;
+    let changed = false;
+    for (const { path: absPath, preHash } of rewritten) {
+        const rel = (0, node_path_1.relative)(configDir, absPath).replace(/\\/g, '/');
+        if (rel === '' || rel.startsWith('..') || (0, node_path_1.isAbsolute)(rel))
+            continue;
+        if (preHash === null || entries[rel] !== preHash)
+            continue;
+        try {
+            entries[rel] = fileHash(absPath);
+            changed = true;
+        }
+        catch { /* unreadable file: leave its entry as recorded */ }
+    }
+    if (!changed)
+        return false;
+    const tmpPath = `${manifestPath}.tmp.${process.pid}`;
+    try {
+        (0, node_fs_1.writeFileSync)(tmpPath, JSON.stringify(manifest, null, 2));
+        (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, manifestPath);
+        return true;
+    }
+    catch {
+        try {
+            (0, node_fs_1.unlinkSync)(tmpPath);
+        }
+        catch { /* already gone or never created */ }
+        return false;
+    }
+}

package/gsd-core/bin/lib/install-profiles.cjs

@@ -35,7 +35,7 @@ const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs
 const capabilityLedger = require("./capability-ledger.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const conversionModule = require("./runtime-artifact-conversion.cjs");
-const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, appendAgentTools: _appendAgentTools, } = conversionModule;
+const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, appendAgentTools: _appendAgentTools, _shieldAgentConverterPrefix, } = conversionModule;
 // #2995 (epic #1671 Phase 6.4): agent bodies join the fragment model. Markers are
 // stripped at emit BEFORE any path rewrite or converter runs, so a `.claude/` ->
 // `.windsurf/` regex can never reach inside a marker attribute and corrupt it —
@@ -1011,7 +1011,9 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
                 // Step 3: validated canonical grants, before host conversion.
                 content = _appendAgentTools(content, grants);
                 // Step 4: converter (runtime-specific frontmatter/body transform)
-                content = converter(content, isGlobal, { agentName });
+                // #5715: the converter runs after the prefix pass above; shield the emitted prefix
+                // from it, except where the runtime declares no path rewrite (nothing was emitted).
+                content = _shieldAgentConverterPrefix(content, agentCtx.runtime, agentCtx.pathPrefix, (shielded) => converter(shielded, isGlobal, { agentName, pathPrefix: agentCtx.pathPrefix }));
                 // Step 5: frontmatter extensions (effort/disallowedTools; no-op unless
                 // the runtime declares hostBehaviors.agentFrontmatterExtensions)
                 content = _applyAgentFrontmatterExtensions(content, { runtime: agentCtx.runtime, agentName, targetDir: agentCtx.targetDir });

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})` }] };
             }

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

@@ -38,7 +38,7 @@ const stateContract = require("./state-contract.cjs");
 const { publishStateContract } = stateContract;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs, isSentinelPhaseId, isSentinelPhaseDir, buildPhaseHeadingScanRegex, PHASE_HEADING_BASELINE } = phaseIdMod;
+const { isSentinelPhaseId, isSentinelPhaseDir, buildPhaseHeadingScanRegex, PHASE_HEADING_BASELINE } = phaseIdMod;
 const pattern_cjs_1 = require("./pattern.cjs");
 const milestone_release_map_cjs_1 = require("./milestone-release-map.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -55,7 +55,7 @@ const planScanMod = require("./plan-scan.cjs");
 const { scanPhasePlans } = planScanMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { listMilestonePhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, listMilestonePhaseDirs, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
 const { planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 // ADR-3408 §8.3 / #3469: `writeStateMd` gets sync and NO preservation — the
@@ -73,43 +73,6 @@ const { syncAndPreserveStateMd, withStateLock, readModifyWriteStateMd, assertVer
 // the caller-supplied `--archive-version` override and the STATE.md-derived
 // live-read value, so a crafted value cannot escape `.planning/milestones/`.
 const ARCHIVE_VERSION_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-/**
- * Scope an `updateTableCell` call to the `## Traceability` (or
- * `## Traceability Status`) heading's own section — up to the next H1/H2
- * heading — instead of handing it the WHOLE REQUIREMENTS.md content.
- *
- * F1 (#2245 review, BLOCKER): `updateTableCell` binds to the FIRST GFM table
- * found in whatever text it is given. The shipped requirements template
- * (gsd-core/templates/requirements.md) puts an `## Out of Scope` table
- * (`| Feature | Reason |`, no `Status` column) BEFORE `## Traceability` — so
- * an unscoped whole-file call targets the Out-of-Scope table instead, fails
- * with `{ok:false, reason:'unknown column: Status'}`, and the real
- * Traceability row is never flipped, while the checkbox surface still flips
- * and the command reports success (the #2140 silent-divergence class one
- * level deeper). Mirrors phase.cts's `editProgressHeadingSlice` scoping of
- * `## Progress` writes to that heading's own slice.
- *
- * Falls back to running `updateTableCell` against the whole `text` when no
- * `## Traceability` heading exists — matching the previous (unscoped)
- * behaviour for a REQUIREMENTS.md whose traceability table sits under some
- * other heading, or with no heading at all (never worse than before this fix).
- */
-function updateTraceabilityCell(text, match, column, newValue) {
-    const headingMatch = text.match(/^##[ \t]+Traceability(?:[ \t]+Status)?\b/im);
-    if (!headingMatch || headingMatch.index === undefined) {
-        return (0, markdown_table_cjs_1.updateTableCell)(text, match, column, newValue);
-    }
-    const headingOffset = headingMatch.index;
-    const before = text.slice(0, headingOffset);
-    const fromHeading = text.slice(headingOffset);
-    const nextHeadingOffset = fromHeading.search(/\n#{1,2}[ \t]/);
-    const scoped = nextHeadingOffset >= 0 ? fromHeading.slice(0, nextHeadingOffset) : fromHeading;
-    const after = nextHeadingOffset >= 0 ? fromHeading.slice(nextHeadingOffset) : '';
-    const result = (0, markdown_table_cjs_1.updateTableCell)(scoped, match, column, newValue);
-    if (!result.ok)
-        return result;
-    return { ok: true, value: before + result.value + after };
-}
 function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     if (!reqIdsRaw || reqIdsRaw.length === 0) {
         error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
@@ -187,7 +150,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // Complete" gate is folded into the newValue callback so one
         // updateTableCell call both probes the current value and writes.
         let tableHit = false;
-        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const tableUpdate = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             // #2788: accept `Gaps Found` as a forward input too — `revert-phase` (the
             // documented gaps_found response) leaves a row stranded at Gaps Found with
             // no inverse; a genuinely-satisfied requirement must be able to reach
@@ -230,7 +193,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // that genuinely exists. Probe via a no-op updateTableCell write (its own
         // tolerant scan) instead of findTableWithColumns (whole-table parse gate).
         let currentStatusCell = '';
-        const statusProbe = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const statusProbe = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             currentStatusCell = current;
             return current;
         });
@@ -434,7 +397,7 @@ function cmdRequirementsRevertPhase(cwd, reqIdsRaw, raw) {
         // "only flip Pending -> Complete" gate, in reverse).
         const rowMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === reqId.toLowerCase();
         let tableHit = false;
-        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+        const tableUpdate = (0, markdown_table_cjs_1.updateTraceabilityCell)(reqContent, rowMatch, 'Status', (current) => {
             if (/^complete$/i.test(current.trim())) {
                 tableHit = true;
                 return ' Gaps Found ';
@@ -585,7 +548,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // `platformEnsureDir(archiveDir)` below — a refused run (scope not COMPLETE,
     // no --force) must be a true no-op on disk, and creating the archive
     // directory first left an empty directory behind even on refusal.
-    const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
+    const isDirInMilestone = getMilestonePhaseFilter(cwd, version, undefined, undefined, phaseDirectoryOptions(cwd));
     if (isDirInMilestone.missingExplicitVersion) {
         error(`no phases found for milestone ${version} in ROADMAP.md`);
     }
@@ -610,6 +573,10 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             `entries, even though the ROADMAP has phase entries elsewhere), so phase scoping ` +
             `cannot be trusted for this destructive operation. Re-run with --force to override.`);
     }
+    // #2761/#4304: resolve once for every phase-directory consumer in this
+    // command. The matcher opts in only for bracket; the milestone enumerator
+    // retains the full resolved value it already accepted.
+    const phaseConvention = resolvePhaseIdConvention(cwd);
     // Guard: prevent marking complete when ROADMAP still lists phases that have
     // no directory on disk (disk_status: no_directory). This catches the case
     // where the active milestone was erroneously marked complete before phases
@@ -691,8 +658,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             // properly-scaffolded bracket phase reads as disk_status: 'no_directory'
             // — turning a real bracket project's own phases into false "ROADMAP
             // lists N unstarted phase(s)" failures on `milestone complete`.
-            const convention = resolvePhaseIdConvention(cwd);
-            const { regex: phasePattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, convention);
+            const directoryContext = phaseDirectoryOptions(cwd, undefined, scopedContent);
+            const { regex: phasePattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.ANY_BRACKET, phaseConvention, directoryContext);
             const noDirectoryPhases = [];
             let pm;
             const phaseDirEntries = (() => {
@@ -716,12 +683,14 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this local check already covered both 0 and 999; now delegates to the single canonical owner.
                 if (isSentinelPhaseId(phaseNum))
                     continue;
-                const normalized = normalizePhaseName(phaseNum);
+                const lookup = resolvePhaseDirectoryLookup(cwd, phaseNum, undefined, directoryContext);
                 // A phase has disk_status: 'no_directory' when no phase directory
                 // with a matching token exists on disk. Use the same matchPhaseDirs
                 // owner that roadmap.analyze uses to avoid false positives on decimal
-                // (2.1) and letter-suffix (12A) phase IDs. (#2528)
-                const hasDirectory = matchPhaseDirs(phaseDirEntries, normalized, convention).matches.length > 0;
+                // (2.1) and letter-suffix (12A) phase IDs. (#2528) Under #4304 the
+                // current checkout's bracket convention and migration-window legacy
+                // fallback are both owned by the shared lookup adapter.
+                const hasDirectory = matchPhaseDirsForLookup(phaseDirEntries, lookup, undefined, directoryContext).matches.length > 0;
                 if (!hasDirectory) {
                     noDirectoryPhases.push(phaseNum);
                 }
@@ -751,7 +720,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     let totalPlans = 0;
     let totalTasks = 0;
     const accomplishments = [];
-    // #2761 (round-11 BLOCKER): resolved ONCE, ambiently (no explicit `ws` —
+    // #2761: resolved ONCE above, ambiently (no explicit `ws` —
     // this function has none of its own and already resolves everything else
     // off `cwd` via planningPaths(cwd), matching the ambient-workstream
     // contract `resolvePhaseIdConvention`/`planningDir` share), and threaded
@@ -766,7 +735,6 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // the silent-inherit path without changing behavior for `null` /
     // `milestone-prefixed` projects, whose resolved convention is the same
     // value `undefined` would have lazily produced anyway.
-    const phaseConvention = resolvePhaseIdConvention(cwd);
     // #3597 (ADR-3180 Decision 2): SINGLE resolution of "which phase
     // directories belong to the current milestone" AND the SCOPE discriminator
     // that resolution came from — shared verbatim by the read-only stats loop

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

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Phase-entry grammar — the one definition of a ROADMAP phase-list entry
+ * (`- [ ] **Phase 1: Name**`): bullet marker, checkbox, bold token and line
+ * anchoring (#5763, Phase 3 of epic #5692; census in #5703).
+ *
+ * Before this module every reader owned a private pattern, and the patterns
+ * disagreed on each axis (`-` only vs `[-*]`; required, optional or `\*{0,2}`
+ * bold; `[ x]` vs `[ xX]` vs `(x| )`; `^`-anchored vs the unanchored forms
+ * behind #4965 and #5545). Readers now compose their pattern from the prefix
+ * built here and keep only their own tail (label, id token, separator).
+ *
+ * The accepted grammar:
+ *   entry  := indent marker mgap box gap bold? gap <caller tail>
+ *   indent := [ \t]*                   — an entry starts its line
+ *   marker := '-' | '*'
+ *   mgap   := [ \t]{1,4}               — a list item: `-[ ]` is not one (#5764)
+ *   box    := '[' (' ' | 'x' | 'X') ']'
+ *   bold   := '**' | '__'              — a reader may require it
+ *   gap    := [ \t]*                   — horizontal whitespace only
+ * A reader that needs plain `- **Phase N**` bullets may make the box optional.
+ *
+ * Writers (flip, delete, renumber, id rewrite) compose their patterns here too
+ * (#5764, Phase 4): `phaseEntryRegExp` for a whole-line match and
+ * `phaseEntrySplitRegExp` when the writer rewrites the box and needs the text on
+ * either side of it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PHASE_ENTRY_BOLD_CLOSE_SRC = exports.PHASE_ENTRY_BOLD_TOKEN_SRC = void 0;
+exports.phaseEntryPrefixSrc = phaseEntryPrefixSrc;
+exports.phaseEntryRegExp = phaseEntryRegExp;
+exports.phaseEntrySplitRegExp = phaseEntrySplitRegExp;
+exports.isPhaseEntryChecked = isPhaseEntryChecked;
+exports.isBoxCharChecked = isBoxCharChecked;
+const MARKER_SRC = '[-*]';
+// A list item has 1 to 4 spaces or tabs after its marker (CommonMark: none is not a list item,
+// five or more makes the rest an indented code block), so `-[ ] **Phase 1**` is not an entry.
+const MARKER_GAP_SRC = '[ \\t]{1,4}';
+const BOLD_TOKEN_SRC = '(?:\\*\\*|__)';
+/** Regex source of one bold token, for a reader that must also consume the closing wrapper. */
+exports.PHASE_ENTRY_BOLD_TOKEN_SRC = BOLD_TOKEN_SRC;
+/**
+ * Regex source of a closing bold wrapper for a reader that captures the entry's
+ * name up to it. `**` closes anywhere; `__` closes only at the end of the line,
+ * so a name that contains `__init__` or `__tests__` is not cut short.
+ */
+exports.PHASE_ENTRY_BOLD_CLOSE_SRC = '(?:\\*\\*|__(?=[ \\t]*\\r?$))';
+/**
+ * Line start, indent, marker and the marker's gap, up to where the box opens.
+ * A leading BOM can only precede the first line; it is not part of the grammar's indent.
+ */
+const LINE_OPEN_SRC = `^\\uFEFF?[ \\t]*${MARKER_SRC}${MARKER_GAP_SRC}`;
+/**
+ * Source for the bold token and its trailing gap. `(?:token[ \t]*)?` rather than
+ * `[ \t]*` + token + `[ \t]*`, which backtracks quadratically on a long blank run.
+ */
+function boldSrcFor(bold) {
+    return bold === 'required' ? `${BOLD_TOKEN_SRC}[ \\t]*` : `(?:${BOLD_TOKEN_SRC}[ \\t]*)?`;
+}
+/** Source for the box interior, honouring the requested state filter. */
+function stateSrc(state) {
+    if (state === 'unchecked')
+        return ' ';
+    if (state === 'checked')
+        return '[xX]';
+    if (state === 'captured')
+        return '([ xX])';
+    return '[ xX]';
+}
+/**
+ * Regex source of everything before the caller's `Phase`/label tail: line start, indent,
+ * marker, box, bold token and the horizontal gaps between them. A `captured`
+ * state adds exactly one capture group (the box character) at the front.
+ */
+function phaseEntryPrefixSrc(options = {}) {
+    const { bold = 'optional', box = 'required', state = 'any', decorated = false } = options;
+    // The decoration may not contain the word `Phase`, so the entry's own label is the first one
+    // on the line and `- [ ] **Phase 5**: needs Phase 2` is not an entry of phase 2. No gap
+    // before the run: `[ \t]*` then a lazy run overlap and backtrack quadratically.
+    if (decorated)
+        return `${LINE_OPEN_SRC}\\[${stateSrc(state)}\\](?:(?!Phase)[^\\r\\n])*?`;
+    const boxSrc = `\\[${stateSrc(state)}\\][ \\t]*`;
+    const body = box === 'optional' ? `(?:${boxSrc})?` : boxSrc;
+    return `${LINE_OPEN_SRC}${body}${boldSrcFor(bold)}`;
+}
+/**
+ * A RegExp for a phase entry: the grammar prefix followed by the caller's
+ * `tailSrc`. The `m` flag is always set, so `^` is a line start.
+ */
+function phaseEntryRegExp(tailSrc, flags = '', options = {}) {
+    const withM = flags.includes('m') ? flags : `${flags}m`;
+    return new RegExp(`${phaseEntryPrefixSrc(options)}${tailSrc}`, withM);
+}
+/**
+ * A RegExp for a phase entry a writer rewrites at the box: capture group 1 is
+ * everything through the opening `[` (indent, marker, gap) and capture group 2
+ * is everything from the closing `]` through the end of `tailSrc` (gap, bold
+ * token, label). A flip is `line.replace(re, '$1x$2')`; the box state itself is
+ * matched, not captured, so the writer chooses the new state. The `m` flag is
+ * always set.
+ */
+function phaseEntrySplitRegExp(tailSrc, flags = '', options = {}) {
+    const { bold = 'optional', state = 'any' } = options;
+    const withM = flags.includes('m') ? flags : `${flags}m`;
+    return new RegExp(`(${LINE_OPEN_SRC}\\[)${stateSrc(state)}(\\][ \\t]*${boldSrcFor(bold)}${tailSrc})`, withM);
+}
+const ENTRY_BOX_RE = new RegExp(`^\\uFEFF?[ \\t]*${MARKER_SRC}${MARKER_GAP_SRC}\\[([ xX])\\]`);
+/**
+ * Whether a phase entry line (or a regex match of one, which starts at the
+ * line) is ticked. The single place the box character is interpreted.
+ */
+function isPhaseEntryChecked(entryText) {
+    const m = ENTRY_BOX_RE.exec(entryText);
+    return m !== null && m[1].toLowerCase() === 'x';
+}
+/** Whether a captured box character (`captured` state option) is a tick. */
+function isBoxCharChecked(boxChar) {
+    return boxChar.toLowerCase() === 'x';
+}

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

@@ -75,4 +75,6 @@ function renderBracketMilestoneDisplay(milestone, projectCode) {
 module.exports = {
     renderBracketPhaseDisplay,
     renderBracketMilestoneDisplay,
+    milestoneToken,
+    phaseToken,
 };