ultra11y 5.34.0 → 5.34.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review of the code under change before every commit, push and pull request, plus full WCAG 2.2 AA / RGAA audits and conformance deliverables on demand.",
-      "version": "5.34.0",
+      "version": "5.34.2",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/maxgfr/ultra11y",
       "repository": "https://github.com/maxgfr/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "5.34.0",
+  "version": "5.34.2",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "5.34.0",
+  "version": "5.34.2",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.opencode/plugins/ultra11y.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "node:url";
 // Ownership marker: `ultra11y install --opencode` refuses to overwrite a plugin file that
 // does not carry it, so a user's own ultra11y.js is never clobbered.
 const ULTRA11Y_OPENCODE_PLUGIN = "ULTRA11Y_OPENCODE_PLUGIN";
-const ULTRA11Y_PLUGIN_VERSION = "5.34.0";
+const ULTRA11Y_PLUGIN_VERSION = "5.34.2";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "5.34.0",
+  "version": "5.34.2",
   "description": "Audit HTML/CSS/JSX against WCAG 2.2 AA and produce a dated compliance report, or author/review accessible markup (native-HTML-first). A skills.sh agent skill: an install-free static engine (bundled, no npm install) plus the agent's judgment, with check/verify gates against hallucinated non-conformities, and pluggable in-repo standards packs (RGAA France first; Section 508 & EN 301 549 next).",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join52, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.34.0";
+var VERSION = "5.34.2";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -59367,6 +59367,12 @@ function auditFiles(audit2, cwd) {
     return /* @__PURE__ */ new Set();
   }
 }
+function offHarvestHint(criteriaId, evidence) {
+  const anchors = [...new Set(evidence.map((e) => e.selector?.trim() || `${e.file}:${e.line}`).filter(Boolean))];
+  const shown = anchors.slice(0, 4).join(", ");
+  const rest = anchors.length > 4 ? `, +${anchors.length - 4}` : "";
+  return anchors.length ? ` \u2014 this anchor is not among the evidence harvested for ${criteriaId}, so the snippet was verified literally rather than vouched for by the harvest. Cite one of: ${shown}${rest}.` : ` \u2014 ${criteriaId} was harvested no evidence, so nothing can vouch for a transcription here. If the criterion has no subject in scope, the verdict is NA with a justification and no citation to ground.`;
+}
 function tagOf2(x) {
   const fromSnippet = /<\s*([a-zA-Z][\w-]*)/.exec(x.snippet ?? "");
   if (fromSnippet) return fromSnippet[1].toLowerCase();
@@ -59538,8 +59544,8 @@ function applyAdjudication(audit2, adj, opts = {}) {
     }
     return engineNcCache.get(key2) ?? EMPTY_IDS;
   };
-  const toGround = (criteriaId, g, fallback) => {
-    const entry = { g, ...fallback ? { fallback } : {} };
+  const toGround = (criteriaId, g, fallback, offHarvest) => {
+    const entry = { g, ...fallback ? { fallback } : {}, ...offHarvest ? { offHarvest } : {} };
     const list = groundInputs.get(criteriaId);
     if (list) list.push(entry);
     else groundInputs.set(criteriaId, [entry]);
@@ -59584,7 +59590,7 @@ function applyAdjudication(audit2, adj, opts = {}) {
               anchor.representative ? { file: anchor.at.file, line: anchor.at.line, selector: anchor.at.selector ?? c2.selector, snippet: anchor.at.snippet } : { file: c2.file, line: c2.line, selector: anchor.at.selector ?? c2.selector }
             );
           } else {
-            toGround(it.criteriaId, cite);
+            toGround(it.criteriaId, cite, void 0, anchor ? void 0 : offHarvestHint(it.criteriaId, it.evidence));
           }
         }
       }
@@ -59644,7 +59650,7 @@ function applyAdjudication(audit2, adj, opts = {}) {
   }
   const grounding = { grounded: 0, moved: 0, failed: 0, issues: [] };
   for (const [criteriaId, inputs] of groundInputs) {
-    for (const { g, fallback } of inputs) {
+    for (const { g, fallback, offHarvest } of inputs) {
       let r = groundFinding(g, { cwd: opts.cwd });
       if (!r.ok && fallback) {
         const viaAnchor = groundFinding(fallback, { cwd: opts.cwd });
@@ -59656,8 +59662,9 @@ function applyAdjudication(audit2, adj, opts = {}) {
       } else {
         grounding.failed++;
         if (r.issue) {
-          grounding.issues.push(r.issue);
-          blame(criteriaId, r.issue);
+          const issue = offHarvest && r.issue.startsWith("cited snippet not found") ? `${r.issue}${offHarvest}` : r.issue;
+          grounding.issues.push(issue);
+          blame(criteriaId, issue);
         }
       }
     }
@@ -60378,7 +60385,9 @@ var VERDICT_KINDS = `Rule it (the apply gate is FAIL-CLOSED \u2014 a verdict mis
    - \`NC\` (non-conforming) \u2014 REQUIRES \`findings\`: at least one groundable \`{ file, line, selector?, message, snippet?, severity?, normativeRef }\` pointing at REAL source. The fold re-grounds every finding; an invented file:line is rejected, and so is a finding with no \`file\` at all. \`normativeRef\` MUST cite the precise failed test \u2014 under a country standard, one of the criterion's OWN numbered tests, listed in its brief under \xAB tests to rule on \xBB. A WCAG id looks alike, denotes an unrelated test, and is rejected.
    - \`NA\` (not applicable) \u2014 REQUIRES \`justification\`, AND \`citations[]\` whenever evidence WAS presented, to say which of those items fall outside the criterion's scope.
    - \`manual\` (still undecidable) \u2014 REQUIRES \`reason\`: \`needs-rendered-dom\` (only a rendered DOM can decide it, and no capture in this run carries its subject) or \`undecidable\` (the evidence cannot settle it either way).`;
-var ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. \xAB No second navigation system \xBB, \xAB no search engine \xBB, \xAB no error message suggests the expected format \xBB \u2014 an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.`;
+var ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. \xAB No second navigation system \xBB, \xAB no search engine \xBB, \xAB no error message suggests the expected format \xBB \u2014 an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.
+
+AND CITE FROM THIS CRITERION'S OWN ANCHORS, NOT THE THING YOU ARE RULING OUT. An absence pulls you toward the element you are arguing ABOUT \u2014 the search form that is not a site search engine, the menu that is not a second navigation system \u2014 and that element is, precisely because it is off-topic, absent from what this criterion was harvested. A citation on one of the criterion's own anchors is vouched for by the harvest; one outside it has its snippet verified LITERALLY, character for character, and a retyping then fails. Cite the region you inspected \u2014 the \`header\`, the \`nav\`, the \`footer\` the brief listed \u2014 and say in the justification what you did not find in it.`;
 var CAPTURE_RULE = `THE RENDERED PAGE MAY BE ON DISK. When a criterion's evidence is anchored under \`.ultra11y/pages/<id>/\`, the browser already ran: \`dom.html\`, \`styles.json\`, \`boxes.json\`, \`axtree.json\` and \`screen.png\` are there to read. \`needs-rendered-dom\` is refused on such a criterion \u2014 decide it from those files, or answer \`undecidable\` and say what the capture does not settle.`;
 var NEVER_GUESS_RULE = `Never guess. A criterion you cannot decide from real evidence stays \`manual\` with its reason \u2014 that is a valid, honest verdict, and it is worth more than a verdict the gate throws away.`;
 var SCOPE_RULE = `Rule ONLY on the criteria presented. Never introduce another \u2014 a verdict for a criterion nobody asked about is dropped, and under the fold it would otherwise overwrite what the deterministic engine already decided.`;

package/scripts/verify-skill-bundle.mjs

@@ -16,17 +16,14 @@ import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// Claude Code truncates the COMBINED `description` + `when_to_use` text at 1536
-// chars in the skill listing — that listing is what the model matches a task
-// against, so anything past the cut is invisible and the skill silently stops
-// auto-invoking. 1500 leaves a safety margin. NOTE: the budget is shared, not
-// per-field: growing `description` eats into `when_to_use` and vice versa.
-const LISTING_MAX = 1500;
-
-// Frontmatter keys Claude Code understands, plus the two this repo carries
-// (`license`, `metadata`). An unknown key at the root is almost always a typo
-// — `when-to-use` for `when_to_use` costs the whole automatic trigger and
-// otherwise fails silently, so it is a hard error here.
+// Codex accepts descriptions up to 1024 characters. Keep the gate at the
+// official limit so the same frontmatter remains discoverable across hosts.
+const DESCRIPTION_MAX = 1024;
+const CLAUDE_LISTING_MAX = 1500;
+
+// Accept the union of the Codex keys and the Claude Code keys supported by this
+// multi-host repository. The installable skills themselves are tested below
+// against the stricter portable subset.
 const KNOWN_KEYS = new Set([
   "name",
   "description",
@@ -107,11 +104,13 @@ for (const name of skillNames) {
     const when = scalar(fm[1], "when_to_use");
     if (!desc) bad(`skills/${name}: frontmatter has no description`);
     else {
-      const total = desc.length + (when?.length ?? 0);
-      const parts = `description ${desc.length}${when ? ` + when_to_use ${when.length}` : ""} = ${total}`;
-      total <= LISTING_MAX
-        ? ok(`${parts} chars (<= ${LISTING_MAX} safety cap)`)
-        : bad(`skills/${name}: ${parts} chars exceeds the ${LISTING_MAX}-char safety cap — Claude Code truncates the listing at 1536 and the tail stops matching`);
+      desc.length <= DESCRIPTION_MAX
+        ? ok(`description ${desc.length} chars (<= ${DESCRIPTION_MAX} Codex limit)`)
+        : bad(`skills/${name}: description ${desc.length} chars exceeds the ${DESCRIPTION_MAX}-char Codex limit`);
+      const listingLength = desc.length + (when?.length ?? 0);
+      listingLength <= CLAUDE_LISTING_MAX
+        ? ok(`Claude listing ${listingLength} chars (<= ${CLAUDE_LISTING_MAX} safety cap)`)
+        : bad(`skills/${name}: Claude listing ${listingLength} chars exceeds the ${CLAUDE_LISTING_MAX}-char safety cap`);
     }
   }
 

package/skills/review-a11y/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: review-a11y
-description: "Use to REVIEW code changes for accessibility — '/review-a11y', 'review my changes/PR/branch for a11y', 'accessibility review of this diff'. Scopes to exactly the code under change (staged files, working diff, or branch vs merge-base), runs the bundled install-free ultra11y engine (node scripts/ultra11y.mjs, no keys; static WCAG 2.2 AA checks tied to success criteria, cross-file JSX/TSX via --graph), then adds YOUR judgment: refute false positives (SFC/library-source findings are preliminary), decide alt relevance and link purpose, name the rendering criteria (contrast, focus, zoom) as residual risks — never invent a non-conformity. Output: a severity-ranked review (blocking → major → minor) with file:line, concrete fixes, residual risks and a one-line verdict, in the conversation's language (technical tokens stay in English). Companion of the ultra11y skill (full audits, reports, PRD, RGAA packs). Triggers: 'review a11y', 'a11y review', 'accessibility review'."
-when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should be checked: the user just finished or modified a component, template, page or stylesheet; is about to commit, push or open a pull request; asks 'is this accessible?' or 'anything to fix before merge?'; a diff, branch or PR is under discussion; or a hook or CI reports accessibility findings on the change. NOT for a whole-repo audit, a dated conformance report, an RGAA/Section 508 deliverable or a PRD backlog — that is the `ultra11y` skill."
-allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
+description: "Use to REVIEW changed frontend code for accessibility: staged files, a working diff, branch, or PR; prompts such as 'review a11y', 'is this accessible?', or 'anything to fix before merge?'; and hook or CI findings on a change. Run the bundled install-free engine with cross-file JSX/TSX analysis, then adjudicate candidates and return a severity-ranked WCAG 2.2 AA review with file:line fixes, residual rendering risks, and a verdict. Use `ultra11y` instead for whole-repo audits, dated conformance reports, country standards, PRD backlogs, or authoring accessible markup."
 license: MIT
 metadata:
-  version: 5.34.0
+  version: 5.34.2
 ---
 
 # review-a11y — accessibility review of changed code

package/skills/review-a11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join52, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.34.0";
+var VERSION = "5.34.2";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -59367,6 +59367,12 @@ function auditFiles(audit2, cwd) {
     return /* @__PURE__ */ new Set();
   }
 }
+function offHarvestHint(criteriaId, evidence) {
+  const anchors = [...new Set(evidence.map((e) => e.selector?.trim() || `${e.file}:${e.line}`).filter(Boolean))];
+  const shown = anchors.slice(0, 4).join(", ");
+  const rest = anchors.length > 4 ? `, +${anchors.length - 4}` : "";
+  return anchors.length ? ` \u2014 this anchor is not among the evidence harvested for ${criteriaId}, so the snippet was verified literally rather than vouched for by the harvest. Cite one of: ${shown}${rest}.` : ` \u2014 ${criteriaId} was harvested no evidence, so nothing can vouch for a transcription here. If the criterion has no subject in scope, the verdict is NA with a justification and no citation to ground.`;
+}
 function tagOf2(x) {
   const fromSnippet = /<\s*([a-zA-Z][\w-]*)/.exec(x.snippet ?? "");
   if (fromSnippet) return fromSnippet[1].toLowerCase();
@@ -59538,8 +59544,8 @@ function applyAdjudication(audit2, adj, opts = {}) {
     }
     return engineNcCache.get(key2) ?? EMPTY_IDS;
   };
-  const toGround = (criteriaId, g, fallback) => {
-    const entry = { g, ...fallback ? { fallback } : {} };
+  const toGround = (criteriaId, g, fallback, offHarvest) => {
+    const entry = { g, ...fallback ? { fallback } : {}, ...offHarvest ? { offHarvest } : {} };
     const list = groundInputs.get(criteriaId);
     if (list) list.push(entry);
     else groundInputs.set(criteriaId, [entry]);
@@ -59584,7 +59590,7 @@ function applyAdjudication(audit2, adj, opts = {}) {
               anchor.representative ? { file: anchor.at.file, line: anchor.at.line, selector: anchor.at.selector ?? c2.selector, snippet: anchor.at.snippet } : { file: c2.file, line: c2.line, selector: anchor.at.selector ?? c2.selector }
             );
           } else {
-            toGround(it.criteriaId, cite);
+            toGround(it.criteriaId, cite, void 0, anchor ? void 0 : offHarvestHint(it.criteriaId, it.evidence));
           }
         }
       }
@@ -59644,7 +59650,7 @@ function applyAdjudication(audit2, adj, opts = {}) {
   }
   const grounding = { grounded: 0, moved: 0, failed: 0, issues: [] };
   for (const [criteriaId, inputs] of groundInputs) {
-    for (const { g, fallback } of inputs) {
+    for (const { g, fallback, offHarvest } of inputs) {
       let r = groundFinding(g, { cwd: opts.cwd });
       if (!r.ok && fallback) {
         const viaAnchor = groundFinding(fallback, { cwd: opts.cwd });
@@ -59656,8 +59662,9 @@ function applyAdjudication(audit2, adj, opts = {}) {
       } else {
         grounding.failed++;
         if (r.issue) {
-          grounding.issues.push(r.issue);
-          blame(criteriaId, r.issue);
+          const issue = offHarvest && r.issue.startsWith("cited snippet not found") ? `${r.issue}${offHarvest}` : r.issue;
+          grounding.issues.push(issue);
+          blame(criteriaId, issue);
         }
       }
     }
@@ -60378,7 +60385,9 @@ var VERDICT_KINDS = `Rule it (the apply gate is FAIL-CLOSED \u2014 a verdict mis
    - \`NC\` (non-conforming) \u2014 REQUIRES \`findings\`: at least one groundable \`{ file, line, selector?, message, snippet?, severity?, normativeRef }\` pointing at REAL source. The fold re-grounds every finding; an invented file:line is rejected, and so is a finding with no \`file\` at all. \`normativeRef\` MUST cite the precise failed test \u2014 under a country standard, one of the criterion's OWN numbered tests, listed in its brief under \xAB tests to rule on \xBB. A WCAG id looks alike, denotes an unrelated test, and is rejected.
    - \`NA\` (not applicable) \u2014 REQUIRES \`justification\`, AND \`citations[]\` whenever evidence WAS presented, to say which of those items fall outside the criterion's scope.
    - \`manual\` (still undecidable) \u2014 REQUIRES \`reason\`: \`needs-rendered-dom\` (only a rendered DOM can decide it, and no capture in this run carries its subject) or \`undecidable\` (the evidence cannot settle it either way).`;
-var ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. \xAB No second navigation system \xBB, \xAB no search engine \xBB, \xAB no error message suggests the expected format \xBB \u2014 an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.`;
+var ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. \xAB No second navigation system \xBB, \xAB no search engine \xBB, \xAB no error message suggests the expected format \xBB \u2014 an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.
+
+AND CITE FROM THIS CRITERION'S OWN ANCHORS, NOT THE THING YOU ARE RULING OUT. An absence pulls you toward the element you are arguing ABOUT \u2014 the search form that is not a site search engine, the menu that is not a second navigation system \u2014 and that element is, precisely because it is off-topic, absent from what this criterion was harvested. A citation on one of the criterion's own anchors is vouched for by the harvest; one outside it has its snippet verified LITERALLY, character for character, and a retyping then fails. Cite the region you inspected \u2014 the \`header\`, the \`nav\`, the \`footer\` the brief listed \u2014 and say in the justification what you did not find in it.`;
 var CAPTURE_RULE = `THE RENDERED PAGE MAY BE ON DISK. When a criterion's evidence is anchored under \`.ultra11y/pages/<id>/\`, the browser already ran: \`dom.html\`, \`styles.json\`, \`boxes.json\`, \`axtree.json\` and \`screen.png\` are there to read. \`needs-rendered-dom\` is refused on such a criterion \u2014 decide it from those files, or answer \`undecidable\` and say what the capture does not settle.`;
 var NEVER_GUESS_RULE = `Never guess. A criterion you cannot decide from real evidence stays \`manual\` with its reason \u2014 that is a valid, honest verdict, and it is worth more than a verdict the gate throws away.`;
 var SCOPE_RULE = `Rule ONLY on the criteria presented. Never introduce another \u2014 a verdict for a criterion nobody asked about is dropped, and under the fold it would otherwise overwrite what the deterministic engine already decided.`;

package/skills/ultra11y/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: ultra11y
-description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibility and produce a dated auditor-conformance report, OR to AUTHOR/REVIEW accessible markup (native-HTML-first, ARIA last). An install-free engine (`node scripts/ultra11y.mjs`, no keys) runs 81 static checks tied to WCAG criteria — alt/lang/title, unlabeled fields, empty links/buttons, tables, headings, ARIA vocabulary, label-in-name, autocomplete — measured against the official W3C ACT corpus. The engine decides 3 of the 55 criteria; the AI agent adjudicates the 38 judgment ones from harvested evidence + a per-criterion decision protocol (`verify --manual`, gated, fannable via `orchestrate`), and the 14 rendering ones go to `scan` — never silently conforming. Library/SFC code is audited as RENDERED captures (`render --setup`); country standards are pluggable packs (`--standard rgaa`, `scan --sample`). check/verify reject invented non-conformities. Triggers: 'audit WCAG/a11y', 'make accessible', 'fix a11y', 'audit RGAA'."
-when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
+description: "Use to AUDIT a repository, site, or page against WCAG 2.2 AA or a country standard such as RGAA; produce a dated conformance report, criterion grid, PRD backlog, or tickets; AUTHOR accessible markup; fix accessibility; or wire a repo gate and rendered-DOM capture pipeline. The bundled install-free engine runs 81 static checks tied to success criteria, while the agent adjudicates judgment criteria and routes rendering criteria to browser scans; check/verify reject invented non-conformities. Use `review-a11y` instead for a review scoped only to a diff, branch, or PR."
 license: MIT
 metadata:
-  version: 5.34.0
+  version: 5.34.2
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -14,7 +13,7 @@ that with a **division of labour**: the deterministic, install-free engine
 (`node scripts/ultra11y.mjs <command>` — no `npm install`, no key; the JSX/TSX parser
 is embedded in the bundle) does the *mechanical* work — detect the machine-checkable
 non-conformities and tie each to the right **WCAG success criterion** — and **the AI agent**
-(Claude running this skill) *adjudicates the judgment criteria itself* — alt relevance, link
+(the AI agent running this skill) *adjudicates the judgment criteria itself* — alt relevance, link
 purpose in context, reading order — statically, from the evidence the engine harvests
 (`verify --manual`), each verdict gated by `verify`/`check`. Only the truly **rendered-DOM**
 criteria (computed contrast, visible focus, zoom/reflow, content-on-hover) fall to the `scan`
@@ -411,8 +410,11 @@ This skill does the analysis end to end: audit, render, adjudicate, fix, re-audi
 When it has produced fixes, **dispatch `review-a11y` on the code under change as a subagent**,
 and report what it returns.
 
+Use the host's native subagent capability: Codex dispatches a subagent with the prompt below;
+Claude Code can use `Agent(...)`. If the host exposes neither, follow the sequential route below.
+
 ```
-Agent(subagent_type: "general-purpose", prompt: "Use the review-a11y skill on the working diff. Return its report verbatim.")
+Use the review-a11y skill on the working diff. Return its report verbatim.
 ```
 
 Two skills, two scopes, and the split is not cosmetic:

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join52, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.34.0";
+var VERSION = "5.34.2";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -59367,6 +59367,12 @@ function auditFiles(audit2, cwd) {
     return /* @__PURE__ */ new Set();
   }
 }
+function offHarvestHint(criteriaId, evidence) {
+  const anchors = [...new Set(evidence.map((e) => e.selector?.trim() || `${e.file}:${e.line}`).filter(Boolean))];
+  const shown = anchors.slice(0, 4).join(", ");
+  const rest = anchors.length > 4 ? `, +${anchors.length - 4}` : "";
+  return anchors.length ? ` \u2014 this anchor is not among the evidence harvested for ${criteriaId}, so the snippet was verified literally rather than vouched for by the harvest. Cite one of: ${shown}${rest}.` : ` \u2014 ${criteriaId} was harvested no evidence, so nothing can vouch for a transcription here. If the criterion has no subject in scope, the verdict is NA with a justification and no citation to ground.`;
+}
 function tagOf2(x) {
   const fromSnippet = /<\s*([a-zA-Z][\w-]*)/.exec(x.snippet ?? "");
   if (fromSnippet) return fromSnippet[1].toLowerCase();
@@ -59538,8 +59544,8 @@ function applyAdjudication(audit2, adj, opts = {}) {
     }
     return engineNcCache.get(key2) ?? EMPTY_IDS;
   };
-  const toGround = (criteriaId, g, fallback) => {
-    const entry = { g, ...fallback ? { fallback } : {} };
+  const toGround = (criteriaId, g, fallback, offHarvest) => {
+    const entry = { g, ...fallback ? { fallback } : {}, ...offHarvest ? { offHarvest } : {} };
     const list = groundInputs.get(criteriaId);
     if (list) list.push(entry);
     else groundInputs.set(criteriaId, [entry]);
@@ -59584,7 +59590,7 @@ function applyAdjudication(audit2, adj, opts = {}) {
               anchor.representative ? { file: anchor.at.file, line: anchor.at.line, selector: anchor.at.selector ?? c2.selector, snippet: anchor.at.snippet } : { file: c2.file, line: c2.line, selector: anchor.at.selector ?? c2.selector }
             );
           } else {
-            toGround(it.criteriaId, cite);
+            toGround(it.criteriaId, cite, void 0, anchor ? void 0 : offHarvestHint(it.criteriaId, it.evidence));
           }
         }
       }
@@ -59644,7 +59650,7 @@ function applyAdjudication(audit2, adj, opts = {}) {
   }
   const grounding = { grounded: 0, moved: 0, failed: 0, issues: [] };
   for (const [criteriaId, inputs] of groundInputs) {
-    for (const { g, fallback } of inputs) {
+    for (const { g, fallback, offHarvest } of inputs) {
       let r = groundFinding(g, { cwd: opts.cwd });
       if (!r.ok && fallback) {
         const viaAnchor = groundFinding(fallback, { cwd: opts.cwd });
@@ -59656,8 +59662,9 @@ function applyAdjudication(audit2, adj, opts = {}) {
       } else {
         grounding.failed++;
         if (r.issue) {
-          grounding.issues.push(r.issue);
-          blame(criteriaId, r.issue);
+          const issue = offHarvest && r.issue.startsWith("cited snippet not found") ? `${r.issue}${offHarvest}` : r.issue;
+          grounding.issues.push(issue);
+          blame(criteriaId, issue);
         }
       }
     }
@@ -60378,7 +60385,9 @@ var VERDICT_KINDS = `Rule it (the apply gate is FAIL-CLOSED \u2014 a verdict mis
    - \`NC\` (non-conforming) \u2014 REQUIRES \`findings\`: at least one groundable \`{ file, line, selector?, message, snippet?, severity?, normativeRef }\` pointing at REAL source. The fold re-grounds every finding; an invented file:line is rejected, and so is a finding with no \`file\` at all. \`normativeRef\` MUST cite the precise failed test \u2014 under a country standard, one of the criterion's OWN numbered tests, listed in its brief under \xAB tests to rule on \xBB. A WCAG id looks alike, denotes an unrelated test, and is rejected.
    - \`NA\` (not applicable) \u2014 REQUIRES \`justification\`, AND \`citations[]\` whenever evidence WAS presented, to say which of those items fall outside the criterion's scope.
    - \`manual\` (still undecidable) \u2014 REQUIRES \`reason\`: \`needs-rendered-dom\` (only a rendered DOM can decide it, and no capture in this run carries its subject) or \`undecidable\` (the evidence cannot settle it either way).`;
-var ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. \xAB No second navigation system \xBB, \xAB no search engine \xBB, \xAB no error message suggests the expected format \xBB \u2014 an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.`;
+var ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. \xAB No second navigation system \xBB, \xAB no search engine \xBB, \xAB no error message suggests the expected format \xBB \u2014 an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.
+
+AND CITE FROM THIS CRITERION'S OWN ANCHORS, NOT THE THING YOU ARE RULING OUT. An absence pulls you toward the element you are arguing ABOUT \u2014 the search form that is not a site search engine, the menu that is not a second navigation system \u2014 and that element is, precisely because it is off-topic, absent from what this criterion was harvested. A citation on one of the criterion's own anchors is vouched for by the harvest; one outside it has its snippet verified LITERALLY, character for character, and a retyping then fails. Cite the region you inspected \u2014 the \`header\`, the \`nav\`, the \`footer\` the brief listed \u2014 and say in the justification what you did not find in it.`;
 var CAPTURE_RULE = `THE RENDERED PAGE MAY BE ON DISK. When a criterion's evidence is anchored under \`.ultra11y/pages/<id>/\`, the browser already ran: \`dom.html\`, \`styles.json\`, \`boxes.json\`, \`axtree.json\` and \`screen.png\` are there to read. \`needs-rendered-dom\` is refused on such a criterion \u2014 decide it from those files, or answer \`undecidable\` and say what the capture does not settle.`;
 var NEVER_GUESS_RULE = `Never guess. A criterion you cannot decide from real evidence stays \`manual\` with its reason \u2014 that is a valid, honest verdict, and it is worth more than a verdict the gate throws away.`;
 var SCOPE_RULE = `Rule ONLY on the criteria presented. Never introduce another \u2014 a verdict for a criterion nobody asked about is dropped, and under the fold it would otherwise overwrite what the deterministic engine already decided.`;

package/src/adjudicate.ts

@@ -484,6 +484,22 @@ function auditFiles(audit: AuditResult, cwd?: string): Set<string> {
  *  criterion was never given. And it is only half the gate — `groundFinding` still has to find
  *  the cited content in the real source, so a plausible-looking file:line in the right
  *  neighbourhood proves nothing on its own. */
+/** Why a citation was held to the literal check, and what to cite instead.
+ *
+ *  Appended to a `cited snippet not found` refusal when the citation missed THIS criterion's
+ *  harvest. Without it the message names a symptom — a transcription that did not match — and
+ *  hides the cause, which is that the citation left the evidence the criterion was shown. The
+ *  two are fixed differently: one asks the adjudicator to copy more carefully, the other asks
+ *  it to cite something else entirely. */
+export function offHarvestHint(criteriaId: string, evidence: Evidence[]): string {
+  const anchors = [...new Set(evidence.map((e) => e.selector?.trim() || `${e.file}:${e.line}`).filter(Boolean))];
+  const shown = anchors.slice(0, 4).join(", ");
+  const rest = anchors.length > 4 ? `, +${anchors.length - 4}` : "";
+  return anchors.length
+    ? ` — this anchor is not among the evidence harvested for ${criteriaId}, so the snippet was verified literally rather than vouched for by the harvest. Cite one of: ${shown}${rest}.`
+    : ` — ${criteriaId} was harvested no evidence, so nothing can vouch for a transcription here. If the criterion has no subject in scope, the verdict is NA with a justification and no citation to ground.`;
+}
+
 /** The tag a citation or an anchor is about, from its snippet first and its selector second.
  *  Lowercased — HTML tag names are case-insensitive. Undefined when neither says. */
 function tagOf(x: { snippet?: string; selector?: string }): string | undefined {
@@ -789,7 +805,7 @@ export function applyAdjudication(
   // flat list) for the same reason as `blame`: a failed citation has to condemn its own
   // criterion and no other.
   type Ground = { file: string; line: number; selector?: string; snippet?: string };
-  const groundInputs = new Map<string, { g: Ground; fallback?: Ground }[]>();
+  const groundInputs = new Map<string, { g: Ground; fallback?: Ground; offHarvest?: string }[]>();
   // Memoised: only a citation that missed its criterion's own anchors ever asks for it.
   let scopeCache: Set<string> | undefined;
   const { citationDrift } = adjudicationLimits(opts.cwd);
@@ -819,8 +835,9 @@ export function applyAdjudication(
     criteriaId: string,
     g: { file: string; line: number; selector?: string; snippet?: string },
     fallback?: { file: string; line: number; selector?: string; snippet?: string },
+    offHarvest?: string,
   ) => {
-    const entry = { g, ...(fallback ? { fallback } : {}) };
+    const entry = { g, ...(fallback ? { fallback } : {}), ...(offHarvest ? { offHarvest } : {}) };
     const list = groundInputs.get(criteriaId);
     if (list) list.push(entry);
     else groundInputs.set(criteriaId, [entry]);
@@ -948,7 +965,30 @@ export function applyAdjudication(
                 : { file: c.file, line: c.line, selector: anchor.at.selector ?? c.selector },
             );
           } else {
-            toGround(it.criteriaId, cite);
+            // WHY THE STRICT PATH APPLIED, said at the point it applies.
+            //
+            // The citation belongs (it is in a file this audit read) but it is not on an anchor
+            // THIS criterion was shown, so the paragraph above cannot let the harvest vouch for
+            // the transcription — and the refusal that follows says only `cited snippet not
+            // found`, which reads as « you mistyped » when the actionable fact is « you cited
+            // outside this criterion's evidence, so your retyping was verified literally ».
+            //
+            // Measured: that message sent a reader diagnosing RGAA 12.5 to the wrong conclusion
+            // — a fold bug — with this source open. The risk is not the lost criterion, it is
+            // the « fix » that would follow: relaxing the strict path is exactly the hole the
+            // two bounds above exist to close. So the cause travels with the refusal.
+            //
+            // It bites hardest where the criterion's subject is an ABSENCE. 12.1 and 12.5 are
+            // the repeat offenders the adjudicator prompt already names: asked to prove there is
+            // no search engine, a model cites the search form it is arguing about — which is, by
+            // definition, not among the anchors harvested for a criterion about navigation.
+            // ONLY when the citation is genuinely off-harvest. Landing on an anchor and then
+            // claiming a different KIND of element (an <img> cited as a <video>) also reaches
+            // this branch, and telling that reader « not among the harvested evidence » would
+            // be false: the anchor is right there, it is the element that is wrong. That case
+            // keeps the bare refusal, which already says the honest thing — this markup is not
+            // in the file.
+            toGround(it.criteriaId, cite, undefined, anchor ? undefined : offHarvestHint(it.criteriaId, it.evidence));
           }
         }
       }
@@ -1069,7 +1109,7 @@ export function applyAdjudication(
   // flat `groundItems` produced.
   const grounding: GroundingSummary = { grounded: 0, moved: 0, failed: 0, issues: [] };
   for (const [criteriaId, inputs] of groundInputs) {
-    for (const { g, fallback } of inputs) {
+    for (const { g, fallback, offHarvest } of inputs) {
       let r = groundFinding(g, { cwd: opts.cwd });
       // The harvested anchor vouches for a citation the file could not confirm on its own —
       // an adjudicator's retyping of an element it did read. `moved` either way: what
@@ -1084,8 +1124,12 @@ export function applyAdjudication(
       } else {
         grounding.failed++;
         if (r.issue) {
-          grounding.issues.push(r.issue);
-          blame(criteriaId, r.issue);
+          // The cause travels with the refusal, and only when it IS the cause: a citation that
+          // never reached the literal check (a missing file, a line out of range) is not an
+          // off-harvest problem, and saying so would send the reader chasing the wrong thing.
+          const issue = offHarvest && r.issue.startsWith("cited snippet not found") ? `${r.issue}${offHarvest}` : r.issue;
+          grounding.issues.push(issue);
+          blame(criteriaId, issue);
         }
       }
     }

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "5.34.0";
+export const VERSION = "5.34.2";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,

package/src/verdict-rules.ts

@@ -27,7 +27,9 @@ export const VERDICT_KINDS = `Rule it (the apply gate is FAIL-CLOSED — a verdi
    - \`manual\` (still undecidable) — REQUIRES \`reason\`: \`needs-rendered-dom\` (only a rendered DOM can decide it, and no capture in this run carries its subject) or \`undecidable\` (the evidence cannot settle it either way).`;
 
 /** An absence is observed somewhere. Measured: 12.1 and 12.5 lost to this on one run. */
-export const ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. « No second navigation system », « no search engine », « no error message suggests the expected format » — an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.`;
+export const ABSENCE_RULE = `AN NC SHAPED LIKE AN ABSENCE IS STILL ANCHORED. « No second navigation system », « no search engine », « no error message suggests the expected format » — an absence is OBSERVED somewhere: cite the element and the page you observed it on. And when the criterion's subject exists nowhere in the audited scope, the verdict is \`NA\` with its justification, never \`NC\`.
+
+AND CITE FROM THIS CRITERION'S OWN ANCHORS, NOT THE THING YOU ARE RULING OUT. An absence pulls you toward the element you are arguing ABOUT — the search form that is not a site search engine, the menu that is not a second navigation system — and that element is, precisely because it is off-topic, absent from what this criterion was harvested. A citation on one of the criterion's own anchors is vouched for by the harvest; one outside it has its snippet verified LITERALLY, character for character, and a retyping then fails. Cite the region you inspected — the \`header\`, the \`nav\`, the \`footer\` the brief listed — and say in the justification what you did not find in it.`;
 
 /** `needs-rendered-dom` is a claim about the RUN, not a way out of a hard criterion. */
 export const CAPTURE_RULE = `THE RENDERED PAGE MAY BE ON DISK. When a criterion's evidence is anchored under \`.ultra11y/pages/<id>/\`, the browser already ran: \`dom.html\`, \`styles.json\`, \`boxes.json\`, \`axtree.json\` and \`screen.png\` are there to read. \`needs-rendered-dom\` is refused on such a criterion — decide it from those files, or answer \`undecidable\` and say what the capture does not settle.`;