tewip-ai 0.33.0 → 0.35.0

package/README.md

@@ -1,6 +1,10 @@
 # Tewip
 
-**Tewip** (Uyghur *téwip*, تېۋىپ: healer, doctor) finds why each failing test failed: a real bug, a flaky test, the environment, test data, or a changed selector. Every answer comes with its confidence, its evidence and one next step, and names its source: a deterministic rule, the AI model, or a person's correction.
+**Tewip** (Uyghur *téwip*, تېۋىپ: healer, doctor) is the layer that **proves software work** - written by a person or by an agent.
+
+It finds why each failing test failed (a real bug, a flaky test, the environment, test data, or a changed selector), says whether a test could ever fail at all, breaks your code to find out whether the tests would notice, reads what a migration will do to a live database, and gives one verdict on whether a change is done. Every answer carries its evidence and names what decided it: a deterministic rule, the AI model, or a person's correction.
+
+What makes it worth installing is what it refuses to say. It answers *"cannot say"* rather than guessing, it will not narrow a test run it cannot prove safe to narrow, and every report ends with what it did **not** check. Each number below was measured on strangers' real code, never on fixtures.
 
 It works for every stack: Node.js (node:test, Jest, Vitest, Mocha), Python (pytest, unittest), Java and Kotlin (JUnit, TestNG), Go, .NET, Ruby, PHP and Rust, each checked against its real runner's report ([the full list](QUICKSTART.md#not-using-playwright-every-stack-works)), plus Playwright in depth with traces, selector drift and verified fixes. It also reads the failure wording of the browser and component-test tools on top of those runners (Selenium, WebdriverIO, Cypress, Testing Library for React, Vue and Angular, Vue Test Utils, jest-dom and Jasmine), checked against more than 500 real messages from public projects.
 
@@ -112,18 +116,20 @@ jobs:
 
 The report reads the history cache of the branch it runs on, usually the default branch.
 
-The repository needs "Allow GitHub Actions to create and approve pull requests" enabled for fix PRs. Pull requests opened by the workflow token don't trigger CI themselves; the agent verified each change by re-running the test before opening the PR. See [triage-agent-sandbox](https://github.com/hmamut39/triage-agent-sandbox) for a working example. If this repository is private, other repositories can only use the action when Settings → Actions → Access allows it.
+The repository needs "Allow GitHub Actions to create and approve pull requests" enabled for fix PRs. Pull requests opened by the workflow token don't trigger CI themselves; the agent verified each change by re-running the test before opening the PR. It was first proved end to end on a private practice repository, which is why there is no link to click here. If this repository is private, other repositories can only use the action when Settings → Actions → Access allows it.
 
 ### As a Claude Code plugin (no account, no marketplace approval)
 
 ```bash
-claude plugin marketplace add hmamut39/tewip
+claude plugin marketplace add hmamut39/tewip-plugin
 claude plugin install tewip@tewip
 ```
 
 That is the whole publication process. A marketplace is a `.claude-plugin/marketplace.json` file in a git
-repository, so Tewip ships one in its own repo - nobody has to approve it, and there is nothing to pay
-for. The plugin brings Tewip's MCP server and three skills that tell Claude Code *when* to use it:
+repository, so Tewip publishes one at
+[hmamut39/tewip-plugin](https://github.com/hmamut39/tewip-plugin) - nobody has to approve it, and there
+is nothing to pay for. That repository holds the plugin only: a manifest, three skills and a pointer to
+the npm package, which is why this one can stay private. The plugin brings Tewip's MCP server and three skills that tell Claude Code *when* to use it:
 before claiming a change is done, when a test fails, and when a change touches a migration. It costs
 about 410 tokens per session until a skill is actually needed.
 
@@ -568,6 +574,61 @@ With `--json` the verdict is **sealed**: editing `not-ready` to `ready` in the f
 fail, so a verdict that travels into a ticket or a release note can be checked rather than trusted. It is
 also an MCP tool, so an agent can ask whether its own work is done before saying that it is.
 
+## Can everybody use it? (Phase 28, new)
+
+```bash
+tewip access                           # every markup file in the project
+tewip access src/components/Nav.tsx    # or just one
+tewip access --strict                  # fails the build on a barrier that stops somebody outright
+```
+
+Accessibility is the one quality question that is also a legal one. The European Accessibility Act has
+been enforceable since June 2025, and it lands on the people who already own testing.
+
+The reason teams do not trust the tools they have is the reason they switch off every scanner: axe,
+Lighthouse and pa11y hand back several hundred undifferentiated violations, a large share of which are
+not barriers at all, and nobody has the afternoon it takes to sort them.
+
+Tewip makes **two kinds of statement and no third**:
+
+- **a barrier** — the element as written stops somebody, and reading it is enough to know that;
+- **a question** — something here is missing or unreadable, and only you can settle it.
+
+There is no "warning", because a warning is the category people learn to scroll past.
+
+```
+**6 barriers (5 that stop somebody outright), 18 for a person to settle.**
+
+### button-name - 3 places
+
+WCAG 2.2 4.1.2 Name, Role, Value (A), blocker.
+
+Who it stops: a screen reader announces "button" and nothing else, so it cannot be used or spoken to.
+
+- `components/VPNavBarAskAiButton.vue:2`  <button type="button" class="VPNavBarAskAiButton">
+  - it contains no text and carries no aria-label, so it is announced with its role and nothing else
+  - do this: put text inside it, or add aria-label="..." saying what it does
+```
+
+Every finding names its **WCAG 2.2 success criterion and level**, which is what turns it into something
+you can put in front of a regulator instead of a note saying "bad contrast".
+
+**What it refuses to decide is the reason it is worth running.** `alt={caption}` is not a missing alt.
+A button whose text comes from a child component cannot be called empty. `:aria-label="label"` is a
+label. `<slot />` is content this file cannot see. Each of those becomes a question, never an accusation
+— because a tool that accuses `<img alt={alt} />` of having no alt text gets switched off in a day.
+
+**And every report prints what it did not check** — contrast, focus order, meaningful sequence, whether
+the alt text is any good — because those need a rendered page. A clean result means these checks found
+nothing. It never means the product is accessible.
+
+No browser, no server, no network, no model, no cost. 416 real files in 1.65 seconds.
+
+Measured on four public projects, never on fixtures — excalidraw, bootstrap, vitepress and svelte:
+**50 barriers, 29 of them the kind that stop somebody outright, and 90 questions.** Seven false-positive
+classes were found and fixed along the way, every one of them a defect in Tewip rather than in the
+projects, and none of them reachable from a fixture. They are listed in [ROADMAP.md](ROADMAP.md).
+
 ## Teach it your house rules (Phase 27)
 
 ```bash
@@ -817,7 +878,7 @@ With `--act` it carries the decision out, and this is where the refusals matter
 
 | Project | How | Result |
 |---|---|---|
-| [triage-agent-sandbox](https://github.com/hmamut39/triage-agent-sandbox) (private practice repo) | Live GitHub Action on a release PR with 11 planted failures | Diagnosis comment, one environment issue, and a fix PR whose 5 locator changes pass when checked out. Traps left alone. Synthetic. |
+| A private practice repository (not linked: it is private) | Live GitHub Action on a release PR with 11 planted failures | Diagnosis comment, one environment issue, and a fix PR whose 5 locator changes pass when checked out. Traps left alone. Synthetic. |
 | WordPress Gutenberg (public) | Offline, from 5 windows of real CI blob reports, two of them harvested after the pipeline was frozen | 84–98% accuracy on 1,441 labelled real failures; the only project with enough drift cases to measure that category (see [eval/README.md](eval/README.md) for caveats) |
 | JupyterLab (public) | Offline, from its Galata UI suite | 90.2% on 41 labelled failures; the deterministic rules alone were right on 34 of 34 they decided |
 | LXD UI (public) | Offline, from its pull-request suite | 91.3% on 69 labelled failures; rules right on 63 of 63. All 6 misses are cross-branch flakes read as real bugs |

package/dist/cli/help.js

@@ -118,6 +118,16 @@ Usage:
                                     is what was asked for covered. Answers ready, not ready, or cannot
                                     say - and cannot say is never rounded up to ready. --json writes a
                                     sealed verdict that can be checked later. No model, no cost.
+  tewip access [<file or directory>] [--strict] [--out access.md]
+                                    Can everybody use this? Reads your markup and names the barriers
+                                    that reading alone can prove - a picture with no alt text, a field
+                                    with no label, a div only a mouse can use - each against its WCAG
+                                    2.2 criterion, which is what a regulator asks for. What only a
+                                    person can settle is kept apart from what is proved, and every
+                                    criterion it cannot reach without rendering the page (contrast,
+                                    focus order, whether the alt text is any good) is printed every
+                                    time. It never says a page is accessible, only what was checked.
+                                    No browser, no network, no model, no cost.
   tewip standards [--diff main...HEAD] [--strict] [--out standards.md]
                                     Teach Tewip your house rules. Markdown files in
                                     .tewip/standards/ - a forbid or require line is checked and

package/dist/cli/tewip.js

@@ -12,6 +12,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { flag } from './args.js';
 import { HELP } from './help.js';
+import { proveVerb } from './verbs-prove.js';
 import { workVerb } from './verbs-work.js';
 // cli/ in the source tree, dist/cli/ in the published package: package.json is one or two levels up.
 const ROOT = [join(import.meta.dirname, '..'), join(import.meta.dirname, '..', '..')].find((d) => existsSync(join(d, 'package.json'))) ?? join(import.meta.dirname, '..');
@@ -21,6 +22,9 @@ async function main() {
     // The verbs that reach into a tracker, a scan or a build live next door; the rest are here.
     if (await workVerb(verb, args))
         return;
+    // The verbs that prove a change live next door too.
+    if (await proveVerb(verb, args))
+        return;
     switch (verb) {
         case 'explain': {
             // The explain script reads its arguments from process.argv, as when it is run directly.
@@ -185,75 +189,6 @@ async function main() {
             runPursue({ root: process.cwd(), goal, act: args.includes('--act'), name: flag(args, 'name'), out: flag(args, 'out') });
             return;
         }
-        case 'done': {
-            const { runDone } = await import('../engine/verdict/verdict-command.js');
-            runDone({
-                root: process.cwd(),
-                diff: flag(args, 'diff') ?? 'main...HEAD',
-                prove: args.includes('--prove'),
-                proveBudgetSeconds: Number(flag(args, 'budget') ?? '300'),
-                out: flag(args, 'out'),
-                json: flag(args, 'json'),
-                name: flag(args, 'name'),
-                strict: args.includes('--strict'),
-            });
-            return;
-        }
-        case 'standards': {
-            const { runStandards } = await import('../engine/standards/standards-command.js');
-            runStandards({
-                root: process.cwd(),
-                diff: flag(args, 'diff'),
-                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out'),
-                out: flag(args, 'out'),
-                strict: args.includes('--strict'),
-            });
-            return;
-        }
-        case 'schema': {
-            const { runSchema } = await import('../engine/schema/schema-command.js');
-            runSchema({
-                root: process.cwd(),
-                diff: flag(args, 'diff') ?? 'main...HEAD',
-                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out'),
-                out: flag(args, 'out'),
-                strict: args.includes('--strict'),
-            });
-            return;
-        }
-        case 'pick': {
-            const { runPick } = await import('../engine/pick/pick-command.js');
-            runPick({
-                root: process.cwd(),
-                diff: flag(args, 'diff') ?? 'main...HEAD',
-                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out' && args[i - 1] !== '--recent' && args[i - 1] !== '--name'),
-                out: flag(args, 'out'),
-                list: args.includes('--list'),
-                recentRuns: Number(flag(args, 'recent') ?? '5'),
-                name: flag(args, 'name'),
-            });
-            return;
-        }
-        case 'prove': {
-            const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--diff', '--limit', '--budget'].includes(args[i - 1] ?? ''));
-            const { runProve } = await import('../engine/prove/prove-command.js');
-            runProve({
-                root: process.cwd(),
-                files: paths,
-                diff: flag(args, 'diff'),
-                limit: Number(flag(args, 'limit') ?? '6'),
-                budgetSeconds: Number(flag(args, 'budget') ?? '600'),
-                out: flag(args, 'out'),
-                strict: args.includes('--strict'),
-            });
-            return;
-        }
-        case 'vouch': {
-            const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--json'].includes(args[i - 1] ?? ''));
-            const { runVouch } = await import('../engine/vouch/run-vouch.js');
-            runVouch({ root: process.cwd(), paths: paths.length > 0 ? paths : ['.'], out: flag(args, 'out'), json: flag(args, 'json'), strict: args.includes('--strict') });
-            return;
-        }
         case 'trace': {
             const { runTrace } = await import('../engine/trace/trace-command.js');
             runTrace({ root: process.cwd(), only: flag(args, 'only'), name: flag(args, 'name'), out: flag(args, 'out') });

package/dist/cli/verbs-prove.js

@@ -0,0 +1,93 @@
+// The verbs that prove a change rather than describe it: the verdict, the project's own standards,
+// what a migration does to a live database, which tests could notice a change, whether the tests would
+// catch a bug, and whether a test could ever fail. Split out of cli/tewip.ts the same way the work
+// verbs were, to keep every file inside this project's own 300-line rule.
+import { flag } from './args.js';
+/** Runs `verb` if it is one of these, and says whether it did. */
+export async function proveVerb(verb, args) {
+    switch (verb) {
+        case 'done': {
+            const { runDone } = await import('../engine/verdict/verdict-command.js');
+            runDone({
+                root: process.cwd(),
+                diff: flag(args, 'diff') ?? 'main...HEAD',
+                prove: args.includes('--prove'),
+                proveBudgetSeconds: Number(flag(args, 'budget') ?? '300'),
+                out: flag(args, 'out'),
+                json: flag(args, 'json'),
+                name: flag(args, 'name'),
+                strict: args.includes('--strict'),
+            });
+            return true;
+        }
+        case 'access': {
+            const { runAccess } = await import('../engine/access/access-command.js');
+            const paths = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--out');
+            runAccess({
+                root: process.cwd(),
+                only: paths[0],
+                out: flag(args, 'out'),
+                gate: args.includes('--strict'),
+            });
+            return true;
+        }
+        case 'standards': {
+            const { runStandards } = await import('../engine/standards/standards-command.js');
+            runStandards({
+                root: process.cwd(),
+                diff: flag(args, 'diff'),
+                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out'),
+                out: flag(args, 'out'),
+                strict: args.includes('--strict'),
+            });
+            return true;
+        }
+        case 'schema': {
+            const { runSchema } = await import('../engine/schema/schema-command.js');
+            runSchema({
+                root: process.cwd(),
+                diff: flag(args, 'diff') ?? 'main...HEAD',
+                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out'),
+                out: flag(args, 'out'),
+                strict: args.includes('--strict'),
+            });
+            return true;
+        }
+        case 'pick': {
+            const { runPick } = await import('../engine/pick/pick-command.js');
+            runPick({
+                root: process.cwd(),
+                diff: flag(args, 'diff') ?? 'main...HEAD',
+                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out' && args[i - 1] !== '--recent' && args[i - 1] !== '--name'),
+                out: flag(args, 'out'),
+                list: args.includes('--list'),
+                recentRuns: Number(flag(args, 'recent') ?? '5'),
+                name: flag(args, 'name'),
+            });
+            return true;
+        }
+        case 'prove': {
+            const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--diff', '--limit', '--budget'].includes(args[i - 1] ?? ''));
+            const { runProve } = await import('../engine/prove/prove-command.js');
+            runProve({
+                root: process.cwd(),
+                files: paths,
+                diff: flag(args, 'diff'),
+                limit: Number(flag(args, 'limit') ?? '6'),
+                budgetSeconds: Number(flag(args, 'budget') ?? '600'),
+                out: flag(args, 'out'),
+                strict: args.includes('--strict'),
+            });
+            return true;
+        }
+        case 'vouch': {
+            const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--json'].includes(args[i - 1] ?? ''));
+            const { runVouch } = await import('../engine/vouch/run-vouch.js');
+            runVouch({ root: process.cwd(), paths: paths.length > 0 ? paths : ['.'], out: flag(args, 'out'), json: flag(args, 'json'), strict: args.includes('--strict') });
+            return true;
+        }
+        default:
+            return false;
+    }
+    return true;
+}

package/dist/engine/access/access-command.js

@@ -0,0 +1,164 @@
+// Phase 28: `tewip access` - the accessibility barriers that can be proved by reading the markup,
+// separated from the questions only a person can answer, with everything it did not check named.
+//
+// Why this exists when axe, Lighthouse and pa11y already do: those tools hand a team a few hundred
+// undifferentiated violations, a large share of which are not barriers at all, and the team turns
+// the check off. Tewip makes exactly two kinds of statement - "this stops somebody, here is the
+// element" and "only you can settle this one" - and prints the criteria it cannot reach. It needs
+// no browser, no server, no network and no model, so it runs on any repository in a second.
+//
+// It never says a page is accessible. It says what was checked.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { sourceFiles } from '../secure/secrets.js';
+import { JS_LIKE, MARKUP, tags } from './markup.js';
+import { checkFile } from './checks.js';
+import { blocks, criterionOf, NOT_CHECKED, RULES } from './wcag.js';
+const ORDER = { blocker: 0, serious: 1, moderate: 2, minor: 3 };
+/** One line per finding a person has already judged: "<rule> <file>:<line> - reason". */
+export function readAccepted(root) {
+    const file = join(root, '.tewip', 'access-accepted.txt');
+    if (!existsSync(file))
+        return new Set();
+    return new Set(readFileSync(file, 'utf8')
+        .split('\n')
+        .map((l) => l.split(' - ')[0].trim())
+        .filter((l) => l !== '' && !l.startsWith('#')));
+}
+export function keyOf(f) {
+    return `${f.rule} ${f.file}:${f.line}`;
+}
+export function worstFirst(a, b) {
+    const sa = ORDER[RULES[a.rule]?.severity ?? 'minor'];
+    const sb = ORDER[RULES[b.rule]?.severity ?? 'minor'];
+    if (sa !== sb)
+        return sa - sb;
+    if (a.file !== b.file)
+        return a.file < b.file ? -1 : 1;
+    return a.line - b.line;
+}
+/** Reads every markup file under `root` and returns what the markup alone can settle. */
+/**
+ * Markup written to exercise code, not to be used by a person. An `<img>` with no alt in a
+ * clipboard test is not a barrier to anybody, and excalidraw's test suite produced exactly that.
+ */
+const TEST_MARKUP = /(?:^|[\\/])(?:__tests__|__mocks__|tests?|spec|e2e|stories|fixtures?)[\\/]|\.(?:test|spec|stories|cy)\.[cm]?[jt]sx?$/i;
+export function findBarriers(root, only) {
+    const base = only ? resolve(root, only) : root;
+    const all = existsSync(base) && MARKUP.test(base) ? [base] : sourceFiles(base).filter((f) => MARKUP.test(f));
+    // Asking for a path by name overrides the exclusion: if you point at a fixture, you want it read.
+    const files = only ? all : all.filter((f) => !TEST_MARKUP.test(relative(root, f)));
+    const findings = [];
+    let filesRead = 0;
+    for (const path of files) {
+        let source;
+        try {
+            source = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // A file too large to be hand-written is generated or minified, and accusing it helps nobody.
+        if (source.length > 400_000)
+            continue;
+        filesRead++;
+        const jsLike = JS_LIKE.test(path);
+        // One page, rather than a file of components: only then do repeated ids land in one document.
+        const isDocument = /\.html?$/i.test(path);
+        findings.push(...checkFile(source, tags(source, jsLike), relative(root, path).replaceAll('\\', '/'), isDocument));
+    }
+    return { findings, filesRead };
+}
+function group(findings) {
+    const by = new Map();
+    for (const f of findings) {
+        const list = by.get(f.rule);
+        if (list)
+            list.push(f);
+        else
+            by.set(f.rule, [f]);
+    }
+    return by;
+}
+function section(title, findings, lines) {
+    if (findings.length === 0)
+        return;
+    lines.push(`## ${title}`, '');
+    for (const [rule, found] of group(findings)) {
+        const meta = RULES[rule];
+        lines.push(`### ${rule} - ${found.length} ${found.length === 1 ? 'place' : 'places'}`, '');
+        lines.push(`${criterionOf(rule)}, ${meta?.severity ?? 'unrated'}.`, '');
+        if (meta)
+            lines.push(`Who it stops: ${meta.stops}.`, '');
+        for (const f of found.slice(0, 20)) {
+            lines.push(`- \`${f.file}:${f.line}\`  ${f.element}`);
+            lines.push(`  - ${f.why}`);
+            lines.push(`  - do this: ${f.next}`);
+        }
+        if (found.length > 20)
+            lines.push(`- ...and ${found.length - 20} more of the same, in the JSON beside this report.`);
+        lines.push('');
+    }
+}
+export function renderAccess(result, scanned) {
+    const { barriers, questions, accepted, filesRead } = result;
+    const lines = ['# Tewip accessibility check', ''];
+    lines.push(`Read ${filesRead} markup ${filesRead === 1 ? 'file' : 'files'} under \`${scanned}\`, without rendering any of them.`, '');
+    if (barriers.length === 0 && questions.length === 0) {
+        lines.push('No barrier was found that reading the markup can settle, and nothing needs a decision.', '');
+    }
+    else {
+        const stopping = barriers.filter((f) => blocks(f.rule)).length;
+        const counts = [
+            `${barriers.length} ${barriers.length === 1 ? 'barrier' : 'barriers'} (${stopping} that stop somebody outright)`,
+            `${questions.length} for a person to settle`,
+        ];
+        if (accepted.length > 0)
+            counts.push(`${accepted.length} already accepted`);
+        lines.push(`**${counts.join(', ')}.**`, '');
+    }
+    section('Barriers', [...barriers].sort(worstFirst), lines);
+    section('Only a person can settle these', [...questions].sort(worstFirst), lines);
+    if (accepted.length > 0) {
+        lines.push('## Already accepted', '');
+        lines.push(`${accepted.length} ${accepted.length === 1 ? 'finding is' : 'findings are'} listed in \`.tewip/access-accepted.txt\`, so they are not repeated here.`, '');
+    }
+    lines.push('## What was not checked', '');
+    lines.push('This read the markup. It did not render a page, so none of the following was tested:', '');
+    for (const n of NOT_CHECKED)
+        lines.push(`- **${n.criterion}** - ${n.why}`);
+    lines.push('');
+    lines.push('A clean result here means these checks found nothing, not that the product is accessible. ' +
+        'Roughly a third of WCAG can be judged by a machine at all, and reading source rather than a rendered page reaches less than that. ' +
+        'The rest needs a person, ideally one who uses a screen reader.', '');
+    lines.push('To accept a finding, add its key to `.tewip/access-accepted.txt`, one per line, with a reason after ` - `.', '');
+    return lines.join('\n');
+}
+export function runAccess(cmd) {
+    const root = resolve(cmd.root);
+    const { findings, filesRead } = findBarriers(root, cmd.only);
+    const alreadyJudged = readAccepted(root);
+    const accepted = findings.filter((f) => alreadyJudged.has(keyOf(f)));
+    const open = findings.filter((f) => !alreadyJudged.has(keyOf(f)));
+    const barriers = open.filter((f) => f.confidence === 'barrier');
+    const questions = open.filter((f) => f.confidence === 'ask-a-person');
+    const result = { barriers, questions, accepted, filesRead };
+    const report = renderAccess(result, cmd.only ? resolve(root, cmd.only) : root);
+    console.log(report);
+    // What fails a build is deliberately narrower than what gets reported. A question never fails it:
+    // a build that breaks because something needs a human decision teaches a team to stop asking. Nor
+    // does a moderate finding - bootstrap's example pages skip a heading level, which is worth knowing
+    // and not worth blocking a release over. Only the barriers that stop somebody outright.
+    const blocking = barriers.filter((f) => blocks(f.rule));
+    if (cmd.gate && blocking.length > 0) {
+        console.error(`${String.fromCharCode(10)}${blocking.length} accessibility barrier(s) that stop somebody outright, out of ${barriers.length} found.`);
+        process.exitCode = 1;
+    }
+    if (cmd.out) {
+        const path = resolve(root, cmd.out);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, report, 'utf8');
+        writeFileSync(path.replace(/\.md$/, '') + '.json', JSON.stringify({ barriers, questions, accepted, filesRead }, null, 2), 'utf8');
+    }
+    return { ...result, report };
+}