@opengsd/gsd-core 1.14.0 → 1.16.0

package/scripts/lint-phase-id-drift.cjs

@@ -37,6 +37,22 @@
  *   over markdown, not `.cts` source, so its sanction is an HTML comment on the
  *   nearest preceding non-blank line: `<!-- phase-id-owner: <reason> -->`.
  *
+ * - phase-heading-scan literal drift (#4906 Phase 5 / #4984): `findPhaseHeadingScanLiteralDrift`
+ *   detects a hand-rolled `#{2,4}\s*Phase\s+` heading-SCAN literal, which bypasses
+ *   `buildPhaseHeadingScanRegex` / `phaseHeadingPrefixSrcFor` (both in
+ *   `src/phase-id.cts`) and so silently fails to recognize bracket-convention
+ *   headings. Sanctioned the same way as the token/bracket/name-validity rules
+ *   (`// phase-id-owner:` on the nearest preceding non-blank line), with a
+ *   line-level escape for a line that already names either owner function.
+ *   Wired into `scanRepo` (ADR-4910 §8): every pre-existing site this phase
+ *   could not migrate (src/phase.cts x11, src/roadmap-parser.cts x3,
+ *   src/planning-snapshot.cts x1) is grandfathered with a dedicated
+ *   `// phase-id-owner:` sanction comment rather than a separate allowlist —
+ *   the guard is ACTIVE from this phase forward: a fresh unsanctioned copy
+ *   fails CI immediately, and each grandfathered comment is deleted as its
+ *   site migrates in a later phase (ADR-4910 §8's census/grandfather/delete
+ *   sequence, never renewed).
+ *
  * - branch-slug fallback drift: a `.replace('{slug}', ... || 'phase')` call
  *   silently substitutes the literal string `'phase'` when a phase's slug
  *   can't be derived, producing a non-identifying branch name like
@@ -234,6 +250,67 @@ function findBranchSlugFallbackDrift(text) {
   return out;
 }
 
+// #4906 Phase 5 (#4984): a hand-rolled heading-SCAN literal `#{2,4}\s*Phase\s+`
+// (in either regex-literal `\s` or template `\\s` escaping, mirroring
+// TOKEN_DRIFT_RE's tolerance) bypasses `buildPhaseHeadingScanRegex` /
+// `phaseHeadingPrefixSrcFor` (both in `src/phase-id.cts`) entirely, so it
+// silently fails to recognize bracket-convention headings (`[GSD.03] Phase
+// 03:`) — the exact defect this phase fixed at five call sites in init.cts
+// and milestone.cts. A line naming either owner function counts as "built
+// from the owner" and is not flagged, mirroring the token rule's
+// `line.includes(CANON_REF)` escape.
+const PHASE_HEADING_SCAN_LITERAL_DRIFT_RE = /#\{2,4\}\\{1,2}s\*Phase\\{1,2}s\+/;
+const PHASE_HEADING_SCAN_LITERAL_CANON_REFS = ['buildPhaseHeadingScanRegex', 'phaseHeadingPrefixSrcFor'];
+
+/**
+ * Pure: find every unsanctioned hand-rolled `#{2,4}\s*Phase\s+` heading-scan
+ * literal in `text`. Sanctioned when the line already names either owner
+ * function (`buildPhaseHeadingScanRegex(` / `phaseHeadingPrefixSrcFor(`), or
+ * by a `// phase-id-owner:` comment on the nearest preceding non-blank line
+ * (same mechanism as every other rule in this file). Returns [{ line, found }].
+ */
+function findPhaseHeadingScanLiteralDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = PHASE_HEADING_SCAN_LITERAL_DRIFT_RE.exec(line);
+    if (!m) continue;
+    if (PHASE_HEADING_SCAN_LITERAL_CANON_REFS.some((ref) => line.includes(ref))) continue;
+    if (isSanctionedByPrecedingComment(lines, i, OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+/**
+ * Scan the authored source tree (`src/**\/*.cts`, the same `SCAN_DIRS` root
+ * and `phase-id.cts` owner exemption that `scanRepo` applies to this
+ * detector — the heading-scan literal is a `src/**\/*.cts` defect, not a
+ * markdown one, unlike its sibling wrappers below) for unsanctioned
+ * hand-rolled heading-scan literals. Returns [{ file, line, found }] with
+ * repo-relative paths.
+ */
+function scanMarkdownPhaseHeadingScanLiteral(root) {
+  const violations = [];
+  for (const dir of SCAN_DIRS) {
+    for (const file of walk(path.join(root, dir), [])) {
+      const rel = path.relative(root, file);
+      if (EXEMPT.has(rel)) continue;
+      let text;
+      try {
+        text = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const d of findPhaseHeadingScanLiteralDrift(text)) {
+        violations.push({ file: rel, kind: 'phase-heading-scan-literal', ...d });
+      }
+    }
+  }
+  return violations;
+}
+
 // #4634: ban base-10-forced shell arithmetic (`$((10#...))`) on a variable
 // that still carries a possibly-decimal/multi-segment phase id — this
 // construct is exactly the pattern that breaks on a value like `08.5`. The
@@ -246,11 +323,14 @@ function findBranchSlugFallbackDrift(text) {
 //   1. Prose mentioning the literal pattern in a full-line `#`-comment
 //      (filtered by the caller, not this regex — see below).
 //   2. `$((10#$PHASE_INT))` / `$((10#$SPOT_PHASE_INT))` — arithmetic on the
-//      NOW-safe variable the #4619 fix produces via `PHASE_INT=${PHASE_NUMBER%%.*}`;
-//      a `%%.*`-stripped value can never contain a dot, so base-10 arithmetic
-//      on it can never hit the #4619 syntax-error class. Any name ending in
-//      `_INT` (case-insensitive) is that established "already reduced to a
-//      safe integer" convention.
+//      NOW-safe variable the #4619 fix produces via a leading-digit-run split
+//      (`PHASE_INT=${PHASE_NUMBER%%[!0-9]*}` since #4748; `%%.*` before it);
+//      a digit-run value can never contain a dot OR a letter, so base-10
+//      arithmetic on it can never hit the #4619 / #4748 error classes. Any
+//      name ending in `_INT` (case-insensitive) is that established "already
+//      reduced to a safe integer" convention. That convention is a NAME, not
+//      a proof — `findDotOnlyIntegerSplitDrift` below polices that the split
+//      producing it actually stops at the first non-digit.
 //   3. `$((10#{plan_padded}))` / `$((10#${PLAN_ID}))` — plan ids are plain
 //      integers and were never in scope; this rule only polices variables
 //      that carry a *phase* id.
@@ -389,6 +469,204 @@ function scanMarkdownSingleSegmentPhaseRegex(root) {
   return violations;
 }
 
+// #4660 (epic #4634): the six shell/markdown mirrors #4568 widened on the
+// segment-count axis stayed digit-only on the LETTER axis — the canonical
+// grammar (`src/phase-id.cts`) is `\d+[A-Z]?(?:\.\d+)*`, with an optional
+// single uppercase letter after the leading digits (`12A`, `3A`, `23A.1.2`,
+// documented in docs/CONFIGURATION.md and relied on by `renameIntegerPhases`).
+// A digit-only mirror `[0-9]+(\.[0-9]+)*` hard-rejects (validating sites) or
+// silently truncates (extracting sites) a letter-suffixed id. This rule is the
+// ratchet for that axis, the twin of the single-segment rule above: it flags
+// the unbounded-segment shape whose digit run is NOT followed by the letter
+// class. `[A-Z]` is the canonical spelling; the case-flexible `[A-Za-z]`
+// directory-scanning variant is a deliberately separate axis and is tolerated
+// here so this rule cannot force it to narrow.
+const LETTERLESS_PHASE_MIRROR_DRIFT_RE =
+  /(?:\\{1,2}d|\[0-9\])\+(?!\[A-Z(?:a-z)?\]\?)\(\\{1,2}\.(?:\\{1,2}d|\[0-9\])\+\)\*/;
+
+/**
+ * Pure: find every unsanctioned digit-only (letter-less) unbounded-segment
+ * phase regex in `text`, restricted to lines that plausibly carry a
+ * phase-number variable — the same `PHASE_CARRYING_LINE_RE` filter and the
+ * same `<!-- phase-id-owner: ... -->` sanction as the single-segment rule.
+ * Returns [{ line, found }].
+ */
+function findLetterlessPhaseMirrorDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = LETTERLESS_PHASE_MIRROR_DRIFT_RE.exec(line);
+    if (!m) continue;
+    if (!PHASE_CARRYING_LINE_RE.test(line)) continue;
+    if (isSanctionedByPrecedingComment(lines, i, MD_OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+/**
+ * Scan the same three markdown roots as the single-segment rule for
+ * unsanctioned letter-less phase-regex mirrors. Returns [{ file, line, found }]
+ * with repo-relative paths.
+ */
+function scanMarkdownLetterlessPhaseMirror(root) {
+  const violations = [];
+  for (const dir of SINGLE_SEGMENT_SCAN_DIRS) {
+    for (const file of walkMd(path.join(root, dir), [])) {
+      const rel = path.relative(root, file);
+      let text;
+      try {
+        text = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const d of findLetterlessPhaseMirrorDrift(text)) {
+        violations.push({ file: rel, kind: 'letterless-phase-mirror', ...d });
+      }
+    }
+  }
+  return violations;
+}
+
+// #4748 (epic #4634): three shell shapes OUTSIDE the grammar-mirror family the
+// rules above police — consumers of a phase id rather than regexes for one —
+// each of which the letter axis broke while every rule above reported clean:
+//
+//   a. `PHASE_INT=${PHASE_NUMBER%%.*}` — the post-#4619 dot-only split. The
+//      `_INT` name it produces satisfies the shell-arithmetic rule's escape,
+//      but on `03A` the "integer" is `03A` and `$((10#03A))` aborts. The safe
+//      split stops at the first NON-digit: `${PHASE_NUMBER%%[!0-9]*}`.
+//   b. `[0-9]+\.?[0-9]*` (and `\d+\.?\d*`) — a digit-then-optional-dot
+//      extraction that is neither the bounded `(\.[0-9]+)?` shape the
+//      single-segment rule bans nor the unbounded `(\.[0-9]+)*` shape the
+//      letterless rule inspects, so both were blind to it. It captures `12`
+//      from `12A` and `23.1` from `23.1.2`, silently.
+//   c. `printf "%02d" "$PHASE_NUMBER"` — re-padding the whole id in shell.
+//      Rejects a letter id (prints `03`, exit 1) and misreads an already
+//      padded `08` as octal (prints `00`). Padding belongs to the canonical
+//      normalizer (`padded_phase` from init, or `normalizePhaseName`); the one
+//      legitimate shell pad is of an `_INT` value via `$((10#…))`.
+//
+// Same sanction as the other markdown rules: `<!-- phase-id-owner: … -->` on
+// the nearest preceding non-blank line. Same documented limit: a per-line
+// textual scan for the common accidental shape, not an obfuscated one.
+
+// a. `<name>_INT=${<phase-carrying>%%.*}` — the `_INT` destination is the
+//    discriminator, deliberately: it is the name the shell-arithmetic rule
+//    trusts as "already a safe integer", so a dot-only split INTO it is the
+//    exact promise this rule exists to check. A dot-only split into any other
+//    name is a different, legitimate operation — `PARENT_PHASE="${PHASE_NUMBER%%.*}"`
+//    (gap-closure-artifacts.md) wants everything before the first dot, letter
+//    included, and is correct. Widening to any destination was tried and flagged
+//    that site. The optional quote after `=` is the one spelling that site uses.
+const DOT_ONLY_INT_SPLIT_DRIFT_RE = /[A-Za-z0-9_]*_INT="?\$\{([A-Za-z0-9_]+)%%\\?\.\*\}/i;
+
+/**
+ * Pure: find every unsanctioned dot-only integer split of a phase-carrying
+ * variable in `text`. Skips full-line `#` comments (prose). Returns [{ line, found }].
+ */
+function findDotOnlyIntegerSplitDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*#/.test(line)) continue;
+    const m = DOT_ONLY_INT_SPLIT_DRIFT_RE.exec(line);
+    if (!m) continue;
+    if (!/phase/i.test(m[1])) continue;
+    if (isSanctionedByPrecedingComment(lines, i, MD_OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+// b. The digit-then-optional-dot shape, in both `[0-9]` and `\d` spellings.
+//    Anchored on the trailing `*` of the second digit class so a bare `[0-9]+`
+//    probe or a `[0-9]+\.[0-9]+` (mandatory-dot) shape is not matched.
+const LOOSE_DOTTED_PHASE_DRIFT_RE = /(?:\\{1,2}d|\[0-9\])\+\\{1,2}\.\?(?:\\{1,2}d|\[0-9\])\*/;
+
+/**
+ * Pure: find every unsanctioned `[0-9]+\.?[0-9]*`-shaped phase extraction in
+ * `text`, restricted to phase-carrying lines like its two sibling regex rules.
+ * Returns [{ line, found }].
+ */
+function findLooseDottedPhaseRegexDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = LOOSE_DOTTED_PHASE_DRIFT_RE.exec(line);
+    if (!m) continue;
+    if (!PHASE_CARRYING_LINE_RE.test(line)) continue;
+    if (isSanctionedByPrecedingComment(lines, i, MD_OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+// c. `printf "%Nd" …` / `printf '%0Nd' …` — any integer conversion, either
+//    quote, with or without the zero flag — whose argument list names a
+//    phase-carrying variable that is NOT an `_INT` (the `$((10#$PHASE_INT))`
+//    pad is the sanctioned shape). `%d` cannot parse a letter id under any
+//    width, so the flag is not the discriminator. Captures the first such name
+//    so the report says what was padded.
+const SHELL_PHASE_PRINTF_PAD_RE = /printf\s+(?:"%0?\d*d[^"]*"|'%0?\d*d[^']*')\s+(.*)$/;
+const SHELL_VAR_NAME_RE = /\$\{?([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/**
+ * Pure: find every unsanctioned `printf "%02d"` re-pad of a phase-carrying,
+ * non-`_INT` shell variable in `text`. Skips full-line `#` comments.
+ * Returns [{ line, found }].
+ */
+function findShellPhasePrintfPadDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*#/.test(line)) continue;
+    const m = SHELL_PHASE_PRINTF_PAD_RE.exec(line);
+    if (!m) continue;
+    const offender = [...m[1].matchAll(SHELL_VAR_NAME_RE)]
+      .map((v) => v[1])
+      .find((name) => /phase/i.test(name) && !/_int$/i.test(name));
+    if (!offender) continue;
+    if (isSanctionedByPrecedingComment(lines, i, MD_OWNER_RE)) continue;
+    out.push({ line: i + 1, found: `printf "%0…d" …$${offender}` });
+  }
+  return out;
+}
+
+/**
+ * Scan the shell roots (`gsd-core/workflows/**\/*.md`, `gsd-core/references/**\/*.md`)
+ * for the two shell-idiom rules (a, c) and the three regex roots (those plus
+ * `agents/**\/*.md`) for the extraction-shape rule (b). Returns
+ * [{ file, kind, line, found }] with repo-relative paths.
+ */
+function scanMarkdownLetterAxisConsumers(root) {
+  const violations = [];
+  const collect = (dirs, finder, kind) => {
+    for (const dir of dirs) {
+      for (const file of walkMd(path.join(root, dir), [])) {
+        const rel = path.relative(root, file);
+        let text;
+        try {
+          text = fs.readFileSync(file, 'utf8');
+        } catch {
+          continue;
+        }
+        for (const d of finder(text)) {
+          violations.push({ file: rel, kind, ...d });
+        }
+      }
+    }
+  };
+  collect(MD_SCAN_DIRS, findDotOnlyIntegerSplitDrift, 'dot-only-int-split');
+  collect(SINGLE_SEGMENT_SCAN_DIRS, findLooseDottedPhaseRegexDrift, 'loose-dotted-phase-regex');
+  collect(MD_SCAN_DIRS, findShellPhasePrintfPadDrift, 'shell-phase-printf-pad');
+  return violations;
+}
+
 // Authored TypeScript source only (the generated bin/lib/*.cjs mirror it).
 const SCAN_DIRS = ['src'];
 const SCAN_EXT = new Set(['.cts', '.ts', '.mts']);
@@ -523,6 +801,16 @@ function scanRepo(root) {
       for (const d of findBranchSlugFallbackDrift(text)) {
         violations.push({ file: rel, kind: 'branch-slug-fallback', ...d });
       }
+      // #4906 Phase 5 (#4984): heading-scan literal drift, owner file exempt
+      // via the shared `EXEMPT` check above. Pre-existing sites this phase
+      // could not reach (src/phase.cts, src/roadmap-parser.cts,
+      // src/planning-snapshot.cts) are grandfathered with a `// phase-id-owner:`
+      // sanction each, per ADR-4910 §8's census/grandfather/delete Phase 6 plan
+      // — the allowlist is those sanction comments, not a separate list here,
+      // and it is deleted entry-by-entry as each site migrates.
+      for (const d of findPhaseHeadingScanLiteralDrift(text)) {
+        violations.push({ file: rel, kind: 'phase-heading-scan-literal', ...d });
+      }
     }
   }
   return violations;
@@ -541,6 +829,8 @@ function scanAll(root) {
     ...scanRepo(root),
     ...scanMarkdownShellArith(root),
     ...scanMarkdownSingleSegmentPhaseRegex(root),
+    ...scanMarkdownLetterlessPhaseMirror(root),
+    ...scanMarkdownLetterAxisConsumers(root),
   ];
 }
 
@@ -567,8 +857,19 @@ function main() {
   process.stderr.write('near-variant) is banned outright in gsd-core/workflows/**/*.md,\n');
   process.stderr.write('gsd-core/references/**/*.md, and agents/**/*.md — widen it to `*` (unbounded\n');
   process.stderr.write('segments) or sanction with `<!-- phase-id-owner: <reason> -->`.\n');
+  process.stderr.write('A digit-only unbounded-segment phase regex `[0-9]+(\\.[0-9]+)*` on the same roots\n');
+  process.stderr.write('is missing the canonical letter axis (#4660) — widen to `[0-9]+[A-Z]?(\\.[0-9]+)*`\n');
+  process.stderr.write('or sanction with `<!-- phase-id-owner: <reason> -->`.\n');
+  process.stderr.write('Three letter-hostile consumers of a phase id are banned on the same roots (#4748):\n');
+  process.stderr.write('a dot-only integer split `X_INT=${PHASE%%.*}` (split at the first non-digit,\n');
+  process.stderr.write('`${PHASE%%[!0-9]*}`); a `[0-9]+\\.?[0-9]*` extraction (use `[0-9]+[A-Z]?(\\.[0-9]+)*`);\n');
+  process.stderr.write('and a `printf "%02d"` re-pad of a phase variable (bind init\'s `padded_phase`, or pad\n');
+  process.stderr.write('only an `_INT` via `$((10#…))`) — or sanction with `<!-- phase-id-owner: <reason> -->`.\n');
   process.stderr.write('A `.replace(\'{slug}\', ... || \'phase\')` fallback is banned outright (#4126) —\n');
   process.stderr.write('use `renderPhaseBranchName(` or sanction with\n');
+  process.stderr.write('`// phase-id-owner: <reason>` on the line directly above.\n');
+  process.stderr.write('A hand-rolled `#{2,4}\\s*Phase\\s+` heading-scan literal is banned (#4906 Phase 5) —\n');
+  process.stderr.write('use `buildPhaseHeadingScanRegex(` / `phaseHeadingPrefixSrcFor(` or sanction with\n');
   process.stderr.write('`// phase-id-owner: <reason>` on the line directly above:\n');
   for (const d of violations) {
     process.stderr.write(`  [${d.kind}] ${d.file}:${d.line}  ${d.found}\n`);
@@ -583,10 +884,18 @@ module.exports = {
   findBracketGrammarDrift,
   findNameValidityDrift,
   findBranchSlugFallbackDrift,
+  findPhaseHeadingScanLiteralDrift,
+  scanMarkdownPhaseHeadingScanLiteral,
   findShellPhaseArithDrift,
   findSingleSegmentPhaseRegexDrift,
+  findLetterlessPhaseMirrorDrift,
+  findDotOnlyIntegerSplitDrift,
+  findLooseDottedPhaseRegexDrift,
+  findShellPhasePrintfPadDrift,
   scanMarkdownShellArith,
   scanMarkdownSingleSegmentPhaseRegex,
+  scanMarkdownLetterlessPhaseMirror,
+  scanMarkdownLetterAxisConsumers,
   scanRepo,
   scanAll,
   countSelectorBaselines,
@@ -595,6 +904,11 @@ module.exports = {
   BRACKET_CODE_DRIFT_RE,
   NAME_VALIDITY_DRIFT_RE,
   BRANCH_SLUG_FALLBACK_DRIFT_RE,
+  PHASE_HEADING_SCAN_LITERAL_DRIFT_RE,
   SHELL_PHASE_ARITH_DRIFT_RE,
   SINGLE_SEGMENT_PHASE_DRIFT_RE,
+  LETTERLESS_PHASE_MIRROR_DRIFT_RE,
+  DOT_ONLY_INT_SPLIT_DRIFT_RE,
+  LOOSE_DOTTED_PHASE_DRIFT_RE,
+  SHELL_PHASE_PRINTF_PAD_RE,
 };