From e782c3dd33aa3e87809cb039b7c34735bc5f6096 Mon Sep 17 00:00:00 2001
From: Gianluca Carucci <gianluca@carucci.org>
Date: Tue, 14 Jul 2026 10:59:17 +0200
Subject: [PATCH 1/2] [#209] refactor: consolidate gate/tooling scripts into
 @pair/dev-tools
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New @pair/dev-tools package holds the genuinely repo-wide, no-package-affinity
gates as tested TS modules (ADL 2026-07-13): code-hygiene-check (ported from
scripts/code-hygiene-check.js) and sync-version-in-docs (ported from
scripts/sync-version-in-docs.js). Both scripts deleted; root package.json and
version.yml delegate to the new package.

docs-staleness-check, skills-conformance-check, check-broken-links stay in
their owning packages (website, knowledge-hub) — each needs that package's
own context (docs tree, dataset), moving them would trade correct path
resolution for a deep relative reach into a sibling package's internals.

Also promotes skills-conformance's catalog-count check from WARN to hard
ERROR (TODO #313/T1) now that next correctly states 35 skills.

Refs: #209

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/version.yml                 |   2 +-
 package.json                                  |   3 +-
 packages/dev-tools/README.md                  |  20 ++
 packages/dev-tools/package.json               |  32 +++
 .../dev-tools/src/code-hygiene-check.test.ts  |  80 +++++++
 packages/dev-tools/src/code-hygiene-check.ts  | 135 ++++++++++++
 .../src/sync-version-in-docs.test.ts          | 163 ++++++++++++++
 .../dev-tools/src/sync-version-in-docs.ts     | 205 ++++++++++++++++++
 packages/dev-tools/tsconfig.json              |   6 +
 packages/dev-tools/vitest.config.ts           |  30 +++
 .../tools/skills-conformance-check.test.ts    |  10 +-
 .../src/tools/skills-conformance-check.ts     |  33 +--
 pnpm-lock.yaml                                |  33 +++
 scripts/code-hygiene-check.js                 |  63 ------
 scripts/sync-version-in-docs.js               | 112 ----------
 15 files changed, 723 insertions(+), 204 deletions(-)
 create mode 100644 packages/dev-tools/README.md
 create mode 100644 packages/dev-tools/package.json
 create mode 100644 packages/dev-tools/src/code-hygiene-check.test.ts
 create mode 100644 packages/dev-tools/src/code-hygiene-check.ts
 create mode 100644 packages/dev-tools/src/sync-version-in-docs.test.ts
 create mode 100644 packages/dev-tools/src/sync-version-in-docs.ts
 create mode 100644 packages/dev-tools/tsconfig.json
 create mode 100644 packages/dev-tools/vitest.config.ts
 delete mode 100644 scripts/code-hygiene-check.js
 delete mode 100644 scripts/sync-version-in-docs.js

diff --git a/.github/workflows/version.yml b/.github/workflows/version.yml
index 1f3c87b1..f7d9fd00 100644
--- a/.github/workflows/version.yml
+++ b/.github/workflows/version.yml
@@ -78,7 +78,7 @@ jobs:
           pnpm changeset version
 
           # Sync version into markdown/MDX files that hardcode it
-          node scripts/sync-version-in-docs.js "$OLD_CLI_VERSION"
+          pnpm sync-version -- "$OLD_CLI_VERSION"
 
           # Get new CLI version after changesets
           CLI_VERSION=$(node -e "console.log(require('./apps/pair-cli/package.json').version)")
diff --git a/package.json b/package.json
index 827e95be..8acaabe8 100644
--- a/package.json
+++ b/package.json
@@ -23,7 +23,8 @@
     "clean": "pnpm -w -r turbo prune && turbo clean && find . -type d \\( -name node_modules -o -name .turbo -o -name dist -o -name coverage \\) -exec rm -rf {} + 2>/dev/null || true; find . -type d -path './scripts/workflows/release' -prune -o -type d -name release -exec rm -rf {} + 2>/dev/null || true; find . -type f -name \"*tsbuildinfo\" -exec rm -f {} + 2>/dev/null || true",
     "a11y:report": "turbo a11y:report",
     "a11y:report:html": "turbo a11y:report:html",
-    "hygiene:check": "node scripts/code-hygiene-check.js",
+    "hygiene:check": "pnpm --filter @pair/dev-tools code-hygiene:check",
+    "sync-version": "pnpm --filter @pair/dev-tools sync-version",
     "docs:staleness": "pnpm --filter @pair/website docs:staleness",
     "skills:conformance": "pnpm --filter @pair/knowledge-hub skills:conformance",
     "dup:check": "jscpd apps packages",
diff --git a/packages/dev-tools/README.md b/packages/dev-tools/README.md
new file mode 100644
index 00000000..163a13b6
--- /dev/null
+++ b/packages/dev-tools/README.md
@@ -0,0 +1,20 @@
+# @pair/dev-tools
+
+Pair's own gate/tooling scripts, as tested TypeScript modules — the reference pattern for repo quality gates (per [ADL 2026-07-13-gate-tooling-code-in-tested-modules](../../.pair/adoption/decision-log/2026-07-13-gate-tooling-code-in-tested-modules.md)).
+
+## Tools
+
+| Script                | Module                        | Purpose                                                                 |
+| --------------------- | ----------------------------- | ------------------------------------------------------------------------ |
+| `code-hygiene:check`  | `src/code-hygiene-check.ts`   | Fails if suppression markers (`@ts-ignore`, `eslint-disable`, `.skip`) are committed |
+| `sync-version`        | `src/sync-version-in-docs.ts` | Detects/rewrites hardcoded CLI version strings across `.md`/`.mdx` docs |
+
+Both are runnable via the repo-root scripts (`pnpm hygiene:check`, `pnpm sync-version -- <old-version>`), which delegate here (`pnpm --filter @pair/dev-tools <script>`).
+
+## Scope
+
+This package owns the genuinely **repo-wide, no-package-affinity** gates. Three related tools — `docs-staleness-check` (`apps/website/lib/`), `skills-conformance-check` and `check-broken-links` (`packages/knowledge-hub/src/tools/`) — stay in their owning packages: each needs that package's own context (the website's docs tree, knowledge-hub's dataset) and moving them here would trade a clean path resolution for a deep relative reach into a sibling package's internals. `scripts/perf/benchmark-update-link.js` also stays put (perf benchmark, not a correctness gate).
+
+## Conventions
+
+Every module here follows the shape: logic as exported, unit-tested pure functions; a thin `main()` CLI wrapper behind a `require.main === module` guard. Tests are white-box (import the module directly) and never spawn the script as a subprocess — see the ADL linked above.
diff --git a/packages/dev-tools/package.json b/packages/dev-tools/package.json
new file mode 100644
index 00000000..989dee87
--- /dev/null
+++ b/packages/dev-tools/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "@pair/dev-tools",
+  "version": "0.4.3",
+  "description": "Pair's own gate/tooling scripts (code-hygiene, sync-version) as tested TypeScript modules — the reference pattern for repo quality gates.",
+  "private": true,
+  "scripts": {
+    "prettier:fix": "prettier-fix",
+    "prettier:check": "prettier-check",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "ts:check": "tsc --noEmit",
+    "lint": "lint",
+    "lint:fix": "lint-fix",
+    "mdlint:check": "markdownlint-check",
+    "mdlint:fix": "markdownlint-fix",
+    "code-hygiene:check": "ts-node src/code-hygiene-check.ts",
+    "sync-version": "ts-node src/sync-version-in-docs.ts"
+  },
+  "devDependencies": {
+    "@pair/eslint-config": "workspace:*",
+    "@pair/prettier-config": "workspace:*",
+    "@pair/markdownlint-config": "workspace:*",
+    "@pair/ts-config": "workspace:*",
+    "@types/node": "catalog:",
+    "vitest": "catalog:",
+    "vite-tsconfig-paths": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "typescript": "catalog:",
+    "ts-node": "catalog:"
+  },
+  "prettier": "@pair/prettier-config"
+}
diff --git a/packages/dev-tools/src/code-hygiene-check.test.ts b/packages/dev-tools/src/code-hygiene-check.test.ts
new file mode 100644
index 00000000..b88b0343
--- /dev/null
+++ b/packages/dev-tools/src/code-hygiene-check.test.ts
@@ -0,0 +1,80 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  PATTERNS,
+  FILE_GLOBS,
+  buildGitGrepCommand,
+  parseGrepOutput,
+  scanPattern,
+  runHygieneCheck,
+  type HygienePattern,
+} from './code-hygiene-check'
+
+// Test fixtures below use synthetic marker names ("marker-one" etc.), not the real
+// suppression strings (split in the module under test — @ts- + ignore, etc.) — this
+// file is itself scanned by *.ts globs, so it must not contain the literal markers.
+
+describe('buildGitGrepCommand', () => {
+  it('builds a git grep invocation with quoted globs and a self-exclude pathspec', () => {
+    // Globs are joined with ' -- ' (matches the original script verbatim); git
+    // tolerates the repeated separator — verified against a real git grep.
+    const cmd = buildGitGrepCommand('marker-one', ['*.ts', '*.tsx'], 'scripts/self.ts')
+    expect(cmd).toBe('git grep -n "marker-one" -- "*.ts" -- "*.tsx" \':!scripts/self.ts\'')
+  })
+})
+
+describe('parseGrepOutput', () => {
+  it('parses one match per line into "  file:line" entries', () => {
+    const out = 'src/a.ts:10:// marker-one\nsrc/b.ts:22:// marker-one reason\n'
+    expect(parseGrepOutput(out)).toEqual(['  src/a.ts:10', '  src/b.ts:22'])
+  })
+
+  it('drops empty lines and trims trailing newline noise', () => {
+    expect(parseGrepOutput('\n\n')).toEqual([])
+  })
+})
+
+describe('scanPattern', () => {
+  const pattern: HygienePattern = { label: 'marker-one', regex: 'marker-one' }
+
+  it('returns formatted matches from the injected exec function', () => {
+    const exec = vi.fn(() => 'src/a.ts:5:// marker-one\n')
+    const matches = scanPattern(pattern, FILE_GLOBS, 'self.ts', exec)
+    expect(matches).toEqual(['  src/a.ts:5'])
+    expect(exec).toHaveBeenCalledWith(buildGitGrepCommand(pattern.regex, FILE_GLOBS, 'self.ts'))
+  })
+
+  it('treats a thrown error (git grep exit 1, no matches) as the happy path — empty result', () => {
+    const exec = vi.fn(() => {
+      throw new Error('exit 1')
+    })
+    expect(scanPattern(pattern, FILE_GLOBS, 'self.ts', exec)).toEqual([])
+  })
+})
+
+describe('runHygieneCheck', () => {
+  it('aggregates violations across patterns and totals the match count', () => {
+    const patterns: HygienePattern[] = [
+      { label: 'marker-one', regex: 'marker-one' },
+      { label: 'marker-two', regex: 'marker-two' },
+      { label: 'marker-three', regex: 'marker-three' },
+    ]
+    const exec: (cmd: string) => string = cmd => {
+      if (cmd.includes('marker-one')) return 'src/a.ts:1:x\nsrc/b.ts:2:x\n'
+      if (cmd.includes('marker-two')) return 'src/c.ts:3:x\n'
+      throw new Error('exit 1') // marker-three: no matches
+    }
+    const { violations, total } = runHygieneCheck(patterns, FILE_GLOBS, 'self.ts', exec)
+    expect(total).toBe(3)
+    expect(violations.get('marker-one')).toEqual(['  src/a.ts:1', '  src/b.ts:2'])
+    expect(violations.get('marker-two')).toEqual(['  src/c.ts:3'])
+    expect(violations.has('marker-three')).toBe(false)
+  })
+
+  it('reports zero total when nothing matches', () => {
+    const { violations, total } = runHygieneCheck(PATTERNS, FILE_GLOBS, 'self.ts', () => {
+      throw new Error('exit 1')
+    })
+    expect(total).toBe(0)
+    expect(violations.size).toBe(0)
+  })
+})
diff --git a/packages/dev-tools/src/code-hygiene-check.ts b/packages/dev-tools/src/code-hygiene-check.ts
new file mode 100644
index 00000000..bd11eef2
--- /dev/null
+++ b/packages/dev-tools/src/code-hygiene-check.ts
@@ -0,0 +1,135 @@
+/**
+ * Code Hygiene Check — prevents suppression markers from entering the codebase.
+ *
+ * The LOGIC lives here as individually exported, unit-tested functions (see
+ * code-hygiene-check.test.ts, white-box, exec injected — no real git repo needed).
+ * The `main()` block is a thin CLI wrapper run via `ts-node src/code-hygiene-check.ts`
+ * (package script `code-hygiene:check`, delegated from the repo-root `hygiene:check`
+ * script). Exit 0 = clean, Exit 1 = violations found.
+ *
+ * Runs `git grep` with an explicit `cwd` (the repo root, resolved from this file's
+ * location: packages/dev-tools/src -> packages/dev-tools -> packages -> repo root,
+ * up 3) so the scan behaves identically regardless of the caller's working
+ * directory (e.g. `pnpm --filter` sets cwd to the package dir, not the repo root).
+ */
+import { execSync } from 'child_process'
+import { resolve } from 'path'
+
+const REPO_ROOT = resolve(__dirname, '..', '..', '..')
+
+// Path of this module, relative to the repo root — excluded from its own scan so
+// the patterns below (deliberately split so they don't match this file) never
+// trip on the string literals that define them.
+const SELF_EXCLUDE = 'packages/dev-tools/src/code-hygiene-check.ts'
+
+export interface HygienePattern {
+  label: string
+  regex: string
+}
+
+// Patterns are split so this file does not match itself.
+export const PATTERNS: HygienePattern[] = [
+  { label: '@ts-ignore', regex: '@ts-' + 'ignore' },
+  { label: '@ts-nocheck', regex: '@ts-' + 'nocheck' },
+  { label: 'eslint-disable', regex: 'eslint-' + 'disable' },
+  { label: 'test.skip', regex: '\\btest\\.' + 'skip\\b' },
+  { label: 'it.skip', regex: '\\bit\\.' + 'skip\\b' },
+  { label: 'describe.skip', regex: '\\bdescribe\\.' + 'skip\\b' },
+]
+
+export const FILE_GLOBS = ['*.ts', '*.tsx', '*.js', '*.cjs', '*.mjs']
+
+/** Build the `git grep` invocation for one pattern (exported for direct assertion). */
+export function buildGitGrepCommand(
+  regex: string,
+  fileGlobs: string[],
+  selfExclude: string,
+): string {
+  const globsArg = fileGlobs.map(g => `"${g}"`).join(' -- ')
+  return `git grep -n "${regex}" -- ${globsArg} ':!${selfExclude}'`
+}
+
+/** Parse raw `git grep -n` stdout into formatted `  file:line` entries. */
+export function parseGrepOutput(out: string): string[] {
+  return out
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map(line => {
+      const sep = line.indexOf(':')
+      const sep2 = line.indexOf(':', sep + 1)
+      const file = line.substring(0, sep)
+      const lineNum = line.substring(sep + 1, sep2)
+      return `  ${file}:${lineNum}`
+    })
+}
+
+export type Exec = (cmd: string) => string
+
+function defaultExec(cmd: string): string {
+  return execSync(cmd, { cwd: REPO_ROOT, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] })
+}
+
+/** Scan one pattern; `git grep` exits 1 with no output when there are no matches — that's the happy path. */
+export function scanPattern(
+  pattern: HygienePattern,
+  fileGlobs: string[] = FILE_GLOBS,
+  selfExclude: string = SELF_EXCLUDE,
+  exec: Exec = defaultExec,
+): string[] {
+  try {
+    const out = exec(buildGitGrepCommand(pattern.regex, fileGlobs, selfExclude))
+    return parseGrepOutput(out)
+  } catch {
+    return []
+  }
+}
+
+export interface RunResult {
+  violations: Map<string, string[]>
+  total: number
+}
+
+/** Run every pattern and aggregate results. */
+export function runHygieneCheck(
+  patterns: HygienePattern[] = PATTERNS,
+  fileGlobs: string[] = FILE_GLOBS,
+  selfExclude: string = SELF_EXCLUDE,
+  exec: Exec = defaultExec,
+): RunResult {
+  const violations = new Map<string, string[]>()
+  let total = 0
+  for (const pattern of patterns) {
+    const matches = scanPattern(pattern, fileGlobs, selfExclude, exec)
+    if (matches.length) {
+      violations.set(pattern.label, matches)
+      total += matches.length
+    }
+  }
+  return { violations, total }
+}
+
+/** Thin CLI wrapper: print the report and set the exit code. */
+export function main(): void {
+  const { violations, total } = runHygieneCheck()
+
+  console.log('Code Hygiene Check')
+  console.log('==================')
+
+  if (total === 0) {
+    console.log('PASS — no violations')
+    process.exit(0)
+  } else {
+    console.log(`FAIL — ${total} violation${total > 1 ? 's' : ''}\n`)
+    for (const [label, matches] of violations) {
+      console.log(`${label} (${matches.length}):`)
+      for (const m of matches) console.log(m)
+      console.log()
+    }
+    process.exit(1)
+  }
+}
+
+if (require.main === module) {
+  main()
+}
diff --git a/packages/dev-tools/src/sync-version-in-docs.test.ts b/packages/dev-tools/src/sync-version-in-docs.test.ts
new file mode 100644
index 00000000..755bf8bb
--- /dev/null
+++ b/packages/dev-tools/src/sync-version-in-docs.test.ts
@@ -0,0 +1,163 @@
+import { describe, it, expect, afterAll } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  isExternalLine,
+  rewriteLine,
+  rewriteContent,
+  shouldExclude,
+  walkDocFiles,
+  findFilesWithVersion,
+  syncVersionInDocs,
+  parseArgv,
+} from './sync-version-in-docs'
+
+describe('isExternalLine', () => {
+  it('flags a GitHub Actions "uses:" pin', () => {
+    expect(isExternalLine('      uses: actions/checkout@v0.4.3')).toBe(true)
+  })
+
+  it('flags an npm install with a pinned version', () => {
+    expect(isExternalLine('npm install some-pkg@0.4.3')).toBe(true)
+  })
+
+  it('flags a pnpm add with a pinned version', () => {
+    expect(isExternalLine('pnpm add some-pkg@0.4.3')).toBe(true)
+  })
+
+  it('does not flag an ordinary prose line', () => {
+    expect(isExternalLine('pair v0.4.3 is the current release.')).toBe(false)
+  })
+})
+
+describe('rewriteLine', () => {
+  it('replaces the version when present and not an external-version line', () => {
+    expect(rewriteLine('pair v0.4.3 released.', '0.4.3', '0.5.0')).toBe('pair v0.5.0 released.')
+  })
+
+  it('leaves the line untouched when the version is absent', () => {
+    expect(rewriteLine('no version here', '0.4.3', '0.5.0')).toBe('no version here')
+  })
+
+  it('leaves an external-version line untouched even if it contains our version substring', () => {
+    const line = 'uses: some/action@0.4.3'
+    expect(rewriteLine(line, '0.4.3', '0.5.0')).toBe(line)
+  })
+})
+
+describe('rewriteContent', () => {
+  it('rewrites every eligible line and reports changed=true', () => {
+    const content = 'pair v0.4.3\nsome prose\nuses: some/action@0.4.3\n'
+    const { updated, changed } = rewriteContent(content, '0.4.3', '0.5.0')
+    expect(changed).toBe(true)
+    expect(updated).toBe('pair v0.5.0\nsome prose\nuses: some/action@0.4.3\n')
+  })
+
+  it('reports changed=false when nothing needed rewriting', () => {
+    const content = 'uses: some/action@0.4.3\n'
+    const { changed } = rewriteContent(content, '0.4.3', '0.5.0')
+    expect(changed).toBe(false)
+  })
+})
+
+describe('shouldExclude', () => {
+  it('matches a substring anywhere in the relative path', () => {
+    expect(shouldExclude('packages/foo/node_modules/bar.md', ['node_modules'])).toBe(true)
+    expect(shouldExclude('docs/CHANGELOG.md', ['CHANGELOG.md'])).toBe(true)
+    expect(shouldExclude('docs/guide.md', ['CHANGELOG.md'])).toBe(false)
+  })
+})
+
+describe('walkDocFiles / findFilesWithVersion (fixture tree)', () => {
+  const root = mkdtempSync(join(tmpdir(), 'sync-version-'))
+  afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+  const write = (rel: string, content: string) => {
+    const abs = join(root, rel)
+    mkdirSync(join(abs, '..'), { recursive: true })
+    writeFileSync(abs, content)
+  }
+
+  write('docs/guide.md', 'pair v0.4.3 install guide')
+  write('docs/other.md', 'no version mentioned here')
+  write('docs/action.mdx', 'uses: some/action@0.4.3')
+  write('CHANGELOG.md', 'pair v0.4.3 changelog entry — must be excluded')
+  write('node_modules/dep/readme.md', 'pair v0.4.3 vendored, must be excluded')
+  write('notes.txt', 'pair v0.4.3 — not a doc file, must be skipped')
+
+  it('walkDocFiles collects only .md/.mdx outside excluded paths', () => {
+    const files = walkDocFiles(root, root, ['node_modules', 'CHANGELOG.md'])
+    const rels = files.map(f => f.replace(root + '/', '')).sort()
+    expect(rels).toEqual(['docs/action.mdx', 'docs/guide.md', 'docs/other.md'])
+  })
+
+  it('findFilesWithVersion further filters to files whose content contains oldVersion', () => {
+    const files = findFilesWithVersion(root, '0.4.3', ['node_modules', 'CHANGELOG.md'])
+    const rels = files.map(f => f.replace(root + '/', '')).sort()
+    expect(rels).toEqual(['docs/action.mdx', 'docs/guide.md'])
+  })
+})
+
+describe('syncVersionInDocs', () => {
+  const setup = () => {
+    const root = mkdtempSync(join(tmpdir(), 'sync-version-run-'))
+    const write = (rel: string, content: string) => {
+      const abs = join(root, rel)
+      mkdirSync(join(abs, '..'), { recursive: true })
+      writeFileSync(abs, content)
+    }
+    write('docs/guide.md', 'pair v0.4.3 install guide')
+    write('docs/action.mdx', 'uses: some/action@0.4.3')
+    write('CHANGELOG.md', 'pair v0.4.3 changelog entry')
+    return { root, write }
+  }
+
+  it('check mode: reports drift without writing files', () => {
+    const { root } = setup()
+    const before = readFile(join(root, 'docs/guide.md'))
+    const result = syncVersionInDocs(root, '0.4.3', '0.5.0', { check: true })
+    expect(result.drifted).toEqual(['docs/guide.md'])
+    expect(result.unchanged).toEqual(['docs/action.mdx'])
+    expect(result.fixed).toEqual([])
+    expect(readFile(join(root, 'docs/guide.md'))).toBe(before) // unchanged on disk
+  })
+
+  it('apply mode: rewrites drifted files in place', () => {
+    const { root } = setup()
+    const result = syncVersionInDocs(root, '0.4.3', '0.5.0', { check: false })
+    expect(result.fixed).toEqual(['docs/guide.md'])
+    expect(result.drifted).toEqual([])
+    expect(readFile(join(root, 'docs/guide.md'))).toBe('pair v0.5.0 install guide')
+    // external-version line is never rewritten
+    expect(readFile(join(root, 'docs/action.mdx'))).toBe('uses: some/action@0.4.3')
+  })
+
+  it('excludes CHANGELOG.md from the scan entirely', () => {
+    const { root } = setup()
+    const result = syncVersionInDocs(root, '0.4.3', '0.5.0', { check: true })
+    expect(result.scanned).not.toContain('CHANGELOG.md')
+  })
+})
+
+function readFile(path: string): string {
+  return readFileSync(path, 'utf-8')
+}
+
+describe('parseArgv', () => {
+  it('extracts --check and the positional old-version arg', () => {
+    expect(parseArgv(['0.4.3', '--check'])).toEqual({ check: true, oldVersionArg: '0.4.3' })
+  })
+
+  it('defaults check to false and oldVersionArg to undefined with no args', () => {
+    expect(parseArgv([])).toEqual({ check: false, oldVersionArg: undefined })
+  })
+
+  // Regression: `pnpm ... sync-version -- 0.4.3` can leave a literal '--' in argv
+  // (pnpm/ts-node do not always strip the separator) — if not filtered, '--' would
+  // be read as the old-version arg and match nearly every doc (e.g. markdown '---').
+  it('filters out a stray literal "--" left over from pnpm/ts-node arg forwarding', () => {
+    expect(parseArgv(['--', '0.4.3'])).toEqual({ check: false, oldVersionArg: '0.4.3' })
+    expect(parseArgv(['--', '--check'])).toEqual({ check: true, oldVersionArg: undefined })
+  })
+})
diff --git a/packages/dev-tools/src/sync-version-in-docs.ts b/packages/dev-tools/src/sync-version-in-docs.ts
new file mode 100644
index 00000000..36a8b23e
--- /dev/null
+++ b/packages/dev-tools/src/sync-version-in-docs.ts
@@ -0,0 +1,205 @@
+/**
+ * Sync Version In Docs — auto-detects and replaces hardcoded version strings in
+ * .md/.mdx files across the repo.
+ *
+ * The LOGIC lives here as individually exported, unit-tested functions (see
+ * sync-version-in-docs.test.ts, white-box, exercised against a temp-dir fixture
+ * tree — no shell-out to an external search tool). The `main()` block is a thin
+ * CLI wrapper run via `ts-node src/sync-version-in-docs.ts` (package script
+ * `sync-version`).
+ *
+ * Usage:
+ *   pnpm --filter @pair/dev-tools sync-version -- <old-version>           # apply
+ *   pnpm --filter @pair/dev-tools sync-version -- <old-version> --check   # dry-run, exit 1 if drift
+ *   pnpm --filter @pair/dev-tools sync-version -- --check                 # detect current version drift
+ *
+ * In the version workflow, OLD_CLI_VERSION is captured before `changeset version`
+ * and passed as the first argument. The new version is read from
+ * apps/pair-cli/package.json.
+ *
+ * REPO_ROOT is resolved from this file's location: packages/dev-tools/src ->
+ * packages/dev-tools -> packages -> repo root (up 3).
+ */
+import { readFileSync, readdirSync, writeFileSync } from 'fs'
+import { join, relative, resolve } from 'path'
+
+const REPO_ROOT = resolve(__dirname, '..', '..', '..')
+
+// Directories/patterns to skip — not our version strings. Merged with infra dirs
+// that should never be walked (large, generated, or vendored trees).
+const INFRA_EXCLUDES = ['node_modules', '.git', 'dist', 'coverage', '.turbo', '.next']
+export const DEFAULT_EXCLUDES = [
+  ...INFRA_EXCLUDES,
+  'CHANGELOG.md',
+  'pnpm-lock.yaml',
+  'pnpm-workspace.yaml',
+  '.changeset/',
+]
+
+// Patterns that indicate an external version (not ours) — skip these lines.
+const EXTERNAL_LINE_PATTERNS = [
+  /uses:\s*\S+@v?\d/, // GitHub Actions: uses: org/action@v1.2.3
+  /npm i\S*\s+\S+@\d/, // npm install pkg@version
+  /pnpm add\S*\s+\S+@\d/, // pnpm add pkg@version
+]
+
+export function isExternalLine(line: string): boolean {
+  return EXTERNAL_LINE_PATTERNS.some(re => re.test(line))
+}
+
+/** Rewrite one line: replace oldVersion with newVersion, unless it's an external-version line. */
+export function rewriteLine(line: string, oldVersion: string, newVersion: string): string {
+  if (!line.includes(oldVersion)) return line
+  if (isExternalLine(line)) return line
+  const versionRegex = new RegExp(oldVersion.replace(/\./g, '\\.'), 'g')
+  return line.replace(versionRegex, newVersion)
+}
+
+export interface RewriteResult {
+  updated: string
+  changed: boolean
+}
+
+/** Rewrite every line of a file's content; `changed` is false when nothing needed rewriting. */
+export function rewriteContent(
+  content: string,
+  oldVersion: string,
+  newVersion: string,
+): RewriteResult {
+  const updated = content
+    .split('\n')
+    .map(line => rewriteLine(line, oldVersion, newVersion))
+    .join('\n')
+  return { updated, changed: updated !== content }
+}
+
+export function shouldExclude(relPath: string, excludePatterns: string[]): boolean {
+  return excludePatterns.some(p => relPath.includes(p))
+}
+
+/** Walk a directory tree collecting .md/.mdx files, skipping excluded paths (files or dirs). */
+export function walkDocFiles(dir: string, root: string, excludePatterns: string[]): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    const rel = relative(root, full)
+    if (shouldExclude(rel, excludePatterns)) continue
+    if (entry.isDirectory()) {
+      out.push(...walkDocFiles(full, root, excludePatterns))
+    } else if (/\.(md|mdx)$/.test(entry.name)) {
+      out.push(full)
+    }
+  }
+  return out
+}
+
+/** Every .md/.mdx file (outside excluded paths) whose content contains oldVersion. */
+export function findFilesWithVersion(
+  root: string,
+  oldVersion: string,
+  excludePatterns: string[],
+): string[] {
+  return walkDocFiles(root, root, excludePatterns).filter(f =>
+    readFileSync(f, 'utf-8').includes(oldVersion),
+  )
+}
+
+export interface SyncOptions {
+  check: boolean
+  excludePatterns?: string[]
+}
+
+export interface SyncResult {
+  scanned: string[]
+  fixed: string[]
+  drifted: string[]
+  unchanged: string[]
+}
+
+/** Core sync logic: find candidate files, rewrite (or just report drift), no process exit. */
+export function syncVersionInDocs(
+  root: string,
+  oldVersion: string,
+  newVersion: string,
+  opts: SyncOptions,
+): SyncResult {
+  const excludePatterns = [...DEFAULT_EXCLUDES, ...(opts.excludePatterns ?? [])]
+  const files = findFilesWithVersion(root, oldVersion, excludePatterns)
+  const result: SyncResult = { scanned: [], fixed: [], drifted: [], unchanged: [] }
+
+  for (const abs of files) {
+    const rel = relative(root, abs)
+    result.scanned.push(rel)
+    const original = readFileSync(abs, 'utf-8')
+    const { updated, changed } = rewriteContent(original, oldVersion, newVersion)
+
+    if (!changed) {
+      result.unchanged.push(rel)
+      continue
+    }
+    if (opts.check) {
+      result.drifted.push(rel)
+    } else {
+      writeFileSync(abs, updated)
+      result.fixed.push(rel)
+    }
+  }
+
+  return result
+}
+
+/** Parse CLI argv into { check, oldVersion } — `--` may survive from `pnpm ... <script> -- <args>` invocations (pnpm/ts-node do not always strip the separator), so it's filtered out alongside --check. */
+export function parseArgv(argv: string[]): { check: boolean; oldVersionArg: string | undefined } {
+  const check = argv.includes('--check')
+  const positional = argv.filter(a => a !== '--check' && a !== '--')
+  return { check, oldVersionArg: positional[0] }
+}
+
+/** Print the per-file report lines (OK/DRIFT/FIXED) for a completed run. */
+function printReport(result: SyncResult, newVersion: string): void {
+  for (const rel of result.unchanged) console.log(`OK    ${rel}`)
+  for (const rel of result.drifted) console.log(`DRIFT ${rel}`)
+  for (const rel of result.fixed) console.log(`FIXED ${rel} → v${newVersion}`)
+}
+
+/** Thin CLI wrapper: print the report and set the exit code. */
+export function main(argv: string[] = process.argv.slice(2)): void {
+  const { check, oldVersionArg } = parseArgv(argv)
+
+  const newVersion = JSON.parse(
+    readFileSync(join(REPO_ROOT, 'apps/pair-cli/package.json'), 'utf-8'),
+  ).version as string
+  const oldVersion = oldVersionArg || newVersion
+
+  if (oldVersion === newVersion && !check) {
+    console.log('Old and new versions are identical, nothing to do.')
+    return
+  }
+
+  const result = syncVersionInDocs(REPO_ROOT, oldVersion, newVersion, { check })
+
+  if (result.scanned.length === 0) {
+    console.log(check ? 'No version drift detected.' : 'No files to update.')
+    return
+  }
+
+  printReport(result, newVersion)
+
+  if (check) {
+    if (result.drifted.length > 0) {
+      console.error(
+        `\n${result.drifted.length} file(s) have stale version. Run: pnpm --filter @pair/dev-tools sync-version -- ${oldVersion}`,
+      )
+      process.exit(1)
+    }
+    return
+  }
+
+  console.log(
+    `\nDone. ${result.scanned.length} file(s) scanned, version: ${oldVersion} → ${newVersion}`,
+  )
+}
+
+if (require.main === module) {
+  main()
+}
diff --git a/packages/dev-tools/tsconfig.json b/packages/dev-tools/tsconfig.json
new file mode 100644
index 00000000..f0dbb070
--- /dev/null
+++ b/packages/dev-tools/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "@pair/ts-config/node.json",
+  "compilerOptions": {},
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}
diff --git a/packages/dev-tools/vitest.config.ts b/packages/dev-tools/vitest.config.ts
new file mode 100644
index 00000000..b56b0fba
--- /dev/null
+++ b/packages/dev-tools/vitest.config.ts
@@ -0,0 +1,30 @@
+import { defineConfig } from 'vitest/config'
+import tsconfigPaths from 'vite-tsconfig-paths'
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  test: {
+    environment: 'node',
+    globals: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'coverage/',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        'vitest.config.ts',
+      ],
+      thresholds: {
+        global: {
+          branches: 80,
+          functions: 80,
+          lines: 80,
+          statements: 80,
+        },
+      },
+    },
+  },
+})
diff --git a/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts b/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
index 3f0a3910..34734f4c 100644
--- a/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
+++ b/packages/knowledge-hub/src/tools/skills-conformance-check.test.ts
@@ -167,17 +167,17 @@ describe('runChecks (fixture corpus)', () => {
   )
   skill('next', 'name: next\ndescription: "Router."', 'Covers the full 2-skill catalog.')
 
-  it('reports violations per file, catalog warnings, and the corpus count', () => {
-    const { errors, warnings, skillCount } = runChecks(root)
+  it('reports violations per file plus a catalog-count mismatch as a hard error (drives CLI exit 1)', () => {
+    const { errors, skillCount } = runChecks(root)
     expect(skillCount).toBe(4)
     expect(
       errors.some(e => e.includes('bad-field') && e.includes('disable-model-invocation')),
     ).toBe(true)
     expect(errors.some(e => e.includes('broken-link') && e.includes('./missing.md'))).toBe(true)
     expect(errors.some(e => e.includes('good/SKILL.md'))).toBe(false)
-    expect(warnings).toHaveLength(1)
-    expect(warnings[0]).toContain('2-skill')
-    expect(warnings[0]).toContain('4 skills')
+    const catalogErrors = errors.filter(e => e.includes('2-skill'))
+    expect(catalogErrors).toHaveLength(1)
+    expect(catalogErrors[0]).toContain('4 skills')
   })
 })
 
diff --git a/packages/knowledge-hub/src/tools/skills-conformance-check.ts b/packages/knowledge-hub/src/tools/skills-conformance-check.ts
index 3ef9f8a8..7e035a1a 100644
--- a/packages/knowledge-hub/src/tools/skills-conformance-check.ts
+++ b/packages/knowledge-hub/src/tools/skills-conformance-check.ts
@@ -14,13 +14,12 @@
  *   3. Pointer resolution — relative file links in SKILL.md bodies resolve to
  *      existing files/dirs in the dataset.
  *   4. Catalog counts — every "N skills"/"N-skill" figure stated in next's
- *      SKILL.md matches the real corpus dir count.
- *      TODO(#313/T1): promote catalog-count findings from warning to error once
- *      T1 (#325) regenerates next's catalog (currently states 33, corpus has 35).
+ *      SKILL.md matches the real corpus dir count. Hard error, like every other
+ *      check here (promoted from WARN once #313/T1 (#325) regenerated next's
+ *      catalog to the real, stable count).
  *
  * Runnable as a CLI via `ts-node src/tools/skills-conformance-check.ts`
- * (package script `skills:conformance`). Exit 0 = conformant (warnings allowed),
- * Exit 1 = violations.
+ * (package script `skills:conformance`). Exit 0 = conformant, Exit 1 = violations.
  */
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { basename, dirname, join, relative, resolve } from 'path'
@@ -52,7 +51,6 @@ export interface Frontmatter {
 
 export interface RunResult {
   errors: string[]
-  warnings: string[]
   skillCount: number
 }
 
@@ -198,14 +196,14 @@ export function checkLinks(filePath: string, body: string): string[] {
 // --- Catalog counts ---
 
 export function checkCatalogCounts(nextContent: string, actualCount: number): string[] {
-  const warnings: string[] = []
+  const mismatches: string[] = []
   for (const m of nextContent.matchAll(/(\d+)[-\s]skills?\b/g)) {
     const stated = parseInt(m[1] as string, 10)
     if (stated !== actualCount) {
-      warnings.push(`next/SKILL.md states "${m[0]}" but the corpus has ${actualCount} skills`)
+      mismatches.push(`next/SKILL.md states "${m[0]}" but the corpus has ${actualCount} skills`)
     }
   }
-  return warnings
+  return mismatches
 }
 
 // --- Corpus walk ---
@@ -233,7 +231,6 @@ export function collectSkillFiles(skillsDir: string): string[] {
 
 export function runChecks(skillsDir: string): RunResult {
   const errors: string[] = []
-  const warnings: string[] = []
   const files = collectSkillFiles(skillsDir)
 
   for (const file of files) {
@@ -253,29 +250,21 @@ export function runChecks(skillsDir: string): RunResult {
 
   const nextFile = files.find(f => basename(dirname(f)) === 'next')
   if (nextFile) {
-    warnings.push(...checkCatalogCounts(readFileSync(nextFile, 'utf-8'), files.length))
+    errors.push(...checkCatalogCounts(readFileSync(nextFile, 'utf-8'), files.length))
   }
 
-  return { errors, warnings, skillCount: files.length }
+  return { errors, skillCount: files.length }
 }
 
 if (require.main === module) {
-  const { errors, warnings, skillCount } = runChecks(SKILLS_DIR)
+  const { errors, skillCount } = runChecks(SKILLS_DIR)
 
   console.log('Skills Conformance Check')
   console.log('========================')
 
-  if (warnings.length > 0) {
-    console.log(
-      `WARN — ${warnings.length} non-blocking finding${warnings.length > 1 ? 's' : ''} (error once #313/T1 lands):\n`,
-    )
-    for (const w of warnings) console.log(`  • ${w}`)
-    console.log()
-  }
-
   if (errors.length === 0) {
     console.log(
-      `PASS — ${skillCount} skills conformant (frontmatter portability, size limits, pointer resolution)`,
+      `PASS — ${skillCount} skills conformant (frontmatter portability, size limits, pointer resolution, catalog counts)`,
     )
     process.exit(0)
   } else {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e721878a..5c34f725 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -483,6 +483,39 @@ importers:
         specifier: 'catalog:'
         version: 3.2.4(@types/debug@4.1.12)(@types/node@24.3.0)(jiti@1.21.7)(jsdom@25.0.1)(tsx@4.23.1)(yaml@2.8.2)
 
+  packages/dev-tools:
+    devDependencies:
+      '@pair/eslint-config':
+        specifier: workspace:*
+        version: link:../../tools/eslint-config
+      '@pair/markdownlint-config':
+        specifier: workspace:*
+        version: link:../../tools/markdownlint-config
+      '@pair/prettier-config':
+        specifier: workspace:*
+        version: link:../../tools/prettier-config
+      '@pair/ts-config':
+        specifier: workspace:*
+        version: link:../../tools/ts-config
+      '@types/node':
+        specifier: 'catalog:'
+        version: 24.3.0
+      '@vitest/coverage-v8':
+        specifier: 'catalog:'
+        version: 3.2.4(vitest@3.2.4(@types/debug@4.1.12)(@types/node@24.3.0)(jiti@1.21.7)(jsdom@25.0.1)(tsx@4.23.1)(yaml@2.8.2))
+      ts-node:
+        specifier: 'catalog:'
+        version: 10.9.2(@types/node@24.3.0)(typescript@5.4.5)
+      typescript:
+        specifier: 'catalog:'
+        version: 5.4.5
+      vite-tsconfig-paths:
+        specifier: 'catalog:'
+        version: 5.1.4(typescript@5.4.5)(vite@7.2.6(@types/node@24.3.0)(jiti@1.21.7)(tsx@4.23.1)(yaml@2.8.2))
+      vitest:
+        specifier: 'catalog:'
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@24.3.0)(jiti@1.21.7)(jsdom@25.0.1)(tsx@4.23.1)(yaml@2.8.2)
+
   packages/knowledge-hub:
     devDependencies:
       '@pair/content-ops':
diff --git a/scripts/code-hygiene-check.js b/scripts/code-hygiene-check.js
deleted file mode 100644
index 2c23bf3d..00000000
--- a/scripts/code-hygiene-check.js
+++ /dev/null
@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-/**
- * Code Hygiene Check — prevents suppression markers from entering the codebase.
- * Exit 0 = clean, Exit 1 = violations found.
- */
-const { execSync } = require('child_process')
-
-// Patterns are split so this file does not match itself.
-const PATTERNS = [
-  { label: '@ts-ignore', regex: '@ts-' + 'ignore' },
-  { label: '@ts-nocheck', regex: '@ts-' + 'nocheck' },
-  { label: 'eslint-disable', regex: 'eslint-' + 'disable' },
-  { label: 'test.skip', regex: '\\btest\\.' + 'skip\\b' },
-  { label: 'it.skip', regex: '\\bit\\.' + 'skip\\b' },
-  { label: 'describe.skip', regex: '\\bdescribe\\.' + 'skip\\b' },
-]
-
-const FILE_GLOBS = ['*.ts', '*.tsx', '*.js', '*.cjs', '*.mjs'].map((g) => `"${g}"`).join(' -- ')
-
-const violations = new Map()
-let total = 0
-
-for (const { label, regex } of PATTERNS) {
-  try {
-    const out = execSync(`git grep -n "${regex}" -- ${FILE_GLOBS} ':!scripts/code-hygiene-check.js'`, {
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-    const matches = out
-      .trim()
-      .split('\n')
-      .filter(Boolean)
-      .map((line) => {
-        const sep = line.indexOf(':')
-        const sep2 = line.indexOf(':', sep + 1)
-        const file = line.substring(0, sep)
-        const lineNum = line.substring(sep + 1, sep2)
-        return `  ${file}:${lineNum}`
-      })
-    if (matches.length) {
-      violations.set(label, matches)
-      total += matches.length
-    }
-  } catch {
-    // git grep exits 1 when no matches — that's the happy path
-  }
-}
-
-console.log('Code Hygiene Check')
-console.log('==================')
-
-if (total === 0) {
-  console.log('PASS — no violations')
-  process.exit(0)
-} else {
-  console.log(`FAIL — ${total} violation${total > 1 ? 's' : ''}\n`)
-  for (const [label, matches] of violations) {
-    console.log(`${label} (${matches.length}):`)
-    for (const m of matches) console.log(m)
-    console.log()
-  }
-  process.exit(1)
-}
diff --git a/scripts/sync-version-in-docs.js b/scripts/sync-version-in-docs.js
deleted file mode 100644
index 5fa28def..00000000
--- a/scripts/sync-version-in-docs.js
+++ /dev/null
@@ -1,112 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Auto-detects and replaces hardcoded version strings in .md/.mdx files.
- *
- * Usage:
- *   node scripts/sync-version-in-docs.js <old-version>           # apply
- *   node scripts/sync-version-in-docs.js <old-version> --check   # dry-run, exit 1 if drift
- *   node scripts/sync-version-in-docs.js --check                 # detect current version drift
- *
- * In the version workflow, OLD_CLI_VERSION is captured before `changeset version`
- * and passed as the first argument. The new version is read from package.json.
- */
-
-const { execSync } = require('child_process')
-const fs = require('fs')
-const path = require('path')
-
-const root = path.resolve(__dirname, '..')
-const args = process.argv.slice(2).filter((a) => a !== '--check')
-const check = process.argv.includes('--check')
-
-const newVersion = JSON.parse(
-  fs.readFileSync(path.join(root, 'apps/pair-cli/package.json'), 'utf8'),
-).version
-
-const oldVersion = args[0] || newVersion
-
-if (oldVersion === newVersion && !check) {
-  console.log('Old and new versions are identical, nothing to do.')
-  process.exit(0)
-}
-
-// Directories/patterns to skip — not our version strings
-const EXCLUDE_PATTERNS = [
-  'node_modules',
-  'CHANGELOG.md',
-  'pnpm-lock.yaml',
-  'pnpm-workspace.yaml',
-  '.changeset/',
-]
-
-// Find all .md/.mdx files containing the old version string
-const grepExcludes = EXCLUDE_PATTERNS.map((p) => `--glob=!${p}`).join(' ')
-let files
-try {
-  const cmd = `rg --hidden --files-with-matches --glob="*.md" --glob="*.mdx" ${grepExcludes} --fixed-strings "${oldVersion}" .`
-  files = execSync(cmd, { cwd: root, encoding: 'utf8' })
-    .trim()
-    .split('\n')
-    .filter(Boolean)
-} catch {
-  // rg exits 1 when no matches
-  files = []
-}
-
-if (files.length === 0) {
-  console.log(check ? 'No version drift detected.' : 'No files to update.')
-  process.exit(0)
-}
-
-// Patterns that indicate an external version (not ours) — skip these lines
-const EXTERNAL_LINE_PATTERNS = [
-  /uses:\s*\S+@v?\d/,      // GitHub Actions: uses: org/action@v1.2.3
-  /npm i\S*\s+\S+@\d/,     // npm install pkg@version
-  /pnpm add\S*\s+\S+@\d/,  // pnpm add pkg@version
-]
-
-function isExternalLine(line) {
-  return EXTERNAL_LINE_PATTERNS.some((re) => re.test(line))
-}
-
-let drifted = 0
-const versionRegex = new RegExp(oldVersion.replace(/\./g, '\\.'), 'g')
-
-for (const rel of files) {
-  const abs = path.join(root, rel)
-  const original = fs.readFileSync(abs, 'utf8')
-
-  const updated = original
-    .split('\n')
-    .map((line) => {
-      if (!line.includes(oldVersion)) return line
-      if (isExternalLine(line)) return line
-      return line.replace(versionRegex, newVersion)
-    })
-    .join('\n')
-
-  if (original === updated) {
-    console.log(`OK    ${rel}`)
-    continue
-  }
-
-  if (check) {
-    console.log(`DRIFT ${rel}`)
-    drifted++
-  } else {
-    fs.writeFileSync(abs, updated)
-    console.log(`FIXED ${rel} → v${newVersion}`)
-  }
-}
-
-if (check && drifted > 0) {
-  console.error(
-    `\n${drifted} file(s) have stale version. Run: node scripts/sync-version-in-docs.js <old-version>`,
-  )
-  process.exit(1)
-}
-
-if (!check) {
-  console.log(`\nDone. ${files.length} file(s) scanned, version: ${oldVersion} → ${newVersion}`)
-}

From 693da03727334765ad2eb794d7c391354f0be6ce Mon Sep 17 00:00:00 2001
From: Gianluca Carucci <gianluca@carucci.org>
Date: Thu, 16 Jul 2026 08:02:14 +0200
Subject: [PATCH 2/2] [#209] fix: sync-version .gitignore parity (review
 finding)

The pure-JS walker that replaced the rg shell-out didn't honor .gitignore
the way rg implicitly did. Concrete gap: release/ is gitignored and can
hold a real stale-version .md file (build artifact), but wasn't excluded.

Test-first: added a failing regression test reproducing the gap, then
added parseGitignoreExcludes/readGitignoreExcludes (parses the real
.gitignore at the scan root, simple single-segment entries) and merged
into syncVersionInDocs's exclude list. Verified live against a real
release/ fixture in the repo tree.

Refs: #209

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../src/sync-version-in-docs.test.ts          | 48 +++++++++++++++++++
 .../dev-tools/src/sync-version-in-docs.ts     | 34 ++++++++++++-
 2 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/packages/dev-tools/src/sync-version-in-docs.test.ts b/packages/dev-tools/src/sync-version-in-docs.test.ts
index 755bf8bb..57635622 100644
--- a/packages/dev-tools/src/sync-version-in-docs.test.ts
+++ b/packages/dev-tools/src/sync-version-in-docs.test.ts
@@ -11,6 +11,8 @@ import {
   findFilesWithVersion,
   syncVersionInDocs,
   parseArgv,
+  parseGitignoreExcludes,
+  readGitignoreExcludes,
 } from './sync-version-in-docs'
 
 describe('isExternalLine', () => {
@@ -69,6 +71,37 @@ describe('shouldExclude', () => {
   })
 })
 
+describe('parseGitignoreExcludes', () => {
+  it('extracts simple top-level entries, stripping trailing slashes', () => {
+    const content = ['node_modules/', 'dist/', 'TODO.md', ''].join('\n')
+    expect(parseGitignoreExcludes(content)).toEqual(['node_modules', 'dist', 'TODO.md'])
+  })
+
+  it('ignores comments, blank lines, and negation patterns', () => {
+    const content = ['# comment', '', 'release/', '!scripts/workflows/release'].join('\n')
+    expect(parseGitignoreExcludes(content)).toEqual(['release'])
+  })
+
+  it('ignores multi-segment paths and wildcard globs (not meaningful for segment-level excludes)', () => {
+    const content = ['*.log', 'apps/website/scripts/landing-video/*.cast', 'coverage/'].join('\n')
+    expect(parseGitignoreExcludes(content)).toEqual(['coverage'])
+  })
+})
+
+describe('readGitignoreExcludes', () => {
+  const root = mkdtempSync(join(tmpdir(), 'gitignore-read-'))
+  afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+  it('returns [] when no .gitignore exists at root', () => {
+    expect(readGitignoreExcludes(root)).toEqual([])
+  })
+
+  it('reads and parses a real .gitignore at root', () => {
+    writeFileSync(join(root, '.gitignore'), 'release/\ncoverage/\n')
+    expect(readGitignoreExcludes(root)).toEqual(['release', 'coverage'])
+  })
+})
+
 describe('walkDocFiles / findFilesWithVersion (fixture tree)', () => {
   const root = mkdtempSync(join(tmpdir(), 'sync-version-'))
   afterAll(() => rmSync(root, { recursive: true, force: true }))
@@ -138,6 +171,21 @@ describe('syncVersionInDocs', () => {
     const result = syncVersionInDocs(root, '0.4.3', '0.5.0', { check: true })
     expect(result.scanned).not.toContain('CHANGELOG.md')
   })
+
+  // Regression: the pure-JS walker replaced an `rg`-based scan that implicitly
+  // respected .gitignore. A gitignored top-level dir (e.g. `release/`, a real
+  // build-artifact dir in this repo's own .gitignore) can hold real .md files on
+  // disk locally; those must never surface as DRIFT/FIXED.
+  it('skips a gitignored top-level dir holding a stale-version .md file', () => {
+    const { root, write } = setup()
+    write('.gitignore', 'release/\n')
+    write('release/pair-cli-manual-0.4.3/README.md', 'pair v0.4.3 packaged build')
+
+    const result = syncVersionInDocs(root, '0.4.3', '0.5.0', { check: true })
+
+    expect(result.scanned.some(f => f.startsWith('release/'))).toBe(false)
+    expect(readFile(join(root, 'release/pair-cli-manual-0.4.3/README.md'))).toContain('0.4.3')
+  })
 })
 
 function readFile(path: string): string {
diff --git a/packages/dev-tools/src/sync-version-in-docs.ts b/packages/dev-tools/src/sync-version-in-docs.ts
index 36a8b23e..9146885c 100644
--- a/packages/dev-tools/src/sync-version-in-docs.ts
+++ b/packages/dev-tools/src/sync-version-in-docs.ts
@@ -20,7 +20,7 @@
  * REPO_ROOT is resolved from this file's location: packages/dev-tools/src ->
  * packages/dev-tools -> packages -> repo root (up 3).
  */
-import { readFileSync, readdirSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
 import { join, relative, resolve } from 'path'
 
 const REPO_ROOT = resolve(__dirname, '..', '..', '..')
@@ -36,6 +36,32 @@ export const DEFAULT_EXCLUDES = [
   '.changeset/',
 ]
 
+/**
+ * Parse a .gitignore file's content into simple exclude patterns. The deleted
+ * `rg`-based script implicitly respected .gitignore; the pure-JS walker that
+ * replaced it does not by default, so gitignored build-artifact dirs (e.g.
+ * `release/`, which can hold real .md files on disk locally) must be folded in
+ * explicitly. Only simple, single-segment entries are usable by `shouldExclude`
+ * (path-segment substring matching) — comments, blank lines, negations (`!...`),
+ * multi-segment paths, and wildcard globs are skipped (not meaningful at that
+ * granularity, and harmless to omit: they don't hold version-string docs).
+ */
+export function parseGitignoreExcludes(content: string): string[] {
+  return content
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#') && !line.startsWith('!'))
+    .map(line => (line.endsWith('/') ? line.slice(0, -1) : line))
+    .filter(pattern => !pattern.includes('/') && !pattern.includes('*'))
+}
+
+/** Read and parse `<root>/.gitignore`; [] if the file doesn't exist (e.g. test fixtures). */
+export function readGitignoreExcludes(root: string): string[] {
+  const gitignorePath = join(root, '.gitignore')
+  if (!existsSync(gitignorePath)) return []
+  return parseGitignoreExcludes(readFileSync(gitignorePath, 'utf-8'))
+}
+
 // Patterns that indicate an external version (not ours) — skip these lines.
 const EXTERNAL_LINE_PATTERNS = [
   /uses:\s*\S+@v?\d/, // GitHub Actions: uses: org/action@v1.2.3
@@ -123,7 +149,11 @@ export function syncVersionInDocs(
   newVersion: string,
   opts: SyncOptions,
 ): SyncResult {
-  const excludePatterns = [...DEFAULT_EXCLUDES, ...(opts.excludePatterns ?? [])]
+  const excludePatterns = [
+    ...DEFAULT_EXCLUDES,
+    ...readGitignoreExcludes(root),
+    ...(opts.excludePatterns ?? []),
+  ]
   const files = findFilesWithVersion(root, oldVersion, excludePatterns)
   const result: SyncResult = { scanned: [], fixed: [], drifted: [], unchanged: [] }