@opengsd/gsd-core 1.9.1 → 1.10.0

package/gsd-core/bin/lib/retired-artifact-cleanup.cjs

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Conservative cleanup for artifact surfaces retired by a runtime descriptor.
+ *
+ * A descriptor may stop materializing an artifact kind while old installs
+ * still contain files from that surface. Install and profile/surface apply
+ * both call this helper so either path converges an existing installation.
+ * Only files proven managed by the previous install manifest are removed;
+ * modified and unknown files are preserved for the journaled installer
+ * migration (or the user) to handle without data loss.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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 installerMigrations = require("./installer-migrations.cjs");
+const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
+// Generated at build time, so no TypeScript source declaration exists.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityRegistry = require('./capability-registry.cjs');
+function retiredArtifactsFor(runtime) {
+    const configured = capabilityRegistry.runtimes?.[runtime]?.runtime?.hostBehaviors?.retiredArtifacts;
+    return Array.isArray(configured) ? configured : [];
+}
+function pruneRetiredRuntimeArtifacts(runtime, configDir) {
+    const result = { removed: [], preserved: [] };
+    const declarations = retiredArtifactsFor(runtime);
+    if (declarations.length === 0)
+        return result;
+    const manifest = installerMigrations.readInstallManifest(configDir);
+    for (const declaration of declarations) {
+        const destSubpath = declaration.destSubpath;
+        const prefix = declaration.prefix;
+        const suffix = declaration.suffix;
+        if (typeof destSubpath !== 'string' || destSubpath.length === 0 ||
+            typeof prefix !== 'string' || prefix.length === 0 ||
+            typeof suffix !== 'string' || suffix.length === 0 ||
+            !(0, external_descriptor_trust_cjs_1.isPathConfined)(destSubpath, configDir)) {
+            continue;
+        }
+        const destDir = node_path_1.default.resolve(configDir, destSubpath);
+        let entries;
+        try {
+            if (!node_fs_1.default.existsSync(destDir) || node_fs_1.default.lstatSync(destDir).isSymbolicLink())
+                continue;
+            entries = node_fs_1.default.readdirSync(destDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith(suffix))
+                continue;
+            const relPath = node_path_1.default.posix.join(destSubpath.replace(/\\/g, '/'), entry.name);
+            const artifact = installerMigrations.classifyArtifact(configDir, relPath, manifest);
+            if (artifact.classification !== 'managed-pristine') {
+                result.preserved.push(relPath);
+                continue;
+            }
+            try {
+                node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, entry.name));
+                result.removed.push(relPath);
+            }
+            catch {
+                result.preserved.push(relPath);
+            }
+        }
+        try {
+            if (node_fs_1.default.readdirSync(destDir).length === 0)
+                node_fs_1.default.rmdirSync(destDir);
+        }
+        catch {
+            // Non-empty, unreadable, or concurrently changed: preserve the directory.
+        }
+    }
+    return result;
+}
+module.exports = { pruneRetiredRuntimeArtifacts, retiredArtifactsFor };

package/gsd-core/bin/lib/review-lane-descriptor.cjs

@@ -52,6 +52,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DOCS_PARITY_VIOLATION = exports.LANE_SLUG_RE = exports.PARITY_VIOLATION = exports.REVIEWER_LANES = exports.ARGV_PLACEHOLDER = void 0;
+exports.mergeReviewerLanes = mergeReviewerLanes;
 exports.checkReviewerLaneParity = checkReviewerLaneParity;
 exports.checkReviewerDocsParity = checkReviewerDocsParity;
 /**
@@ -423,6 +424,104 @@ exports.REVIEWER_LANES = Object.freeze([
         handler: null,
     },
 ].map((lane) => Object.freeze(lane)));
+/**
+ * Merge the first-party lane set with installed overlay `reviewer` bodies
+ * (ADR-2782 D8: first-party ∪ overlay, first-party wins on slug collision).
+ *
+ * `routeReviewLane` (gsd-core/bin/gsd-tools.cjs) consumes this to build the lane
+ * map its `sections`/`flags`/`plan`/`invoke` subcommands resolve against, so an
+ * installed, consented third-party reviewer capability (`role:"reviewer"` with a
+ * declared `reviewer` body) becomes selectable, plannable, and invocable through
+ * the same surface as a built-in lane — closing #2927, where the overlay was
+ * roster-visible (`deriveReviewerSlugs`) and disclosed at install
+ * (`collectReviewerLaneSurfaces`) but never reached the invocation path.
+ *
+ * ADR-2782 D1 deliberately made the manifest `reviewer` body field-identical to
+ * `ReviewerLaneCommon` so "Phase 2 harvests the shape into the capability manifest
+ * with no translation layer" (CONTEXT.md reviewer-lane-descriptor predicate). The
+ * overlay body IS already `ReviewerLane`-shaped; this function MERGES, it does not
+ * PROJECT — there is no field renaming, no vocabulary translation. That is the
+ * design decision the bug violated by simply never calling anything.
+ *
+ * Pure and TOTAL — never throws on any input, because third-party overlay
+ * manifests are untrusted data reaching this seam at load time. A cap whose
+ * `reviewer` body is absent, non-object, or carries an empty/grammar-invalid slug
+ * is SKIPPED (contributes no lane) rather than crashing, so one malformed overlay
+ * cannot take the whole `review-lane` surface (and every first-party lane with it)
+ * down. The slug grammar (`LANE_SLUG_RE`) is enforced HERE even though
+ * `resolveLanePlan`'s trust boundary re-checks it, because `sections`/`flags` read
+ * lane fields before reaching `resolveLanePlan` — defense in depth against the
+ * path-traversal class the invocation boundary exists for.
+ *
+ * First-party wins: an overlay declaring a slug that already names a first-party
+ * lane is silently superseded (the first-party entry is kept, identity-stable),
+ * never overwritten. The first-party object is returned by reference, not copied.
+ *
+ * @param firstParty The frozen first-party lane set (`REVIEWER_LANES`).
+ * @param registry   The merged capability registry
+ *                   (`loadRegistry({ includeInstalled: true })`); only its
+ *                   `capabilities` map is read. A cap contributes a lane iff it
+ *                   carries an object `reviewer` body with a non-empty,
+ *                   grammar-valid `slug`. The `role:"runtime"` legacy
+ *                   `reviewerCli` alias contributes NO lane here — it has no lane
+ *                   descriptor, and the selection roster (`deriveReviewerSlugs`)
+ *                   is a separate surface.
+ * @returns A NEW array: first-party lanes (in order) followed by accepted overlay
+ *          lanes (in registry iteration order). Callers must not mutate it.
+ */
+function mergeReviewerLanes(firstParty, registry) {
+    // First-party always wins and is returned by reference (identity-stable), so a
+    // collision cannot perturb the first-party entry a consumer already holds.
+    const bySlug = new Map();
+    const ordered = [];
+    for (const lane of firstParty) {
+        const slug = typeof lane.slug === 'string' ? lane.slug.trim() : '';
+        if (!slug)
+            continue; // unreachable for the shipped frozen set, but this is exported
+        if (!bySlug.has(slug)) {
+            bySlug.set(slug, lane);
+            ordered.push(lane);
+        }
+    }
+    const capabilities = (registry && registry.capabilities) || {};
+    for (const cap of Object.values(capabilities)) {
+        if (cap === null || typeof cap !== 'object' || Array.isArray(cap))
+            continue;
+        const body = cap.reviewer;
+        // C1/C2 (mirroring collectReviewerLaneSurfaces): a missing, null, or
+        // non-object reviewer body declares no lane — never an error at this layer.
+        if (body === null || typeof body !== 'object' || Array.isArray(body))
+            continue;
+        const rawSlug = body.slug;
+        const slug = typeof rawSlug === 'string' ? rawSlug.trim() : '';
+        // Empty/whitespace slug: nothing to key on. Grammar-invalid slug: the
+        // path-traversal class — skip rather than admit, even though resolveLanePlan
+        // would reject it downstream. Both are skips, not throws.
+        if (!slug || !exports.LANE_SLUG_RE.test(slug))
+            continue;
+        if (bySlug.has(slug))
+            continue; // D8: first-party (or an earlier overlay) wins
+        // The body is already ReviewerLane-shaped per ADR-2782 D1. We do NOT
+        // deep-validate every field here: the invocation trust boundary
+        // (resolveLanePlan) is the seam that re-validates a lane before it runs, and
+        // `sections`/`flags` are both tolerant of a partial body (flags filters by
+        // shape; sections reads slug/reviewsSection which a non-string cap simply
+        // renders as undefined). Admitting the body keeps the merge a pure merge.
+        //
+        // The slug is normalized to its trimmed value on the stored lane so the merge
+        // and the selection roster (`deriveReviewerSlugs`, which trims before adding)
+        // agree on the canonical key — otherwise a body declaring `slug: '  x  '`
+        // would key the map on `'x'` but emit the raw `'  x  '` in `sections` and fail
+        // to match a `--selected` value coming from the roster. (The capability
+        // validator's grammar check rejects surrounding whitespace before this is
+        // reachable through a real install, so this is belt-and-braces parity with the
+        // roster, not a live-input guard.)
+        const lane = { ...body, slug };
+        bySlug.set(slug, lane);
+        ordered.push(lane);
+    }
+    return ordered;
+}
 /* ------------------------------------------------------------------ *
  * DEFECT.GENERATIVE-FIX parity (CONTEXT.md:797)
  * ------------------------------------------------------------------ */

package/gsd-core/bin/lib/review-lane-runner.cjs

@@ -283,18 +283,32 @@ function antigravityWatermark(workspace, deps) {
         return { convId, lines: deps.readFile(tx).split(/\r?\n/).filter((l) => l.trim()).length };
     }
     catch {
-        return { convId, lines: 0 };
+        // #3118: this conv-id pre-dates this run, so its transcript exists but this run cannot verify
+        // its line count. Reporting `lines: 0` would assert a fact we could not check — flag it instead
+        // so the fallback can decline rather than silently skip zero and replay a stale response.
+        return { convId, lines: 0, unreadable: true };
     }
 }
-/** Workspace lookup is case-insensitive — the leg's jq did `ascii_downcase` on both sides. */
+/**
+ * Workspace lookup is case-insensitive — the leg's jq did `ascii_downcase` on both sides.
+ *
+ * #3118: a successful `JSON.parse` does not by itself make the payload a usable object —
+ * `JSON.parse('null')` succeeds and returns `null`, so a truncated/zeroed cache file slips past
+ * the callers' parse-only try/catch. `typeof null === 'object'`, so the guard below must exclude
+ * `null` explicitly. Arrays are excluded too (not a workspace map), which also falls out of the
+ * `Object.entries`/`hasOwnProperty` lookups below returning nothing for array input.
+ */
 function resolveConvId(cache, workspace) {
-    if (Object.prototype.hasOwnProperty.call(cache, workspace)) {
-        const direct = cache[workspace];
+    if (cache === null || typeof cache !== 'object')
+        return '';
+    const record = cache;
+    if (Object.prototype.hasOwnProperty.call(record, workspace)) {
+        const direct = record[workspace];
         if (typeof direct === 'string' && direct)
             return direct;
     }
     const target = workspace.toLowerCase();
-    for (const [k, v] of Object.entries(cache)) {
+    for (const [k, v] of Object.entries(record)) {
         if (k.toLowerCase() === target && typeof v === 'string' && v)
             return v;
     }
@@ -324,6 +338,10 @@ function antigravityTranscriptFallback(workspace, mark, deps) {
     const convId = resolveConvId(cache, workspace);
     if (!convId)
         return '';
+    // #3118: the watermark could not read this conversation's transcript, so there is no trustworthy
+    // skip for it. Declining is the fail-closed answer; skipping 0 would replay a prior run's review.
+    if (mark.unreadable === true && convId === mark.convId)
+        return '';
     const tx = transcriptPath(deps.homeDir, convId);
     if (!deps.exists(tx))
         return '';
@@ -549,7 +567,13 @@ function runSpawnLane(plan, deps, repoRoot) {
         ? antigravityArgv(plan.argv, plan.promptPath, repoRoot, deps)
         : plan.argv;
     const out = deps.spawn(plan.binary, argv, { input, timeoutMs: plan.timeoutMs });
-    deps.writeFile(plan.errPath, out.stderr ?? '');
+    // #3086: surface spawn errors (ENOENT, ETIMEDOUT, etc.) that would otherwise
+    // be silently dropped — the review path read only stdout/stderr and treated
+    // an empty-stderr spawn failure as "the model had nothing to say".
+    const errContent = out.errorCode
+        ? `${out.stderr ?? ''}\n[spawn error: ${out.errorCode}]\n`
+        : (out.stderr ?? '');
+    deps.writeFile(plan.errPath, errContent);
     // `file-arg` lanes write the review themselves and their stdout is deliberately discarded (#1698).
     let review = plan.outputTarget.kind === 'file'
         ? deps.exists(plan.outputTarget.path)

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

@@ -24,6 +24,9 @@ const { planningDir } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig } = configLoaderMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitMod = require("./cli-exit.cjs");
+const { ExitError } = cliExitMod;
 // ─── W021 Implementation ──────────────────────────────────────────────────────
 /**
  * Check each phase entry in a milestone-prefixed ROADMAP.md for W021 violations.
@@ -110,12 +113,40 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
             'annotate-dependencies': () => roadmap.cmdRoadmapAnnotateDependencies(cwd, args[2], raw),
             'validate': () => {
                 const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
-                let roadmapContent = '';
+                const warnings = [];
+                // #2978: structural validation. A verb named "validate" that cannot
+                // produce a negative result provides false assurance. Before the
+                // opt-in milestone-prefix check, verify the file is structurally a
+                // roadmap at all.
+                let roadmapContent;
                 try {
                     roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf8');
                 }
                 catch {
-                    // ROADMAP.md missing — return empty warnings
+                    // ROADMAP.md missing — not silent success.
+                    warnings.push({ code: 'V001', message: 'ROADMAP.md not found or unreadable' });
+                    const result = { warnings };
+                    process.stdout.write(raw ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+                    throw new ExitError(1);
+                }
+                // Empty or whitespace-only.
+                if (roadmapContent.trim() === '') {
+                    warnings.push({ code: 'V002', message: 'ROADMAP.md is empty' });
+                }
+                // Malformed frontmatter — a `---` opener with no matching closer.
+                // Tolerate a leading BOM (#3057) before the fence.
+                const contentAfterBom = roadmapContent.replace(/^\uFEFF/, '');
+                if (contentAfterBom.startsWith('---')) {
+                    const closeMatch = contentAfterBom.slice(3).match(/\r?\n---\s*(\r?\n|$)/);
+                    if (!closeMatch) {
+                        warnings.push({ code: 'V003', message: 'ROADMAP.md frontmatter is malformed (unterminated --- fence)' });
+                    }
+                }
+                // No recognizable phase structure — at least one `### Phase N:` heading.
+                // Mirrors the phase-heading pattern used across roadmap-parser.cts.
+                const hasPhaseEntry = /^#{2,4}\s*Phase\s+\S/im.test(roadmapContent);
+                if (!hasPhaseEntry && !warnings.some((w) => w.code === 'V002')) {
+                    warnings.push({ code: 'V004', message: 'ROADMAP.md contains no recognizable phase entries (no "### Phase N:" headings)' });
                 }
                 // W021 only fires when phase_id_convention is explicitly 'milestone-prefixed'.
                 // Authoritative source: .planning/config.json (set by the upgrade command).
@@ -141,14 +172,16 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                         }
                     }
                 }
-                const warnings = (convention === 'milestone-prefixed')
-                    ? checkW021(roadmapContent)
-                    : [];
+                if (convention === 'milestone-prefixed') {
+                    warnings.push(...checkW021(roadmapContent));
+                }
                 const result = { warnings };
-                if (raw)
-                    process.stdout.write(JSON.stringify(result));
-                else
-                    process.stdout.write(JSON.stringify(result, null, 2));
+                process.stdout.write(raw ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+                // #2978: exit non-zero on any warning, per the documented contract
+                // ("exits non-zero on any error or warning").
+                if (warnings.length > 0) {
+                    throw new ExitError(1);
+                }
             },
             'upgrade': () => {
                 const dryRun = !args.includes('--apply');

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

@@ -36,21 +36,76 @@ const unusableInputMod = require("./unusable-input.cjs");
 const { UNUSABLE_REASON, warnUnusableInput } = unusableInputMod;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Roadmap milestone scoping ───────────────────────────────────────────────
+/**
+ * Markers that classify a MILESTONE HEADING (or `<summary>`) as closed/shipped
+ * versus still active. Hoisted to module scope in #2562 — three call sites
+ * (`extractCurrentMilestone`, `currentMilestoneRawRanges`,
+ * `isMilestoneShippedInRoadmap`) previously kept byte-identical copies.
+ */
+const MILESTONE_CLOSED_MARKER_PATTERN = /\b(?:CLOSED|ARCHIVED|ABANDONED|SHIPPED|FAILED)\b|✅|🗄/i;
+const MILESTONE_ACTIVE_MARKER_PATTERN = /\b(?:STARTED|ACTIVE|WIP)\b|in\s+progress|🚧|🔄/i;
+function isClosedMilestoneHeading(headingText) {
+    return MILESTONE_CLOSED_MARKER_PATTERN.test(headingText) && !MILESTONE_ACTIVE_MARKER_PATTERN.test(headingText);
+}
 /**
  * Strip shipped milestone content wrapped in <details> blocks.
  */
 function stripShippedMilestones(content) {
     return (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(content, 'details');
 }
+/**
+ * #2562: is the milestone `version` marked SHIPPED by the ROADMAP itself?
+ *
+ * Scoped deliberately narrowly, because a false positive here reproduces the
+ * exact symptom #2562 reports ("milestone complete" while phases are unstarted):
+ *
+ * - Only a MILESTONE HEADING (`^#{1,3}` that is not a `Phase N:` heading) or a
+ *   `<summary>` line can carry the signal. A bullet or checklist item that
+ *   merely NAMES the version (`- [x] 03-01: ship the v2.0 login endpoint ✅`)
+ *   is prose about a phase, not a milestone verdict, and is ignored.
+ * - The version token is boundary-matched with `(?![\w.-])` (mirrors the #730
+ *   sub-milestone boundary at `extractCurrentMilestone`), so `v2.0` does not
+ *   match inside `v2.0.1` — `\b` alone would, since `.` is a non-word char.
+ * - Shipped/active classification reuses the same marker patterns the milestone
+ *   sectioniser uses, so an in-progress marker on the line always wins.
+ *
+ * Both patterns are anchored and use only complementary character classes
+ * (`[^\n]`, `[^<]`, `[^>]`) with no overlapping alternation, so matching stays
+ * linear in the ROADMAP's length — an untrusted ROADMAP cannot drive backtracking.
+ */
+function isMilestoneShippedInRoadmap(content, version) {
+    const boundedVersion = `${escapeRegex(version)}(?![\\w.-])`;
+    const candidates = [
+        // A milestone heading: `## v2.0 Launch — ✅ SHIPPED`.
+        new RegExp(`^#{1,3}[^\\S\\n]+(?!Phase\\s+\\S)[^\\n]*${boundedVersion}[^\\n]*$`, 'gmi'),
+        // A collapsed shipped block's own summary: `<summary>✅ v2.0 … SHIPPED</summary>`.
+        new RegExp(`<summary[^>]*>[^<]*${boundedVersion}[^<]*<\\/summary>`, 'gi'),
+    ];
+    for (const pattern of candidates) {
+        for (const match of content.matchAll(pattern)) {
+            if (isClosedMilestoneHeading(match[0]))
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * Extract the current milestone section from ROADMAP.md by positive lookup.
+ *
+ * @param content - ROADMAP.md content.
+ * @param cwd - Project working directory, used to read the companion STATE.md
+ *   for the current `milestone:` version.
+ * @param ws - #2562: workstream name, so the companion STATE.md is read from
+ *   `.planning/workstreams/<ws>/` instead of the project root. Omitted (the
+ *   default) preserves the prior `planningDir(cwd)` resolution exactly,
+ *   including its `GSD_WORKSTREAM` env fallback.
  */
-function extractCurrentMilestone(content, cwd) {
+function extractCurrentMilestone(content, cwd, ws) {
     if (!cwd)
         return stripShippedMilestones(content);
     let version = null;
     try {
-        const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
+        const statePath = node_path_1.default.join(planningDir(cwd, ws), 'STATE.md');
         const stateRaw = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
         if (stateRaw !== null) {
             const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
@@ -97,9 +152,7 @@ function extractCurrentMilestone(content, cwd) {
         return stripShippedMilestones(content);
     }
     const allMatches = headingMatches;
-    const closedMarkerPattern = /\b(?:CLOSED|ARCHIVED|ABANDONED|SHIPPED|FAILED)\b|✅|🗄/i;
-    const activeMarkerPattern = /\b(?:STARTED|ACTIVE|WIP)\b|in\s+progress|🚧|🔄/i;
-    const isClosed = (h) => closedMarkerPattern.test(h) && !activeMarkerPattern.test(h);
+    const isClosed = isClosedMilestoneHeading;
     const firstMatch = allMatches[0];
     const selected = allMatches.find((m) => !isClosed(m[1])) || firstMatch;
     const sectionStart = selected.index;
@@ -156,26 +209,36 @@ function extractCurrentMilestone(content, cwd) {
         const detailsStart = detailsMatch.index ?? 0;
         detailsSection = content.slice(detailsStart, computeSectionEnd(detailsMatch[0], detailsStart));
     }
+    // #2947: the preamble strip removes `### Phase N:` detail headings from the
+    // pre-milestone region so they don't duplicate the ones inside the selected
+    // milestone section. But when the phase list lives under a non-version-bearing
+    // `## Phases` heading (the shipped greenfield template's own shape) and the
+    // selected version-bearing heading is a LATER progress/notes sub-heading with
+    // NO phase details of its own, stripping the preamble phases silently drops
+    // every phase (phase_count: 0, exit 0). Only strip preamble phase details when
+    // the selected milestone section actually contains its own — otherwise the
+    // preamble phases ARE this milestone's phases and must be preserved.
+    const currentSectionHasPhaseDetails = /^#{2,4}\s*Phase\s+\S/im.test(currentSection);
     const preamble = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(beforeMilestones, 'details')
         // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+        .replace(currentSectionHasPhaseDetails ? /^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim : /$/, '')
         .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
     return detailsSection
         ? preamble + currentSection + '\n' + detailsSection
         : preamble + currentSection;
 }
-/**
- * Replace a pattern only in the current milestone section of ROADMAP.md.
- */
 function replaceInCurrentMilestone(content, pattern, replacement) {
+    const apply = (src) => typeof replacement === 'function'
+        ? src.replace(pattern, replacement)
+        : src.replace(pattern, replacement);
     const lastDetailsClose = content.lastIndexOf('</details>');
     if (lastDetailsClose === -1) {
-        return content.replace(pattern, replacement);
+        return apply(content);
     }
     const offset = lastDetailsClose + '</details>'.length;
     const before = content.slice(0, offset);
     const after = content.slice(offset);
-    return before + after.replace(pattern, replacement);
+    return before + apply(after);
 }
 /**
  * Resolve a single phase's detail-section heading (`### Phase N: …`, any level
@@ -452,16 +515,24 @@ function getMilestoneInfo(cwd) {
  *   free-form ROADMAPs that lack versioned milestone headings. When absent or
  *   any other value, the warning is suppressed — legacy/default projects must
  *   never see spurious warnings.
+ * @param ws - #2562: workstream name, so the ROADMAP/STATE pair is read from
+ *   `.planning/workstreams/<ws>/` instead of the project root. Required by any
+ *   caller that iterates workstreams (it cannot set `GSD_WORKSTREAM` per
+ *   iteration). Omitted (the default) preserves the prior `planningDir(cwd)`
+ *   resolution exactly, including its `GSD_WORKSTREAM` env fallback — every
+ *   pre-#2562 call site is unaffected.
  */
-function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
+function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
     const milestonePhaseNums = new Set();
     let missingExplicitVersion = false;
+    let versionScoped = false;
+    let versionSectionFound = false;
     try {
-        const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
+        const roadmapPath = node_path_1.default.join(planningDir(cwd, ws), 'ROADMAP.md');
         const roadmapContent = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
         if (roadmapContent === null)
             throw new Error('missing');
-        let roadmap = extractCurrentMilestone(roadmapContent, cwd);
+        let roadmap = extractCurrentMilestone(roadmapContent, cwd, ws);
         const hasVersionedMilestonesGlobal = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
         const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
         if (!hasVersionedMilestonesGlobal && hasPhaseHeadings && phaseIdConvention === 'milestone-prefixed') {
@@ -493,6 +564,8 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
                 }
             }
             else {
+                versionScoped = true;
+                versionSectionFound = true;
                 const sectionStart = sectionMatch.index;
                 const headingLevel = (sectionMatch[1].match(/^(#{1,3})\s/) ?? ['', '#'])[1].length;
                 const afterHeading = sectionStart + sectionMatch[0].length;
@@ -552,12 +625,20 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         const passAll = (() => true);
         passAll.phaseCount = 0;
         passAll.missingExplicitVersion = missingExplicitVersion;
+        passAll.versionScoped = false;
+        // #2562: preserved through the pass-all degrade precisely BECAUSE
+        // `versionScoped` is reset here — this is the only surviving evidence that
+        // the current milestone exists in the ROADMAP and simply has no phases yet.
+        passAll.versionSectionFound = versionSectionFound;
         return passAll;
     }
-    const normalized = new Set([...milestonePhaseNums].map(n => n.split('-').map(seg => (seg.replace(/^0+(?=\d)/, '') || '0')).join('-').toLowerCase()));
     function normalizePhaseIdSegments(id) {
         return id.split('-').map(seg => seg.replace(/^0+(?=\d)/, '') || '0').join('-');
     }
+    // #2562: derive BOTH sides of every membership comparison from
+    // normalizePhaseIdSegments. This set previously inlined a byte-identical
+    // second copy of that logic — the drift-prone shape this issue is about.
+    const normalized = new Set([...milestonePhaseNums].map(n => normalizePhaseIdSegments(n).toLowerCase()));
     const roadmapUsesHyphenedIds = [...normalized].some(n => n.includes('-'));
     // #2043: milestone-prefixed sub-phase components must be zero-padded — so a
     // single-digit slug word after the phase
@@ -587,6 +668,8 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
     }
     isDirInMilestone.phaseCount = milestonePhaseNums.size;
     isDirInMilestone.missingExplicitVersion = missingExplicitVersion;
+    isDirInMilestone.versionScoped = versionScoped;
+    isDirInMilestone.versionSectionFound = versionSectionFound;
     return isDirInMilestone;
 }
 /**
@@ -628,9 +711,7 @@ function currentMilestoneRawRanges(content, cwd) {
     const headingMatches = [...content.matchAll(sectionPattern)];
     if (headingMatches.length === 0)
         return null;
-    const closedMarkerPattern = /\b(?:CLOSED|ARCHIVED|ABANDONED|SHIPPED|FAILED)\b|✅|🗄/i;
-    const activeMarkerPattern = /\b(?:STARTED|ACTIVE|WIP)\b|in\s+progress|🚧|🔄/i;
-    const isClosed = (h) => closedMarkerPattern.test(h) && !activeMarkerPattern.test(h);
+    const isClosed = isClosedMilestoneHeading;
     const firstMatch = headingMatches[0];
     const selected = headingMatches.find((m) => !isClosed(m[1])) || firstMatch;
     const sectionStart = selected.index ?? 0;
@@ -671,6 +752,7 @@ function currentMilestoneRawRanges(content, cwd) {
 module.exports = {
     stripShippedMilestones,
     extractCurrentMilestone,
+    isMilestoneShippedInRoadmap,
     replaceInCurrentMilestone,
     getRoadmapPhaseInternal,
     getMilestoneInfo,

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

@@ -265,7 +265,11 @@ function cmdRoadmapAnalyze(cwd, raw) {
     // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
     // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
-    const phasePattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)(?:\s*\([^)\n]{0,200}\))?\s*:\s*([^\n]+)/gi;
+    // #3036: widen the id capture to accept non-numeric-leading ids (e.g. B7, P0.3-2)
+    // that get-phase/execute-phase already resolve. An optional leading letter prefix
+    // ([A-Za-z]?) covers letter-prefixed ids without breaking numeric-leading ones.
+    // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+([A-Za-z]?\d+[A-Z]?(?:[.-]\d+)*)(?:\s*\([^)\n]{0,200}\))?\s*:\s*([^\n]+)/gi;
     const phases = [];
     let match;
     // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not real
@@ -297,8 +301,9 @@ function cmdRoadmapAnalyze(cwd, raw) {
         const sectionStart = match.index;
         const restOfContent = content.slice(sectionStart);
         // #3691: `\d` → `\d[\d.]*` so decimal phase headings (e.g. `### Phase 02.3:`) are
-        // recognised as section boundaries.
-        const nextHeader = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]{1,200}\]\s*)?Phase\s+\d[\d.-]*/i);
+        // recognised as section boundaries. #3036: `[A-Za-z]?\d` so non-numeric-leading ids
+        // (e.g. B7) are also recognised.
+        const nextHeader = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]{1,200}\]\s*)?Phase\s+[A-Za-z]?\d[\d.-]*/i);
         const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length;
         const section = content.slice(sectionStart, sectionEnd);
         const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
@@ -389,7 +394,9 @@ function cmdRoadmapAnalyze(cwd, raw) {
     // IDs (e.g. `1-01`) match the detail-heading scanner above; otherwise they truncate
     // at the dash (`1-01` -> `1`) and every such phase reports a phantom missing detail.
     // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
-    const checklistPattern = /-\s*\[[ x]\]\s*\*\*Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)/gi;
+    // #3036: widen to accept non-numeric-leading ids (same widening as the detail-heading pattern above).
+    // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
+    const checklistPattern = /-\s*\[[ x]\]\s*\*\*Phase\s+([A-Za-z]?\d+[A-Z]?(?:[.-]\d+)*)/gi;
     const checklistPhases = new Set();
     let checklistMatch;
     while ((checklistMatch = checklistPattern.exec(content)) !== null) {
@@ -468,8 +475,13 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     // cmdPhaseComplete's gate (phase.cts:1436). Previously the checkbox fired the
     // moment the last plan summary landed — before gsd-verifier had verified.
     const phaseDir = node_path_1.default.join(cwd, phaseInfo.directory);
-    const verificationPassed = readVerificationStatus(phaseDir).status === 'passed';
+    const verificationResult = readVerificationStatus(phaseDir);
+    const verificationPassed = verificationResult.status === 'passed';
     const isComplete = summaryCount >= planCount && verificationPassed;
+    // #3057 B3: routing above is unchanged (an indeterminate staleness check
+    // still routes as if nothing were stale) — this only makes the fact visible
+    // to whatever reads this command's JSON output.
+    const verificationStaleCheckIndeterminate = verificationResult.staleCheckIndeterminate === true;
     const status = isComplete ? 'Complete' : summaryCount > 0 ? 'In Progress' : 'Planned';
     const today = clock_cjs_1.realClock.localToday();
     if (!node_fs_1.default.existsSync(roadmapPath)) {
@@ -526,11 +538,28 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         //   `**Plans**: N plans`  — bold word + outer colon (gsd-core/templates/roadmap.md)
         //   `**Plans:** N plans`  — bold "Plans:" (colon inside bold)
         //   `Plans: N plans`      — plain text header
-        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)[^\\n]+`, 'i');
+        //
+        // #2853: the verb owns the count token ONLY — it must not destroy hand-written
+        // prose a human placed after the count (e.g. "(11-16 are gap closure ...)").
+        // Group $1 = phase header → `Plans:` label + trailing whitespace (unchanged).
+        // Group $2 = the existing count token to replace: matches `N/N plans complete`,
+        // `N/N plans executed`, or the bare template `N plans` form. Group $3 = whatever
+        // else is on the line (`[^\r\n]*`, so CRLF `\r` is preserved).
+        //
+        // Trailing text is preserved ONLY when a real count token ($2) was present —
+        // i.e. an annotation a human wrote after a real count. When $2 is absent the
+        // line is the fresh-template bracketed placeholder (`[Number of plans…]`) or
+        // other freeform guidance, not user prose: the count replaces the whole token,
+        // preserving the pre-#2853 clean-output behaviour on the template path.
+        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)(\\d+\\s*\\/\\s*\\d+\\s+plans(?:\\s+(?:complete|executed))?|\\d+\\s+plans)?([^\\r\\n]*)`, 'i');
         const planCountText = isComplete
             ? `${summaryCount}/${planCount} plans complete`
             : `${summaryCount}/${planCount} plans executed`;
-        roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
+        roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, (_match, label, existingCount, trailing) => {
+            // Preserve trailing text only when a real count preceded it.
+            const suffix = existingCount ? trailing : '';
+            return `${label}${planCountText}${suffix}`;
+        });
         // If complete: check checkbox
         if (isComplete) {
             const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
@@ -628,6 +657,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         summary_count: summaryCount,
         status,
         complete: isComplete,
+        verification_stale_check_indeterminate: verificationStaleCheckIndeterminate,
     }, raw, `${summaryCount}/${planCount} ${status}`);
 }
 // ─── cmdRoadmapAnnotateDependencies ───────────────────────────────────────────