dsh-vibe-math 2.7.2 → 2.8.0

package/scripts/clean-temp.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * TEMP HYGIENE (task-12) — sweep STALE test scratch directories and prefer a roomier temp root.
+ *
+ * WHY THIS EXISTS (measured, 2026-10 on this machine): the suites create their workspace with
+ * `mkdtempSync(join(tmpdir(), '<prefix>-…'))` and remove it in `finally` — but a suite KILLED by the
+ * runner's per-suite timeout cannot clean up, and some suites create many directories per run. After
+ * hundreds of sweeps `%TEMP%` had reached **248,737 top-level entries, 245,288 of them ours**
+ * (`vibe-*` 221,939, `v2-fix-*` 23,160, …), with 111,223 older than 24 h (oldest ~2 weeks).
+ *
+ * TWO RULES, both bounded:
+ *   1. SWEEP: delete only entries at the TOP LEVEL of the temp root, only whose name starts with a
+ *      prefix ACTUALLY USED BY THE SUITES (extracted from `tests/*.mjs`, never hand-written), and only
+ *      when older than `--age-hours` (default 6 h — a concurrently running gate's dirs stay safe).
+ *   2. PREFER D:: when `D:\_tmp` can be created, point TEMP/TMP/TMPDIR at it (the suites follow
+ *      `os.tmpdir()` automatically, so this needs NO product change). Never hard-fail: if the drive is
+ *      absent the ambient temp root is kept.
+ *
+ * Usage:
+ *   node scripts/clean-temp.mjs                     # sweep (age 6 h) and print counts
+ *   node scripts/clean-temp.mjs --dry-run           # print the plan, delete nothing
+ *   node scripts/clean-temp.mjs --age-hours=12      # change the threshold
+ *   node scripts/clean-temp.mjs --root=<dir>        # sweep another temp root (mainly for tests)
+ *   node scripts/clean-temp.mjs --self-test         # prove the guards below (fresh dirs are NEVER swept)
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const TESTS = join(REPO, 'tests')
+
+/** Prefixes the suites really use — extracted from their own `mkdtempSync(join(tmpdir(), '<prefix>'))` calls. */
+export function suitePrefixes(testsDir = TESTS) {
+  const out = new Set()
+  let files = []
+  try { files = readdirSync(testsDir) } catch (e) { return [] }
+  for (const f of files) {
+    if (!f.endsWith('.mjs')) continue
+    let text = ''
+    try { text = readFileSync(join(testsDir, f), 'utf8') } catch (e) { continue }
+    for (const m of text.matchAll(/mkdtempSync\(\s*join\(\s*tmpdir\(\)\s*,\s*'([^']+)'/g)) out.add(m[1])
+    for (const m of text.matchAll(/mkdtempSync\(\s*join\(\s*tmpdir\(\)\s*,\s*"([^"]+)"/g)) out.add(m[1])
+  }
+  return [...out].sort()
+}
+
+/**
+ * PURE planner: which entries may be deleted. `entries` are `{name, mtimeMs}` already read from the
+ * temp root. An entry qualifies only if BOTH hold: its name starts with a suite prefix, and it is older
+ * than the threshold. (This is the function the mutant family attacks: replacing the age test with
+ * `true` must make the "a FRESH dir is never swept" check go red BY NAME.)
+ */
+export function planSweep(entries, { prefixes, ageHours = 6, now = Date.now() } = {}) {
+  const cut = now - ageHours * 3600 * 1000
+  return entries
+    .filter((e) => Array.isArray(prefixes) ? prefixes.some((p) => String(e.name).startsWith(p)) : false)
+    .filter((e) => Number(e.mtimeMs) < cut)
+    .map((e) => e.name)
+}
+
+/** Read the top level of a temp root into planner entries. Only DIRECTORIES are considered. */
+export function listTop(root) {
+  const out = []
+  let names = []
+  try { names = readdirSync(root, { withFileTypes: true }) } catch (e) { return out }
+  for (const d of names) {
+    if (!d.isDirectory()) continue
+    let mtimeMs = 0
+    try { mtimeMs = statSync(join(root, d.name)).mtimeMs } catch (e) { continue }
+    out.push({ name: d.name, mtimeMs })
+  }
+  return out
+}
+
+/** Delete the planned entries. Returns counts so callers can print a checkable summary. */
+export function sweep({ root = tmpdir(), prefixes, ageHours = 6, dryRun = false, log = () => {} } = {}) {
+  const all = listTop(root)
+  const doomed = planSweep(all, { prefixes, ageHours })
+  if (dryRun) return { root, scanned: all.length, planned: doomed.length, deleted: 0, failed: 0, dryRun: true }
+  let deleted = 0
+  let failed = 0
+  for (const name of doomed) {
+    try { rmSync(join(root, name), { recursive: true, force: true }); deleted++ } catch (e) { failed++ }
+  }
+  log('temp-hygiene: root=' + root + ' scanned=' + all.length + ' stale=' + doomed.length + ' deleted=' + deleted + ' failed=' + failed + ' ageHours=' + ageHours)
+  return { root, scanned: all.length, planned: doomed.length, deleted, failed }
+}
+
+/** `D:\_tmp` when the D: drive is usable; otherwise null (keep the ambient temp root). Never throws. */
+export function preferredTempRoot(candidate = 'D:\\_tmp') {
+  try {
+    if (!existsSync(candidate)) mkdirSync(candidate, { recursive: true })
+    return existsSync(candidate) ? candidate : null
+  } catch (e) { return null }
+}
+
+/** Point TEMP/TMP/TMPDIR at `root` (children inherit; `os.tmpdir()` follows). No-op when root is falsy. */
+export function useTempRoot(root) {
+  if (!root) return false
+  process.env.TEMP = root
+  process.env.TMP = root
+  process.env.TMPDIR = root
+  return true
+}
+
+/**
+ * Leftover-PROCESS detector (task-15). Measured motivation: a leftover DSH host (`--profile vmfix7`,
+ * started two days earlier, its parent gone) had burned **197,410 s of CPU** on this 4-core machine - a
+ * full core, permanently. With it, whole-gate `sum of suite times` went 2822 s -> 7875 s (x2.8) and
+ * individual suites ran 1.3x-4.5x slower, so honest suites reported failures that never reproduced
+ * standalone. The rule is deliberately NARROW: flag a process only when its command line matches THIS
+ * project/team AND its parent is gone (a process the running gate spawned has a live parent, so a healthy
+ * gate is never flagged - that property is asserted in `--self-test` and mutated by the family).
+ */
+export const DEFAULT_PROCESS_PATTERNS = [
+  /--profile\s+\S+/,              // a DSH host started against any profile (including our clones)
+  /[\\/]review[\\/][^\\/]*\.mjs/, // the dev-only harness scripts kept under _oneoff/review
+  /[\\/]tests[\\/][^\\/]*\.mjs/,  // a test/probe script (gates, mutant families)
+  /--temp-dry-run/,               // another gate run
+]
+
+export function suspectProcesses(entries, { selfPids = [], patterns = DEFAULT_PROCESS_PATTERNS } = {}) {
+  const self = new Set((selfPids || []).map((p) => String(p)))
+  return (entries || []).filter((e) => {
+    if (!e || self.has(String(e.pid))) return false
+    if (!patterns.some((re) => re.test(String(e.cmd || '')))) return false
+    return e.parentGone === true          // the safety property: a live parent means something owns it
+  })
+}
+
+/**
+ * List node processes with a `parentGone` flag. Windows-only in practice (PowerShell JSON); other
+ * platforms return [] rather than pretending. `exec` is injectable so the self-test can feed fixtures.
+ */
+export function listProcesses({ exec = null } = {}) {
+  if (process.platform !== 'win32' && !exec) return []
+  const ps = "$live=@{}; Get-Process | ForEach-Object { $live[[int]$_.Id]=1 }; " +
+    "Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'node.exe' } | ForEach-Object { " +
+    "[pscustomobject]@{ pid=[int]$_.ProcessId; parent=[int]$_.ParentProcessId; cmd=[string]$_.CommandLine; " +
+    "parentGone=(-not $live.ContainsKey([int]$_.ParentProcessId)); created=[string]$_.CreationDate } } | ConvertTo-Json -Compress"
+  try {
+    const run = exec || ((args) => execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', args], { encoding: 'utf8', timeout: 30000 }))
+    const raw = String(run(ps) || '').trim()
+    if (!raw) return []
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed : [parsed]
+  } catch (e) { return [] }
+}
+
+export function formatSuspect(s) {
+  const cmd = String(s.cmd || '')
+  return '  pid=' + s.pid + '  parent=' + s.parent + (s.parentGone ? ' (GONE)' : '') + '  ' + (s.created || '') + '  ' + cmd.slice(0, 120)
+}
+
+const argv = process.argv.slice(2)
+const has = (n) => argv.includes('--' + n)
+const val = (n, d) => { const a = argv.find((x) => x.startsWith('--' + n + '=')); return a ? a.split('=').slice(1).join('=') : d }
+
+if (has('self-test')) {
+  // The GUARD: these three checks fail BY NAME if the planner's prefix test or age test is broken.
+  const now = Date.now()
+  const prefixes = ['vibe-', 'v2-fix-']
+  const entries = [
+    { name: 'vibe-fresh-abc', mtimeMs: now - 60 * 1000 },              // fresh  ⇒ must NOT be planned
+    { name: 'vibe-stale-abc', mtimeMs: now - 48 * 3600 * 1000 },       // stale  ⇒ MUST be planned
+    { name: 'v2-fix-stale', mtimeMs: now - 48 * 3600 * 1000 },         // stale  ⇒ MUST be planned
+    { name: 'unrelated-stale', mtimeMs: now - 48 * 3600 * 1000 },      // foreign⇒ must NOT be planned
+    { name: 'vibestale-nodash', mtimeMs: now - 48 * 3600 * 1000 },     // prefix must match exactly
+  ]
+  const planned = planSweep(entries, { prefixes, ageHours: 6, now })
+  const failures = []
+  const check = (cond, label) => { console.log((cond ? 'PASS ' : 'FAIL - ') + label); if (!cond) failures.push(label) }
+  check(!planned.includes('vibe-fresh-abc'), 'TEMP-HYGIENE: a FRESH suite dir is never swept (age threshold respected)')
+  check(planned.includes('vibe-stale-abc') && planned.includes('v2-fix-stale'), 'TEMP-HYGIENE: STALE dirs with a suite prefix ARE swept')
+  check(!planned.includes('unrelated-stale') && !planned.includes('vibestale-nodash'), 'TEMP-HYGIENE: only exact suite prefixes are swept (no glob-like overreach)')
+  const live = suitePrefixes()
+  check(live.length >= 3, 'TEMP-HYGIENE: the prefix table is EXTRACTED from the suites (found ' + live.length + ': ' + live.slice(0, 4).join(', ') + ' …)')
+  // task-15: the leftover-PROCESS predicate, tested on fixtures so the property is checkable and mutable.
+  const procs = [
+    { pid: 1, parent: 999, parentGone: true, cmd: 'node tests/run-tests.mjs --temp-dry-run' },  // excluded via selfPids ONLY
+    { pid: 5, parent: 995, parentGone: false, cmd: 'node tests/run-tests.mjs --temp-dry-run' }, // LIVE parent -> never suspect
+    { pid: 2, parent: 998, parentGone: true, cmd: 'node tests/run-tests.mjs --temp-dry-run' },  // an ORPHANED gate
+    { pid: 3, parent: 997, parentGone: true, cmd: 'node bin.js --profile vmfix7 --port 7791' }, // the measured leftover
+    { pid: 4, parent: 996, parentGone: true, cmd: 'C:/apps/editor/editor.exe --open notes.md' },// unrelated program
+  ]
+  const susp = suspectProcesses(procs, { selfPids: [1] })
+  check(!susp.some((s) => s.pid === 1), 'TEMP-HYGIENE: an explicitly excluded pid (self / own parent) is never reported')
+  // This one is what the "parent-gone" mutation attacks: pid 5 is NOT excluded by selfPids, so only the
+  // live-parent property keeps it out of the report.
+  check(!susp.some((s) => s.pid === 5), 'TEMP-HYGIENE: a process with a LIVE parent (our running gate) is never called a leftover')
+  check(susp.some((s) => s.pid === 2) && susp.some((s) => s.pid === 3), 'TEMP-HYGIENE: ORPHANED project/team processes are reported (incl. a DSH host started against a clone profile)')
+  check(!susp.some((s) => s.pid === 4), 'TEMP-HYGIENE: an unrelated program is never reported (the command-line gate holds)')
+  console.log('temp-hygiene self-test: ' + (failures.length ? failures.length + ' failure(s)' : 'all checks passed'))
+  process.exit(failures.length ? 1 : 0)
+}
+
+// CLI entry detection must survive being IMPORTED (then `process.argv[1]` is undefined — the naive
+// `process.argv[1].replace(...)` form threw a TypeError for every importer).
+const isCli = (() => {
+  try { return !!process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url) } catch (e) { return false }
+})()
+
+if (isCli) {
+  // task-15: read-only leftover-process report. `--kill` must be asked for explicitly, and the current
+  // process + its parent are always excluded (a running gate must never kill itself).
+  if (has('ps')) {
+    const procs = listProcesses()
+    const susp = suspectProcesses(procs, { selfPids: [process.pid, process.ppid] })
+    console.log('temp-hygiene --ps: scanned ' + procs.length + ' node process(es); suspects=' + susp.length)
+    for (const s of susp) console.log(formatSuspect(s))
+    if (has('kill')) {
+      let killed = 0
+      for (const s of susp) { try { process.kill(Number(s.pid), 'SIGKILL'); killed++ } catch (e) { /* already gone */ } }
+      console.log('temp-hygiene --ps --kill: killed=' + killed)
+    } else if (susp.length) {
+      console.log('temp-hygiene --ps: read-only. Re-run with --kill to stop them (each one steals CPU from the gate).')
+    }
+    process.exit(0)
+  }
+  const root = val('root', null)
+  if (!root) { const pref = preferredTempRoot(); if (useTempRoot(pref)) console.log('temp-hygiene: using temp root ' + pref) }
+  const res = sweep({
+    root: val('root', tmpdir()),
+    prefixes: suitePrefixes(),
+    ageHours: Number(val('age-hours', '6')),
+    dryRun: has('dry-run'),
+    log: (m) => console.log(m),
+  })
+  console.log('temp-hygiene: ' + JSON.stringify(res))
+}

package/scripts/update-doc-counts.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Regenerate the count sentences quoted by shipped docs FROM THE TREE (D1: derive, don't type).
+ *
+ *   node scripts/update-doc-counts.mjs          # rewrite in place
+ *   node scripts/update-doc-counts.mjs --check  # exit 1 if anything would change (converges: whole-line rewrites)
+ *
+ * Authority: `node tests/run-tests.mjs --counts` (the gate's own JOB list) + `package.json#files`
+ * (shipped FILE counts). Shapes come from tests/helpers/doc-counts-format.mjs, shared with the guard
+ * (tests/audit-readme-counts.mjs) and its mutant harness. Adding a test file reddens the guard; the fix
+ * is to run this script. Whole lines are rebuilt (no partial regex edits), so a corrupted previous
+ * shape is repaired rather than half-matched.
+ *
+ * Grep anchors: update-doc-counts, doc-counts-format.
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { claims, MARKERS } from '../tests/helpers/doc-counts-format.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..')
+const checkOnly = process.argv.includes('--check')
+
+const derived = JSON.parse(spawnSync(process.execPath, [join(REPO, 'tests', 'run-tests.mjs'), '--counts'], { cwd: REPO, encoding: 'utf8' }).stdout.trim())
+const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf8'))
+const shippedFiles = pkg.files.filter((f) => f.startsWith('tests/') && f.endsWith('.mjs'))
+const shipped = { total: shippedFiles.length, suites: shippedFiles.filter((f) => f.endsWith('.test.mjs')).length }
+shipped.probes = shipped.total - shipped.suites
+const c = claims(derived, shipped)
+
+function replaceLine(text, marker, canonical) {
+  const lines = text.split(/\r?\n/)
+  const i = lines.findIndex((l) => l.indexOf(marker) !== -1)
+  if (i === -1) return null
+  if (lines[i] === canonical) return text
+  lines[i] = canonical
+  return lines.join(text.includes('\r\n') ? '\r\n' : '\n')
+}
+
+const log = []
+let changed = 0
+const apply = (file, fn) => {
+  const p = join(REPO, file)
+  const before = readFileSync(p, 'utf8')
+  const after = fn(before)
+  if (after === null) { log.push('MARKER MISS: ' + file); return }
+  if (after !== before) {
+    changed++
+    if (checkOnly) log.push('WOULD CHANGE ' + file)
+    else { writeFileSync(p, after); log.push('updated ' + file) }
+  }
+}
+
+apply('README.md', (s) => replaceLine(s, MARKERS.zhBullet, c.zhBullet))
+apply('README.en.md', (s) => replaceLine(s, MARKERS.enBullet, c.enBullet))
+apply('docs/test-timing.md', (s) => replaceLine(s, MARKERS.ttRow, c.ttRow))
+apply('docs/AUDIT-CHECKLIST.md', (s) => {
+  let out = replaceLine(s, MARKERS.d1Row, c.d1Row)
+  if (out === null) return null
+  out = out.replace(/\d+ 项作业（job count）= \d+ 套件 \+ \d+ 探针\/变体/, c.ckClaim)
+  out = out.replace(/只发 `tests\/` 的 .*?（[^）]*）/, c.ckShipped)
+  return out
+})
+
+log.push((checkOnly ? 'check: ' : '') + 'derived JOBS total=' + derived.total + ' suites=' + derived.suites + ' probes=' + derived.probes
+  + ' | shipped FILES tests/*.mjs=' + shipped.total + ' (' + shipped.suites + ' suites + ' + shipped.probes + ' probes/scripts)'
+  + ' | files changed=' + changed)
+console.log(log.join('\n'))
+process.exit(checkOnly && changed ? 1 : 0)

package/tests/audit-artifact-docs.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * ARTIFACT DOCS vs CODE — the READMEs and the contract doc must not name an artifact a preset does not
+ * write, and must name the ones it does.
+ *
+ * DEFECT CLASS (D2): `Paper/<id>/paper.lock.json` was listed in the README's v4 section as "the directory's
+ * write lock, serialising concurrent rewrites/recompiles" — while v4 writes NO such file and
+ * `vibe-math-v4.js` says the shared-file lock is **NOT IMPLEMENTED** ("nothing is reserved, nothing is
+ * serialized"). The README promised a mechanism the code explicitly disclaims. The inverse direction
+ * matters too: v2/v3 DO write it (vibe-math-v2.js:3725/3732, vibe-math-v3.js:4318/4325) and their
+ * sections must list it.
+ *
+ * Run: node tests/audit-artifact-docs.mjs
+ * Env (mutant harness): ARTIFACT_README / ARTIFACT_README_EN / ARTIFACT_DOC / ARTIFACT_V2_JS /
+ * ARTIFACT_V3_JS / ARTIFACT_V4_JS / ARTIFACT_V5_JS (absolute or repo-relative).
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..')
+const ARTIFACT = 'paper.lock.json'
+let passed = 0, failed = 0
+const failures = []
+const ok = (cond, label, detail) => { if (cond) passed++; else { failed++; failures.push(label + (detail ? ' — ' + detail : '')) } }
+
+const read = (envName, rel) => {
+  const v = process.env[envName]
+  return readFileSync(v ? (isAbsolute(v) ? v : join(REPO, v)) : join(REPO, rel), 'utf8')
+}
+const count = (text, needle) => text.split(needle).length - 1
+
+// 1) CODE TRUTH: which presets write the artifact?
+const presets = {
+  v2: read('ARTIFACT_V2_JS', 'vibe-math-v2/vibe-math-v2.js'),
+  v3: read('ARTIFACT_V3_JS', 'vibe-math-v3/vibe-math-v3.js'),
+  v4: read('ARTIFACT_V4_JS', 'vibe-math-v4/vibe-math-v4.js'),
+  v5: read('ARTIFACT_V5_JS', 'vibe-math-v5/vibe-math-v5.js'),
+}
+const writers = Object.keys(presets).filter((k) => count(presets[k], ARTIFACT) > 0)
+const nonWriters = Object.keys(presets).filter((k) => count(presets[k], ARTIFACT) === 0)
+ok(writers.length > 0, 'at least one preset writes ' + ARTIFACT + ' (else the doc expectation is empty)', JSON.stringify(writers))
+ok(writers.join(',') === 'v2,v3', 'the writing presets are exactly v2,v3 (derived from code)', JSON.stringify({ writers, nonWriters }))
+
+// 2) every README mention must sit in a writer's context OR be an explicit denial
+const DENY = /(不写|未实现|无此锁|not implemented|does NOT write|no such|not write)/i
+for (const [name, envName, rel] of [['README.md', 'ARTIFACT_README', 'README.md'], ['README.en.md', 'ARTIFACT_README_EN', 'README.en.md']]) {
+  const lines = read(envName, rel).split(/\r?\n/)
+  const mentions = lines.map((l, i) => ({ n: i + 1, l })).filter((x) => x.l.indexOf(ARTIFACT) !== -1)
+  ok(mentions.length > 0, name + ' mentions ' + ARTIFACT + ' somewhere (it is a real artifact for v2/v3)')
+  const bad = mentions.filter((m) => !/v2|v3/.test(m.l) && !DENY.test(m.l))
+  ok(bad.length === 0, '★ ' + name + ': every ' + ARTIFACT + ' mention names a WRITING preset or denies the claim', JSON.stringify(bad.map((b) => b.n)))
+  const listed = mentions.filter((m) => /Paper\/<[^>]*>\/\{[^}]*paper\.lock\.json/.test(m.l))
+  ok(listed.length >= 2, '★ ' + name + ' lists ' + ARTIFACT + ' inside the v2/v3 artifact braces', 'brace mentions=' + listed.length)
+}
+
+// 3) the contract doc must state the scope (v2/v3 write it; v4/v5 do not)
+const doc = read('ARTIFACT_DOC', 'docs/final-paper.md')
+const docLines = doc.split(/\r?\n/).filter((l) => l.indexOf(ARTIFACT) !== -1)
+ok(docLines.length > 0, 'docs/final-paper.md documents ' + ARTIFACT)
+const docScope = docLines.some((l) => /v2\/v3/.test(l) && DENY.test(l))
+ok(docScope, '★ docs/final-paper.md scopes ' + ARTIFACT + ' to v2/v3 AND states that v4/v5 do not write it', docLines[0] ? docLines[0].slice(0, 80) : '(no line)')
+
+// 4) the non-writer's own disclaimer must exist in code (so the doc denial is backed by the source)
+ok(/NOT IMPLEMENTED/.test(presets.v4) && /claim_write/.test(presets.v4),
+  'vibe-math-v4.js still carries the explicit NOT-IMPLEMENTED shared-lock disclaimer (the source of the doc denial)')
+
+console.log('')
+console.log('=== ARTIFACT DOCS: ' + passed + ' passed, ' + failed + ' failed ===')
+for (const f of failures) console.error('  - ' + f)
+process.exit(failed === 0 ? 0 : 1)

package/tests/audit-artifact-docs.mutants.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Mutant harness for tests/audit-artifact-docs.mjs (ships: `tests/*.mutants.mjs`).
+ *
+ * Two single-site mutations, ONE PER DIRECTION (the guard must bite both ways):
+ *   A) a COPY of README.md whose v2/v3 brace list loses `paper.lock.json`  -> the listing assertion reddens
+ *   B) a COPY of vibe-math-v4.js that mentions `paper.lock.json`           -> the "writers are exactly v2,v3"
+ *      assertion reddens (i.e. if v4 ever gains the artifact, the docs expectation moves with the code)
+ *
+ * Run: node tests/audit-artifact-docs.mutants.mjs
+ */
+import { mkdtempSync, readFileSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = fileURLToPath(new URL('./', import.meta.url))
+const REPO = join(HERE, '..')
+const GUARD = join(HERE, 'audit-artifact-docs.mjs')
+const ARTIFACT = 'paper.lock.json'
+let passed = 0, failed = 0
+const ok = (c, l, d) => { if (c) { passed++; console.log('  ok   ' + l) } else { failed++; console.log('  FAIL ' + l + (d ? ' — ' + d : '')) } }
+
+const run = (env) => {
+  const r = spawnSync(process.execPath, [GUARD], { cwd: REPO, encoding: 'utf8', env: Object.assign({}, process.env, env || {}) })
+  const out = String(r.stdout || '') + String(r.stderr || '')
+  return { status: r.status, out, failLines: out.split('\n').filter((l) => /^  - /.test(l)) }
+}
+const baseline = run(null)
+ok(baseline.status === 0, 'baseline: the artifact-docs guard is green',
+  (baseline.out.trim().split('\n').filter(Boolean).slice(-1)[0] || '').slice(0, 80))
+
+const dir = mkdtempSync(join(tmpdir(), 'artifact-mut-'))
+// A) README loses the v2/v3 brace listing
+const zh = readFileSync(join(REPO, 'README.md'), 'utf8')
+const braces = zh.match(/Paper\/<[^>]*>\/\{[^}]*paper\.lock\.json[^}]*\}/g) || []
+if (!braces.length) ok(false, 'A: the README v2/v3 brace listing exists (harness and guard agree on the shape)', 'ANCHOR MISS')
+else {
+  const tampered = zh.split(braces[0]).join(braces[0].replace(',' + ARTIFACT, ''))
+  writeFileSync(join(dir, 'README.md'), tampered)
+  const a = run({ ARTIFACT_README: join(dir, 'README.md') })
+  const named = a.failLines.some((l) => l.indexOf('lists ' + ARTIFACT + ' inside the v2/v3 artifact braces') !== -1)
+  ok(a.status !== 0 && named, '★ A: dropping the artifact from the v2/v3 brace list reddens the guard by name', 'exit=' + a.status)
+  if (!named) for (const l of a.failLines.slice(0, 3)) console.log('      guard failure: ' + l.trim().slice(0, 130))
+}
+// B) v4 "gains" the artifact
+const v4 = readFileSync(join(REPO, 'vibe-math-v4/vibe-math-v4.js'), 'utf8')
+writeFileSync(join(dir, 'vibe-math-v4.js'), v4 + '\n// mutant: pretend v4 writes ' + ARTIFACT + '\n')
+const b = run({ ARTIFACT_V4_JS: join(dir, 'vibe-math-v4.js') })
+const namedB = b.failLines.some((l) => l.indexOf('the writing presets are exactly v2,v3') !== -1)
+ok(b.status !== 0 && namedB, '★ B: a v4 that mentions the artifact reddens the "writers are exactly v2,v3" assertion', 'exit=' + b.status)
+if (!namedB) for (const l of b.failLines.slice(0, 3)) console.log('      guard failure: ' + l.trim().slice(0, 130))
+
+rmSync(dir, { recursive: true, force: true })
+console.log('')
+console.log('=== ARTIFACT DOCS MUTANTS: ' + passed + ' passed, ' + failed + ' failed ===')
+process.exit(failed === 0 ? 0 : 1)