@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/test-quality/scripts/mock-policy-config.mjs

@@ -0,0 +1,176 @@
+// mock-policy-config — project-agnostic classifier for the `mock-internal-seam`
+// lint rule. The engine is invariant; the project's topology is *declared*, not
+// hardcoded. This is the "externals-allowlist inversion": you cannot enumerate
+// every internal seam (unbounded, per-project), but the set of things that may
+// LEGITIMATELY be faked is small, stable, and known — third-party HTTP, the
+// clock, randomness, the runtime/stdlib. So we flip the question: a mock whose
+// target resolves to *first-party* code is a candidate gap; anything on the
+// declared externals allowlist (or the stdlib) is exempt. This makes the
+// "real internals, faked externals, nothing between" policy (SKILL.md principle 3)
+// decidable from config rather than from a baked-in path regex.
+//
+// Per-project facts come from a `coverage.config.json` (or `.coverage.config.json`)
+// at the repo root, under a `mockPolicy` key. The config only *declares topology*
+// (a monorepo's own package scope, generated dirs to exempt) — it does NOT gate
+// whether the rule runs. Over-mock is ZERO-TOLERANCE: the gate is default-on and
+// works with zero config on a conventional `@/`-aliased repo. There is no
+// `enabled:false` off switch and no inline waiver.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Generic defaults — safe for any repo; tune topology via coverage.config.json. */
+export const DEFAULT_MOCK_POLICY = {
+  // Default-ON. Zero-tolerance: a project cannot turn the over-mock gate off via
+  // config; `enabled` is retained only so a config that sets it is accepted, but
+  // the rule is default-on (defaultOn:true) regardless. There is no opt-out.
+  enabled: true,
+  // Import-specifier prefixes that denote first-party app source. `@/` and `~/`
+  // are near-universal TS path aliases for "this app's src".
+  firstPartyAliasPrefixes: ['@/', '~/'],
+  // Bare package names (exact or prefix) that are actually first-party workspace
+  // packages — e.g. a monorepo's own scope `@acme/`. Declared per project.
+  firstPartyPackages: [],
+  // Regex sources (strings) for specifiers that ARE legitimately external and so
+  // exempt — third-party APIs/SDKs a project wants to name explicitly. Bare npm
+  // packages are already treated as external by default; this is for the rare
+  // case you must override (or to exempt a first-party-looking alias).
+  externals: [],
+  // Path segments that mark a relative import as a test util / fixture / mock,
+  // NOT an internal seam — mocking those is not over-mocking.
+  testUtilHints: [
+    '__mocks__', '__fixtures__', 'fixtures', 'mocks', 'helpers',
+    'test-utils', 'testing', 'support', 'stubs', 'factories',
+  ],
+}
+
+/**
+ * Compile externals regex sources once and attach them as a genuinely
+ * non-enumerable cache, so the compiled RegExp[] never leaks into a
+ * `JSON.stringify(policy)` (where it would serialize to a useless `{}`) or a
+ * `deepEqual` over the policy's declared fields.
+ */
+function compile(policy) {
+  const externalsRe = (policy.externals || []).map((src) => {
+    try { return new RegExp(src) } catch { return null }
+  }).filter(Boolean)
+  const compiled = { ...policy }
+  Object.defineProperty(compiled, '_externalsRe', { value: externalsRe, enumerable: false })
+  return compiled
+}
+
+/**
+ * Merge a project's `mockPolicy` over the defaults and compile it. Pure given
+ * the override object (no fs); use loadMockPolicy() to read from disk.
+ */
+export function resolveMockPolicy(override = {}) {
+  const merged = {
+    ...DEFAULT_MOCK_POLICY,
+    ...override,
+    // arrays replace wholesale when provided, else inherit the default
+    firstPartyAliasPrefixes: override.firstPartyAliasPrefixes ?? DEFAULT_MOCK_POLICY.firstPartyAliasPrefixes,
+    firstPartyPackages: override.firstPartyPackages ?? DEFAULT_MOCK_POLICY.firstPartyPackages,
+    externals: override.externals ?? DEFAULT_MOCK_POLICY.externals,
+    testUtilHints: override.testUtilHints ?? DEFAULT_MOCK_POLICY.testUtilHints,
+  }
+  return compile(merged)
+}
+
+/** Non-fatal warning sink (stderr). Kept here so both loaders warn identically. */
+function warn(msg) {
+  process.stderr.write(`lint-tests: ${msg}\n`)
+}
+
+/**
+ * Read+resolve `mockPolicy` from one config file. Returns the resolved policy,
+ * or `null` when the file does not exist (so the dir-search can fall through).
+ * A *malformed* file resolves to defaults AND warns — a silent fallback would let
+ * a typo'd config that meant `enabled:true` masquerade as a clean run (finding #2).
+ */
+function readConfigFile(p) {
+  if (!fs.existsSync(p)) return null
+  try {
+    const cfg = JSON.parse(fs.readFileSync(p, 'utf8'))
+    return resolveMockPolicy(cfg.mockPolicy ?? {})
+  } catch (e) {
+    warn(`ignoring malformed ${p} (${e.message}); mock-policy running on defaults`)
+    return resolveMockPolicy({})
+  }
+}
+
+/**
+ * Discover `coverage.config.json` / `.coverage.config.json` in rootDir and resolve
+ * its `mockPolicy`. Returns the compiled default policy when absent/unparsable
+ * (never throws — a missing config must not break the gate).
+ */
+export function loadMockPolicy(rootDir = process.cwd()) {
+  for (const name of ['coverage.config.json', '.coverage.config.json']) {
+    const got = readConfigFile(path.join(rootDir, name))
+    if (got) return got
+  }
+  return resolveMockPolicy({})
+}
+
+/**
+ * Resolve the policy for an explicit `--config <file>`. Reads THAT file (finding
+ * #1: the old caller passed only its dirname, so a non-standard filename was
+ * silently discarded and the gate ran on defaults). Falls back to dir-discovery
+ * when no file is given, and WARNS (non-fatal) when the named file is missing —
+ * a declared config that doesn't apply must never look like a clean pass.
+ */
+export function loadMockPolicyFromFile(configFile, rootDir = process.cwd()) {
+  if (!configFile) return loadMockPolicy(rootDir)
+  const got = readConfigFile(configFile)
+  if (got) return got
+  warn(`--config ${configFile} not found; mock-policy running on defaults`)
+  return resolveMockPolicy({})
+}
+
+/**
+ * Extract the mocked module specifier from a (comment-stripped) line of test
+ * code, or null. Covers the JS/TS module-mock front-ends: `vi.mock`/`vi.doMock`,
+ * `jest.mock`/`jest.doMock`, `vitest.mock`. Other ecosystems (e.g. Python
+ * `patch('a.b.c')`) are a future adapter — keep one matcher per ecosystem so the
+ * core classify logic stays shared. Returns the FIRST string argument only.
+ */
+export function extractMockTarget(codeLine) {
+  const m = /\b(?:vi|jest|vitest)\s*\.\s*(?:mock|doMock)\s*\(\s*(['"`])([^'"`]+)\1/.exec(codeLine || '')
+  return m ? m[2] : null
+}
+
+/**
+ * Classify a mock target as an internal seam (a gap) or an allowed external.
+ * Decidable given the policy — no fs, no module resolution at runtime; the
+ * project's declared topology supplies the facts.
+ *
+ * Precedence: declared externals > stdlib > relative(util vs source) >
+ * first-party alias > first-party package > bare package (external default).
+ */
+export function classifyMockTarget(target, policy = DEFAULT_MOCK_POLICY) {
+  const p = policy._externalsRe ? policy : compile(policy)
+  if (!target) return { internal: false, reason: 'no target' }
+
+  for (const re of p._externalsRe) {
+    if (re.test(target)) return { internal: false, reason: 'declared external' }
+  }
+  if (target.startsWith('node:')) return { internal: false, reason: 'node builtin' }
+
+  if (target.startsWith('.')) {
+    const segs = target.split('/')
+    if (segs.some((s) => p.testUtilHints.includes(s))) {
+      return { internal: false, reason: 'relative test util/fixture/mock' }
+    }
+    return { internal: true, reason: 'relative import into first-party source' }
+  }
+
+  for (const pre of p.firstPartyAliasPrefixes) {
+    if (target.startsWith(pre)) return { internal: true, reason: `first-party alias "${pre}"` }
+  }
+  for (const fp of p.firstPartyPackages) {
+    const base = fp.endsWith('/') ? fp.slice(0, -1) : fp
+    if (target === base || target.startsWith(`${base}/`)) {
+      return { internal: true, reason: `first-party package "${fp}"` }
+    }
+  }
+  return { internal: false, reason: 'external package' }
+}

package/skills/engineering/test-quality/scripts/mock-policy-config.test.mjs

@@ -0,0 +1,119 @@
+// Tests for the mock-policy classifier (pure; one fs case via a temp dir).
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import {
+  DEFAULT_MOCK_POLICY,
+  resolveMockPolicy,
+  loadMockPolicy,
+  loadMockPolicyFromFile,
+  extractMockTarget,
+  classifyMockTarget,
+} from './mock-policy-config.mjs'
+
+test('default policy is zero-tolerance: default-on, no waiver tag', () => {
+  assert.equal(DEFAULT_MOCK_POLICY.enabled, true)
+  // the inline-waiver escape hatch is gone
+  assert.equal(DEFAULT_MOCK_POLICY.waiverTag, undefined)
+})
+
+test('extractMockTarget pulls the specifier from vi/jest/vitest mock+doMock', () => {
+  assert.equal(extractMockTarget("vi." + "mock('@/lib/x')"), '@/lib/x')
+  assert.equal(extractMockTarget('jest.' + 'mock("pkg")'), 'pkg')
+  assert.equal(extractMockTarget('vi.' + 'doMock(`@/a/b`)'), '@/a/b')
+  assert.equal(extractMockTarget('vitest.' + 'mock("./rel")'), './rel')
+  assert.equal(extractMockTarget('const x = mockThing()'), null) // bare mock() is not a module mock
+  assert.equal(extractMockTarget('expect(x).toBe(1)'), null)
+})
+
+test('classify: first-party alias @/ and ~/ are internal seams (the incident case)', () => {
+  const p = resolveMockPolicy({})
+  assert.equal(classifyMockTarget('@/lib/org-allowlist-client', p).internal, true)
+  assert.equal(classifyMockTarget('~/services/cp', p).internal, true)
+})
+
+test('classify: stdlib and third-party packages are external (exempt)', () => {
+  const p = resolveMockPolicy({})
+  assert.equal(classifyMockTarget('node:fs', p).internal, false)
+  assert.equal(classifyMockTarget('react', p).internal, false)
+  assert.equal(classifyMockTarget('@playwright/test', p).internal, false)
+})
+
+test('classify: relative import into source is internal; into a test util/fixture is not', () => {
+  const p = resolveMockPolicy({})
+  assert.equal(classifyMockTarget('../services/payments', p).internal, true)
+  assert.equal(classifyMockTarget('./helpers/operator-session-store', p).internal, false)
+  assert.equal(classifyMockTarget('../__mocks__/cp', p).internal, false)
+  assert.equal(classifyMockTarget('../fixtures/data', p).internal, false)
+})
+
+test('classify: declared first-party workspace package is internal', () => {
+  const p = resolveMockPolicy({ firstPartyPackages: ['@acme/'] })
+  assert.equal(classifyMockTarget('@acme/db', p).internal, true)
+  assert.equal(classifyMockTarget('@acme', p).internal, true)
+  assert.equal(classifyMockTarget('@other/db', p).internal, false)
+})
+
+test('classify: declared externals allowlist exempts a first-party-looking target', () => {
+  const p = resolveMockPolicy({ externals: ['^@/generated/'] })
+  assert.equal(classifyMockTarget('@/generated/openapi', p).internal, false) // exempted
+  assert.equal(classifyMockTarget('@/lib/x', p).internal, true) // still flagged
+})
+
+test('compiled _externalsRe is non-enumerable: does not leak into JSON / enumeration', () => {
+  const p = resolveMockPolicy({ externals: ['^@/generated/'] })
+  // the compiled RegExp cache works...
+  assert.equal(classifyMockTarget('@/generated/openapi', p).internal, false)
+  // ...but is hidden from enumeration and serialization
+  assert.ok(!Object.keys(p).includes('_externalsRe'))
+  assert.equal(JSON.parse(JSON.stringify(p))._externalsRe, undefined)
+})
+
+test('loadMockPolicy reads coverage.config.json topology, defaults to on with no config', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mpc-'))
+  // no config → zero-tolerance default (on), conventional topology
+  assert.equal(loadMockPolicy(dir).enabled, true)
+  // with config → declared topology is merged in (config declares topology, not on/off)
+  fs.writeFileSync(
+    path.join(dir, 'coverage.config.json'),
+    JSON.stringify({ mockPolicy: { firstPartyPackages: ['@acme/'] } }),
+  )
+  const p = loadMockPolicy(dir)
+  assert.equal(p.enabled, true)
+  assert.deepEqual(p.firstPartyPackages, ['@acme/'])
+  // inherited default array still present
+  assert.ok(p.firstPartyAliasPrefixes.includes('@/'))
+})
+
+test('loadMockPolicy never throws on malformed config (and stays on)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mpc-'))
+  fs.writeFileSync(path.join(dir, 'coverage.config.json'), '{ not json')
+  assert.equal(loadMockPolicy(dir).enabled, true)
+})
+
+test('loadMockPolicyFromFile reads the NAMED file (finding #1: not just its dirname)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mpc-'))
+  const file = path.join(dir, 'team-coverage.json') // deliberately non-standard name
+  fs.writeFileSync(file, JSON.stringify({ mockPolicy: { enabled: true, externals: ['^@/generated/'] } }))
+  const p = loadMockPolicyFromFile(file)
+  assert.equal(p.enabled, true)
+  // the declared externals must actually apply (proof the file was read, not defaults)
+  assert.equal(classifyMockTarget('@/generated/openapi', p).internal, false)
+  assert.equal(classifyMockTarget('@/lib/auth', p).internal, true)
+})
+
+test('loadMockPolicyFromFile falls back to defaults when the named file is missing', () => {
+  // finding #1: a declared config that does not apply must not look like a clean pass.
+  // (It warns on stderr; here we assert the zero-tolerance default — gate stays ON.)
+  const p = loadMockPolicyFromFile(path.join(os.tmpdir(), 'definitely-absent-config-xyz.json'))
+  assert.equal(p.enabled, true)
+})
+
+test('loadMockPolicyFromFile with no argument discovers coverage.config.json in cwd', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mpc-'))
+  fs.writeFileSync(path.join(dir, 'coverage.config.json'), JSON.stringify({ mockPolicy: { enabled: true } }))
+  assert.equal(loadMockPolicyFromFile(undefined, dir).enabled, true)
+})

package/skills/engineering/test-quality/scripts/persist-conventions-core.mjs

@@ -0,0 +1,117 @@
+// persist-conventions-core — write one skill's section into a repo's
+// CONTRIBUTING.md, point AGENTS.md at the file, and make CLAUDE.md a symlink to
+// AGENTS.md (Claude Code reads CLAUDE.md, not AGENTS.md). Import-only: each skill's
+// `persist-conventions.mjs` is the always-running CLI wrapper that names its
+// section, so no main-module guard here.
+//
+// Byte-identical copies live in test-quality (Testing conventions), github-flow
+// (CI conventions, Delivery) and data-catalog (Data catalog conventions);
+// skills/conventions-sections.test.mjs keeps them identical and proves the sections
+// coexist in one file.
+//
+// A section sits between `conventions:<id>` markers, so a re-run replaces only
+// that block and keeps everything else, including other skills' sections.
+// Nothing is written without --write: the user triggers the write, not an agent.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const CONTRIBUTING_FILE = 'CONTRIBUTING.md'
+const MENTIONS_CONTRIBUTING = /(?:^|[^\w-])CONTRIBUTING\.md/
+
+export const AGENTS_SECTION = [
+  '## Contributing',
+  '',
+  `Follow [${CONTRIBUTING_FILE}](${CONTRIBUTING_FILE}) when writing, reviewing, or delivering code: tests, CI, data definitions, and what to do after each commit.`,
+  '',
+].join('\n')
+
+export function markers(id) {
+  return [`<!-- conventions:${id}:start -->`, `<!-- conventions:${id}:end -->`]
+}
+
+export function sectionBlock({ id, owner, body }) {
+  const [start, end] = markers(id)
+  const note = `<!-- Written by the ${owner} skill: re-run its persist-conventions.mjs --write to update; edit outside these markers. -->`
+  return `${start}\n${note}\n\n${body.trim()}\n${end}\n`
+}
+
+// Pure: the new CONTRIBUTING.md text given the current one (or null).
+export function renderConventions(current, id, block) {
+  if (current == null) return `# Contributing\n\n${block}`
+  const [start, end] = markers(id)
+  const from = current.indexOf(start)
+  const to = current.indexOf(end)
+  if (from !== -1 && to > from) {
+    const after = current.slice(to + end.length).replace(/^\r?\n/, '')
+    return current.slice(0, from) + block + after
+  }
+  return `${current.replace(/\s*$/, '')}\n\n${block}`
+}
+
+// Pure: the new AGENTS.md text given the current one (or null).
+export function renderAgents(current) {
+  if (current == null) return `# AGENTS.md\n\n${AGENTS_SECTION}`
+  if (MENTIONS_CONTRIBUTING.test(current)) return current
+  return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
+}
+
+// A missing CLAUDE.md becomes a symlink to AGENTS.md.
+export const LINK_TO_AGENTS = Symbol('link CLAUDE.md to AGENTS.md')
+
+// Pure: the new CLAUDE.md text given the current one (or null). A missing file
+// becomes LINK_TO_AGENTS; a regular file keeps its content and gains the pointer
+// unless it already names AGENTS.md or CONTRIBUTING.md.
+export function renderClaude(current) {
+  if (current == null) return LINK_TO_AGENTS
+  if (/(?:^|[^\w-])(?:AGENTS|CONTRIBUTING)\.md/.test(current)) return current
+  return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
+}
+
+export function persist(repoRoot, section, { write = false } = {}) {
+  const block = sectionBlock(section)
+  const plan = [
+    [CONTRIBUTING_FILE, (text) => renderConventions(text, section.id, block)],
+    ['AGENTS.md', renderAgents],
+    ['CLAUDE.md', renderClaude],
+  ]
+  return plan.map(([name, render]) => {
+    const file = path.join(repoRoot, name)
+    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) return { file: name, action: 'unchanged' }
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
+    const next = render(current)
+    const action = current == null ? 'create' : next === current ? 'unchanged' : 'update'
+    if (next === LINK_TO_AGENTS) {
+      if (write) fs.symlinkSync('AGENTS.md', file)
+      return { file: name, action: 'link' }
+    }
+    if (write && action !== 'unchanged') fs.writeFileSync(file, next)
+    return { file: name, action }
+  })
+}
+
+// `section` = { id, owner, title, body }. Exit 0 on success, 2 on a usage error.
+export function runCli(argv, section, { cwd = process.cwd(), log = console.log } = {}) {
+  let repoRoot = cwd
+  let write = false
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--write') write = true
+    else if (argv[i] === '--repo-root' && argv[i + 1]) repoRoot = path.resolve(cwd, argv[++i])
+    else {
+      log(`persist-conventions: unknown argument ${argv[i]}`)
+      return 2
+    }
+  }
+  if (!fs.statSync(repoRoot, { throwIfNoEntry: false })?.isDirectory()) {
+    log(`persist-conventions: not a directory: ${repoRoot}`)
+    return 2
+  }
+  const results = persist(repoRoot, section, { write })
+  const done = { create: 'created', link: 'linked to AGENTS.md', update: 'updated', unchanged: 'unchanged' }
+  for (const r of results) log(`  ${r.file}: ${write || r.action === 'unchanged' ? done[r.action] : `would ${r.action}`}`)
+  const changed = results.filter((r) => r.action !== 'unchanged').length
+  log(write
+    ? `persist-conventions: ${section.title}: ${changed} file(s) written, ${results.length - changed} unchanged`
+    : `persist-conventions: ${section.title}: preview only, ${changed} file(s) would change; re-run with --write to write`)
+  return 0
+}

package/skills/engineering/test-quality/scripts/persist-conventions.mjs

@@ -0,0 +1,17 @@
+// persist-conventions — the test principles as the `## Testing conventions`
+// section of a repo's CONTRIBUTING.md (../SKILL.md, Persist mode). Run only when
+// the user asks; previews unless --write.
+//
+//   node persist-conventions.mjs [--repo-root <dir>] [--write]
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { runCli } from './persist-conventions-core.mjs'
+
+const SECTION = {
+  id: 'testing',
+  owner: 'test-quality',
+  title: 'Testing conventions',
+  body: fs.readFileSync(fileURLToPath(new URL('../references/testing-conventions.md', import.meta.url)), 'utf8'),
+}
+
+process.exitCode = runCli(process.argv.slice(2), SECTION)

package/skills/engineering/test-quality/scripts/persist-conventions.test.mjs

@@ -0,0 +1,104 @@
+// Tests for persist-conventions: the real CLI against real files in a temp repo.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { markers } from './persist-conventions-core.mjs'
+
+const CLI = fileURLToPath(new URL('./persist-conventions.mjs', import.meta.url))
+const SKILL = readFileSync(fileURLToPath(new URL('../SKILL.md', import.meta.url)), 'utf8')
+const TEMPLATE = readFileSync(fileURLToPath(new URL('../references/testing-conventions.md', import.meta.url)), 'utf8')
+const [START, END] = markers('testing')
+
+function withRepo(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'persist-conventions-'))
+  try {
+    return fn(dir, (name) => readFileSync(join(dir, name), 'utf8'))
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+function run(dir, ...args) {
+  const res = spawnSync(process.execPath, [CLI, '--repo-root', dir, ...args], { encoding: 'utf8' })
+  return { code: res.status, out: res.stdout }
+}
+
+test('the persisted conventions carry one rule per SKILL.md principle, in order', () => {
+  const fromSkill = [...SKILL.matchAll(/^\| (\d) \| \[/gm)].map((m) => Number(m[1]))
+  const fromTemplate = [...TEMPLATE.matchAll(/^(\d+)\. /gm)].map((m) => Number(m[1]))
+  assert.ok(fromSkill.length >= 5, 'principle table not found in SKILL.md')
+  assert.deepEqual(fromTemplate, fromSkill)
+})
+
+test('without --write it previews and writes nothing', () => {
+  withRepo((dir) => {
+    const { code, out } = run(dir)
+    assert.equal(code, 0)
+    assert.match(out, /CONTRIBUTING\.md: would create/)
+    assert.match(out, /re-run with --write to write$/m)
+    assert.equal(existsSync(join(dir, 'CONTRIBUTING.md')), false)
+    assert.equal(existsSync(join(dir, 'AGENTS.md')), false)
+  })
+})
+
+test('--write creates CONTRIBUTING.md and AGENTS.md, links CLAUDE.md to it, and a re-run changes nothing', () => {
+  withRepo((dir, read) => {
+    const first = run(dir, '--write')
+    assert.equal(first.code, 0)
+    assert.match(first.out, /CONTRIBUTING\.md: created/)
+    assert.match(first.out, /AGENTS\.md: created/)
+    assert.match(first.out, /CLAUDE\.md: linked to AGENTS\.md/)
+    const conventions = read('CONTRIBUTING.md')
+    assert.ok(conventions.startsWith(`# Contributing\n\n${START}`))
+    assert.ok(conventions.includes('## Testing conventions'))
+    assert.ok(conventions.includes("6. Don't test config files"))
+    assert.match(read('AGENTS.md'), /\[CONTRIBUTING\.md\]\(CONTRIBUTING\.md\)/)
+
+    assert.ok(lstatSync(join(dir, 'CLAUDE.md')).isSymbolicLink())
+
+    const before = [conventions, read('AGENTS.md'), read('CLAUDE.md')]
+    assert.match(run(dir, '--write').out, /0 file\(s\) written, 3 unchanged$/m)
+    assert.deepEqual([read('CONTRIBUTING.md'), read('AGENTS.md'), read('CLAUDE.md')], before)
+  })
+})
+
+test('a stale section is replaced and the rest of each file is kept', () => {
+  withRepo((dir, read) => {
+    writeFileSync(join(dir, 'CONTRIBUTING.md'), `# Contributing\n\nUse tabs.\n\n${START}\nold principles\n${END}\n\n## Naming\n\ncamelCase.\n`)
+    writeFileSync(join(dir, 'AGENTS.md'), '# Agents\n\nRun `pnpm test`.\n')
+    run(dir, '--write')
+    const conventions = read('CONTRIBUTING.md')
+    assert.ok(conventions.startsWith('# Contributing\n\nUse tabs.\n\n'))
+    assert.ok(conventions.endsWith(`${END}\n\n## Naming\n\ncamelCase.\n`))
+    assert.ok(!conventions.includes('old principles'))
+    assert.equal(conventions.split(START).length, 2) // exactly one section
+    assert.ok(read('AGENTS.md').startsWith('# Agents\n\nRun `pnpm test`.\n\n## Contributing'))
+  })
+})
+
+test('an AGENTS.md that already names CONTRIBUTING.md is left alone; OLD_CONTRIBUTING.md is not a mention', () => {
+  withRepo((dir, read) => {
+    const agents = '# Agents\n\nSee CONTRIBUTING.md.\n'
+    writeFileSync(join(dir, 'AGENTS.md'), agents)
+    assert.match(run(dir, '--write').out, /AGENTS\.md: unchanged/)
+    assert.equal(read('AGENTS.md'), agents)
+  })
+  withRepo((dir, read) => {
+    writeFileSync(join(dir, 'AGENTS.md'), '# Agents\n\nSee OLD_CONTRIBUTING.md.\n')
+    assert.match(run(dir, '--write').out, /AGENTS\.md: updated/)
+    assert.match(read('AGENTS.md'), /\[CONTRIBUTING\.md\]\(CONTRIBUTING\.md\)/)
+  })
+})
+
+test('an unknown argument or a missing repo root is a usage error', () => {
+  withRepo((dir) => {
+    assert.equal(run(dir, '--force').code, 2)
+    assert.equal(run(join(dir, 'missing')).code, 2)
+    assert.equal(existsSync(join(dir, 'CONTRIBUTING.md')), false)
+  })
+})

package/skills/risk-compliance/compliance-audit/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO