@opengsd/gsd-core 1.7.0 → 1.9.0

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

@@ -56,6 +56,11 @@ const uatPredicate = require("./uat-predicate.cjs");
 const { evaluateUatPassed } = uatPredicate;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
+// #2572: the artifact↔disk core behind the `verify-summary` verb. `verify.cts`
+// has no transitive import path back to `phase.cts`, so this edge introduces no
+// cycle (the reverse edge, `state.cts → verify.cjs`, would).
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- verify.cjs is an export= CommonJS module
+const verifyMod = require("./verify.cjs");
 const { readVerificationStatus } = verificationMod;
 const { planningDir, withPlanningLock, listAvailableWorkstreams, getActiveWorkstream } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
@@ -106,6 +111,19 @@ function updateTraceabilityCell(text, match, column, newValue) {
         return result;
     return { ok: true, value: before + result.value + after };
 }
+/**
+ * Extract the MAJOR version segment from a version-ish string: "v1", "v1.3",
+ * "V1.0", and "1.0" all yield "1"; "v2" yields "2". Used (#2334 BLOCKER fix)
+ * to compare a `## v<N> ...` REQUIREMENTS.md heading against the current
+ * milestone's version at MAJOR-version granularity only — "v1" heading vs
+ * milestone "v1.3" is the SAME major version and must not be treated as a
+ * version mismatch. Returns null when `raw` has no leading digit run (not a
+ * version-shaped string), which the caller treats as "cannot resolve".
+ */
+function extractMajorVersion(raw) {
+    const m = raw.trim().match(/^v?(\d+)/i);
+    return m ? m[1] : null;
+}
 function describeNonCanonicalPlans(dirFiles, matchedFiles) {
     const matched = new Set(matchedFiles);
     const offenders = dirFiles.filter((f) => looksLikePlanFile(f) && !matched.has(f));
@@ -127,8 +145,13 @@ function extractCanonicalPlanId(filename) {
     // or a single-digit-plus-letter id ("3A"); a *bare* single digit is a slug word,
     // so "46-6-rs-…" is not paired into a "46-6" id while "3A-01" stays intact.
     const tokenRe = /^(?:\d{2,}[A-Z]?|\d[A-Z])(?:\.\d+)*$/i;
+    // #2232: the PAIRED plan component is a zero-padded continuation segment
+    // (exactly 2 digits), so a ≥3-digit slug word (a year) is not paired into a
+    // bogus "14-2026" id. The leading phase component keeps tokenRe's unbounded
+    // \d{2,} — phase numbers ≥100 are legitimate; only continuations are capped.
+    const planTokenRe = new RegExp(`^(?:${phaseIdMod.PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?|\\d[A-Z])(?:\\.\\d+)*$`, 'i');
     const phaseIdx = parts.findIndex((p) => tokenRe.test(p));
-    if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && tokenRe.test(parts[phaseIdx + 1])) {
+    if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && planTokenRe.test(parts[phaseIdx + 1])) {
         return `${parts[phaseIdx]}-${parts[phaseIdx + 1]}`;
     }
     return base;
@@ -494,7 +517,8 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         const planId = planFile.replace('-PLAN.md', '').replace('PLAN.md', '');
         const planPath = node_path_1.default.join(phaseDir, planFile);
         const content = node_fs_1.default.readFileSync(planPath, 'utf-8');
-        const fm = extractFrontmatter(content);
+        // Pass planPath so a truncated PLAN.md names the file in the #1882 diagnostic.
+        const fm = extractFrontmatter(content, planPath);
         const xmlTasks = content.match(/<task[\s>]/gi) || [];
         const mdTasks = content.match(/##\s*Task\s*\d+/gi) || [];
         const taskCount = xmlTasks.length || mdTasks.length;
@@ -603,6 +627,29 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         result['warnings'] = warnings;
     output(result, raw);
 }
+// #2390 — phase.add title-shape heuristic. A description at or under this many
+// characters, and with no sentence-ending punctuation followed by more text,
+// reads as a short Title. Anything longer or multi-sentence reads as a Goal,
+// not a Title. phase.add still writes the phase verbatim (it never mangles
+// ROADMAP.md), but when the description looks goal-shaped the JSON result
+// gains a `warning` key naming the gap, so the caller — or the orchestrating
+// add-phase workflow — can split title vs. goal instead of the whole paragraph
+// landing silently in the `### Phase N:` header.
+const PHASE_ADD_TITLE_MAX_LEN = 80;
+const PHASE_ADD_MULTI_SENTENCE_RE = /[.!?]['")\]]?\s+\S/;
+function describeGoalShapedTitle(description) {
+    const trimmed = description.trim();
+    const tooLong = trimmed.length > PHASE_ADD_TITLE_MAX_LEN;
+    const multiSentence = PHASE_ADD_MULTI_SENTENCE_RE.test(trimmed);
+    if (!tooLong && !multiSentence)
+        return null;
+    const reasons = [
+        tooLong ? `${trimmed.length} chars (over the ${PHASE_ADD_TITLE_MAX_LEN}-char title threshold)` : null,
+        multiSentence ? 'multiple sentences' : null,
+    ].filter(Boolean).join(', ');
+    return (`description looks goal-shaped, not title-shaped (${reasons}). It was written verbatim ` +
+        `as the phase title; consider a short title with the detail moved to **Goal:**.`);
+}
 function cmdPhaseAdd(cwd, description, raw, customId) {
     if (!description) {
         error('description required for phase add');
@@ -690,6 +737,7 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent);
         return { newPhaseId: _newPhaseId, dirName: _dirName };
     });
+    const titleWarning = describeGoalShapedTitle(description);
     const result = {
         phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
         padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId),
@@ -698,7 +746,9 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         directory: toPosixPath(node_path_1.default.join(node_path_1.default.relative(cwd, planningDir(cwd)), 'phases', dirName)),
         naming_mode: config.phase_naming,
     };
-    output(result, raw, result.padded);
+    if (titleWarning)
+        result['warning'] = titleWarning;
+    output(result, raw, result['padded']);
 }
 function cmdPhaseAddBatch(cwd, descriptions, raw) {
     if (!Array.isArray(descriptions) || descriptions.length === 0) {
@@ -1358,13 +1408,14 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 warnings.push(`${file}: has diagnosed gaps`);
         }
         for (const file of phaseFiles.filter((f) => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
+            const verificationFilePath = node_path_1.default.join(phaseFullDir, file);
+            const content = node_fs_1.default.readFileSync(verificationFilePath, 'utf-8');
             // #1159 (Defect A): read ONLY the frontmatter `status` key to avoid false positives
             // from historical metadata in the file body (e.g. `previous_status: gaps_found`).
             // A full-text regex like /status: gaps_found/ matches the substring inside
             // `previous_status: gaps_found`, producing spurious warnings even when the
             // current frontmatter status is `passed`.
-            const verFm = extractFrontmatter(content);
+            const verFm = extractFrontmatter(content, verificationFilePath);
             // Normalise to lower-case so `status: Passed` (title-case) is not missed.
             const verStatus = typeof verFm['status'] === 'string' ? verFm['status'].trim().toLowerCase() : '';
             if (verStatus === 'human_needed')
@@ -1380,11 +1431,51 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
          * mechanism). A readdirSync/readFileSync failure here just means fewer
          * warnings are surfaced this run, not a blocked or corrupted completion. */
     }
+    // #2572: artifact↔disk advisory for the SUMMARYs of the phase being completed.
+    //
+    // A SUMMARY asserts "I created these files". Nothing checked that claim for
+    // phase summaries — the `verify-summary` verb has existed since the beginning
+    // but was only ever pointed at `.planning/research/SUMMARY.md`. An interrupted
+    // or over-reported phase therefore counted toward 100% silently.
+    //
+    // Joins the same ADVISORY channel as the pre-scan above: findings land in
+    // `warnings[]` (rendered by execute-phase.md's "If has_warnings is true"
+    // step), never in the completion GATE (readVerificationStatus below).
+    // Completion is never blocked.
+    //
+    // `checkCommits: false` — only the file-existence half is surfaced here, so
+    // the `git cat-file` probes would be spawned and their result discarded. The
+    // hash pattern is a loose `\b[0-9a-f]{7,40}\b` that matches any hex-shaped
+    // token in prose, too noisy to put in front of a user even as a warning.
+    //
+    // `Infinity` — report every referenced file, not the CLI verb's default first
+    // two, so a phase that lists twelve files and landed three says so. The verb
+    // keeps its 2-file default; only this caller opts out of the cap.
+    try {
+        const phaseDirRel = phaseInfo['directory'];
+        // `summaries` arrives pre-sorted from the phase locator, so warning order is
+        // deterministic across platforms rather than readdir-dependent.
+        const summaryNames = phaseInfo['summaries'] || [];
+        for (const summaryName of summaryNames) {
+            const v = verifyMod.verifySummaryCore(cwd, `${phaseDirRel}/${summaryName}`, Infinity, { checkCommits: false });
+            const missing = v.checks.files_created.missing;
+            if (missing.length > 0) {
+                warnings.push(`${summaryName}: references ${missing.length} file(s) not on disk: ${missing.join(', ')}`);
+            }
+        }
+    }
+    catch {
+        /* best-effort, same posture as the #2245 pre-scan above: an unreadable
+         * SUMMARY means one fewer advisory this run, never a blocked completion. */
+    }
     let nextPhaseNum = null;
     let nextPhaseName = null;
     let isLastPhase = true;
     const verificationBlocked = withPlanningLock(cwd, () => {
-        const verificationStatus = readVerificationStatus(phaseFullDir);
+        // #2617: pass the project's runtime so the blocked-completion error below
+        // suggests the command surface this runtime actually installs
+        // ($gsd-… on Codex) rather than a hard-coded Claude-style string.
+        const verificationStatus = readVerificationStatus(phaseFullDir, { runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd) });
         if (verificationStatus.status !== 'passed') {
             return verificationStatus;
         }
@@ -1553,13 +1644,43 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     const reqMatch = sectionText.match(/\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]+)/i);
                     const originalReqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
                     let reqContent = originalReqContent;
+                    // #2316: `citedReqIds` — the REQ-IDs ROADMAP's own **Requirements:**
+                    // line for this phase actually cites — is hoisted out of the
+                    // `if (reqMatch)` block (previously scoped only inside it) so the
+                    // ghost-ID cross-check below (~#2316-1) can consult it. `TBD` is the
+                    // literal placeholder `phase.add`/`-batch`/`-insert` seed
+                    // (`**Requirements**: TBD`, src/phase.cts:833,920,1078) — never a
+                    // real REQ-ID, so it is filtered out wherever a cited-ID list feeds
+                    // a warning (#2316-7 boundary).
+                    const isPlaceholderReqId = (id) => id.toUpperCase() === 'TBD';
+                    let citedReqIds = [];
+                    // #2316-1: Traceability-row writes that matched NO row (ghost or
+                    // otherwise) — the `if (reqUpdate.ok)` below previously had no
+                    // `else`, discarding this fact silently instead of surfacing it.
+                    const traceabilityWriteMisses = [];
                     if (reqMatch) {
-                        const reqIds = reqMatch[1]
+                        // #2334 HIGH 3: filter the tokenized capture to the REQ-ID SHAPE —
+                        // the SAME shape bodyReqIds (`\*\*([A-Z][A-Z0-9]*-\d+)\*\*`, below)
+                        // and tableReqIds (`([A-Z][A-Z0-9]*-\d+)`, below) already require —
+                        // so the ghost-ID / unregistered comparisons stay shape-symmetric.
+                        // Without this, `[^\n]+` split on `[,\s]+` turned EVERY word after
+                        // the ID list into a "cited REQ-ID": the shipped
+                        // `templates/roadmap.md:32` line
+                        // `**Requirements**: [REQ-01, REQ-02]  <!-- brackets optional, ... -->`
+                        // warned to register `<!--`, `brackets`, `optional`, `-->`, etc., and
+                        // `**Requirements:** None` warned to register the literal word
+                        // `None`. This subsumes the `TBD` placeholder special-case (`TBD`
+                        // does not match the REQ-ID shape either); `isPlaceholderReqId` is
+                        // kept below as a defensive no-op for any caller that still hands
+                        // it a raw token.
+                        const REQ_ID_SHAPE_RE = /^[A-Z][A-Z0-9]*-\d+$/i;
+                        citedReqIds = reqMatch[1]
                             .replace(/[\[\]]/g, '')
                             .split(/[,\s]+/)
                             .map((r) => r.trim())
-                            .filter(Boolean);
-                        for (const reqId of reqIds) {
+                            .filter(Boolean)
+                            .filter((r) => REQ_ID_SHAPE_RE.test(r));
+                        for (const reqId of citedReqIds) {
                             const reqEscaped = escapeRegex(reqId);
                             reqContent = reqContent.replace(new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'), '$1x$2');
                             // Traceability row: | <REQ-ID> | Phase N | Pending|In Progress | ->
@@ -1578,14 +1699,19 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             // Complete" gate is folded into the newValue callback so one
                             // updateTableCell call both probes and writes.
                             const reqUpdate = updateTraceabilityCell(reqContent, reqRowMatch, 'Status', (current) => /^(?:pending|in progress)$/i.test(current.trim()) ? ' Complete ' : current);
-                            if (reqUpdate.ok)
+                            if (reqUpdate.ok) {
                                 reqContent = reqUpdate.value;
+                            }
+                            else if (!isPlaceholderReqId(reqId)) {
+                                traceabilityWriteMisses.push(reqId);
+                            }
                         }
                     }
                     // #1159 (Defect B): collect requirement IDs only from ACTIVE sections.
                     // Requirements under headings whose text contains "deferred", "backlog",
-                    // "future", or "v2" (case-insensitive) are explicitly out of current scope
-                    // and must not be flagged as missing from the Traceability table.
+                    // "future", or an OFF-milestone `v<N>` (case-insensitive) are explicitly
+                    // out of current scope and must not be flagged as missing from the
+                    // Traceability table.
                     //
                     // Strategy: walk lines, track heading depth, and toggle a "deferred" flag
                     // when a heading matching the pattern is encountered.  A sub-heading (higher
@@ -1593,7 +1719,47 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // opens a same-or-shallower heading that does NOT match the pattern.
                     // Lines inside fenced code blocks (``` or ~~~) are treated as content, not
                     // headings, to avoid false deferred-section detection from code examples.
-                    const DEFERRED_HEADING_RE = /\b(?:deferred|backlog|future|v\d+)\b/i;
+                    //
+                    // #2334 BLOCKER fix (regresses closed bug #1159 against GSD's OWN
+                    // shipped template): #2316-4a dropped the bare `v\d+` alternative
+                    // entirely to stop it over-matching an ACTIVE heading like "## v1
+                    // Requirements" — but the shipped `templates/requirements.md:35`
+                    // scaffold ships `## v2 Requirements` / "Deferred to future release"
+                    // as its ONLY deferred marker, and `v\d+` was the ONLY alternative
+                    // that ever matched a bare version heading (the deferred-ness lives
+                    // in body prose, not the heading text). Dropping it regressed #1159
+                    // for every project scaffolded from the shipped template.
+                    //
+                    // Fix: make the `v<N>` alternative MILESTONE-AWARE instead of
+                    // deleting it. A `## v<N> ...` heading is deferred ONLY when `<N>`
+                    // (MAJOR version only — "v1" vs milestone "v1.3" is the SAME major
+                    // version) does not match the CURRENT milestone's major version,
+                    // resolved via `stateExtractField` against STATE.md's `milestone:`
+                    // frontmatter field (the same seam `getMilestoneInfo`/state.cts's
+                    // frontmatter builder already use — no bespoke frontmatter parsing).
+                    // "## v1 Requirements" while the milestone is v1.x is the ACTIVE
+                    // milestone's own section (#2316's original ask) and must NOT be
+                    // swallowed; "## v2 Requirements" while the milestone is v1.x is a
+                    // genuinely future milestone (#1159's ask, and the literal shipped-
+                    // template shape) and MUST stay suppressed. `deferred`/`backlog`/
+                    // `future` are unaffected by milestone resolution — a genuinely
+                    // deferred heading always spells one of those words too (see
+                    // #2316-5 regression guard: "## Deferred v2 Requirements", "##
+                    // Future Backlog", "## Deferred", "## Backlog", "## Future").
+                    //
+                    // Fail-safe: when the milestone version cannot be resolved at all
+                    // (no STATE.md, or no `milestone:` field), fall back to the OLD
+                    // pre-#2316-4a behavior and treat every `v\d+` heading as deferred.
+                    // A false "deferred" here only ever SUPPRESSES a warning — strictly
+                    // safer than spamming a warning on every v\d+-headed scaffold when
+                    // we cannot tell whether it names the active milestone.
+                    const DEFERRED_KEYWORD_RE = /\b(?:deferred|backlog|future)\b/i;
+                    const HEADING_VERSION_RE = /\bv(\d+)(?:\.\d+)*\b/i;
+                    const stateRawForMilestone = node_fs_1.default.existsSync(statePath) ? node_fs_1.default.readFileSync(statePath, 'utf-8') : null;
+                    const currentMilestoneRaw = stateRawForMilestone
+                        ? stateExtractField(stateRawForMilestone, 'milestone')
+                        : null;
+                    const currentMilestoneMajor = currentMilestoneRaw ? extractMajorVersion(currentMilestoneRaw) : null;
                     const bodyReqIds = [];
                     // deferredDepth: the heading level that opened the current deferred block,
                     // or 0 when we are in an active section.
@@ -1617,11 +1783,21 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             }
                             // Heading at same level or shallower than current deferred opener,
                             // or no active deferred block yet.
-                            if (DEFERRED_HEADING_RE.test(text)) {
+                            if (DEFERRED_KEYWORD_RE.test(text)) {
                                 deferredDepth = depth; // enter a deferred block
                             }
                             else {
-                                deferredDepth = 0; // back in an active section
+                                const versionMatch = text.match(HEADING_VERSION_RE);
+                                if (versionMatch) {
+                                    const headingMajor = versionMatch[1];
+                                    deferredDepth =
+                                        currentMilestoneMajor === null || headingMajor !== currentMilestoneMajor
+                                            ? depth // unresolved milestone (fail-safe) or off-milestone version -> deferred
+                                            : 0; // same major version as the current milestone -> active
+                                }
+                                else {
+                                    deferredDepth = 0; // back in an active section
+                                }
                             }
                             continue;
                         }
@@ -1654,8 +1830,68 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     if (unregistered.length > 0) {
                         warnings.push(`REQUIREMENTS.md: ${unregistered.length} REQ-ID(s) found in body but missing from Traceability table: ${unregistered.join(', ')} — add them manually to keep traceability in sync`);
                     }
+                    // #2316-1: ghost REQ-IDs — cited by ROADMAP's own **Requirements:**
+                    // line for this phase, but registered NOWHERE in REQUIREMENTS.md
+                    // (neither its body nor its Traceability table). The `unregistered`
+                    // check above only ever compares REQUIREMENTS.md's own body against
+                    // its own Traceability table; it never consults `citedReqIds`, so an
+                    // ID that ROADMAP cites but REQUIREMENTS.md never defines at all was
+                    // previously invisible to every guard. `TBD` (the phase.add/-batch/
+                    // -insert placeholder) is excluded — see #2316-7 boundary.
+                    //
+                    // #2334 HIGH 2: classify "ghost" by PROBING THE ACTUAL WRITE
+                    // SURFACES this same function just wrote to (:1947 checkbox,
+                    // :1967 Traceability row) — case-insensitively — mirroring
+                    // milestone.cts's `notFound`/`hasRow`/`doneCheckbox` classification
+                    // (src/milestone.cts:117-141,209-215), instead of set-differencing
+                    // `bodyReqIds` (deferred-filtered, case-sensitive, bold-only) and
+                    // `tableReqIds` (case-sensitive) against `citedReqIds`. Those two
+                    // indexes can disagree with the writes: an ID under a `##
+                    // Deferred` heading gets its checkbox ticked by the write loop
+                    // above but is deliberately EXCLUDED from `bodyReqIds` by the
+                    // deferred-heading filter (#1159), so the old set-diff reported it
+                    // as an unregistered ghost in the SAME response that just ticked
+                    // its checkbox; a case-mismatched citation (`known-01` vs
+                    // `**KNOWN-01**`) lands its write via the writes' case-insensitive
+                    // regexes but failed the old set-diff's case-SENSITIVE
+                    // `Array.includes`/`Set.has`. An ID whose checkbox OR Traceability
+                    // row actually matched is registered — not a ghost — regardless of
+                    // which section (deferred or not) it lives under.
+                    const reqIsRegisteredAnywhere = (id) => {
+                        const reqEscaped = escapeRegex(id);
+                        // Surface 1 — checkbox, EITHER state (`[ ]` or `[x]`), case-
+                        // insensitive: existence check, not the write's space-only match.
+                        if (new RegExp(`-\\s*\\[[ xX]\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent)) {
+                            return true;
+                        }
+                        // Surface 2 — Traceability row exists at all (any Status value),
+                        // via the SAME no-op-probe-through-updateTraceabilityCell
+                        // technique milestone.cts's `hasRow` uses (:210-214): a case-
+                        // insensitive first-cell match, regardless of current Status.
+                        const rowProbeMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === id.toLowerCase();
+                        return updateTraceabilityCell(reqContent, rowProbeMatch, 'Status', (current) => current).ok;
+                    };
+                    const ghostReqIds = citedReqIds.filter((id) => !isPlaceholderReqId(id) && !reqIsRegisteredAnywhere(id));
+                    if (ghostReqIds.length > 0) {
+                        warnings.push(`ROADMAP Phase ${phaseNum} cites REQ-ID(s) not registered anywhere in REQUIREMENTS.md (neither body nor Traceability table): ${ghostReqIds.join(', ')} — add them to REQUIREMENTS.md or correct the ROADMAP citation`);
+                    }
+                    // #2316-1 cont.: a cited ID whose Traceability-row write matched no
+                    // row for a reason OTHER than being a ghost (e.g. a malformed table)
+                    // still deserves a warning instead of a silent discard — but skip
+                    // IDs already reported above as ghosts to avoid a duplicate message
+                    // for the same root cause.
+                    const traceabilityWriteFailures = traceabilityWriteMisses.filter((id) => !ghostReqIds.includes(id));
+                    if (traceabilityWriteFailures.length > 0) {
+                        warnings.push(`REQUIREMENTS.md: Traceability row write skipped for REQ-ID(s) cited by ROADMAP (no matching row found): ${traceabilityWriteFailures.join(', ')}`);
+                    }
                     writes.push({ filePath: reqPath, before: originalReqContent, after: reqContent });
-                    requirementsUpdated = true;
+                    // #2316-3: `requirements_updated` must reflect whether REQUIREMENTS.md
+                    // content actually CHANGED, not merely that the file existed in the
+                    // transaction — mirrors the `writes.push({filePath,before,after})`
+                    // diff-tracking pattern used for the ROADMAP write above. A phase
+                    // whose citations match nothing (ghost REQ-IDs only) must report
+                    // `false`, not a bare "the file was present" `true`.
+                    requirementsUpdated = reqContent !== originalReqContent;
                 }
             }
             try {
@@ -1802,10 +2038,15 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     clock: clock_cjs_1.realClock,
                     progressProvider: () => null, // completePhase derives progress from the roadmap, not disk
                     roadmapProvider: () => roadmapContent,
+                    sourcePath: statePath,
                 });
                 stateContent = completeResult.content;
                 stateContent = updatePerformanceMetricsSection(stateContent, cwd, phaseNum, planCount, summaryCount);
-                stateContent = syncStateFrontmatter(stateContent, cwd);
+                // #2736: the transition holds the next phase's exact display name in
+                // the intent; pass it as authoritative so the sync's prose
+                // re-derivation cannot rewrite current_phase_name to the name's own
+                // parenthetical (`Closer-ruling measurement (D1a)` → `D1a`).
+                stateContent = syncStateFrontmatter(stateContent, cwd, nextPhaseDisplayName ? { current_phase_name: nextPhaseDisplayName } : undefined);
                 writes.push({ filePath: statePath, before: originalStateContent, after: stateContent });
             }
             writePlanningFileSet(writes);

package/gsd-core/bin/lib/plan-drift-guard.cjs

@@ -3,7 +3,7 @@
  * ADR-22 Drift-Guard Decision Module
  *
  * Implements the authority ladder and severity classification table from
- * ADR-22 (docs/adr/0022-source-grounding-drift-guard.md).
+ * ADR-22 (docs/adr/22-plan-drift-guard.md).
  *
  * Design constraints:
  *   - Pure module: no I/O, no require() calls, no side effects.

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

@@ -12,10 +12,62 @@ const node_path_1 = require("node:path");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtils = require("./core-utils.cjs");
 const { countMatchedSummaries } = coreUtils;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterMod;
 // Excluded derivative files
 const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
 const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
 const PLAN_REVIEW_RE = /-PLAN-REVIEW\.md$/i;
+// #2349: a plan's frontmatter always sits at byte 0 and closes well before the
+// body, so only a bounded prefix is ever needed to read the `status` marker.
+// Capping the read keeps scanPhasePlans — which loops over every phase directory
+// on hot paths (state sync/validate, roadmap progress) — from slurping a
+// pathologically large committed plan file into memory just to inspect one key.
+const PLAN_FRONTMATTER_READ_CAP = 64 * 1024;
+/**
+ * #2349: a plan whose frontmatter declares `status: superseded` was deliberately
+ * reassigned or never executed — its work moved to a later plan, so it can never
+ * gain a matching `*-SUMMARY.md`. Like a retired phase (#1514, one level up), such
+ * a plan must be excluded from BOTH the plan and summary counts; otherwise a phase
+ * with a deliberately-unexecuted plan reads `completed: false` forever, pinning the
+ * milestone below 100%. Reading only the frontmatter `status` key is the same seam
+ * verify.cts / phase.cts already use for plan metadata; a plan without the marker is
+ * counted exactly as before.
+ *
+ * This is the only path in scanPhasePlans that opens file *contents* (the rest is
+ * filename matching), so it is hardened accordingly: `statSync().isFile()` rejects
+ * anything that is not a regular file — a directory, socket, or a symlink resolving
+ * to a device such as `/dev/zero` (a git-committable DoS vector; cf. #2378/#2383) —
+ * BEFORE any open, and the read is bounded to a fixed prefix. Fail-safe throughout:
+ * a non-regular or unreadable plan is treated as a normal (counted) plan, never
+ * silently dropped.
+ */
+function isPlanSuperseded(planFullPath) {
+    let content;
+    try {
+        const st = (0, node_fs_1.statSync)(planFullPath); // follows symlinks → resolves to the target's real type
+        if (!st.isFile())
+            return false;
+        const length = Math.min(st.size, PLAN_FRONTMATTER_READ_CAP);
+        if (length === 0)
+            return false;
+        const fd = (0, node_fs_1.openSync)(planFullPath, 'r');
+        try {
+            const buf = Buffer.allocUnsafe(length);
+            const bytesRead = (0, node_fs_1.readSync)(fd, buf, 0, length, 0);
+            content = buf.toString('utf8', 0, bytesRead);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+    const status = extractFrontmatter(content, planFullPath)['status'];
+    return typeof status === 'string' && status.trim().toLowerCase() === 'superseded';
+}
 function isRootPlanFile(fileName) {
     if (PLAN_OUTLINE_RE.test(fileName))
         return false;
@@ -75,7 +127,16 @@ function scanPhasePlans(phaseDir) {
         }
         catch { /* ignore unreadable nested layout */ }
     }
-    const planFiles = rootPlanFiles.concat(nestedPlanFiles);
+    const allPlanFiles = rootPlanFiles.concat(nestedPlanFiles);
+    // #2349: drop plans explicitly marked `status: superseded` from the plan set
+    // BEFORE counting, so they inflate neither the denominator (planCount) nor,
+    // via countMatchedSummaries below, the numerator (summaryCount). Plans without
+    // the marker are untouched, so behaviour is byte-for-behaviour identical for
+    // every existing phase — only a phase carrying the new marker changes.
+    const supersededPlanFiles = allPlanFiles.filter((f) => isPlanSuperseded((0, node_path_1.join)(phaseDir, f)));
+    const planFiles = supersededPlanFiles.length === 0
+        ? allPlanFiles
+        : allPlanFiles.filter((f) => !supersededPlanFiles.includes(f));
     const summaryFiles = rootSummaryFiles.concat(nestedSummaryFiles);
     const planCount = planFiles.length;
     // Count only summaries that are the PLAN→SUMMARY partner of an existing plan
@@ -87,7 +148,14 @@ function scanPhasePlans(phaseDir) {
     return {
         planCount,
         summaryCount,
-        completed: planCount > 0 && summaryCount >= planCount,
+        // #2349: gate completion on whether the phase had ANY plans on disk
+        // (allPlanFiles), NOT on the post-exclusion planCount. A phase whose plans
+        // were ALL marked superseded has planCount 0, but it is NOT an unplanned
+        // empty phase — there is simply no remaining work, so it must read complete
+        // (0 >= 0) rather than being pinned below 100% forever, which is the very
+        // failure this fix removes. A genuinely empty phase (no plans authored)
+        // still has allPlanFiles.length 0 and stays not-completed, exactly as before.
+        completed: allPlanFiles.length > 0 && summaryCount >= planCount,
         hasNestedPlans,
         planFiles,
         summaryFiles,

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -369,8 +369,15 @@ function findContextMdIn(absDirOrFiles) {
             return 'CONTEXT.md';
         return files.find((f) => f.endsWith('-CONTEXT.md')) ?? null;
     }
-    catch {
-        return null;
+    catch (err) {
+        // #1883: distinguish genuine absence from a permission/I-O failure. ENOENT
+        // ("nothing there") keeps the long-standing null contract the callers rely
+        // on; every other error (EACCES, EIO, …) is a real read failure that must
+        // propagate — otherwise an unreadable phase dir is silently reported as
+        // "no CONTEXT.md" and the discuss/plan gates wrongly skip context.
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
     }
 }
 module.exports = {

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

@@ -920,24 +920,50 @@ function cmdGenerateClaudeProfile(cwd, options, raw) {
         '<!-- GSD:profile-end -->',
     ];
     const sectionContent = sectionLines.join('\n');
+    // #2565: resolve target through effective runtime policy instead of
+    // hardcoded .claude/CLAUDE.md. Mirrors the #3163 fix applied to
+    // cmdGenerateClaudeMd above; that fix diverged when it didn't propagate
+    // here, leaving /gsd-profile-user writing Claude files on Codex installs.
+    // - Project scope: getProjectInstructionFile(runtime) is the single source
+    //   of truth (AGENTS.md for codex/opencode/kilo/kimi/unknown; GEMINI.md for
+    //   antigravity; .github/copilot-instructions.md for copilot).
+    // - Global scope: ~/.<config-home>/<instruction-basename>, derived from
+    //   getGlobalConfigDir + basename(getProjectInstructionFile), so codex lands
+    //   at ~/.codex/AGENTS.md. Claude global is preserved byte-for-byte (no
+    //   env-var drift beyond the prior hardcoded path).
+    // - GSD_RUNTIME env var takes precedence over config.runtime (mirrors the
+    //   #3163 env-precedence contract). Non-claude always wins over a stale
+    //   claude_md_path (#3163 rationale: an AGENTS-native project must never
+    //   write to CLAUDE.md even if a prior Claude setup left claude_md_path).
+    let config = {};
+    try {
+        config = loadConfig(cwd);
+    }
+    catch { /* use defaults */ }
+    const effectiveRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime']);
+    const isClaudeRuntime = !effectiveRuntime || effectiveRuntime === 'claude';
     let targetPath;
     if (options.global) {
-        targetPath = node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'CLAUDE.md');
+        if (isClaudeRuntime) {
+            targetPath = node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'CLAUDE.md');
+        }
+        else {
+            targetPath = node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(effectiveRuntime), node_path_1.default.basename((0, runtime_name_policy_cjs_1.getProjectInstructionFile)(effectiveRuntime)));
+        }
     }
     else if (options.output) {
         targetPath = node_path_1.default.isAbsolute(options.output) ? options.output : node_path_1.default.join(cwd, options.output);
     }
     else {
-        // Read claude_md_path from config; #1098 default is ./.claude/CLAUDE.md
+        // Read claude_md_path from config; #1098 default is .claude/CLAUDE.md
         // (kept consistent with cmdGenerateClaudeMd so the profile section and the
         // managed sections land in the same file on a config-less project).
-        let configClaudeMdPath = './.claude/CLAUDE.md';
-        try {
-            const config = loadConfig(cwd);
-            if (config['claude_md_path'])
-                configClaudeMdPath = config['claude_md_path'];
+        let configClaudeMdPath = '.claude/CLAUDE.md';
+        if (config['claude_md_path'])
+            configClaudeMdPath = config['claude_md_path'];
+        if (!isClaudeRuntime) {
+            configClaudeMdPath = (0, runtime_name_policy_cjs_1.getProjectInstructionFile)(effectiveRuntime);
         }
-        catch { /* use default */ }
         targetPath = node_path_1.default.isAbsolute(configClaudeMdPath) ? configClaudeMdPath : node_path_1.default.join(cwd, configClaudeMdPath);
     }
     let action;