@opengsd/gsd-core 1.13.0 → 1.14.0

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

@@ -20,6 +20,34 @@
  * directly above). Sites that build their regex from `PHASE_NUMBER_TOKEN_SOURCE`
  * carry no literal grammar and pass automatically.
  *
+ * #4634 extends the same pattern with two more detectors:
+ *
+ * - name-validity-guard drift: `hasNameableContent(s)` in `src/roadmap-parser.cts`
+ *   is the sole owner of the "does this string have nameable content" predicate
+ *   (`/[\p{L}\p{N}]/u.test(s)`). Any other `src/**` file re-deriving that exact
+ *   character class (regex-literal or `new RegExp` template form) instead of
+ *   calling `hasNameableContent` is drift, sanctioned the same way as the token
+ *   and bracket rules (`// phase-id-owner:` on the nearest preceding non-blank
+ *   line), with a line-level escape for a line that already calls
+ *   `hasNameableContent(`.
+ *
+ * - shell phase-number-arithmetic ban: `$((10#...))` base-10-forced arithmetic
+ *   inside `gsd-core/workflows/**\/*.md` and `gsd-core/references/**\/*.md` breaks
+ *   on decimal or multi-segment phase ids and is banned outright. This scan runs
+ *   over markdown, not `.cts` source, so its sanction is an HTML comment on the
+ *   nearest preceding non-blank line: `<!-- phase-id-owner: <reason> -->`.
+ *
+ * - 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
+ *   `gsd/phase-08-phase` (#4126, now fixed via the shared renderPhaseBranchName
+ *   owner in phase-id.cts, consumed by both prior call sites). 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 calls `renderPhaseBranchName(`. Unlike the other
+ *   `.cts`-scanning rules, this one has no per-file exemption — it is a banned
+ *   anti-pattern everywhere, not a grammar with one legitimate owner site.
+ *
  * Detection is intentionally NARROW: only the contiguous canonical token
  * (`\d+[A-Z]?(?:\.\d+)*`, its `[A-Za-z]` and `[.-]` near-variants, in both
  * regex-literal `\d` and `new RegExp` template `\\d` escaping) is drift. Bare
@@ -82,6 +110,18 @@ const BRACKET_CODE_DRIFT_RE = /\[A-Z(?:a-z)?\]\[A-Z(?:a-z)?0-9_\]\*/;
 const BRACKET_OWNER_HINT =
   'BRACKET_PROJECT_CODE_SRC / BRACKET_ID_SRC / bracketMilestoneIntroSrcFor / BRACKET_MILESTONE_INTRO_CAPTURING_SRC';
 
+/**
+ * Pure: true if the nearest preceding non-blank line to `lines[i]` is a
+ * dedicated sanction comment matching `ownerRe`. Shared by every detector in
+ * this file so the "how do you sanction a finding" walk has one owner instead
+ * of four independent copies that could silently diverge.
+ */
+function isSanctionedByPrecedingComment(lines, i, ownerRe) {
+  let j = i - 1;
+  while (j >= 0 && lines[j].trim() === '') j--; // nearest preceding non-blank line
+  return j >= 0 && ownerRe.test(lines[j]);
+}
+
 /**
  * Pure: find every literal re-derivation of the canonical phase-number token in
  * `text` that is NOT sanctioned. A site is sanctioned when the nearest preceding
@@ -100,9 +140,7 @@ function findPhaseIdRegexDrift(text) {
     const m = TOKEN_DRIFT_RE.exec(line);
     if (!m) continue;
     if (line.includes(CANON_REF)) continue;
-    let j = i - 1;
-    while (j >= 0 && lines[j].trim() === '') j--; // nearest preceding non-blank line
-    if (j >= 0 && OWNER_RE.test(lines[j])) continue;
+    if (isSanctionedByPrecedingComment(lines, i, OWNER_RE)) continue;
     out.push({ line: i + 1, found: m[0] });
   }
   return out;
@@ -122,21 +160,249 @@ function findBracketGrammarDrift(text) {
   for (let i = 0; i < lines.length; i++) {
     const m = BRACKET_CODE_DRIFT_RE.exec(lines[i]);
     if (!m) continue;
-    let j = i - 1;
-    while (j >= 0 && lines[j].trim() === '') j--; // nearest preceding non-blank line
-    if (j >= 0 && OWNER_RE.test(lines[j])) continue;
+    if (isSanctionedByPrecedingComment(lines, i, OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+// #4634: the name-validity-guard grammar — `hasNameableContent(s)` in
+// `src/roadmap-parser.cts` is `/[\p{L}\p{N}]/u.test(s)`. Tolerates both the
+// regex-literal single-backslash form and the doubled-backslash template
+// form (`new RegExp('[\\p{L}\\p{N}]'`), mirroring how TOKEN_DRIFT_RE tolerates
+// both escapings.
+const NAME_VALIDITY_DRIFT_RE = /\[\\{1,2}p\{L\}\\{1,2}p\{N\}\]/;
+const NAME_VALIDITY_CANON_REF = 'hasNameableContent(';
+
+/**
+ * Pure: find every literal re-derivation of the canonical name-validity
+ * character class in `text` that is NOT sanctioned. Same sanction mechanism
+ * as the token/bracket rules — a dedicated `// phase-id-owner:` comment on
+ * the nearest preceding non-blank line — plus a line-level escape for a line
+ * that already calls `hasNameableContent(`. Returns [{ line, found }].
+ */
+function findNameValidityDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = NAME_VALIDITY_DRIFT_RE.exec(line);
+    if (!m) continue;
+    if (line.includes(NAME_VALIDITY_CANON_REF)) continue;
+    if (isSanctionedByPrecedingComment(lines, i, OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+// #4634: the branch-slug fallback anti-pattern (#4126) — a
+// `.replace('{slug}', ... || 'phase')` call silently falls back to the
+// literal string `'phase'` when a phase's slug can't be derived, producing a
+// non-identifying branch name like `gsd/phase-08-phase`. Now fixed at both
+// prior call sites (commands.cts, init.cts) via the shared
+// `renderPhaseBranchName` owner in phase-id.cts; this rule is the ratchet
+// against a THIRD site reintroducing the inline fallback. Deliberately
+// narrow: it requires the literal `'phase'` fallback on the same line as the
+// `{slug}` template token, so it does NOT match the sibling milestone-branch
+// fallback (`|| 'milestone'`), which is a different, correct-as-is case.
+const BRANCH_SLUG_FALLBACK_DRIFT_RE = /\{slug\}'.*\|\|\s*'phase'/;
+
+// The canonical fix is `renderPhaseBranchName(...)`. There is no "owner file"
+// for this rule the way there is for the token/bracket/name-validity
+// grammars above — it is a banned anti-pattern everywhere, so no per-file
+// exemption exists.
+const BRANCH_SLUG_FALLBACK_CANON_REF = 'renderPhaseBranchName(';
+
+/**
+ * Pure: find every unsanctioned branch-slug `|| 'phase'` fallback in `text`.
+ * Same sanction mechanism as the token/bracket/name-validity rules — a
+ * dedicated `// phase-id-owner:` comment on the nearest preceding non-blank
+ * line — plus a line-level escape for a line that already calls
+ * `renderPhaseBranchName(`. Returns [{ line, found }].
+ */
+function findBranchSlugFallbackDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = BRANCH_SLUG_FALLBACK_DRIFT_RE.exec(line);
+    if (!m) continue;
+    if (line.includes(BRANCH_SLUG_FALLBACK_CANON_REF)) continue;
+    if (isSanctionedByPrecedingComment(lines, i, OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+// #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
+// capture group grabs the token immediately inside the parens (after an
+// optional `$` and/or `{`, stripping a trailing `}`) so callers can inspect
+// *which* variable is being coerced, not merely that the substring occurred.
+//
+// Refined post-#4619: the original blunt "ban `$((10#` outright" version
+// over-fired on three false-positive classes once #4619's fix landed:
+//   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.
+//   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.
+// So a match is only a violation when the captured name contains `phase`
+// case-insensitively (it is phase-carrying) AND does not end in `_int`
+// case-insensitively (it has not already been reduced to a safe integer).
+const SHELL_PHASE_ARITH_DRIFT_RE = /\$\(\(\s*10#\$?\{?([A-Za-z0-9_]+)\}?/;
+
+// A markdown comment can't easily carry a `//` line, so the sanction for the
+// shell-arithmetic rule is an HTML comment on the nearest preceding non-blank
+// line: `<!-- phase-id-owner: <reason> -->`.
+const MD_OWNER_RE = /^\s*<!--.*phase-id-owner:/;
+
+/**
+ * Pure: find every unsanctioned `$((10#...))` base-10-forced shell arithmetic
+ * site in `text` that still coerces an un-reduced phase-carrying variable.
+ * Skips full-line `#` comments outright (pure prose mentioning the pattern,
+ * not executable code), and skips any captured variable name that either
+ * doesn't contain `phase` (never in scope — e.g. plan ids) or already ends
+ * in `_int` (the #4619-fix convention for "safely stripped to an integer").
+ * Sanctioned by an HTML comment `<!-- phase-id-owner: ... -->` on the
+ * nearest preceding non-blank line. Returns [{ line, found }].
+ */
+function findShellPhaseArithDrift(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_ARITH_DRIFT_RE.exec(line);
+    if (!m) continue;
+    const name = m[1];
+    if (!/phase/i.test(name)) continue;
+    if (/_int$/i.test(name)) continue;
+    if (isSanctionedByPrecedingComment(lines, i, MD_OWNER_RE)) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
+// #4634: the markdown scan roots — shell embedded in workflow/reference docs.
+const MD_SCAN_DIRS = [path.join('gsd-core', 'workflows'), path.join('gsd-core', 'references')];
+
+// #4568 (epic #4634): the single-segment phase regex ban scans a THIRD root,
+// `agents/**/*.md`, that the #4619 shell-arithmetic extension above never
+// touched — the gsd-code-fixer agent prompts re-derive the phase-number
+// grammar too. Reuses the same `walkMd` walker as the shell-arith scan.
+const SINGLE_SEGMENT_SCAN_DIRS = [...MD_SCAN_DIRS, 'agents'];
+
+/**
+ * Scan `gsd-core/workflows/**\/*.md` and `gsd-core/references/**\/*.md` for
+ * unsanctioned `$((10#...))` shell arithmetic. Returns [{ file, line, found }]
+ * with repo-relative paths.
+ */
+function scanMarkdownShellArith(root) {
+  const violations = [];
+  for (const dir of MD_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 findShellPhaseArithDrift(text)) {
+        violations.push({ file: rel, kind: 'shell-arith', ...d });
+      }
+    }
+  }
+  return violations;
+}
+
+// #4568 (epic #4634): ban the single-optional-dotted-segment phase regex
+// shape `[0-9]+(\.[0-9]+)?` (and its `\d`/doubled-backslash near-variants)
+// outright — this is exactly the grammar that hard-rejects or silently
+// truncates a 3-or-more-segment phase id like `23.1.2`. The canonical
+// grammar (`src/phase-id.cts`) uses the unbounded `(?:\.\d+)*` form; shell
+// snippets embedded in markdown can't import that module, so textual parity
+// (`*` in place of `?`) is the fix, and this rule is the ratchet against a
+// future site re-deriving the bounded form. Deliberately narrow to the
+// bounded ONE-optional-segment shape — the fixed `*`-form is not flagged.
+const SINGLE_SEGMENT_PHASE_DRIFT_RE =
+  /(?:\\{1,2}d|\[0-9\])\+\(\\{1,2}\.(?:\\{1,2}d|\[0-9\])\+\)\?/;
+
+// A single-segment shape like `[0-9]+(\.[0-9]+)?` is not inherently
+// phase-specific (e.g. it could describe a version number), so the rule
+// only fires on a line whose text plausibly carries a phase-number
+// variable — a case-insensitive `phase` substring anywhere on the line,
+// mirroring the phase-carrying filter `findShellPhaseArithDrift` already
+// applies to its own variable-name capture.
+const PHASE_CARRYING_LINE_RE = /phase/i;
+
+/**
+ * Pure: find every unsanctioned single-optional-dotted-segment phase regex
+ * in `text`, restricted to lines that plausibly carry a phase-number
+ * variable. Sanctioned by an HTML comment `<!-- phase-id-owner: ... -->` on
+ * the nearest preceding non-blank line (same convention as the shell-arith
+ * rule). Returns [{ line, found }].
+ */
+function findSingleSegmentPhaseRegexDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = SINGLE_SEGMENT_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;
 }
 
+/**
+ * Scan `gsd-core/workflows/**\/*.md`, `gsd-core/references/**\/*.md`, and
+ * `agents/**\/*.md` for unsanctioned single-optional-dotted-segment phase
+ * regexes. Returns [{ file, line, found }] with repo-relative paths.
+ */
+function scanMarkdownSingleSegmentPhaseRegex(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 findSingleSegmentPhaseRegexDrift(text)) {
+        violations.push({ file: rel, kind: 'single-segment-phase-regex', ...d });
+      }
+    }
+  }
+  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']);
 // The canonical owner defines the grammar; it is exempt by construction.
 const EXEMPT = new Set([path.join('src', 'phase-id.cts')]);
 
-function walk(dir, acc) {
+// #4634: the name-validity-guard rule owns a DIFFERENT file (roadmap-parser.cts
+// defines `hasNameableContent`), so it needs its own exemption set — the
+// token/bracket rules above must NOT start exempting roadmap-parser.cts too,
+// since it is not their owner.
+const NAME_VALIDITY_EXEMPT = new Set([path.join('src', 'roadmap-parser.cts')]);
+
+function walk(dir, acc, ext) {
+  const extSet = ext || SCAN_EXT;
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -147,14 +413,22 @@ function walk(dir, acc) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
-      walk(full, acc);
-    } else if (entry.isFile() && SCAN_EXT.has(path.extname(entry.name))) {
+      walk(full, acc, extSet);
+    } else if (entry.isFile() && extSet.has(path.extname(entry.name))) {
       acc.push(full);
     }
   }
   return acc;
 }
 
+// #4634: markdown scan for the shell phase-arithmetic ban walks a disjoint set
+// of roots/extensions from the src/**/*.cts scan above, so it gets its own thin
+// wrapper over the same `walk` rather than a parallel tree-walker.
+const MD_EXT = new Set(['.md']);
+function walkMd(dir, acc) {
+  return walk(dir, acc, MD_EXT);
+}
+
 // ─── #2761 M4: the heading-baseline selector census ────────────────────────
 //
 // `phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.<MODE>)` is the other half
@@ -239,23 +513,63 @@ function scanRepo(root) {
       for (const d of findBracketGrammarDrift(text)) {
         violations.push({ file: rel, kind: 'bracket', ...d });
       }
+      // #4634: name-validity-guard drift, exempting only its own owner file.
+      if (!NAME_VALIDITY_EXEMPT.has(rel)) {
+        for (const d of findNameValidityDrift(text)) {
+          violations.push({ file: rel, kind: 'name-validity', ...d });
+        }
+      }
+      // #4634: branch-slug fallback anti-pattern, exempt nowhere.
+      for (const d of findBranchSlugFallbackDrift(text)) {
+        violations.push({ file: rel, kind: 'branch-slug-fallback', ...d });
+      }
     }
   }
   return violations;
 }
 
+/**
+ * Scan EVERYTHING this seam guards: the `src/**\/*.cts` token/bracket/
+ * name-validity invariants (`scanRepo`) plus the markdown shell
+ * phase-arithmetic ban (`scanMarkdownShellArith`). This is what the CLI runs;
+ * `scanRepo` alone stays narrowly scoped to its original src/** contract so
+ * a live, separately-tracked markdown defect (#4619) cannot make the
+ * pinned-clean `scanRepo` test spuriously fail.
+ */
+function scanAll(root) {
+  return [
+    ...scanRepo(root),
+    ...scanMarkdownShellArith(root),
+    ...scanMarkdownSingleSegmentPhaseRegex(root),
+  ];
+}
+
 function main() {
   const root = path.join(__dirname, '..');
-  const violations = scanRepo(root);
+  const violations = scanAll(root);
   if (violations.length === 0) {
-    process.stdout.write('ok phase-id-drift: no unsanctioned phase-token or bracket-grammar re-derivations outside phase-id.cts\n');
+    process.stdout.write(
+      'ok phase-id-drift: no unsanctioned phase-token, bracket-grammar, name-validity, ' +
+        'branch-slug-fallback, or shell phase-arithmetic re-derivations found\n',
+    );
     return;
   }
   process.stderr.write('phase-id-drift: literal re-derivation(s) of a canonical grammar found.\n');
   process.stderr.write(`Build the regex from phase-id.cjs \`${CANON_REF}\` (or phaseMarkdownRegexSource for a\n`);
   process.stderr.write(`known number) for the phase-number token, or from ${BRACKET_OWNER_HINT}\n`);
-  process.stderr.write('for the bracket grammar — or sanction the site with a dedicated\n');
-  process.stderr.write('`// phase-id-owner: <reason>` comment on the line directly above the regex:\n');
+  process.stderr.write('for the bracket grammar, or call `hasNameableContent(` (src/roadmap-parser.cts) for\n');
+  process.stderr.write('the name-validity predicate — or sanction the site with a dedicated\n');
+  process.stderr.write('`// phase-id-owner: <reason>` comment on the line directly above the regex.\n');
+  process.stderr.write('`$((10#...))` base-10-forced shell arithmetic is banned outright in\n');
+  process.stderr.write('gsd-core/workflows/**/*.md and gsd-core/references/**/*.md — sanction with\n');
+  process.stderr.write('`<!-- phase-id-owner: <reason> -->` on the line directly above.\n');
+  process.stderr.write('The single-optional-dotted-segment phase regex `[0-9]+(\\.[0-9]+)?` (or its \\d\n');
+  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 `.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');
   for (const d of violations) {
     process.stderr.write(`  [${d.kind}] ${d.file}:${d.line}  ${d.found}\n`);
   }
@@ -267,9 +581,20 @@ if (require.main === module) main();
 module.exports = {
   findPhaseIdRegexDrift,
   findBracketGrammarDrift,
+  findNameValidityDrift,
+  findBranchSlugFallbackDrift,
+  findShellPhaseArithDrift,
+  findSingleSegmentPhaseRegexDrift,
+  scanMarkdownShellArith,
+  scanMarkdownSingleSegmentPhaseRegex,
   scanRepo,
+  scanAll,
   countSelectorBaselines,
   scanSelectorBaselines,
   TOKEN_DRIFT_RE,
   BRACKET_CODE_DRIFT_RE,
+  NAME_VALIDITY_DRIFT_RE,
+  BRANCH_SLUG_FALLBACK_DRIFT_RE,
+  SHELL_PHASE_ARITH_DRIFT_RE,
+  SINGLE_SEGMENT_PHASE_DRIFT_RE,
 };

package/scripts/lint-response-language-coverage.cjs

@@ -22,8 +22,10 @@
  * explanations" describes the gap rather than closing it. Coverage therefore
  * requires a narration-class token as well — see `NARRATION_CLASS_RE`.
  *
- * A workflow FRAGMENT (`<workflow>/<modes|steps|templates>/<name>.md`, the shape
- * the #1671 fragment epic extracts) additionally passes when its parent workflow
+ * A workflow FRAGMENT (`<workflow>/<modes|steps|templates|detail>/<name>.md`, the
+ * shape the #1671 fragment epic extracts — `detail/` is the fourth such
+ * subdirectory kind, added by the #4403/ADR-4139 spine+detail split) additionally
+ * passes when its parent workflow
  * names that exact fragment path and is itself covered — see
  * `inheritsParentCoverage`, which proves the inheritance per file instead of
  * granting it to a directory.
@@ -124,7 +126,11 @@ const EXACT_INLINE_DIRECTIVE_WORKFLOWS = new Set([
 // failure for a quiet assumption; as it stands, extracting a fragment-of-a-
 // fragment without pinning it turns the lint RED, which is the correct answer
 // and names the file to fix.
-const FRAGMENT_DIRS = new Set(['modes', 'steps', 'templates']);
+// `detail` (ADR-4139 §6 Decision 6 / #4403) is the fourth fragment-directory kind,
+// alongside modes/steps/templates from #1671: a spine's `detail/<part>.md` is
+// reached the same way -- a `read and execute` stub in the top-level parent -- so
+// it inherits coverage through the exact same mechanism, not a parallel one.
+const FRAGMENT_DIRS = new Set(['modes', 'steps', 'templates', 'detail']);
 const DIRECTIVE_ACTION_RE = /\b(?:apply|present|render|respond|translate|use|write|must|should)\b/i;
 const USER_OUTPUT_RE = /\b(?:explanations?|language|narration|outputs?|prompts?|prose|questions?|templates?|user-facing)\b/i;
 // The defect #2529 reports is NARRATION, not the question/answer surface: a

package/scripts/lint-source-test-name-collision.cjs

@@ -114,7 +114,7 @@ function toPosix(p) {
 function isGeneratedOutput(relPath) {
   const posixRel = toPosix(relPath);
   return GENERATED_OUTPUT_PREFIXES.some(
-    (prefix) => posixRel === prefix || posixRel.startsWith(`${prefix}/`)
+    (prefix) => posixRel === prefix || posixRel.startsWith(`${prefix}/`) // allow-handrolled-containment: scan-exclusion membership test against a fixed generated-output prefix list, not a filesystem root-confinement gate
   );
 }
 

package/scripts/lint-test-file-count.allowlist.json

@@ -123,6 +123,7 @@
         "state-prune.test.cjs",
         "state-rebuild-cli.test.cjs",
         "state-rebuild.test.cjs",
+        "state-todos-render.test.cjs",
         "state-write-path-drift-guard.test.cjs",
         "state.test.cjs"
       ],

package/scripts/lint-vendored-deps.cjs

@@ -161,8 +161,24 @@ function compareFiles(relA, relB) {
  * @param {string} spec
  * @returns {string}
  */
+const PIN_OPERATOR_RE = /^(\^|~|>=|<=|>|<|=)?/;
+
 function stripRangeOperator(spec) {
-  return String(spec || '').trim().replace(/^[\^~]|^>=|^<=|^>|^<|^=/, '').trim();
+  return String(spec || '').trim().replace(PIN_OPERATOR_RE, '').trim();
+}
+
+/**
+ * The leading range-operator token (if any) a package.json dependency spec
+ * was written with — the inverse half of stripRangeOperator, needed by
+ * `fixRow` to rebuild a pin (`<same operator>` + `<new version>`) that
+ * preserves the author's original range style instead of collapsing every
+ * pin to an exact version.
+ * @param {string} spec
+ * @returns {string} the operator (e.g. "^", "~", ">="), or "" for an exact pin
+ */
+function pinOperatorPrefix(spec) {
+  const m = String(spec || '').trim().match(PIN_OPERATOR_RE);
+  return (m && m[1]) || '';
 }
 
 /**
@@ -211,12 +227,40 @@ function checkHandAuthoredTwin(row) {
   return findings;
 }
 
+/**
+ * Read a row's pin state: the package.json devDependencies spec for
+ * `row.name` and, if `node_modules/<row.name>/package.json` exists, its
+ * installed version. Shared by checkRow (compares) and fixRow (rewrites) so
+ * the two can never silently diverge on how a pin is read.
+ * @param {VendoredPackage} row
+ * @param {string} [pkgRoot] Override for testing -- defaults to the real repo ROOT. Lets a
+ *   test point fixRow's pin-rewrite at an isolated temp package.json instead of writing the
+ *   real, shared one, which other concurrently-running node --test files read at module
+ *   top-level (the same race class already fixed for the vendored .cjs copy).
+ * @returns {{pinnedSpec: string | undefined, installedVersion: string | undefined}}
+ */
+function readPinState(row, pkgRoot = ROOT) {
+  const pkgPath = path.join(pkgRoot, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const pinnedSpec = pkg.devDependencies && pkg.devDependencies[row.name];
+  const installedPkgPath = path.join(pkgRoot, 'node_modules', row.name, 'package.json');
+  let installedVersion;
+  if (fs.existsSync(installedPkgPath)) {
+    installedVersion = JSON.parse(fs.readFileSync(installedPkgPath, 'utf8')).version;
+  }
+  return { pinnedSpec, installedVersion };
+}
+
 /**
  * Run all applicable freshness checks for one vendored package row.
  * @param {VendoredPackage} row
+ * @param {string} [pkgRoot] Override for testing -- defaults to the real repo ROOT. Lets a
+ *   test point fixRow's pin-rewrite at an isolated temp package.json instead of writing the
+ *   real, shared one, which other concurrently-running node --test files read at module
+ *   top-level (the same race class already fixed for the vendored .cjs copy).
  * @returns {string[]} findings (empty when the row is fresh)
  */
-function checkRow(row) {
+function checkRow(row, pkgRoot = ROOT) {
   const findings = [];
 
   const cjsDrift = compareFiles(row.vendoredCjs, row.upstreamCjs);
@@ -235,31 +279,96 @@ function checkRow(row) {
     findings.push(...checkHandAuthoredTwin(row));
   }
 
-  const pkgPath = path.join(ROOT, 'package.json');
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-  const pinnedSpec = pkg.devDependencies && pkg.devDependencies[row.name];
+  const { pinnedSpec, installedVersion } = readPinState(row, pkgRoot);
   if (!pinnedSpec) {
     findings.push(`package.json devDependencies.${row.name} is missing`);
+  } else if (installedVersion === undefined) {
+    findings.push(`node_modules/${row.name}/package.json does not exist (run npm install)`);
   } else {
-    const installedPkgPath = path.join(ROOT, 'node_modules', row.name, 'package.json');
-    if (!fs.existsSync(installedPkgPath)) {
-      findings.push(`node_modules/${row.name}/package.json does not exist (run npm install)`);
-    } else {
-      const installed = JSON.parse(fs.readFileSync(installedPkgPath, 'utf8'));
-      const pinned = stripRangeOperator(pinnedSpec);
-      if (pinned !== installed.version) {
-        findings.push(
-          `package.json devDependencies.${row.name} ("${pinnedSpec}" -> "${pinned}") != `
-            + `node_modules/${row.name}/package.json version ("${installed.version}")`,
-        );
-      }
+    const pinned = stripRangeOperator(pinnedSpec);
+    if (pinned !== installedVersion) {
+      findings.push(
+        `package.json devDependencies.${row.name} ("${pinnedSpec}" -> "${pinned}") != `
+          + `node_modules/${row.name}/package.json version ("${installedVersion}")`,
+      );
     }
   }
 
   return findings;
 }
 
+/**
+ * Mechanically resolve a vendored package's byte/pin drift: copy the
+ * upstream .cjs (and, for `upstream-verbatim` rows, the .d.cts twins) over
+ * the vendored copy, and bump the package.json pin to the installed
+ * version, preserving the original range-operator prefix. Then re-runs
+ * `checkRow` and returns whatever findings remain.
+ *
+ * This NEVER hand-edits a `hand-authored` twin (e.g. js-yaml.d.cts) — that
+ * file encodes a human's deliberate judgment about which exports are safe
+ * to expose, and only a human can tell whether a declared-export-missing
+ * finding is mechanical drift or a real upstream API break. If one remains
+ * after this runs, that is by design: the caller must not treat it as
+ * fixed.
+ * @param {VendoredPackage} row
+ * @param {string} [pkgRoot] Override for testing -- defaults to the real repo ROOT. Lets a
+ *   test point fixRow's pin-rewrite at an isolated temp package.json instead of writing the
+ *   real, shared one, which other concurrently-running node --test files read at module
+ *   top-level (the same race class already fixed for the vendored .cjs copy).
+ * @returns {string[]} findings remaining after the fix (empty when fully resolved)
+ */
+function fixRow(row, pkgRoot = ROOT) {
+  fs.copyFileSync(resolvePath(row.upstreamCjs), resolvePath(row.vendoredCjs));
+
+  if (row.twinKind === 'upstream-verbatim' && row.upstreamDts) {
+    if (row.vendoredDts) fs.copyFileSync(resolvePath(row.upstreamDts), resolvePath(row.vendoredDts));
+    if (row.srcTwin) fs.copyFileSync(resolvePath(row.upstreamDts), resolvePath(row.srcTwin));
+  }
+
+  const { pinnedSpec, installedVersion } = readPinState(row, pkgRoot);
+  if (pinnedSpec && installedVersion !== undefined) {
+    const newPin = `${pinOperatorPrefix(pinnedSpec)}${installedVersion}`;
+    if (newPin !== pinnedSpec) {
+      const pkgPath = path.join(pkgRoot, 'package.json');
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      pkg.devDependencies[row.name] = newPin;
+      fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    }
+  }
+
+  return checkRow(row, pkgRoot);
+}
+
 function main() {
+  if (process.argv.includes('--fix')) {
+    /** @type {Record<string, string[]>} */
+    const remaining = {};
+    for (const row of VENDORED) {
+      const findings = fixRow(row);
+      if (findings.length > 0) remaining[row.name] = findings;
+    }
+
+    const names = VENDORED.map((row) => row.name).join(', ');
+
+    if (Object.keys(remaining).length === 0) {
+      process.stdout.write(
+        `ok lint-vendored-deps --fix: gsd-core/bin/lib/vendor/{${names}} refreshed and now match node_modules and their pinned versions\n`,
+      );
+      return 0;
+    }
+
+    const detail = Object.entries(remaining)
+      .map(([name, findings]) => `  ${name}:\n${findings.map((f) => `    ${f}`).join('\n')}`)
+      .join('\n');
+    throw new ExitError(
+      1,
+      `lint-vendored-deps --fix: mechanical drift refreshed, but the following row(s)\n`
+        + 'still have findings that --fix cannot resolve automatically — these need a\n'
+        + 'human, not just a re-run of --fix:\n'
+        + detail,
+    );
+  }
+
   const findings = [];
   for (const row of VENDORED) {
     findings.push(...checkRow(row));
@@ -288,9 +397,11 @@ if (require.main === module) runMain(main);
 module.exports = {
   compareFiles,
   stripRangeOperator,
+  pinOperatorPrefix,
   VENDORED,
   buildRefreshCommand,
   checkRow,
+  fixRow,
   declaredValueExports,
   checkHandAuthoredTwin,
   resolvePath,