@opengsd/gsd-core 1.7.0 → 1.9.0

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

@@ -48,6 +48,88 @@ const OPTIONAL_PHASE_TAG_SOURCE = '(?:\\s*\\([^)\\n]{0,200}\\))?';
 // (scripts/lint-phase-id-drift.cjs) fails CI if a literal re-derivation is
 // introduced outside this module without a `// phase-id-owner:` justification.
 const PHASE_NUMBER_TOKEN_SOURCE = '\\d+[A-Z]?(?:\\.\\d+)*';
+// #2232: the canonical CONTINUATION-segment grammar — a dash-separated segment
+// that extends a phase token (a zero-padded sub-phase or plan number, e.g. the
+// "01" in "02-01-setup"). getPhaseDirFromPhaseId writes these zero-padded to
+// exactly 2 digits, so the digit RUN of a genuine continuation is exactly 2:
+// #2043's `\d{2,}` (2-or-more) over-collected a slug word that merely leads
+// with ≥2 digits (a year: "14-2026-photos-…" yielded token "14-2026", so every
+// phase-locating verb reported the phase as missing). The `(?!\d)` guard caps
+// the run at 2 without anchoring what may follow, so call sites keep their own
+// trailing grammar (letter suffixes, dotted sub-phases, segment boundaries).
+// POLICY (locked by boundary tests): sub-phase/plan numbers ≥100 are out of the
+// dir-token grammar — the LEADING phase number stays unbounded (`\d+`), only
+// continuation segments are width-capped. Shared from here so the five #2043
+// call sites cannot drift independently (see scripts/lint-phase-id-drift.cjs).
+const PHASE_CONTINUATION_SEGMENT_SOURCE = '\\d{2}(?!\\d)';
+const PHASE_CONTINUATION_SEGMENT_PREFIX_RE = new RegExp(`^${PHASE_CONTINUATION_SEGMENT_SOURCE}`);
+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;
@@ -80,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)
@@ -105,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.
@@ -201,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;
@@ -211,9 +466,11 @@ function extractPhaseToken(dirName) {
     }
     const segments = rest.split('-');
     const tokenSegments = [];
-    // #2043: distinguish a real (zero-padded, ≥2-digit) phase/sub-phase segment
-    // from a single-digit slug word. A pure-numeric leading segment ("46") only
-    // continues with ≥2-digit segments, so "46-6-rs-…" yields "46" (the "6" is the
+    // #2043: distinguish a real (zero-padded) phase/sub-phase segment from a
+    // single-digit slug word. A pure-numeric leading segment ("46") only
+    // continues with exactly-2-digit segments (#2232: a ≥3-digit run is a slug
+    // word such as a year — "14-2026-photos-…" yields "14", not "14-2026"), so
+    // "46-6-rs-…" yields "46" (the "6" is the
     // slug's first word), not "46-6". Milestone-prefixed ids like "M1-2" reach here
     // with "M1-" already stripped as a project-code prefix (see
     // PROJECT_CODE_PREFIX_CAPTURE_RE_I), so "2" is the leading segment and the same
@@ -236,7 +493,7 @@ function extractPhaseToken(dirName) {
                 break;
             }
         }
-        else if (/^\d{2,}/.test(seg) || (firstLetterPrefixed && /^\d/.test(seg))) {
+        else if (isPhaseContinuationSegment(seg) || (firstLetterPrefixed && /^\d/.test(seg))) {
             tokenSegments.push(seg);
         }
         else {
@@ -290,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 {
@@ -358,10 +644,19 @@ module.exports = {
     OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
     OPTIONAL_PHASE_TAG_SOURCE,
     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,