@opengsd/gsd-core 1.15.0 → 1.16.0

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

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestStatus = exports.ReportFormat = void 0;
+exports.parseTestReport = parseTestReport;
+/** Format adapters for RED evidence. Parsing never depends on the runner command. */
+const tap_parser_cjs_1 = require("./vendor/tap-parser.cjs");
+const saxes_cjs_1 = require("./vendor/saxes.cjs");
+exports.ReportFormat = {
+    Tap: 'tap', Junit: 'junit', SwiftTesting: 'swift-testing', Unittest: 'unittest', Unknown: 'unknown',
+};
+exports.TestStatus = { Passed: 'passed', Failed: 'failed', Skipped: 'skipped', Todo: 'todo' };
+function parseTap(output) {
+    const report = { format: exports.ReportFormat.Tap, valid: true, tests: [], issues: [] };
+    const parser = new tap_parser_cjs_1.Parser({ strict: true });
+    const assertions = [];
+    const openBuffered = new Map();
+    let completed = false;
+    const watch = (p) => {
+        p.on('child', (child) => {
+            if (child.buffered)
+                openBuffered.set(p, (openBuffered.get(p) ?? 0) + 1);
+            watch(child);
+        });
+        // tap-parser finalizes buffered children at EOF even without their closing
+        // brace. Track its child/line events so that truncation cannot prove RED.
+        p.on('line', (line) => {
+            if (line === '}\n')
+                openBuffered.set(p, (openBuffered.get(p) ?? 0) - 1);
+        });
+        p.on('assert', (result) => {
+            if (!result.closingTestPoint)
+                assertions.push({ result, owner: p });
+            if (result.buffered && !result.closingTestPoint)
+                report.issues.push('Missing buffered TAP subtest');
+            const diag = result.diag;
+            if (diag && ['cancelledByParent', 'hookFailed', 'testTimeoutFailure'].includes(String(diag['failureType']))) {
+                report.issues.push('Test run interrupted by cancellation, hook failure, or timeout');
+            }
+        });
+        p.on('extra', (extra) => { if (extra.trim())
+            report.issues.push('Non-TAP data in report'); });
+        p.on('complete', (summary) => {
+            if (p === parser)
+                completed = true;
+            const { start, end } = summary.plan;
+            if (start !== 1 || end === null || summary.count !== end)
+                report.issues.push('Missing or incomplete TAP plan');
+            if (summary.bailout)
+                report.issues.push('TAP bailout');
+            if (summary.failures.some((failure) => failure.tapError))
+                report.issues.push('Malformed TAP');
+        });
+    };
+    watch(parser);
+    parser.end(output);
+    if ([...openBuffered.values()].some((count) => count !== 0))
+        report.issues.push('Unclosed buffered TAP subtest');
+    for (const { result, owner } of assertions) {
+        let skipped = Boolean(result.skip);
+        let todo = Boolean(result.todo);
+        for (let parent = owner; parent; parent = parent.parent) {
+            skipped ||= Boolean(parent.closingTestPoint?.skip);
+            todo ||= Boolean(parent.closingTestPoint?.todo);
+        }
+        report.tests.push({
+            name: result.name,
+            identities: [...new Set([result.name, result.fullname])],
+            group: null,
+            groupIdentities: [],
+            status: skipped ? exports.TestStatus.Skipped : todo ? exports.TestStatus.Todo : result.ok ? exports.TestStatus.Passed : exports.TestStatus.Failed,
+        });
+    }
+    if (!completed)
+        report.issues.push('Incomplete TAP stream');
+    report.valid = report.issues.length === 0;
+    return report;
+}
+/** Surefire and Failsafe share the JUnit XML report shape. */
+function parseJunit(output) {
+    const report = { format: exports.ReportFormat.Junit, valid: true, tests: [], issues: [] };
+    const parser = new saxes_cjs_1.SaxesParser({ xmlns: false });
+    const elements = [];
+    const suites = [];
+    let current = null;
+    parser.on('error', () => { report.issues.push('Malformed XML'); });
+    parser.on('doctype', () => { report.issues.push('JUnit reports must not declare a DTD'); });
+    parser.on('opentag', (tag) => {
+        const parent = elements.at(-1);
+        if (!parent && tag.name !== 'testsuite' && tag.name !== 'testsuites')
+            report.issues.push('Not a JUnit report');
+        if (tag.name === 'testsuite' || tag.name === 'testsuites') {
+            if (parent && parent !== 'testsuite' && parent !== 'testsuites')
+                report.issues.push('Misplaced test suite');
+            const count = tag.attributes['tests'];
+            const planned = count === undefined ? null : Number(count);
+            if (count !== undefined && (!/^\d+$/.test(count) || !Number.isSafeInteger(planned)))
+                report.issues.push('Invalid JUnit test count');
+            suites.push({ firstTest: report.tests.length, planned });
+        }
+        else if (tag.name === 'testcase') {
+            if (parent !== 'testsuite' || current)
+                report.issues.push('Misplaced test case');
+            const name = tag.attributes['name'] ?? '';
+            const className = tag.attributes['classname'] ?? '';
+            const qualified = className ? `${className}#${name}` : name;
+            if (!name)
+                report.issues.push('Unnamed test case');
+            current = {
+                name: qualified,
+                identities: [...new Set([name, qualified])],
+                group: className || null,
+                groupIdentities: className ? [className, className.split('.').at(-1)] : [],
+                status: exports.TestStatus.Passed,
+            };
+        }
+        else if (current && parent === 'testcase') {
+            if (tag.name === 'failure' || tag.name === 'error') {
+                if (current.status === exports.TestStatus.Skipped)
+                    report.issues.push('Contradictory JUnit status');
+                current.status = exports.TestStatus.Failed;
+            }
+            if (tag.name === 'skipped') {
+                if (current.status === exports.TestStatus.Failed)
+                    report.issues.push('Contradictory JUnit status');
+                current.status = exports.TestStatus.Skipped;
+            }
+        }
+        elements.push(tag.name);
+    });
+    parser.on('closetag', (tag) => {
+        if (tag.name === 'testcase' && current) {
+            report.tests.push(current);
+            current = null;
+        }
+        else if (tag.name === 'testsuite' || tag.name === 'testsuites') {
+            const suite = suites.pop();
+            if (!suite || (suite.planned !== null && suite.planned !== report.tests.length - suite.firstTest)) {
+                report.issues.push('Incomplete JUnit test suite');
+            }
+        }
+        elements.pop();
+    });
+    parser.write(output).close();
+    report.valid = report.issues.length === 0;
+    return report;
+}
+/**
+ * swift-testing console output (#4957). Only the anchored aggregate line marks
+ * the format; every declared test must have its own result line. The aggregate
+ * counts skipped tests too, and a parameterized test names its case count.
+ * A test is named by its quoted display name (with `(aka 'function()')` under
+ * --verbose) or, without one, by its bare function name. Windows consoles
+ * print √ × - in place of ✔ ✘ ━. swift-testing 6.1 omits the suite count from
+ * the aggregate and marks skipped tests with ✘ (later sources add the count
+ * and use ➜).
+ */
+const SWIFT_AGGREGATE = /^[ \t]*[✘✔━×√-][ \t]*Test run with (\d+) tests?(?: in \d+ suites?)? (passed|failed)\b/gm;
+const SWIFT_RESULT = /^[ \t]*[✘✔━➜×√-][ \t]*Test (?:"([^"]+)"(?: \(aka '([^']+)'\))?|([^\s"]\S*\)))(?: with \d+ test cases?)? (?:(failed|passed|was cancelled) after [\d.]+ seconds?(?: with \d+ [^\n]*?)?(?:\.|: "[^\n]*")|(skipped)(?:\.|: "[^\n]*"))$/gm;
+function parseSwiftTesting(output) {
+    const report = { format: exports.ReportFormat.SwiftTesting, valid: true, tests: [], issues: [] };
+    let declared = 0;
+    let runPassed = true;
+    for (const match of output.matchAll(SWIFT_AGGREGATE)) {
+        declared += Number(match[1]);
+        runPassed &&= match[2] === 'passed';
+    }
+    for (const match of output.matchAll(SWIFT_RESULT)) {
+        const fn = match[2] ?? match[3];
+        report.tests.push({
+            name: match[1] ?? match[3],
+            identities: [...new Set([match[1], fn, fn?.replace(/\(.*\)$/, '')].filter((id) => Boolean(id)))],
+            group: null,
+            groupIdentities: [],
+            status: match[4] === 'failed' ? exports.TestStatus.Failed : match[4] === 'passed' ? exports.TestStatus.Passed : exports.TestStatus.Skipped,
+        });
+    }
+    if (report.tests.length !== declared)
+        report.issues.push('Incomplete swift-testing report');
+    if (runPassed && report.tests.some((test) => test.status === exports.TestStatus.Failed)) {
+        report.issues.push('Contradictory swift-testing status');
+    }
+    report.valid = report.issues.length === 0;
+    return report;
+}
+/**
+ * Python stdlib unittest text output (#4970). Passing tests are unnamed unless
+ * verbose, so they are counted from the summary; failures are named by their
+ * FAIL:/ERROR: headers, which must account for every counted failure. Each
+ * failing subTest repeats its method's header and counts as a failure, while
+ * Ran counts methods, so identical headers collapse into one failed test. An
+ * unexpected success fails the run but is a test that passed.
+ */
+const UNITTEST_RAN = /^Ran (\d+) tests? in [\d.]+s$/gm;
+const UNITTEST_HEADER = /^(?:FAIL|ERROR): (\S+)(?: \(([^)]*)\))?/gm;
+function parseUnittest(output) {
+    const report = { format: exports.ReportFormat.Unittest, valid: true, tests: [], issues: [] };
+    const runs = [...output.matchAll(UNITTEST_RAN)];
+    if (runs.length !== 1) {
+        report.issues.push('Expected exactly one unittest summary');
+        report.valid = false;
+        return report;
+    }
+    const ran = Number(runs[0][1]);
+    const outcome = /^(OK|FAILED)(?: \(([^)]*)\))?$/m.exec(output.slice(runs[0].index + runs[0][0].length));
+    const counts = {};
+    for (const part of outcome?.[2]?.split(', ') ?? []) {
+        const [key, value] = part.split('=');
+        counts[key] = Number(value);
+    }
+    if (!outcome || Object.keys(counts).some((key) => !['failures', 'errors', 'skipped', 'expected failures', 'unexpected successes'].includes(key))) {
+        report.issues.push('Unsupported unittest outcome');
+    }
+    let headers = 0;
+    const failedIds = new Set();
+    for (const match of output.matchAll(UNITTEST_HEADER)) {
+        headers++;
+        const id = match[2] ?? '';
+        const key = `${match[1]} ${id}`;
+        if (failedIds.has(key))
+            continue;
+        failedIds.add(key);
+        // unittest synthesizes _FailedTest for an import/collection crash; its
+        // method name can equal the target, so it is a load failure, never RED.
+        if (id.includes('_FailedTest')) {
+            report.issues.push('unittest module failed to load');
+            continue;
+        }
+        report.tests.push({
+            name: match[1],
+            identities: [...new Set([match[1], id].filter(Boolean))],
+            group: null,
+            groupIdentities: [],
+            status: exports.TestStatus.Failed,
+        });
+    }
+    const failed = (counts['failures'] ?? 0) + (counts['errors'] ?? 0);
+    const skipped = counts['skipped'] ?? 0;
+    const runFailed = failed > 0 || (counts['unexpected successes'] ?? 0) > 0;
+    if (headers !== failed || (outcome?.[1] === 'FAILED') !== runFailed || failedIds.size + skipped > ran) {
+        report.issues.push('Incomplete unittest report');
+    }
+    const unnamed = (status) => ({ name: '', identities: [], group: null, groupIdentities: [], status });
+    for (let i = 0; i < skipped; i++)
+        report.tests.push(unnamed(exports.TestStatus.Skipped));
+    for (let i = Math.max(ran - failedIds.size - skipped, 0); i > 0; i--)
+        report.tests.push(unnamed(exports.TestStatus.Passed));
+    report.valid = report.issues.length === 0;
+    return report;
+}
+const adapters = [
+    { matches: (output) => /^(?:TAP version \d+|(?:not )?ok\b|1\.\.\d+|#)/.test(output.trimStart()), parse: parseTap },
+    { matches: (output) => output.trimStart().startsWith('<'), parse: parseJunit },
+    { matches: (output) => new RegExp(SWIFT_AGGREGATE.source, 'm').test(output), parse: parseSwiftTesting },
+    { matches: (output) => new RegExp(UNITTEST_RAN.source, 'm').test(output), parse: parseUnittest },
+];
+/** Parse supported reports into one result contract; unknown/malformed input fails closed. */
+function parseTestReport(output) {
+    const adapter = adapters.find((candidate) => candidate.matches(output));
+    if (!adapter)
+        return { format: exports.ReportFormat.Unknown, valid: false, tests: [], issues: ['Unsupported report format'] };
+    try {
+        const report = adapter.parse(output);
+        // One entry per problem: a long run of bad lines must not amplify the payload.
+        return { ...report, issues: [...new Set(report.issues)] };
+    }
+    catch {
+        return { format: exports.ReportFormat.Unknown, valid: false, tests: [], issues: ['Malformed report'] };
+    }
+}

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

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const command_aliases_cjs_1 = require("./command-aliases.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
 const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
@@ -145,14 +146,13 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                 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)' });
-                    }
+                // Malformed frontmatter — a `---` opener with no matching closer, as the one fence
+                // owner reads it (a leading BOM, #3057, is tolerated there).
+                const roadmapFence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(roadmapContent);
+                // The milestone-window read below sees the document without its leading BOM (#3057).
+                const contentAfterBom = roadmapContent.charCodeAt(0) === 0xFEFF ? roadmapContent.slice(1) : roadmapContent;
+                if (roadmapFence && !roadmapFence.closed) {
+                    warnings.push({ code: 'V003', message: 'ROADMAP.md frontmatter is malformed (unterminated --- fence)' });
                 }
                 // #3641: resolve phase_id_convention ONCE, ahead of every consumer in
                 // this validate pass — V004's entry check and V005's scope classifier
@@ -169,13 +169,11 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                     convention = undefined;
                 }
                 if (convention === undefined || convention === null) {
-                    // Fallback: read from ROADMAP.md frontmatter. Bounded to match
-                    // cmdRoadmapMilestoneScope's copy exactly (#3641 review NEW-1: an
-                    // unbounded capture here read past 4KB frontmatters the probe's
-                    // bounded copy could not, diverging validate from the probe).
-                    const fmMatch = roadmapContent.match(/^---\r?\n([\s\S]{0,4000}?)\r?\n---/);
-                    if (fmMatch) {
-                        const kvMatch = fmMatch[1].match(/^phase_id_convention:\s*(.*)$/m);
+                    // Fallback: read from ROADMAP.md frontmatter — the block the one fence owner finds,
+                    // exactly as cmdRoadmapMilestoneScope reads it (#3641 review NEW-1: two copies of
+                    // this read disagreed on long frontmatter, diverging validate from the probe).
+                    if (roadmapFence?.closed) {
+                        const kvMatch = roadmapContent.slice(roadmapFence.openEnd, roadmapFence.bodyEnd).match(/^phase_id_convention:\s*(.*)$/m);
                         if (kvMatch) {
                             const val = kvMatch[1].trim();
                             if (val !== 'null' && val !== '') {

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

@@ -926,6 +926,44 @@ function classifyMilestoneWindow(input) {
                         SCOPE.COMPLETE // rows 6, 7
     );
 }
+// #5007 (Phase 6 / ADR-4910 §8): the bulk phase-heading-block strip (heading
+// line + body through to the next heading of any level) used by BOTH the
+// <details>-fallback branch and preambleWithoutPhaseDetails inside
+// extractCurrentMilestoneScoped below — literally the same regex, previously
+// duplicated verbatim at both call sites. Composed from
+// phaseHeadingPrefixSrcFor (LABEL_ONLY, no convention argument — reproduces
+// the prior bare `Phase\s+` literal byte-for-byte, same non-widening
+// discipline as the phase.cts counter sites) rather than routed through
+// buildPhaseHeadingScanRegex, since this site needs the whole matched block
+// (heading + body), not a phase-number/title capture. The one real behavior
+// change here is the phase-number token itself: the prior literal admitted
+// any `[\w][\w.-]*` (including non-numeric garbage); PHASE_NUMBER_TOKEN_SOURCE
+// tightens it to the real phase-number grammar (digits, optional trailing
+// letter, dotted subphases) — verified against real phase-number fixtures
+// (plain, decimal, and bracket-tag-bearing) in tests/roadmap-parser.test.cjs.
+const PHASE_HEADING_BLOCK_STRIP_RE = new RegExp(
+// #1729: `(?:\s*\([^)\n]{0,200}\))?` (OPTIONAL_PHASE_TAG_SOURCE) tolerates a pre-colon ( ) tag.
+`^#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY)}${PHASE_NUMBER_TOKEN_SOURCE}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:[^\\n]*(?:\\n(?!#{1,6}\\s)[^\\n]*)*\\n?`, 'gim');
+/**
+ * #5038: single owner for classifying a `milestone:` scalar as STATE.md spells
+ * it. The frontmatter parser (FAILSAFE_SCHEMA) and the raw-regex readers both
+ * see YAML null as text, so every reader classifies it here. Recognizes the
+ * YAML 1.2 core-schema null spellings (`null`, `Null`, `NULL`, `~`) with an
+ * optional trailing ` # comment` and optional surrounding quotes (the
+ * frontmatter parser has already stripped them, so the raw readers must agree);
+ * a blank value is absent, not null.
+ */
+function classifyMilestoneScalar(raw) {
+    if (typeof raw !== 'string')
+        return { explicitNull: false, version: null };
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return { explicitNull: false, version: null };
+    const bare = trimmed.replace(/\s+#.*$/, '').trim().replace(/^(['"])(.*)\1$/, '$2');
+    if (/^(?:null|Null|NULL|~)$/.test(bare))
+        return { explicitNull: true, version: null };
+    return { explicitNull: false, version: trimmed };
+}
 /**
  * Extract the current milestone section from ROADMAP.md by positive lookup,
  * carrying a `scope` discriminator (ADR-3180 Decision 2) alongside the value.
@@ -960,18 +998,23 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
         return { value: stripShippedMilestones(content), scope: SCOPE.COMPLETE };
     }
     let version = null;
+    let stateAssertsNoMilestone = false;
     try {
         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);
             if (milestoneMatch) {
-                version = milestoneMatch[1].trim();
+                const classified = classifyMilestoneScalar(milestoneMatch[1]);
+                version = classified.version;
+                stateAssertsNoMilestone = classified.explicitNull;
             }
         }
     }
     catch { /* ignore */ }
-    if (!version) {
+    // #5038: an explicit `milestone: null` is a deliberate "no milestone" — do
+    // not let the in-progress bullet guess one (same stance as getMilestoneInfo).
+    if (!version && !stateAssertsNoMilestone) {
         const inProgressMatch = content.match(/(?:🚧|🔄)\s*\*\*v(\d+\.\d+)\s/);
         if (inProgressMatch) {
             version = 'v' + inProgressMatch[1];
@@ -1050,9 +1093,9 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
                 const firstMilestoneMatch = content.match(anyMilestoneOrDetails);
                 const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : detailsOpenIdx;
                 const preamble = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(content.slice(0, preambleCutoff), 'details')
-                    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-                    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
-                    .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+                    // #5007 (Phase 6 / ADR-4910 §8): shared owner, see
+                    // PHASE_HEADING_BLOCK_STRIP_RE above.
+                    .replace(PHASE_HEADING_BLOCK_STRIP_RE, '')
                     .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
                 const value = preamble + content.slice(detailsOpenIdx, detailsEnd);
                 return {
@@ -1287,17 +1330,23 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
     // 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.
-    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
-    const currentSectionHasPhaseDetails = /^#{2,4}\s*Phase\s+\S/im.test(currentSection);
+    // #5007 (Phase 6 / ADR-4910 §8): a pure "does this section have ANY phase
+    // heading" boolean — same shape as phase.cts:1691's anyHeadingPattern
+    // (composed directly from phaseHeadingPrefixSrcFor, no shared owner exposes
+    // a captureless existence check), but this site's terminal token is `\S`
+    // (any non-whitespace), not phase.cts:1691's `\d` — kept as `\S` to
+    // reproduce this site's own prior behavior byte-for-byte rather than
+    // forcing the two sites onto an identical terminal token that would be a
+    // behavior change here.
+    const currentSectionHasPhaseDetails = new RegExp(`^#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY)}\\S`, 'im').test(currentSection);
     const preambleBase = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(beforeMilestones, 'details');
     // #3235: the conditional wraps the REPLACE, not the pattern. This used to select between the
     // strip regex and a `/$/` sentinel, which made the do-not-strip branch an identity replacement
     // (CodeQL js/identity-replacement, alert 53) -- correct, but it left both branches sharing one
     // replacement argument, so changing `''` would silently give the no-op branch a real effect.
-    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    // #5007 (Phase 6 / ADR-4910 §8): shared owner, see PHASE_HEADING_BLOCK_STRIP_RE above.
     const preambleWithoutPhaseDetails = currentSectionHasPhaseDetails
-        // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
-        ? preambleBase.replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+        ? preambleBase.replace(PHASE_HEADING_BLOCK_STRIP_RE, '')
         : preambleBase;
     // Unconditional in BOTH branches -- the #730 `Phase Details` heading strip is independent of
     // whether the selected milestone section carries phase details of its own.
@@ -1707,14 +1756,22 @@ function getMilestoneInfo(cwd) {
         if (roadmap === null)
             throw new Error('missing');
         let stateVersion = null;
+        // #5038: true only when the `milestone:` key is PRESENT and classifies as
+        // an explicit null (any spelling classifyMilestoneScalar accepts), as
+        // opposed to ABSENT. Gates the ROADMAP auto-derivation fallback, which
+        // only bootstraps a milestone for a project that never mentioned one.
+        let explicitlyNoMilestone = false;
         if (cwd) {
             try {
                 const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
                 const stateRaw = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
                 if (stateRaw !== null) {
                     const m = stateRaw.match(/^milestone:\s*(.+)/m);
-                    if (m)
-                        stateVersion = m[1].trim();
+                    if (m) {
+                        const classified = classifyMilestoneScalar(m[1]);
+                        explicitlyNoMilestone = classified.explicitNull;
+                        stateVersion = classified.version;
+                    }
                 }
             }
             catch {
@@ -1771,6 +1828,11 @@ function getMilestoneInfo(cwd) {
             // or heading-but-nameless). §7.2 rule 4 — never fabricate a name.
             return scoped({ version: stateVersion, name: null }, SCOPE.TRUNCATED);
         }
+        // #5038: an explicit null is a deliberate "no milestone"; do not let the
+        // auto-derivation fallback below replace it with a guessed version.
+        if (explicitlyNoMilestone) {
+            return scoped(null, SCOPE.UNSCOPED);
+        }
         // No STATE.md version. The 🚧 in-progress bullet is still consulted first
         // (unchanged from the pre-#3216 fallback).
         const inProgressMatch = roadmap.match(/🚧\s*\*\*v(\d+(?:\.\d+)+)\s+([^*]+)\*\*/);
@@ -2104,17 +2166,21 @@ function currentMilestoneRawRanges(content, cwd) {
     if (!cwd)
         return null;
     let version = null;
+    let stateAssertsNoMilestone = false;
     try {
         const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
         const stateRaw = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
         if (stateRaw !== null) {
             const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
-            if (milestoneMatch)
-                version = milestoneMatch[1].trim();
+            if (milestoneMatch) {
+                const classified = classifyMilestoneScalar(milestoneMatch[1]);
+                version = classified.version;
+                stateAssertsNoMilestone = classified.explicitNull;
+            }
         }
     }
     catch { /* ignore */ }
-    if (!version) {
+    if (!version && !stateAssertsNoMilestone) {
         const inProgressMatch = content.match(/(?:🚧|🔄)\s*\*\*v(\d+\.\d+)\s/);
         if (inProgressMatch)
             version = 'v' + inProgressMatch[1];
@@ -2217,6 +2283,7 @@ module.exports = {
     replaceInCurrentMilestone,
     getRoadmapPhaseInternal,
     getMilestoneInfo,
+    classifyMilestoneScalar,
     getMilestonePhaseFilter,
     currentMilestoneRawRanges,
     withPhaseSection,