@opengsd/gsd-core 1.14.0 → 1.16.0

package/scripts/lint-retired-runtime-name.cjs

@@ -0,0 +1,619 @@
+#!/usr/bin/env node
+/**
+ * lint-retired-runtime-name.cjs
+ *
+ * Prevents a RETIRED GSD runtime name from being presented as if it were a
+ * live runtime (#1928 retired the "Gemini CLI" runtime lane in favor of
+ * Antigravity). Mirrors scripts/lint-legacy-dir-name.cjs's structure and
+ * conventions (same problem shape: forbid a retired token, allowlist
+ * frozen/legitimate content, self-exempt, inline marker, `GSD_LINT_*_REPO_ROOT`
+ * test seam, ./lib/cli-exit.cjs, binary-file skip).
+ *
+ * THE PREDICATE (load-bearing — do not "simplify"):
+ * The forbidden token is matched CASE-SENSITIVELY, standalone (word
+ * boundaries), capitalised: /\bGemini\b/ — NO `i` flag.
+ *
+ * Case sensitivity IS the mechanism. Every LEGITIMATE reference to the
+ * "gemini" string in this repo is spelled differently and therefore cannot
+ * match a case-sensitive `Gemini`:
+ *   - Antigravity's config homes are lowercase with a slash:
+ *     ~/.gemini/antigravity, ~/.gemini/antigravity-ide, ~/.gemini/config
+ *   - Google's model ids are lowercase and hyphenated:
+ *     gemini-3.1-pro-preview, gemini-2.5-flash-lite
+ *   - env vars are uppercase: GEMINI_CONFIG_DIR, GEMINI_SESSION_ID, GEMINI_API_KEY
+ *   - the instruction file is GEMINI.md
+ * A bare capitalised `Gemini` therefore means the retired RUNTIME (or its
+ * retired reviewer lane) is being named as if live — which is the defect
+ * this guard exists to catch.
+ *
+ * RETIRED_RUNTIMES is a table, not a hardcoded single name, so the guard
+ * generalises to the next retired runtime for free. The name is built via
+ * split-string concatenation (same trick the legacy-dir-name precedent
+ * uses) so this guard script cannot flag itself.
+ *
+ * THREE TIERS OF EXEMPTION, deliberately ordered narrowest-first. The
+ * allowlist is the entire risk surface of this guard, so each tier states
+ * what it can and cannot see:
+ *
+ *   1. GENERAL RULES (apply anywhere, no per-file registration) — the two
+ *      spellings that are legitimate wherever they appear:
+ *      (a) the hook DIALECT Antigravity genuinely inherits: `Gemini-style`,
+ *          `Gemini-compatible`, `Gemini スタイル`;
+ *      (b) a model-display version on the provider/model axis
+ *          (`Gemini 2.5 Pro`), REFUSED when a runtime word also appears on
+ *          the line so a version can never launder a runtime claim.
+ *   2. PINNED OCCURRENCES (`ALLOWLIST_OCCURRENCES`) — per-file, per-line
+ *      approved snippets. This is what makes a NEW occurrence in an
+ *      otherwise-legitimate file FAIL: the file is not blanket-trusted, only
+ *      the enumerated lines are. A pin that stops matching is reported as a
+ *      stale allowlist entry, so the allowlist cannot silently rot.
+ *   3. FILE / DIR ALLOWLIST — blanket trust, and therefore reserved for
+ *      content that is append-only by policy (ADRs, dated research) or
+ *      generated-and-locked (CHANGELOG.md). A new occurrence inside these
+ *      IS invisible to this guard; that is the accepted cost of not
+ *      re-litigating frozen history on every run, and it is why the tier is
+ *      kept as small as it is.
+ *
+ * Plus an anti-vacuity floor on files actually READ (not merely listed), so
+ * an empty or failed walk can never report a false clean.
+ *
+ * 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 { escapeRegex } = require('../gsd-core/bin/lib/pattern.cjs');
+
+// Table of retired runtimes. Each name is constructed via split-string
+// concatenation so this guard script cannot flag itself when scanned.
+const RETIRED_RUNTIMES = [
+  {
+    name: 'Gem' + 'ini',
+    retiredBy: '#1928',
+    sunset: '2026-06-18',
+    successor: 'Antigravity',
+  },
+];
+
+const RETIRED_RUNTIME_MATCHERS = RETIRED_RUNTIMES.map((r) => ({
+  runtime: r,
+  // Case-sensitive, no 'i' flag — see module header for why.
+  re: new RegExp('\\b' + r.name + '\\b', 'g'),
+}));
+
+// Minimum plausible number of files actually READ. An empty or failed walk
+// must never silently report "clean" (anti-vacuity requirement).
+const MIN_EXPECTED_FILES = 150;
+
+const ALLOW_MARKER = 'gsd-allow-retired-runtime-name';
+// The escape hatch must carry a justification. Bare-marker abuse was raised in
+// review: the marker is checked first, excuses the whole line, and the failure
+// message advertises it, so an unexplained one is indistinguishable from a
+// defect somebody silenced. Require `gsd-allow-retired-runtime-name: <reason>`.
+const ALLOW_MARKER_RE = new RegExp(escapeRegex(ALLOW_MARKER) + ':\\s*\\S{3,}');
+const SELF_PATH = path.resolve(__filename);
+// GSD_LINT_RETIRED_RUNTIME_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_RETIRED_RUNTIME_REPO_ROOT
+  ? path.resolve(process.env.GSD_LINT_RETIRED_RUNTIME_REPO_ROOT)
+  : path.resolve(__dirname, '..');
+
+// Every tracked *.md file is in scope. An earlier prefix list
+// (docs/ gsd-core/ commands/ agents/ skills/ + root) left `.changeset/`,
+// `.github/`, `capabilities/`, `playbooks/` and `references/` invisible —
+// and `.changeset/*.md` RENDERS INTO CHANGELOG.md, which is blanket-trusted,
+// so a live claim introduced there was invisible at both ends.
+
+// TIER 3 — blanket trust. Append-only by policy, or generated-and-locked.
+// A new occurrence inside these is invisible to this guard; see the module
+// header for why that cost is accepted here and nowhere else.
+const ALLOWLIST_FILES = new Set([
+  // Locked by CLAUDE.md ("CHANGELOG.md is Locked") and generated from
+  // changeset fragments: frozen release history, one entry per shipped
+  // release, including the releases that removed the runtime.
+  'CHANGELOG.md',
+]);
+
+const ALLOWLIST_DIR_PREFIXES = [
+  // `.changeset/` is CHANGELOG.md before rendering — the same surface, one
+  // step upstream — so it gets the same treatment. Measured: all 21 hits are
+  // fragments DESCRIBING the retirement or a fix to it (e.g. "Retired the
+  // Gemini CLI reviewer lane", "Gemini install output is valid on Windows
+  // PowerShell"), which is what a release note is for. 464 of the 479 live
+  // under `archived/`. Pinning them would add friction with no signal: a
+  // fragment can only describe what already shipped, and it is deleted at
+  // release. The cost is stated rather than hidden — a fragment introducing a
+  // live claim is invisible here, as it is in CHANGELOG.md itself.
+  '.changeset/',
+  // Architecture decision records are append-only history.
+  'docs/adr/',
+  // Frozen historical release notes.
+  'docs/RELEASE-NOTES-LEGACY.md',
+  // Dated research records, incl. the gemini-to-antigravity migration note.
+  'docs/research/',
+  // Dated records.
+  'docs/issueevidence/',
+  'docs/discussions/',
+  'docs/superpowers/',
+];
+
+// TIER 2 — pinned occurrences. relPath -> [{ snippet, reason }]. A match is
+// excused only when its LINE contains one of that file's snippets, so a new,
+// unrelated occurrence in the same file still fails. Every snippet is a
+// verbatim fragment of the line it approves.
+const ALLOWLIST_OCCURRENCES = new Map([
+  ['CONTEXT.md', [
+    // The name precedes the annotation on this line, so the snippet must span
+    // both for span containment to cover the match.
+    { snippet: 'Gemini [runtime removed #1928]', reason: 'session log annotates the removal inline' },
+  ]],
+  ['GEMINI.md', [
+    { snippet: 'Gemini CLI was sunset by Google on 2026-06-18', reason: 'states the sunset' },
+    { snippet: 'shared Gemini 3 backend', reason: 'names the shared model backend Antigravity uses' },
+  ]],
+  ['docs/whats-new-1.7.0.md', [
+    // Two occurrences on one line, so two pins: span containment deliberately
+    // refuses to let the first excuse the second.
+    { snippet: 'Gemini CLI removed** (#1928)', reason: 'release note announcing the removal' },
+    { snippet: 'Google discontinued Gemini CLI on 2026-06-18', reason: 'states the sunset date' },
+  ]],
+  ['docs/explanation/embeddable-orchestration-system.md', [
+    { snippet: 'Gemini CLI was retired in', reason: 'records the retirement' },
+  ]],
+  // The fragment is the SOURCE; docs/FEATURES.md is generated from it by
+  // scripts/gen-features.cjs, so both carry the same approved line and the
+  // same pin covers each. A marker written into FEATURES.md by hand would be
+  // dropped on the next regeneration.
+  ['docs/features/embeddable-orchestration-system-host-integration-interface.md', [
+    { snippet: 'retired Gemini CLI now redirects to Antigravity CLI', reason: 'records the redirect' },
+  ]],
+  ['docs/FEATURES.md', [
+    { snippet: 'retired Gemini CLI now redirects to Antigravity CLI', reason: 'generated from the fragment above' },
+  ]],
+  ['docs/reference/host-integration-capability-matrix.md', [
+    { snippet: '(Gemini CLI\'s `thinkingConfig`) was removed as a sunset runtime', reason: 'explains why no config-file member exists' },
+    { snippet: 'successor to the sunset Gemini CLI per #1928', reason: 'records the sunset and the inherited contract' },
+  ]],
+  // --- The inherited hook dialect, where the line ALSO names a runtime -----
+  // Tier 1(a) requires no runtime word on the line, because the tight
+  // "immediately after the name" veto let real laundering through. These ten
+  // lines legitimately pair a dialect compound with a runtime word (usually
+  // `~/.gemini/antigravity-cli` in a table cell, or "runtime files" in the
+  // same sentence), so each is pinned explicitly instead of loosening the
+  // veto for everyone.
+  ['docs/ARCHITECTURE.md', [
+    { snippet: 'Gemini-style `settings.json` hook entries', reason: 'hook dialect Antigravity inherits' },
+  ]],
+  ['docs/ja-JP/ARCHITECTURE.md', [
+    { snippet: 'Gemini スタイル `settings.json` フックエントリ', reason: 'hook dialect Antigravity inherits' },
+  ]],
+  ['docs/ko-KR/ARCHITECTURE.md', [
+    { snippet: 'Gemini 스타일 `settings.json` 훅 항목', reason: 'hook dialect Antigravity inherits' },
+  ]],
+  ['docs/pt-BR/ARCHITECTURE.md', [
+    { snippet: 'no estilo Gemini quando instalado', reason: 'hook dialect Antigravity inherits' },
+  ]],
+  ['docs/zh-CN/ARCHITECTURE.md', [
+    { snippet: 'Gemini 风格 `settings.json` hook 条目', reason: 'hook dialect Antigravity inherits' },
+  ]],
+  ['docs/how-to/install-on-your-runtime.md', [
+    { snippet: 'Uses Gemini-compatible settings policy', reason: 'settings dialect Antigravity inherits' },
+  ]],
+  ['docs/ja-JP/how-to/install-on-your-runtime.md', [
+    { snippet: 'Gemini 互換', reason: 'settings dialect Antigravity inherits' },
+  ]],
+  ['docs/ko-KR/how-to/install-on-your-runtime.md', [
+    { snippet: 'Gemini 호환 설정 정책을 사용합니다', reason: 'settings dialect Antigravity inherits' },
+  ]],
+  ['docs/pt-BR/how-to/install-on-your-runtime.md', [
+    { snippet: 'compatível com Gemini', reason: 'settings dialect Antigravity inherits' },
+  ]],
+  ['docs/zh-CN/how-to/install-on-your-runtime.md', [
+    { snippet: '与 Gemini 兼容的设置策略', reason: 'settings dialect Antigravity inherits' },
+  ]],
+  ['gsd-core/workflows/reapply-patches.md', [
+    { snippet: 'pre-#1928 Gemini CLI install', reason: 'legacy-install patch location, explicitly pre-retirement' },
+  ]],
+  ['gsd-core/workflows/settings-advanced.md', [
+    { snippet: '(Claude / OpenAI / Gemini / Qwen)', reason: 'model-provider menu, not a GSD runtime' },
+  ]],
+  ['gsd-core/references/ai-frameworks.md', [
+    { snippet: 'Google Cloud / Gemini-committed teams', reason: 'provider axis (Google ADK)' },
+    { snippet: 'Optimized for Gemini; supports other models', reason: 'model axis' },
+    { snippet: 'teams already committed to Gemini', reason: 'model axis' },
+    { snippet: 'Model flexibility is required beyond Gemini', reason: 'model axis' },
+    { snippet: 'Gemini vendor lock-in in practice', reason: 'model axis' },
+    { snippet: 'Google/Gemini-committed', reason: 'provider axis (Google ADK)' },
+  ]],
+  ['agents/gsd-framework-selector.md', [
+    // Two occurrences on one line: the menu label and its description.
+    { snippet: 'Google (Gemini)', reason: 'model-provider choice, not a GSD runtime' },
+    { snippet: 'Committed to Gemini / Google Cloud / Vertex AI', reason: 'the same menu entry\'s description' },
+  ]],
+  ['agents/gsd-framework-selector.compact.md', [
+    { snippet: 'Google (Gemini)', reason: 'model-provider choice, not a GSD runtime' },
+  ]],
+]);
+
+// Every pin must contain a retired runtime name. Span containment means a
+// snippet that does not contain the name can never cover a match, so such a
+// pin is dead config that would also be reported stale forever — fail loud at
+// load rather than mislead later.
+for (const [relPath, pins] of ALLOWLIST_OCCURRENCES) {
+  for (const pin of pins) {
+    const names = RETIRED_RUNTIMES.filter((r) => pin.snippet.includes(r.name));
+    if (names.length === 0) {
+      throw new Error(
+        'lint-retired-runtime-name: pin for ' + relPath + ' does not contain a retired '
+          + 'runtime name and can never match: ' + JSON.stringify(pin.snippet),
+      );
+    }
+  }
+}
+
+// docs/RELEASE-NOTES-LEGACY.md is a file, not a directory, but the brief
+// lists it alongside the dir prefixes — treat both files and dirs the same
+// way via a "startsWith" prefix check.
+function isAllowlisted(relPath) {
+  if (ALLOWLIST_FILES.has(relPath)) return true;
+  for (const prefix of ALLOWLIST_DIR_PREFIXES) {
+    if (relPath === prefix || relPath.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+function isInScanSet(relPath) {
+  return relPath.endsWith('.md');
+}
+
+function isBinary(fullPath) {
+  // Read a small chunk and check for NUL bytes.
+  let fd;
+  try {
+    fd = fs.openSync(fullPath, 'r');
+    const buf = Buffer.allocUnsafe(512);
+    const bytesRead = fs.readSync(fd, buf, 0, 512, 0);
+    return buf.subarray(0, bytesRead).includes(0);
+  } catch {
+    return false;
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
+// --- TIER 1(a): the hook dialect Antigravity genuinely inherits -------------
+// Antigravity reads Gemini-shaped `settings.json` hook entries, and every
+// locale names that dialect. Marker POSITION is language-dependent and was
+// measured: en `Gemini-style` / `Gemini-compatible`, ja `Gemini スタイル`,
+// ko `Gemini 스타일` / `호환`, zh `Gemini 风格` / `与 Gemini 兼容的`, and pt
+// `no estilo Gemini` / `compatível com Gemini`, where it PRECEDES the name.
+//
+// The marker must form an ADJACENT COMPOUND with the name. An earlier version
+// searched a ±24-character window, which let one legitimate dialect reference
+// launder a second, unrelated live claim on the same line — a reviewer
+// demonstrated `| Antigravity | Gemini-style hooks | Gemini support is live |`
+// exiting 0, because the second occurrence sat 21 characters from `style`.
+// Adjacency is the property that actually distinguishes a dialect NAME from a
+// runtime CLAIM, so it is what is tested.
+const DIALECT_MARKERS = [
+  'style', 'compatible', // en
+  'スタイル', '互換', // ja
+  '스타일', '호환', // ko
+  '风格', '兼容', // zh
+  'estilo', 'compatível', 'compatibilidade', // pt
+];
+const DIALECT_ALT = DIALECT_MARKERS.map(escapeRegex).join('|');
+// Marker immediately follows: "Gemini-style", "Gemini スタイル", "Gemini 兼容".
+const DIALECT_AFTER_RE = new RegExp('^[-\\s]?(?:' + DIALECT_ALT + ')', 'i');
+// Marker immediately precedes, optionally through ONE short connective:
+// "no estilo Gemini", "compatível com Gemini".
+const DIALECT_BEFORE_RE = new RegExp(
+  '(?:' + DIALECT_ALT + ')\\s*(?:com|with|de|da|do|and)?\\s*$',
+  'i',
+);
+
+function isDialectReference(line, matchIndex, afterMatch) {
+  const adjacent = DIALECT_AFTER_RE.test(afterMatch)
+    || DIALECT_BEFORE_RE.test(line.slice(0, matchIndex));
+  if (!adjacent) return false;
+  // A dialect marker is NOT a licence when the line also asserts a runtime.
+  // This veto is line-global on purpose: the tight "immediately after the
+  // name" form let `Suportamos Gemini, no estilo padrao, como runtime de
+  // instalacao.` and `Gemini 兼容，并且是受支持的运行时之一。` both exit 0 while
+  // literally containing `runtime` / `运行时`. Real lines that legitimately
+  // pair a dialect compound with a runtime word are handled by an explicit
+  // Tier-2 pin, not by loosening this.
+  return !RUNTIME_WORD_RE.test(line);
+}
+
+// --- TIER 1(b): the provider/model axis ------------------------------------
+// Matches the display-name spelling of a model version: a version number
+// optionally followed by a model qualifier, or one that ends the list item.
+// Deliberately NOT "space then a digit" — that blanket rule also matched
+// "Gemini 2.5 CLI as a supported runtime.", laundering a genuine stale-runtime
+// claim through an attached version number. Full-width digits and CJK
+// punctuation are included because the translated docs use them.
+const DIGIT = '0-9\\uFF10-\\uFF19';
+const SP = ' \\u3000'; // ASCII space + ideographic space
+const QUALIFIER = 'Pro|Flash|Ultra|Nano|Lite|Preview|Exp|Thinking';
+const PUNCT = ',;.:)\\]\\u3001\\u3002\\uFF0C\\uFF09\\uFF3D\\uFF1A';
+const MODEL_DISPLAY_AFTER = new RegExp(
+  '^[' + SP + ']'
+  + '[' + DIGIT + ']+(?:[.\\uFF0E][' + DIGIT + ']+)*'
+  + '(?:'
+  + '[' + SP + ']+(?:' + QUALIFIER + ')\\b[\\w-]*'
+  + '|[' + SP + ']*[' + PUNCT + ']'
+  + '|[' + SP + ']*$'
+  + ')',
+);
+
+// Words that indicate a RUNTIME (not a model) is being named on the line, in
+// every language this repo ships translated docs for. If any appears
+// alongside a model-display version, the version does NOT get to launder the
+// runtime claim — the line is still a violation.
+//
+// Latin terms are anchored with \b so "CLI" cannot match inside "client" and
+// "host" cannot match inside "ghost"; CJK terms are matched raw because \b is
+// ASCII-word-based and would never fire next to a non-word ideograph.
+//
+// Deliberately EXCLUDED: "agent" and "target". Both occur throughout ordinary
+// prose ("AI coding agents (Claude Code, Codex, Gemini 2.5 Pro)"), so vetoing
+// on them would red legitimate model lists rather than catch runtime claims.
+const RUNTIME_WORDS = [
+  'CLI',
+  'runtime',
+  'runtimes',
+  'IDE',
+  'extension',
+  'host',
+  'ランタイム', // ja
+  '実行環境', // ja
+  '런타임', // ko
+  '运行时', // zh
+  '运行环境', // zh
+  'tempo de execução', // pt
+];
+const RUNTIME_WORD_RE = new RegExp(
+  RUNTIME_WORDS.map((w) => {
+    const esc = escapeRegex(w);
+    // Anchor only when the term begins/ends with an ASCII word character;
+    // \b is meaningless beside an ideograph.
+    return /^[A-Za-z0-9]/.test(w) ? '\\b' + esc + '\\b' : esc;
+  }).join('|'),
+  'i',
+);
+
+// Positive evidence that the line is on the MODEL axis. Required, not merely
+// the absence of a runtime word: a reviewer demonstrated that "absence of a
+// veto word" is not evidence, with `The installer now offers Gemini 3.`,
+// `GSD installs cleanly on Gemini 3, Kimi, and Codex.` and
+// `Supported agents include Gemini 3, Kimi, and Cursor.` all exiting 0 — the
+// exact laundering class this guard exists to catch. Every real model-axis
+// line in this repo names a model explicitly, so requiring it costs nothing
+// and inverts the failure direction from "silently allow" to "flag".
+const MODEL_WORDS = [
+  'model', 'models', // en
+  'モデル', // ja
+  '모델', // ko
+  '模型', // zh
+  'modelo', 'modelos', // pt
+];
+const MODEL_WORD_RE = new RegExp(
+  MODEL_WORDS.map((w) => {
+    const esc = escapeRegex(w);
+    return /^[A-Za-z0-9]/.test(w) ? '\\b' + esc + '\\b' : esc;
+  }).join('|'),
+  'i',
+);
+
+/**
+ * Is `pin` satisfied AT this match? The match must fall INSIDE an occurrence
+ * of the pin's snippet, not merely share a line with it.
+ *
+ * Line-level containment was too weak: a reviewer showed
+ * `Known provider menu update: Gemini CLI is once again a selectable GSD
+ * runtime.` and `Install target: Google (Gemini) — choose Gemini CLI as your
+ * GSD runtime.` both exiting 0, because a short snippet elsewhere on the line
+ * pre-approved a brand-new claim. Span containment means a pin can only ever
+ * excuse the occurrence its own text covers.
+ */
+function pinCoversMatch(line, matchIndex, matchedText, pin) {
+  const end = matchIndex + matchedText.length;
+  let from = 0;
+  for (;;) {
+    const at = line.indexOf(pin.snippet, from);
+    if (at === -1) return false;
+    if (matchIndex >= at && end <= at + pin.snippet.length) return true;
+    from = at + 1;
+  }
+}
+
+/**
+ * Decide whether one MATCH (not the whole line) is legitimate.
+ *
+ * Returns the matched pin, `true` for a general-rule exemption, or `false`
+ * for a violation.
+ */
+function classifyMatch(line, matchIndex, matchedText, pins) {
+  // The explicit escape hatch, which must carry a reason.
+  if (ALLOW_MARKER_RE.test(line)) return true;
+
+  const afterMatch = line.slice(matchIndex + matchedText.length);
+
+  // TIER 1(a) — inherited hook dialect, as an adjacent compound.
+  if (isDialectReference(line, matchIndex, afterMatch)) return true;
+
+  // TIER 1(b) — provider/model axis. Needs positive model evidence AND no
+  // runtime word; a version number alone never launders a claim.
+  if (MODEL_DISPLAY_AFTER.test(afterMatch)
+    && MODEL_WORD_RE.test(line)
+    && !RUNTIME_WORD_RE.test(line)) {
+    return true;
+  }
+
+  // TIER 2 — a pinned occurrence for this specific file, span-scoped.
+  for (const pin of pins) {
+    if (pinCoversMatch(line, matchIndex, matchedText, pin)) return pin;
+  }
+
+  return false;
+}
+
+function main() {
+  // Enumerate tracked files via git ls-files so only committed/staged source is checked.
+  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-retired-runtime-name: git ls-files failed: ' + err.message);
+  }
+
+  const scanFiles = trackedFiles.filter(isInScanSet);
+
+  const violations = [];
+  const usedPins = new Set();
+  // Files present in the scan set, so a stale-pin check can distinguish
+  // "this pin's file is gone/not in this tree" from "this pin matched nothing".
+  const scannedRelPaths = new Set();
+  // Anti-vacuity counts files actually READ, not merely listed: if every read
+  // failed, a candidate count would still look healthy.
+  let filesRead = 0;
+
+  for (const relPath of scanFiles) {
+    if (isAllowlisted(relPath)) continue;
+
+    const fullPath = path.join(REPO_ROOT, relPath);
+
+    // Skip this guard script itself (path-based, though it is not a .md file
+    // and would never be in-scan-set anyway — defense in depth).
+    if (path.resolve(fullPath) === SELF_PATH) continue;
+
+    if (isBinary(fullPath)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      // Unreadable files (permissions, etc.) — skip silently.
+      continue;
+    }
+    filesRead += 1;
+    scannedRelPaths.add(relPath);
+
+    const pins = ALLOWLIST_OCCURRENCES.get(relPath) || [];
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Mark pins used by PRESENCE on the line, independent of which tier
+      // ultimately excused the match. Previously this was recorded only on
+      // the Tier-2 branch, so a pinned line that a general rule also matched
+      // never marked its pin used and the pin was reported stale — a reviewer
+      // demonstrated a provably false "no line matches pinned snippet" whose
+      // printed remedy told the maintainer to delete a still-needed pin.
+      for (const pin of pins) {
+        if (line.includes(pin.snippet)) usedPins.add(relPath + ' ' + pin.snippet);
+      }
+
+      for (const { runtime, re } of RETIRED_RUNTIME_MATCHERS) {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(line)) !== null) {
+          const verdict = classifyMatch(line, match.index, match[0], pins);
+          if (verdict) continue;
+          violations.push({
+            file: relPath,
+            line: i + 1,
+            col: match.index + 1,
+            text: line.trim(),
+            runtime,
+          });
+        }
+      }
+    }
+  }
+
+  // Anti-vacuity: the scan must have READ a plausible number of files.
+  if (filesRead < MIN_EXPECTED_FILES) {
+    throw new ExitError(
+      1,
+      'ERROR lint-retired-runtime-name: only ' + filesRead + ' file(s) read '
+        + '(expected at least ' + MIN_EXPECTED_FILES + '); the walk is empty or broken — refusing '
+        + 'to report a false clean.',
+    );
+  }
+
+  // A pin that no longer matches anything is a stale allowlist entry: the
+  // content it approved was edited or removed, and leaving it in place would
+  // pre-approve a future occurrence nobody reviewed. Only checked for files
+  // actually present in this tree, so fixture roots are unaffected.
+  const stalePins = [];
+  for (const [relPath, pins] of ALLOWLIST_OCCURRENCES) {
+    if (!scannedRelPaths.has(relPath)) continue;
+    for (const pin of pins) {
+      if (!usedPins.has(relPath + ' ' + pin.snippet)) {
+        stalePins.push({ file: relPath, snippet: pin.snippet });
+      }
+    }
+  }
+
+  if (violations.length === 0 && stalePins.length === 0) {
+    process.stdout.write(
+      'ok lint-retired-runtime-name: ' + filesRead + ' files scanned, 0 violations\n',
+    );
+    return 0;
+  }
+
+  if (violations.length > 0) {
+    process.stderr.write('\nERROR lint-retired-runtime-name: ' + violations.length + ' violation(s) found\n\n');
+    for (const v of violations) {
+      process.stderr.write('  ' + v.file + ':' + v.line + ': ' + v.text + '\n');
+    }
+    process.stderr.write('\n');
+    for (const runtime of RETIRED_RUNTIMES) {
+      process.stderr.write(
+        'Fix: `' + runtime.name + '` was retired by ' + runtime.retiredBy + ' (sunset ' + runtime.sunset + ') '
+          + 'in favor of `' + runtime.successor + '`. Either correct the reference to name the live runtime, '
+          + 'or, if the use is a legitimate historical/provider reference, add the `' + ALLOW_MARKER + '` '
+          + 'marker on the line.\n',
+      );
+    }
+    process.stderr.write('\n');
+  }
+
+  if (stalePins.length > 0) {
+    process.stderr.write(
+      'ERROR lint-retired-runtime-name: ' + stalePins.length + ' stale allowlist entr'
+        + (stalePins.length === 1 ? 'y' : 'ies') + ' in ALLOWLIST_OCCURRENCES\n\n',
+    );
+    for (const s of stalePins) {
+      process.stderr.write('  ' + s.file + ': no line matches pinned snippet ' + JSON.stringify(s.snippet) + '\n');
+    }
+    process.stderr.write(
+      '\nFix: the approved line was edited or removed. Delete the pin, or update its '
+        + 'snippet to the new wording — an unmatched pin pre-approves a future occurrence '
+        + 'nobody reviewed.\n\n',
+    );
+  }
+
+  return 1;
+}
+
+// Only run the lint when invoked directly. `require()`ing this module (the
+// parity test in tests/runtime-name-policy.test.cjs does) must not
+// execute a full repository walk as a side effect.
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = { RETIRED_RUNTIMES };

package/scripts/lint-skill-deps.cjs

@@ -29,6 +29,8 @@ const { runMain } = require('./lib/cli-exit.cjs');
 
 const PROFILES_MODULE = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'install-profiles.cjs');
 const { PROFILES, loadSkillsManifest, resolveProfile } = require(PROFILES_MODULE);
+// The one frontmatter fence owner, from the same build:lib output as install-profiles.
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -58,9 +60,11 @@ function extractBodyReferences(body) {
 }
 
 function extractBody(content) {
-  const fmEnd = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/m);
-  if (!fmEnd) return content;
-  return content.slice(fmEnd[0].length);
+  // The block is the one the one fence owner finds (found while implementing #5105);
+  // the body starts past the closing fence line and its line ending.
+  const fence = locateFrontmatterFence(content);
+  if (!fence || !fence.closed) return content;
+  return content.slice(fence.closingFenceEnd).replace(/^\r?\n/, '');
 }
 
 // ---------------------------------------------------------------------------