acuvo-code 0.2.0

package/scripts/cache-floor.mjs

@@ -0,0 +1,176 @@
+/**
+ * ── ⭐⭐ MEASURE THE CACHE FLOOR. IT COSTS $0.00 AND IT IS THE MARGIN. ───────
+ *
+ *     node scripts/cache-floor.mjs [repoA] [repoB] ...
+ *
+ * `PRICING.md` §5 states `cache floor = sharedHead ÷ typicalPrompt` and closes
+ * with the open item *"measure the achieved cache floor"*. This is that
+ * measurement, and it runs offline: the model is SCRIPTED, so what is being read
+ * is the bytes WE send — the half of the cache contract we control, and the only
+ * half that can be checked on every commit without a key or a bill.
+ *
+ * It prints two things a live `acuvo --json` reading cannot tell apart on its
+ * own:
+ *
+ *   1. **the floor across tenants** — how much of a brand-new user's very first
+ *      request the provider has already seen, because some other tenant sent the
+ *      same head. This is the number the ladder is sized on.
+ *   2. **the floor across configurations** — what one machine's `--no-run`, TTY
+ *      or `MODAL_*` setting does to that head. Two tenants whose configs differ
+ *      are two cache pools, however perfect the prefix is inside each.
+ *
+ * ⚠️ IT DOES NOT MEASURE WHAT THE PROVIDER DID. A perfect prefix still misses if
+ * the request lands on a cold upstream — `lib/model.mjs` measured 46.7% unpinned
+ * against 95.8% pinned on the same bytes. That reading comes from
+ * `acuvo --json`'s `.cache` block against a real key. ⭐ The point of this
+ * script is that it makes that reading INTERPRETABLE: a live 0% beside a
+ * measured 99.9% prefix is a routing finding, and a live 0% beside a measured
+ * 4% prefix is ours.
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, basename } from 'node:path';
+
+import { runSession } from '../lib/turn.mjs';
+import { createLocalExecutor } from '../lib/workspace.mjs';
+import { toolNamesForRounds, toolSchemasFor } from '../lib/tools.mjs';
+import { orderForCachePrefix } from '../lib/tool-prefix.mjs';
+import { sharedPrefixBytes, describeDivergence, wireBytes } from '../lib/cache-floor.mjs';
+
+const ROUNDS = 8;
+const made = [];
+
+/** A throwaway repository, so the script has something to measure with no arguments. */
+function scratchRepo(name, files) {
+  const root = mkdtempSync(join(tmpdir(), `acuvo-floor-${name}-`));
+  made.push(root);
+  writeFileSync(join(root, 'package.json'), `{"name":"${name}","version":"1.0.0"}\n`);
+  mkdirSync(join(root, 'src'), { recursive: true });
+  for (let i = 0; i < files; i += 1) {
+    writeFileSync(join(root, 'src', `mod${i}.js`), `export function fn${i}(x) {\n  return x + ${i};\n}\n`);
+  }
+  return root;
+}
+
+/**
+ * Round 1 of a FRESH invocation, which is the round the floor is a claim about.
+ * ⚠️ Rounds 2+ are a different measurement — they append tool results the
+ * provider has by definition never seen, so their miss is arithmetic.
+ */
+async function firstRequest(root, task) {
+  let captured = null;
+  const callModelImpl = async (opts) => {
+    if (!captured) captured = { tools: opts.tools ?? null, messages: opts.messages };
+    return {
+      ok: true, content: 'done', toolCalls: [],
+      usage: { cost: 0, total_tokens: 0 }, finishReason: 'stop', model: 'scripted/none',
+    };
+  };
+  await runSession({
+    task,
+    executor: createLocalExecutor(root),
+    config: { apiKey: 'scripted', model: 'scripted/none' },
+    maxRounds: ROUNDS,
+    allowRun: false,
+    callModelImpl,
+    onEvent: () => {},
+  });
+  return captured;
+}
+
+const kb = (n) => `${(n / 1024).toFixed(1)}k`;
+const pct = (n) => (n === null ? '  —  ' : `${(n * 100).toFixed(1)}%`);
+
+const args = process.argv.slice(2).filter((p) => existsSync(p));
+const roots = args.length >= 2
+  ? args.map((p) => [p, `describe what ${basename(p)} does`])
+  : [
+    [scratchRepo('alpha', 30), 'add a test for src/mod3.js'],
+    [scratchRepo('beta', 60), 'rename fn7 to seven and update the callers'],
+    [scratchRepo('gamma', 12), 'write a README'],
+  ];
+
+console.log('── 1. THE FLOOR ACROSS TENANTS ─────────────────────────────────────');
+console.log('   round 1 of a fresh invocation, one scripted round, $0.00\n');
+
+const caps = [];
+for (const [root, task] of roots) {
+  const cap = await firstRequest(root, task);
+  if (!cap) { console.log(`   ${root}: no request was made`); continue; }
+  const bytes = wireBytes(cap);
+  caps.push({ root, bytes, cap });
+  console.log(
+    `   ${basename(root).padEnd(28)} prompt ${kb(bytes.length).padStart(7)}`
+    + `  tools ${kb(JSON.stringify(cap.tools).length).padStart(7)} (${cap.tools.length})`
+    + `  system ${kb(String(cap.messages[0]?.content ?? '').length).padStart(7)}`,
+  );
+}
+
+console.log('\n   pair                                 shared head      floor');
+let worst = null;
+for (let i = 0; i < caps.length; i += 1) {
+  for (let j = i + 1; j < caps.length; j += 1) {
+    const d = describeDivergence(caps[i].bytes, caps[j].bytes);
+    const label = `${basename(caps[i].root)} vs ${basename(caps[j].root)}`;
+    console.log(`   ${label.padEnd(52)} ${kb(d.sharedPrefix).padStart(8)}      ${pct(d.floor)}`);
+    if (worst === null || d.floor < worst.floor) worst = { ...d, label };
+  }
+}
+if (worst) {
+  console.log(`\n   ⚠️ the head ends at byte ${worst.at} (${worst.label}), where the two requests read:`);
+  console.log(`      A …${JSON.stringify(worst.aroundA.slice(100, 200))}`);
+  console.log(`      B …${JSON.stringify(worst.aroundB.slice(100, 200))}`);
+  /**
+   * ⚠️ THE TWO NUMBERS ARE PRINTED WHETHER OR NOT THEY DISAGREE, and the reading
+   * says which case this is. Printing them only when they diverge would teach a
+   * reader that "shared" and "cacheable" are normally the same word, which is
+   * the exact confusion that turns a 98.9%-shared / 0%-cached probe into a
+   * hunt for a prefix bug that is not there.
+   */
+  const drift = (worst.sharedFraction ?? 0) - (worst.floor ?? 0);
+  console.log(`\n   shared bytes ${pct(worst.sharedFraction)} · cacheable prefix ${pct(worst.floor)} — `
+    + (drift > 0.02
+      ? '⚠️ SHARED BYTES ARE NOT A SHARED PREFIX. What they have in common is behind the divergence, so none of it bills as cache.'
+      : 'healthy: what they share is at the front, so the cache can reach all of it.'));
+}
+
+if (args.length < 2) {
+  console.log('\n   ⚠️ THESE ARE SCRATCH REPOSITORIES AND THEY FLATTER THE FLOOR. A repo map is');
+  console.log('      the per-tenant half of the prompt, and a 30-file scratch repo has almost none');
+  console.log('      of one. Measured on three REAL repositories in this tree the same day, the head');
+  console.log('      was 22.9k against a 41.9k prompt — a 54.6% floor. Pass real paths:');
+  console.log('        node scripts/cache-floor.mjs ../acuvo-code ../acuvo-gateway ../slopscore');
+}
+
+console.log('\n── 2. THE FLOOR ACROSS CONFIGURATIONS ──────────────────────────────');
+console.log('   one machine\'s settings against another\'s, tools block only\n');
+
+const probeRoot = caps[0]?.root ?? roots[0][0];
+const variants = [
+  ['reference (bare machine)', { allowRun: true, env: {}, root: probeRoot }],
+  ['--no-run', { allowRun: false, env: {}, root: probeRoot }],
+  ['ACUVO_ALLOW_PUSH=1', { allowRun: true, env: { ACUVO_ALLOW_PUSH: '1' }, root: probeRoot }],
+  ['MODAL_TTS_URL set', { allowRun: true, env: { MODAL_TTS_URL: 'https://x' }, root: probeRoot }],
+  ['stdin is a TTY (ask_user)', { allowRun: true, env: {}, root: probeRoot, interactive: true }],
+  ['running as a subagent', { allowRun: true, env: {}, root: probeRoot, subagent: true }],
+];
+
+const block = (opts, ordered) => {
+  const picked = toolSchemasFor(toolNamesForRounds(ROUNDS, opts));
+  return JSON.stringify(ordered ? orderForCachePrefix(picked, { maxRounds: ROUNDS }) : picked);
+};
+const refOpts = variants[0][1];
+
+console.log('   difference from the reference        registry order      cache order');
+for (const [label, opts] of variants) {
+  const before = sharedPrefixBytes(block(refOpts, false), block(opts, false));
+  const after = sharedPrefixBytes(block(refOpts, true), block(opts, true));
+  const gain = before > 0 ? ` (${(after / before).toFixed(1)}x)` : '';
+  console.log(`   ${label.padEnd(34)} ${String(before).padStart(9)} B      ${String(after).padStart(9)} B${gain}`);
+}
+
+console.log('\n   ⭐ the cache order is a PERMUTATION — every tool above is still offered.');
+console.log('   ⚠️ what a provider then did with these bytes is `acuvo --json` .cache, not this.\n');
+
+for (const d of made) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }

package/scripts/machine.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * ── ⚠️⚠️ THIS EXISTS BECAUSE A BENCHMARK RUN MADE THE OWNER'S LAPTOP UNUSABLE ─
+ *
+ * 2026-08-12, verbatim: *"we have to figure out a way to stop hammering my
+ * laptop dude, it's fucked. I cannot even watch Netflix, I can't even change
+ * tabs."* A Terminal-Bench run had twenty Docker containers on an 8-core machine
+ * with no `.wslconfig`, so WSL2 — which is what Docker Desktop runs on — helped
+ * itself to every logical processor and most of the RAM.
+ *
+ * ⭐ AND THE INSTRUCTION WAS NOT "DO LESS WORK." It was *"that doesn't mean
+ * workload goes lower, we need to be able to control my laptop."* So this is
+ * about a CEILING and a KILL SWITCH, never about scaling ambition down. Heavy
+ * work runs flat out inside a box it cannot climb out of.
+ *
+ * ── THE THREE CONTROLS, IN ORDER OF HOW MUCH THEY MATTER ────────────────────
+ *
+ *   1. `~/.wslconfig` — the real one. Caps the VM at 4 of 8 processors and 6GB.
+ *      Without it there is no limit at all, which is the state this machine was
+ *      in. ⚠️ Needs `wsl --shutdown` to take effect; editing it does nothing to
+ *      a VM already running.
+ *   2. Priority — our long jobs run BELOW NORMAL, so the desktop always wins a
+ *      contested core. A build that takes 10% longer and never stutters the UI
+ *      is the correct trade on somebody's personal machine.
+ *   3. This script — `status` to see what we are costing, `stop` to end all of
+ *      it in one command, without hunting pids.
+ *
+ * Zero dependencies, like everything else here.
+ *
+ *   node scripts/machine.mjs status
+ *   node scripts/machine.mjs stop
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const WSLCONFIG = join(homedir(), '.wslconfig');
+
+/** Processes that are OURS and heavy. Never the user's editor or browser. */
+const OURS = /harbor|acuvo|terminal-bench/i;
+
+function sh(file, args, { quiet = false } = {}) {
+  try {
+    return execFileSync(file, args, {
+      encoding: 'utf8', timeout: 20_000, windowsHide: true,
+      stdio: quiet ? ['ignore', 'pipe', 'ignore'] : ['ignore', 'pipe', 'inherit'],
+    });
+  } catch (e) {
+    return e?.stdout ?? '';
+  }
+}
+
+function dockerContainers() {
+  const out = sh('docker', ['ps', '--format', '{{.ID}}\t{{.Names}}\t{{.Image}}'], { quiet: true });
+  return out.split('\n').map((l) => l.trim()).filter(Boolean).map((l) => {
+    const [id, name, image] = l.split('\t');
+    return { id, name, image };
+  });
+}
+
+/**
+ * ⚠️ `docker stats` WITHOUT `--no-stream`, ON WINDOWS, NEVER RETURNS. It streams
+ * until interrupted, and a script that hangs while you are trying to reclaim
+ * your machine is the opposite of this file's job.
+ */
+function dockerLoad() {
+  const out = sh('docker', ['stats', '--no-stream', '--format', '{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}']);
+  return out.split('\n').map((l) => l.trim()).filter(Boolean);
+}
+
+function wslCap() {
+  if (!existsSync(WSLCONFIG)) {
+    return {
+      ok: false,
+      detail: 'NO ~/.wslconfig — WSL2 (and therefore Docker) may take EVERY core and most of your RAM. '
+        + 'This is the state that made the machine unusable.',
+    };
+  }
+  const text = readFileSync(WSLCONFIG, 'utf8');
+  const procs = /processors\s*=\s*(\d+)/i.exec(text)?.[1] ?? null;
+  const mem = /memory\s*=\s*(\S+)/i.exec(text)?.[1] ?? null;
+  return {
+    ok: procs !== null && mem !== null,
+    procs,
+    mem,
+    detail: procs && mem
+      ? `capped at ${procs} processors and ${mem}`
+      : 'present but does not set BOTH processors and memory — the unset one is uncapped',
+  };
+}
+
+function heavyProcesses() {
+  // ⚠️ Windows only, and it fails quietly elsewhere rather than pretending.
+  if (process.platform !== 'win32') return [];
+  /**
+   * ⚠️⚠️ IT MATCHED ITSELF. The query's OWN command line contains the words it
+   * searches for, so every `status` reported one phantom powershell.exe and told
+   * the owner something of ours was still running when the machine was idle. A
+   * monitor that cannot report "all clear" is worse than no monitor — this one
+   * exists precisely to be believed.
+   *
+   * Excluded by pid (our own child) and by the give-away that only the detector
+   * mentions BOTH patterns in one command line.
+   */
+  const ps = sh('powershell', ['-NoProfile', '-Command',
+    "Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'harbor|terminal-bench' } "
+    + '| Select-Object ProcessId,Name,CommandLine | ConvertTo-Json -Compress'], { quiet: true });
+  try {
+    const parsed = JSON.parse(ps || '[]');
+    const list = Array.isArray(parsed) ? parsed : [parsed];
+    return list.filter((p) => {
+      if (!p || p.ProcessId === process.pid) return false;
+      const cl = String(p.CommandLine ?? '');
+      // The detector is the only thing that names both patterns at once.
+      return !(cl.includes('harbor|terminal-bench'));
+    });
+  } catch { return []; }
+}
+
+function status() {
+  const cap = wslCap();
+  console.log('');
+  console.log(`  WSL / Docker ceiling   ${cap.ok ? '✔' : '✖'}  ${cap.detail}`);
+  if (!cap.ok) {
+    console.log('                         → write ~/.wslconfig with processors= and memory=, then `wsl --shutdown`');
+  }
+
+  const containers = dockerContainers();
+  console.log(`  containers running     ${containers.length === 0 ? '✔  none' : `⚠  ${containers.length}`}`);
+  for (const c of containers) console.log(`                           ${c.name}  (${c.image})`);
+
+  if (containers.length > 0) {
+    for (const line of dockerLoad()) console.log(`                           ${line}`);
+  }
+
+  const procs = heavyProcesses();
+  console.log(`  our heavy processes    ${procs.length === 0 ? '✔  none' : `⚠  ${procs.length}`}`);
+  for (const p of procs) console.log(`                           pid ${p.ProcessId}  ${p.Name}`);
+
+  const quiet = containers.length === 0 && procs.length === 0;
+  console.log('');
+  console.log(quiet
+    ? '  Nothing of ours is running. The machine is yours.'
+    : '  Run `node scripts/machine.mjs stop` to end all of it.');
+  console.log('');
+  return quiet ? 0 : 1;
+}
+
+function stop() {
+  /**
+   * ⚠️ CONTAINERS FIRST, THEN THE ORCHESTRATOR. Killing harbor first leaves its
+   * containers running with nothing supervising them — orphans, which is the
+   * exact failure `background.mjs` was written to avoid, at a larger size.
+   */
+  const containers = dockerContainers();
+  if (containers.length > 0) {
+    console.log(`  killing ${containers.length} container${containers.length === 1 ? '' : 's'}…`);
+    spawnSync('docker', ['kill', ...containers.map((c) => c.id)], { stdio: 'ignore', timeout: 60_000, windowsHide: true });
+  }
+
+  const procs = heavyProcesses();
+  for (const p of procs) {
+    console.log(`  killing pid ${p.ProcessId} (${p.Name})…`);
+    spawnSync('taskkill', ['/T', '/F', '/PID', String(p.ProcessId)], { stdio: 'ignore', timeout: 30_000, windowsHide: true });
+  }
+
+  /**
+   * ⭐ AND THE VM ITSELF, because a shut-down WSL2 releases its RAM immediately
+   * instead of holding it until the next reboot. This is the line that actually
+   * gives the memory back.
+   */
+  console.log('  shutting down the WSL VM to release its memory…');
+  spawnSync('wsl', ['--shutdown'], { stdio: 'ignore', timeout: 60_000, windowsHide: true });
+
+  console.log('');
+  console.log('  Done. The machine is yours.');
+  return 0;
+}
+
+/**
+ * ── ⭐ RUN SOMETHING HEAVY WITHOUT IT OWNING THE MACHINE ────────────────────
+ *
+ * `machine.mjs run -- <command…>` starts a command at BELOW NORMAL priority, so
+ * the desktop wins every contested core. A benchmark that takes 10% longer and
+ * never stutters a video is the correct trade on somebody's personal laptop —
+ * and it is the difference between "workload goes lower" (which was explicitly
+ * NOT the instruction) and "workload stays out of your way".
+ *
+ * ⚠️ PRIORITY IS NOT A SUBSTITUTE FOR THE `.wslconfig` CAP. Docker's work does
+ * not happen in the child we launch; it happens inside the WSL VM, which this
+ * cannot reach. Both controls are needed and they cover different things:
+ * priority governs OUR processes, the cap governs the VM.
+ */
+function runLow(argv) {
+  if (argv.length === 0) {
+    console.error('usage: node scripts/machine.mjs run -- <command> [args…]');
+    return 64;
+  }
+  const cap = wslCap();
+  if (!cap.ok) {
+    // ⚠️ Refuse rather than warn. This is the exact configuration that made the
+    // machine unusable, and a warning at the top of a two-hour run is a warning
+    // nobody is present to read.
+    console.error(`  ✖ refusing to start heavy work: ${cap.detail}`);
+    console.error('    Write ~/.wslconfig with processors= and memory=, then `wsl --shutdown`.');
+    return 1;
+  }
+  console.log(`  starting at BELOW NORMAL priority (VM ${cap.detail})`);
+  const r = process.platform === 'win32'
+    ? spawnSync('cmd', ['/c', 'start', '/b', '/belownormal', '/wait', ...argv], { stdio: 'inherit', windowsHide: true })
+    : spawnSync('nice', ['-n', '15', ...argv], { stdio: 'inherit' });
+  return r.status ?? 0;
+}
+
+const cmd = process.argv[2] ?? 'status';
+if (cmd === 'stop' || cmd === 'panic' || cmd === 'kill') process.exit(stop());
+else if (cmd === 'status') process.exit(status());
+else if (cmd === 'run') {
+  const sep = process.argv.indexOf('--');
+  process.exit(runLow(sep === -1 ? process.argv.slice(3) : process.argv.slice(sep + 1)));
+} else {
+  console.error('usage: node scripts/machine.mjs [status|stop|run -- <cmd>]');
+  process.exit(64);
+}

package/scripts/test.mjs

@@ -0,0 +1,139 @@
+/**
+ * ── ⚠️⚠️ ZERO TESTS EXITED 0, AND THAT IS THE WORST POSSIBLE GREEN ──────────
+ *
+ * `SHAKEDOWN.md` §1.2, measured on an INSTALLED copy of this package:
+ *
+ *     npm test
+ *     # tests 0 / pass 0 / fail 0 — exit 0
+ *
+ * The old script was `node --test --test-timeout=180000 test/*.test.mjs`, and
+ * the glob is expanded by the SHELL. On a machine whose shell does not expand it
+ * (cmd.exe), or in an install where the pattern matches nothing, node is handed
+ * a literal `test/*.test.mjs`, finds no such file, runs **nothing**, and reports
+ * success. ⭐ Someone auditing this package — which `ENTERPRISE.md` explicitly
+ * invites, and which is the entire reason `test/` is in the published files
+ * allowlist — would run `npm test`, see green, and conclude the suite passed.
+ *
+ * ⭐ THIS IS THE SAME DEFECT CLASS AS "watch the total, not the failures": a
+ * test file that fails to COMPILE also contributes zero tests, and the run still
+ * says passed. Counting failures can never catch either one. **Only the total
+ * can**, so the total is what this asserts.
+ *
+ * ⚠️ AND IT DOES NOT GLOB. Node's own directory discovery is used, so the
+ * behaviour no longer depends on which shell invoked npm.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { cpus } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const testDir = join(root, 'test');
+
+/**
+ * ⚠️ A MISSING `test/` IS A FAILURE, NOT A SKIP. An install that dropped the
+ * directory is exactly the case this script exists to catch, and "there was
+ * nothing to run" must never be reported as "everything passed".
+ */
+if (!existsSync(testDir)) {
+  console.error(`✖ ${testDir} does not exist — this copy of acuvo-code ships no tests, so nothing was verified.`);
+  process.exit(1);
+}
+
+/**
+ * ⚠️ A FLOOR, NOT AN EXACT COUNT. Pinning the precise number would fail every
+ * commit that adds a test — a check that fails correct work, which this repo has
+ * paid for repeatedly. The floor only ever catches the collapse this exists for:
+ * hundreds of tests becoming a handful because a glob broke or a file stopped
+ * compiling. Raise it deliberately, never automatically.
+ */
+const MINIMUM_TESTS = 500;
+
+/**
+ * ⚠️⚠️ THE FILES ARE ENUMERATED HERE, NOT GLOBBED AND NOT DISCOVERED.
+ *
+ * · A shell glob (`test/*.test.mjs`) is what broke: cmd.exe does not expand it,
+ *   so node received the literal string, matched nothing, and exited 0.
+ * · Passing the DIRECTORY does not work either — measured on Node 22.17:
+ *   `node --test test/` resolves `test/` as a MODULE and dies with
+ *   `Cannot find module …\test`, which the runner then reports as one failing
+ *   test. Directory discovery is not what that argument means.
+ *
+ * ⭐ `readdirSync` depends on neither the shell nor a node version's glob
+ * support, and the list it produces can be counted before anything runs.
+ */
+const files = readdirSync(testDir)
+  .filter((n) => n.endsWith('.test.mjs'))
+  .map((n) => `test/${n}`)
+  .sort();
+
+if (files.length === 0) {
+  console.error(`✖ ${testDir} contains no *.test.mjs files — nothing was verified.`);
+  process.exit(1);
+}
+
+/**
+ * ── ⚠️⚠️ A CONCURRENCY CEILING, BECAUSE THIS RUNS ON SOMEBODY'S LAPTOP ──────
+ *
+ * `node --test` defaults to one worker PER CORE. With 189 test files that is
+ * eight processes on this machine — fine alone, and not fine at all in the
+ * configuration this repo actually runs in: **two terminals plus three
+ * background agents**, each firing the same suite. 8 cores, up to 24 workers.
+ *
+ * Measured consequence, 2026-08-16, from the person paying for the laptop:
+ * *"we are absolutely fucking the shit out of my laptop so hard I can't even
+ * open my Google tabs."* ⭐ THE INSTRUCTION WAS EXPLICITLY NOT "DO LESS WORK" —
+ * it was that the machine has to stay usable while the work happens. So this
+ * is a ceiling, not a reduction: the same tests run, they just cannot take
+ * every core at once.
+ *
+ * ⚠️ HALF THE CORES, MINUS ONE, FLOOR OF 2. Half leaves room for a second
+ * agent; the minus-one leaves a core for the interactive session, which is the
+ * thing a human actually notices. A floor of 2 stops a small machine
+ * serialising a 189-file suite into something nobody will wait for.
+ *
+ * ⭐ Override with `ACUVO_TEST_CONCURRENCY` when the machine is idle and you
+ * want the suite back at full speed — the ceiling exists for the shared case,
+ * not because more is wrong.
+ */
+const cores = Math.max(1, cpus().length);
+const concurrency = (() => {
+  const asked = Number(process.env.ACUVO_TEST_CONCURRENCY);
+  if (Number.isInteger(asked) && asked > 0) return asked;
+  return Math.max(2, Math.floor(cores / 2) - 1);
+})();
+
+// ⚠️ TAP, not spec: the machine-readable `# tests N` line is the thing being
+// asserted below, and the spec reporter writes a decorated `ℹ tests N` instead.
+const args = ['--test', `--test-concurrency=${concurrency}`, '--test-timeout=180000', '--test-reporter=tap', ...files];
+const run = spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+const out = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+process.stdout.write(out);
+
+/**
+ * ⚠️ READ FROM THE REPORTER'S OWN TOTAL, never recomputed by counting lines.
+ * `# tests N` is what node itself concluded; a line count is our opinion about
+ * its output, and the two drift the moment the reporter changes.
+ */
+const total = Number(/^# tests (\d+)$/m.exec(out)?.[1] ?? NaN);
+const failed = Number(/^# fail (\d+)$/m.exec(out)?.[1] ?? NaN);
+
+if (!Number.isFinite(total)) {
+  console.error('\n✖ could not read a test total out of the runner output — treating that as a failure, '
+    + 'because an unreadable result is not a passing one.');
+  process.exit(1);
+}
+
+if (total < MINIMUM_TESTS) {
+  console.error(`\n✖ only ${total} tests ran, and this package expects at least ${MINIMUM_TESTS}.`);
+  console.error('  Nothing here failed — that is the point. A suite that collects no tests reports success,');
+  console.error('  so the TOTAL is the check. Usually this means the test directory did not ship, or a test');
+  console.error('  file failed to compile and silently contributed zero tests.');
+  process.exit(1);
+}
+
+if (Number.isFinite(failed) && failed > 0) process.exit(1);
+process.exit(run.status === null ? 1 : run.status);

package/skills/accessibility.md

@@ -0,0 +1,87 @@
+---
+name: accessibility
+description: Semantic HTML, keyboard paths, focus and contrast — the parts that break real usage
+when: When building any interactive UI, a modal, a menu, or anything you can click
+---
+
+# Accessibility
+
+Beyond the basics in `web-app-quality`. These are the failures that make an
+interface genuinely unusable rather than merely imperfect.
+
+## ⚠️⚠️ The right element does most of the work for free
+
+```html
+✗ <div class="btn" onclick="save()">Save</div>
+✓ <button type="button" onclick="save()">Save</button>
+```
+
+The `<div>` cannot be focused, cannot be triggered by Enter or Space, is not
+announced as a button, and does not participate in forms. The `<button>` does
+all four with no code. Recreating that with `tabindex`, `role` and key handlers
+is a lot of work to arrive back where you started — and it is usually incomplete.
+
+Same for `<a>` for navigation, `<label>` for inputs, `<nav>`/`<main>`/`<h1>`
+for structure. **Reach for ARIA only when no element exists for the job.** Bad
+ARIA is worse than none, because it overrides what the browser knew.
+
+## Every path must work from the keyboard
+
+Tab through the whole thing without touching the mouse. If you cannot reach a
+control, open a menu, or close a dialog, it is broken — for keyboard users, for
+screen readers, and for anyone whose trackpad died.
+
+- `Escape` closes overlays
+- `Enter`/`Space` activate
+- Arrow keys move within a composite widget (menu, tabs), not between pages
+
+⚠️ **Tab order follows the DOM, not the CSS.** Reordering visually with grid or
+flex leaves the tab order where the markup put it. Never use positive
+`tabindex` values to patch that — fix the markup order.
+
+## Focus is not decoration
+
+```css
+✗ *:focus { outline: none; }        /* the keyboard user is now lost */
+✓ :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+```
+
+`:focus-visible` shows the ring for keyboard users and not for mouse clicks, so
+there is no reason left to remove it.
+
+⭐ **Move focus deliberately.** Open a dialog → focus inside it and trap it
+there. Close it → return focus to the control that opened it. Delete a row →
+move focus somewhere sensible, not to `<body>`.
+
+## Contrast, and never colour alone
+
+- Body text at **4.5:1**, large text at **3:1**. Grey-on-grey placeholder text
+  is the usual offender.
+- About 1 in 12 men cannot separate red from green — so an error state needs an
+  icon or words, not just a red border. Same for chart series (`data-and-charts`).
+
+## Images and icons
+
+`alt` describes the *purpose*: `alt="Search"` on a magnifier, not
+`alt="magnifying glass icon"`. Decorative images take `alt=""` so screen readers
+skip them — omitting `alt` entirely makes them read the filename instead.
+
+## ⚠️ Tell people when something changed
+
+A screen reader does not notice a div appearing. Announce it:
+
+```html
+<div role="status" aria-live="polite">Invoice saved</div>
+```
+
+Use `assertive` only for genuine interruptions — an error that stops the task.
+
+## Respect the settings people already chose
+
+```css
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after {
+  animation-duration: .01ms !important; transition-duration: .01ms !important; } }
+```
+
+Also honour `prefers-color-scheme`. These are the user telling you what they
+need; overriding them is a decision you do not have the information to make.