@givolt/i3-composer-agent 2.0.0 → 2.1.1

package/scripts/validate-reference-links-test.js

@@ -1,495 +0,0 @@
-#!/usr/bin/env node
-
-'use strict';
-
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-const { afterEach, test } = require('node:test');
-
-const VALIDATOR = path.join(__dirname, 'validate-reference-links.js');
-const sandboxes = [];
-
-function makeSandbox() {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-validate-reference-links-test-'));
-  const scriptsDir = path.join(root, 'scripts');
-  fs.mkdirSync(scriptsDir, { recursive: true });
-  fs.copyFileSync(VALIDATOR, path.join(scriptsDir, 'validate-reference-links.js'));
-  fs.mkdirSync(path.join(scriptsDir, 'lib'));
-  fs.copyFileSync(path.join(__dirname, 'lib', 'skill-lint.js'), path.join(scriptsDir, 'lib', 'skill-lint.js'));
-  sandboxes.push(root);
-  return root;
-}
-
-function writeFile(root, relativePath, content) {
-  const file = path.join(root, relativePath);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, content);
-}
-
-function run(root) {
-  return spawnSync(process.execPath, [path.join(root, 'scripts', 'validate-reference-links.js')], {
-    cwd: root,
-    encoding: 'utf8',
-  });
-}
-
-afterEach(() => {
-  for (const root of sandboxes.splice(0)) {
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test('passes when a skill reaches the shared checklist two levels up', () => {
-  const root = makeSandbox();
-  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
-  writeFile(
-    root,
-    'skills/i3-using-agent-skills/SKILL.md',
-    'See `../../references/definition-of-done.md`.\n'
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-test('fails when a skill links the shared checklist as if it were colocated', () => {
-  // The regression: references/ lives at the repo root, but the link is
-  // resolved from skills/<name>/, so it points two levels too deep.
-  const root = makeSandbox();
-  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
-  writeFile(
-    root,
-    'skills/i3-using-agent-skills/SKILL.md',
-    'See `references/definition-of-done.md`.\n'
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-  assert.match(
-    result.stdout,
-    /L1: references\/definition-of-done\.md — resolves to skills\/i3-using-agent-skills\/references\/definition-of-done\.md/
-  );
-  assert.match(result.stdout, /use `\.\.\/\.\.\/references\/<file>\.md`/);
-});
-
-test('checks markdown link syntax, not just backtick mentions', () => {
-  const root = makeSandbox();
-  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
-  writeFile(root, 'skills/i3-using-agent-skills/SKILL.md', 'See [DoD](references/definition-of-done.md).\n');
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /L1: references\/definition-of-done\.md/);
-});
-
-test('passes when a skill colocates its own references directory', () => {
-  // CLAUDE.md allows self-contained skills to keep references under
-  // skills/<name>/references/. Those links are correct as written.
-  const root = makeSandbox();
-  writeFile(root, 'skills/dataviz/references/palette.md', '# Palette\n');
-  writeFile(root, 'skills/dataviz/SKILL.md', 'See `references/palette.md`.\n');
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-test('passes when a skill reference file reaches the shared checklist three levels up', () => {
-  // A file under skills/<name>/references/ sits one directory deeper than
-  // SKILL.md, so the shared checklists are three levels up from it, not two.
-  const root = makeSandbox();
-  writeFile(root, 'references/security-checklist.md', '# Security\n');
-  writeFile(root, 'skills/hardening/SKILL.md', 'See [patterns](references/patterns.md).\n');
-  writeFile(
-    root,
-    'skills/hardening/references/patterns.md',
-    'Shared checklists live in `../../../references/security-checklist.md`.\n'
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /✓ {2}skills\/hardening\/references\/patterns\.md/);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-test('fails when a skill reference file links the shared checklist with the SKILL.md prefix', () => {
-  // The same off-by-a-level mistake this validator exists to catch, made from
-  // inside the skill's references/ directory: the link is resolved from the
-  // file that contains it, so `../../` stops at skills/.
-  const root = makeSandbox();
-  writeFile(root, 'references/security-checklist.md', '# Security\n');
-  writeFile(root, 'skills/hardening/SKILL.md', 'See [patterns](references/patterns.md).\n');
-  writeFile(
-    root,
-    'skills/hardening/references/patterns.md',
-    ['# Patterns', '', 'See `../../references/security-checklist.md`.', ''].join('\n')
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /✓ {2}skills\/hardening\/SKILL\.md/);
-  assert.match(result.stdout, /✗ {2}skills\/hardening\/references\/patterns\.md/);
-  assert.match(
-    result.stdout,
-    /L3: \.\.\/\.\.\/references\/security-checklist\.md — resolves to skills\/references\/security-checklist\.md/
-  );
-  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-  assert.match(result.stdout, /use `\.\.\/\.\.\/\.\.\/references\/<file>\.md`/);
-});
-
-test('keeps the same narrow rule inside a skill reference file', () => {
-  // Same exemptions as SKILL.md: fenced examples, sibling files named without
-  // a references/ prefix, and artifacts that do not exist yet.
-  const root = makeSandbox();
-  writeFile(root, 'references/security-checklist.md', '# Security\n');
-  writeFile(root, 'skills/hardening/SKILL.md', 'See [patterns](references/patterns.md).\n');
-  writeFile(
-    root,
-    'skills/hardening/references/patterns.md',
-    [
-      'Record findings in `SECURITY.md` or `docs/threat-model.md`. See also `other-patterns.md`.',
-      '',
-      '```markdown',
-      '[wrong on purpose](../../references/security-checklist.md)',
-      '```',
-      '',
-    ].join('\n')
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-test('counts errors from SKILL.md and its reference files together', () => {
-  const root = makeSandbox();
-  writeFile(root, 'references/security-checklist.md', '# Security\n');
-  writeFile(root, 'skills/hardening/SKILL.md', 'See `references/security-checklist.md`.\n');
-  writeFile(root, 'skills/hardening/references/a.md', 'See `../../references/security-checklist.md`.\n');
-  writeFile(root, 'skills/hardening/references/b.md', 'See `../../../references/security-checklist.md`.\n');
-  writeFile(root, 'skills/hardening/references/notes.txt', 'See ../../references/security-checklist.md\n');
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /✗ {2}skills\/hardening\/references\/a\.md/);
-  assert.match(result.stdout, /✓ {2}skills\/hardening\/references\/b\.md/);
-  assert.doesNotMatch(result.stdout, /notes\.txt/);
-  assert.match(result.stdout, /1 skills checked — 2 error\(s\) — FAILED/);
-});
-
-test('fails when a link points at a checklist that no longer exists', () => {
-  const root = makeSandbox();
-  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
-  writeFile(root, 'skills/i3-shipping-and-launch/SKILL.md', 'See `../../references/renamed.md`.\n');
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /L1: \.\.\/\.\.\/references\/renamed\.md/);
-  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-});
-
-test('ignores paths that are not references/ links', () => {
-  // Skills legitimately name artifacts the user has yet to create. Widening
-  // this validator into a general markdown linter would fail the build on them.
-  const root = makeSandbox();
-  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
-  writeFile(
-    root,
-    'skills/i3-planning-and-task-breakdown/SKILL.md',
-    [
-      'Save the task list to `tasks/todo.md` and the plan to `tasks/plan.md`.',
-      'Record findings in `PERF.md` or `docs/ideas/[idea-name].md`.',
-      'Related: `skills/i3-incremental-implementation/SKILL.md`.',
-      'See `../../references/definition-of-done.md`.',
-      '',
-    ].join('\n')
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-test('reports every unresolvable link, not just the first per skill', () => {
-  const root = makeSandbox();
-  writeFile(root, 'references/security-checklist.md', '# Security\n');
-  writeFile(root, 'references/performance-checklist.md', '# Performance\n');
-  writeFile(
-    root,
-    'skills/i3-code-review-and-quality/SKILL.md',
-    ['See `references/security-checklist.md`.', 'And `references/performance-checklist.md`.', ''].join('\n')
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 2 error\(s\) — FAILED/);
-});
-
-test('a link inside a fenced block is an example, not a link to resolve', () => {
-  const root = makeSandbox();
-  writeFile(root, 'references/definition-of-done.md', '# DoD\n');
-  writeFile(
-    root,
-    'skills/i3-using-agent-skills/SKILL.md',
-    [
-      'Shared checklists live two levels up:',
-      '',
-      'See `../../references/definition-of-done.md`.',
-      '',
-      'Do not write it this way:',
-      '',
-      '```markdown',
-      '[Definition of Done](references/definition-of-done.md)',
-      '```',
-      '',
-    ].join('\n')
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-test('fence exemption follows CommonMark rather than a bare ``` match', () => {
-  const root = makeSandbox();
-  writeFile(
-    root,
-    'skills/i3-using-agent-skills/SKILL.md',
-    [
-      '~~~markdown',
-      '[a](references/missing-a.md)',
-      '```',                                  // wrong marker: must not close the ~~~ block
-      '[b](references/missing-b.md)',
-      '~~~',
-      '',
-      '   ```markdown',                       // three-space indent is still a fence
-      '[c](references/missing-c.md)',
-      '   `````',                             // a longer closer is legal
-      '',
-    ].join('\n')
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /0 error\(s\) — PASSED/);
-});
-
-test('a real broken link outside any fence is still reported', () => {
-  const root = makeSandbox();
-  writeFile(
-    root,
-    'skills/i3-using-agent-skills/SKILL.md',
-    [
-      '```markdown',
-      '[shown as an example](references/example-only.md)',
-      '```',
-      '',
-      'See `references/definition-of-done.md`.',   // genuinely wrong, outside the fence
-      '',
-    ].join('\n')
-  );
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-  assert.match(result.stdout, /L5: references\/definition-of-done\.md/);
-});
-
-for (const [ending, newline] of [['LF', '\n'], ['CRLF', '\r\n']]) {
-  test(`inline backticks do not hide subsequent broken links (${ending})`, () => {
-    const root = makeSandbox();
-    writeFile(root, 'skills/example/SKILL.md', [
-      '```js``` is inline code, not a fence opener.',
-      'See [missing](references/missing.md).',
-      '',
-    ].join(newline));
-
-    const result = run(root);
-
-    assert.equal(result.status, 1, result.stdout + result.stderr);
-    assert.match(result.stdout, /L2: references\/missing\.md/);
-    assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-  });
-
-  for (const marker of ['```', '~~~']) {
-    test(`trailing text does not close a ${marker} fence (${ending})`, () => {
-      const root = makeSandbox();
-      writeFile(root, 'skills/example/SKILL.md', [
-        marker + 'markdown',
-        marker + ' still part of the example',
-        '[example](references/example-only.md)',
-        marker + ' \t',
-        '[real link](references/missing.md)',
-        '',
-      ].join(newline));
-
-      const result = run(root);
-
-      assert.equal(result.status, 1, result.stdout + result.stderr);
-      assert.match(result.stdout, /L5: references\/missing\.md/);
-      assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-      assert.doesNotMatch(result.stdout, /example-only\.md/);
-    });
-  }
-}
-
-test('tilde fence info strings may contain backticks', () => {
-  const root = makeSandbox();
-  writeFile(root, 'skills/example/SKILL.md', [
-    '~~~example `code`',
-    '[example](references/example-only.md)',
-    '~~~',
-    '',
-  ].join('\n'));
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-// Anchors. A `#fragment` after a references/ link must match a heading in the
-// target file, slugged the way GitHub does it. Without this, renaming a heading
-// silently breaks every link to it while the file itself still exists.
-
-function hardeningSkill(root, link) {
-  writeFile(root, 'skills/hardening/SKILL.md', `See [patterns](${link}).\n`);
-}
-
-test('passes when an anchor matches a heading in the target file', () => {
-  const root = makeSandbox();
-  hardeningSkill(root, 'references/patterns.md#cross-site-scripting-xss');
-  writeFile(root, 'skills/hardening/references/patterns.md', '# Patterns\n\n## Cross-Site Scripting (XSS)\n');
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
-});
-
-test('fails when an anchor matches no heading in the target file', () => {
-  // The file exists, so the existing check is satisfied; only the fragment is stale.
-  const root = makeSandbox();
-  hardeningSkill(root, 'references/patterns.md#injection');
-  writeFile(root, 'skills/hardening/references/patterns.md', '# Patterns\n\n## Injection attacks\n');
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(
-    result.stdout,
-    /L1: references\/patterns\.md#injection — no heading in skills\/hardening\/references\/patterns\.md produces #injection/
-  );
-  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-  assert.match(result.stdout, /GitHub's heading slugs/);
-  // The path was right, so the path hint would only mislead.
-  assert.doesNotMatch(result.stdout, /use `\.\.\/\.\.\/references/);
-});
-
-test('a repeated heading gets a -1 suffix, as on GitHub', () => {
-  const root = makeSandbox();
-  writeFile(root, 'skills/hardening/SKILL.md', [
-    'See [first](references/patterns.md#example).',
-    'See [second](references/patterns.md#example-1).',
-    'See [third](references/patterns.md#example-2).',
-    '',
-  ].join('\n'));
-  writeFile(root, 'skills/hardening/references/patterns.md', '## Example\n\n## Example\n');
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /L3: references\/patterns\.md#example-2 — no heading/);
-  assert.doesNotMatch(result.stdout, /L[12]:/);
-  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-});
-
-test('slugs come from the rendered heading text, not its markdown', () => {
-  // Real headings in the pack carry emphasis, code spans and links.
-  const root = makeSandbox();
-  writeFile(root, 'skills/hardening/SKILL.md', [
-    'See [a](references/patterns.md#why-this-is-not-a-ship-job).',
-    'See [b](references/patterns.md#owasp-top-10).',
-    'See [c](references/patterns.md#snake_case-names-stay).',
-    'See [d](references/patterns.md#closing-hashes).',
-    '',
-  ].join('\n'));
-  writeFile(root, 'skills/hardening/references/patterns.md', [
-    '### Why this is *not* a `/ship` job',
-    '## [OWASP](https://owasp.org/Top10/) Top 10',
-    '## snake_case names stay',
-    '## Closing hashes ##',
-    '',
-  ].join('\n'));
-
-  const result = run(root);
-
-  assert.equal(result.status, 0, result.stdout + result.stderr);
-});
-
-test('a heading-like line inside a fenced block is not an anchor', () => {
-  // Bash comments in a fenced example look like H1s.
-  const root = makeSandbox();
-  hardeningSkill(root, 'references/patterns.md#chrome-devtools');
-  writeFile(root, 'skills/hardening/references/patterns.md', [
-    '# Patterns',
-    '',
-    '```bash',
-    '# Chrome DevTools',
-    '```',
-    '',
-  ].join('\n'));
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /#chrome-devtools — no heading/);
-});
-
-test('anchors resolve from a reference file to a shared checklist', () => {
-  const root = makeSandbox();
-  writeFile(root, 'references/security-checklist.md', '# Security\n\n## OWASP Top 10 Quick Reference\n');
-  hardeningSkill(root, 'references/patterns.md');
-  writeFile(root, 'skills/hardening/references/patterns.md', [
-    'See `../../../references/security-checklist.md#owasp-top-10-quick-reference`.',
-    'See `../../../references/security-checklist.md#destructive-path-operations`.',
-    '',
-  ].join('\n'));
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /✗ {2}skills\/hardening\/references\/patterns\.md/);
-  assert.match(result.stdout, /L2: \.\.\/\.\.\/\.\.\/references\/security-checklist\.md#destructive-path-operations — no heading in references\/security-checklist\.md/);
-  assert.doesNotMatch(result.stdout, /L1:/);
-});
-
-test('a missing file is reported once, not again for its anchor', () => {
-  const root = makeSandbox();
-  hardeningSkill(root, 'references/renamed.md#injection');
-
-  const result = run(root);
-
-  assert.equal(result.status, 1, result.stdout + result.stderr);
-  assert.match(result.stdout, /L1: references\/renamed\.md — resolves to skills\/hardening\/references\/renamed\.md, which does not exist/);
-  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
-});

package/scripts/validate-reference-links.js

@@ -1,187 +0,0 @@
-#!/usr/bin/env node
-/**
- * validate-reference-links.js
- *
- * Guards links from skills to the shared `references/` checklists.
- *
- * Those checklists live in the repo-root `references/` directory, but every
- * SKILL.md used to link them as `references/<file>.md` — a path relative to
- * the skill's own directory, which is two levels below the root. All 18 links
- * across 11 skills resolved to files that do not exist, in the repo and in
- * every plugin-install layout (~/.claude/plugins/cache/..., ~/.codex/...).
- * Agents that followed the guidance — for example i3-using-agent-skills pointing
- * at the Definition of Done — hit a file-not-found and stalled.
- *
- * Nothing else in CI catches this: validate-artifact-paths.js is scoped to
- * spec/plan/todo artifacts and is explicitly not a general markdown linter.
- *
- * The rule enforced here: every `references/*.md` link in a SKILL.md must
- * resolve to an existing file relative to that skill's own directory. This
- * accepts both conventions in CLAUDE.md — shared checklists reached via
- * `../../references/`, and a skill's own colocated `references/` directory.
- *
- * The markdown files inside a skill's own `references/` directory get the
- * same check, with each link resolved from the file that contains it. They
- * sit one directory deeper than SKILL.md, so from there the shared checklists
- * are `../../../references/`: the same off-by-a-level mistake, one level down.
- *
- * A `#fragment` after such a link must match a heading in the target file,
- * slugged the way GitHub renders anchors. The file existing is not enough:
- * renaming a heading breaks every link to it while the path still resolves.
- *
- * Scope is deliberately narrow: only `references/*.md` links, only SKILL.md
- * and `skills/<name>/references/*.md` files. It is not a general markdown
- * path linter — skills legitimately mention paths that do not exist yet
- * (`tasks/todo.md`, `PERF.md`, `docs/ideas/[idea-name].md`), and those must
- * not fail the build.
- *
- * Fenced code blocks are exempt for the same reason. Text inside a fence is
- * an example, not a link an agent will follow — and this rule in particular
- * has to be documentable: the failure message below tells authors to write
- * `../../references/<file>.md` rather than `references/<file>.md`, which no
- * skill could show as an example without failing the very check explaining it.
- *
- * Exit codes: 0 = all clear, 1 = one or more unresolvable links.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { stripFencedCodeBlocks } = require('./lib/skill-lint');
-
-const ROOT = path.resolve(__dirname, '..');
-const SKILLS_DIR = path.join(ROOT, 'skills');
-
-// Matches a link to a references/ markdown file, with any number of leading
-// `../` segments: `references/x.md`, `../../references/x.md`. Anchored on a
-// non-path character so `myreferences/x.md` does not match. An optional
-// `#fragment` is captured separately.
-const REFERENCE_LINK_RE = /(?<![A-Za-z0-9._/-])((?:\.\.\/)*references\/[A-Za-z0-9._-]+\.md)(?:#([\p{L}\p{N}_-]+))?/gu;
-
-// GitHub's heading anchor: the rendered text, lowercased, with everything but
-// letters, numbers, `_`, `-` and spaces dropped, then spaces turned to hyphens.
-function slugify(heading) {
-  const text = heading
-    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // links and images keep their text
-    .replace(/<[^>]+>/g, '');                  // inline HTML renders no text
-  return text.toLowerCase().replace(/[^\p{L}\p{M}\p{N}_\- ]/gu, '').replace(/ /g, '-');
-}
-
-// The anchors a file's ATX headings produce, outside fenced blocks. A repeated
-// slug gets `-1`, `-2`, ... as on GitHub.
-function headingAnchors(file) {
-  const anchors = new Set();
-  const seen = new Map();
-  for (const line of stripFencedCodeBlocks(fs.readFileSync(file, 'utf8')).split('\n')) {
-    const match = line.match(/^ {0,3}#{1,6}[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/);
-    if (!match) continue;
-    const slug = slugify(match[1]);
-    const count = seen.get(slug) || 0;
-    anchors.add(count === 0 ? slug : `${slug}-${count}`);
-    seen.set(slug, count + 1);
-  }
-  return anchors;
-}
-
-// A link is resolved from the directory of the file that contains it.
-function findViolations(file) {
-  const violations = [];
-  const baseDir = path.dirname(file);
-  // Share the linter's fence rules; blanked lines preserve diagnostic positions.
-  const lines = stripFencedCodeBlocks(fs.readFileSync(file, 'utf8')).split('\n');
-
-  lines.forEach((line, i) => {
-    for (const match of line.matchAll(REFERENCE_LINK_RE)) {
-      const [, link, anchor] = match;
-      const target = path.resolve(baseDir, link);
-      if (!fs.existsSync(target)) {
-        violations.push({ line: i + 1, link, target });
-      } else if (anchor && !headingAnchors(target).has(anchor)) {
-        violations.push({ line: i + 1, link, target, anchor });
-      }
-    }
-  });
-
-  return violations;
-}
-
-// The markdown files directly inside a skill's own references/ directory.
-function skillReferenceFiles(skillDir) {
-  const dir = path.join(skillDir, 'references');
-  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
-  return fs.readdirSync(dir)
-    .filter((name) => name.endsWith('.md'))
-    .sort()
-    .map((name) => path.join(dir, name))
-    .filter((file) => fs.statSync(file).isFile());
-}
-
-function toPosix(file) {
-  return path.relative(ROOT, file).split(path.sep).join('/');
-}
-
-function main() {
-  console.log('Checking references/ links in skills...\n');
-
-  if (!fs.existsSync(SKILLS_DIR)) {
-    console.log('No skills/ directory — nothing to check.');
-    return;
-  }
-
-  let checked = 0;
-  let errors = 0;
-  let referenceFileErrors = 0;
-  let anchorErrors = 0;
-
-  const skillNames = fs.readdirSync(SKILLS_DIR).sort();
-  for (const name of skillNames) {
-    const skillDir = path.join(SKILLS_DIR, name);
-    const skillFile = path.join(skillDir, 'SKILL.md');
-    if (!fs.statSync(skillDir).isDirectory() || !fs.existsSync(skillFile)) continue;
-
-    checked++;
-    for (const file of [skillFile, ...skillReferenceFiles(skillDir)]) {
-      const violations = findViolations(file);
-
-      if (violations.length === 0) {
-        console.log(`  ✓  ${toPosix(file)}`);
-        continue;
-      }
-
-      console.log(`  ✗  ${toPosix(file)}`);
-      for (const { line, link, target, anchor } of violations) {
-        errors++;
-        if (anchor) {
-          console.log(`       L${line}: ${link}#${anchor} — no heading in ${toPosix(target)} produces #${anchor}`);
-          anchorErrors++;
-          continue;
-        }
-        console.log(`       L${line}: ${link} — resolves to ${toPosix(target)}, which does not exist`);
-        if (file !== skillFile) referenceFileErrors++;
-      }
-    }
-  }
-
-  const status = errors > 0 ? 'FAILED' : 'PASSED';
-  console.log(`\n${checked} skills checked — ${errors} error(s) — ${status}`);
-
-  if (errors > 0) {
-    if (errors > anchorErrors) {
-      console.log('\nLinks to references/ are resolved from the directory of the file that contains them.');
-      console.log('Shared checklists live in the repo-root references/, two levels up from a SKILL.md:');
-      console.log('use `../../references/<file>.md`, not `references/<file>.md`.');
-      if (referenceFileErrors > 0) {
-        console.log('From a file inside skills/<name>/references/ they are three levels up:');
-        console.log('use `../../../references/<file>.md`.');
-      }
-    }
-    if (anchorErrors > 0) {
-      console.log("\nAnchors are matched against GitHub's heading slugs: the heading text lowercased,");
-      console.log('punctuation dropped, spaces turned to hyphens, and -1, -2, ... for repeated headings.');
-    }
-    process.exit(1);
-  }
-}
-
-main();