tewip-ai 0.34.0 → 0.36.0

package/README.md

@@ -574,6 +574,97 @@ 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).
+
+### Already run axe? Give Tewip the JSON (Phase 29, new)
+
+```bash
+tewip access --report axe-results.json
+```
+
+Reading markup cannot see contrast. A browser can, so if your Playwright, Cypress or jest-axe suite
+already writes an axe report, hand it over — and Tewip will triage it instead of relaying it.
+
+This is where the numbers get uncomfortable. axe 4.14 over nine real pages returned **174 findings**:
+
+| | |
+|---|---|
+| **53 barriers** | a real WCAG criterion, with the **EN 301 549** clause the EU Accessibility Act cites |
+| **51 advice** | axe rules tagged `best-practice` that map to **no criterion at all** |
+| **70 questions** | axe's own `incomplete` — it could not determine them |
+
+**42% of what axe hands you tests no standard.** `region` alone — "all content should be contained by
+landmarks" — was 40 findings, outnumbering every real barrier on the page. Tewip reports those as advice,
+never as barriers, and they never fail a build. That separation is most of the point.
+
+And the unchecked list shrinks, honestly: **one** of its seven entries — 1.4.3 Contrast — moves to
+checked. The other six stay, because no tool settles them. The report also names how many pages the run
+covered, and says plainly that nothing is known about a page it did not open or a state it did not reach.
+
+```
+## Checked here only because a browser run was given
+
+- **1.4.3 Contrast (Minimum)** - would otherwise be unreachable: needs the computed colours of a
+  rendered page, not the markup
+```
+
+A source finding is set aside only when the run opened **that same file** and re-ran the equivalent rule.
+In a React or Vue project that means nothing is set aside — the source and the rendered output are two
+different artefacts, and neither is evidence about the other.
+
 ## Teach it your house rules (Phase 27)
 
 ```bash

package/dist/cli/help.js

@@ -118,6 +118,20 @@ 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>] [--report axe.json] [--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.
+                                    Give it --report with the JSON from an axe run and it reads that
+                                    too: contrast moves out of the unchecked list, axe rules that map
+                                    to no WCAG criterion are reported as advice rather than barriers
+                                    (51 of 174 findings on nine real pages), and what axe could not
+                                    determine becomes a question. No browser, no network, no model.
   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/verbs-prove.js

@@ -20,6 +20,18 @@ export async function proveVerb(verb, args) {
             });
             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' && args[i - 1] !== '--report');
+            runAccess({
+                root: process.cwd(),
+                only: paths[0],
+                out: flag(args, 'out'),
+                report: flag(args, 'report'),
+                gate: args.includes('--strict'),
+            });
+            return true;
+        }
         case 'standards': {
             const { runStandards } = await import('../engine/standards/standards-command.js');
             runStandards({

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

@@ -0,0 +1,233 @@
+// 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 { readAxeReport } from './reports.js';
+import { merge, nowChecked, pagesIn, renderBrowserSection, standardOf, stillNotChecked } from './merge.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, browser } = result;
+    const lines = ['# Tewip accessibility check', ''];
+    lines.push(`Read ${filesRead} markup ${filesRead === 1 ? 'file' : 'files'} under \`${scanned}\`, without rendering any of them.`, '');
+    if (browser) {
+        lines.push(`Also read an axe run over ${browser.pages.length} rendered ${browser.pages.length === 1 ? 'page' : 'pages'}, ` +
+            'which settles what reading markup cannot.', '');
+    }
+    if (barriers.length === 0 && questions.length === 0 && !browser) {
+        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`);
+        if (browser) {
+            counts.unshift(`${browser.barriers.length} barriers the browser run proves`);
+            if (browser.questions.length > 0)
+                counts.push(`${browser.questions.length} the browser could not determine`);
+        }
+        lines.push(`**${counts.join(', ')}.**`, '');
+    }
+    if (browser) {
+        renderBrowserSection('Barriers seen in the browser', browser.barriers, lines);
+        renderBrowserSection('The browser could not determine these', browser.questions, lines);
+    }
+    section('Barriers read from the source', [...barriers].sort(worstFirst), lines);
+    section('Only a person can settle these', [...questions].sort(worstFirst), lines);
+    if (browser && browser.advice.length > 0) {
+        // Kept out of the counts above on purpose. These are axe's own best-practice rules, which test
+        // no standard: on nine real pages they were 51 of 174 findings, outnumbering every real barrier.
+        // Reporting them as equals is how a team learns to ignore the whole report.
+        const rules = [...new Set(browser.advice.map((f) => f.rule))].sort();
+        lines.push('## Advice, not barriers', '');
+        lines.push(`${browser.advice.length} findings come from axe rules that map to no WCAG criterion - ` +
+            `${rules.join(', ')}. They are somebody's good idea rather than a standard, so they are not counted as barriers ` +
+            'and never fail a build. Worth reading once; not worth a release.', '');
+    }
+    if (browser && browser.superseded.length > 0) {
+        lines.push('## Set aside, because the browser run checked them', '');
+        lines.push(`${browser.superseded.length} source ${browser.superseded.length === 1 ? 'finding' : 'findings'} ` +
+            'are not listed above: the axe run checked their criterion on a rendered page, so its answer is the better ' +
+            'one and repeating them here would count the same barrier twice. They are in the JSON beside this report.', '');
+    }
+    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.`, '');
+    }
+    // Coverage comes from every rule that ran, not from the ones that found something: a contrast
+    // check that ran and passed has still checked contrast.
+    const ran = browser?.rulesRun ?? new Set();
+    const settled = nowChecked(ran);
+    const remaining = stillNotChecked(ran);
+    if (settled.length > 0) {
+        lines.push('## Checked here only because a browser run was given', '');
+        for (const n of settled)
+            lines.push(`- **${n.criterion}** - would otherwise be unreachable: ${n.why}`);
+        lines.push('');
+    }
+    lines.push('## What was not checked', '');
+    lines.push(browser
+        ? 'Even with the browser run, none of the following was tested:'
+        : 'This read the markup. It did not render a page, so none of the following was tested:', '');
+    for (const n of remaining)
+        lines.push(`- **${n.criterion}** - ${n.why}`);
+    if (browser) {
+        lines.push('');
+        lines.push(`The run covered ${browser.pages.length} ${browser.pages.length === 1 ? 'page' : 'pages'}. ` +
+            'Nothing is known about a page it did not open, or about a state it did not reach - a dialog that was never ' +
+            'opened, a form that was never submitted, an error that was never triggered.');
+    }
+    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' +
+        (browser ? '' : ', 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)));
+    // Phase 29: a browser run, where one was given. It is the better witness for every criterion it
+    // checked, so the source findings for those criteria are set aside rather than repeated.
+    const run = cmd.report ? readAxeReport(resolve(root, cmd.report)) : undefined;
+    const graded = run ? merge(open, run, root) : undefined;
+    const kept = graded ? graded.kept : open;
+    const barriers = kept.filter((f) => f.confidence === 'barrier');
+    const questions = kept.filter((f) => f.confidence === 'ask-a-person');
+    const browser = run && graded
+        ? {
+            barriers: run.findings.filter((f) => f.confidence === 'barrier'),
+            questions: run.findings.filter((f) => f.confidence === 'ask-a-person'),
+            advice: run.findings.filter((f) => f.confidence === 'advice'),
+            superseded: graded.superseded,
+            pages: pagesIn(run),
+            rulesRun: run.rulesRun,
+        }
+        : undefined;
+    const result = { barriers, questions, accepted, filesRead, ...(browser ? { browser } : {}) };
+    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.
+    // A browser barrier counts the same way: axe saw it on a rendered page, which is stronger
+    // evidence than reading source, not weaker. Advice never counts, whatever axe's impact says.
+    const blocking = barriers.filter((f) => blocks(f.rule)).length + (browser?.barriers.filter((f) => f.severity === 'blocker').length ?? 0);
+    if (cmd.gate && blocking > 0) {
+        const found = barriers.length + (browser?.barriers.length ?? 0);
+        console.error(`${String.fromCharCode(10)}${blocking} accessibility barrier(s) that stop somebody outright, out of ${found} 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 };
+}

package/dist/engine/access/checks.js

@@ -0,0 +1,231 @@
+// Phase 28: the checks. Each one is deterministic, each one names the element it is talking about,
+// and each one has a shape it refuses rather than guesses on.
+//
+// The restraint matters more than the coverage. These are the barriers that can be decided by
+// reading the markup - a picture with no alt attribute at all, a field with no label anywhere, a
+// div that only answers to a mouse. The ones that need a rendered page (contrast, focus order,
+// whether alt text is any good) are not attempted here and are listed in NOT_CHECKED instead.
+import { inside, labelledBy } from './markup.js';
+/** Elements that already answer to the keyboard and already carry a role. */
+const INTERACTIVE = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary', 'details']);
+/** `role="presentation"` and friends: the author has said this is decoration. */
+function decorative(t) {
+    return t.attrs['aria-hidden'] === 'true' || t.attrs.role === 'presentation' || t.attrs.role === 'none';
+}
+function show(t) {
+    const keep = ['src', 'href', 'type', 'name', 'id', 'class', 'role'];
+    const shown = keep
+        .filter((k) => typeof t.attrs[k] === 'string' && t.attrs[k] !== '')
+        .slice(0, 2)
+        .map((k) => ` ${k}="${t.attrs[k].slice(0, 40)}"`)
+        .join('');
+    return `<${t.name}${shown}${t.spread ? ' {...}' : ''}>`;
+}
+function at(t, file) {
+    return { file, line: t.line, element: show(t) };
+}
+/** Every real `aria-*` attribute. A name outside this set is a typo, and a typo does nothing at all. */
+const ARIA = new Set([
+    'aria-activedescendant', 'aria-atomic', 'aria-autocomplete', 'aria-braillelabel', 'aria-brailleroledescription',
+    'aria-busy', 'aria-checked', 'aria-colcount', 'aria-colindex', 'aria-colindextext', 'aria-colspan',
+    'aria-controls', 'aria-current', 'aria-describedby', 'aria-description', 'aria-details', 'aria-disabled',
+    'aria-dropeffect', 'aria-errormessage', 'aria-expanded', 'aria-flowto', 'aria-grabbed', 'aria-haspopup',
+    'aria-hidden', 'aria-invalid', 'aria-keyshortcuts', 'aria-label', 'aria-labelledby', 'aria-level', 'aria-live',
+    'aria-modal', 'aria-multiline', 'aria-multiselectable', 'aria-orientation', 'aria-owns', 'aria-placeholder',
+    'aria-posinset', 'aria-pressed', 'aria-readonly', 'aria-relevant', 'aria-required', 'aria-roledescription',
+    'aria-rowcount', 'aria-rowindex', 'aria-rowindextext', 'aria-rowspan', 'aria-selected', 'aria-setsize',
+    'aria-sort', 'aria-valuemax', 'aria-valuemin', 'aria-valuenow', 'aria-valuetext',
+]);
+/** A click handler, in any of the four dialects this scanner reads. */
+function clickHandler(t) {
+    return ['onclick', '@click', 'v-on:click', 'on:click'].some((a) => a in t.attrs || t.dynamic.has(a));
+}
+function keyHandler(t) {
+    return Object.keys(t.attrs).concat([...t.dynamic]).some((a) => /key(down|up|press)/i.test(a));
+}
+function tabIndexOf(t) {
+    const raw = t.attrs.tabindex ?? t.attrs.tabIndex;
+    if (raw === undefined)
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Fields that take typing, and therefore need a label. Buttons and hidden fields are excluded: a
+ * submit button is named by its value, and a hidden field is not announced at all.
+ */
+const UNLABELLED_TYPES = new Set(['hidden', 'submit', 'reset', 'button', 'image']);
+/** Checks that look at one element at a time. */
+function perElement(t, file, labelFor, openLabels, ancestorKey) {
+    const out = [];
+    const place = at(t, file);
+    const name = labelledBy(t);
+    if (t.name === 'img' && !t.component) {
+        if (decorative(t)) {
+            // Said to be decoration. That is a legitimate choice and not Tewip's to second-guess.
+        }
+        else if ('alt' in t.attrs || t.dynamic.has('alt')) {
+            // An alt attribute is present. Whether its words are any good is in NOT_CHECKED.
+        }
+        else if (t.spread) {
+            out.push({ rule: 'image-alt', confidence: 'ask-a-person', ...place,
+                why: 'no alt attribute is written here, but the element carries a spread, so alt may come from the props',
+                next: 'check what is spread in; if alt is not among it, add alt, or alt="" if the image is decoration' });
+        }
+        else {
+            out.push({ rule: 'image-alt', confidence: 'barrier', ...place,
+                why: 'no alt attribute at all, and nothing marks the image as decoration',
+                next: 'add alt="..." describing what the image conveys, or alt="" if it conveys nothing' });
+        }
+    }
+    if (t.name === 'input' && !UNLABELLED_TYPES.has(t.attrs.type ?? 'text')) {
+        const linked = typeof t.attrs.id === 'string' && labelFor.has(t.attrs.id);
+        if (!name.named && !linked && openLabels === 0) {
+            if (name.unknown || t.dynamic.has('id')) {
+                out.push({ rule: 'input-label', confidence: 'ask-a-person', ...place,
+                    why: 'no label, aria-label or wrapping <label> can be read here, and part of the element is an expression',
+                    next: 'confirm the field is labelled at runtime; if not, add aria-label or a <label for>' });
+            }
+            else {
+                out.push({ rule: 'input-label', confidence: 'barrier', ...place,
+                    why: 'no aria-label, no title, no id matching a <label for>, and not inside a <label>',
+                    next: 'wrap it in a <label>, or give it an id and point a <label for> at it' });
+            }
+        }
+    }
+    if (t.name === 'iframe' && !name.named && !decorative(t)) {
+        out.push({ rule: 'iframe-title', confidence: name.unknown ? 'ask-a-person' : 'barrier', ...place,
+            why: 'an iframe with no title and no aria-label',
+            next: 'add title="..." saying what the frame contains' });
+    }
+    const tabindex = tabIndexOf(t);
+    if (tabindex !== null && tabindex > 0) {
+        out.push({ rule: 'positive-tabindex', confidence: 'barrier', ...place,
+            why: `tabindex="${tabindex}" takes this element out of the document order and puts it before everything that has none`,
+            next: 'use tabindex="0" and let the source order decide, or move the element in the markup' });
+    }
+    if (t.attrs['aria-hidden'] === 'true' && (INTERACTIVE.has(t.name) || (tabindex !== null && tabindex >= 0))) {
+        out.push({ rule: 'aria-hidden-focusable', confidence: 'barrier', ...place,
+            why: 'hidden from screen readers but still reachable by the tab key',
+            next: 'also remove it from the tab order with tabindex="-1", or stop hiding it' });
+    }
+    // `ancestorKey`: an enclosing element already handles keys, which is how every dialog in the
+    // world is built - a backdrop div closes on click, and Escape closes it from the dialog itself.
+    // WCAG 2.1.1 asks that the *function* be reachable from the keyboard, not that this particular
+    // div be focusable. Excalidraw's Modal.tsx is exactly this shape, and calling it a blocker is wrong.
+    if (clickHandler(t) && !INTERACTIVE.has(t.name) && !t.component && !t.attrs.role && tabindex === null && !keyHandler(t) && !ancestorKey) {
+        out.push({ rule: 'click-without-keyboard', confidence: 'barrier', ...place,
+            why: 'it responds to a click, but it has no role, no tabindex and no key handler, so the keyboard cannot reach or fire it',
+            next: 'use a <button>, or add role="button", tabindex="0" and a key handler' });
+    }
+    if ((t.name === 'video' || t.name === 'audio') && 'autoplay' in t.attrs && !('muted' in t.attrs)) {
+        out.push({ rule: 'autoplay-sound', confidence: 'barrier', ...place,
+            why: 'it plays on load and is not muted, so it talks over a screen reader',
+            next: 'add muted, or remove autoplay and let the person press play' });
+    }
+    if (t.name === 'meta' && (t.attrs.name ?? '').toLowerCase() === 'viewport') {
+        const content = (t.attrs.content ?? '').toLowerCase();
+        const max = /maximum-scale\s*=\s*([\d.]+)/.exec(content);
+        if (/user-scalable\s*=\s*(no|0)/.test(content) || (max && Number(max[1]) < 2)) {
+            out.push({ rule: 'zoom-blocked', confidence: 'barrier', ...place,
+                why: `the viewport meta tag prevents zooming: ${content}`,
+                next: 'drop user-scalable=no and maximum-scale, or set maximum-scale to at least 2' });
+        }
+    }
+    for (const a of Object.keys(t.attrs).concat([...t.dynamic])) {
+        if (a.startsWith('aria-') && !ARIA.has(a)) {
+            out.push({ rule: 'aria-unknown', confidence: 'barrier', ...place,
+                why: `${a} is not an ARIA attribute, so it is ignored entirely and whatever it was meant to do does not happen`,
+                next: 'correct the spelling, or remove it' });
+        }
+    }
+    return out;
+}
+/**
+ * Everything that needs more than one element: names from content, nesting, ids, heading order.
+ *
+ * `isDocument` says this file is one page. It is false for a component file, and that distinction
+ * decides whether duplicate ids mean anything: excalidraw's icons.tsx holds fifty separate SVG
+ * icons, each with its own `<clipPath id="a">`, and they are never in one document together. A
+ * check that calls that a defect is wrong fifty times in one file.
+ */
+export function checkFile(source, all, file, isDocument = false) {
+    const out = [];
+    const labelFor = new Set(all.filter((t) => t.name === 'label' && t.attrs.for).map((t) => t.attrs.for));
+    const seenIds = new Set();
+    let openLabels = 0;
+    let interactiveDepth = 0;
+    let lastHeading = 0;
+    /** The elements currently open around this one, and whether each handles keys. */
+    const open = [];
+    for (const [i, t] of all.entries()) {
+        if (t.name === 'label')
+            openLabels += t.closing ? -1 : t.selfClosing ? 0 : 1;
+        if (t.closing) {
+            if (INTERACTIVE.has(t.name) && interactiveDepth > 0)
+                interactiveDepth--;
+            // Unwind to the matching open element, tolerating markup that never closed it.
+            const from = open.map((o) => o.name).lastIndexOf(t.name);
+            if (from !== -1)
+                open.length = from;
+            continue;
+        }
+        out.push(...perElement(t, file, labelFor, Math.max(openLabels - (t.name === 'label' ? 1 : 0), 0), open.some((o) => o.keys)));
+        if (!t.selfClosing)
+            open.push({ name: t.name, keys: keyHandler(t) });
+        const id = t.attrs.id;
+        if (isDocument && id && !t.dynamic.has('id')) {
+            if (seenIds.has(id)) {
+                out.push({ rule: 'duplicate-id', confidence: 'barrier', ...at(t, file),
+                    why: `id="${id}" is used more than once in this file, so anything pointing at it reaches only the first`,
+                    next: 'make the ids unique' });
+            }
+            seenIds.add(id);
+        }
+        const heading = /^h([1-6])$/.exec(t.name);
+        if (heading) {
+            const level = Number(heading[1]);
+            if (lastHeading > 0 && level > lastHeading + 1) {
+                out.push({ rule: 'heading-skip', confidence: 'barrier', ...at(t, file),
+                    why: `h${level} follows h${lastHeading}, so a level is missing from the outline`,
+                    next: `use h${lastHeading + 1} here, or add the missing heading above it` });
+            }
+            lastHeading = level;
+        }
+        // A name from content: a button or link whose text is the only thing announcing it.
+        if ((t.name === 'button' || (t.name === 'a' && ('href' in t.attrs || t.dynamic.has('href')))) && !t.component) {
+            const label = labelledBy(t);
+            if (!label.named) {
+                const body = inside(source, all, i);
+                const rule = t.name === 'button' ? 'button-name' : 'link-name';
+                if (body.text !== '') {
+                    // Named by its own text. Nothing to say.
+                }
+                else if (label.unknown || body.unreadable) {
+                    out.push({ rule, confidence: 'ask-a-person', ...at(t, file),
+                        why: 'its name would come from content this scanner cannot read - an expression, a component, or an image whose alt is set elsewhere',
+                        next: 'check what it announces with a screen reader; if it is silent, add aria-label' });
+                }
+                else {
+                    out.push({ rule, confidence: 'barrier', ...at(t, file),
+                        why: 'it contains no text and carries no aria-label, so it is announced with its role and nothing else',
+                        next: 'put text inside it, or add aria-label="..." saying what it does' });
+                }
+            }
+            if (interactiveDepth > 0) {
+                out.push({ rule: 'nested-interactive', confidence: 'barrier', ...at(t, file),
+                    why: 'a link or button inside another link or button',
+                    next: 'move it out, so the two controls are siblings rather than nested' });
+            }
+            if (!t.selfClosing)
+                interactiveDepth++;
+        }
+    }
+    const html = all.find((t) => t.name === 'html' && !t.closing);
+    if (html && !('lang' in html.attrs) && !html.dynamic.has('lang')) {
+        out.push({ rule: 'html-lang', confidence: 'barrier', ...at(html, file),
+            why: 'the <html> element has no lang attribute, so a screen reader guesses the language',
+            next: 'add lang="en", or whichever language the page is written in' });
+    }
+    return out;
+}

package/dist/engine/access/markup.js

@@ -0,0 +1,174 @@
+// Phase 28: reading markup well enough to be honest about it.
+//
+// This is not an HTML parser and does not try to be. It is a tolerant tag scanner over the four
+// shapes a real project writes its interface in - HTML, JSX/TSX, Vue and Svelte templates - and its
+// one job is to know *when it does not know*. An attribute whose value is an expression
+// (`alt={caption}`), an element carrying a spread (`<img {...props} />`), a component rather than an
+// element (`<Image />`): in every one of those the markup alone cannot say whether a barrier exists,
+// and the scanner says so rather than guessing. That refusal is the whole reason this is worth
+// shipping; a tool that accuses `<img alt={alt} />` of having no alt text gets switched off in a day.
+//
+// Everything here is deterministic and costs nothing: no browser, no network, no model.
+/**
+ * Elements HTML closes for you. A scanner that expects `</img>` pairs everything wrong from the
+ * first image onwards, which is how naive checkers end up reporting a button as empty.
+ */
+const VOID = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+/**
+ * A tag, with the three attribute-value shapes that appear in practice kept apart from `>` so an
+ * expression containing a greater-than sign does not end the tag early.
+ */
+// The lookahead after the name is load-bearing: a real tag is followed by whitespace, `/` or `>`.
+// Without it `/<!doctype html|<html[\s>]/i` - a regex literal in excalidraw's App.tsx - parsed as an
+// <html> element and was reported as a page with no lang attribute.
+// The attribute group is lazy on purpose. Greedy, it absorbs the `/` of `<button ... />` into the
+// attributes, the element is recorded as still open, and the next sibling control is reported as
+// nested inside it. Quoted and braced values are matched as whole units in the alternation, so
+// laziness cannot stop at a `>` that lives inside one.
+const TAG = /<(\/?)([A-Za-z][A-Za-z0-9._:-]*)(?=[\s/>])((?:[^>"'{]|"[^"]*"|'[^']*'|\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\})*?)(\/?)>/g;
+const ATTRIBUTE = /([@:#\[A-Za-z_][-A-Za-z0-9_:.@\]]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|\{((?:[^{}]|\{[^{}]*\})*)\}|([^\s"'<>`=]+)))?/g;
+/** `{...props}`, `{...rest}` - the thing that makes every other judgement about the element unsafe. */
+const SPREAD = /\{\s*\.\.\./;
+/**
+ * Comments, and the bodies of script and style, hold things shaped like tags that are not tags.
+ *
+ * `jsLike` additionally blanks template literals, which is not optional in a .tsx file: real
+ * projects build HTML in backtick strings - an iframe's srcDoc, an email body, a test fixture - and
+ * reading those as the page's own markup produces findings about code that no browser ever renders
+ * as part of this component. Found on excalidraw, whose AI.tsx holds an entire error page in a
+ * template literal and was reported as a page with no lang attribute.
+ *
+ * Blanking rather than scanning is the conservative choice: a string may be a page, or it may be a
+ * SQL query, a documentation sample or an assertion. Tewip does not guess which.
+ */
+function withoutNonMarkup(source, jsLike) {
+    const blank = (m) => m.replace(/[^\n]/g, ' ');
+    const stripped = source
+        .replace(/<!--[\s\S]*?-->/g, blank)
+        .replace(/\{\/\*[\s\S]*?\*\/\}/g, blank)
+        .replace(/<script\b[\s\S]*?<\/script\s*>/gi, blank)
+        .replace(/<style\b[\s\S]*?<\/style\s*>/gi, blank);
+    return jsLike ? stripped.replace(/`(?:[^`\\]|\\[\s\S])*`/g, blank) : stripped;
+}
+/** Files whose markup is embedded in JavaScript, where a backtick string is not page markup. */
+export const JS_LIKE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/i;
+function readAttributes(blob) {
+    const attrs = {};
+    const dynamic = new Set();
+    const spread = SPREAD.test(blob);
+    // A spread's contents would otherwise be read as attribute names: `{...props}` becomes `props`.
+    const readable = blob.replace(/\{\s*\.\.\.(?:[^{}]|\{[^{}]*\})*\}/g, ' ');
+    for (const m of readable.matchAll(ATTRIBUTE)) {
+        // A bound attribute is the same attribute. Vue writes `:aria-label="label"` and
+        // `v-bind:title="t"`, Angular writes `[attr.aria-label]="l"`, and reading those names
+        // literally means the element looks as though it has no label at all - which reported eight
+        // perfectly well-labelled buttons in vitepress as unnamed. The value is an expression, so the
+        // attribute is present but unreadable: that is `dynamic`, which asks rather than accuses.
+        const written = m[1].toLowerCase();
+        const binding = /^(?::|v-bind:|\[attr\.|\[)/.exec(written);
+        const name = binding ? written.slice(binding[0].length).replace(/\]$/, '') : written;
+        const quoted = m[2] ?? m[3] ?? m[5];
+        const expression = m[4];
+        if (binding && name !== '') {
+            dynamic.add(name);
+            continue;
+        }
+        if (expression !== undefined) {
+            // A literal inside braces is still a literal: alt={"a cat"} and alt={''} are both readable.
+            const literal = /^\s*(?:"([^"]*)"|'([^']*)'|`([^`$]*)`)\s*$/.exec(expression);
+            if (literal)
+                attrs[name] = literal[1] ?? literal[2] ?? literal[3] ?? '';
+            else
+                dynamic.add(name);
+            continue;
+        }
+        attrs[name] = quoted ?? '';
+    }
+    return { attrs, dynamic, spread };
+}
+/** Every tag in a file, in source order. `jsLike` says to ignore template literals. */
+export function tags(source, jsLike = false) {
+    const text = withoutNonMarkup(source, jsLike);
+    const out = [];
+    let line = 1;
+    let read = 0;
+    for (const m of text.matchAll(TAG)) {
+        const at = m.index;
+        for (let i = read; i < at; i++)
+            if (text[i] === '\n')
+                line++;
+        read = at;
+        const raw = m[2];
+        const name = raw.toLowerCase();
+        out.push({
+            name,
+            component: /^[A-Z]/.test(raw) || raw.includes('.'),
+            ...readAttributes(m[3]),
+            closing: m[1] === '/',
+            selfClosing: m[4] === '/' || VOID.has(name),
+            line,
+            start: at,
+            end: at + m[0].length,
+        });
+    }
+    return out;
+}
+/** Reads what is inside the element opened by `tags[index]`, pairing tags with a depth count. */
+export function inside(source, all, index) {
+    const open = all[index];
+    if (open.selfClosing || open.closing)
+        return { text: '', unreadable: false, within: [] };
+    let depth = 1;
+    let close = -1;
+    const within = [];
+    for (let i = index + 1; i < all.length; i++) {
+        const t = all[i];
+        if (t.name === open.name && !t.selfClosing)
+            depth += t.closing ? -1 : 1;
+        if (depth === 0) {
+            close = i;
+            break;
+        }
+        within.push(t);
+    }
+    // No closing tag found: the file is a fragment, or the markup is broken. Either way, refuse.
+    if (close === -1)
+        return { text: '', unreadable: true, within };
+    const between = source.slice(open.end, all[close].start);
+    const literal = between
+        .replace(/<[^>]*>/g, ' ')
+        .replace(/\{(?:[^{}]|\{[^{}]*\})*\}/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const expressions = /\{(?:[^{}]|\{[^{}]*\})*\}/.test(between);
+    // An image inside a link or button *is* its accessible name when it has alt text. A logo link
+    // written `<a href="/"><img src="logo.png" alt="Home"></a>` is the commonest shape on the web,
+    // and reporting it as an unnamed link would be wrong on nearly every site there is.
+    const alts = within
+        .filter((t) => t.name === 'img' && typeof t.attrs.alt === 'string' && t.attrs.alt.trim() !== '')
+        .map((t) => t.attrs.alt.trim());
+    // `<slot />` is Vue's and Svelte's `{children}`: whatever is inside comes from whoever used this
+    // component, so the markup here cannot say whether the control ends up named. vitepress's
+    // VPSwitch is exactly that shape and was being accused rather than asked about.
+    const unknownChild = within.some((t) => t.component || t.name === 'slot' || t.dynamic.size > 0 || t.spread);
+    const text = [literal, ...alts].filter((s) => s !== '').join(' ');
+    return { text, unreadable: expressions || (unknownChild && alts.length === 0), within };
+}
+/** The accessible name an element carries on its own attributes, if one can be read. */
+export function labelledBy(tag) {
+    const explicit = ['aria-label', 'aria-labelledby', 'title', 'alt'];
+    for (const a of explicit) {
+        if (tag.dynamic.has(a))
+            return { named: false, unknown: true };
+        const v = tag.attrs[a];
+        if (typeof v === 'string' && v.trim() !== '')
+            return { named: true, unknown: false };
+    }
+    if (tag.spread)
+        return { named: false, unknown: true };
+    return { named: false, unknown: false };
+}
+/** Files whose markup this scanner reads. */
+export const MARKUP = /\.(?:html?|jsx|tsx|vue|svelte|astro|erb|php)$/i;

package/dist/engine/access/merge.js

@@ -0,0 +1,119 @@
+import { EQUIVALENT_AXE_RULE } from './reports.js';
+import { NOT_CHECKED, RULES } from './wcag.js';
+/** `1.1.1 Non-text Content` -> `1.1.1`, so a criterion from either source can be compared. */
+export function criterionNumber(criterion) {
+    return /^\d+(?:\.\d+)*/.exec(criterion.trim())?.[0] ?? '';
+}
+/** The criterion a source-read rule belongs to, as a bare number. */
+export function criterionOfRule(rule) {
+    const r = RULES[rule];
+    return r ? criterionNumber(r.criterion) : '';
+}
+/**
+ * Sets aside the source findings the run actually re-checked, rule by rule.
+ *
+ * The test is whether the *equivalent axe rule ran*, not whether axe found something and not
+ * whether some other rule under the same criterion ran. A rule that ran and passed still
+ * supersedes - axe looked at the rendered page and disagreed, which is the better evidence. A rule
+ * with no axe equivalent, like `click-without-keyboard`, is never superseded by anything.
+ */
+export function merge(source, run, root) {
+    const opened = pagesAsFiles(run, root);
+    const kept = [];
+    const superseded = [];
+    for (const f of source) {
+        const equivalent = EQUIVALENT_AXE_RULE[f.rule];
+        // Both conditions, and the second is the one that was missing. A run of nine pages does not
+        // supersede a finding in the hundredth file it never opened: on bootstrap that silently
+        // discarded all 44 source findings, including every one in the example pages axe never saw.
+        // A component file is never a page a browser opens, so in a React or Vue project nothing is
+        // superseded at all - correctly, because the source and the rendered output are two artefacts
+        // and neither is evidence about the other.
+        if (equivalent !== undefined && run.rulesRun.has(equivalent) && opened.has(f.file))
+            superseded.push(f);
+        else
+            kept.push(f);
+    }
+    return { kept, superseded, covered: run.criteriaCovered };
+}
+/** The pages a run opened, as repository-relative paths, for the ones that were local files. */
+export function pagesAsFiles(run, root) {
+    const out = new Set();
+    const base = root.replaceAll('\\', '/').replace(/\/$/, '').toLowerCase();
+    for (const page of run.pages) {
+        // `file:///C:/repo/a.html` -> `C:/repo/a.html`, but `file:///repo/a.html` -> `/repo/a.html`.
+        // Stripping every slash after the scheme is wrong on anything but Windows: the third one is
+        // the root, not padding.
+        const stripped = decodeURIComponent(page.replace(/^file:\/\//i, '')).replaceAll('\\', '/');
+        const path = /^\/[A-Za-z]:/.test(stripped) ? stripped.slice(1) : stripped;
+        const lower = path.toLowerCase();
+        if (lower.startsWith(`${base}/`))
+            out.add(path.slice(base.length + 1));
+    }
+    return out;
+}
+/**
+ * What is still unchecked once the browser run is counted.
+ *
+ * This is the payoff of the phase and the reason it is worth building: the list of criteria Tewip
+ * admits it cannot reach should get shorter when real evidence arrives, rather than being printed
+ * unchanged beneath a browser run that already settled half of it.
+ */
+export function stillNotChecked(rulesRun) {
+    return NOT_CHECKED.filter((n) => n.settledBy === undefined || !rulesRun.has(n.settledBy));
+}
+/** The criteria from NOT_CHECKED that this run did settle, for the report to say so. */
+export function nowChecked(rulesRun) {
+    return NOT_CHECKED.filter((n) => n.settledBy !== undefined && rulesRun.has(n.settledBy));
+}
+const SEVERITY_ORDER = { blocker: 0, serious: 1, moderate: 2, minor: 3 };
+export function worstBrowserFirst(a, b) {
+    const d = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (d !== 0)
+        return d;
+    if (a.rule !== b.rule)
+        return a.rule < b.rule ? -1 : 1;
+    return a.selector < b.selector ? -1 : 1;
+}
+/** Groups by rule, keeping the order the comparator produced. */
+function byRule(findings) {
+    const out = new Map();
+    for (const f of [...findings].sort(worstBrowserFirst)) {
+        const list = out.get(f.rule);
+        if (list)
+            list.push(f);
+        else
+            out.set(f.rule, [f]);
+    }
+    return out;
+}
+/** How a browser finding names its standard: both WCAG and the clause the EAA cites. */
+export function standardOf(f) {
+    if (!f.criterion)
+        return 'no criterion - this is a best-practice rule, not a standard';
+    const en = f.en301549 ? `, EN 301 549 clause ${f.en301549}` : '';
+    return `WCAG 2.2 ${f.criterion} (${f.level ?? 'A'})${en}`;
+}
+export function renderBrowserSection(title, findings, lines, limit = 8) {
+    if (findings.length === 0)
+        return;
+    lines.push(`## ${title}`, '');
+    for (const [rule, found] of byRule(findings)) {
+        lines.push(`### ${rule} - ${found.length} ${found.length === 1 ? 'place' : 'places'}`, '');
+        lines.push(`${standardOf(found[0])}, ${found[0].severity}.`, '');
+        lines.push(`${found[0].why}`, '');
+        for (const f of found.slice(0, limit)) {
+            lines.push(`- \`${f.selector}\``);
+            lines.push(`  - \`${f.html}\``);
+            if (f.next && f.next !== found[0].why)
+                lines.push(`  - ${f.next}`);
+        }
+        if (found.length > limit)
+            lines.push(`- ...and ${found.length - limit} more of the same.`);
+        lines.push('');
+    }
+}
+/** The pages a browser run covered, which bounds everything it can be said to prove. */
+export function pagesIn(run) {
+    return [...run.pages].sort();
+}

package/dist/engine/access/reports.js

@@ -0,0 +1,206 @@
+// Phase 29: reading a real browser run, so the criteria Phase 28 says it cannot reach stop being
+// unreachable.
+//
+// `tewip access` reads markup and is honest that contrast, focus order and anything else needing a
+// rendered page is outside it. The answer is not for Tewip to ship a browser. It is to read the run
+// a team already produces - axe, in a Playwright, Cypress or jest-axe suite - and do to its output
+// what Phase 9 does to a security scanner's: decide which findings matter, and say why.
+//
+// Why that is worth doing, measured on axe 4.14 over nine real pages (bootstrap's own component
+// pages and excalidraw's index): 122 findings, of which **51 carry no WCAG criterion at all**. Forty
+// are `region` ("all content should be contained by landmarks") and nine are `landmark-one-main`.
+// Both are axe's own `best-practice` rules, not failures of any standard, and they outnumber every
+// real barrier on the page. A team that is handed all 122 as equals stops reading them, which is the
+// reported reason accessibility tooling gets switched off.
+//
+// So the tags decide, not the impact:
+//   a wcag* tag  -> a numbered criterion a regulator can cite, and a barrier;
+//   best-practice only -> advice, reported apart and never failing a build;
+//   `incomplete` -> axe could not determine it, which is exactly Tewip's "ask a person".
+import { readFileSync } from 'node:fs';
+/** axe's impact, in Tewip's words. A WCAG-tagged `moderate` is still worth fixing, not a blocker. */
+const SEVERITY = {
+    critical: 'blocker',
+    serious: 'blocker',
+    moderate: 'moderate',
+    minor: 'minor',
+};
+/**
+ * `wcag143` -> `1.4.3`. The first digit is the principle, the second the guideline, the rest the
+ * criterion - so `wcag1411` is 1.4.11 and not 14.1.1, there being no fourteenth principle.
+ */
+function criterionFrom(tags) {
+    for (const tag of tags) {
+        const m = /^wcag(\d)(\d)(\d+)$/.exec(tag);
+        if (m)
+            return `${m[1]}.${m[2]}.${m[3]}`;
+    }
+    return null;
+}
+/** `wcag2a`, `wcag21aa`, `wcag22aa` -> the conformance level being claimed. */
+function levelFrom(tags) {
+    let best = null;
+    for (const tag of tags) {
+        const m = /^wcag\d{1,2}(a{1,3})$/.exec(tag);
+        if (!m)
+            continue;
+        const level = m[1].toUpperCase();
+        // The strictest statement wins, so a rule tagged both A and AA is reported as AA.
+        if (best === null || level.length > best.length)
+            best = level;
+    }
+    return best;
+}
+/** `EN-9.1.4.3` -> `9.1.4.3`. */
+function enClauseFrom(tags) {
+    for (const tag of tags) {
+        const m = /^EN-(\d+(?:\.\d+)+)$/.exec(tag);
+        if (m)
+            return m[1];
+    }
+    return null;
+}
+/** axe writes its guidance as "Fix any of the following:\n  <reason>". One line reads better. */
+function tidySummary(summary, fallback) {
+    const cleaned = summary
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l !== '' && !/^Fix (any|all) of the following:$/.test(l))
+        .join('; ');
+    return cleaned === '' ? fallback : cleaned;
+}
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+const text = (v) => (typeof v === 'string' ? v : '');
+function fromRule(rule, page, kind) {
+    const tags = strings(rule.tags);
+    const criterion = criterionFrom(tags);
+    const help = text(rule.help) || text(rule.description);
+    const id = text(rule.id);
+    // No criterion and axe's own best-practice tag: somebody's good idea, not a standard. Reported,
+    // but never as a barrier and never as something that fails a build.
+    const advice = criterion === null && tags.includes('best-practice');
+    const confidence = kind === 'incomplete' ? 'ask-a-person' : advice ? 'advice' : 'barrier';
+    const nodes = Array.isArray(rule.nodes) ? rule.nodes : [];
+    return nodes.map((node) => ({
+        rule: id,
+        tool: 'axe',
+        confidence,
+        criterion,
+        level: levelFrom(tags),
+        en301549: enClauseFrom(tags),
+        severity: advice ? 'minor' : (SEVERITY[text(rule.impact)] ?? 'moderate'),
+        html: text(node.html).replace(/\s+/g, ' ').slice(0, 160),
+        selector: strings(node.target).join(' '),
+        page,
+        why: kind === 'incomplete'
+            ? `${help}. axe could not determine this one: ${tidySummary(text(node.failureSummary), 'no reason given')}`
+            : help,
+        next: tidySummary(text(node.failureSummary), help),
+    }));
+}
+const OUTCOMES = ['violations', 'incomplete', 'passes', 'inapplicable'];
+/** One axe result object: what `axe.run()` resolves to. */
+function fromResult(result, page, run) {
+    // Recorded before any finding is read: a page on which every rule passed has still been opened,
+    // and leaving it out made a clean page look like one the browser never visited.
+    run.pages.add(page);
+    for (const outcome of OUTCOMES) {
+        for (const rule of (Array.isArray(result[outcome]) ? result[outcome] : [])) {
+            const id = text(rule.id);
+            if (id !== '')
+                run.rulesRun.add(id);
+            const criterion = criterionFrom(strings(rule.tags));
+            if (criterion)
+                run.criteriaCovered.add(criterion);
+            // Only the two outcomes that need a person's attention become findings. A rule that passed
+            // or did not apply is evidence of coverage, not something to report.
+            if (outcome === 'violations')
+                run.findings.push(...fromRule(rule, page, 'violation'));
+            if (outcome === 'incomplete')
+                run.findings.push(...fromRule(rule, page, 'incomplete'));
+        }
+    }
+}
+/** True of anything shaped like the object `axe.run()` resolves to. */
+function looksLikeAxe(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return Array.isArray(v.violations) || Array.isArray(v.incomplete) || Array.isArray(v.passes);
+}
+/**
+ * Reads an axe report, in any of the shapes real suites write it.
+ *
+ * One run; an array of runs, which is what a suite checking several pages produces; or an array of
+ * `{ url, result }` wrappers, which is what people write when they want to keep the page alongside
+ * its findings. Guessing wrong here means reporting a clean page, so an unreadable file throws
+ * rather than returning nothing.
+ */
+export function readAxeReport(path) {
+    let parsed;
+    const raw = readFileSync(path, 'utf8');
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${path} is not JSON. Tewip reads the JSON an axe run writes.`);
+    }
+    const run = { findings: [], pages: new Set(), rulesRun: new Set(), criteriaCovered: new Set() };
+    const pageOf = (v, fallback) => text(v.url) || text(v.page) || fallback;
+    if (looksLikeAxe(parsed)) {
+        fromResult(parsed, pageOf(parsed, path), run);
+        return run;
+    }
+    if (Array.isArray(parsed)) {
+        let read = 0;
+        for (const entry of parsed) {
+            if (looksLikeAxe(entry)) {
+                fromResult(entry, pageOf(entry, path), run);
+                read++;
+                continue;
+            }
+            // A wrapper: { page | url, result: <axe run> }.
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            const wrapper = entry;
+            // axe records the page it actually ran against in `result.url`, which is authoritative.
+            // A wrapper's own label is only a fallback for runs that did not keep it.
+            if (looksLikeAxe(wrapper.result)) {
+                fromResult(wrapper.result, pageOf(wrapper.result, pageOf(wrapper, path)), run);
+                read++;
+            }
+        }
+        if (read > 0 || parsed.length === 0)
+            return run;
+    }
+    throw new Error(`${path} is JSON, but not an axe report: Tewip looked for a "violations" array, a list of runs, ` +
+        'or a list of { page, result } wrappers. Write one with axe.run() in your Playwright, Cypress or jest-axe suite.');
+}
+/**
+ * The axe rule that tests the same thing as one of Tewip's source-read rules.
+ *
+ * Supersession is decided here, rule by rule, rather than by criterion. By criterion it is too
+ * coarse and loses real findings: axe reporting `aria-required-children` means it checked *that*
+ * part of 1.3.1, not that it looked at heading structure, which axe treats as best-practice and
+ * tests under no criterion at all. Nineteen real heading findings disappeared that way before this
+ * map existed.
+ *
+ * `click-without-keyboard` has no entry on purpose: axe has no equivalent rule, so a source finding
+ * for it is never superseded by any run.
+ */
+export const EQUIVALENT_AXE_RULE = {
+    'image-alt': 'image-alt',
+    'input-label': 'label',
+    'button-name': 'button-name',
+    'link-name': 'link-name',
+    'html-lang': 'html-has-lang',
+    'iframe-title': 'frame-title',
+    'zoom-blocked': 'meta-viewport',
+    'nested-interactive': 'nested-interactive',
+    'aria-hidden-focusable': 'aria-hidden-focus',
+    'duplicate-id': 'duplicate-id',
+    'aria-unknown': 'aria-valid-attr',
+    'positive-tabindex': 'tabindex',
+    'autoplay-sound': 'no-autoplay-audio',
+    'heading-skip': 'heading-order',
+};

package/dist/engine/access/wcag.js

@@ -0,0 +1,135 @@
+// Phase 28: the catalogue. Which success criterion each check belongs to, how much it matters, and
+// - the part no other tool writes down - which criteria this check deliberately does not touch.
+//
+// Why the criterion numbers are here at all: accessibility is the one quality question that is also
+// a legal one. The European Accessibility Act has been enforceable since June 2025 and the US
+// Section 508 and ADA rules point at the same standard, WCAG 2.2 level AA. A finding a team can
+// trace to a numbered criterion is a finding they can put in front of a lawyer or a regulator; a
+// finding that only says "bad contrast" is not. So every rule carries its criterion and its level.
+export const RULES = {
+    'image-alt': {
+        criterion: '1.1.1 Non-text Content',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader reads the file name instead of the picture, or says nothing at all',
+    },
+    'input-label': {
+        criterion: '3.3.2 Labels or Instructions',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader announces "edit text" with no way to know what to type',
+    },
+    'button-name': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader announces "button" and nothing else, so it cannot be used or spoken to',
+    },
+    'link-name': {
+        criterion: '2.4.4 Link Purpose',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader lists the page links as "link, link, link"',
+    },
+    'html-lang': {
+        criterion: '3.1.1 Language of Page',
+        level: 'A',
+        severity: 'serious',
+        stops: 'a screen reader reads the page in the wrong accent, which can make it unintelligible',
+    },
+    'click-without-keyboard': {
+        criterion: '2.1.1 Keyboard',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'anyone who cannot use a mouse, including every screen reader user, cannot activate it',
+    },
+    'positive-tabindex': {
+        criterion: '2.4.3 Focus Order',
+        level: 'A',
+        severity: 'serious',
+        stops: 'the tab key jumps around the page in an order that does not match what is on screen',
+    },
+    'nested-interactive': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'serious',
+        stops: 'a control inside a control is announced and operated unpredictably, and often cannot be reached',
+    },
+    'iframe-title': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'serious',
+        stops: 'a screen reader announces an unnamed frame with no clue what is inside it',
+    },
+    'zoom-blocked': {
+        criterion: '1.4.4 Resize Text',
+        level: 'AA',
+        severity: 'serious',
+        stops: 'anyone with low vision cannot pinch to zoom the page on a phone',
+    },
+    'autoplay-sound': {
+        criterion: '1.4.2 Audio Control',
+        level: 'A',
+        severity: 'serious',
+        stops: 'sound plays over a screen reader, which makes the page unusable while it runs',
+    },
+    'duplicate-id': {
+        criterion: '4.1.1 Parsing',
+        level: 'A',
+        severity: 'moderate',
+        stops: 'a label or description points at the wrong element, so the wrong thing is announced',
+    },
+    'heading-skip': {
+        criterion: '1.3.1 Info and Relationships',
+        level: 'A',
+        severity: 'moderate',
+        stops: 'a screen reader user navigating by heading cannot tell how the page is organised',
+    },
+    'aria-unknown': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'moderate',
+        stops: 'nothing - a misspelled aria attribute is silently ignored, so the help it was meant to give never arrives',
+    },
+    'aria-hidden-focusable': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'serious',
+        stops: 'the tab key lands on something a screen reader has been told does not exist',
+    },
+};
+/**
+ * What reading markup cannot settle, said plainly so nobody mistakes a clean run for a pass.
+ *
+ * This list is the honest half of the command. Roughly a third of WCAG is machine-checkable at all,
+ * and a scanner reading source rather than a rendered page checks less than that. Printing this
+ * every time is what stops "Tewip found no barriers" from being heard as "this is accessible".
+ */
+export const NOT_CHECKED = [
+    {
+        criterion: '1.4.3 Contrast (Minimum)',
+        why: 'needs the computed colours of a rendered page, not the markup',
+        // The one entry on this list a browser run genuinely closes (Phase 29).
+        settledBy: 'color-contrast',
+    },
+    // Everything below has no `settledBy` on purpose, and must not acquire one because a tool
+    // reports something under the same criterion number. axe's `image-alt` checks that an alt
+    // attribute exists; it has no opinion on whether the words describe the picture, which is the
+    // part named here. Matching on the number alone briefly made Tewip claim it had checked alt-text
+    // quality and timing behaviour, which no tool can.
+    { criterion: '1.1.1 Non-text Content, quality', why: 'whether alt text actually describes the picture is a human judgement' },
+    { criterion: '2.4.7 Focus Visible', why: 'needs a rendered page to see whether the focus ring survives the stylesheet' },
+    { criterion: '1.3.2 Meaningful Sequence', why: 'needs the rendered order, which CSS can change from the source order' },
+    { criterion: '4.1.3 Status Messages', why: 'needs a running page to observe what a live region announces' },
+    { criterion: '2.2.1 Timing Adjustable', why: 'needs the running behaviour of timeouts' },
+    { criterion: '3.2.x Predictable', why: 'needs a person to use the page and judge it' },
+];
+/** Rules whose finding, on its own, should stop a release. */
+export function blocks(rule) {
+    return RULES[rule]?.severity === 'blocker';
+}
+/** `1.1.1 Non-text Content (A)` - how a finding names its criterion in a report. */
+export function criterionOf(rule) {
+    const r = RULES[rule];
+    return r ? `WCAG 2.2 ${r.criterion} (${r.level})` : 'WCAG 2.2';
+}

package/dist/mcp/tools-prove.js

@@ -95,6 +95,50 @@ export function registerProofTools(server, { answer, readOnly, project }) {
             return 'No migration or schema file in that change.';
         return renderSchema(migrations, stillUsed(root, migrations.flatMap((m) => m.findings)));
     }));
+    server.registerTool('accessibility_barriers', {
+        title: 'Can everybody use this interface?',
+        description: "Accessibility barriers in a project's markup, each named against the WCAG 2.2 criterion a regulator would cite, with the evidence to check it. Two kinds of answer, kept apart on purpose: barriers that reading the markup proves (no alt attribute at all, a field with no label anywhere, a div that only a mouse can activate), and the ones only a person can settle, where something is written as an expression or a component and the markup cannot say. It also returns every criterion it did NOT check - contrast, focus order, whether alt text is any good - because those need a rendered page. Use it before shipping an interface, or when asked whether something is accessible; a clean result means these checks found nothing, never that the product is accessible. No browser, no network, no model.",
+        inputSchema: {
+            project,
+            path: z.string().optional().describe('A file or directory inside the project to check instead of all of it'),
+            axeReport: z
+                .string()
+                .optional()
+                .describe('The JSON from an axe run, if the project has one. It settles contrast, which reading markup cannot, and its findings are triaged rather than relayed: axe rules that map to no WCAG criterion are reported as advice, and what axe could not determine becomes a question.'),
+        },
+        annotations: readOnly,
+    }, ({ project: root, path, axeReport }) => answer(async () => {
+        if (!isAbsolute(root) || !existsSync(root))
+            throw new Error(`project must be an existing absolute path, got "${root}"`);
+        // The pure functions, not runAccess: that one prints, and anything on stdout breaks JSON-RPC.
+        const { findBarriers, keyOf, readAccepted, renderAccess } = await import('../engine/access/access-command.js');
+        const { merge, pagesIn } = await import('../engine/access/merge.js');
+        const { readAxeReport } = await import('../engine/access/reports.js');
+        const { findings, filesRead } = findBarriers(root, path);
+        const judged = readAccepted(root);
+        const open = findings.filter((f) => !judged.has(keyOf(f)));
+        const run = axeReport ? readAxeReport(isAbsolute(axeReport) ? axeReport : `${root}/${axeReport}`) : undefined;
+        const graded = run ? merge(open, run, root) : undefined;
+        const kept = graded ? graded.kept : open;
+        return renderAccess({
+            barriers: kept.filter((f) => f.confidence === 'barrier'),
+            questions: kept.filter((f) => f.confidence === 'ask-a-person'),
+            accepted: findings.filter((f) => judged.has(keyOf(f))),
+            filesRead,
+            ...(run && graded
+                ? {
+                    browser: {
+                        barriers: run.findings.filter((f) => f.confidence === 'barrier'),
+                        questions: run.findings.filter((f) => f.confidence === 'ask-a-person'),
+                        advice: run.findings.filter((f) => f.confidence === 'advice'),
+                        superseded: graded.superseded,
+                        pages: pagesIn(run),
+                        rulesRun: run.rulesRun,
+                    },
+                }
+                : {}),
+        }, path ?? root);
+    }));
     server.registerTool('project_standards', {
         title: "What are this project's own rules?",
         description: "The house rules this team has written down in .tewip/standards/, and whether a change keeps them. Returns two things kept carefully apart: rules Tewip checks and enforces (a forbid or require pattern over a set of files), and guidance it can only carry - prose for the parts no pattern captures, which is passed on when something is written but never reported as verified. Use it before writing or changing code in somebody's project, so what you produce matches their conventions rather than yours.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "mcpName": "io.github.hmamut39/tewip",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [