@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/gsd-core/bin/lib/review-reviewer-selection.cjs

@@ -7,10 +7,19 @@
  *
  * Owns reviewer-selection policy projection for /gsd:review:
  * explicit flags > --all > review.default_reviewers > all detected.
+ *
+ * Reviewer instances (#1517): a bounded config surface
+ * `review.reviewer_instances.<name> = {cli, model?, agent?}` lets one
+ * model-capable adapter (e.g. opencode) run as several independent reviewer
+ * identities. Instances participate ONLY in the config_default branch (no
+ * per-instance CLI flags). An instance is available iff its base `cli` is
+ * detected. The instance→cli mapping lives HERE (single source; see the parity
+ * test in tests/review-reviewer-instances.test.cjs — DEFECT.GENERATIVE-FIX).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_REVIEWER_SLUGS = void 0;
+exports.INSTANCE_NAME_PATTERN = exports.KNOWN_REVIEWER_SLUGS = void 0;
 exports.normalizeConfiguredDefaultReviewers = normalizeConfiguredDefaultReviewers;
+exports.normalizeReviewerInstances = normalizeReviewerInstances;
 exports.resolveReviewerSelection = resolveReviewerSelection;
 exports.KNOWN_REVIEWER_SLUGS = [
     'gemini',
@@ -25,6 +34,8 @@ exports.KNOWN_REVIEWER_SLUGS = [
     'lm_studio',
     'llama_cpp',
 ];
+/** Instance names are lowercase slugs that must not shadow a built-in slug. */
+exports.INSTANCE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 function normalizeConfiguredDefaultReviewers(rawValue) {
     if (rawValue === undefined || rawValue === null) {
         return { absent: true, values: [], errors: [] };
@@ -63,14 +74,75 @@ function normalizeConfiguredDefaultReviewers(rawValue) {
     }
     return { absent: false, values: normalized, errors };
 }
+/**
+ * Validate the `review.reviewer_instances` config object (#1517).
+ * `cli` MUST be a known adapter (never an arbitrary shell command — Kerckhoffs /
+ * Postel: strict at the invocation boundary). `model`/`agent` are opaque
+ * pass-through strings; they are never interpolated into shell strings by this
+ * module. Instance names must not collide with a built-in slug.
+ */
+function normalizeReviewerInstances(rawValue) {
+    if (rawValue === undefined || rawValue === null) {
+        return { instances: {}, errors: [] };
+    }
+    if (typeof rawValue !== 'object' || Array.isArray(rawValue)) {
+        return {
+            instances: {},
+            errors: ['review.reviewer_instances must be a JSON object mapping instance names to {cli,model,agent}'],
+        };
+    }
+    const obj = rawValue;
+    const instances = {};
+    const errors = [];
+    for (const [name, spec] of Object.entries(obj)) {
+        if (!exports.INSTANCE_NAME_PATTERN.test(name)) {
+            errors.push(`invalid reviewer instance name '${name}': must match ^[a-z0-9][a-z0-9-]*$`);
+            continue;
+        }
+        if (exports.KNOWN_REVIEWER_SLUGS.includes(name)) {
+            errors.push(`reviewer instance name '${name}' must not equal a built-in reviewer slug`);
+            continue;
+        }
+        if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+            errors.push(`reviewer_instances.${name} must be an object with at least {cli}`);
+            continue;
+        }
+        const s = spec;
+        const cli = s.cli;
+        if (typeof cli !== 'string' || !exports.KNOWN_REVIEWER_SLUGS.includes(cli)) {
+            errors.push(`reviewer_instances.${name}.cli must be a known reviewer adapter (got: ${JSON.stringify(cli)})`);
+            continue;
+        }
+        const instance = { cli };
+        if (s.model !== undefined && s.model !== null) {
+            if (typeof s.model !== 'string') {
+                errors.push(`reviewer_instances.${name}.model must be a string`);
+                continue;
+            }
+            instance.model = s.model;
+        }
+        if (s.agent !== undefined && s.agent !== null) {
+            if (typeof s.agent !== 'string') {
+                errors.push(`reviewer_instances.${name}.agent must be a string`);
+                continue;
+            }
+            instance.agent = s.agent;
+        }
+        instances[name] = instance;
+    }
+    return { instances, errors };
+}
 function resolveReviewerSelection(input) {
     const detected = new Set((input.detected ?? []).map((v) => String(v).toLowerCase()));
     const explicitFlags = new Set((input.explicitFlags ?? []).map((v) => String(v).toLowerCase()));
     const allFlag = !!input.allFlag;
     const normalizedDefaults = normalizeConfiguredDefaultReviewers(input.configuredDefaultReviewers);
+    const normalizedInstances = normalizeReviewerInstances(input.reviewerInstances);
+    const instances = normalizedInstances.instances;
+    const instancesConfigured = Object.keys(instances).length > 0;
     const warnings = [];
     const infos = [];
-    const errors = [...normalizedDefaults.errors];
+    const errors = [...normalizedDefaults.errors, ...normalizedInstances.errors];
     let source = 'no_config_all_detected';
     let selected = [];
     if (explicitFlags.size > 0) {
@@ -90,20 +162,40 @@ function resolveReviewerSelection(input) {
     }
     else if (!normalizedDefaults.absent) {
         source = 'config_default';
-        const knownDefaults = [];
-        for (const slug of normalizedDefaults.values) {
-            if (!exports.KNOWN_REVIEWER_SLUGS.includes(slug)) {
-                warnings.push(`unknown reviewer slug in review.default_reviewers: ${slug}`);
+        // #1517: expand instance references BEFORE the built-in-slug check. An
+        // instance name and a built-in slug are the two legal kinds of entry.
+        for (const entry of normalizedDefaults.values) {
+            if (instances[entry]) {
+                // Instance reference — available iff its base cli is detected.
+                const cli = instances[entry].cli;
+                if (!detected.has(cli)) {
+                    infos.push(`configured instance ${entry} not detected (cli ${cli} missing on this host)`);
+                }
+                else {
+                    selected.push(entry);
+                }
+            }
+            else if (exports.KNOWN_REVIEWER_SLUGS.includes(entry)) {
+                if (!detected.has(entry)) {
+                    infos.push(`configured reviewers not detected on this host: ${entry}`);
+                }
+                else {
+                    selected.push(entry);
+                }
             }
             else {
-                knownDefaults.push(slug);
+                // Neither a defined instance nor a built-in slug.
+                if (instancesConfigured) {
+                    // Most likely a typo'd instance name — must be loud (#1517 design Q2).
+                    errors.push(`reviewer instance '${entry}' referenced in review.default_reviewers is not defined in review.reviewer_instances`);
+                }
+                else {
+                    // Backward-compatible behaviour: unknown slug with no instances
+                    // configured warns and is dropped.
+                    warnings.push(`unknown reviewer slug in review.default_reviewers: ${entry}`);
+                }
             }
         }
-        const undetected = knownDefaults.filter((slug) => !detected.has(slug));
-        if (undetected.length > 0) {
-            infos.push(`configured reviewers not detected on this host: ${undetected.join(', ')}`);
-        }
-        selected = knownDefaults.filter((slug) => detected.has(slug));
         if (selected.length === 0 && errors.length === 0) {
             errors.push('all configured default reviewers are unavailable on this host');
         }
@@ -111,11 +203,35 @@ function resolveReviewerSelection(input) {
     else {
         selected = [...detected];
     }
+    const selectedSorted = selected.sort();
+    // Single-source instance→cli resolution projected onto the selected set.
+    const resolvedInstances = selectedSorted.map((identity) => {
+        const inst = instances[identity];
+        if (inst) {
+            return {
+                identity,
+                kind: 'instance',
+                cli: inst.cli,
+                model: inst.model,
+                agent: inst.agent,
+            };
+        }
+        return { identity, kind: 'builtin', cli: identity };
+    });
+    const cliCounts = {};
+    for (const r of resolvedInstances) {
+        if (r.kind === 'instance') {
+            cliCounts[r.cli] = (cliCounts[r.cli] ?? 0) + 1;
+        }
+    }
+    const sharedAdapterCaveat = Object.values(cliCounts).some((c) => c >= 2);
     return {
         source,
-        selected: selected.sort(),
+        selected: selectedSorted,
         warnings,
         infos,
         errors,
+        resolvedInstances,
+        sharedAdapterCaveat,
     };
 }

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

@@ -46,9 +46,10 @@ function checkW021(content) {
     // Capture the major integer.
     const MILESTONE_RE = /^#{1,3}\s+(?:\[[^\]]+\]\s+|Roadmap\s+|[✅🚧]\s*)?v(\d+)\.\d+(?:\s|:|\s*—)/iu;
     // Migrated phase heading: ### Phase M-NN: Name  (M-NN or unpadded M-N form)
-    const PHASE_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+)-(\d+)(?:-\d+)*\s*:/i;
+    // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    const PHASE_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+)-(\d+)(?:-\d+)*(?:\s*\([^)\n]*\))?\s*:/i;
     // Unprefixed legacy phase heading: ### Phase N: Name  (no hyphen sub-index)
-    const UNPREFIXED_PHASE_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Za-z]?(?:\.\d+)*)\s*:/i;
+    const UNPREFIXED_PHASE_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Za-z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:/i;
     let currentMilestoneMajor = null;
     const lines = content.split('\n');
     for (const line of lines) {

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

@@ -22,7 +22,7 @@ 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, } = phaseIdModule;
+const { escapeRegex, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, stripProjectCodePrefix, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
@@ -82,7 +82,8 @@ function extractCurrentMilestone(content, cwd) {
                 const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : detailsOpenIdx;
                 const preamble = content.slice(0, preambleCutoff)
                     .replace(/<details>[\s\S]*?<\/details>/gi, '')
-                    .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+                    // #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, '')
                     .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
                 return preamble + content.slice(detailsOpenIdx, detailsEnd);
             }
@@ -151,7 +152,8 @@ function extractCurrentMilestone(content, cwd) {
     }
     const preamble = beforeMilestones
         .replace(/<details>[\s\S]*?<\/details>/gi, '')
-        .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+        // #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, '')
         .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
     return detailsSection
         ? preamble + currentSection + '\n' + detailsSection
@@ -171,16 +173,20 @@ function replaceInCurrentMilestone(content, pattern, replacement) {
     return before + after.replace(pattern, replacement);
 }
 function findRoadmapPhaseInContent(content, phaseNum, phaseSource) {
-    const phasePattern = new RegExp(`#{2,4}\\s*(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${phaseSource ?? phaseMarkdownRegexSource(phaseNum)}:\\s*([^\\n]+)`, 'i');
-    const headerMatch = content.match(phasePattern);
+    // #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 headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+    const headingIndex = headings.findIndex((heading) => headingPattern.test(heading.text));
+    if (headingIndex === -1)
+        return null;
+    const heading = headings[headingIndex];
+    const headerMatch = heading.text.match(headingPattern);
     if (!headerMatch)
         return null;
     const phaseName = headerMatch[1].trim();
-    const headerIndex = headerMatch.index;
-    const restOfContent = content.slice(headerIndex);
-    const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i);
-    const sectionEnd = nextHeaderMatch ? headerIndex + nextHeaderMatch.index : content.length;
-    const section = content.slice(headerIndex, sectionEnd).trim();
+    const nextHeading = headings.slice(headingIndex + 1).find((candidate) => candidate.level <= heading.level);
+    const sectionEnd = nextHeading ? nextHeading.offset : content.length;
+    const section = content.slice(heading.offset, sectionEnd).trim();
     const goalMatch = section.match(/\*\*Goal(?:\*\*:|\*?\*?:\*\*)\s*([^\n]+)/i);
     const goal = goalMatch ? goalMatch[1].trim() : null;
     return {
@@ -209,6 +215,9 @@ function roadmapPhaseLookupSources(phaseNum) {
 function getRoadmapPhaseInternal(cwd, phaseNum) {
     if (!phaseNum)
         return null;
+    const normalizedPhase = stripProjectCodePrefix(phaseNum);
+    if (/^999(?:\.|$)/.test(normalizedPhase))
+        return null;
     const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
     if (!node_fs_1.default.existsSync(roadmapPath))
         return null;
@@ -369,7 +378,8 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         }
         // Use tokenizeHeadings (fence-aware) instead of stripFencedLines + regex.
         // T4 seam migration: phase headings inside fences are excluded automatically.
-        const phaseHeadingPattern = /^(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/i;
+        // #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;
         for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(roadmap)) {
             if (h.level < 2 || h.level > 4)
                 continue;

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

@@ -13,6 +13,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_child_process_1 = require("node:child_process");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -416,7 +417,7 @@ function applyMigration(cwd, plan, options = {}) {
             const oldPath = node_path_1.default.join(phasesDir, phaseEntry.oldDir);
             const newPath = node_path_1.default.join(phasesDir, phaseEntry.newDir);
             if (node_fs_1.default.existsSync(oldPath)) {
-                node_fs_1.default.renameSync(oldPath, newPath);
+                (0, shell_command_projection_cjs_1.retryRenameSync)(oldPath, newPath);
                 performedRenames.push({ oldPath, newPath });
                 renamedDirs.push(`${phaseEntry.oldDir} → ${phaseEntry.newDir}`);
             }
@@ -483,7 +484,7 @@ function applyMigration(cwd, plan, options = {}) {
             const { oldPath, newPath } = performedRenames[i];
             try {
                 if (node_fs_1.default.existsSync(newPath))
-                    node_fs_1.default.renameSync(newPath, oldPath);
+                    (0, shell_command_projection_cjs_1.retryRenameSync)(newPath, oldPath);
             }
             catch { /* best-effort */ }
         }

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

@@ -17,13 +17,14 @@ 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 } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, phaseTokenMatches, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserModule = require("./roadmap-parser.cjs");
 const { stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone } = roadmapParserModule;
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -55,8 +56,11 @@ function coerceTruthToString(t) {
         return String(t);
     }
     if (typeof t === 'object') {
-        // Prefer common title-bearing keys produced by parseMustHavesBlock
-        for (const k of ['title', 'text', 'name', 'rule', 'path', 'provides']) {
+        // Prefer common title-bearing keys produced by parseMustHavesBlock. `statement` is the canonical
+        // truth/prohibition payload field — and the carrier of #1154's object-form backstop truth
+        // `{ statement, verification: backstop }`, so it leads (a non-inferable truth must be coerced by
+        // its statement, never dropped — the Hyrum backward-compat guard for the new marker).
+        for (const k of ['statement', 'title', 'text', 'name', 'rule', 'path', 'provides']) {
             const v = t[k];
             if (typeof v === 'string' && v.trim())
                 return v;
@@ -91,12 +95,14 @@ function countPhasePlansAndSummaries(phaseDir) {
  * checklist-only match), or null if the phase is not present at all.
  */
 function searchPhaseInContent(content, escapedPhase, phaseNum) {
-    // Match "## Phase X:", "### Phase X:", or "#### Phase X:" with optional name
-    const phasePattern = new RegExp(`#{2,4}\\s*(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i');
-    const headerMatch = content.match(phasePattern);
+    // #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 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);
     if (!headerMatch) {
         // Fallback: check if phase exists in summary list but missing detail section
-        const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${escapedPhase}:\\s*([^*]+)\\*\\*`, 'i');
+        const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*([^*]+)\\*\\*`, 'i');
         const checklistMatch = content.match(checklistPattern);
         if (checklistMatch) {
             return {
@@ -110,14 +116,12 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
         return null;
     }
     const phaseName = headerMatch[1].trim();
-    const headerIndex = headerMatch.index;
-    // Find the end of this section (next ## or ### phase header, or end of file).
-    // Also matches bracket-prefixed headings like ### [GSD] Phase 2-01:.
-    const restOfContent = content.slice(headerIndex);
-    const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+[\w][\w.-]*/i);
-    const sectionEnd = nextHeaderMatch
-        ? headerIndex + nextHeaderMatch.index
-        : content.length;
+    const headerIndex = headings[headingIndex].offset;
+    const currentHeading = headings[headingIndex];
+    const nextHeading = headings
+        .slice(headingIndex + 1)
+        .find((candidate) => candidate.level <= currentHeading.level);
+    const sectionEnd = nextHeading ? nextHeading.offset : content.length;
     const section = content.slice(headerIndex, sectionEnd).trim();
     // Extract goal if present (supports both **Goal:** and **Goal**: formats)
     const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
@@ -156,6 +160,8 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
  * phase resolution as `roadmap.get-phase` — not a milestone-only subset.
  */
 function getRoadmapPhaseWithFallback(cwd, phaseNum) {
+    if (/^999(?:\.|$)/.test(stripProjectCodePrefix(phaseNum)))
+        return null;
     const roadmapPath = planningPaths(cwd).roadmap;
     if (!node_fs_1.default.existsSync(roadmapPath))
         return null;
@@ -182,6 +188,10 @@ function getRoadmapPhaseWithFallback(cwd, phaseNum) {
 }
 // ─── cmdRoadmapGetPhase ───────────────────────────────────────────────────────
 function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
+    if (/^999(?:\.|$)/.test(stripProjectCodePrefix(phaseNum))) {
+        output({ found: false, phase_number: phaseNum }, raw, '');
+        return;
+    }
     const roadmapPath = planningPaths(cwd).roadmap;
     if (!node_fs_1.default.existsSync(roadmapPath)) {
         output({ found: false, error: 'ROADMAP.md not found' }, raw, '');
@@ -246,7 +256,8 @@ 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
-    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)\s*:\s*([^\n]+)/gi;
+    // #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;
     const phases = [];
     let match;
     // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not real
@@ -322,7 +333,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
         // #3537: padding-tolerant fragment — the heading discovered above may use
         // a different padding than the summary-bullet checkbox below it (mixed
         // padding inside one ROADMAP is legal and seen in real projects).
-        const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}[:\\s]`, 'i');
+        const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
         const checkboxMatch = content.match(checkboxPattern);
         const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
         // If roadmap marks phase complete, trust that over disk file structure.
@@ -447,14 +458,14 @@ 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}(?=[:\\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])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)[^\\n]+`, 'i');
         const planCountText = isComplete
             ? `${summaryCount}/${planCount} plans complete`
             : `${summaryCount}/${planCount} plans executed`;
         roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
         // If complete: check checkbox
         if (isComplete) {
-            const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phasePattern}[:\\s][^\\n]*)`, 'i');
+            const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
             roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
         }
         // Mark completed plan checkboxes (e.g. "- [ ] 50-01-PLAN.md", "- [ ] 50-01:", or "- [ ] **50-01**")
@@ -504,8 +515,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}(?=[:\\s])[\\s\\S]*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
-            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
+            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 sortedMissing = [...missingPlans].sort();
             const newRows = sortedMissing.map(p => `- [ ] ${p}`).join('\n');
             const inserter = (match) => `${match}\n${newRows}`;
@@ -642,7 +653,7 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         // #3537: padding-tolerant fragment so the caller's resolved padded id
         // matches un-padded ROADMAP headings.
         const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
-        const phaseHeaderPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}:[^\\n]*)`, 'i');
+        const phaseHeaderPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:[^\\n]*)`, 'i');
         const phaseMatch = content.match(phaseHeaderPattern);
         if (!phaseMatch)
             return;

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

@@ -25,6 +25,7 @@ const commandRoster = require("./command-roster.cjs");
 const { readGsdCommandNames, transformContentToHyphen } = commandRoster;
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
 const { getDirName } = runtimeNamePolicy;
+const capabilityRegistry = require("./capability-registry.cjs");
 // #1383: resolve GSD's version WITHOUT a top-level
 // `require('../../../package.json')`. That require ran at module load on every
 // gsd-tools invocation (this module sits in the gsd-tools loader chain) and
@@ -1997,16 +1998,15 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
 }
 /**
  * Canonical list of every non-Claude runtime that gsd-core emits artifacts for.
- * Exported so test files can import this single source of truth rather than
- * maintaining divergent hand-rolled arrays (#1521).
- *
- * Keep in sync with the runtime flags in bin/install.js and getDirName().
+ * DERIVED from the capability registry (ADR-1239 Phase B, #1679) — the registry's
+ * `runtimes` map is the single source of truth for runtime identity, so the
+ * non-Claude set is its key set minus 'claude'. This replaces a hand-maintained
+ * literal that had to be kept in sync with bin/install.js and getDirName(), and
+ * can no longer drift from the registry. Exported so tests import one source (#1521).
  */
-const NON_CLAUDE_RUNTIMES = [
-    'codex', 'opencode', 'kilo', 'gemini', 'copilot', 'antigravity',
-    'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'kimi',
-    'codebuddy', 'cline',
-];
+const NON_CLAUDE_RUNTIMES = Object.keys(capabilityRegistry.runtimes)
+    .filter((id) => id !== 'claude')
+    .sort();
 /**
  * #1521: Every non-Claude runtime resolves its own runtime identity from a
  * runtime-neutral config, and defaults workflow.use_worktrees to false —
@@ -2310,6 +2310,59 @@ function rewriteStagedCommandBodies(stagedDir, opts) {
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
     return applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathPrefix, isGlobal, attribution);
 }
+/**
+ * Runtimes that use the hyphen-namespace form `/gsd-<cmd>` in agent bodies.
+ * claude/qwen/hermes use hyphen-name:`...` frontmatter; cursor/windsurf/etc
+ * self-convert. Mirrors the `HYPHEN_NAME_AGENT_RUNTIMES` set in bin/install.js.
+ *
+ * @private — export normalizeAgentBodyForRuntime for callers.
+ */
+const HYPHEN_NAME_AGENT_RUNTIMES = new Set(['claude', 'qwen', 'hermes']);
+/**
+ * Normalize `/gsd:<cmd>` colon refs in the agent body to `/gsd-<cmd>` for
+ * hyphen-`name:` runtimes (claude / qwen / hermes). No-op for all other
+ * runtimes. Mirrors the per-file call in bin/install.js line 9400.
+ *
+ * @param content   raw agent file content (post-converter)
+ * @param runtime   canonical runtime ID
+ * @param cmdNames  gsd command names from readGsdCommandNames()
+ */
+function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
+    if (!HYPHEN_NAME_AGENT_RUNTIMES.has(runtime))
+        return content;
+    return transformContentToHyphen(content, cmdNames);
+}
+/**
+ * Apply the 4 base `~/.claude/` path-prefix rewrites to a single agent content
+ * string. Mirrors the inline agent loop in bin/install.js lines 9330-9340:
+ *   ~/\.claude/ → pathPrefix
+ *   $HOME/\.claude/ → pathPrefix
+ *   ~/\.claude\b → normalizedPathPrefix
+ *   $HOME/\.claude\b → normalizedPathPrefix
+ *
+ * Skipped for copilot and antigravity (which do NOT do path rewrites in the
+ * inline loop). NO stamp (_stampNonClaudeRuntimeDefaults) — agents are NOT
+ * stamped in the inline loop.
+ *
+ * ADR-1235 §1: pre-converter cross-cutting for descriptor-driven agent pipeline.
+ * Exported as `applyAgentPathRewrites` for testing and for injection into
+ * stageAgentsForRuntimeWithConverter via agentCtx.
+ *
+ * @param content     raw agent file content
+ * @param runtime     canonical runtime ID
+ * @param pathPrefix  trailing-slash path prefix (e.g. '$HOME/.cursor/')
+ * @returns content with path-prefix rewrites applied (or unchanged for copilot/antigravity)
+ */
+function applyAgentPathRewrites(content, runtime, pathPrefix) {
+    if (runtime === 'copilot' || runtime === 'antigravity')
+        return content;
+    const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
+    content = content.replace(/~\/\.claude\//g, pathPrefix);
+    content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
+    content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
+    content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
+    return content;
+}
 // ── End rewrite engine ────────────────────────────────────────────────────────
 /**
  * Apply Co-Authored-By attribution policy to file content.
@@ -2398,6 +2451,9 @@ module.exports = {
     // High-level wrappers (derive pathPrefix + attribution from opts):
     rewriteStagedSkillBodies,
     rewriteStagedCommandBodies,
+    // ADR-1235 §1: descriptor-driven agent cross-cutting
+    applyAgentPathRewrites,
+    normalizeAgentBodyForRuntime,
     _computePathPrefix: computePathPrefix,
     _applyRuntimeRewrites,
     _stampNonClaudeRuntimeDefaults,