@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/lint_blocker_citations.ts

@@ -21,13 +21,20 @@
  * `lint_blocker_citations`): line numbers drift, so a miss already in the tree
  * is drift rather than a new defect, and the count may only fall.
  *
+ * Usage:
+ *   ./scripts-run src/scripts/lint_blocker_citations
+ *   ./scripts-run src/scripts/lint_blocker_citations --root <repo>
+ *   ./scripts-run src/scripts/lint_blocker_citations --self-test
+ *
  * Exit codes: 0 within the ratchet · 1 above it · 2 usage error.
  */
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { checkRatchet } from './_lib/gate_baseline.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { reportScanned } from './_lib/scan_scope.js';
 
 type MissKind = 'missing-file' | 'beyond-end';
@@ -133,11 +140,108 @@ function scanTree(root: string): { misses: Miss[]; scanned: number; citations: n
 
 const _DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 
+/**
+ * Five fixtures over a temporary tree, driven through the real CLI.
+ *
+ * Each fixture carries its own baselines file pinned at 0, so the ratchet is
+ * out of the way and a single planted miss has to redden. That is the one thing
+ * the repository's own run cannot show: on the real tree this gate sits two
+ * below its baseline, so a planted citation reads green there — which is why
+ * this gate's `gate-coverage.yml` row carries `no_canary_reason` and leans on
+ * exactly these cases instead.
+ */
+function selfTest(): number {
+    const repoRoot = _DEFAULT_ROOT;
+    const rel = 'src/scripts/lint_blocker_citations.ts';
+    const BASELINE = JSON.stringify({
+        gates: {
+            lint_blocker_citations: {
+                count: 0,
+                landed: '2026-10-13',
+                falsifier: 'self-test fixture — pinned at zero so one planted miss must redden',
+                note: 'Self-test fixture baseline. Not a tree reading.',
+            },
+        },
+    });
+
+    const over = (blockers: string, extra?: { file: string; body: string }): (() => number) => (): number => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'blocker-cites-self-'));
+        try {
+            const roadmaps = path.join(dir, 'agents', 'roadmaps');
+            fs.mkdirSync(roadmaps, { recursive: true });
+            fs.mkdirSync(path.join(dir, 'src', 'config'), { recursive: true });
+            fs.writeFileSync(path.join(dir, 'src', 'config', 'gate-violation-baselines.json'), BASELINE);
+            if (extra !== undefined) {
+                const abs = path.join(dir, extra.file);
+                fs.mkdirSync(path.dirname(abs), { recursive: true });
+                fs.writeFileSync(abs, extra.body);
+            }
+            fs.writeFileSync(path.join(roadmaps, 'road-to-fixture.md'), blockers);
+            return runGateCli(repoRoot, rel, ['--root', dir], repoRoot);
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    };
+
+    const THREE_LINES = 'one\ntwo\nthree\n';
+
+    return runSelfTest({
+        gate: 'lint_blocker_citations',
+        minCases: 5,
+        minRejectCases: 2,
+        cases: [
+            {
+                name: 'a citation whose file does not exist is rejected',
+                expect: 'reject',
+                run: over('## Blockers\n\nResolved when `src/scripts/nope.ts:12` says so.\n'),
+            },
+            {
+                name: 'a citation past the end of an existing file is rejected',
+                expect: 'reject',
+                run: over('## Blockers\n\nResolved when `src/scripts/real.ts:99` says so.\n', {
+                    file: 'src/scripts/real.ts',
+                    body: THREE_LINES,
+                }),
+            },
+            {
+                name: 'a citation inside an existing file is accepted',
+                expect: 'accept',
+                run: over('## Blockers\n\nResolved when `src/scripts/real.ts:2` says so.\n', {
+                    file: 'src/scripts/real.ts',
+                    body: THREE_LINES,
+                }),
+            },
+            {
+                name: 'a bare `:12` with no path is not a citation and is accepted',
+                expect: 'accept',
+                run: over('## Blockers\n\nResolved when the block at :12 says so.\n'),
+            },
+            {
+                name: 'the same dead citation OUTSIDE the Blockers section is accepted',
+                expect: 'accept',
+                run: over('## Context\n\nSee `src/scripts/nope.ts:12`.\n\n## Goal\n\nNothing.\n'),
+            },
+            {
+                name: 'a roadmap tree with no Blockers section at all is accepted',
+                expect: 'accept',
+                run: over('# Road to nothing\n\nNo blockers here.\n'),
+            },
+        ],
+    });
+}
+
 function main(argv: string[] = process.argv.slice(2)): number {
     let root = _DEFAULT_ROOT;
     let baselineRoot = _DEFAULT_ROOT;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
+        if (arg === '--self-test') {
+            if (process.env['GATE_SELF_TEST_CHILD'] === '1') {
+                process.stderr.write('lint_blocker_citations: --self-test does not recurse\n');
+                return 2;
+            }
+            return selfTest();
+        }
         if (arg === '--root') {
             const v = argv[i + 1];
             if (v === undefined) {

package/src/scripts/lint_breaking_changes_index.ts

@@ -14,7 +14,9 @@
  * breaking note under `## [Unreleased]` is WIP and never trips the gate.
  *
  * REQUIREMENT: when triggered, the same diff must also modify
- * `BREAKING_CHANGES.md`.
+ * `BREAKING_CHANGES.md`, unless the index already carries a by-major row
+ * (`| **N.0.0** |`) for that major — the row the Pending workflow lands on main
+ * before the cut, which the release diff then never touches.
  *
  * Escape hatch (mirrors `check_structural_breaking.ts`'s `ci-override` trailer):
  * an own-line trailer `ci-override: breaking-index-override` (the bare token
@@ -95,23 +97,45 @@ export function added_released_breaking_majors(
     return added;
 }
 
+// A by-major row opens with the version in bold: `| **17.0.0** | 2026-10-21 | …`.
+const INDEX_ROW_RE = /^\|\s*\*\*(?<version>\d+\.\d+\.\d+)\*\*\s*\|/;
+
+/** The majors `BREAKING_CHANGES.md` already carries a by-major row for. */
+export function indexed_majors(indexLines: readonly string[]): Set<string> {
+    const found = new Set<string>();
+    for (const ln of indexLines) {
+        const m = INDEX_ROW_RE.exec(ln);
+        if (m) found.add(m.groups!['version']!);
+    }
+    return found;
+}
+
 export interface CheckResult {
     readonly addedMajors: readonly string[];
+    /** Added majors with no by-major row in the index. */
+    readonly unindexedMajors: readonly string[];
     readonly indexChanged: boolean;
     readonly overridden: boolean;
     readonly violation: boolean;
 }
 
-/** Pure decision: violation iff a released BREAKING was added, the index was not touched, and no override cleared it. */
+/**
+ * Pure decision: violation iff a released BREAKING was added for a major the
+ * index carries no row for, the index was not touched, and no override cleared
+ * it. A row landed before the cut satisfies the index: the Pending workflow
+ * writes it on main, so the release diff itself never touches the file.
+ */
 export function evaluate(
     oldLines: readonly string[],
     newLines: readonly string[],
     indexChanged: boolean,
     overridden: boolean,
+    indexed: ReadonlySet<string> = new Set(),
 ): CheckResult {
     const addedMajors = added_released_breaking_majors(oldLines, newLines);
-    const violation = addedMajors.length > 0 && !indexChanged && !overridden;
-    return { addedMajors, indexChanged, overridden, violation };
+    const unindexedMajors = addedMajors.filter((v) => !indexed.has(v));
+    const violation = unindexedMajors.length > 0 && !indexChanged && !overridden;
+    return { addedMajors, unindexedMajors, indexChanged, overridden, violation };
 }
 
 // ─── git helpers (CLI only) ──────────────────────────────────────────────────
@@ -267,12 +291,21 @@ function main(argv?: readonly string[]): number {
     const log = _git('log', '--format=%B', `${base}..HEAD`);
     const overridden = OVERRIDE_RE.test(log) || process.env['BREAKING_INDEX_OVERRIDE'] === '1';
 
-    const result = evaluate(oldLines, newLines, indexChanged, overridden);
+    const indexPath = path.join(REPO_ROOT, INDEX_REL);
+    const indexed = fs.existsSync(indexPath)
+        ? indexed_majors(_splitlines(fs.readFileSync(indexPath, 'utf-8')))
+        : new Set<string>();
+
+    const result = evaluate(oldLines, newLines, indexChanged, overridden, indexed);
 
     if (!result.violation) {
         if (!args.quiet) {
             if (result.addedMajors.length > 0) {
-                const why = result.overridden ? 'override' : `${INDEX_REL} updated`;
+                const why = result.indexChanged
+                    ? `${INDEX_REL} updated`
+                    : result.unindexedMajors.length === 0
+                      ? `an existing ${INDEX_REL} row`
+                      : 'override';
                 process.stdout.write(
                     `✅ lint-breaking-changes-index: ${result.addedMajors.length} released ` +
                         `BREAKING addition(s), cleared by ${why}\n`,
@@ -290,7 +323,7 @@ function main(argv?: readonly string[]): number {
         `❌ lint-breaking-changes-index: released BREAKING entr(y/ies) added to ${CHANGELOG_REL} ` +
             `without a matching ${INDEX_REL} change:\n`,
     );
-    for (const v of result.addedMajors) {
+    for (const v of result.unindexedMajors) {
         process.stderr.write(`   - ## [${v}] gained a ### BREAKING section\n`);
     }
     process.stderr.write(

package/src/scripts/lint_consolidation_lineage.ts

@@ -44,6 +44,15 @@
  *                       parent set does not name.
  * - `missing-parent`    a declared parent with no matching file — the lineage
  *                       names something nobody can open.
+ * - `unresolvable-parent`  a declared parent named only in prose: no slug, so
+ *                       no file could ever match it. Distinct from
+ *                       `missing-parent`, which sends the reader looking for a
+ *                       file.
+ *
+ * A sibling that declares itself DOWNSTREAM of the consolidating file
+ * (`supersedes:`, `supersedes_proposals:`, or a `relates:` entry with
+ * `relation: extends`) is a successor, not an omission, and is not reported
+ * as `omitted-sibling`.
  * - `overlapping-sets`  two artifacts in one folder declaring overlapping parent
  *                       sets while neither names the other: an artifact that
  *                       reads as the settled answer while a peer of equal
@@ -121,7 +130,7 @@ export interface Declaration {
 }
 
 export interface Finding {
-    code: 'omitted-sibling' | 'missing-parent' | 'overlapping-sets' | 'claims-without-field';
+    code: 'omitted-sibling' | 'missing-parent' | 'unresolvable-parent' | 'overlapping-sets' | 'claims-without-field';
     folder: string;
     file: string;
     detail: string;
@@ -134,16 +143,23 @@ export interface Finding {
  * with or without `.md`, with a download-collision `(1)` suffix, and followed by
  * arbitrary prose (`road-to-gated-self-evolution` v3 (Claude-Session) — P0–P7).
  * Everything after the first token is commentary.
+ *
+ * A YAML scalar may also arrive quoted. One matching pair of wrapping quotes is
+ * removed — around the whole input and around the selected token — and nothing
+ * else, so an apostrophe inside a slug survives (D6 of
+ * road-to-gates-that-read-what-was-written). Callers pass the raw value.
  */
 export function normalizeParent(raw: string): string {
     let s = raw.trim();
     s = s.replace(/^[-*]\s+/, '');
+    s = unwrapQuotes(s, true);
     const tick = /`([^`]+)`/.exec(s);
     if (tick) {
         s = tick[1] as string;
     } else {
         s = (s.split(/[\s—–,;|]/)[0] ?? '').trim();
     }
+    s = unwrapQuotes(s, false);
     s = s.replace(/^.*\//, '');
     s = s.replace(/\.md$/i, '');
     s = s.replace(/\(\d+\)$/, '');
@@ -154,6 +170,19 @@ export function normalizeParent(raw: string): string {
     return s;
 }
 
+/**
+ * Remove one matching pair of wrapping quotes. With `whole`, the pair must be
+ * the only occurrence of that quote character: `"a" — "b"` is two quoted
+ * strings, not one, and unwrapping it would glue a quote onto the first token.
+ */
+function unwrapQuotes(s: string, whole: boolean): string {
+    const q = s[0];
+    if (s.length < 2 || (q !== '"' && q !== "'") || s[s.length - 1] !== q) return s;
+    const inner = s.slice(1, -1);
+    if (whole && inner.includes(q)) return s;
+    return inner.trim();
+}
+
 function frontmatterList(fm: string, key: string): string[] | null {
     const lines = fm.split(/\r?\n/);
     const head = new RegExp(`^${key}:\\s*(.*)$`);
@@ -165,7 +194,7 @@ function frontmatterList(fm: string, key: string): string[] | null {
             return inline
                 .slice(1, inline.lastIndexOf(']') === -1 ? undefined : inline.lastIndexOf(']'))
                 .split(',')
-                .map((x) => normalizeParent(x.replace(/["']/g, '')))
+                .map((x) => normalizeParent(x))
                 .filter(Boolean);
         }
         const out: string[] = [];
@@ -185,6 +214,82 @@ function frontmatterList(fm: string, key: string): string[] | null {
     return null;
 }
 
+/**
+ * The `relates:` entries of a frontmatter block that carry a DOWNSTREAM
+ * relation, as `{slug}` stems.
+ *
+ * Only `extends` is directional by declaration in the measured corpus; a
+ * generic `relates` names a neighbour without saying which came first, and
+ * reading it as succession would suppress real omissions. AI council
+ * 2026-10-16 (anthropic + openai, convergent): an allowlist of one, widened
+ * only on evidence that another relation value states a direction.
+ */
+const DOWNSTREAM_RELATIONS: ReadonlySet<string> = new Set(['extends']);
+
+function downstreamRelates(fm: string): string[] {
+    const lines = fm.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^relates:\s*$/.test(l));
+    if (start === -1) return [];
+    const out: string[] = [];
+    let slug: string | null = null;
+    const flush = (relation: string | null): void => {
+        if (slug && relation && DOWNSTREAM_RELATIONS.has(relation)) out.push(normalizeParent(slug));
+    };
+    let relation: string | null = null;
+    for (let j = start + 1; j < lines.length; j += 1) {
+        const line = lines[j] as string;
+        if (line.trim() === '' || /^\s*#/.test(line)) continue;
+        if (!/^\s/.test(line)) break;
+        const head = /^\s+-\s+(.*)$/.exec(line);
+        const body = head ? (head[1] as string) : line.trim();
+        if (head) {
+            flush(relation);
+            slug = null;
+            relation = null;
+        }
+        const kv = /^(slug|relation):\s*(.*)$/.exec(body);
+        if (!kv) continue;
+        const value = unwrapQuotes((kv[2] as string).replace(/#.*$/, '').trim(), false);
+        if (kv[1] === 'slug') slug = value;
+        else relation = value;
+    }
+    flush(relation);
+    return out.filter(Boolean);
+}
+
+/**
+ * The stems this artifact declares itself DOWNSTREAM of: a supersession key
+ * (`supersedes:`, `supersedes_proposals:`) or a `relates:` entry with a
+ * directional relation. A sibling that names the consolidating file here was
+ * written knowing it, so it is a successor, never an undiscussed parent.
+ * Keyed on explicit declaration only — never on dates or file order.
+ */
+export function downstreamOf(text: string): string[] {
+    const fmMatch = FM_RE.exec(text);
+    if (!fmMatch) return [];
+    const fm = fmMatch[1] as string;
+    return [
+        ...(frontmatterList(fm, 'supersedes') ?? []),
+        ...(frontmatterList(fm, 'supersedes_proposals') ?? []),
+        ...downstreamRelates(fm),
+    ];
+}
+
+/**
+ * Whether a declared parent that resolves to no file is at least slug-shaped.
+ *
+ * A separator-joined name (`road-to-x`, `deep-plan-2026-09-30`) is a file
+ * somebody can be sent to look for: `missing-parent`. A single word — the
+ * first word of a prose title, `AC` — names no file at all, and reporting it as
+ * missing sends the reader hunting for one: `unresolvable-parent`.
+ *
+ * The council suggested a lowercase `road-to-*` grammar. It is widened on two
+ * measured facts: a non-roadmap parent is a supported shape (see
+ * analyseFolder's `present`), and the archived estate carries roadmap names
+ * with dots and capitals (`road-to-6.0.0-…`, `…-HUMAN-MEASUREMENT`).
+ */
+const SLUG_RE = /^[A-Za-z0-9._]+(?:[-_][A-Za-z0-9._]+)+$/;
+
 /** A prose `**Label:**` heading followed by a `- ` bullet list. */
 function proseList(body: string, label: RegExp): string[] | null {
     const lines = body.split(/\r?\n/);
@@ -276,6 +381,8 @@ interface Artifact {
     stem: string;
     file: string;
     decl: Declaration;
+    /** Stems this artifact declares itself a successor of — see downstreamOf. */
+    downstream: string[];
 }
 
 /**
@@ -313,18 +420,25 @@ export function analyseFolder(
     surface: Surface = 'inbox',
 ): Finding[] {
     const findings: Finding[] = [];
-    let names: string[];
+    let entries: string[];
     try {
-        names = fs.readdirSync(dir).filter((n) => ROADMAP_RE.test(n)).sort();
+        entries = fs.readdirSync(dir);
     } catch {
         return findings;
     }
-    const artifacts: Artifact[] = names.map((n) => ({
-        stem: n.replace(/\.md$/i, ''),
-        file: n,
-        decl: parseDeclaration(fs.readFileSync(path.join(dir, n), 'utf-8'), surface),
-    }));
-    const present = new Set(artifacts.map((a) => a.stem));
+    const names = entries.filter((n) => ROADMAP_RE.test(n)).sort();
+    const artifacts: Artifact[] = names.map((n) => {
+        const text = fs.readFileSync(path.join(dir, n), 'utf-8');
+        return {
+            stem: n.replace(/\.md$/i, ''),
+            file: n,
+            decl: parseDeclaration(text, surface),
+            downstream: downstreamOf(text),
+        };
+    });
+    // A parent need not be named road-to-*: a dated deep-dive plan is a parent
+    // too, and only its absence makes it missing.
+    const present = new Set(entries.filter((n) => /\.md$/i.test(n)).map((n) => n.replace(/\.md$/i, '')));
 
     for (const a of artifacts) {
         if (a.decl.unparseable) {
@@ -339,18 +453,35 @@ export function analyseFolder(
         if (a.decl.parents.length === 0) continue;
 
         for (const p of a.decl.parents) {
-            if (!present.has(p)) {
-                findings.push({
-                    code: 'missing-parent',
-                    folder: folderLabel,
-                    file: a.file,
-                    detail: `declares parent \`${p}\` but no such file is present`,
-                });
-            }
+            if (present.has(p)) continue;
+            findings.push(
+                SLUG_RE.test(p)
+                    ? {
+                          code: 'missing-parent',
+                          folder: folderLabel,
+                          file: a.file,
+                          detail: `declares parent \`${p}\` but no such file is present`,
+                      }
+                    : {
+                          code: 'unresolvable-parent',
+                          folder: folderLabel,
+                          file: a.file,
+                          detail: `declares a parent named only in prose (normalised to \`${p}\`) — no slug, so no file can match; name it by slug`,
+                      },
+            );
         }
         const omitted =
             surface === 'inbox'
-                ? artifacts.filter((b) => b.stem !== a.stem && !a.decl.parents.includes(b.stem)).map((b) => b.stem)
+                ? artifacts
+                      .filter(
+                          (b) =>
+                              b.stem !== a.stem
+                              && !a.decl.parents.includes(b.stem)
+                              // A sibling declaring itself downstream of `a` is
+                              // a successor: `a` could not have discussed it.
+                              && !b.downstream.includes(a.stem),
+                      )
+                      .map((b) => b.stem)
                 : [];
         if (omitted.length > 0) {
             findings.push({

package/src/scripts/lint_consumer_internal_refs.ts

@@ -31,18 +31,18 @@
  *
  * Scope: every `dist/agent-src/skills/<name>/SKILL.md` — the consumer projection
  * actually shipped in the npm package (mirrors the reviewer's own vantage
- * point: `npm i` + read the installed skills).
+ * point: `npm i` + read the installed skills) — plus, for the skill-script
+ * form alone, `references/*.md` beside it.
  *
- * Carve-outs:
+ * The twenty-skill `SCRIPTS_RUN_ALLOWLIST` this gate used to carry is GONE.
+ * It exempted the one form that most needed the finding: a line telling a
+ * consumer to type a wrapper the package does not ship. The skills now teach
+ * `node <skills-root>/<name>/scripts/<tool>.mjs`, which an install can start,
+ * so the exemption has nothing left to exempt.
+ *
+ * Carve-out:
  *   - Skill frontmatter `workspaces: [agent-config-maintainer]` (exclusive)
  *     — entirely exempt, per the mechanism above.
- *   - `SCRIPTS_RUN_ALLOWLIST` below — the `corpus-grounding` engine's own
- *     documented consumer-runtime CLI convention (`./scripts-run
- *     <skills-root>/<name>/scripts/<tool> …`, skill-bundled assets per
- *     `docs/contracts/skill-bundled-assets.md`) — the invoked PATH is real
- *     and reachable in every install; only the wrapper name is inherited
- *     from the maintainer dispatcher. Tracked as a separate, larger-scope
- *     naming-consistency item; out of scope for this lint's 17-skill sweep.
  *
  * Exit codes: 0 clean · 1 findings · 2 internal error.
  */
@@ -57,38 +57,6 @@ import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const SKILLS_DIR = path.join(REPO_ROOT, 'dist', 'agent-src', 'skills');
 
-/**
- * Skills using `corpus-grounding`'s documented `./scripts-run
- * <skills-root>/<name>/scripts/<tool>` consumer-runtime CLI convention
- * (skill-bundled assets, `docs/contracts/skill-bundled-assets.md`) — the
- * path is real and reachable once installed; only the wrapper name drifted
- * from the contract's prescribed `node_modules/.bin/tsx` form. A single,
- * uniform, cross-skill convention — renaming it is a separate, larger-scope
- * follow-up, not one of this sweep's 17 leaky skills.
- */
-const SCRIPTS_RUN_ALLOWLIST = new Set([
-    'accessibility-auditor',
-    'api-design',
-    'api-endpoint',
-    'authz-review',
-    'blade-ui',
-    'brand',
-    'brand-identity',
-    'brand-strategy',
-    'brand-to-tokens',
-    'corpus-grounding',
-    'dashboard-design',
-    'database',
-    'design-intelligence',
-    'design-tokens',
-    'flux',
-    'livewire',
-    'react-shadcn-ui',
-    'sql-writing',
-    'threat-modeling',
-    'typography-system',
-]);
-
 interface PatternDef {
     readonly re: RegExp;
     readonly label: string;
@@ -120,10 +88,73 @@ const PATTERNS: readonly PatternDef[] = [
     {
         re: /\.\/scripts-run\b/,
         label: 'invocation of the maintainer-only `./scripts-run` dispatcher (not in `package.json` `files`, never reaches a consumer install)',
-        allowlist: SCRIPTS_RUN_ALLOWLIST,
+    },
+    {
+        re: /node_modules\/\.bin\/tsx\b/,
+        label: 'invocation through `node_modules/.bin/tsx` (a devDependency binary; an install carries `node`, not a TypeScript loader)',
     },
 ];
 
+/**
+ * The skill-script form: `<runner> <skills-root>/<skill>/scripts/<tool>`.
+ *
+ * Checked apart from PATTERNS because the runner is not always on the line
+ * that carries the path — a wrapped command leaves it at the end of the line
+ * above, and a per-line regex reading only its own line reports every wrapped
+ * invocation in the tree.
+ *
+ * It is also the one form checked inside `references/`. A blanket widening
+ * would red on the reference files that name `./scripts-run src/scripts/…`,
+ * which is a different class — a maintainer script, invoked while working on
+ * this package — and this gate is not the place that decides those.
+ */
+const SKILL_SCRIPT_RE = /<skills-root>\/([A-Za-z0-9._-]+)\/scripts\/([A-Za-z0-9._-]+)/;
+const SKILL_SCRIPT_RUNNER = 'node';
+
+/** The last shell-ish token of a markdown fragment, decoration stripped. */
+function lastToken(fragment: string): string {
+    const cleaned = fragment.replace(/\\\s*$/, '').replace(/[`\s]+$/, '').trim();
+    if (cleaned === '') return '';
+    return (cleaned.split(/\s+/).pop() ?? '').replace(/^[`>*_(]+/, '').replace(/[`*_)]+$/, '');
+}
+
+/** The runner a taught line names: its own, or the one the line above ends with. */
+function runnerFor(lines: readonly string[], idx: number, col: number): string {
+    const before = (lines[idx] as string).slice(0, col);
+    const own = lastToken(before.replace(/^[\s>]*(?:[-*+]\s+|\d+\.\s+)?/, ''));
+    if (own !== '') return own;
+    if (idx === 0) return '';
+    const above = lines[idx - 1] as string;
+    if (/^\s*(?:```|~~~)/.test(above)) return '';
+    return lastToken(above);
+}
+
+/** Findings for taught skill-script lines that a node-only install cannot start. */
+export function scanSkillScriptForm(relPath: string, text: string): string[] {
+    const findings: string[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = SKILL_SCRIPT_RE.exec(lines[i] as string);
+        if (!m) continue;
+        const tool = m[2] as string;
+        const runner = runnerFor(lines, i, m.index);
+        if (runner !== SKILL_SCRIPT_RUNNER) {
+            findings.push(
+                `${relPath}:${i + 1}: skill-script line whose runner is ` +
+                    `${runner === '' ? 'absent' : `\`${runner}\``}, not \`node\` — ` +
+                    'an install carries the runtime and the bundle, nothing else',
+            );
+        }
+        if (!tool.endsWith('.mjs')) {
+            findings.push(
+                `${relPath}:${i + 1}: skill-script line naming \`${tool}\` — ` +
+                    'the shipped entry point is the `.mjs` beside the source',
+            );
+        }
+    }
+    return findings;
+}
+
 /** `workspaces:` frontmatter list of a skill file ([] when untagged). */
 function skillWorkspaces(skillPath: string): string[] {
     const src = fs.readFileSync(skillPath, 'utf-8');
@@ -191,6 +222,23 @@ export function main(): number {
         }
         const relPath = path.relative(REPO_ROOT, abs);
         findings.push(...scanText(name, relPath, text));
+        findings.push(...scanSkillScriptForm(relPath, text));
+
+        // `references/` is read for the skill-script form only — see the note
+        // above `SKILL_SCRIPT_RE` for why the other patterns stop at SKILL.md.
+        const refsDir = path.join(SKILLS_DIR, name, 'references');
+        if (!fs.existsSync(refsDir) || !fs.statSync(refsDir).isDirectory()) continue;
+        for (const ref of fs.readdirSync(refsDir).sort()) {
+            if (!ref.endsWith('.md')) continue;
+            const refAbs = path.join(refsDir, ref);
+            let refText: string;
+            try {
+                refText = fs.readFileSync(refAbs, 'utf-8');
+            } catch {
+                continue;
+            }
+            findings.push(...scanSkillScriptForm(path.relative(REPO_ROOT, refAbs), refText));
+        }
     }
 
     // Counted BEFORE the maintainer-exclusive skip, so an all-maintainer