@opengsd/gsd-core 1.9.0 → 1.10.0

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

@@ -27,6 +27,9 @@
  * the additive, importable server surface a host (or the bin shim) drives.
  */
 'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_NAME = exports.PROTOCOL_VERSION = void 0;
 exports.handleMessage = handleMessage;
@@ -36,9 +39,62 @@ const stateIo = require("./state-io.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCommandProjection = require("./shell-command-projection.cjs");
 const { dispatchGsdCommand } = shellCommandProjection;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const mcp_catalog_cjs_1 = require("./mcp-catalog.cjs");
 exports.PROTOCOL_VERSION = '2024-11-05';
 exports.SERVER_NAME = 'gsd-core';
-const SERVER_VERSION = '1.7.0';
+// #3072: resolve SERVER_VERSION from package.json (source tree) or the
+// installed gsd-core/VERSION marker, WITHOUT a top-level `require(...)` —
+// mirrors the established, already-precedented resolver in
+// `runtime-artifact-conversion.cts`'s `gsdVersion()` (#1383): a top-level
+// require would throw on any runtime whose root has no package.json/VERSION,
+// and `scripts/sync-manifest-versions.cjs` is not a fit here — its
+// `VERSIONED_MANIFESTS` list stamps a `version` FIELD into hand-authored JSON
+// manifests (plugin.json, marketplace.json, vscode/package.json); a `.cts`
+// source constant is not a JSON document that script can round-trip through
+// `readJson`/`setByPath`, and teaching it to text-edit TypeScript source
+// would be a much larger footprint than this lazy, cached, defensive read.
+// Resolved once per process (never per-request) and cached; a failed lookup
+// degrades to '0.0.0' (never `undefined`, never a crash) rather than making
+// `initialize`'s `serverInfo.version` field absent or malformed.
+const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+let cachedServerVersion;
+function resolveServerVersion() {
+    if (cachedServerVersion !== undefined)
+        return cachedServerVersion;
+    let version = '0.0.0';
+    try {
+        const v = node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, '..', '..', 'VERSION'), 'utf8').trim();
+        if (SEMVER_PREFIX.test(v))
+            version = v;
+    }
+    catch {
+        /* not an installed tree (no gsd-core/VERSION) */
+    }
+    if (version === '0.0.0') {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy, defensive: a top-level require would throw on a runtime root with no package.json.
+            const pkg = require(node_path_1.default.join(__dirname, '..', '..', '..', 'package.json'));
+            if (pkg && typeof pkg.version === 'string' && SEMVER_PREFIX.test(pkg.version))
+                version = pkg.version;
+        }
+        catch {
+            /* runtime root has no package.json */
+        }
+    }
+    cachedServerVersion = version;
+    return version;
+}
+// Catalog is built once per process, lazily, and cached (design "Shape" /
+// Gall's Law — no watching, no invalidation; Known limits: the package is
+// immutable in every install mode we ship).
+let cachedCatalog;
+function getCatalog() {
+    if (cachedCatalog === undefined)
+        cachedCatalog = (0, mcp_catalog_cjs_1.buildCatalog)();
+    return cachedCatalog;
+}
 // JSON-RPC 2.0 error codes.
 const PARSE_ERROR = -32700;
 const INVALID_REQUEST = -32600;
@@ -93,6 +149,32 @@ function okResponse(id, result) {
 function asString(v) {
     return typeof v === 'string' ? v : null;
 }
+/** Extract the {@link REASON} carried by a `CatalogError`, if any (see `mcp-catalog.cts`). */
+function catalogErrorReason(err) {
+    const reason = err && typeof err === 'object' ? err.reason : undefined;
+    return typeof reason === 'string' ? reason : undefined;
+}
+function catalogErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Map a `mcp-catalog.cts` `CatalogError.reason` to a JSON-RPC error code.
+ * `READ_FAILED` is a server-side IO/compose failure (`INTERNAL_ERROR`);
+ * every other reason (unknown uri/prompt/cursor/root, malformed/traversal
+ * uri, wrong-typed param) is a client-supplied-value problem (`INVALID_PARAMS`)
+ * — deliberately never `METHOD_NOT_FOUND`, so a refusal is never
+ * indistinguishable from the method simply not existing (test-matrix rows
+ * 33/35).
+ */
+function catalogErrorCode(err) {
+    return catalogErrorReason(err) === mcp_catalog_cjs_1.REASON.READ_FAILED ? INTERNAL_ERROR : INVALID_PARAMS;
+}
+function wireResource(entry) {
+    return { uri: entry.uri, name: entry.name, title: entry.title, description: entry.description, mimeType: entry.mimeType };
+}
+function wirePrompt(entry) {
+    return { name: entry.name, title: entry.title, description: entry.description };
+}
 function callTool(name, args, ctx) {
     const a = (args && typeof args === 'object' ? args : {});
     const cwd = asString(ctx.cwd) || process.cwd();
@@ -148,8 +230,12 @@ function handleMessage(request, ctx = {}) {
         case 'initialize':
             result = {
                 protocolVersion: exports.PROTOCOL_VERSION,
-                capabilities: { tools: {} },
-                serverInfo: { name: exports.SERVER_NAME, version: SERVER_VERSION },
+                // #3072: resources/prompts declared alongside tools. Deliberately NO
+                // subscribe/listChanged — nothing ever sends those notifications
+                // (design row 2 / Hyrum's Law: advertising an unimplemented
+                // notification is a lie a host would act on).
+                capabilities: { tools: {}, resources: {}, prompts: {} },
+                serverInfo: { name: exports.SERVER_NAME, version: resolveServerVersion() },
             };
             break;
         case 'tools/list':
@@ -163,6 +249,52 @@ function handleMessage(request, ctx = {}) {
             result = callTool(toolName, params.arguments, ctx);
             break;
         }
+        case 'resources/list': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            try {
+                const cursor = typeof params.cursor === 'string' ? params.cursor : undefined;
+                const pageSize = typeof params.pageSize === 'number' ? params.pageSize : undefined;
+                const page = (0, mcp_catalog_cjs_1.listResources)(getCatalog(), { cursor, pageSize });
+                result = page.nextCursor === undefined
+                    ? { resources: page.resources.map(wireResource) }
+                    : { resources: page.resources.map(wireResource), nextCursor: page.nextCursor };
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
+        case 'resources/read': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            try {
+                const read = (0, mcp_catalog_cjs_1.readResource)(getCatalog(), params.uri);
+                result = { contents: [{ uri: read.uri, mimeType: read.mimeType, text: read.text }] };
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
+        case 'prompts/list':
+            result = {
+                prompts: [...getCatalog().prompts.values()]
+                    .map(wirePrompt)
+                    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+            };
+            break;
+        case 'prompts/get': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            const name = asString(params.name);
+            if (!name)
+                return errorResponse(id, INVALID_PARAMS, 'prompts/get requires string "name".');
+            try {
+                result = (0, mcp_catalog_cjs_1.getPrompt)(getCatalog(), name, params.arguments);
+            }
+            catch (e) {
+                return errorResponse(id, catalogErrorCode(e), catalogErrorMessage(e));
+            }
+            break;
+        }
         default:
             if (isNotification)
                 return null;

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

@@ -135,10 +135,15 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // Surface 1 — the checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
         // Use replace() + compare to avoid the test()+replace() global regex
         // lastIndex bug where test() advances state and replace() misses matches.
+        // (#2788 defect 2: the flip is CONDITIONAL — when a traceability row EXISTS
+        // for this ID but its Status write is rejected, the checkbox must NOT flip,
+        // so the two surfaces cannot silently diverge. The row-write outcome below
+        // gates whether the flip is kept.)
         const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+        const beforeCheckbox = reqContent;
         const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
-        const checkboxHit = afterCheckbox !== reqContent;
-        if (checkboxHit)
+        const checkboxFlipped = afterCheckbox !== beforeCheckbox;
+        if (checkboxFlipped)
             reqContent = afterCheckbox;
         // Surface 2 — the traceability row: | <REQ-ID> | Phase N | Pending | → ... Complete |
         // via the markdown-table seam (ADR-2143 §7) — supersedes the prior ordinal
@@ -156,7 +161,11 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         // updateTableCell call both probes the current value and writes.
         let tableHit = false;
         const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
-            if (/^pending$/i.test(current.trim())) {
+            // #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
+            // Complete again via mark-complete, or the milestone is blocked forever.
+            if (/^(pending|gaps found)$/i.test(current.trim())) {
                 tableHit = true;
                 return ' Complete ';
             }
@@ -165,6 +174,17 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         if (tableUpdate.ok) {
             reqContent = tableUpdate.value;
         }
+        // #2788 defect 2: if a row EXISTS for this ID but its Status write was
+        // rejected (e.g. the row reads `Blocked`, which mark-complete does not
+        // accept), roll the checkbox back so the checkbox and the row cannot
+        // silently diverge. The checkbox and the row are two representations of the
+        // same fact; flipping one while the other rejects the write is the lie.
+        let checkboxHit = checkboxFlipped;
+        const rowExistsProbe = tableUpdate; // ok === a row matched (probes existence)
+        if (checkboxFlipped && rowExistsProbe.ok && !tableHit) {
+            reqContent = beforeCheckbox;
+            checkboxHit = false;
+        }
         // ADR-2143 §6 per-ID write-set entries: this ID's checkbox surface is
         // always tracked; the traceability surface is tracked only when the file
         // has a traceability table at all (same `hasTable` gate the existing
@@ -190,7 +210,14 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         const hasRow = statusProbe.ok;
         const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent);
         const doneTable = Boolean(hasRow && /^complete$/i.test(currentStatusCell.trim()));
-        if (checkboxHit || tableHit) {
+        // #2788 defect 2: when a traceability table exists AND this ID has a row in
+        // it, `updated`/`marked_complete` must reflect the ROW moving, not a
+        // checkbox-only flip. Otherwise (`table_unmatched` — no row for this ID, or
+        // no table at all) the checkbox flip is a legitimate partial reconcile / the
+        // sole completion surface, so the #2140 OR semantics are preserved.
+        const rowExists = hasTable && hasRow;
+        const idUpdated = rowExists ? tableHit : (checkboxHit || tableHit);
+        if (idUpdated) {
             updated.push(reqId);
         }
         else if (doneTable || (doneCheckbox && !hasTable)) {
@@ -437,13 +464,25 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // 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
-    // were even started. Only fires when STATE.md confirms the current milestone
-    // version matches what is being completed — no false positives on fresh
-    // projects where phases haven't been scaffolded yet.
+    // were even started. The scan scopes the ROADMAP via the `version` argument
+    // (getMilestonePhaseFilter / extractCurrentMilestone above) and runs whenever
+    // --force is absent — a fresh project with no `### Phase N:` headings in the
+    // scoped slice yields an empty `noDirectoryPhases` and the guard is a no-op,
+    // so no STATE match is required to avoid false positives.
     // Pass --force to override this guard.
+    //
+    // #2946: the scan used to be nested inside `if (stateVersion && stateVersion
+    // === version)`, which silently disarmed the guard whenever STATE.md's
+    // `milestone:` field was desynced or absent — functionally an implicit
+    // --force on a one-way-door operation (ROADMAP/REQUIREMENTS archived, phase
+    // directories MOVED). The STATE field is not the source of truth for which
+    // phases belong to this milestone; the ROADMAP scoping is. The scan now runs
+    // unconditionally, and a present-but-mismatched STATE field emits a WARNING
+    // so the suspicious condition is visible rather than silent.
     if (!options.force) {
         try {
-            // Only guard when STATE.md's milestone field matches the version being completed.
+            // Read STATE.md's milestone field only to detect a suspicious mismatch;
+            // it no longer gates the scan. (#2946)
             let stateVersion = null;
             try {
                 const stateRaw = node_fs_1.default.existsSync(statePath) ? node_fs_1.default.readFileSync(statePath, 'utf-8') : null;
@@ -454,50 +493,66 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 }
             }
             catch {
-                /* skip */
+                /* skip — stateVersion stays null, scan still runs */
             }
-            if (stateVersion && stateVersion === version) {
-                const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-                const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
-                // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
-                const noDirectoryPhases = [];
-                let pm;
-                const phaseDirEntries = (() => {
-                    try {
-                        return node_fs_1.default
-                            .readdirSync(phasesDir, { withFileTypes: true })
-                            .filter((e) => e.isDirectory())
-                            .map((e) => e.name);
-                    }
-                    catch {
-                        return [];
-                    }
-                })();
-                while ((pm = phasePattern.exec(scopedContent)) !== null) {
-                    const phaseNum = pm[1];
-                    // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not
-                    // real phases — they legitimately have no directory and must not block
-                    // milestone completion. Mirrors the engine-wide sentinel convention
-                    // (phase-id getMilestoneFromPhaseId, roadmap-command-router SENTINELS,
-                    // the #1445 /^999/ progress filters). (#1580)
-                    const major = parseInt(phaseNum, 10);
-                    if (major === 0 || major === 999)
-                        continue;
-                    const normalized = normalizePhaseName(phaseNum);
-                    // A phase has disk_status: 'no_directory' when no phase directory
-                    // with a matching token exists on disk. Use the same phaseTokenMatches
-                    // helper that roadmap.analyze uses to avoid false positives on decimal
-                    // (2.1) and letter-suffix (12A) phase IDs.
-                    const hasDirectory = phaseDirEntries.some((d) => phaseTokenMatches(d, normalized));
-                    if (!hasDirectory) {
-                        noDirectoryPhases.push(phaseNum);
-                    }
+            if (stateVersion !== null && stateVersion !== version) {
+                // #2946: emit a WARNING so the suspicious STATE mismatch is visible
+                // rather than silently disarming the guard. Plain-text diagnostic on
+                // stderr, matching the existing [gsd-tools] WARNING convention
+                // (state.cts). A missing STATE.md `milestone:` field is not warned
+                // here — the scan still runs, and "no milestone declared" is a normal
+                // state for a fresh project, not a suspicious drift.
+                //
+                // `stateVersion` comes from a user-controlled file (STATE.md) and is
+                // not validated like the CLI `version` arg (ARCHIVE_VERSION_LABEL_RE).
+                // Sanitize before interpolating into stderr so ANSI escapes / control
+                // chars / secret-looking strings cannot be echoed verbatim into a CI
+                // log or terminal (CONTRIBUTING.md security: secret-looking values in
+                // stderr). `version` is already constrained to [A-Za-z0-9._-].
+                const safeStateVersion = stateVersion.replace(/[\x00-\x1f\x7f]/g, '?').slice(0, 80);
+                process.stderr.write(`[gsd-tools] WARNING: STATE.md milestone: "${safeStateVersion}" ≠ requested "${version}" — ` +
+                    `running the unstarted-phase guard against the ROADMAP scoped for "${version}" anyway.\n`);
+            }
+            const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+            const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
+            // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+            const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
+            const noDirectoryPhases = [];
+            let pm;
+            const phaseDirEntries = (() => {
+                try {
+                    return node_fs_1.default
+                        .readdirSync(phasesDir, { withFileTypes: true })
+                        .filter((e) => e.isDirectory())
+                        .map((e) => e.name);
                 }
-                if (noDirectoryPhases.length > 0) {
-                    error(`Cannot mark milestone complete: ROADMAP lists ${noDirectoryPhases.length} unstarted phase(s) ` +
-                        `(e.g. Phase ${noDirectoryPhases[0]}). Re-run with --force to override.`);
+                catch {
+                    return [];
                 }
+            })();
+            while ((pm = phasePattern.exec(scopedContent)) !== null) {
+                const phaseNum = pm[1];
+                // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not
+                // real phases — they legitimately have no directory and must not block
+                // milestone completion. Mirrors the engine-wide sentinel convention
+                // (phase-id getMilestoneFromPhaseId, roadmap-command-router SENTINELS,
+                // the #1445 /^999/ progress filters). (#1580)
+                const major = parseInt(phaseNum, 10);
+                if (major === 0 || major === 999)
+                    continue;
+                const normalized = normalizePhaseName(phaseNum);
+                // A phase has disk_status: 'no_directory' when no phase directory
+                // with a matching token exists on disk. Use the same phaseTokenMatches
+                // helper that roadmap.analyze uses to avoid false positives on decimal
+                // (2.1) and letter-suffix (12A) phase IDs.
+                const hasDirectory = phaseDirEntries.some((d) => phaseTokenMatches(d, normalized));
+                if (!hasDirectory) {
+                    noDirectoryPhases.push(phaseNum);
+                }
+            }
+            if (noDirectoryPhases.length > 0) {
+                error(`Cannot mark milestone complete: ROADMAP lists ${noDirectoryPhases.length} unstarted phase(s) ` +
+                    `(e.g. Phase ${noDirectoryPhases[0]}). Re-run with --force to override.`);
             }
         }
         catch (e) {
@@ -505,7 +560,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             const message = e instanceof Error ? e.message : String(e);
             if (message && message.startsWith('Cannot mark milestone complete:'))
                 throw e;
-            // Phase scan failed or STATE version mismatch — allow completion to proceed.
+            // Phase scan failed (e.g. ROADMAP unreadable) — allow completion to proceed.
         }
     }
     // Gather stats from phases (scoped to current milestone only)
@@ -668,7 +723,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             kind: 'milestoneComplete',
             version,
             nextMilestoneCommand: (0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
-        }, { clock: clock_cjs_1.realClock, progressProvider: () => null, sourcePath: statePath });
+        }, { clock: clock_cjs_1.realClock, sourcePath: statePath });
         writeStateMd(statePath, result.content, cwd);
     }
     // Archive phase directories if requested

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

@@ -520,6 +520,65 @@ function phaseTokenMatches(dirName, normalized) {
     }
     return false;
 }
+// ─── Canonical phase KEY surface (#2562) ─────────────────────────────────────
+//
+// A phase "key" is the padding-, case- and project-code-insensitive identity of
+// a phase, for use as a Map/Set key when two independently-derived phase
+// references (a ROADMAP table cell and a phase directory name, say) must be
+// compared. Promoted here from a local pair in state.cts (#2445) so every
+// consumer derives BOTH sides of a comparison from the SAME function — deriving
+// one side with a bespoke regex is the #2562 defect class (a `01` table cell
+// never matching a `1-slug` directory, silently zeroing a rollup).
+/**
+ * Canonical key for an already-extracted phase TOKEN (`"5"`, `"05"`, `"005"`,
+ * `"12A"`, `"30.1"`, `"PROJ-05"`). Padding- and case-insensitive: every
+ * spelling of a number collapses to one key.
+ *
+ * Leading zeros are stripped per hyphen-separated segment BEFORE
+ * `normalizePhaseName` pads to the 2-digit convention. Padding alone is not a
+ * normalisation — `padStart(2)` is a no-op once the input is already ≥2
+ * characters, so `5` yielded `05` while `005` stayed `005` and the two never
+ * compared equal. The strip is deliberately confined to this key surface:
+ * `normalizePhaseName` itself is a RENDERING function whose verbatim treatment
+ * of wide IDs (`001.10`) is relied on by plan-ID capture and wave assignment.
+ * Arithmetic is avoided (`parseInt` would lose precision on a long digit run).
+ */
+function phaseKeyFromToken(token) {
+    const stripped = String(token)
+        .split('-')
+        .map(segment => segment.replace(/^0+(?=\d)/, ''))
+        .join('-');
+    return normalizePhaseName(stripped).toUpperCase();
+}
+/**
+ * Canonical key for a phase DIRECTORY name (`"05-schedule-8"` → `"05"`,
+ * `"PROJ-5-x"` → `"05"`, `"30.1-follow-up"` → `"30.1"`).
+ */
+function phaseKeyFromDir(dirName) {
+    return phaseKeyFromToken(extractPhaseToken(dirName));
+}
+/**
+ * Canonical key for a phase referenced in PROSE — a ROADMAP `## Progress` table
+ * cell (`"30. Schedule 8 rollout"`, `"**05.1 Follow-up**"`) or a STATE.md
+ * `Phase:` value. Markdown emphasis is stripped first so a bolded cell is not
+ * mistaken for a non-phase. Returns null when the value does not BEGIN with a
+ * phase token (`parsePhaseFromProse` anchoring, #2111).
+ */
+function phaseKeyFromProse(value) {
+    if (value == null)
+        return null;
+    const { phase } = parsePhaseFromProse(String(value).replace(/[*_`~]/g, ''));
+    return phase === null ? null : phaseKeyFromToken(phase);
+}
+/**
+ * The PARENT phase key of a sub-phase key (`"30.1"` → `"30"`), or null for a
+ * top-level phase. A sub-phase directory inserted mid-milestone frequently has
+ * no ROADMAP row of its own and inherits its parent's milestone (#2562).
+ */
+function parentPhaseKey(key) {
+    const dot = key.indexOf('.');
+    return dot === -1 ? null : key.slice(0, dot);
+}
 // ─── #2121 canonical surface (ADR-2121) ──────────────────────────────────────
 /**
  * Parse a phase identifier from a STATE.md `Phase:` prose field VALUE — the text
@@ -662,6 +721,10 @@ module.exports = {
     comparePhaseNum,
     extractPhaseToken,
     phaseTokenMatches,
+    phaseKeyFromToken,
+    phaseKeyFromDir,
+    phaseKeyFromProse,
+    parentPhaseKey,
     parsePhaseFromProse,
     stripConfiguredProjectCodePrefix,
     isForeignPrefixedPhaseQuery,