@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.5

package/gsd-core/bin/lib/roadmap-parser.cjs

@@ -22,7 +22,10 @@ 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 phaseIdModule = require("./phase-id.cjs");
-const { escapeRegex, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, stripProjectCodePrefix, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, } = phaseIdModule;
+const { escapeRegex, phaseMarkdownRegexSource, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, 
+// #2121: roadmapPhaseLookupSources now lives in phase-id.cjs (single owner of
+// the lookup-source ordering); imported here rather than defined locally.
+roadmapPhaseLookupSources, } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
@@ -33,7 +36,7 @@ const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
  * Strip shipped milestone content wrapped in <details> blocks.
  */
 function stripShippedMilestones(content) {
-    return content.replace(/<details>[\s\S]*?<\/details>/gi, '');
+    return (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(content, 'details');
 }
 /**
  * Extract the current milestone section from ROADMAP.md by positive lookup.
@@ -80,10 +83,9 @@ function extractCurrentMilestone(content, cwd) {
                 const anyMilestoneOrDetails = /^#{1,3}\s+(?!Phase\s+\S)(?:.*v\d+\.\d+|✅|📋|🚧|🔄)|<details/im;
                 const firstMilestoneMatch = content.match(anyMilestoneOrDetails);
                 const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : detailsOpenIdx;
-                const preamble = content.slice(0, preambleCutoff)
-                    .replace(/<details>[\s\S]*?<\/details>/gi, '')
-                    // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-                    .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]*\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+                const preamble = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(content.slice(0, preambleCutoff), 'details')
+                    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                    .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
                     .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
                 return preamble + content.slice(detailsOpenIdx, detailsEnd);
             }
@@ -150,10 +152,9 @@ function extractCurrentMilestone(content, cwd) {
         const detailsStart = detailsMatch.index ?? 0;
         detailsSection = content.slice(detailsStart, computeSectionEnd(detailsMatch[0], detailsStart));
     }
-    const preamble = beforeMilestones
-        .replace(/<details>[\s\S]*?<\/details>/gi, '')
-        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]*\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+    const preamble = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(beforeMilestones, 'details')
+        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
         .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
     return detailsSection
         ? preamble + currentSection + '\n' + detailsSection
@@ -174,7 +175,7 @@ function replaceInCurrentMilestone(content, pattern, replacement) {
 }
 function findRoadmapPhaseInContent(content, phaseNum, phaseSource) {
     // #1729: OPTIONAL_PHASE_TAG_SOURCE after the number tolerates a pre-colon ( ) tag.
-    const headingPattern = new RegExp(`^(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${phaseSource ?? phaseMarkdownRegexSource(phaseNum)}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*(.+)$`, 'i');
+    const headingPattern = new RegExp(`^(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${phaseSource ?? phaseMarkdownRegexSource(phaseNum)}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*(.+)$`, 'i');
     const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
     const headingIndex = headings.findIndex((heading) => headingPattern.test(heading.text));
     if (headingIndex === -1)
@@ -197,21 +198,6 @@ function findRoadmapPhaseInContent(content, phaseNum, phaseSource) {
         section,
     };
 }
-function roadmapPhaseLookupSources(phaseNum) {
-    const sources = [];
-    const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
-    if (exactSource)
-        sources.push(exactSource);
-    const numericSource = phaseMarkdownRegexSource(phaseNum);
-    // Source order matters: the bare numeric source is tried before the
-    // prefix-tolerant form so that a canonical bare heading ("Phase 117:") is
-    // preferred over a drifted prefixed heading ("Phase MANIFOLD-117:") when
-    // both exist in the same ROADMAP.  The prefix-tolerant form is the fallback
-    // that handles the drifted-only case.
-    sources.push(numericSource);
-    sources.push(`${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${numericSource}`);
-    return [...new Set(sources)];
-}
 function getRoadmapPhaseInternal(cwd, phaseNum) {
     if (!phaseNum)
         return null;
@@ -323,7 +309,7 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
             throw new Error('missing');
         let roadmap = extractCurrentMilestone(roadmapContent, cwd);
         const hasVersionedMilestonesGlobal = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
-        const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
+        const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
         if (!hasVersionedMilestonesGlobal && hasPhaseHeadings && phaseIdConvention === 'milestone-prefixed') {
             console.warn('[gsd] Deprecated: free-form ROADMAP.md detected (no versioned milestone headings). ' +
                 'The project has phase_id_convention set to "milestone-prefixed" in config.json but the ' +
@@ -378,8 +364,8 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         }
         // Use tokenizeHeadings (fence-aware) instead of stripFencedLines + regex.
         // T4 seam migration: phase headings inside fences are excluded automatically.
-        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        const phaseHeadingPattern = /^(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/i;
+        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const phaseHeadingPattern = /^(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/i;
         for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(roadmap)) {
             if (h.level < 2 || h.level > 4)
                 continue;
@@ -401,8 +387,13 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         return id.split('-').map(seg => seg.replace(/^0+(?=\d)/, '') || '0').join('-');
     }
     const roadmapUsesHyphenedIds = [...normalized].some(n => n.includes('-'));
+    // #2043: milestone-prefixed sub-phase components must be zero-padded (≥2 digits)
+    // — "-\d{2,}" instead of "-0*\d+" — so a single-digit slug word after the phase
+    // number (e.g. dir "46-6-rs-…") captures "46" and is not silently excluded from
+    // the milestone as a bogus "46-6" id.
     const numericRe = roadmapUsesHyphenedIds
-        ? /^0*(\d+(?:-0*\d+)*[A-Za-z]?(?:\.\d+)*)/
+        ? /^0*(\d+(?:-\d{2,})*[A-Za-z]?(?:\.\d+)*)/
+        // phase-id-owner: the [A-Za-z] letter class does real case handling here — this regex carries NO /i flag; kept literal, not source-byte-equal to the canonical PHASE_NUMBER_TOKEN_SOURCE.
         : /^0*(\d+[A-Za-z]?(?:\.\d+)*)/;
     function isDirInMilestone(dirName) {
         const m2 = dirName.match(numericRe);

package/gsd-core/bin/lib/roadmap-upgrade.cjs

@@ -19,16 +19,16 @@ const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
 const { planningDir } = planningWorkspace;
-const { stripProjectCodePrefix } = phaseIdMod;
+const { stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
 // ─── Regex helpers ────────────────────────────────────────────────────────────
 // Matches legacy phase headings: ### Phase N: Name  (also decimal: Phase 2.1:)
 // Captures: (hashes)(spaces)(phase-number)(rest-of-line)
-const LEGACY_PHASE_HEADING_RE = /^(#{2,4})\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:(.*)/i;
+const LEGACY_PHASE_HEADING_RE = new RegExp(`^(#{2,4})\\s*(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})\\s*:(.*)`, 'i');
 // Matches already-migrated phase headings: ### Phase M-NN: Name
-const MIGRATED_PHASE_HEADING_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+\d+-\d{2}\s*:/i;
+const MIGRATED_PHASE_HEADING_RE = /^#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+\d+-\d{2}\s*:/i;
 // Matches milestone section headings: ## v1.0, ## Roadmap v2.0, ## ✅ v1.0, ## [GSD] v1.0, etc.
 // The optional bracket-token prefix (e.g., [GSD]) must be tested before the emoji group.
-const MILESTONE_HEADING_RE = /^##\s+(?:\[[^\]]+\]\s+|Roadmap\s+|[✅🚧]\s*)?v(\d+)\.(\d+)(?:\s|:)/iu;
+const MILESTONE_HEADING_RE = /^##\s+(?:\[[^\]]{1,200}\]\s+|Roadmap\s+|[✅🚧]\s*)?v(\d+)\.(\d+)(?:\s|:)/iu;
 // ─── Pure computation helpers ─────────────────────────────────────────────────
 /**
  * Parse the ROADMAP.md content and build a list of phase entries with their
@@ -106,7 +106,7 @@ function extractPhaseNumFromDir(dirName) {
     const stripped = stripProjectCodePrefix(dirName);
     // Matches: digits + optional letter + optional decimal suffix, followed by '-' or end.
     // e.g. "02.1-hotfix" → "02.1", "01-setup" → "01"
-    const m = stripped.match(/^(\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i);
+    const m = stripped.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})(?:-|$)`, 'i'));
     return m ? m[1] : null;
 }
 /**
@@ -119,7 +119,7 @@ function buildNewDirName(oldDirName, newId, projectCode) {
     // Strip existing project_code prefix
     const stripped = stripProjectCodePrefix(oldDirName);
     // Extract slug: everything after "NN-" (the old phase num, including decimal like 02.1)
-    const slugMatch = stripped.match(/^\d+[A-Z]?(?:\.\d+)*-(.*)/i);
+    const slugMatch = stripped.match(new RegExp(`^${PHASE_NUMBER_TOKEN_SOURCE}-(.*)`, 'i'));
     const slug = slugMatch ? slugMatch[1] : stripped;
     // Build M-NN prefix (zero-pad both parts)
     const [milestoneStr, subStr] = newId.split('-');
@@ -256,7 +256,7 @@ function computeMigrationPlan(cwd, options = {}) {
             continue;
         // Rewrite heading line: "### Phase N: Name" → "### Phase M-NN: Name"
         const oldLine = lines[entry.lineIndex];
-        const newLine = oldLine.replace(/^(#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+)\d+[A-Z]?(?:\.\d+)*(\s*:)/i, `$1${mapping.newId}$2`);
+        const newLine = oldLine.replace(new RegExp(`^(#{2,4}\\s*(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+)${PHASE_NUMBER_TOKEN_SOURCE}(\\s*:)`, 'i'), `$1${mapping.newId}$2`);
         if (newLine !== oldLine) {
             roadmapEdits.push({ lineIndex: entry.lineIndex, from: oldLine, to: newLine });
         }
@@ -274,7 +274,7 @@ function computeMigrationPlan(cwd, options = {}) {
         if (roadmapEdits.some(e => e.lineIndex === i))
             continue;
         // Match checklist items: "- [ ] **Phase N:**" or "- [x] Phase N:"  (also decimal)
-        const checklistMatch = line.match(/^(\s*-\s*\[[ x]\]\s*\*{0,2}Phase\s+)(\d+[A-Z]?(?:\.\d+)*)(\s*[:\s*])/i);
+        const checklistMatch = line.match(new RegExp(`^(\\s*-\\s*\\[[ x]\\]\\s*\\*{0,2}Phase\\s+)(${PHASE_NUMBER_TOKEN_SOURCE})(\\s*[:\\s*])`, 'i'));
         if (checklistMatch) {
             const legacyNum = checklistMatch[2];
             const cIntPart = parseInt(legacyNum, 10);
@@ -300,7 +300,7 @@ function computeMigrationPlan(cwd, options = {}) {
                     newId = found.newId;
             }
             if (newId) {
-                const newLine = line.replace(/^(\s*-\s*\[[ x]\]\s*\*{0,2}Phase\s+)\d+[A-Z]?(?:\.\d+)*(\s*[:\s*])/i, `$1${newId}$2`);
+                const newLine = line.replace(new RegExp(`^(\\s*-\\s*\\[[ x]\\]\\s*\\*{0,2}Phase\\s+)${PHASE_NUMBER_TOKEN_SOURCE}(\\s*[:\\s*])`, 'i'), `$1${newId}$2`);
                 if (newLine !== line) {
                     roadmapEdits.push({ lineIndex: i, from: line, to: newLine });
                 }

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

@@ -17,7 +17,7 @@ const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, phaseTokenMatches, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseTokenMatches, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal } = phaseLocatorMod;
@@ -102,7 +102,7 @@ function countPhasePlansAndSummaries(phaseDir) {
  */
 function searchPhaseInContent(content, escapedPhase, phaseNum) {
     // #1729: OPTIONAL_PHASE_TAG_SOURCE after the number tolerates a pre-colon ( ) tag.
-    const headingPattern = new RegExp(`^(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*(.+)$`, 'i');
+    const headingPattern = new RegExp(`^(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*(.+)$`, 'i');
     const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
     const headingIndex = headings.findIndex((heading) => headingPattern.test(heading.text));
     const headerMatch = headingIndex === -1 ? null : headings[headingIndex].text.match(headingPattern);
@@ -174,23 +174,18 @@ function getRoadmapPhaseWithFallback(cwd, phaseNum) {
     const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
     const fullContent = stripShippedMilestones(rawContent);
-    const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
-    if (exactSource) {
-        const exactMilestone = searchPhaseInContent(milestoneContent, exactSource, phaseNum);
-        if (exactMilestone && !exactMilestone.error)
-            return exactMilestone.section ?? null;
-        const exactFull = searchPhaseInContent(fullContent, exactSource, phaseNum);
-        if (exactFull && !exactFull.error)
-            return exactFull.section ?? null;
+    // #2121/#2114: iterate the shared lookup-source list (exact → numeric →
+    // prefix-tolerant) so this resolver matches getRoadmapPhaseInternal and a
+    // bare-number query resolves a drifted project-code-prefixed heading.
+    for (const source of roadmapPhaseLookupSources(phaseNum)) {
+        const milestoneResult = searchPhaseInContent(milestoneContent, source, phaseNum);
+        if (milestoneResult && !milestoneResult.error)
+            return milestoneResult.section ?? null;
+        const fullResult = searchPhaseInContent(fullContent, source, phaseNum);
+        if (fullResult && !fullResult.error)
+            return fullResult.section ?? null;
     }
-    const escapedPhase = phaseMarkdownRegexSource(phaseNum);
-    const milestoneResult = searchPhaseInContent(milestoneContent, escapedPhase, phaseNum);
-    const result = (milestoneResult && !milestoneResult.error)
-        ? milestoneResult
-        : searchPhaseInContent(fullContent, escapedPhase, phaseNum) || milestoneResult;
-    if (!result || result.error)
-        return null;
-    return result.section ?? null;
+    return null;
 }
 // ─── cmdRoadmapGetPhase ───────────────────────────────────────────────────────
 function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
@@ -206,46 +201,35 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
     try {
         const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const milestoneContent = extractCurrentMilestone(rawContent, cwd);
-        // #3599 two-pass: when the caller passes a project-code-prefixed ID like
-        // `PROJ-42`, try the exact-prefixed heading first (`### Phase PROJ-42:`).
-        // If no match, fall back to the #3537 padding-tolerant numeric form so
-        // a `CK-01` query still resolves to `### Phase 1:`. Doing this at the
-        // call site (instead of inside phaseMarkdownRegexSource) avoids the
-        // alternation-order ambiguity where a bare `### Phase 42:` heading in
-        // the same document would intercept the match for a `PROJ-42` query.
         const fullContent = stripShippedMilestones(rawContent);
-        const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
-        if (exactSource) {
-            const exactMilestone = searchPhaseInContent(milestoneContent, exactSource, phaseNum);
-            if (exactMilestone && !exactMilestone.error) {
-                output(exactMilestone, raw, exactMilestone.section);
+        // #2121/#2114: iterate the shared lookup-source list (exact → numeric →
+        // prefix-tolerant) so all three roadmap resolvers share one contract and a
+        // bare-number query resolves a drifted `### Phase AB-29:` heading. This
+        // preserves the #3599 exact-prefix-first and #3537 padding-tolerant behavior
+        // (both now encoded in roadmapPhaseLookupSources' ordering). A clean match
+        // (milestone or full, any source) wins immediately; a malformed_roadmap
+        // (checklist-only) candidate is surfaced only if no source finds a real
+        // heading — so a milestone checklist never blocks a full-roadmap header.
+        let malformed = null;
+        for (const source of roadmapPhaseLookupSources(phaseNum)) {
+            const milestoneResult = searchPhaseInContent(milestoneContent, source, phaseNum);
+            if (milestoneResult && !milestoneResult.error) {
+                output(milestoneResult, raw, milestoneResult.section);
                 return;
             }
-            const exactFull = searchPhaseInContent(fullContent, exactSource, phaseNum);
-            if (exactFull && !exactFull.error) {
-                output(exactFull, raw, exactFull.section);
+            const fullResult = searchPhaseInContent(fullContent, source, phaseNum);
+            if (fullResult && !fullResult.error) {
+                output(fullResult, raw, fullResult.section);
                 return;
             }
+            if (!malformed)
+                malformed = (milestoneResult?.error ? milestoneResult : (fullResult?.error ? fullResult : null));
         }
-        // #3537: padding-tolerant fragment so callers passing `02.7` still match
-        // un-padded ROADMAP prose (`### Phase 2.7:`).
-        const escapedPhase = phaseMarkdownRegexSource(phaseNum);
-        // Search the current milestone slice first, then fall back to full roadmap.
-        // A malformed_roadmap result (checklist-only) from the milestone should not
-        // block finding a full header match in the wider roadmap content.
-        const milestoneResult = searchPhaseInContent(milestoneContent, escapedPhase, phaseNum);
-        const result = (milestoneResult && !milestoneResult.error)
-            ? milestoneResult
-            : searchPhaseInContent(fullContent, escapedPhase, phaseNum) || milestoneResult;
-        if (!result) {
-            output({ found: false, phase_number: phaseNum }, raw, '');
-            return;
-        }
-        if (result.error) {
-            output(result, raw, '');
+        if (malformed) {
+            output(malformed, raw, '');
             return;
         }
-        output(result, raw, result.section);
+        output({ found: false, phase_number: phaseNum }, raw, '');
     }
     catch (e) {
         error('Failed to read ROADMAP.md: ' + e.message);
@@ -262,8 +246,9 @@ function cmdRoadmapAnalyze(cwd, raw) {
     const content = extractCurrentMilestone(rawContent, cwd);
     const phasesDir = planningPaths(cwd).phases;
     // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
-    // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
+    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)(?:\s*\([^)\n]{0,200}\))?\s*:\s*([^\n]+)/gi;
     const phases = [];
     let match;
     // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not real
@@ -296,7 +281,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
         const restOfContent = content.slice(sectionStart);
         // #3691: `\d` → `\d[\d.]*` so decimal phase headings (e.g. `### Phase 02.3:`) are
         // recognised as section boundaries.
-        const nextHeader = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+\d[\d.-]*/i);
+        const nextHeader = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]{1,200}\]\s*)?Phase\s+\d[\d.-]*/i);
         const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length;
         const section = content.slice(sectionStart, sectionEnd);
         const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
@@ -383,6 +368,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
     // The char class must allow `-` (not just `.`) so dash-separated milestone-prefixed
     // IDs (e.g. `1-01`) match the detail-heading scanner above; otherwise they truncate
     // at the dash (`1-01` -> `1`) and every such phase reports a phantom missing detail.
+    // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
     const checklistPattern = /-\s*\[[ x]\]\s*\*\*Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)/gi;
     const checklistPhases = new Set();
     let checklistMatch;
@@ -473,7 +459,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         //   `**Plans**: N plans`  — bold word + outer colon (gsd-core/templates/roadmap.md)
         //   `**Plans:** N plans`  — bold "Plans:" (colon inside bold)
         //   `Plans: N plans`      — plain text header
-        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)[^\\n]+`, 'i');
+        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)[^\\n]+`, 'i');
         const planCountText = isComplete
             ? `${summaryCount}/${planCount} plans complete`
             : `${summaryCount}/${planCount} plans executed`;
@@ -530,8 +516,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             //
             // Pattern A: anchor to bare `Plans:` header (preferred).
             // Pattern B: fallback to bold summary when no bare header exists.
-            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])[\\s\\S]*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
-            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
+            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
+            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
             const sortedMissing = [...missingPlans].sort();
             const newRows = sortedMissing.map(p => `- [ ] ${p}`).join('\n');
             const inserter = (match) => `${match}\n${newRows}`;

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -2277,7 +2277,7 @@ function rewriteStagedSkillBodies(stagedDir, opts) {
     const resolvedTarget = node_path_1.default.resolve(configDir).replace(/\\/g, '/');
     const homeDir = homedir().replace(/\\/g, '/');
     const isGlobal = scope === 'global';
-    const isOpencode = runtime === 'opencode';
+    const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';
     const pathPrefix = computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir });
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
@@ -2290,10 +2290,12 @@ function rewriteStagedSkillBodies(stagedDir, opts) {
  * attribution from opts, then delegates to applyRuntimeContentRewritesForCommandsInPlace
  * (single copy+rewrite owner).
  *
- * @internal — symmetric companion to rewriteStagedSkillBodies; retained as the deep-seam
- * API for command bodies. No production caller today (install rewrites commands via
- * copyWithPathReplacement → applyRuntimeContentRewritesForCommandsInPlace). Kept for
- * API symmetry + test coverage.
+ * @internal — symmetric companion to rewriteStagedSkillBodies; the deep-seam API for
+ * command bodies. Production callers: applySurface (surface.cts) and the install path
+ * in createRuntimeArtifactInstallPlan (runtime-artifact-install-plan.cts) — both keep
+ * the returned temp dir alive until they have copied its contents out, then clean it up
+ * in their own finally. (A test that treats this as a throwaway shared-tmp path will
+ * race those live temp dirs under --test-concurrency; see #1575/#2090.)
  *
  * @returns {string} path to the temp dir (caller is responsible for cleanup)
  */
@@ -2304,7 +2306,7 @@ function rewriteStagedCommandBodies(stagedDir, opts) {
     const resolvedTarget = node_path_1.default.resolve(configDir).replace(/\\/g, '/');
     const homeDir = homedir().replace(/\\/g, '/');
     const isGlobal = scope === 'global';
-    const isOpencode = runtime === 'opencode';
+    const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';
     const pathPrefix = computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir });
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
@@ -2425,6 +2427,11 @@ module.exports = {
     neutralizeAgentReferences,
     convertClaudeCommandToOpencodeSkill,
     convertClaudeCommandToKiloSkill,
+    // #2087 — opencode/kilo command-frontmatter converters, exported so the
+    // layout-driven `convertedCommandsKind` can resolve them by name (routes the
+    // opencode/kilo command install through the engine instead of the bespoke path).
+    convertClaudeToOpencodeFrontmatter,
+    convertClaudeToKiloFrontmatter,
     readGsdCommandNames,
     transformContentToHyphen,
     // #1383: version resolver (exported for regression test of the Codex

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -111,7 +111,7 @@ function createRuntimeArtifactInstallPlan(args) {
         items.push({
             kind: kind.kind,
             sourceDir,
-            destDir: assertDestWithinConfigHome(layout.configDir, kind.destSubpath),
+            destDir: assertDestWithinConfigHome(kind.home ?? layout.configDir, kind.destSubpath),
         });
     }
     return { ok: true, plan: { items, cleanupDirs } };
@@ -120,7 +120,7 @@ function createRuntimeArtifactUninstallPlan(layout) {
     return {
         items: layout.kinds.map((kind) => ({
             kind: kind.kind,
-            destDir: assertDestWithinConfigHome(layout.configDir, kind.destSubpath),
+            destDir: assertDestWithinConfigHome(kind.home ?? layout.configDir, kind.destSubpath),
         })),
     };
 }

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -278,27 +278,34 @@ function getRegistry() {
 function dispatchKindEntry(entry, runtime, configDir, scope) {
     const { kind, destSubpath, prefix, nesting, converter } = entry;
     const nested = nesting === 'nested';
+    let result;
     switch (kind) {
         case 'commands':
-            if (converter == null) {
-                return commandsKind(destSubpath, prefix, configDir);
-            }
-            return convertedCommandsKind(destSubpath, prefix, converter, configDir);
+            result = converter == null
+                ? commandsKind(destSubpath, prefix, configDir)
+                : convertedCommandsKind(destSubpath, prefix, converter, configDir);
+            break;
         case 'agents':
-            if (converter == null) {
-                return agentsKind(destSubpath, prefix, configDir);
-            }
-            return convertedAgentsKind(destSubpath, prefix, converter, configDir, scope);
+            result = converter == null
+                ? agentsKind(destSubpath, prefix, configDir)
+                : convertedAgentsKind(destSubpath, prefix, converter, configDir, scope);
+            break;
         case 'skills':
             if (converter == null) {
                 throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);
             }
-            return skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope);
+            result = skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope);
+            break;
         case 'kimi-agents':
-            return kimiAgentsKind(destSubpath, prefix, configDir);
+            result = kimiAgentsKind(destSubpath, prefix, configDir);
+            break;
         default:
             throw new TypeError(`resolveRuntimeArtifactLayout: unknown kind '${kind}' in descriptor for runtime '${runtime}'`);
     }
+    if (typeof entry.home === 'string' && entry.home !== '') {
+        result.home = node_path_1.default.join(node_os_1.default.homedir(), entry.home);
+    }
+    return result;
 }
 /**
  * Resolve the artifact layout for a given runtime and config directory.

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -296,6 +296,14 @@ function getGlobalSkillsBase(runtime) {
     const runtimeEntry = getRegistry().runtimes[runtime];
     const descriptor = runtimeEntry?.runtime;
     const globalSkillsKind = descriptor?.artifactLayout?.global?.find((entry) => entry.kind === 'skills');
+    // ADR-1239 upgrade 3 (#2088): honor a skills-kind `home` override (e.g. Codex
+    // → $HOME/.agents/skills, independent of $CODEX_HOME) so the reported skills
+    // root matches where the installer actually writes (the artifact layout /
+    // _resolveSkillsRootDir). Without this, `--skills-root` and the sync-skills
+    // workflow would look under configHome/skills while skills live under ~/.agents.
+    if (globalSkillsKind?.home && globalSkillsKind?.destSubpath) {
+        return node_path_1.default.join(node_os_1.default.homedir(), globalSkillsKind.home, globalSkillsKind.destSubpath);
+    }
     if (descriptor?.configHome && globalSkillsKind?.destSubpath) {
         return resolveSkillsBaseFromDescriptor(descriptor.configHome, { env: process.env, home: node_os_1.default.homedir(), existsSync: node_fs_1.default.existsSync }, globalSkillsKind.destSubpath);
     }

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -28,6 +28,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+const imperative_hook_bus_cjs_1 = require("./host-integration-adapters/imperative-hook-bus.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCmdProjection = require("./shell-command-projection.cjs");
 const { isManagedHookBasename, isManagedHookCommand, projectLegacySettingsHookCommand, projectManagedHookCommand, projectPortableHookBaseDir, projectCodexHookTomlCommand, shellHookOmitsBashRunner, } = shellCmdProjection;
@@ -57,7 +58,18 @@ const GSD_COPILOT_SESSION_HOOK_PWSH = 'if (Test-Path .planning/STATE.md) ' +
 // ---------------------------------------------------------------------------
 const GSD_CURSOR_SESSION_HOOK_SCRIPT = 'gsd-cursor-session-start.js';
 const GSD_CURSOR_POST_TOOL_HOOK_SCRIPT = 'gsd-cursor-post-tool.js';
+const GSD_CURSOR_PRE_TOOL_HOOK_SCRIPT = 'gsd-cursor-pre-tool.js';
+const GSD_CURSOR_STOP_HOOK_SCRIPT = 'gsd-cursor-stop.js';
+const GSD_CURSOR_SUBAGENT_START_HOOK_SCRIPT = 'gsd-cursor-subagent-start.js';
+const GSD_CURSOR_SUBAGENT_STOP_HOOK_SCRIPT = 'gsd-cursor-subagent-stop.js';
 const GSD_CURSOR_HOOK_MARKER = 'gsd-managed';
+// The full set of Cursor hook events GSD manages — sourced from the adapter
+// (src/host-integration-adapters/imperative-hook-bus.cts) so the vocabulary
+// stays closed and first-party. Used by reconcileCursorHooksJson (the
+// reconciliation scope is always the full set). The install path
+// (writeCursorHooksJson) resolves a descriptor-driven subset via
+// resolveManagedHookEvents(opts.managedHookEvents).
+const CURSOR_MANAGED_EVENTS = imperative_hook_bus_cjs_1.CURSOR_HOOK_EVENTS;
 // ---------------------------------------------------------------------------
 // Cline / AGENTS.md constants
 // ---------------------------------------------------------------------------
@@ -819,9 +831,8 @@ function reconcileCursorHooksJson(hooksJsonPath, managedEntries) {
         parsed = {};
     const hasNestedHooksObject = parsed['hooks'] && typeof parsed['hooks'] === 'object' && !Array.isArray(parsed['hooks']);
     if (!hasNestedHooksObject) {
-        const eventKeys = ['sessionStart', 'postToolUse'];
         const lifted = {};
-        for (const k of eventKeys) {
+        for (const k of CURSOR_MANAGED_EVENTS) {
             if (Array.isArray(parsed[k])) {
                 lifted[k] = parsed[k];
                 delete parsed[k];
@@ -832,9 +843,8 @@ function reconcileCursorHooksJson(hooksJsonPath, managedEntries) {
     if (!parsed['version'])
         parsed['version'] = 1;
     const hookTable = parsed['hooks'];
-    const MANAGED_EVENTS = ['sessionStart', 'postToolUse'];
     const entries = managedEntries || {};
-    for (const event of MANAGED_EVENTS) {
+    for (const event of CURSOR_MANAGED_EVENTS) {
         const existing = Array.isArray(hookTable[event]) ? hookTable[event] : [];
         const userOwned = existing.filter((e) => !isManagedCursorHookEntry(e));
         const newEntry = entries[event] || null;
@@ -862,7 +872,11 @@ function writeCursorHooksJson(targetDir, src, opts) {
     opts = opts || {};
     const hooksDir = node_path_1.default.join(targetDir, 'hooks');
     node_fs_1.default.mkdirSync(hooksDir, { recursive: true });
-    const hookScripts = [GSD_CURSOR_SESSION_HOOK_SCRIPT, GSD_CURSOR_POST_TOOL_HOOK_SCRIPT];
+    // Descriptor-driven event resolution (#2089): the managed event set comes
+    // from the host descriptor's hostBehaviors.managedHookEvents via the pure
+    // adapter (resolveManagedHookEvents), NOT a hardcoded constant.
+    const events = (0, imperative_hook_bus_cjs_1.resolveManagedHookEvents)(opts.managedHookEvents);
+    const hookScripts = (0, imperative_hook_bus_cjs_1.resolveHookScripts)(events);
     const srcHooksDir = node_path_1.default.join(src, 'hooks');
     const installedScripts = new Set();
     for (const script of hookScripts) {
@@ -880,27 +894,17 @@ function writeCursorHooksJson(targetDir, src, opts) {
         }
     }
     const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
-    const sessionStartCmd = installedScripts.has('gsd-cursor-session-start.js')
-        ? buildHookCommand(targetDir, 'gsd-cursor-session-start.js', hookOpts)
-        : null;
-    const postToolCmd = installedScripts.has('gsd-cursor-post-tool.js')
-        ? buildHookCommand(targetDir, 'gsd-cursor-post-tool.js', hookOpts)
-        : null;
-    const managedEntries = {};
-    if (sessionStartCmd) {
-        managedEntries['sessionStart'] = {
-            type: 'command',
-            command: sessionStartCmd,
-            [GSD_CURSOR_HOOK_MARKER]: true,
-        };
-    }
-    if (postToolCmd) {
-        managedEntries['postToolUse'] = {
-            type: 'command',
-            command: postToolCmd,
-            [GSD_CURSOR_HOOK_MARKER]: true,
-        };
+    const commands = {};
+    for (const ev of events) {
+        const script = imperative_hook_bus_cjs_1.CURSOR_EVENT_SCRIPT_MAP[ev];
+        if (script && installedScripts.has(script)) {
+            commands[ev] = buildHookCommand(targetDir, script, hookOpts);
+        }
+        else {
+            commands[ev] = null;
+        }
     }
+    const managedEntries = (0, imperative_hook_bus_cjs_1.buildHookBusEntries)(events, commands);
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     const result = reconcileCursorHooksJson(hooksJsonPath, managedEntries);
     return { hooksJsonPath, changed: result.changed };
@@ -1449,6 +1453,10 @@ module.exports = {
     removeCursorHooksJson,
     GSD_CURSOR_SESSION_HOOK_SCRIPT,
     GSD_CURSOR_POST_TOOL_HOOK_SCRIPT,
+    GSD_CURSOR_PRE_TOOL_HOOK_SCRIPT,
+    GSD_CURSOR_STOP_HOOK_SCRIPT,
+    GSD_CURSOR_SUBAGENT_START_HOOK_SCRIPT,
+    GSD_CURSOR_SUBAGENT_STOP_HOOK_SCRIPT,
     GSD_CURSOR_HOOK_MARKER,
     // Copilot
     buildCopilotHookConfig,