@ersbeth/codelife 0.0.0-bootstrap.0 → 0.11.1

package/agents/reproduce.md

@@ -0,0 +1,65 @@
+---
+name: reproduce
+description: codelife's reproduce — answers whether one claimed behaviour actually happens, with the cheapest instrument that can settle it, and returns yes, no or inconclusive as its report. Dispatched by /review-mr on one manual step of How to test; it leaves nothing behind.
+tools: Read, Grep, Glob, Bash, Write, mcp__plugin_codelife_playwright
+---
+
+You answer one question: *does this actually happen?* Your prompt carries one claim — a manual
+step of a merge request's *How to test*, its numbered actions and its **Expected** line — and the
+review summary's `app:` line when the repository is an application. You answer `yes`, `no` or
+`inconclusive`. You look for no cause, propose no fix, and write nothing to the tracker or the
+forge: the session posts what you return.
+
+1. **Restate the claim as one observable behaviour** — what would be seen, and where. A step with
+   no **Expected** line is its sentence. Vague beyond that — *something is wrong with the debounce*
+   — ends on `### reproduce question`, which the session puts to the user and answers you with.
+2. **A throwaway test first**, everywhere, an application included: it builds the state directly
+   and runs through the repository's `test:one` script. Write it inside the repository, beside the
+   tests the runner already collects and named like them, since a runner collects nothing outside
+   its root; note its path, and never stage it. A probe in the source is restored as
+   `codelife help method cause` step 3 says.
+3. **Read whether it exercised the claim.** It did, and the behaviour appeared → `yes`; it did,
+   and it did not → `no`; it did not → step 4.
+4. **The browser, when the state lives in a running page** — a render, a layout, an interaction, a
+   console error no test surfaces. Escalate because the test could not answer, never because the
+   repository is an application. The browser branch has never been walked end to end: say so when
+   you take it.
+   - No `browser_*` tool among yours means the session started before the server loaded: say the
+     restart is the user's, and stop. No shell, fetch or screenshot utility stands in for it.
+   - The application is reached at the `app:` line's URL. Down, or no `app:` line: quote the start
+     command it gives, or say there is none, and stop. You never start it, nor its backend.
+   - Walk the route; a sign-in types the credential through the server's secret substitution, never
+     read, echoed or written. `browser_snapshot` first — text, and the answer for anything in the
+     DOM; `browser_take_screenshot` only for *does this render correctly*, never headless; read
+     `browser_console_messages` every time, since rendering failures surface there and in no
+     snapshot. Close no browser another session may be using.
+   - What the browser shows is observed, never proof: the report says what test or guard would prove it.
+
+   Neither instrument, or nothing can be built → `inconclusive`, naming what was tried.
+5. **Restore the tree**: the throwaway test deleted, every probe back; `git status` shows nothing of
+   yours.
+
+`no` means the instrument ran and the behaviour did not appear; `inconclusive` means nothing was
+learned about the problem. Never return `no` for a test that did not exercise the claim.
+
+Your report is your last message, quoting what happened rather than summarising it:
+
+```markdown
+### reproduce result
+- verdict: yes | no | inconclusive
+- claim: <the claim, as one observable behaviour>
+- instrument: throwaway test | browser | none could be built
+- what happened: <the command and its output, or what the browser showed and the console said — quoted>
+- not proof: <with the browser: the test or guard that would prove it> | not needed
+- escalated: <why the test could not answer> | not needed
+- left behind: nothing — the throwaway test deleted, every probe restored
+```
+
+Or, at step 1:
+
+```markdown
+### reproduce question
+- situation: <the claim as given, and why it is not one observable behaviour>
+- options: <the behaviours it could mean>
+- recommendation: <the one you would test, and why>
+```

package/bin/codelife

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// The `codelife` command on a session's PATH (K-43, R-293): Claude Code puts a plugin's bin/ there,
+// and npm links package.json's bin. A Node file rather than a shell one, so Git Bash on Windows runs it.
+import '../scripts/codelife.mjs'

package/package.json

@@ -1 +1,40 @@
-{ "name": "@ersbeth/codelife", "version": "0.0.0-bootstrap.0", "description": "Placeholder; the first version is 0.11.0." }
+{
+  "name": "@ersbeth/codelife",
+  "version": "0.11.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/ersbeth-web/codelife.git"
+  },
+  "bin": {
+    "codelife": "bin/codelife"
+  },
+  "files": [
+    ".claude-plugin/plugin.json",
+    "bin/",
+    "skills/",
+    "agents/",
+    "scripts/",
+    "presets/"
+  ],
+  "packageManager": "pnpm@11.9.0",
+  "engines": {
+    "node": ">=22.13.0",
+    "pnpm": ">=11.9.0"
+  },
+  "scripts": {
+    "prepare": "node scripts/install.mjs",
+    "verify:commit": "node --test tests/skills.test.mjs tests/references.test.mjs tests/shell.test.mjs tests/spec-form.test.mjs",
+    "verify:push": "pnpm verify:commit && claude plugin validate . && pnpm test:all",
+    "verify:release": "pnpm verify:push && node tests/release.mjs",
+    "test:all": "node tests/prereqs.mjs && node --test \"tests/*.test.mjs\"",
+    "test:one": "node --test"
+  },
+  "dependencies": {
+    "git-cliff": "2.13.1"
+  },
+  "exports": {
+    "./presets/*": "./presets/*",
+    "./package.json": "./package.json"
+  }
+}

package/presets/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "noEmit": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true
+  }
+}

package/presets/vite.config.d.mts

@@ -0,0 +1,3 @@
+import type { UserConfig } from 'vite-plus'
+
+export function library(options: { entry: string[] }): UserConfig

package/presets/vite.config.mjs

@@ -0,0 +1,49 @@
+// One configuration for every mode: the build, the type check, the tests and the playground's dev
+// server all read it. Two configurations is a build that depends on which command was typed.
+// The base a repository's `vite.config.ts` composes: it passes its package name, its entries and
+// its own directory, and adds what is its own with `mergeConfig`. That merge concatenates arrays,
+// so what varies from one repository to the next is a parameter here, never an array to replace.
+// A plain object, not `defineConfig`'s: the repository's file wraps it, so this file imports nothing.
+export function library({ entry }) {
+  return {
+    // The tests and the playground import the library by its name, which the repository's
+    // `tsconfig.json` maps to the source in `paths`: one mapping that the type checker and Vite
+    // both read, so they always show the working tree rather than the last build.
+    resolve: {
+      tsconfigPaths: true,
+    },
+
+    // The dev server serves the playground, not the package root: the package root has no page.
+    root: process.env.PLAYGROUND ? 'playground' : undefined,
+
+    // `vp pack` is tsdown, and this block is all it reads: a Vite `build` block builds nothing here.
+    // No `external`: tsdown already leaves every `dependencies` and `peerDependencies` entry out of
+    // the bundle, so a consumer resolves one copy of each.
+    pack: {
+      entry,
+      format: ['esm'],
+      // Written rather than inferred: tsdown emits declarations unprompted only when the manifest
+      // names a `types` field.
+      dts: true,
+      // `dist/` is versioned and `pre-commit` stages its diff: a chunk named by its content's hash is
+      // renamed by every change, and the diff reads as a file deleted and another added.
+      hash: false,
+      // The extension follows the manifest's `type` — `.js` under `"type": "module"`, which is what
+      // `exports` names — rather than tsdown's fixed `.mjs`.
+      fixedExtension: false,
+      // The declarations carry the documentation a consumer's editor reads, so the JavaScript keeps
+      // no comment: tsdown would keep them all, and the size compared at the port would measure that.
+      outputOptions: { comments: false },
+    },
+
+    // Without type information every rule that needs the checker is silent, even set to `error`, and
+    // `vp check` still passes.
+    lint: {
+      options: { typeAware: true, typeCheck: true },
+    },
+
+    test: {
+      include: ['test/**/*.test.ts'],
+    },
+  }
+}

package/scripts/audit/cadence.mjs

@@ -0,0 +1,24 @@
+// The audit cadence (audit's R-248, R-172): the campaign table of docs/audit/README.md, its rows in
+// campaign order whatever order the table lists them in, and whether a full campaign is due — none
+// ever run, or the last one older than six months. `codelife overview` prints it; `codelife release
+// prep` adds what a bump asks.
+import '../node-floor.mjs';
+import { readFileSync } from 'node:fs';
+
+export function cadence(now = new Date()) {
+  let text = '';
+  try { text = readFileSync('docs/audit/README.md', 'utf8'); } catch { /* no campaign yet */ }
+  // A row's first cell is the campaign's id, bare or as a link to its frozen report.
+  const number = (row) => Number(row[0].match(/^A(\d+)/)[1]);
+  const rows = text.split('\n').filter((l) => /^\| ?\[?`?A\d+/.test(l)).map((l) => l.split('|').slice(1, -1).map((c) => c.trim()))
+    .map(([id, ...rest]) => [id.match(/A\d+[\w-]*/)[0], ...rest]).sort((a, b) => number(a) - number(b));
+  const full = rows.filter((r) => /^full/i.test(r[2] ?? '')).at(-1) ?? null;
+  let next = null, due = null;
+  if (full) {
+    // In UTC, the day clamped to the target month's length: August 31 is due February 28.
+    const [y, m, d] = full[1].split('-').map(Number), at = new Date(Date.UTC(y, m + 5, Math.min(d, new Date(Date.UTC(y, m + 6, 0)).getUTCDate())));
+    next = at.toISOString().slice(0, 10);
+    if (at < now) due = `the last full campaign, ${full[0]}, is older than six months`;
+  } else if (rows.length) due = 'no full campaign was ever run';
+  return { rows, last: rows.at(-1) ?? null, full, next, due };
+}

package/scripts/audit/close.mjs

@@ -0,0 +1,57 @@
+// `codelife audit close` (R-226, R-227, R-260): closes the campaign under way, from the repository's
+// root. Checks first, changing nothing: every finding carries its disposition, and the index holds
+// no placeholder but the two this verb fills. Then writes the index's findings by lens and the paths
+// no lens read in the end, turns its banner FROZEN, compares the tree with the fingerprint taken at
+// the open — each file that differs named, never restored — and removes the fingerprint. Prints the
+// paths the close commit carries: the campaign folder, a new domain lens, the refusal lines, and the
+// issues filed under tracker.kind none. Exit 1 on a check that fails, nothing written.
+import '../node-floor.mjs';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fingerprint, findings, idOf, inProgress, lines, partFile, parts, row, sh } from './lib.mjs';
+
+const say = (l) => console.log(`- ${l}`);
+const stop = (why) => { say(`stop: ${why}`); process.exit(1); };
+console.log('### audit close');
+const folder = inProgress() ?? stop('no campaign in progress');
+const index = join(folder, '00-index.md');
+let text = readFileSync(index, 'utf8');
+
+const all = findings(folder);
+const open = all.filter((f) => !f.disposition);
+if (open.length) stop(`findings with no disposition: ${open.map((f) => f.id).join(', ')} — file their lens's table first`);
+const left = [...new Set(text.match(/\{\{[^}]*\}\}/g) ?? [])].filter((p) => !['{{findings}}', '{{unread}}'].includes(p));
+if (left.length) stop(`the index still holds ${left.map((p) => p.slice(0, 40)).join(' · ')} — write it first`);
+
+// What no lens read in the end: each lens's last *Not reached:* line, as its judge copied it.
+const unread = [];
+for (const nn of parts(folder)) for (const [lens, body] of Object.entries(partFile(folder, nn).sections)) {
+  const last = body.filter((l) => l.startsWith('Not reached:')).at(-1);
+  if (last) unread.push(`${last.replace(/^Not reached:\s*/, '').split(' — ')[0]} (${lens}, part ${nn})`);
+}
+const table = ['| Lens | Finding | Severity | Disposition |', '|---|---|---|---|',
+  ...all.map((f) => `| ${f.lens} | [\`${f.id}\`](${f.part}/${f.path.split('/').pop()}) ${f.title} | ${f.severity} | ${f.disposition} |`)];
+const date = new Date().toISOString().slice(0, 10);
+const commit = /`([0-9a-f]+)`/.exec(row(text, 'Commit') ?? '')?.[1] ?? '?';
+text = text.replace('{{findings}}', () => (all.length ? table.join('\n') : 'None.')).replace('{{unread}}', () => unread.join(', ') || 'none')
+  .replace(/^> \*\*⚠ IN PROGRESS\.\*\*.*\n(?:>.*\n)*/m, `> **FROZEN** on ${date}. This report records what was true at \`${commit}\`. Its folder leaves the tree at the fold
+> commit; the campaign table links it at the close commit, and a finding found wrong later is corrected in its issue.\n`);
+writeFileSync(index, text);
+say(`index: ${all.length} findings by lens, never read: ${unread.length ? unread.join(', ') : 'none'}, banner FROZEN`);
+
+// The fingerprint: every file outside docs/audit/ that differs from the open. docs/spec/ holds the
+// refusal lines this campaign wrote, issues/ under tracker.kind none the issues it filed: its own.
+const print = join(folder, 'fingerprint.tsv');
+if (existsSync(print)) {
+  const before = new Map(lines(readFileSync(print, 'utf8')).map((l) => l.split('\t')));
+  const now = new Map(fingerprint().map((l) => l.split('\t')));
+  const differ = [...new Set([...before.keys(), ...now.keys()])].filter((p) => before.get(p) !== now.get(p)).sort();
+  const mine = (p) => /^(docs\/spec|issues)\//.test(p);
+  const own = differ.filter(mine), other = differ.filter((p) => !mine(p));
+  rmSync(print);
+  say(`fingerprint: ${other.length ? `${other.length} files differ from the open — ${other.join(', ')}` : 'the tree is as the campaign found it'}`);
+  if (own.length) say(`the campaign's own: ${own.join(', ')}`);
+} else say('fingerprint: none was taken at the open — the tree cannot be compared');
+
+const docs = lines(sh('git', ['status', '--porcelain', '--untracked-files=all', '--', 'docs/audit/lenses', 'docs/spec', 'issues']).stdout).map((l) => l.slice(3));
+say(`commit: docs(audits): close campaign ${idOf(folder)} — ${[folder, ...docs].join(' ')}`);

package/scripts/audit/file.mjs

@@ -0,0 +1,70 @@
+// `codelife audit file <rows file>` (K-33, R-111, R-112): files one confirmed table of the campaign
+// under way, from the repository's root. One row a line, `<id> <bug|feature> <severity>` for a
+// finding to file, `<id> known` for one an open issue carries, `<id> false`, `<id> refused
+// <address of its Rejected line>` or `<id> merged <id>`. Every row is checked before anything is
+// written. A new finding becomes an issue tagged with its id — never a second one: an issue already
+// carrying the id is taken as filed, and given the comment it lacks — its body the finding's lead,
+// then the finding whole as its first comment, its severity rewritten to the row's; a known one gets a `re-reported` comment. Each disposition is written into its
+// finding's file as the row is done, so a run cut half-way is run again on the same file.
+import '../node-floor.mjs';
+import { appendFileSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findings, idOf, inProgress, lines, pkg, sh } from './lib.mjs';
+
+const [file] = process.argv.slice(2);
+if (!file) {
+  console.error('usage: codelife audit file <rows file>');
+  process.exit(2);
+}
+const say = (l) => console.log(`- ${l}`);
+const stop = (why) => { say(`stop: ${why}`); process.exit(1); };
+console.log('### audit file');
+const folder = inProgress() ?? stop('no campaign in progress');
+const all = new Map(findings(folder).map((f) => [f.id, f]));
+let rows;
+try { rows = lines(readFileSync(file, 'utf8')).map((l) => l.trim().split(/\s+/)); } catch (e) { console.error(e.message); process.exit(2); }
+for (const [id, what, extra, ...rest] of rows) {
+  const f = all.get(id);
+  if (!f) stop(`${id}: no such finding in ${folder}`);
+  const ok = (['bug', 'feature'].includes(what) && ['critical', 'high', 'mid', 'low'].includes(extra) && !rest.length)
+    || (what === 'known' && f.known && !extra) || (what === 'false' && !extra) || (what === 'refused' && extra)
+    || (what === 'merged' && all.has(extra) && extra !== id);
+  if (!ok) stop(`${id}: '${[what, extra, ...rest].filter(Boolean).join(' ')}' is not a disposition${what === 'known' && !f.known ? ' — its finding carries no Known: #n' : ''}`);
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'codelife-file-'));
+const date = new Date().toISOString().slice(0, 10), campaign = idOf(folder);
+const tracker = (script, args) => {
+  const r = sh(process.execPath, [join(pkg, 'scripts/tracker', script), ...args]);
+  if (r.status !== 0) stop(`${script.replace('.mjs', '')} failed — ${(r.stderr || r.stdout).trim()}`);
+  return r.stdout.trim();
+};
+// The finding as an issue's comment carries it: without the lines that only the campaign reads.
+const whole = (f) => f.text.split('\n').filter((l) => !/^\*\*(Disposition|From):\*\*/.test(l)).join('\n').trim();
+const lead = (f) => f.text.split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^(#|\*\*)/.test(p)) ?? f.title;
+const write = (f, disposition) => { appendFileSync(f.path, `\n**Disposition:** ${disposition}\n`); say(`${f.id} → ${disposition}`); };
+
+for (const [id, what, extra, ...rest] of rows) {
+  const f = all.get(id);
+  if (f.disposition) { say(`${id} → ${f.disposition} (already)`); continue; }
+  if (what === 'false') write(f, 'false');
+  else if (what === 'refused') write(f, `refused — ${[extra, ...rest].join(' ')}`);
+  else if (what === 'merged') write(f, `merged into ${extra}`);
+  else if (what === 'known') {
+    writeFileSync(join(tmp, 'note.md'), `codelife: re-reported — /audit — ${date}\n\nCampaign ${campaign} observed this again, as finding ${id}: ${lead(f)}\n`);
+    tracker('note.mjs', [f.known, join(tmp, 'note.md')]);
+    write(f, `re-reported on #${f.known}`);
+  } else {
+    writeFileSync(f.path, f.text = f.text.replace(/(\*\*Severity:\*\* )(critical|high|mid|low)/, `$1${extra}`));
+    writeFileSync(join(tmp, 'issue.md'), `# ${f.title}\n\n${lead(f)}\n\n## Where it comes from\n\nAudit ${campaign}, finding ${id}: the finding whole is this issue's first comment.\n`);
+    const created = tracker('create.mjs', ['--once', what, extra, `audit:${id}`, join(tmp, 'issue.md')]);
+    const n = /#(\d+)/.exec(created)[1];
+    const posted = () => JSON.parse(tracker('view.mjs', [n])).comments.some((c) => c.body.startsWith('codelife: finding —'));
+    if (created.startsWith('created') || !posted()) {
+      writeFileSync(join(tmp, 'note.md'), `codelife: finding — /audit — ${date}\n\n${whole(f)}\n`);
+      tracker('note.mjs', [n, join(tmp, 'note.md')]);
+    }
+    write(f, `#${n}`);
+  }
+}

package/scripts/audit/fold.mjs

@@ -0,0 +1,48 @@
+// `codelife audit fold` (R-226): run once the close commit is HEAD, from the repository's root.
+// Deletes the campaign folder that commit carries, staged, and writes the campaign's row at the top
+// of docs/audit/README.md's table — its id linked to the index at the close commit on the forge,
+// its date, type, commit, findings by severity and state — in the form the cadence reads it back
+// (scripts/audit/cadence.mjs). Prints the paths the fold commit carries.
+import '../node-floor.mjs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findings, folders, idOf, pkg, read, row, sh } from './lib.mjs';
+import { parseOrigin } from '../tracker/lib.mjs';
+import { field } from '../contract.mjs';
+
+const say = (l) => console.log(`- ${l}`);
+const stop = (why) => { say(`stop: ${why}`); process.exit(1); };
+console.log('### audit fold');
+const subject = sh('git', ['log', '-1', '--format=%s']).stdout.trim();
+const id = /^docs\(audits\): close campaign (A\d+)$/.exec(subject)?.[1] ?? stop(`HEAD is '${subject}', not a campaign's close commit`);
+const folder = folders().find((d) => idOf(d) === id && /\*\*FROZEN\*\*/.test(read(join(d, '00-index.md'))))
+  ?? stop(`no frozen folder of ${id} under docs/audit/`);
+const sha = sh('git', ['rev-parse', '--short', 'HEAD']).stdout.trim();
+const index = readFileSync(join(folder, '00-index.md'), 'utf8');
+const name = folder.split('/').pop(), path = `${folder}/00-index.md`;
+
+// The link: the index at the close commit on the forge, or the sha and the path git shows it at.
+const tracker = field('tracker.kind') ?? 'none';
+const forge = parseOrigin(sh('git', ['remote', 'get-url', 'origin']).stdout.trim());
+const cell = forge && tracker !== 'none'
+  ? `[\`${name}\`](https://${forge.host}/${forge.project}/${tracker === 'glab' ? '-/' : ''}blob/${sha}/${path})`
+  : `\`${name}\` at \`${sha}\`:\`${path}\``;
+
+const kept = findings(folder).filter((f) => !/^(false|merged)/.test(f.disposition ?? ''));
+const by = (s) => kept.filter((f) => f.severity === s).length;
+const filed = kept.filter((f) => /^#\d+$/.test(f.disposition)).length, again = kept.filter((f) => /^re-reported/.test(f.disposition)).length;
+const date = /^A\d+-(\d{4}-\d{2}-\d{2})-/.exec(name)?.[1] ?? '?';
+const line = `| ${cell} | ${date} | ${row(index, 'Type') ?? '?'} | \`${/`([0-9a-f]+)`/.exec(row(index, 'Commit') ?? '')?.[1] ?? '?'}\` | `
+  + `${kept.length} — ${by('critical')} critical, ${by('high')} high, ${by('mid')} mid, ${by('low')} low | `
+  + `**frozen** ${new Date().toISOString().slice(0, 10)} — ${filed} filed, ${again} re-reported |`;
+
+const readme = 'docs/audit/README.md';
+let text = existsSync(readme) ? readFileSync(readme, 'utf8') : readFileSync(join(pkg, 'scripts/target/templates/audit/README.md'), 'utf8');
+const l = text.split('\n'), header = l.findIndex((x) => /^\| Campaign \|/.test(x));
+if (header < 0 || !/^\|[-| ]+\|$/.test(l[header + 1] ?? '')) stop(`${readme} holds no campaign table`);
+const rm = sh('git', ['rm', '-r', '-q', '--', folder]);
+if (rm.status !== 0) stop(`git rm ${folder}: ${rm.stderr.trim()}`);
+l.splice(header + 2, 0, line);
+writeFileSync(readme, l.join('\n'));
+say(`row: ${line}`);
+say(`commit: docs(audits): fold campaign ${id} — ${folder} ${readme}`);

package/scripts/audit/lib.mjs

@@ -0,0 +1,93 @@
+// What /audit's verbs share: the lens catalogue, the campaign folder and what its judges wrote in
+// it, the fingerprint. From the repository's root.
+import '../node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const pkg = fileURLToPath(new URL('../../', import.meta.url));
+export const LENSES = join(pkg, 'scripts/lenses');
+
+// The lens catalogue (K-31): the plugin's lenses are exactly its references; a `kind` adds its own;
+// the hygiene lenses take one agent together, their facts measured first; five ids are retired.
+export const lensIds = () => readdirSync(LENSES).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)).sort();
+export const KIND = { none: [], lib: ['PKG', 'TYPE', 'LINES', 'CONF'], app: ['COMPAT', 'A11Y', 'CONF'] };
+export const HYGIENE = ['BUILD', 'DEPS', 'PKG', 'TYPE', 'GOV', 'LINES', 'GUARD', 'CONF'];
+export const RETIRED = { CORR: 'BUG, FAIL', TEST: 'VERIF', PATT: 'STANDARDS', AI: 'DOC, VERIF', FILES: 'ARCH' };
+export const domainIds = () => (existsSync('docs/audit/lenses') ? readdirSync('docs/audit/lenses') : [])
+  .filter((f) => /^[A-Z][A-Z0-9]+\.md$/.test(f)).map((f) => f.slice(0, -3)).sort();
+// The reference a lens id reads: the plugin's, or the repository's own for a domain lens.
+export const reference = (id) => [join(LENSES, `${id}.md`), `docs/audit/lenses/${id}.md`].find((p) => existsSync(p)) ?? null;
+
+export const sh = (cmd, args, opts = {}) => spawnSync(cmd, args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, ...opts });
+export const lines = (text) => text.split('\n').filter(Boolean);
+export const read = (p) => { try { return readFileSync(p, 'utf8'); } catch { return ''; } };
+
+// The campaign folders beside the table, and the one under way: its index carries IN PROGRESS.
+export const folders = () => (existsSync('docs/audit') ? readdirSync('docs/audit') : [])
+  .filter((d) => /^A\d+-/.test(d) && statSync(join('docs/audit', d)).isDirectory()).map((d) => join('docs/audit', d));
+export const inProgress = () => folders().find((d) => /IN PROGRESS/.test(read(join(d, '00-index.md')))) ?? null;
+export const idOf = (folder) => folder.match(/\/(A\d+)-/)[1];
+// A row of the index's campaign table, `| **<label>** | <value> |`.
+export const row = (index, label) => new RegExp(`^\\| \\*\\*${label}\\*\\* \\| (.*?) \\|$`, 'm').exec(index)?.[1] ?? null;
+
+export const parts = (folder) => readdirSync(folder).filter((d) => /^\d{2,}$/.test(d)).sort((a, b) => a - b);
+
+// The findings its judges wrote, `NN/<LENS>-<NN>.<n>.md`, as the fields /audit reads from them.
+export function findings(folder, lenses) {
+  const out = [];
+  for (const nn of parts(folder)) for (const f of readdirSync(join(folder, nn)).sort(byNumber)) {
+    const m = /^([A-Z][A-Z0-9]+)-(\d{2,})\.(\d+)\.md$/.exec(f);
+    if (!m || (lenses && !lenses.includes(m[1]))) continue;
+    const path = join(folder, nn, f), text = read(path);
+    out.push({
+      path, text, part: nn, lens: m[1], id: `${idOf(folder)}-${m[1]}-${m[2]}.${m[3]}`,
+      title: /^#### \S+ — (.*)$/m.exec(text)?.[1]?.trim() ?? '',
+      severity: /\*\*Severity:\*\* (critical|high|mid|low)/.exec(text)?.[1] ?? '?',
+      unverified: /\*\*UNVERIFIED\*\*/.test(text),
+      effort: /\*\*Effort:\*\* ([SML])\b/.exec(text)?.[1] ?? '?',
+      known: /^\*\*Known:\*\* #(\d+)/m.exec(text)?.[1] ?? null,
+      from: lines(/^\*\*From:\*\* (.*)$/m.exec(text)?.[1]?.replace(/,/g, '\n') ?? '').map((s) => s.trim()),
+      disposition: /^\*\*Disposition:\*\* (.*)$/m.exec(text)?.[1] ?? null,
+    });
+  }
+  return out;
+}
+function byNumber(a, b) {
+  const n = (f) => Number(/\.(\d+)\.md$/.exec(f)?.[1] ?? 0);
+  return a.split('-')[0].localeCompare(b.split('-')[0]) || n(a) - n(b);
+}
+
+// A part's `part.md`: its `**Received:**` ids, and per lens `## <LENS>` the lines under it.
+export function partFile(folder, nn) {
+  const text = read(join(folder, nn, 'part.md'));
+  const received = lines(/^\*\*Received:\*\* (.*)$/m.exec(text)?.[1]?.replace(/,/g, '\n') ?? '').map((s) => s.trim()).filter((s) => s !== 'none');
+  const sections = {};
+  let lens = null;
+  for (const l of text.split('\n')) {
+    const h = /^## ([A-Z][A-Z0-9]+(?:, ?[A-Z][A-Z0-9]+)*)\s*$/.exec(l);
+    if (h) { lens = h[1].split(/, ?/); for (const id of lens) sections[id] ??= []; continue; }
+    if (lens) for (const id of lens) sections[id].push(l);
+  }
+  return { text, received, sections };
+}
+
+// The ids a judge received that no other line of its part names as a whole id (#825).
+export function unaccounted(folder, nn) {
+  const { text, received } = partFile(folder, nn);
+  const others = [text.split('\n').filter((l) => !l.startsWith('**Received:**')).join('\n'),
+    ...findings(folder).filter((f) => f.part === nn).map((f) => f.text)].join('\n');
+  const named = new Set(others.match(/(?<![A-Za-z0-9-])[A-Z][A-Z0-9]+-[0-9]+(?![A-Za-z0-9.])/g) ?? []);
+  return received.filter((id) => !named.has(id));
+}
+
+// Every tracked and untracked file outside docs/audit/, with its hash: what an audit must leave as
+// it found it (R-227). `path\thash` lines.
+export function fingerprint() {
+  const files = sh('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard']).stdout.split('\0')
+    .filter((f) => f && !f.startsWith('docs/audit/') && existsSync(f) && statSync(f).isFile());
+  const unique = [...new Set(files)].sort();
+  const hashes = lines(sh('git', ['hash-object', '--stdin-paths'], { input: unique.join('\n') }).stdout);
+  return unique.map((f, i) => `${f}\t${hashes[i]}`);
+}