@opengsd/gsd-core 1.7.0-rc.1 → 1.7.0-rc.3

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

@@ -29,7 +29,7 @@ const phaseIdMod = require("./phase-id.cjs");
 const { escapeRegex, normalizePhaseName, phaseTokenMatches } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { getMilestonePhaseFilter, extractCurrentMilestone } = roadmapParserMod;
+const { getMilestonePhaseFilter, extractCurrentMilestone, getMilestoneInfo } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtilsMod = require("./core-utils.cjs");
 const { extractOneLinerFromBody } = coreUtilsMod;
@@ -112,8 +112,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
-    const milestonesPath = node_path_1.default.join(cwd, '.planning', 'MILESTONES.md');
-    const archiveDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    // #1911: derive the archive base from the workstream-aware planning root so
+    // `milestone complete --ws` archives into the workstream, not root. planningPaths(cwd).planning
+    // resolves to the workstream base when GSD_WORKSTREAM is set and to root .planning otherwise
+    // (flat mode is a no-op).
+    const planningBase = planningPaths(cwd).planning;
+    const milestonesPath = node_path_1.default.join(planningBase, 'MILESTONES.md');
+    const archiveDir = node_path_1.default.join(planningBase, 'milestones');
     const phasesDir = planningPaths(cwd).phases;
     const today = new Date().toISOString().split('T')[0];
     const milestoneName = options.name || version;
@@ -151,7 +156,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             if (stateVersion && stateVersion === version) {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
-                const phasePattern = /#{2,4}\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*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
                 const noDirectoryPhases = [];
                 let pm;
                 const phaseDirEntries = (() => {
@@ -257,11 +263,17 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // Archive REQUIREMENTS.md
     if (node_fs_1.default.existsSync(reqPath)) {
         const reqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
-        const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+        // Derive the display path from the same source the writer uses (reqPath), so a
+        // workstream archive header points at `.planning/workstreams/<ws>/REQUIREMENTS.md`
+        // instead of the hardcoded root path (#1993). Root case is byte-identical.
+        // Normalize to POSIX separators so the header is cross-platform (Windows
+        // path.relative yields backslashes; the original literal was forward-slash).
+        const reqDisplay = node_path_1.default.relative(cwd, reqPath).split(node_path_1.default.sep).join('/');
+        const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`${reqDisplay}\`.\n\n---\n\n`;
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent);
     }
     // Archive audit file if exists
-    const auditFile = node_path_1.default.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+    const auditFile = node_path_1.default.join(planningBase, `${version}-MILESTONE-AUDIT.md`);
     if (node_fs_1.default.existsSync(auditFile)) {
         (0, shell_command_projection_cjs_1.retryRenameSync)(auditFile, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
     }
@@ -309,7 +321,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     }
     // Archive phase directories if requested
     let phasesArchived = false;
-    if (options.archivePhases) {
+    // #1871: archive phase dirs by default on milestone complete (opt out via --no-archive-phases).
+    if (options.archivePhases !== false) {
         try {
             const phaseArchiveDir = node_path_1.default.join(archiveDir, `${version}-phases`);
             (0, shell_command_projection_cjs_1.platformEnsureDir)(phaseArchiveDir);
@@ -398,10 +411,8 @@ function cmdPhasesClear(cwd, raw, args) {
             }
         }
         try {
-            for (const entry of dirs) {
-                node_fs_1.default.rmSync(node_path_1.default.join(phasesDir, entry.name), { recursive: true, force: true });
-                cleared++;
-            }
+            // #1871: archive phase directories instead of destroying them (shared helper).
+            cleared = archivePhaseDirectories(cwd, phasesDir, dirs).archived;
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -410,6 +421,40 @@ function cmdPhasesClear(cwd, raw, args) {
     }
     output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
 }
+/**
+ * #1871: move each non-999 phase directory under `phasesDir` into
+ * `milestones/<version>-phases/` (collision-safe; version from getMilestoneInfo,
+ * timestamp fallback). Shared by `phases clear` (archive-then-remove) and the
+ * internal milestone.complete phase archival so phase history survives a
+ * milestone switch instead of being hard-deleted.
+ */
+function archivePhaseDirectories(cwd, phasesDir, dirs) {
+    let archiveVersion = null;
+    try {
+        archiveVersion = getMilestoneInfo(cwd).version ?? null;
+    }
+    catch {
+        /* ROADMAP/STATE unreadable — fall back to a dated label */
+    }
+    if (!archiveVersion) {
+        archiveVersion = `archived-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 8)}`;
+    }
+    const archivePhasesDir = node_path_1.default.join(planningPaths(cwd).planning, 'milestones', `${archiveVersion}-phases`);
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(archivePhasesDir);
+    let archived = 0;
+    for (const entry of dirs) {
+        const src = node_path_1.default.join(phasesDir, entry.name);
+        // Collision-safe: if a same-named archive entry exists (re-run), suffix it.
+        let dest = node_path_1.default.join(archivePhasesDir, entry.name);
+        let n = 1;
+        while (node_fs_1.default.existsSync(dest)) {
+            dest = node_path_1.default.join(archivePhasesDir, `${entry.name}.${n++}`);
+        }
+        (0, shell_command_projection_cjs_1.retryRenameSync)(src, dest);
+        archived++;
+    }
+    return { archiveDir: archivePhasesDir, archived };
+}
 module.exports = {
     cmdRequirementsMarkComplete,
     cmdMilestoneComplete,

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

@@ -20,6 +20,23 @@ const PROJECT_CODE_PREFIX_STRIP_RE = /^[A-Z][A-Z0-9_]*-(?=\d)/;
 const PROJECT_CODE_PREFIX_STRIP_RE_I = /^[A-Z][A-Z0-9_]*-(?=\d)/i;
 const PROJECT_CODE_PREFIX_CAPTURE_RE_I = /^([A-Z][A-Z0-9_]*)-(\d.*)/i;
 const OPTIONAL_PROJECT_CODE_PREFIX_SOURCE = '(?:[A-Z][A-Z0-9_]*-)?';
+// #1729: phase headers may carry a parenthetical tag between the number and the
+// colon, e.g. `### Phase 26 (Cluster B): Title`. This optional, non-capturing
+// fragment is injected at every phase-header regex call site (immediately after
+// the phase-number token, before the colon/space delimiter) so the resolver
+// tolerates the tag — mirroring how `[...]` is already tolerated before `Phase`.
+// `[^)\n]*` keeps the match single-line (headers are one line) to avoid
+// over-consuming across a malformed multi-line document. Injected at the call
+// site (not baked into phaseMarkdownRegexSource) so it applies uniformly to
+// both the numeric and project-code-exact escaped sources, and so the decimal
+// sub-phase patterns can place it after the `.N` segment.
+//
+// Enumeration/parse call sites that read phase headers from a regex *literal*
+// (rather than a `new RegExp` built from an interpolated phase number) cannot
+// reference this constant; they inline its literal-regex mirror instead —
+// `(?:\s*\([^)\n]*\))?` — kept character-for-character equivalent to this
+// source. Both forms must change together; see the #1729 regression test.
+const OPTIONAL_PHASE_TAG_SOURCE = '(?:\\s*\\([^)\\n]*\\))?';
 function stripProjectCodePrefix(value, caseInsensitive = true) {
     const input = String(value);
     const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
@@ -215,6 +232,7 @@ function phaseTokenMatches(dirName, normalized) {
 module.exports = {
     escapeRegex,
     OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
+    OPTIONAL_PHASE_TAG_SOURCE,
     stripProjectCodePrefix,
     normalizePhaseName,
     getMilestoneFromPhaseId,

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

@@ -32,7 +32,7 @@ const coreUtilsMod = require("./core-utils.cjs");
 const { toPosixPath, generateSlugInternal, readSubdirectories } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal, getArchivedPhaseDirs } = phaseLocatorMod;
@@ -181,7 +181,7 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
         if (node_fs_1.default.existsSync(roadmapPath)) {
             try {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalized)}\\.(\\d+)\\s*:`, 'gi');
+                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalized)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
                 let pm;
                 while ((pm = phasePattern.exec(roadmapContent)) !== null) {
                     decimalSet.add(parseInt(pm[1], 10));
@@ -221,7 +221,7 @@ function getRoadmapModeForPhase(cwd, phaseNum) {
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
     const fullContent = stripShippedMilestones(rawContent);
     const escapedPhase = phaseMarkdownRegexSource(phaseNum);
-    const phaseHeader = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}\\s*:`, 'i');
+    const phaseHeader = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
     for (const content of [milestoneContent, fullContent]) {
         const headerMatch = content.match(phaseHeader);
         if (!headerMatch || headerMatch.index === undefined)
@@ -578,7 +578,8 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             // Three sources are scanned so that a phase in ANY representation
             // (section header, roadmap bullet, or on-disk directory) is counted:
             // 1) Section headers: ### Phase N: / ## Phase N: / #### Phase N:
-            const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
+            // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+            const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]*\))?:/gi;
             // 2) Roadmap bullet entries: - [ ] **Phase N: ...** (all checkbox variants)
             // The lookahead accepts colon, decimal-dot, whitespace, bold-close asterisk,
             // or end-of-line so titleless forms ("- [ ] **Phase 11**", "- [ ] Phase 11")
@@ -662,7 +663,8 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
         const content = extractCurrentMilestone(rawContent, cwd);
         let maxPhase = 0;
         if (config.phase_naming !== 'custom') {
-            const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
+            // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+            const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]*\))?:/gi;
             let m;
             while ((m = phasePattern.exec(content)) !== null) {
                 const num = parseInt(m[1], 10);
@@ -740,14 +742,14 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         const content = extractCurrentMilestone(rawContent, cwd);
         const normalizedAfter = normalizePhaseName(afterPhase);
         const afterPhaseEscaped = phaseMarkdownRegexSource(normalizedAfter);
-        const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+${afterPhaseEscaped}:`, 'i');
+        const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:`, 'i');
         const headingMatch = targetPattern.test(content);
-        const bulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}[:\\s]`, 'i');
+        const bulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
         const anyHeadingPattern = /#{2,4}\s*Phase\s+\d/i;
         const roadmapHasHeadingPhases = anyHeadingPattern.test(content);
         const isBulletStyle = !headingMatch && bulletPattern.test(content) && !roadmapHasHeadingPhases;
         if (!headingMatch && !isBulletStyle) {
-            const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}[:\\s]`, 'i');
+            const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
             if (checklistPattern.test(content)) {
                 error(`Phase ${afterPhase} exists in roadmap summary but is missing a detail section (### Phase ${afterPhase}: ...).`);
             }
@@ -769,7 +771,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         catch {
             /* intentionally empty */
         }
-        const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalizedBase)}\\.(\\d+)\\s*:`, 'gi');
+        const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalizedBase)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
         let rmMatch;
         while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
             decimalSet.add(parseInt(rmMatch[1], 10));
@@ -785,13 +787,13 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dirPath, '.gitkeep'), '');
         let updatedContent;
         if (isBulletStyle) {
-            const boldBulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${afterPhaseEscaped}:`, 'i');
+            const boldBulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:`, 'i');
             const useBold = boldBulletPattern.test(content);
             const phaseLabel = useBold
                 ? `**Phase ${_decimalPhase}: ${description}**`
                 : `Phase ${_decimalPhase}: ${description}`;
             const bulletEntry = `\n- [ ] ${phaseLabel}`;
-            const targetBulletPattern = new RegExp(`(-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}[:\\s][^\\n]*)`, 'i');
+            const targetBulletPattern = new RegExp(`(-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
             const bulletMatchResult = rawContent.match(targetBulletPattern);
             if (!bulletMatchResult) {
                 error(`Could not find Phase ${afterPhase} bullet line`);
@@ -811,7 +813,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         }
         else {
             const phaseEntry = `\n### Phase ${_decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${_decimalPhase} to break down)\n`;
-            const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
+            const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:[^\\n]*\\n)`, 'i');
             const headerMatch = rawContent.match(headerPattern);
             if (!headerMatch) {
                 error(`Could not find Phase ${afterPhase} header`);
@@ -940,11 +942,13 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
     withPlanningLock(cwd, () => {
         let content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const escaped = escapeRegex(targetPhase);
-        content = content.replace(new RegExp(`\\n?(?<h>#{2,4})\\s*Phase\\s+${escaped}\\s*:[\\s\\S]*?(?=\\n\\k<h>(?!#)\\s+Phase\\s+[^\\n:]+\\s*:|$)`, 'i'), '');
-        content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}[:\\s][^\\n]*`, 'gi'), '');
+        content = content.replace(new RegExp(`\\n?(?<h>#{2,4})\\s*Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:[\\s\\S]*?(?=\\n\\k<h>(?!#)\\s+Phase\\s+[^\\n:]+\\s*:|$)`, 'i'), '');
+        content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*`, 'gi'), '');
         content = content.replace(new RegExp(`\\n?\\|\\s*${escaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'), '');
         if (!isDecimal) {
-            content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)(\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
+            // #1729: fold an optional pre-colon ( ) tag into the suffix capture so it
+            // is re-emitted verbatim — a tagged later phase still gets renumbered.
+            content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)((?:\s*\([^)\n]*\))?\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
             content = content.replace(/(-\s*\[[ x]\]\s*.*?Phase\s+)(\d+)(\s*:|\s+)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
             content = content.replace(/(\|\s*)(\d+)(\.\s)/g, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
             content = content.replace(/(?<![0-9-])(\d{2})-(\d{2})(?=(?:(?:-[A-Za-z][A-Za-z0-9-]*)?-(?:PLAN|SUMMARY)\.md)|(?![0-9-]))/g, (_match, phaseNum, planNum) => `${decrementRoadmapPaddedPhaseNumber(phaseNum, removedInt)}-${planNum}`);
@@ -1047,7 +1051,7 @@ function phaseDisplayNameFromRoadmap(roadmapContent, phaseNum) {
     if (!roadmapContent || !phaseNum)
         return null;
     const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
-    const heading = roadmapContent.match(new RegExp(`^#{2,4}\\s*Phase\\s+${phaseEscaped}\\s*:\\s*([^\\n]+)`, 'im'));
+    const heading = roadmapContent.match(new RegExp(`^#{2,4}\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:\\s*([^\\n]+)`, 'im'));
     if (!heading)
         return null;
     const name = heading[1].replace(/\(INSERTED\)/i, '').trim();
@@ -1128,10 +1132,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 const originalRoadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 roadmapContent = originalRoadmapContent;
                 const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
-                const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`, 'i');
+                const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
                 roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
                 const tableRowPattern = new RegExp(`^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
-                roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
+                // Scope the Progress-row search to the ## Progress section so the regex
+                // doesn't bind to an earlier table (e.g. | Phase | Requirements | Count |)
+                // whose rows also start with the phase number. (#2012)
+                const updateProgressRow = (fullRow) => {
                     const cells = fullRow.split('|').slice(1, -1);
                     const dateShape = /^\d{4}-\d{2}-\d{2}$/;
                     if (cells.length === 5) {
@@ -1149,7 +1156,16 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         cells[3] = dateShape.test(existingDate4) ? cells[3] : ` ${today} `;
                     }
                     return '|' + cells.join('|') + '|';
-                });
+                };
+                const progressIdx = roadmapContent.indexOf('## Progress');
+                if (progressIdx >= 0) {
+                    const beforeProgress = roadmapContent.slice(0, progressIdx);
+                    const progressSection = roadmapContent.slice(progressIdx);
+                    roadmapContent = beforeProgress + progressSection.replace(tableRowPattern, updateProgressRow);
+                }
+                else {
+                    roadmapContent = roadmapContent.replace(tableRowPattern, updateProgressRow);
+                }
                 const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, 'i');
                 roadmapContent = roadmapContent.replace(planCountPattern, `$1${summaryCount}/${planCount} plans complete`);
                 const phaseInfoSummaries = phaseInfo['summaries'];
@@ -1170,7 +1186,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 if (node_fs_1.default.existsSync(reqPath)) {
                     const phaseEsc = phaseMarkdownRegexSource(phaseNum);
                     const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd);
-                    const phaseSectionMatch = currentMilestoneRoadmap.match(new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i'));
+                    const phaseSectionMatch = currentMilestoneRoadmap.match(new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i'));
                     const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : '';
                     const reqMatch = sectionText.match(/\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]+)/i);
                     const originalReqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
@@ -1288,15 +1304,21 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 try {
                     const roadmapForPhases = extractCurrentMilestone(roadmapContent, cwd);
                     // #1591: match BOTH heading-style phases (`### Phase N:`) AND
-                    // checkbox-list items (`- [ ] Phase N:` / `- [x] Phase N:`). When
-                    // the active milestone's checklist is `- [ ]` items inside a
-                    // <details> block (and the next phase has no directory yet, so the
-                    // disk-based resolver finds nothing), this roadmap-enumeration
-                    // fallback is the only path that can find the next phase. The prior
-                    // heading-only pattern missed checkbox items → is_last_phase=true on
-                    // a mid-milestone phase. The marker alternation is the only change;
-                    // the number/name captures are unchanged.
-                    const phasePattern = /(?:#{2,4}|-\s*\[[ xX]\])\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+                    // checkbox-list items, INCLUDING the canonical bold form the roadmap
+                    // template emits (`- [ ] **Phase N: Name**`). When the active
+                    // milestone's checklist is `- [ ]` items inside a <details> block
+                    // (and the next phase has no directory yet, so the disk-based
+                    // resolver finds nothing), this roadmap-enumeration fallback is the
+                    // only path that can find the next phase. The prior heading-only
+                    // pattern missed checkbox items, and a checkbox-only broadening still
+                    // missed the bold template rows → is_last_phase=true on a mid-milestone
+                    // phase. Allow optional `**`/`__` emphasis after the marker and stop
+                    // the name capture at emphasis so bold names slug cleanly; the number
+                    // capture is unchanged.
+                    // #1729: `(?:\s*\([^)\n]*\))?` after the number tolerates a pre-colon
+                    // ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE) so
+                    // `### Phase N (Cluster B): X` resolves. Captures are unchanged.
+                    const phasePattern = /(?:#{2,4}|-\s*\[[ xX]\])\s*(?:\*\*|__)?\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n*]+)/gi;
                     let pm;
                     while ((pm = phasePattern.exec(roadmapForPhases)) !== null) {
                         if (comparePhaseNum(pm[1], phaseNum) > 0) {

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

@@ -4,8 +4,8 @@
  * Keeps gsd-tools.cjs thin while preserving current CJS semantics.
  *
  * Unsupported in this router (treated as unknown):
- * - archive: `phases archive` is excluded from the subcommands list so it
- *   falls through to the unknown-subcommand error path.
+ * - archive: `phases archive` is excluded (#2684) — it is an internal
+ *   subcommand that milestone.complete forwards to, not a public surface.
  *
  * ADR-457 build-at-publish: the hand-written bin/lib/phases-command-router.cjs
  * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
@@ -19,7 +19,8 @@ const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
 function routePhasesCommand({ phase, milestone, args, cwd, raw, error }) {
     routeCjsCommandFamily({
         args,
-        // Exclude 'archive' so it hits the unknownMessage path.
+        // #2684: `phases archive` is deliberately excluded — it is an internal
+        // subcommand that milestone.complete forwards to, not a public surface.
         subcommands: command_aliases_cjs_1.PHASES_SUBCOMMANDS.filter((s) => s !== 'archive'),
         error,
         unknownMessage: (_subcommand, available) => `Unknown phases subcommand. Available: ${available.join(', ')}`,

package/gsd-core/bin/lib/plan-scan.cjs

@@ -9,6 +9,9 @@
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtils = require("./core-utils.cjs");
+const { countMatchedSummaries } = coreUtils;
 // Excluded derivative files
 const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
 const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
@@ -72,7 +75,12 @@ function scanPhasePlans(phaseDir) {
     const planFiles = rootPlanFiles.concat(nestedPlanFiles);
     const summaryFiles = rootSummaryFiles.concat(nestedSummaryFiles);
     const planCount = planFiles.length;
-    const summaryCount = summaryFiles.length;
+    // Count only summaries that are the PLAN→SUMMARY partner of an existing plan
+    // (#1988): stray non-plan summaries (e.g. 30-FIX-CR02-SUMMARY.md,
+    // 30-GAPCLOSURE-SUMMARY.md) must not inflate summary_count or flip a phase to
+    // Complete when plans are still missing summaries. summaryFiles (the array)
+    // still holds every summary on disk for callers that read/list them.
+    const summaryCount = countMatchedSummaries(planFiles, summaryFiles);
     return {
         planCount,
         summaryCount,

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

@@ -48,11 +48,40 @@ exports.VALID_STATUS = ['resolved', 'dismissed', 'unresolved'];
 function errMessage(e) {
     return e instanceof Error ? e.message : String(e);
 }
+/**
+ * Structural guard for ONE item of the report `items[]` — enforces the `Item` contract (#1907).
+ * `analyzeCoverage` always emits fully-populated, category/status-validated Items, so this never
+ * rejects legitimate output; it catches an adapter that bypasses the merge and hands back per-item
+ * garbage (e.g. `items:[{}]`) inside a well-shaped envelope — which the container-only guard let
+ * sail through as green output despite the fail-closed docstring below.
+ */
+function isValidItem(item) {
+    if (item == null || typeof item !== 'object')
+        return false;
+    const i = item;
+    if (typeof i.requirement_id !== 'string' || !i.requirement_id.trim())
+        return false;
+    if (typeof i.category !== 'string' || !i.category.trim())
+        return false;
+    if (!exports.VALID_STATUS.includes(i.status))
+        return false;
+    if (typeof i.probe !== 'string')
+        return false;
+    // The three nullable fields must be a string or null — never some other type.
+    if (i.verification !== null && typeof i.verification !== 'string')
+        return false;
+    if (i.resolution !== null && typeof i.resolution !== 'string')
+        return false;
+    if (i.reason !== null && typeof i.reason !== 'string')
+        return false;
+    return true;
+}
 /**
  * Structural guard for the report an adapter's `analyze` returns. The scaffold types `analyze`
  * loosely (it runs over JSON-parsed input the adapter `as`-casts), so a future adapter (#644)
  * that forgets to validate inside its closure could hand back a malformed object. Rather than
- * stringify garbage as green output, `runProbeCli` checks the report shape and fails closed.
+ * stringify garbage as green output, `runProbeCli` checks the report shape — container AND every
+ * item — and fails closed.
  */
 function isValidReport(report) {
     if (report == null || typeof report !== 'object')
@@ -60,6 +89,8 @@ function isValidReport(report) {
     const r = report;
     if (!Array.isArray(r.items))
         return false;
+    if (!r.items.every(isValidItem))
+        return false;
     const c = r.coverage;
     if (c == null || typeof c !== 'object')
         return false;
@@ -373,13 +404,22 @@ function truthStatement(truth) {
 /**
  * Extract a truth's verification tier, or `null` when it carries none (a plain string, or an object
  * with no/garbled marker). Failing toward `null` is the Postel-safe direction: an unrecognized marker
- * grades NORMALLY (never a spurious abstention — the over-abstention guard, AC#3), and the marker is
- * machine-emitted from validated edge data so garbling is not a live input path.
+ * grades NORMALLY (never a spurious abstention — the over-abstention guard, AC#3).
+ *
+ * The marker is NOT only machine-emitted: `must_haves` markers can be authored BY HAND (#1820's
+ * spec-optional predicate rail), and the frontmatter continuation-KV parser preserves stray
+ * surrounding whitespace/quotes on a hand-authored value. So we normalize before comparison
+ * (Postel: be liberal in what you accept) — `'backstop '`, `' backstop'`, `'"backstop"'` all
+ * recognize as the tier. Without this, a hand-authored non-inferable `backstop` truth with a stray
+ * trailing space silently grades green instead of abstaining — the exact #1154 false-pass (#1905).
+ * An unrecoverably-corrupted marker (e.g. an embedded quote) stays unrecognized → null → graded
+ * normally (AC#3): we cannot know its intent, and abstaining on it would be a spurious abstention.
  */
 function truthVerification(truth) {
     if (truth == null || typeof truth !== 'object')
         return null;
-    const v = truth.verification;
+    const raw = truth.verification;
+    const v = typeof raw === 'string' ? raw.trim().replace(/^["']|["']$/g, '').trim() : raw;
     return v === 'explicit' || v === 'backstop' ? v : null;
 }
 /**

package/gsd-core/bin/lib/profile-output.cjs

@@ -1024,7 +1024,7 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
         // project-instruction-file`). Previously this was a codex-only override
         // (#3163) that left AGENTS-native runtimes (opencode/kilo/kimi) emitting
         // CLAUDE.md; copilot now resolves to .github/copilot-instructions.md, and
-        // antigravity/gemini to GEMINI.md. GSD_RUNTIME env var takes precedence
+        // antigravity to GEMINI.md. GSD_RUNTIME env var takes precedence
         // over config.runtime, mirroring detectRuntime().
         //
         // Non-claude runtimes always win over a stale `claude_md_path` (the #3163

package/gsd-core/bin/lib/prohibition-enforcement.cjs

@@ -515,12 +515,12 @@ function defaultProveFailFirst(check, cwd, timeoutMs) {
             // a setup crash, not from the prohibition firing. Requiring the fixture to exist before spawning
             // closes the realistic typo/stale-path case (#1279 review, Major 1).
             //
-            // CAUSATION (#1346): existence + a non-vacuous red is necessary but not sufficient — a deceptive
-            // negative test that reds merely BECAUSE `GSD_PROHIB_SUBJECT` is set (rather than because the
-            // subject's CONTENT violates the must-NOT) would otherwise be accepted. The OPTIONAL `cleanFixture`
-            // control below proves content-dependence when supplied (red on bad AND green on clean). When NO
-            // clean fixture is authored the control cannot run, so the residual remains a documented constraint
-            // for that case (an author opts into the stronger proof by supplying a known-clean control subject).
+            // CAUSATION (#1346; MANDATORY as of #1906): existence + a non-vacuous red is necessary but not
+            // sufficient — a deceptive negative test that reds merely BECAUSE `GSD_PROHIB_SUBJECT` is set
+            // (rather than because the subject's CONTENT violates the must-NOT) would otherwise be accepted.
+            // The `cleanFixture` control below proves content-dependence (red on bad AND green on clean) and is
+            // now REQUIRED for the node-test kind: absent it, the check is un-provable (fail-closed), not
+            // accepted under the weaker violation-only proof (#1906 supersedes #1346's opt-in; ADR-1606 D4).
             // Resolve the fixture against `cwd` (NOT the verify process's cwd): the spawned test reads
             // `GSD_PROHIB_SUBJECT` and resolves a relative subject against `cwd`, so the existence check must
             // use the SAME base or it could pass here yet ENOENT in the child (re-opening the fail-open hole).
@@ -530,20 +530,22 @@ function defaultProveFailFirst(check, cwd, timeoutMs) {
             const redOut = runNodeTestWithSubject(check, cwd, fixture, timeoutMs);
             if (!isNonVacuousNodeTestRed(redOut, check.target))
                 return { provenFailFirst: false, method: 'violation-fixture' };
-            // #1346 CAUSATION CONTROL (optional): if a clean control subject is supplied, run the SAME test
-            // against it and require it to stay GREEN. This proves the red above was caused by the subject's
-            // CONTENT — a deceptive test that reds merely because GSD_PROHIB_SUBJECT is SET reds here too →
-            // not content-dependent → not proven. Absent → no control (documented residual; backward-compat).
+            // #1906 CAUSATION CONTROL (MANDATORY for node-test — supersedes #1346's opt-in, ADR-1606 D4): the
+            // clean control subject is REQUIRED. Run the SAME test against it and require it to stay GREEN,
+            // proving the red above was caused by the subject's CONTENT — a deceptive test that reds merely
+            // because GSD_PROHIB_SUBJECT is SET reds here too → not content-dependent → not proven. ABSENT →
+            // the control cannot run → un-provable → fail-closed (NOT accepted under the weaker violation-only
+            // proof). This is the one behavior change vs #1346: absent `cleanFixture` was previously proven.
             const clean = check.cleanFixture;
-            if (clean) {
-                // A supplied-but-missing/typo'd control path can't run the control → fail-closed, symmetric
-                // with the violation-fixture existence guard (resolve against the SAME `cwd` as the child).
-                if (!node_fs_1.default.existsSync(node_path_1.default.resolve(cwd, clean)))
-                    return { provenFailFirst: false, method: 'violation-fixture' };
-                const cleanOut = runNodeTestWithSubject(check, cwd, clean, timeoutMs);
-                if (!isNonVacuousNodeTestPass(cleanOut, check.target))
-                    return { provenFailFirst: false, method: 'violation-fixture' };
-            }
+            if (!clean)
+                return { provenFailFirst: false, method: 'violation-fixture' };
+            // A supplied-but-missing/typo'd control path can't run the control → fail-closed, symmetric
+            // with the violation-fixture existence guard (resolve against the SAME `cwd` as the child).
+            if (!node_fs_1.default.existsSync(node_path_1.default.resolve(cwd, clean)))
+                return { provenFailFirst: false, method: 'violation-fixture' };
+            const cleanOut = runNodeTestWithSubject(check, cwd, clean, timeoutMs);
+            if (!isNonVacuousNodeTestPass(cleanOut, check.target))
+                return { provenFailFirst: false, method: 'violation-fixture' };
             return { provenFailFirst: true, method: 'violation-fixture' };
         }
         // Unknown kind — defensive; the LOCATE guard already rejects it.

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) {