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

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;
@@ -47,8 +47,8 @@ const frontmatterMod = require("./frontmatter.cjs");
 const stateMod = require("./state.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
-const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 const clock_cjs_1 = require("./clock.cjs");
+const state_transition_cjs_1 = require("./state-transition.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
 const uatPredicate = require("./uat-predicate.cjs");
 const { evaluateUatPassed } = uatPredicate;
@@ -57,7 +57,7 @@ const verificationMod = require("./verification.cjs");
 const { readVerificationStatus } = verificationMod;
 const { planningDir, withPlanningLock } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
-const { readModifyWriteStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, syncStateFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
+const { readModifyWriteStateMd, stateExtractField, stateReplaceField, syncStateFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
 // #2893 — strict canonical filter: `{padded_phase}-{NN}-PLAN.md` or `PLAN.md`.
 const isCanonicalPlanFile = (f) => f.endsWith('-PLAN.md') || f === 'PLAN.md';
 // Any .md file with PLAN anywhere in the basename — diagnostic net
@@ -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`);
@@ -860,12 +862,12 @@ function renameDecimalPhases(phasesDir, baseInt, removedDecimal) {
         const oldPhaseId = `${baseInt}.${item.oldDecimal}`;
         const newPhaseId = `${baseInt}.${newDecimal}`;
         const newDirName = `${item.prefix}.${newDecimal}-${item.slug}`;
-        node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, item.dir), node_path_1.default.join(phasesDir, newDirName));
+        (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, item.dir), node_path_1.default.join(phasesDir, newDirName));
         renamedDirs.push({ from: item.dir, to: newDirName });
         for (const f of node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, newDirName))) {
             if (f.includes(oldPhaseId)) {
                 const newFileName = f.replace(oldPhaseId, newPhaseId);
-                node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, newDirName, f), node_path_1.default.join(phasesDir, newDirName, newFileName));
+                (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, newDirName, f), node_path_1.default.join(phasesDir, newDirName, newFileName));
                 renamedFiles.push({ from: f, to: newFileName });
             }
         }
@@ -903,12 +905,12 @@ function renameIntegerPhases(phasesDir, removedInt) {
         const oldPrefix = `${oldPadded}${letterSuffix}${decimalSuffix}`;
         const newPrefix = `${newPadded}${letterSuffix}${decimalSuffix}`;
         const newDirName = `${newPrefix}-${item.slug}`;
-        node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, item.dir), node_path_1.default.join(phasesDir, newDirName));
+        (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, item.dir), node_path_1.default.join(phasesDir, newDirName));
         renamedDirs.push({ from: item.dir, to: newDirName });
         for (const f of node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, newDirName))) {
             if (f.startsWith(oldPrefix)) {
                 const newFileName = newPrefix + f.slice(oldPrefix.length);
-                node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, newDirName, f), node_path_1.default.join(phasesDir, newDirName, newFileName));
+                (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, newDirName, f), node_path_1.default.join(phasesDir, newDirName, newFileName));
                 renamedFiles.push({ from: f, to: newFileName });
             }
         }
@@ -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,7 +1132,7 @@ 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) => {
@@ -1170,7 +1174,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');
@@ -1299,7 +1303,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // phase. Allow optional `**`/`__` emphasis after the marker and stop
                     // the name capture at emphasis so bold names slug cleanly; the number
                     // capture is unchanged.
-                    const phasePattern = /(?:#{2,4}|-\s*\[[ xX]\])\s*(?:\*\*|__)?\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n*]+)/gi;
+                    // #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) {
@@ -1321,73 +1328,33 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             if (node_fs_1.default.existsSync(statePath)) {
                 const originalStateContent = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
                 let stateContent = originalStateContent;
-                const phaseValue = nextPhaseNum || phaseNum;
+                // ADR-1769 Phase 3: the STATE.md field-update policy (Current Phase
+                // shape/name, Status, Current Plan, Last Activity + Description, and
+                // the Completed/Total Phases + Progress percent block) now dispatches
+                // to the STATE.md Transition Module. The ~90-line inline RMW callback
+                // that lived here is the pure `completePhaseCore` in
+                // src/state-transition.cts, backed by the field-classification table.
+                // `updatePerformanceMetricsSection` + `syncStateFrontmatter` stay in
+                // this adapter: they are section-table / disk-scan concerns, not
+                // classified fields, and `syncStateFrontmatter` is the post-sync this
+                // transaction needs (it does NOT go through readModifyWriteStateMd
+                // because STATE.md is committed atomically with ROADMAP/REQUIREMENTS).
                 const nextPhaseDisplayName = phaseDisplayNameFromRoadmap(roadmapContent, nextPhaseNum) ??
                     phaseDisplayNameFromSlug(nextPhaseName);
-                const existingPhaseField = stateExtractField(stateContent, 'Current Phase') ||
-                    stateExtractField(stateContent, 'Phase');
-                let newPhaseValue = String(phaseValue);
-                if (existingPhaseField) {
-                    const totalMatch = existingPhaseField.match(/of\s+(\d+)/);
-                    const nameMatch = existingPhaseField.match(/\(([^)]+)\)/);
-                    if (totalMatch) {
-                        const total = totalMatch[1];
-                        const nameStr = nextPhaseDisplayName
-                            ? ` (${nextPhaseDisplayName})`
-                            : nameMatch
-                                ? ` (${nameMatch[1]})`
-                                : '';
-                        newPhaseValue = `${phaseValue} of ${total}${nameStr}`;
-                    }
-                    else if (nextPhaseDisplayName) {
-                        newPhaseValue = `${phaseValue} — ${nextPhaseDisplayName}`;
-                    }
-                }
-                stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Phase', 'Phase', newPhaseValue);
-                if (nextPhaseDisplayName) {
-                    stateContent =
-                        stateReplaceField(stateContent, 'Current Phase Name', nextPhaseDisplayName) ||
-                            stateContent;
-                }
-                stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, isLastPhase ? 'Milestone complete' : 'Ready to plan');
-                stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Plan', 'Plan', 'Not started');
-                const lastActivityDescription = `Phase ${phaseNum} complete${nextPhaseNum ? `, transitioned to Phase ${nextPhaseNum}` : ''}`;
-                if (/^Last activity:/m.test(stateContent)) {
-                    stateContent =
-                        stateReplaceField(stateContent, 'Last activity', `${today} — ${lastActivityDescription}`) ||
-                            stateContent;
-                }
-                else {
-                    stateContent =
-                        stateReplaceField(stateContent, 'Last Activity', today) ||
-                            stateContent;
-                }
-                stateContent =
-                    stateReplaceField(stateContent, 'Last Activity Description', lastActivityDescription) ||
-                        stateContent;
-                const completedRaw = stateExtractField(stateContent, 'Completed Phases');
-                if (completedRaw !== null) {
-                    let newCompleted = parseInt(completedRaw, 10);
-                    let derivedTotalPhases = null;
-                    if (roadmapContent !== null) {
-                        const derived = (0, phase_lifecycle_cjs_1.deriveProgressFromRoadmap)(roadmapContent);
-                        if (derived.completedPhases !== null)
-                            newCompleted = derived.completedPhases;
-                        if (derived.totalPhases !== null)
-                            derivedTotalPhases = derived.totalPhases;
-                    }
-                    stateContent =
-                        stateReplaceField(stateContent, 'Completed Phases', String(newCompleted)) ||
-                            stateContent;
-                    const totalRaw = stateExtractField(stateContent, 'Total Phases');
-                    const totalPhases = derivedTotalPhases || (totalRaw ? parseInt(totalRaw, 10) : null);
-                    if (totalPhases && totalPhases > 0) {
-                        const newPercent = (0, phase_lifecycle_cjs_1.clampPercent)(newCompleted, totalPhases);
-                        stateContent =
-                            stateReplaceField(stateContent, 'Progress', `${newPercent}%`) || stateContent;
-                        stateContent = stateContent.replace(/(percent:\s*)\d+/, `$1${newPercent}`);
-                    }
-                }
+                const completeResult = (0, state_transition_cjs_1.transitionCore)(stateContent, {
+                    kind: 'completePhase',
+                    phaseNum,
+                    nextPhaseNum,
+                    nextPhaseName: nextPhaseDisplayName,
+                    isLastPhase,
+                    planCount,
+                    summaryCount,
+                }, {
+                    clock: clock_cjs_1.realClock,
+                    progressProvider: () => null, // completePhase derives progress from the roadmap, not disk
+                    roadmapProvider: () => roadmapContent,
+                });
+                stateContent = completeResult.content;
                 stateContent = updatePerformanceMetricsSection(stateContent, cwd, phaseNum, planCount, summaryCount);
                 stateContent = syncStateFrontmatter(stateContent, cwd);
                 writes.push({ filePath: statePath, before: originalStateContent, after: stateContent });

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/planning-workspace.cjs

@@ -260,7 +260,7 @@ function withPlanningLock(cwd, fn, clock) {
                         const stolen = lockPath + '.stale-' + process.pid + '-' + clock.now() + '-' + (_planningStealSeq++);
                         let renamed = false;
                         try {
-                            node_fs_1.default.renameSync(lockPath, stolen);
+                            (0, shell_command_projection_cjs_1.retryRenameSync)(lockPath, stolen);
                             renamed = true;
                         }
                         catch { /* another racer won */ }

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

@@ -30,13 +30,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROHIBITION_VALIDATORS = exports.VALID_STATUS = void 0;
+exports.INSUFFICIENT_SPEC = exports.PROHIBITION_VALIDATORS = exports.VALID_STATUS = void 0;
 exports.validateRequirement = validateRequirement;
 exports.validateResolution = validateResolution;
 exports.analyzeCoverage = analyzeCoverage;
 exports.validateProhibitionResolution = validateProhibitionResolution;
 exports.projectProhibitions = projectProhibitions;
 exports.dispositionForProhibition = dispositionForProhibition;
+exports.truthStatement = truthStatement;
+exports.truthVerification = truthVerification;
+exports.projectTruths = projectTruths;
+exports.dispositionForUnverifiableTruth = dispositionForUnverifiableTruth;
 exports.runProbeCli = runProbeCli;
 const node_fs_1 = __importDefault(require("node:fs"));
 /** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
@@ -44,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')
@@ -56,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;
@@ -355,6 +390,101 @@ function dispositionForProhibition(prohibition, context = {}) {
         reason: 'judgment-tier prohibition routes to judgment review — never a silent green (ADR-550 D4)',
     };
 }
+/** Extract a truth's statement text from either the string or the object form (the Hyrum normalizer). */
+function truthStatement(truth) {
+    if (typeof truth === 'string')
+        return truth;
+    if (truth != null && typeof truth === 'object') {
+        const s = truth.statement;
+        if (typeof s === 'string')
+            return s;
+    }
+    return '';
+}
+/**
+ * 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).
+ *
+ * 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 raw = truth.verification;
+    const v = typeof raw === 'string' ? raw.trim().replace(/^["']|["']$/g, '').trim() : raw;
+    return v === 'explicit' || v === 'backstop' ? v : null;
+}
+/**
+ * Conservative serializer (Postel: "send well-formed, minimal data") for projecting truths into a
+ * `must_haves.truths` block — the truth-axis analogue of `projectProhibitions`. A `backstop` truth is
+ * emitted as a flat-scalar object `{ statement, verification: 'backstop' }` (ADR-550 #1278: flat
+ * scalars round-trip the existing `parseMustHavesBlock`; a nested object would mangle it). Every other
+ * truth collapses to a bare statement string — only the non-inferable tier needs a structured marker,
+ * so an `explicit`/inferable truth never carries one (no spurious markers). Empty statements are dropped.
+ */
+function projectTruths(items) {
+    if (!Array.isArray(items))
+        return [];
+    const out = [];
+    for (const item of items) {
+        const statement = truthStatement(item);
+        if (!statement)
+            continue;
+        if (truthVerification(item) === 'backstop') {
+            out.push({ statement, verification: 'backstop' });
+        }
+        else {
+            out.push(statement);
+        }
+    }
+    return out;
+}
+/** The stable, distinguishable verdict-reason token for an abstained non-inferable truth (review condition 1). */
+exports.INSUFFICIENT_SPEC = 'insufficient_spec';
+/**
+ * Deterministic verify-time disposition for a single truth (ADR-550 D4 truth-axis mirror, #1154).
+ * PURE — no LLM judgment (ADR-550 D5); the LLM verifier's only job is to decide whether `evidence`
+ * exists, this helper owns the routing once that is known.
+ *
+ *   - A `backstop` (non-inferable) truth with NO explicit evidence → `{ unverified, flagged }`,
+ *     reason `insufficient_spec`. NEVER green — the verify-time companion to D4's never-silent-pass.
+ *   - A `backstop` truth WITH explicit evidence (a passing wired held-out/property test) → `green`.
+ *     Abstention is for the *unconfirmable*, not for every non-inferable check.
+ *   - Any non-`backstop` truth (explicit, or a plain inferable string) → `green`, never flagged.
+ *     This is the over-abstention guard (AC#3): abstention fires ONLY on the exogenous backstop tag.
+ */
+function dispositionForUnverifiableTruth(truth, context = {}) {
+    const tier = truthVerification(truth);
+    // Over-abstention guard (AC#3): only a backstop (non-inferable) truth is ever a candidate to abstain.
+    if (tier !== 'backstop') {
+        return {
+            status: 'green',
+            flagged: false,
+            tier,
+            reason: 'inferable truth — verified normally (no abstention; ADR-550 D4 over-abstention guard)',
+        };
+    }
+    const evidence = Array.isArray(context.evidence) ? context.evidence : [];
+    if (evidence.length === 0) {
+        // ABSTAIN: a non-inferable truth the verifier cannot confirm with explicit evidence. Routes to
+        // human_needed with the distinguishable insufficient_spec reason — never a silent pass (ADR-550 D4).
+        return { status: 'unverified', flagged: true, tier, reason: exports.INSUFFICIENT_SPEC };
+    }
+    return {
+        status: 'green',
+        flagged: false,
+        tier,
+        reason: 'backstop truth confirmed by explicit evidence (a passing wired held-out/property test or directly-observed behavior)',
+    };
+}
 /**
  * Read the requirements file (and optional resolutions file), run the adapter's `analyze`,
  * and write the report as pretty JSON + newline. With no requirements path, writes the usage