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

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/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.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");
@@ -94,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 {
@@ -113,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);
@@ -159,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;
@@ -185,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, '');
@@ -249,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
@@ -325,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.
@@ -450,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**")
@@ -507,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}`;
@@ -645,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/state-transition.cjs

@@ -19,6 +19,7 @@ exports.STATE_MD_SECTIONS = exports.FIELD_CLASSIFICATION = void 0;
 exports.getFieldClassification = getFieldClassification;
 exports.applyStatePreservation = applyStatePreservation;
 exports.transitionCore = transitionCore;
+exports.sliceCurrentPositionSection = sliceCurrentPositionSection;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const state_document_cjs_1 = require("./state-document.cjs");
@@ -319,6 +320,20 @@ function locateCurrentPosition(body) {
     }
     return { start, end };
 }
+/**
+ * Return the body text of the `## Current Position` section, or `null` when it
+ * is absent. Reuses the fence-aware `locateCurrentPosition` locator (ADR-1372).
+ *
+ * Exposed so callers that must read a position field (e.g. `cmdStatePrune`,
+ * #1776) can scope extraction to the canonical section instead of the whole
+ * document — where `stateExtractField`'s pipe-table fallback could otherwise
+ * latch onto an unrelated `| Phase | N |` row elsewhere in STATE.md. This
+ * scopes the *caller*; the shared extractor is left broad for every other use.
+ */
+function sliceCurrentPositionSection(body) {
+    const span = locateCurrentPosition(body);
+    return span === null ? null : body.slice(span.start, span.end);
+}
 /**
  * First-time ## Current Position mutation: update Phase / Plan / Status /
  * Last activity lines. Mirrors state.cts:2261-2324 byte-for-behaviour

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

@@ -35,7 +35,7 @@ const { extractFrontmatter, reconstructFrontmatter } = frontmatter;
 const scanPhasePlans = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateTransitionMod = require("./state-transition.cjs");
-const { transitionCore, applyStatePreservation } = stateTransitionMod;
+const { transitionCore, applyStatePreservation, sliceCurrentPositionSection } = stateTransitionMod;
 const state_document_cjs_1 = require("./state-document.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const STATE_PROGRESS_RESYNC_FIELDS = new Set([
@@ -1293,7 +1293,8 @@ function buildStateFrontmatter(bodyContent, cwd) {
                     // truth for total_phases (#549).
                     let roadmapPhaseCount = 0;
                     if (roadmapScope !== null) {
-                        const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+                        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                        const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
                         let m;
                         while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
                             // Only count tokens that contain at least one digit — excludes
@@ -2245,7 +2246,8 @@ function cmdStateSync(cwd, options, raw) {
     try {
         let roadmapPhaseCount = 0;
         if (syncRoadmapScope !== null) {
-            const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+            // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+            const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
             let m;
             while ((m = phaseHeadingPattern.exec(syncRoadmapScope)) !== null) {
                 // Only count tokens that contain at least one digit — excludes
@@ -2321,12 +2323,29 @@ function cmdStatePrune(cwd, options, raw) {
     }
     const keepRecent = parseInt(String(options.keepRecent), 10) || 3;
     const dryRun = !!options.dryRun;
-    // #1760: the canonical STATE.md template emits `Phase: [X] of [Y]`, not
-    // `Current Phase:`. Read both (mirroring buildStateFrontmatter /
-    // resolvePhaseIdForCompletePhase) so prune engages on template-conformant
-    // STATE.md instead of bailing with "Only 0 phases — nothing to prune".
+    // Resolve the current phase via the same canonical chain buildStateFrontmatter
+    // uses (frontmatter `current_phase` → `Current Phase` field → prose `Phase: X
+    // of Y`), so prune engages on template-conformant STATE.md instead of bailing
+    // "Only 0 phases" (#1760).
+    // #1776: scope ONLY the prose `Phase:` term to the canonical `## Current
+    // Position` section. Over the whole body, `stateExtractField`'s pipe-table
+    // fallback matches any `| Phase | N |` row (e.g. a historical verification
+    // table), resolving a stale phase and computing a wrong cutoff. Frontmatter and
+    // the explicit `Current Phase` field are unambiguous, so they stay document-wide;
+    // the shared extractor is not narrowed for any other caller.
     const rawState = node_fs_1.default.readFileSync(statePath, 'utf-8');
-    const currentPhaseRaw = (0, state_document_cjs_1.stateExtractField)(rawState, 'Current Phase') || (0, state_document_cjs_1.stateExtractField)(rawState, 'Phase');
+    const fm = extractFrontmatter(rawState);
+    const body = stripFrontmatter(rawState);
+    // Mirror buildStateFrontmatter's fmScalar: only string/number/boolean
+    // frontmatter scalars are usable (an object/array `current_phase` is ignored,
+    // which also avoids a base-to-string on a non-primitive).
+    const fmRawPhase = fm.current_phase;
+    const fmCurrentPhase = typeof fmRawPhase === 'string' ? (fmRawPhase.trim() || null)
+        : typeof fmRawPhase === 'number' || typeof fmRawPhase === 'boolean' ? String(fmRawPhase)
+            : null;
+    const positionSection = sliceCurrentPositionSection(body);
+    const prosePhase = positionSection !== null ? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(positionSection, 'Phase')).phase : null;
+    const currentPhaseRaw = fmCurrentPhase ?? (0, state_document_cjs_1.stateExtractField)(body, 'Current Phase') ?? prosePhase;
     const currentPhase = parseInt(String(currentPhaseRaw), 10) || 0;
     const cutoff = currentPhase - keepRecent;
     if (cutoff <= 0) {

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

@@ -93,7 +93,8 @@ function buildRoadmapPhaseVariants(roadmapContent) {
     const roadmapPhaseVariants = new Set();
     // Matches both legacy numeric (Phase 1:), decimal (Phase 2.1:), milestone-prefixed (Phase 2-01:),
     // and bracket-prefixed (### [GSD] Phase 2-01:) headings.
-    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
+    // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
     let m;
     while ((m = phasePattern.exec(roadmapContent)) !== null) {
         roadmapPhases.add(m[1]);

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

@@ -40,7 +40,7 @@ const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig, CONFIG_DEFAULTS } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId } = phaseIdMod;
+const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal } = phaseLocatorMod;
@@ -992,7 +992,8 @@ function checkMilestonePrefixMismatches(roadmapContent, { getMilestoneFromPhaseI
     }
     for (const section of sections) {
         const content = roadmapContent.slice(section.start, section.end);
-        const phaseRx = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
+        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const phaseRx = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
         let pm;
         while ((pm = phaseRx.exec(content)) !== null) {
             const phaseId = pm[1];
@@ -1351,7 +1352,7 @@ function cmdValidateHealth(cwd, options, raw) {
                 stateContent.match(/Current Phase:\s*(\S+)/i);
             if (currentPhaseMatch) {
                 const statePhase = currentPhaseMatch[1].replace(/^0+/, '');
-                const phaseCheckboxRe = new RegExp(`-\\s*\\[x\\].*Phase\\s+0*${escapeRegex(statePhase)}[:\\s]`, 'i');
+                const phaseCheckboxRe = new RegExp(`-\\s*\\[x\\].*Phase\\s+0*${escapeRegex(statePhase)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
                 if (phaseCheckboxRe.test(roadmapContentFull)) {
                     const stateStatus = stateContent.match(/\*\*Status:\*\*\s*(.+)/i);
                     const statusVal = stateStatus ? stateStatus[1].trim().toLowerCase() : '';
@@ -1509,7 +1510,8 @@ function cmdValidateHealth(cwd, options, raw) {
             if (isMarkedComplete) {
                 const roadmapRaw = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 const scopedContent = extractCurrentMilestone(roadmapRaw, 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 unstarted = [];
                 let pm;
                 // Non-hoisted: load-order matters (circular dep guard)

package/gsd-core/bin/lib/workstream-inventory-builder.cjs

@@ -28,7 +28,7 @@ function isCompletedInventory(status) {
     return /\bmilestone\s+complete\b/.test(s) || /\barchived\b/.test(s);
 }
 function buildWorkstreamInventory(inputs) {
-    const { name, projectDir, workstreamDir, phaseDirNames, activeWorkstreamName, phaseFilesCounts, roadmapPhaseCount, stateProjection, filesExist, } = inputs;
+    const { name, projectDir, workstreamDir, phaseDirNames, activeWorkstreamName, phaseFilesCounts, roadmapPhaseCount, stateProjection, filesExist, milestoneShipped, } = inputs;
     // Index counts by directory for O(1) lookup during sort/iteration
     const countsMap = new Map();
     for (const entry of phaseFilesCounts) {
@@ -56,6 +56,14 @@ function buildWorkstreamInventory(inputs) {
             summary_count: counts.summaryCount,
         });
     }
+    // #1913: derive status from authoritative shipped signals rather than trusting
+    // the mutable STATE.md `Status` field. When a shipped signal is present, the
+    // workstream is "milestone complete" regardless of a stale field value.
+    const fieldStatus = stateProjection.status;
+    const useDerived = milestoneShipped;
+    const status = useDerived ? 'milestone complete' : fieldStatus;
+    const status_source = useDerived ? 'derived' : 'field';
+    const status_conflict = useDerived && !isCompletedInventory(fieldStatus);
     return {
         name,
         path: toPosixPath(node_path_1.default.relative(projectDir, workstreamDir)),
@@ -65,7 +73,9 @@ function buildWorkstreamInventory(inputs) {
             state: filesExist.state,
             requirements: filesExist.requirements,
         },
-        status: stateProjection.status,
+        status,
+        status_source,
+        status_conflict,
         current_phase: stateProjection.current_phase,
         last_activity: stateProjection.last_activity,
         phases,

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -63,6 +63,33 @@ function readStateProjection(statePath) {
         };
     }
 }
+/**
+ * #1913: detect an authoritative shipped signal for a workstream so the
+ * inventory status is never trusted from the mutable STATE.md `Status` field
+ * alone. Returns true when EITHER an archived milestone snapshot is present
+ * under `<planningBase>/milestones/` OR the workstream ROADMAP carries a
+ * SHIPPED marker — both are hard to desync, unlike the hand-maintained field.
+ */
+function workstreamMilestoneShipped(roadmapPath, planningBase) {
+    try {
+        const milestonesDir = node_path_1.default.join(planningBase, 'milestones');
+        for (const entry of node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true })) {
+            if (entry.isFile() && /-ROADMAP\.md$/i.test(entry.name))
+                return true;
+        }
+    }
+    catch {
+        /* no milestones archive dir */
+    }
+    try {
+        if (/SHIPPED/i.test(node_fs_1.default.readFileSync(roadmapPath, 'utf-8')))
+            return true;
+    }
+    catch {
+        /* no roadmap */
+    }
+    return false;
+}
 function sortWorkstreamInventories(inventories, activeWorkstreamName) {
     return [...inventories].sort((a, b) => {
         const aActive = a.name === activeWorkstreamName ? 1 : 0;
@@ -99,6 +126,7 @@ function inspectWorkstream(cwd, name, options = {}) {
             state: node_fs_1.default.existsSync(p.state),
             requirements: node_fs_1.default.existsSync(p.requirements),
         },
+        milestoneShipped: workstreamMilestoneShipped(p.roadmap, p.planning),
     });
 }
 function listWorkstreamInventories(cwd) {

package/gsd-core/bin/shared/model-catalog.json

@@ -9,7 +9,7 @@
   "runtimeTierDefaults": {
     "claude": {
       "opus": { "model": "claude-opus-4-8" },
-      "sonnet": { "model": "claude-sonnet-4-6" },
+      "sonnet": { "model": "claude-sonnet-5" },
       "haiku": { "model": "claude-haiku-4-5" }
     },
     "codex": {
@@ -29,17 +29,17 @@
     },
     "opencode": {
       "opus": { "model": "anthropic/claude-opus-4-8" },
-      "sonnet": { "model": "anthropic/claude-sonnet-4-6" },
+      "sonnet": { "model": "anthropic/claude-sonnet-5" },
       "haiku": { "model": "anthropic/claude-haiku-4-5" }
     },
     "copilot": {
       "opus": { "model": "claude-opus-4-8" },
-      "sonnet": { "model": "claude-sonnet-4-6" },
+      "sonnet": { "model": "claude-sonnet-5" },
       "haiku": { "model": "claude-haiku-4-5" }
     },
     "hermes": {
       "opus": { "model": "anthropic/claude-opus-4-8" },
-      "sonnet": { "model": "anthropic/claude-sonnet-4-6" },
+      "sonnet": { "model": "anthropic/claude-sonnet-5" },
       "haiku": { "model": "anthropic/claude-haiku-4-5" }
     },
     "kilo": {
@@ -91,13 +91,13 @@
   "providerPresets": {
     "anthropic": {
       "opus":   { "low": { "model": "claude-opus-4-5" }, "medium": { "model": "claude-opus-4-8" }, "high": { "model": "claude-opus-4-8" } },
-      "sonnet": { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-sonnet-4-6" }, "high": { "model": "claude-opus-4-8" } },
-      "haiku":  { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-haiku-4-5" }, "high": { "model": "claude-sonnet-4-6" } }
+      "sonnet": { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-sonnet-5" }, "high": { "model": "claude-opus-4-8" } },
+      "haiku":  { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-haiku-4-5" }, "high": { "model": "claude-sonnet-5" } }
     },
     "anthropic-fable": {
       "opus":   { "low": { "model": "claude-opus-4-5" }, "medium": { "model": "claude-opus-4-8" }, "high": { "model": "claude-fable-5" } },
-      "sonnet": { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-sonnet-4-6" }, "high": { "model": "claude-fable-5" } },
-      "haiku":  { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-haiku-4-5" }, "high": { "model": "claude-sonnet-4-6" } }
+      "sonnet": { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-sonnet-5" }, "high": { "model": "claude-fable-5" } },
+      "haiku":  { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-haiku-4-5" }, "high": { "model": "claude-sonnet-5" } }
     },
     "openai": {
       "opus":   { "low": { "model": "gpt-5.4", "reasoning_effort": "medium" }, "medium": { "model": "gpt-5.5", "reasoning_effort": "high" }, "high": { "model": "gpt-5.5", "reasoning_effort": "xhigh" } },

package/gsd-core/references/agent-skills-bootstrap.md

@@ -0,0 +1,60 @@
+# Agent Skills Self-Load (Bootstrap)
+
+> **Shared contract.** Every `agent_skills` consumer agent self-loads its configured
+> skills in its mandatory init step, so a project's `.planning/config.json`
+> `agent_skills.<agent-type>` mapping reaches the agent that actually does the work —
+> even when the orchestrator did not run bash init (e.g. a runtime whose `Skill()`
+> delegation does not reliably execute the delegated workflow's bash, such as Cursor;
+> see open-gsd/gsd-core#1600 / #1601). This is the durable counterpart to the
+> orchestrator-side injection documented under
+> [Agent Skills Injection](../../docs/CONFIGURATION.md#agent-skills-injection).
+
+## When to run
+
+In your mandatory init step — right after `mandatory-initial-read.md` / the
+`Project skills` discovery, before any other work.
+
+## Steps
+
+1. **Dedup guard (MANDATORY).** Look at your own prompt. If it already contains an
+   `<agent_skills>` block, the orchestrator already injected one — **skip self-load
+   entirely.** Loading a second copy wastes context on runtimes where orchestrator-side
+   injection also runs (e.g. Claude Code). The guard is what keeps the two seams from
+   doubling the block.
+
+2. **Query your configured skills.** Use **your own agent type** — the `name:` value in
+   your frontmatter (e.g. an agent whose frontmatter says `name: gsd-executor` queries
+   `gsd-executor`). The query is read-only and idempotent — it exits 0 with an empty
+   block when nothing is configured for your type:
+
+   ```bash
+   _AGENT_SKILLS=$(gsd_run query agent-skills <YOUR-FRONTMATTER-NAME> 2>/dev/null || true)
+   ```
+
+   The runtime `gsd_run` resolver is the standard one from
+   `_runtime-launcher.snippet.sh`; your own init already defines it.
+
+3. **Read every listed skill.** The block emits entries as `@<path>/SKILL.md`
+   includes — `Read` each one before starting work. If the block is empty, there is
+   nothing to do (zero overhead).
+
+## What self-load does and does not cover
+
+| Skill form | Self-loads? | Notes |
+|---|---|---|
+| Project-relative path (`skills/my-skill`) | ✅ everywhere | `Read` the `@`-include |
+| Global personal (`global:<name>`) | ✅ everywhere | resolves to the runtime global skills dir, then `Read` |
+| Plugin-provided (`global:<plugin>:<skill>`) | Claude only | emitted as a Skill-tool directive on Claude; **skipped with a warning on all other runtimes** — the plugin/Skill-tool model has no equivalent elsewhere (#1601, #1258). Not closeable on Cursor. |
+
+## Notes
+
+- **Idempotent and read-only.** `query agent-skills` never mutates state; calling it
+  twice (once by the orchestrator, once by the agent) is harmless because the dedup
+  guard suppresses the second load.
+- **No new config keys.** This reuses the existing `agent_skills` map and the existing
+  `buildAgentSkillsBlock` / `cmdAgentSkills` machinery (`src/init.cts`). The 22 consumer
+  agent types are mirrored in `tests/agent-skills.test.cjs` (`CONSUMER_AGENTS`) and
+  guarded against drift by `tests/agent-skills-bootstrap.test.cjs`.
+- **Checkers / read-only agents.** Bash is universal across consumer agents, so
+  self-load works for plan-checkers, verifiers, and auditors too; the bootstrap assumes
+  no tool an agent lacks.