@opengsd/gsd-core 1.8.0 → 1.9.1

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

@@ -66,6 +66,70 @@ const PHASE_CONTINUATION_SEGMENT_PREFIX_RE = new RegExp(`^${PHASE_CONTINUATION_S
 function isPhaseContinuationSegment(seg) {
     return PHASE_CONTINUATION_SEGMENT_PREFIX_RE.test(seg);
 }
+// #612 (PR-1): bracket-convention token/heading sources, kept next to the M-NN
+// PHASE_NUMBER_TOKEN_SOURCE so this owner file stays the single origin of every
+// phase-token grammar. `src/phase-id.cts` is exempt from the #2128 drift guard
+// (scripts/lint-phase-id-drift.cjs) by construction, and that guard fails any
+// literal re-derivation of the token grammar elsewhere — so the downstream
+// bracket readers (PR-2: roadmap/validate/verify) must build their regexes by
+// interpolating these exports, never by copying the literal.
+//
+// The canonical numeric WIDTH of a bracket identity field, mirroring pad2()'s
+// output: exactly 2 digits, or 3+ with no leading zero. Owned here as a SOURCE
+// so the read side (BRACKET_PHASE_TOKEN_SOURCE, below) and the emit-side
+// validator (CANONICAL_NUMERIC_RE, which toDir enforces) are one rule rather
+// than two literals that agree today and drift tomorrow.
+const BRACKET_CANONICAL_NUMERIC_SOURCE = '(?:[1-9]\\d{2,}|\\d{2})';
+// BRACKET_PHASE_TOKEN_SOURCE differs from PHASE_NUMBER_TOKEN_SOURCE by a
+// dot-OR-dash sub-separator: a bracket dir/heading numeric run is `MM-PP[.SS]`
+// (a hyphen joins milestone↔phase, a dot joins phase↔sub-phase), whereas M-NN
+// sub-phases are dot-only.
+//
+// The run is POSITIONAL, not a free repetition — `MM-PP[.SS][-LL]` — and each
+// position gets the width its DELIMITER can actually afford:
+//
+//   MM   leading   unbounded  — delimited by the `{CODE}.` prefix
+//   -PP  dash-1    canonical  — the grammar REQUIRES this dash, so it is a field
+//                              separator, not a continuation heuristic
+//   .SS  dot       canonical  — a slug carries no dot (toDir sanitizes them
+//                              away), so this position cannot collide
+//   -LL  dash-2    #2232 cap  — the ONLY slug-adjacent position, and therefore
+//                              the only one a slug word can collide with
+//
+// #2232 reconciliation: the slug-adjacent position interpolates the single-owner
+// PHASE_CONTINUATION_SEGMENT_SOURCE, so the #2232 bug class cannot reopen on the
+// bracket path — dir `PROJ.01-14-2026-photos-…` (a slug leading with a year)
+// yields `01-14`, never `01-14-2026`.
+//
+// DELIBERATE DIVERGENCE from the M-NN dir-token path (pinned by the parity gate
+// in tests/continuation-grammar-parity.test.cjs, which fails if these two rules
+// drift for a reason nobody intended): the non-slug-adjacent positions stay
+// WIDER than #2232's cap. Bracket admits 3+-digit milestone/phase/sub-phase
+// (CANONICAL_NUMERIC_RE — `[GSD.100] 05` is a pinned regression), and unlike the
+// M-NN continuations those positions are delimiter-disambiguated rather than
+// heuristically recognized, so there is no year collision to defend against.
+// Interpolating the cap verbatim at every position would only under-collect ids
+// that toDir itself emits: `PROJ.02-105-slug` (3-digit phase) would read as
+// `02`, and `[GSD.02] 05.100` (3-digit sub-phase) as `05`. Upstream draws this
+// same line for the same reason — core-utils/phase cap the paired PLAN component
+// while the leading phase component stays unbounded (phase numbers ≥100 are
+// legitimate). The trade-off this accepts is #2232's policy verbatim: a PLAN
+// ≥100 is out of the token grammar.
+//
+// Still deliberately MORE PERMISSIVE than parsePhaseId's strict grammar (it
+// admits a letter-suffixed and unpadded leading token that the parser rejects):
+// this is a READ-TOLERANCE source for the PR-2 readers, which must recognize a
+// bracket-shaped token before deciding what to do with it — it is not the
+// emit/identity grammar. parsePhaseId stays the arbiter of well-formedness.
+const BRACKET_PHASE_TOKEN_SOURCE = `\\d+[A-Z]?` +
+    `(?:-${BRACKET_CANONICAL_NUMERIC_SOURCE}(?!\\d))?` +
+    `(?:\\.${BRACKET_CANONICAL_NUMERIC_SOURCE}(?!\\d))?` +
+    `(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE})?`;
+// A phase HEADING intro under bracket is either a `[...]` bracket (optionally
+// followed by a `Phase ` label) or a bare `Phase ` label; a bare number is NOT
+// a phase-heading intro. The `[^\]]{1,200}` bound mirrors the existing
+// roadmap-parser heading regexes (ReDoS-safe: a header is one short line).
+const PHASE_HEADING_PREFIX_SRC = '(?:\\[[^\\]]{1,200}\\]\\s*(?:Phase\\s+)?|Phase\\s+)';
 function stripProjectCodePrefix(value, caseInsensitive = true) {
     const input = String(value);
     const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
@@ -98,7 +162,23 @@ function normalizePhaseName(phase) {
     // Custom phase IDs (e.g. PROJ-42, AUTH-101): return as-is
     return str;
 }
-function getMilestoneFromPhaseId(phaseId) {
+function getMilestoneFromPhaseId(phaseId, convention) {
+    // READING-B (#612): under the bracket convention the milestone comes from the
+    // `[PROJECT.MM]` / `{CODE}.{MM}-` prefix, never the phase-token leading
+    // integer (ADR-612 Decision 6). Gated on 'bracket' so the `null` and
+    // 'milestone-prefixed' (M-NN) paths keep the legacy leading-int rule
+    // (READING-A) below, byte-untouched. The optional parameter keeps this helper
+    // pure (no config read) and backward-compatible: every existing single-arg
+    // caller resolves to the unchanged READING-A body.
+    if (convention === 'bracket') {
+        const b = String(phaseId).match(/^([A-Z][A-Z0-9_]*)\.(\d+)/);
+        if (!b)
+            return null;
+        const mm = parseInt(b[2], 10);
+        if (SENTINEL_RANGES.includes(mm))
+            return null; // sentinel milestones have no real milestone
+        return `v${mm}.0`;
+    }
     const stripped = stripProjectCodePrefix(phaseId);
     const m = stripped.match(/^0*(\d+)-\d/);
     if (!m)
@@ -123,6 +203,145 @@ function getPhaseDirFromPhaseId(phaseId, phaseName, projectCode) {
     const base = parts.join('-');
     return projectCode ? `${projectCode}-${base}` : base;
 }
+const pad2 = (n) => String(parseInt(n, 10)).padStart(2, '0');
+function parsePhaseId(input) {
+    // No .trim(): the match anchors (`^`...`$`) then reject leading/trailing
+    // whitespace outright, folding that case into the same "not a bracket
+    // phase id" rejection below rather than needing its own check.
+    const str = String(input);
+    // Display form: [PROJECT.MM] PP[.SS][-LL]. The match itself stays
+    // permissive on purpose (it will happily match an unpadded number or a
+    // multi-space run) — canonicality is enforced UNIFORMLY below via the
+    // render round-trip (ADR-612 Decision 4) rather than by hand-tuning every
+    // numeric / whitespace sub-pattern, so a field added later inherits the
+    // check for free instead of needing its own regex micro-surgery.
+    const disp = str.match(/^\[([A-Z][A-Z0-9_]*)\.(\d+)\]\s+(\d+)(?:\.(\d+))?(?:-(\d+))?$/);
+    if (disp) {
+        const id = { project: disp[1], milestone: pad2(disp[2]), phase: pad2(disp[3]) };
+        if (disp[4] !== undefined)
+            id.subphase = pad2(disp[4]);
+        if (disp[5] !== undefined)
+            id.plan = pad2(disp[5]);
+        // Canonicality by construction: re-render the parsed id and require
+        // byte-equality with the input. This rejects unpadded ('[GSD.5] 5'),
+        // over-padded ('[GSD.005] 05'), and multi-space-separated ('[GSD.02]  05')
+        // variants uniformly, without special-casing any one of them — the emit
+        // path (renderPhaseId) is the single source of truth for "canonical".
+        if (renderPhaseId(id) !== str) {
+            throw new Error(`parsePhaseId: not canonical: ${JSON.stringify(input)}`);
+        }
+        return id;
+    }
+    // Dir / token form: {PROJECT}.{MM}-{PP}[.{SS}][-{plan|slug}]
+    const dir = str.match(/^([A-Z][A-Z0-9_]*)\.(\d+)-(\d+)(?:\.(\d+))?(?:-(.+))?$/);
+    if (dir) {
+        const id = { project: dir[1], milestone: pad2(dir[2]), phase: pad2(dir[3]) };
+        if (dir[4] !== undefined)
+            id.subphase = pad2(dir[4]);
+        // Trailing segment: a pure-integer tail is the plan; anything else is a
+        // slug (dropped from the tuple — it is not an identity dimension). The
+        // plan tail participates in the canonicality check below; the slug tail
+        // is read-tolerant pass-through (a slug is not an identity dimension) and
+        // is exempt from it.
+        const tail = dir[5];
+        const tailIsPlan = tail !== undefined && /^\d+$/.test(tail);
+        if (tailIsPlan)
+            id.plan = pad2(tail);
+        // Canonicality by construction, mirroring the display branch: rebuild the
+        // exact dir/token string this id would emit and require it match the
+        // input verbatim. Rejects unpadded milestone/phase ('GSD.2-5') and
+        // unpadded plan tails ('GSD.02-05-1') without special-casing either.
+        const sub = id.subphase ? `.${id.subphase}` : '';
+        const tailOut = tail === undefined ? '' : tailIsPlan ? `-${pad2(tail)}` : `-${tail}`;
+        const canonical = `${id.project}.${id.milestone}-${id.phase}${sub}${tailOut}`;
+        if (canonical !== str) {
+            throw new Error(`parsePhaseId: not canonical: ${JSON.stringify(input)}`);
+        }
+        return id;
+    }
+    // Ambiguous / bare tokens (e.g. `02-04`, `05`, `2-01`) match neither branch,
+    // as does a display/dir form carrying leading/trailing whitespace (the
+    // anchors never match it): reject rather than guess a tuple (ADR-612
+    // conservative default). The rejection lives ONLY in this new parser —
+    // normalizePhaseName and every other legacy reader keep accepting those
+    // tokens unchanged.
+    throw new Error(`parsePhaseId: not a bracket phase id: ${JSON.stringify(input)}`);
+}
+function renderPhaseId(id) {
+    const sub = id.subphase ? `.${id.subphase}` : '';
+    const plan = id.plan ? `-${id.plan}` : '';
+    return `[${id.project}.${id.milestone}] ${id.phase}${sub}${plan}`;
+}
+// PhaseId is a structural type: nothing forces a caller through parsePhaseId,
+// so toDir cannot trust project/milestone/phase/subphase are already
+// canonical — each is validated below against the exact shape parsePhaseId
+// itself would ever produce, closing off a hand-built id as a path-traversal
+// vector. PROJECT_ID_RE mirrors the parser's `[A-Z][A-Z0-9_]*` grammar;
+// CANONICAL_NUMERIC_RE mirrors pad2()'s output shape — exactly 2 digits, or
+// 3+ digits with no leading zero. It is BUILT from
+// BRACKET_CANONICAL_NUMERIC_SOURCE rather than re-spelled as a literal, so this
+// emit-side gate and the read-side token source cannot disagree about what
+// "canonical width" means (the anchors here make the source's trailing `(?!\d)`
+// guard, which the unanchored read side needs, redundant).
+const PROJECT_ID_RE = /^[A-Z][A-Z0-9_]*$/;
+const CANONICAL_NUMERIC_RE = new RegExp(`^${BRACKET_CANONICAL_NUMERIC_SOURCE}$`);
+function toDir(id, slug) {
+    if (!PROJECT_ID_RE.test(id.project)) {
+        throw new Error(`toDir: invalid project: ${JSON.stringify(id.project)}`);
+    }
+    if (!CANONICAL_NUMERIC_RE.test(id.milestone)) {
+        throw new Error(`toDir: invalid milestone: ${JSON.stringify(id.milestone)}`);
+    }
+    if (!CANONICAL_NUMERIC_RE.test(id.phase)) {
+        throw new Error(`toDir: invalid phase: ${JSON.stringify(id.phase)}`);
+    }
+    if (id.subphase !== undefined && !CANONICAL_NUMERIC_RE.test(id.subphase)) {
+        throw new Error(`toDir: invalid subphase: ${JSON.stringify(id.subphase)}`);
+    }
+    // A non-string slug (e.g. an omitted second argument) must not be silently
+    // coerced by String(...) into the literal token 'undefined'/'null' on disk.
+    if (typeof slug !== 'string') {
+        throw new Error(`toDir: slug must be a string: ${JSON.stringify(slug)}`);
+    }
+    const sub = id.subphase ? `.${id.subphase}` : '';
+    // Slug guard: the slug becomes an on-disk path segment, so collapse it to a
+    // safe lowercase token — never a path separator or `..` traversal.
+    const safeSlug = slug.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    // A slug that sanitizes to nothing (e.g. '!!!') would otherwise emit a
+    // dangling trailing hyphen.
+    if (!safeSlug) {
+        throw new Error(`toDir: slug sanitizes to empty: ${JSON.stringify(slug)}`);
+    }
+    // An all-digit slug (e.g. '2026') is string-indistinguishable from the
+    // parsePhaseId dir branch's plan tail, so it would re-parse as a plan, not
+    // a slug — silently breaking the disk↔identity bijection on read-back.
+    if (/^\d+$/.test(safeSlug)) {
+        throw new Error(`toDir: slug must not be all-digit: ${JSON.stringify(slug)}`);
+    }
+    return `${id.project}.${id.milestone}-${id.phase}${sub}-${safeSlug}`;
+}
+// Milestone integers reserved as non-milestone sentinels (0.x backlog / 999.x
+// icebox); a phase id in these ranges has no real milestone.
+const SENTINEL_RANGES = Object.freeze([0, 999]);
+function isSentinelPhaseId(phaseId, convention) {
+    const s = String(phaseId);
+    // Bracket milestone lives in the `{CODE}.{MM}` prefix. GATED on
+    // convention === 'bracket' for the same reason as extractPhaseToken below and
+    // getMilestoneFromPhaseId above: that prefix is string-indistinguishable from
+    // the legacy #1324 letter-prefixed-decimal family (`P0.0-foundation` is a real
+    // phase, NOT sentinel milestone 0) whenever the code ends in a digit. A
+    // convention-less caller uses the legacy/bare leading-int rule below, so no
+    // existing reader gains a false positive; the bracket reading is opt-in.
+    if (convention === 'bracket') {
+        const bracket = s.match(/^[A-Z][A-Z0-9_]*\.(\d+)/); // bracket: milestone in the prefix
+        if (bracket)
+            return SENTINEL_RANGES.includes(parseInt(bracket[1], 10));
+    }
+    const legacy = stripProjectCodePrefix(s).match(/^0*(\d+)/); // legacy/bare: leading int
+    if (!legacy)
+        return false;
+    return SENTINEL_RANGES.includes(parseInt(legacy[1], 10));
+}
 /**
  * Render a regex source fragment matching a phase number against ROADMAP/STATE
  * prose regardless of zero-padding on either side.
@@ -219,7 +438,25 @@ function comparePhaseNum(a, b) {
 /**
  * Extract the phase token from a directory name.
  */
-function extractPhaseToken(dirName) {
+function extractPhaseToken(dirName, convention) {
+    // #612 bracket dir form `{CODE}.{MM}-{PP}[.{SS}]-slug` → phase token `PP[.SS]`.
+    // GATED on convention === 'bracket' (mirrors getMilestoneFromPhaseId's READING-B
+    // decision above). A bracket dir `{CODE}.{MM}-{PP}` is string-INDISTINGUISHABLE
+    // from the legacy #2043/#1324 letter-prefixed-decimal family (`P0.3-2`,
+    // `P0.12-34`) whenever the project code ends in a digit, so NO string-only
+    // discriminator can separate the two conventions — auto-detecting here silently
+    // reinterpreted `P0.3-2` → `2` (was `P0.3-2`), a byte-identical-read regression
+    // on this CRITICAL 6-caller helper (ADR-2121). Requiring an explicit convention
+    // signal keeps every existing (convention-less) call site byte-identical to
+    // prior behaviour — see the #2043 numeric-tail characterization in
+    // tests/phase-id.test.cjs — while keeping the helper pure (optional param, no
+    // config read). The captured token is dot-only (`PP[.SS]`); the milestone↔phase
+    // hyphen and any trailing plan/slug are excluded.
+    if (convention === 'bracket') {
+        const bracketDir = dirName.match(/^[A-Z][A-Z0-9_]*\.\d+-(\d+(?:\.\d+)?)/);
+        if (bracketDir)
+            return bracketDir[1];
+    }
     const codePrefixMatch = dirName.match(PROJECT_CODE_PREFIX_CAPTURE_RE_I);
     let prefix = '';
     let rest = dirName;
@@ -310,9 +547,38 @@ function parsePhaseFromProse(value) {
     // cannot drive O(n^2) regex backtracking (CPU-exhaustion DoS). A real phase
     // name is far shorter than the cap.
     const parenName = str.match(/\(([^)]{1,200})\)/);
-    const dashName = str.match(/—\s*([^(\n]{1,200}?)(?:\s*\(|$)/);
-    const rawName = parenName?.[1] ?? dashName?.[1] ?? null;
-    const name = rawName && !/^(?:complete|executing|not started)$/i.test(rawName.trim())
+    // #2736 (the #1695 AC #3 residual): status-keyword-aware precedence. The
+    // first-party writer shapes are `N — Name (aside)` (completePhaseCore),
+    // `N (Name) — EXECUTING` (beginPhaseCore), `N — COMPLETE`, and the
+    // gsd2-import `N (slug) — Milestone: Title`. A blind paren-first read
+    // harvests the aside as the name on the first shape; a blind dash-first
+    // read harvests the status keyword on the others. Prefer the em-dash name
+    // when it is a genuine name, else fall back to the parenthetical. Still
+    // lossy for names that themselves contain a parenthetical — transitions
+    // that hold the exact name bypass this parser entirely via the
+    // syncStateFrontmatter authoritative override.
+    //
+    // The em-dash separator is searched on a paren-stripped copy, so an em-dash
+    // INSIDE a parenthetical name (`16 (Native — Global Hotkey) — EXECUTING`)
+    // can never be mistaken for the name separator.
+    const strNoParens = str.replace(/\([^)\n]{0,200}\)/g, ' ');
+    const dashName = strNoParens.match(/—\s*([^(\n]{1,200}?)\s*$/);
+    // The precedence-decision vocabulary is deliberately broader than the final
+    // name-nulling filter below: a dash tail that merely LOOKS like a status
+    // annotation should lose to a parenthetical name, without changing which
+    // extracted names are nulled (that set stays the long-standing three).
+    const STATUS_WORD_RE = /^(?:complete|executing|not started)$/i;
+    const STATUSY_TAIL_RE = /^(?:completed?|executing|not started|planning|planned|ready(?:\s+to\s+\S.{0,50})?|done|in progress|blocked|paused|verifying)$/i;
+    const dashRaw = dashName?.[1]?.trim() ?? null;
+    const dashIsName = dashRaw !== null && dashRaw.length > 0
+        && !STATUSY_TAIL_RE.test(dashRaw)
+        && !/^milestone\s*:/i.test(dashRaw)
+        // A lone ALL-CAPS token after the dash reads as a status marker whenever a
+        // parenthetical name exists to prefer (the beginPhase writer's systematic
+        // `(Name) — STATUS` shape); with no parenthetical it stays the best guess.
+        && !(parenName && /^[A-Z][A-Z0-9_-]*$/.test(dashRaw));
+    const rawName = dashIsName ? dashRaw : (parenName?.[1] ?? dashRaw ?? null);
+    const name = rawName && !STATUS_WORD_RE.test(rawName.trim())
         ? rawName.trim()
         : null;
     return {
@@ -380,10 +646,17 @@ module.exports = {
     PHASE_NUMBER_TOKEN_SOURCE,
     PHASE_CONTINUATION_SEGMENT_SOURCE,
     isPhaseContinuationSegment,
+    BRACKET_PHASE_TOKEN_SOURCE,
+    PHASE_HEADING_PREFIX_SRC,
     stripProjectCodePrefix,
     normalizePhaseName,
     getMilestoneFromPhaseId,
     getPhaseDirFromPhaseId,
+    parsePhaseId,
+    renderPhaseId,
+    toDir,
+    SENTINEL_RANGES,
+    isSentinelPhaseId,
     phaseMarkdownRegexSource,
     phaseMarkdownRegexSourceExact,
     comparePhaseNum,

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;
@@ -512,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;
@@ -1402,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')
@@ -1424,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;
         }
@@ -1651,7 +1698,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             // requirement's write. The "only flip Pending/In Progress ->
                             // 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);
+                            const reqUpdate = updateTraceabilityCell(reqContent, reqRowMatch, 'Status', (current) => 
+                            // #2788: accept `Gaps Found` too so a phase stranded by revert-phase (the
+                            // gaps_found response) can complete without hand-editing the table.
+                            /^(?:pending|in progress|gaps found)$/i.test(current.trim()) ? ' Complete ' : current);
                             if (reqUpdate.ok) {
                                 reqContent = reqUpdate.value;
                             }
@@ -1991,10 +2041,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

@@ -65,7 +65,7 @@ function isPlanSuperseded(planFullPath) {
     catch {
         return false;
     }
-    const status = extractFrontmatter(content)['status'];
+    const status = extractFrontmatter(content, planFullPath)['status'];
     return typeof status === 'string' && status.trim().toLowerCase() === 'superseded';
 }
 function isRootPlanFile(fileName) {

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;

package/gsd-core/bin/lib/project-root.cjs

@@ -63,6 +63,33 @@ function findProjectRoot(startDir) {
         }
         return false;
     }
+    // #2843: nearest ancestor (including `from` itself) that contains a `.git`,
+    // bounded by `upTo` (exclusive). Returns the git-repo root, or null if none
+    // exists before `upTo` / the filesystem root. Used to detect a NESTED child
+    // repo whose root is strictly below a candidate ancestor `.planning/` — in
+    // that case the caller's repo boundary sits between start and the ancestor,
+    // so trusting the ancestor's `.planning/` would silently cross into a
+    // different project. (No `git` subprocess — fs walk only, matching
+    // isInsideGitRepo's deliberate no-spawn contract.)
+    function nearestGitRoot(from, upTo) {
+        let d = from;
+        while (d !== fsRoot) {
+            if (d === upTo)
+                break;
+            try {
+                if (node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
+                    return d;
+            }
+            catch {
+                // ignore
+            }
+            const next = node_path_1.default.dirname(d);
+            if (next === d)
+                break;
+            d = next;
+        }
+        return null;
+    }
     let dir = resolvedStart;
     let depth = 0;
     while (dir !== fsRoot && depth < FIND_PROJECT_ROOT_MAX_DEPTH) {
@@ -114,6 +141,18 @@ function findProjectRoot(startDir) {
             // claims our startDir — explicit sub_repos config takes precedence over the
             // implicit .git signal. (#1422)
             if (isInsideGitRepo(parent)) {
+                // #2843: do NOT cross a git-repo boundary. If the caller is inside its
+                // OWN nested repo whose root is strictly below `parent`, trusting
+                // `parent`'s .planning/ would silently resolve to a DIFFERENT project.
+                // isInsideGitRepo only proved SOME .git exists between start and parent;
+                // verify that .git is parent's own (or absent between), not a nested
+                // child repo. If nearestGitRoot finds a .git strictly below parent,
+                // the boundary is crossed — fall through (do not return parent).
+                if (nearestGitRoot(resolvedStart, parent) !== null) {
+                    dir = parent;
+                    depth += 1;
+                    continue;
+                }
                 // Lookahead: walk ancestors above `parent` to find a sub_repos claim.
                 let ancestor = node_path_1.default.dirname(parent);
                 let ancestorDepth = 0;
@@ -169,6 +208,15 @@ function findProjectRoot(startDir) {
         try {
             const candidatePlanning = parent2 + node_path_1.default.sep + '.planning';
             if (node_fs_1.default.existsSync(candidatePlanning) && node_fs_1.default.statSync(candidatePlanning).isDirectory()) {
+                // #2843: do not cross a git-repo boundary. If the caller is inside its
+                // own nested repo (a .git strictly below parent2), parent2's .planning/
+                // belongs to a DIFFERENT project — keep walking is wrong; stop and fall
+                // through to the startDir fallback instead of silently resolving to the
+                // ancestor project. (Reached only when no .git exists anywhere in the
+                // chain per the triage, but guard defensively.)
+                if (nearestGitRoot(resolvedStart, parent2) !== null) {
+                    break;
+                }
                 return parent2;
             }
         }