@opengsd/gsd-core 1.9.1 → 1.11.0

package/scripts/lint-completion-ratio-drift.cjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Anti-divergence drift guard for the completion-RATIO seam
+ * (epic #3180, ADR-3180 "Planning Semantic Model Single Owner").
+ *
+ * `src/phase-lifecycle.cts`'s `clampPercent(completed, total)` /
+ * `clampPercentFromFraction(fraction)` are the SINGLE canonical owner of
+ * "turn a completed/total pair into an integer completion percentage,
+ * clamped to 100". Until just before this guard was added, the identical
+ * expression `total > 0 ? Math.min(100, Math.round((completed / total) * 100)) : 0`
+ * was hand-inlined at six call sites across five modules while the owner sat
+ * exported and unused by them — the exact ADR-3180 divergence class, in a
+ * derivation the epic had not previously named. Those six sites have been
+ * migrated onto the owner; this guard is what stops a seventh copy.
+ *
+ * Per ADR-3180 Decision 4(a) this guard discovers call sites by SCANNING THE
+ * WHOLE `src/` TREE, not by consulting an allowlist of known files — an
+ * allowlist only measures re-derivations in files someone remembered to
+ * list, and a new call site added anywhere else would sail through silently.
+ *
+ * DETECTION. A line is a re-derivation when ALL THREE hold, on that ONE
+ * source line:
+ *   (a) it calls one of the `Math.round(`/`Math.floor(`/`Math.trunc(`/
+ *       `Math.ceil(` rounding family — MATH_ROUND_FAMILY_RE;
+ *   (b) it SCALES by 100 — a `*` followed by optional whitespace then `100`
+ *       at a word boundary — SCALE_100_RE;
+ *   (c) it contains a DIVISION — an identifier/closing-bracket, optional
+ *       whitespace, `/`, optional whitespace, an identifier/opening-paren —
+ *       DIVISION_RE — AND that division's index in the line is EARLIER than
+ *       the index of the `* 100` scale from (b).
+ *
+ * Clause (c)'s ORDERING requirement is the whole precision of this guard.
+ * `(a / b) * 100` — divide FIRST, scale SECOND — is a percentage: the
+ * completed/total-derived shape this guard exists to catch. `Math.round(n *
+ * 100) / 100` — scale FIRST, divide SECOND — is a completely unrelated
+ * idiom (2-decimal-place rounding of an already-fractional value) that
+ * happens to share both a rounding call and a `* 100` token; it appears in
+ * this repo at `src/eval.cts` and `src/commands.cts` and MUST stay
+ * unflagged. Comparing leftmost-match indices (rather than merely testing
+ * "does a division exist anywhere on the line") is what tells the two
+ * idioms apart: this guard finds the EARLIEST division and the EARLIEST
+ * `* 100` scale on the line and requires divIdx < scaleIdx, so a line with a
+ * scale-then-divide shape (divIdx > scaleIdx, or no division at all) never
+ * matches, regardless of what else is on the line.
+ *
+ * `Math.floor(Math.random() * 100)` carries (a) and (b) but no division
+ * anywhere on the line (DIVISION_RE finds nothing, divIdx === -1) and is
+ * correctly excluded by clause (c) alone.
+ *
+ * `src/context-utilization.cts`'s `Math.min(Math.round(ratio * 100), 100)`
+ * is OUT OF SCOPE BY DOMAIN, not by exemption: it scales an
+ * ALREADY-COMPUTED fraction (`ratio`, a context-window utilization figure —
+ * unrelated to `.planning/` phase/plan completion) and there is no division
+ * anywhere on that line either, so clause (c) excludes it the same way as
+ * the `Math.random()` case above; it needs no FUNCTION_SCOPED_EXEMPTIONS
+ * entry because it was never going to match.
+ *
+ * Every regex below is small, bounded, and has no nested/overlapping
+ * quantifiers — each character class is followed by a fixed literal or a
+ * single `\s*` run bounded by the next required literal, so there is
+ * nothing for a backtracking engine to explore more than linearly.
+ * `npm run lint:ci` runs CodeQL js/redos over this repo; mirrors the
+ * ReDoS discipline of `lint-plan-count-drift.cjs` / `lint-milestone-window-drift.cjs`.
+ *
+ * The tree-walk / root-confinement / sanitizer machinery is SHARED with the
+ * sibling drift guards via `scripts/lib/drift-scan.cjs` (ADR-3180 Decision 4)
+ * — see that module for the `isInsideRoot` case-sensitivity note and the
+ * `walk` symlink-confinement rationale. This guard's detection shape needs
+ * no regex-LITERAL extraction (unlike the milestone-window guard), so it
+ * does not use `readRegexLiteralAt`; the reported fragment is simply the
+ * trimmed source line, bounded to MAX_REGEX_LITERAL_LEN characters.
+ *
+ * KNOWN, ACCEPTED limits of a per-line textual scan (same tradeoff the
+ * sibling drift guards document): a re-derivation whose division and
+ * `Math.round`/scale are split across two DIFFERENT lines with no single
+ * line carrying all three tokens is not caught by this narrow shape, nor is
+ * one routed through a helper that itself performs the division one call
+ * away from the rounding. That is left to code review, not this regex.
+ */
+
+const path = require('node:path');
+const driftScan = require('./lib/drift-scan.cjs');
+const { MAX_REGEX_LITERAL_LEN, sanitizeForReport, scanTree } = driftScan;
+
+// (a) The `Math.round`/`Math.floor`/`Math.trunc`/`Math.ceil` rounding family,
+// called with an open paren. `\b` before `Math` keeps this from matching
+// inside a longer identifier (e.g. `fooMath.round(` never occurs in this
+// codebase, but the boundary costs nothing and documents intent).
+const MATH_ROUND_FAMILY_RE = /\bMath\.(?:round|floor|trunc|ceil)\(/;
+
+// (b) A `* 100` scale — a `*` operator, optional whitespace, then the
+// literal digits `100` at a word boundary (so `*1000` or `*100.5` do not
+// match a bare `100` inside a longer number).
+const SCALE_100_RE = /\*\s*100\b/;
+
+// (c) A division: an identifier character/closing-bracket (the end of the
+// numerator expression), optional whitespace, `/`, optional whitespace, an
+// identifier character/opening-paren (the start of the denominator
+// expression). Deliberately does not try to distinguish this from a regex
+// literal or a `//` comment — the detection window is a Math.round-family
+// call on the same line, which neither idiom co-occurs with in practice, and
+// keeping the class small is what keeps the regex non-backtracking.
+const DIVISION_RE = /[A-Za-z0-9_$)\]]\s*\/\s*[A-Za-z0-9_$(]/;
+
+// 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 ratio-to-percent grammar. It is NOT
+// exempt as a whole file (ADR-3180 Decision 4(a) forbids bare file
+// allowlists) — it is scanned like every other file in SCAN_DIRS, and only
+// the two named functions below are exempt, each for a documented reason.
+// An unrelated re-derivation added elsewhere in this same file (including a
+// future one) is still caught.
+const OWNER_FILE = path.join('src', 'phase-lifecycle.cts');
+
+// Per ADR-3180 Decision 4(a): function-scoped, not a bare file allowlist.
+//   - clampPercentFromFraction: `Math.min(100, Math.round(fraction * 100))`
+//     IS the canonical fraction-to-percent kernel this guard exists to
+//     protect, not a copy of it — every other caller in the tree is
+//     expected to CALL this function rather than re-express its body.
+//   - clampPercent: the canonical count-shaped entry point; it delegates to
+//     `clampPercentFromFraction(completed / total)` rather than computing
+//     `Math.round(...)` itself, so it is exempted for the same reason even
+//     though its own line does not currently carry a Math.round-family call.
+const FUNCTION_SCOPED_EXEMPTIONS = new Map([[OWNER_FILE, new Set(['clampPercent', 'clampPercentFromFraction'])]]);
+
+// Optional `export ` modifier, matching the sibling guards' convention —
+// only a column-0 top-level `function` declaration updates the
+// current-function tracker.
+const TOP_LEVEL_FUNCTION_RE = /^(?:export\s+)?function\s+([A-Za-z0-9_]+)\s*\(/;
+
+/**
+ * Pure: find every unsanctioned completion-ratio re-derivation in `text`.
+ * `relPath` is the repo-relative path, used both to report file:line and to
+ * apply the narrow, function-scoped owner exemptions above.
+ * Returns [{ line, found }].
+ */
+function findCompletionRatioDrift(text, relPath) {
+  const out = [];
+  const lines = text.split('\n');
+  const exemptFunctions = FUNCTION_SCOPED_EXEMPTIONS.get(relPath) || null;
+  let currentFunction = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fnMatch = TOP_LEVEL_FUNCTION_RE.exec(line);
+    if (fnMatch) currentFunction = fnMatch[1];
+
+    if (!MATH_ROUND_FAMILY_RE.test(line)) continue;
+    const scaleIdx = line.search(SCALE_100_RE);
+    if (scaleIdx === -1) continue;
+    const divIdx = line.search(DIVISION_RE);
+    if (divIdx === -1 || divIdx >= scaleIdx) continue;
+
+    if (exemptFunctions && exemptFunctions.has(currentFunction)) continue;
+
+    out.push({ line: i + 1, found: line.trim().slice(0, MAX_REGEX_LITERAL_LEN) });
+  }
+  return out;
+}
+
+/**
+ * Scan the authored source tree and return every unsanctioned re-derivation,
+ * each annotated with the repo-relative file path.
+ */
+function scanRepo(root) {
+  return scanTree({
+    root,
+    scanDirs: SCAN_DIRS,
+    scanExt: SCAN_EXT,
+    onFile(rel, text) {
+      // `rel` is already the REAL (canonical) path (scanTree resolves
+      // symlinks before calling onFile), so this — and
+      // FUNCTION_SCOPED_EXEMPTIONS above, also keyed on `rel` — match
+      // consistently regardless of which symlink reached the file.
+      return findCompletionRatioDrift(text, rel).map((d) => ({ file: rel, ...d }));
+    },
+  });
+}
+
+function main() {
+  const root = path.join(__dirname, '..');
+  const violations = scanRepo(root);
+  if (violations.length === 0) {
+    process.stdout.write('ok completion-ratio-drift: no unsanctioned completed/total percent re-derivations outside phase-lifecycle.cts\n');
+    return;
+  }
+  process.stderr.write('completion-ratio-drift: independent re-derivation(s) of completed/total percent found.\n');
+  process.stderr.write('Use src/phase-lifecycle.cjs `clampPercent(completed, total)` (or `clampPercentFromFraction(fraction)`\n');
+  process.stderr.write('when you already hold a fraction) instead of re-deriving Math.round((completed / total) * 100):\n');
+  for (const d of violations) {
+    // `d.file` is exactly as attacker-controlled as `d.found`: a repo can
+    // legally track a filename containing control bytes / bidi overrides,
+    // and it is a fork-PR-authored value reaching a CI log the same way the
+    // matched line text does — sanitize it at the same reporting boundary.
+    process.stderr.write(`  ${sanitizeForReport(d.file)}:${d.line}  ${sanitizeForReport(d.found)}\n`);
+  }
+  process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  findCompletionRatioDrift,
+  scanRepo,
+  MATH_ROUND_FAMILY_RE,
+  SCALE_100_RE,
+  DIVISION_RE,
+  OWNER_FILE,
+  FUNCTION_SCOPED_EXEMPTIONS,
+  MAX_REGEX_LITERAL_LEN,
+};

package/scripts/lint-default-flip-documentation.cjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-default-flip-documentation.cjs — DEFECT.DEFAULT-FLIP-DOCUMENTATION
+ * (CONTEXT.md).
+ *
+ * ## Why
+ *
+ * A PR flips a config default but doesn't call out the migration semantics
+ * (when the new default takes effect; existing configs vs new configs; what
+ * the opt-back-in looks like — #3309, the v2 default flip from mid-flight to
+ * end-of-phase).
+ *
+ * ## Scope (deliberately narrower than the full DEFECT.detect clause)
+ *
+ * The DEFECT text names two surfaces: `CONFIG_DEFAULTS` and
+ * `buildNewProjectConfig`. This check covers ONLY the single-source-of-truth
+ * defaults manifest, `gsd-core/bin/shared/config-defaults.manifest.json`
+ * (what `CONFIG_DEFAULTS` in `src/configuration.cts` / `src/config.cts`
+ * actually loads at runtime) — because it is pure JSON, a resolved
+ * key→value-map diff between base and head is trivially reliable: no line
+ * movement, reordering, or refactor can ever produce a false "value changed"
+ * verdict, only an actual value change can.
+ *
+ * `buildNewProjectConfig`'s `hardcoded` object literal in `src/config.cts`
+ * is DELIBERATELY OUT OF SCOPE here. It mixes literal values with
+ * environment-derived branches (`hasBraveSearch`, etc.) and spreads of
+ * `CONFIG_DEFAULTS.*` — there is no reliable way to compute its *resolved*
+ * value map from source text alone without executing the compiled module at
+ * both refs, and a line/AST-level diff of that literal would inherit exactly
+ * the false-positive risk (a harmless refactor that moves or restructures
+ * the literal reads as a "flip") this check exists to avoid. Per the audit's
+ * own risk callout, a noisy check here is worse than no check — the
+ * `buildNewProjectConfig` half of the DEFECT stays prose-only.
+ *
+ * ## What this checks
+ *
+ * If any *value* differs between the base and head resolved manifest
+ * key→value maps (additions/removals alone don't count as a "flip" — the
+ * symptom is specifically about an EXISTING default changing), fail unless
+ * the PR body contains a `## Breaking Changes` (or `# Breaking Changes`)
+ * heading.
+ *
+ * Needs a PR event payload (`GITHUB_EVENT_PATH`) to read the PR body — this
+ * is a dedicated-workflow check (like `lint-canary-version-leak.cjs`), not a
+ * `lint:ci` member, since a local/push run has no PR body to check against.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const cp = require('node:child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.join(__dirname, '..');
+const MANIFEST_PATH = path.join('gsd-core', 'bin', 'shared', 'config-defaults.manifest.json');
+const BREAKING_CHANGES_RE = /^#{1,6}\s*Breaking Changes\b/im;
+
+/**
+ * Pure: flatten a nested plain-object JSON value into dot-path
+ * `{ "a.b.c": value }` leaves. Arrays and primitives are leaves (compared by
+ * JSON.stringify equality, never recursed into) so array reordering reads as
+ * one value change, not N.
+ * @param {unknown} value
+ * @param {string} prefix
+ * @param {Record<string, unknown>} out
+ * @returns {Record<string, unknown>}
+ */
+function flatten(value, prefix = '', out = {}) {
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    for (const [key, v] of Object.entries(value)) {
+      flatten(v, prefix ? `${prefix}.${key}` : key, out);
+    }
+  } else {
+    out[prefix] = value;
+  }
+  return out;
+}
+
+/**
+ * Pure: given two resolved (already-flattened) key→value maps, return the
+ * keys present in BOTH whose value differs. Additions/removals are NOT
+ * "flips" — a brand-new default has no prior behavior to contradict.
+ * @param {Record<string, unknown>} baseMap
+ * @param {Record<string, unknown>} headMap
+ * @returns {{ key: string, from: unknown, to: unknown }[]}
+ */
+function findDefaultValueChanges(baseMap, headMap) {
+  const changes = [];
+  for (const key of Object.keys(baseMap)) {
+    if (!Object.prototype.hasOwnProperty.call(headMap, key)) continue;
+    if (JSON.stringify(baseMap[key]) !== JSON.stringify(headMap[key])) {
+      changes.push({ key, from: baseMap[key], to: headMap[key] });
+    }
+  }
+  return changes;
+}
+
+/**
+ * Pure verdict: given the detected default-value changes and the PR body,
+ * decide pass/fail.
+ * @param {{ key: string, from: unknown, to: unknown }[]} changes
+ * @param {string} prBody
+ * @returns {{ ok: boolean, changes: object[] }}
+ */
+function evaluateDefaultFlipDoc(changes, prBody) {
+  if (changes.length === 0) return { ok: true, changes: [] };
+  if (BREAKING_CHANGES_RE.test(prBody || '')) return { ok: true, changes };
+  return { ok: false, changes };
+}
+
+/**
+ * Read and JSON.parse the manifest at a given git ref. Returns `{}` when the
+ * file doesn't exist at that ref (new file, or ref predates it) — that is
+ * not a "flip", it's an addition, and is silently excluded by
+ * findDefaultValueChanges's both-sides-present requirement anyway.
+ * @param {string} root
+ * @param {string} ref
+ * @returns {Record<string, unknown>}
+ */
+function readManifestAtRef(root, ref) {
+  let raw;
+  try {
+    raw = cp.execFileSync('git', ['show', `${ref}:${MANIFEST_PATH.split(path.sep).join('/')}`], {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 15000,
+    });
+  } catch {
+    return {};
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new ExitError(2, `lint-default-flip-documentation: ${ref}:${MANIFEST_PATH} is not valid JSON: ${e.message}`);
+  }
+}
+
+function readPrBody() {
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  if (!eventPath || !fs.existsSync(eventPath)) return null;
+  try {
+    const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+    return typeof event.pull_request?.body === 'string' ? event.pull_request.body : '';
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const prBody = readPrBody();
+  if (prBody === null) {
+    console.log('lint-default-flip-documentation: no PR event payload (not a pull_request run), skipping');
+    return;
+  }
+
+  const baseRef = `origin/${process.env.GITHUB_BASE_REF || 'next'}`; // #2988
+  const baseMap = flatten(readManifestAtRef(ROOT, baseRef));
+  const headMap = flatten(readManifestAtRef(ROOT, 'HEAD'));
+  const changes = findDefaultValueChanges(baseMap, headMap);
+  const verdict = evaluateDefaultFlipDoc(changes, prBody);
+
+  if (!verdict.ok) {
+    const detail = verdict.changes
+      .map((c) => `  ${c.key}: ${JSON.stringify(c.from)} → ${JSON.stringify(c.to)}`)
+      .join('\n');
+    throw new ExitError(
+      1,
+      'lint-default-flip-documentation: this PR changes an existing default value in\n'
+        + 'config-defaults.manifest.json (DEFECT.DEFAULT-FLIP-DOCUMENTATION) but the PR body has no\n'
+        + '`## Breaking Changes` section. Add one covering: (a) when the new default takes effect\n'
+        + '(config-set, fresh project, regenerated config), (b) the opt-back-in command\n'
+        + '(`gsd config-set <key> <old-value>`), (c) effect on in-flight artifacts. Changed default(s):\n'
+        + detail,
+    );
+  }
+  console.log(
+    changes.length === 0
+      ? 'ok lint-default-flip-documentation: no default value changed'
+      : `ok lint-default-flip-documentation: ${changes.length} default value change(s), PR body documents Breaking Changes`,
+  );
+}
+
+module.exports = {
+  flatten,
+  findDefaultValueChanges,
+  evaluateDefaultFlipDoc,
+  readManifestAtRef,
+  MANIFEST_PATH,
+  BREAKING_CHANGES_RE,
+};
+
+if (require.main === module) runMain(main);

package/scripts/lint-docs-command-form.cjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * lint-docs-command-form.cjs
+ *
+ * Enforces the human-facing command form in docs/ (#2903).
+ *
+ * `/gsd:<cmd>` (and bare `gsd:<cmd>`) is a SOURCE-AUTHORING token: install-time
+ * converters (`transformContentToHyphen`, `convertSlashCommandsTo<Runtime>SkillMentions`)
+ * rewrite it to `/gsd-<cmd>` per-runtime. It is correct in `commands/gsd/**`,
+ * `gsd-core/workflows/**`, and `agents/**` — but docs are never passed through a
+ * converter, so a doc telling a reader to type `/gsd:<cmd>` names a command no
+ * runtime registers. The real user-facing form is `/gsd-<cmd>`.
+ *
+ * This guard fails any `docs/**\/*.md` file that still contains `/gsd:<cmd>` or
+ * bare `gsd:<cmd>` where `<cmd>` is a real command name (drawn from the
+ * `commands/gsd/*.md` roster). It explicitly permits `/gsd-core:<cmd>` (the
+ * Claude Code plugin namespace) and any `gsd:<token>` whose `<token>` is not a
+ * real command (e.g. the `gsd:section` / `gsd:loop-host` workflow-fragment
+ * marker syntax documented in docs/reference/workflow-fragments.md, or
+ * `gsd:command-name` used as a placeholder while explaining the Gemini CLI
+ * colon-form convention).
+ *
+ * Exclusions (never checked):
+ *   - docs/adr/**                  (historical record)
+ *   - docs/RELEASE-NOTES-LEGACY.md (maintainer question still open)
+ *   - commands/gsd/**, gsd-core/workflows/**, agents/** — never touched by this
+ *     guard at all; the colon form is correct there.
+ *
+ * Exemption — `name:` frontmatter key citations: source command files
+ * (`commands/gsd/*.md`) carry the colon form in their `name:` YAML frontmatter
+ * key (e.g. `name: gsd:next`). A doc that quotes that key verbatim — e.g.
+ * `` `name: gsd:next` `` or `name: gsd:next` — is citing the real source file,
+ * not telling a reader what to type. Rewriting that citation to `gsd-next`
+ * would make the doc lie about the source it's quoting, so a `gsd:<cmd>` token
+ * immediately preceded by `name:` (optionally with a backtick/whitespace in
+ * between) is permitted. This is narrow: it does not exempt `gsd:<cmd>`
+ * anywhere else on the line or file, including the reader-facing `/gsd-<cmd>`
+ * form that may appear later in the same sentence.
+ *
+ * Detection is case-insensitive (`/GSD:next`, `Gsd:Next`, etc. are all
+ * flagged) since the install-time converters and runtimes treat command names
+ * case-insensitively in practice, and a doc typo in casing is still a lie
+ * about the real command form.
+ *
+ * Exit 0 if no violations; exit 1 if any are found (with stderr diagnostics).
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const SELF_PATH = path.resolve(__filename);
+// GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT is used by tests to redirect the guard to
+// a temporary fixture git repo without touching the real working tree.
+const REPO_ROOT = process.env.GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT
+  ? path.resolve(process.env.GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT)
+  : path.resolve(__dirname, '..');
+
+const DOCS_PREFIX = 'docs/';
+const ADR_PREFIX = 'docs/adr/';
+const RELEASE_NOTES_LEGACY = 'docs/RELEASE-NOTES-LEGACY.md';
+const COMMANDS_DIR = path.join(REPO_ROOT, 'commands/gsd');
+
+// Matches `/gsd:<cmd>` and bare `gsd:<cmd>` (not part of `/gsd-core:<cmd>`,
+// which does not contain the substring `gsd:` — the hyphen breaks it).
+// Case-insensitive so `/GSD:next` / `Gsd:Next` are also caught.
+const COMMAND_FORM_RE = /(^|[^A-Za-z0-9_-])(\/)?gsd:([A-Za-z0-9_-]+)/gi;
+
+// A `gsd:<cmd>` token is exempt when it is a citation of a source file's
+// YAML `name:` frontmatter key — i.e. the text immediately before the match
+// (ending exactly where the match begins) is `name:` followed by optional
+// whitespace and/or a backtick. Only applies to the bare (non-`/`) form,
+// since the real frontmatter key never carries a leading slash.
+const NAME_KEY_CITATION_RE = /name:\s*`?\s*$/i;
+
+function loadRoster() {
+  let entries;
+  try {
+    entries = fs.readdirSync(COMMANDS_DIR);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-docs-command-form: could not read commands/gsd: ' + err.message);
+  }
+  return new Set(
+    entries.filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')),
+  );
+}
+
+function isCheckedDocsFile(relPath) {
+  if (!relPath.startsWith(DOCS_PREFIX)) return false;
+  if (relPath.startsWith(ADR_PREFIX)) return false;
+  if (relPath === RELEASE_NOTES_LEGACY) return false;
+  return relPath.endsWith('.md');
+}
+
+/**
+ * Pure scan — no fs, no git. Returns violations for a single file's content.
+ *
+ * @param {string} relPath  file path (used only in violation records)
+ * @param {string} content  file contents
+ * @param {Set<string>} roster  valid command names
+ * @returns {Array<{file:string, line:number, col:number, text:string}>}
+ */
+function scanContent(relPath, content, roster) {
+  const violations = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    COMMAND_FORM_RE.lastIndex = 0;
+    let match;
+    while ((match = COMMAND_FORM_RE.exec(line)) !== null) {
+      const [, pre, slash, cmd] = match;
+      if (!roster.has(cmd.toLowerCase())) continue;
+      if (!slash) {
+        const preContext = line.slice(0, match.index + pre.length);
+        if (NAME_KEY_CITATION_RE.test(preContext)) continue;
+      }
+      const matchedToken = (slash || '') + 'gsd:' + cmd;
+      violations.push({
+        file: relPath,
+        line: i + 1,
+        col: match.index + pre.length + 1,
+        text: matchedToken,
+      });
+    }
+  }
+  return violations;
+}
+
+function main() {
+  const roster = loadRoster();
+
+  let trackedFiles;
+  try {
+    trackedFiles = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' })
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-docs-command-form: git ls-files failed: ' + err.message);
+  }
+
+  const docsFiles = trackedFiles.filter(isCheckedDocsFile);
+  const violations = [];
+
+  for (const relPath of docsFiles) {
+    const fullPath = path.join(REPO_ROOT, relPath);
+    if (path.resolve(fullPath) === SELF_PATH) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      // Unreadable/deleted files — skip silently.
+      continue;
+    }
+
+    violations.push(...scanContent(relPath, content, roster));
+  }
+
+  if (violations.length === 0) {
+    process.stdout.write(
+      'ok lint-docs-command-form: ' + docsFiles.length + ' file(s) checked, 0 violations\n',
+    );
+    return 0;
+  }
+
+  process.stderr.write('\nERROR lint-docs-command-form: ' + violations.length + ' violation(s) found\n\n');
+  for (const v of violations) {
+    process.stderr.write('  ' + v.file + ':' + v.line + ':' + v.col + ' — ' + JSON.stringify(v.text) + '\n');
+  }
+  process.stderr.write('\n');
+  process.stderr.write(
+    'Fix: docs are never passed through the install-time slash-form converters, so the\n',
+  );
+  process.stderr.write(
+    '      colon form names a command no runtime registers. Rewrite to the hyphen form\n',
+  );
+  process.stderr.write(
+    '      (`/gsd-<cmd>`), or `/gsd-core:<cmd>` if this is genuinely the Claude Code\n',
+  );
+  process.stderr.write('      plugin namespace.\n\n');
+  return 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = {
+  scanContent,
+  isCheckedDocsFile,
+  loadRoster,
+  COMMAND_FORM_RE,
+};

package/scripts/lint-docs-required.cjs

@@ -16,6 +16,10 @@
 const { parseFragment, FRAGMENT_ERROR } = require('./changeset/parse.cjs');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
+// #2988: the repo's integration/default branch — the base every PR targets.
+// Used as the local fallback when GITHUB_BASE_REF is unset (CI sets it).
+const DEFAULT_BASE = 'next';
+
 const LINT_REASON = Object.freeze({
   OK_NO_TRIGGERING_FRAGMENTS: 'ok_no_triggering_fragments',
   OK_DOCS_UPDATED: 'ok_docs_updated',
@@ -149,7 +153,10 @@ function main() {
     } catch { /* fall through */ }
   }
 
-  const base = process.env.GITHUB_BASE_REF || 'main';
+  // #2988: local fallback must match the repo's integration branch (`next`),
+  // not the release branch (`main`). CI sets GITHUB_BASE_REF explicitly; the
+  // fallback only fires locally, where `next` is the base every PR targets.
+  const base = process.env.GITHUB_BASE_REF || DEFAULT_BASE;
   let changedFiles = [];
   try {
     // execFileSync with argv — no shell, so a malicious GITHUB_BASE_REF
@@ -216,6 +223,7 @@ module.exports = {
   OPT_OUT_LABEL,
   TRIGGERING_TYPES,
   FRAGMENT_ERROR,
+  DEFAULT_BASE,
   isFragmentPath,
   isDocsFile,
   isExemptFragment,