ultra11y 2.31.3 → 2.32.0

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": "2.31.3",
+      "version": "2.32.0",
       "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": "2.31.3",
+  "version": "2.32.0",
   "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": "2.31.3",
+  "version": "2.32.0",
   "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 = "2.31.3";
+const ULTRA11Y_PLUGIN_VERSION = "2.32.0";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "2.31.3",
+  "version": "2.32.0",
   "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 join45, relative as relative5, sep as sep7, dirname as dirname1
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "2.31.3";
+var VERSION = "2.32.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -49698,6 +49698,22 @@ function issueBody(unit, lang, standard = "wcag", format = "audit") {
   }
   return lines.join("\n");
 }
+function issueLabels(unit, standard = "wcag") {
+  const { tag } = standardTag(standard);
+  return unit.advisory ? ["accessibility", tag, "recommendation", unit.severity] : ["accessibility", tag, unit.severity];
+}
+function issueSet(units, lang, standard = "wcag", format = "audit") {
+  const { label } = standardTag(standard);
+  return units.map((u) => ({
+    criteriaId: u.criteriaId,
+    title: issueTitle(u, label),
+    body: issueBody(u, lang, standard, format),
+    labels: issueLabels(u, standard),
+    severity: u.severity,
+    advisory: u.advisory === true,
+    occurrences: u.findings.map((f) => ({ file: f.file, line: f.line, selector: f.selectorHint, message: resolveMessage(f, lang) }))
+  }));
+}
 function createIssue(title2, body2, labels) {
   const base = ["issue", "create", "--title", title2, "--body-file", "-"];
   try {
@@ -49717,7 +49733,7 @@ function recordFailure(result, reason) {
   if (reason && !result.errors.includes(reason)) result.errors.push(reason);
 }
 function pushIssues(units, lang, standard = "wcag", format = "audit") {
-  const { label, tag } = standardTag(standard);
+  const { label } = standardTag(standard);
   const existing = existingIssueTitles();
   const result = { created: 0, skipped: 0, failed: 0, createdTitles: [], errors: [] };
   for (const u of units) {
@@ -49726,8 +49742,7 @@ function pushIssues(units, lang, standard = "wcag", format = "audit") {
       result.skipped++;
       continue;
     }
-    const labels = u.advisory ? ["accessibility", tag, "recommendation", u.severity] : ["accessibility", tag, u.severity];
-    const r = createIssue(title2, issueBody(u, lang, standard, format), labels);
+    const r = createIssue(title2, issueBody(u, lang, standard, format), issueLabels(u, standard));
     if (r.ok) {
       result.created++;
       result.createdTitles.push(title2);
@@ -51629,6 +51644,18 @@ var adjudication_default = {
 
 // src/adjudicate.ts
 var ADJUDICATE_MAX_EVIDENCE = 30;
+function adjudicationContract() {
+  return {
+    verdicts: [...VERDICTS],
+    manualReasons: [...MANUAL_REASON_VALUES],
+    requires: {
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      NA: "a non-empty justification",
+      NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
+      manual: `a reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`
+    }
+  };
+}
 var selectorFor = (el) => {
   const id = el.attribs.id ? `#${el.attribs.id}` : "";
   const cls = el.attribs.class ? `.${el.attribs.class.trim().split(/\s+/)[0]}` : "";
@@ -51830,6 +51857,31 @@ function buildAdjudicationWorklist(audit2, opts = {}) {
 }
 var NC_SEVERITY_DEFAULT = "majeur";
 var MANUAL_REASONS = /* @__PURE__ */ new Set(["needs-rendered-dom", "undecidable"]);
+var VERDICTS = ["C", "NC", "NA", "manual"];
+var MANUAL_REASON_VALUES = ["needs-rendered-dom", "undecidable"];
+function normalizeVerdict2(v) {
+  if (typeof v !== "string") return void 0;
+  const k = v.trim().toLowerCase();
+  return VERDICTS.find((x) => x.toLowerCase() === k);
+}
+function normalizeManualReason(r) {
+  if (typeof r !== "string") return void 0;
+  const k = r.trim().toLowerCase();
+  return MANUAL_REASON_VALUES.find((x) => x === k);
+}
+function canonicalizeAdjudication(adj) {
+  for (const it of adj.items) {
+    if (it.verdict !== null) {
+      const v = normalizeVerdict2(it.verdict);
+      if (v !== void 0) it.verdict = v;
+    }
+    if (it.reason !== null && it.reason !== void 0) {
+      const r = normalizeManualReason(it.reason);
+      if (r !== void 0) it.reason = r;
+    }
+  }
+  return adj;
+}
 function normativeRefResolves(ref, standard, itemCriterionId) {
   const r = (ref ?? "").trim();
   if (!r) return false;
@@ -51852,6 +51904,7 @@ function normativeRefResolves(ref, standard, itemCriterionId) {
 }
 function applyAdjudication(audit2, adj, opts = {}) {
   const issues = [];
+  canonicalizeAdjudication(adj);
   const byId2 = new Map(adj.items.map((it) => [it.criteriaId, it]));
   const packMode = !isCore(adj.standard);
   const open = /* @__PURE__ */ new Set();
@@ -51913,9 +51966,9 @@ function applyAdjudication(audit2, adj, opts = {}) {
       }
     } else if (v === "manual") {
       if (!it.reason || !MANUAL_REASONS.has(it.reason))
-        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason \u2208 {needs-rendered-dom, undecidable}`);
+        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`);
     } else {
-      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}"`);
+      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}" \u2014 expected one of ${VERDICTS.join(" | ")}`);
     }
     for (const rec of it.recommendations ?? []) groundInputs.push({ file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
   }
@@ -52173,6 +52226,7 @@ function writeAdjudication(items, outDir, opts) {
     schemaVersion: SCHEMA_VERSION,
     standard: opts.standard,
     auditDate: opts.auditDate,
+    contract: adjudicationContract(),
     items
   };
   writeFileSync10(todoPath, JSON.stringify(file, null, 2) + "\n");
@@ -57796,6 +57850,9 @@ Options:
                      technique + Contexte de reproduction) for a pure-auditor block
   --gh-issues        prd: also create one GitHub issue per criterion via the gh CLI (opt-in)
   --gh-single        prd: file the whole audit as ONE consolidated GitHub issue (opt-in; wins over --gh-issues)
+  --issues-json      prd: write the issue set (one item per criterion: title, body, labels,
+                     severity, occurrences) to <out>/issues-<date>.json for a non-GitHub
+                     tracker to file \u2014 same items --gh-issues would create, no gh needed
   --scaffold         render: write an SSR-snapshot harness (default: ultra11y-render.tsx)
   --setup            render: install the zero-touch test-render capture harvester (.ultra11y/capture-setup.mjs) + print the runner wiring
   --coverage         render: report rendered-capture coverage (covered vs blind-spot components); with --json emits the coverage object
@@ -58012,6 +58069,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "no-technical",
   "gh-issues",
   "gh-single",
+  "issues-json",
   "override",
   "local",
   "docker",
@@ -58785,6 +58843,19 @@ async function cmdPrd(p) {
   const paths = writePrd(result, { out: out2, lang, split, format, standard, technical });
   const json = p.flags.json === true;
   if (!json) for (const path of paths) console.log(path);
+  let issuesPath;
+  if (p.flags["issues-json"] === true) {
+    const issueFormat = format === "remediation" ? "remediation" : "audit";
+    const issues = issueSet(prdUnits(result, standard, lang), lang, standard, issueFormat);
+    mkdirSync15(out2, { recursive: true });
+    issuesPath = join45(out2, `issues-${result.date}.json`);
+    writeFileSync17(
+      issuesPath,
+      `${JSON.stringify({ tool: "ultra11y", kind: "issues", schemaVersion: 1, standard, date: result.date, count: issues.length, issues }, null, 2)}
+`
+    );
+    if (!json) console.log(issuesPath);
+  }
   const ghMode = p.flags["gh-single"] === true ? "single" : p.flags["gh-issues"] === true ? "per-criterion" : null;
   let gh2;
   if (ghMode) {
@@ -58808,7 +58879,8 @@ async function cmdPrd(p) {
       }
     }
   }
-  if (json) console.log(JSON.stringify({ paths, units: prdUnits(result, standard, lang), ...gh2 ? { gh: gh2 } : {} }, null, 2));
+  if (json)
+    console.log(JSON.stringify({ paths, ...issuesPath ? { issuesPath } : {}, units: prdUnits(result, standard, lang), ...gh2 ? { gh: gh2 } : {} }, null, 2));
   return gh2 && gh2.failed > 0 ? 1 : 0;
 }
 function depsAt(root) {
@@ -59204,7 +59276,22 @@ function applyAdjudicationFile(p, adj, lang) {
   mkdirSync15(out2, { recursive: true });
   const auditPath = join45(out2, "audit-latest.json");
   writeFileSync17(auditPath, JSON.stringify(r.audit, null, 2) + "\n");
-  if (p.flags.json) console.log(JSON.stringify({ ok: true, auditPath, applied: r.applied, stillManual: r.stillManual, grounding: r.grounding }, null, 2));
+  if (p.flags.json)
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          auditPath,
+          applied: r.applied,
+          stillManual: r.stillManual,
+          conformancePct: r.audit.conformancePct,
+          findings: r.audit.findings.length,
+          grounding: r.grounding
+        },
+        null,
+        2
+      )
+    );
   else
     console.log(
       lang === "fr" ? `\u2713 ${r.applied} crit\xE8re(s) adjug\xE9(s), ${r.stillManual} laiss\xE9(s) en r\xE9siduel \u2192 ${auditPath}` : `\u2713 ${r.applied} criterion(ia) adjudicated, ${r.stillManual} left residual \u2192 ${auditPath}`

package/skills/review-a11y/SKILL.md

@@ -5,7 +5,7 @@ when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should
 allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
 license: MIT
 metadata:
-  version: 2.31.3
+  version: 2.32.0
 ---
 
 # review-a11y — accessibility review of changed code

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

@@ -6,7 +6,7 @@ import { join as join45, relative as relative5, sep as sep7, dirname as dirname1
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "2.31.3";
+var VERSION = "2.32.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -49698,6 +49698,22 @@ function issueBody(unit, lang, standard = "wcag", format = "audit") {
   }
   return lines.join("\n");
 }
+function issueLabels(unit, standard = "wcag") {
+  const { tag } = standardTag(standard);
+  return unit.advisory ? ["accessibility", tag, "recommendation", unit.severity] : ["accessibility", tag, unit.severity];
+}
+function issueSet(units, lang, standard = "wcag", format = "audit") {
+  const { label } = standardTag(standard);
+  return units.map((u) => ({
+    criteriaId: u.criteriaId,
+    title: issueTitle(u, label),
+    body: issueBody(u, lang, standard, format),
+    labels: issueLabels(u, standard),
+    severity: u.severity,
+    advisory: u.advisory === true,
+    occurrences: u.findings.map((f) => ({ file: f.file, line: f.line, selector: f.selectorHint, message: resolveMessage(f, lang) }))
+  }));
+}
 function createIssue(title2, body2, labels) {
   const base = ["issue", "create", "--title", title2, "--body-file", "-"];
   try {
@@ -49717,7 +49733,7 @@ function recordFailure(result, reason) {
   if (reason && !result.errors.includes(reason)) result.errors.push(reason);
 }
 function pushIssues(units, lang, standard = "wcag", format = "audit") {
-  const { label, tag } = standardTag(standard);
+  const { label } = standardTag(standard);
   const existing = existingIssueTitles();
   const result = { created: 0, skipped: 0, failed: 0, createdTitles: [], errors: [] };
   for (const u of units) {
@@ -49726,8 +49742,7 @@ function pushIssues(units, lang, standard = "wcag", format = "audit") {
       result.skipped++;
       continue;
     }
-    const labels = u.advisory ? ["accessibility", tag, "recommendation", u.severity] : ["accessibility", tag, u.severity];
-    const r = createIssue(title2, issueBody(u, lang, standard, format), labels);
+    const r = createIssue(title2, issueBody(u, lang, standard, format), issueLabels(u, standard));
     if (r.ok) {
       result.created++;
       result.createdTitles.push(title2);
@@ -51629,6 +51644,18 @@ var adjudication_default = {
 
 // src/adjudicate.ts
 var ADJUDICATE_MAX_EVIDENCE = 30;
+function adjudicationContract() {
+  return {
+    verdicts: [...VERDICTS],
+    manualReasons: [...MANUAL_REASON_VALUES],
+    requires: {
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      NA: "a non-empty justification",
+      NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
+      manual: `a reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`
+    }
+  };
+}
 var selectorFor = (el) => {
   const id = el.attribs.id ? `#${el.attribs.id}` : "";
   const cls = el.attribs.class ? `.${el.attribs.class.trim().split(/\s+/)[0]}` : "";
@@ -51830,6 +51857,31 @@ function buildAdjudicationWorklist(audit2, opts = {}) {
 }
 var NC_SEVERITY_DEFAULT = "majeur";
 var MANUAL_REASONS = /* @__PURE__ */ new Set(["needs-rendered-dom", "undecidable"]);
+var VERDICTS = ["C", "NC", "NA", "manual"];
+var MANUAL_REASON_VALUES = ["needs-rendered-dom", "undecidable"];
+function normalizeVerdict2(v) {
+  if (typeof v !== "string") return void 0;
+  const k = v.trim().toLowerCase();
+  return VERDICTS.find((x) => x.toLowerCase() === k);
+}
+function normalizeManualReason(r) {
+  if (typeof r !== "string") return void 0;
+  const k = r.trim().toLowerCase();
+  return MANUAL_REASON_VALUES.find((x) => x === k);
+}
+function canonicalizeAdjudication(adj) {
+  for (const it of adj.items) {
+    if (it.verdict !== null) {
+      const v = normalizeVerdict2(it.verdict);
+      if (v !== void 0) it.verdict = v;
+    }
+    if (it.reason !== null && it.reason !== void 0) {
+      const r = normalizeManualReason(it.reason);
+      if (r !== void 0) it.reason = r;
+    }
+  }
+  return adj;
+}
 function normativeRefResolves(ref, standard, itemCriterionId) {
   const r = (ref ?? "").trim();
   if (!r) return false;
@@ -51852,6 +51904,7 @@ function normativeRefResolves(ref, standard, itemCriterionId) {
 }
 function applyAdjudication(audit2, adj, opts = {}) {
   const issues = [];
+  canonicalizeAdjudication(adj);
   const byId2 = new Map(adj.items.map((it) => [it.criteriaId, it]));
   const packMode = !isCore(adj.standard);
   const open = /* @__PURE__ */ new Set();
@@ -51913,9 +51966,9 @@ function applyAdjudication(audit2, adj, opts = {}) {
       }
     } else if (v === "manual") {
       if (!it.reason || !MANUAL_REASONS.has(it.reason))
-        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason \u2208 {needs-rendered-dom, undecidable}`);
+        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`);
     } else {
-      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}"`);
+      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}" \u2014 expected one of ${VERDICTS.join(" | ")}`);
     }
     for (const rec of it.recommendations ?? []) groundInputs.push({ file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
   }
@@ -52173,6 +52226,7 @@ function writeAdjudication(items, outDir, opts) {
     schemaVersion: SCHEMA_VERSION,
     standard: opts.standard,
     auditDate: opts.auditDate,
+    contract: adjudicationContract(),
     items
   };
   writeFileSync10(todoPath, JSON.stringify(file, null, 2) + "\n");
@@ -57796,6 +57850,9 @@ Options:
                      technique + Contexte de reproduction) for a pure-auditor block
   --gh-issues        prd: also create one GitHub issue per criterion via the gh CLI (opt-in)
   --gh-single        prd: file the whole audit as ONE consolidated GitHub issue (opt-in; wins over --gh-issues)
+  --issues-json      prd: write the issue set (one item per criterion: title, body, labels,
+                     severity, occurrences) to <out>/issues-<date>.json for a non-GitHub
+                     tracker to file \u2014 same items --gh-issues would create, no gh needed
   --scaffold         render: write an SSR-snapshot harness (default: ultra11y-render.tsx)
   --setup            render: install the zero-touch test-render capture harvester (.ultra11y/capture-setup.mjs) + print the runner wiring
   --coverage         render: report rendered-capture coverage (covered vs blind-spot components); with --json emits the coverage object
@@ -58012,6 +58069,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "no-technical",
   "gh-issues",
   "gh-single",
+  "issues-json",
   "override",
   "local",
   "docker",
@@ -58785,6 +58843,19 @@ async function cmdPrd(p) {
   const paths = writePrd(result, { out: out2, lang, split, format, standard, technical });
   const json = p.flags.json === true;
   if (!json) for (const path of paths) console.log(path);
+  let issuesPath;
+  if (p.flags["issues-json"] === true) {
+    const issueFormat = format === "remediation" ? "remediation" : "audit";
+    const issues = issueSet(prdUnits(result, standard, lang), lang, standard, issueFormat);
+    mkdirSync15(out2, { recursive: true });
+    issuesPath = join45(out2, `issues-${result.date}.json`);
+    writeFileSync17(
+      issuesPath,
+      `${JSON.stringify({ tool: "ultra11y", kind: "issues", schemaVersion: 1, standard, date: result.date, count: issues.length, issues }, null, 2)}
+`
+    );
+    if (!json) console.log(issuesPath);
+  }
   const ghMode = p.flags["gh-single"] === true ? "single" : p.flags["gh-issues"] === true ? "per-criterion" : null;
   let gh2;
   if (ghMode) {
@@ -58808,7 +58879,8 @@ async function cmdPrd(p) {
       }
     }
   }
-  if (json) console.log(JSON.stringify({ paths, units: prdUnits(result, standard, lang), ...gh2 ? { gh: gh2 } : {} }, null, 2));
+  if (json)
+    console.log(JSON.stringify({ paths, ...issuesPath ? { issuesPath } : {}, units: prdUnits(result, standard, lang), ...gh2 ? { gh: gh2 } : {} }, null, 2));
   return gh2 && gh2.failed > 0 ? 1 : 0;
 }
 function depsAt(root) {
@@ -59204,7 +59276,22 @@ function applyAdjudicationFile(p, adj, lang) {
   mkdirSync15(out2, { recursive: true });
   const auditPath = join45(out2, "audit-latest.json");
   writeFileSync17(auditPath, JSON.stringify(r.audit, null, 2) + "\n");
-  if (p.flags.json) console.log(JSON.stringify({ ok: true, auditPath, applied: r.applied, stillManual: r.stillManual, grounding: r.grounding }, null, 2));
+  if (p.flags.json)
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          auditPath,
+          applied: r.applied,
+          stillManual: r.stillManual,
+          conformancePct: r.audit.conformancePct,
+          findings: r.audit.findings.length,
+          grounding: r.grounding
+        },
+        null,
+        2
+      )
+    );
   else
     console.log(
       lang === "fr" ? `\u2713 ${r.applied} crit\xE8re(s) adjug\xE9(s), ${r.stillManual} laiss\xE9(s) en r\xE9siduel \u2192 ${auditPath}` : `\u2713 ${r.applied} criterion(ia) adjudicated, ${r.stillManual} left residual \u2192 ${auditPath}`

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 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 remediation backlog or GitHub issues; 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."
 license: MIT
 metadata:
-  version: 2.31.3
+  version: 2.32.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -90,6 +90,7 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 | `references/false-positives.md` | Where a finding may still be wrong, and how to refute it |
 | `references/rendered.md` · `references/automation.md` | Auditing produced HTML, captures, hooks and CI |
 | `references/harnesses.md` | Where this runs: Claude Code, Codex CLI, OpenCode, and the AGENTS.md fallback |
+| `references/orchestrators.md` | Driving the engine from a workflow engine / non-GitHub CI: pinning, the six-step pipeline, exit codes, `--issues-json` for any tracker |
 | `references/ci.md` | `--format sarif\|github`: inline PR annotations, code scanning, job summary |
 | `references/pages.md` | Page snapshots + the per-page criterion grid (`pages`), and its honesty rules |
 | `references/e2e.md` | `render --e2e`: auditing a page during your Playwright/Cypress run |

package/skills/ultra11y/references/orchestrators.md

@@ -0,0 +1,176 @@
+# Drive the engine from an orchestrator
+
+The skill and the GitHub Action assume a person or a coding harness is in the loop. An
+**orchestrator** — an agent workflow engine, a CI job that is not GitHub, a cron runner —
+is different: nothing reads a banner, nothing retries on a hunch, and the only things that
+travel between steps are exit codes and JSON. This page is the contract for that caller.
+
+The shape that matters: **the engine finds, the agent adjudicates, the gates refuse.** Keep
+the detection deterministic and there is no model between "a defect exists" and "a defect is
+counted" — which is the whole reason to wire the engine in rather than ask a model to audit.
+
+## Resolving the engine
+
+Pin the version. `npx` resolves `latest` otherwise, so what runs can change with no commit
+anywhere.
+
+```sh
+npm_config_update_notifier=false npx -y ultra11y@2.31.2 --version   # → 2.31.2, exit 0
+```
+
+- **`npm_config_update_notifier=false` is not optional.** Without it npm prints its
+  "New major version available" notice into the output a step is about to parse.
+- **`ULTRA11Y_BIN`** points at an engine you already have (a vendored `ultra11y.mjs`, a
+  container layer). The engine is one self-contained file with no runtime dependencies, so
+  vendoring is a supported path — that is exactly what the skills and the Action do.
+- **Node ≥ 22.18.** No other system dependency, no API key. (`judge` takes a key; nothing
+  else does. `scan` needs a browser tier — see `references/dynamic.md`.)
+- **Verify what you resolved, and fail if it is not what you asked for.** A step that lets a
+  missing engine fall through reports zero findings, which reads exactly like a clean audit.
+  This is the one failure mode worth being loud about.
+
+## The pipeline
+
+Six steps. Four are deterministic; only step 3 involves a model.
+
+```sh
+ENGINE="npx -y ultra11y@2.31.2"        # or "node $ULTRA11Y_BIN"
+RUN=/tmp/a11y-run                          # out-of-tree: see "Where output lands"
+
+# 1. FIND — the static engine. No model. This is the finding set.
+$ENGINE audit "<globs>" --graph --out "$RUN" --json --lang en > /dev/null
+#    …or, on a pull request, exactly what the branch introduced:
+$ENGINE audit --since "$BASE_REF" --graph --out "$RUN" --json --lang en > /dev/null
+
+# 2. WORKLIST — a draft report, then the criteria a static pass cannot decide.
+$ENGINE report --in "$RUN/audit-latest.json" --out "$RUN" --lang en > /dev/null
+$ENGINE verify --report "$RUN"/wcag-*.md --in "$RUN/audit-latest.json" --manual --out "$RUN" --json
+
+# 3. ADJUDICATE — hand $RUN/ADJUDICATE.todo.json to the agent; it fills every `verdict`.
+#    The file carries its own `contract` (see below) — the agent needs nothing else.
+
+# 4. FOLD — fail-closed. Exit 1 with per-criterion reasons if a verdict is unsupported.
+$ENGINE verify --apply "$RUN/adjudication.json" --in "$RUN/audit-latest.json" --out "$RUN" --json
+
+# 5. REPORT — deterministic rendering of the adjudicated audit.
+$ENGINE report --in "$RUN/audit-latest.json" --out audits --standard rgaa --lang fr
+
+# 6. GATE — integrity. Exit ≠ 0 on an invented criterion or unjustified NA.
+$ENGINE check --report audits/rgaa-*.md --in "$RUN/audit-latest.json" --json
+```
+
+Step 4 is the one to understand: it is a **deterministic gate on the model's output**. A
+verdict with no justification, an NC with no resolvable `normativeRef`, a criterion missing
+from the adjudication — each is refused by name, and the run stops. That is what keeps the
+final report defensible.
+
+## The adjudication contract
+
+`ADJUDICATE.todo.json` declares what may be written into it, so the filler never has to read
+ultra11y's source:
+
+```jsonc
+{
+  "contract": {
+    "verdicts": ["C", "NC", "NA", "manual"],
+    "manualReasons": ["needs-rendered-dom", "undecidable"],
+    "requires": {
+      "C":  "a non-empty justification AND citations[] naming the harvested evidence it cleared …",
+      "NA": "a non-empty justification",
+      "NC": "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
+      "manual": "a reason ∈ {needs-rendered-dom, undecidable}"
+    }
+  },
+  "items": [ /* one per criterion the engine could not decide; fill `verdict` */ ]
+}
+```
+
+Note what `C` costs: a clearing verdict is gated exactly like an accusing one. It must
+name in `citations[]` the evidence it cleared, each anchor resolvable and drawn from that
+criterion's own harvested evidence — and a criterion presented with **no** evidence cannot
+be `C` at all. This is what stops "C everywhere with a plausible sentence" from passing.
+
+The header is **advisory**. `verify --apply` validates against its own constants, so editing
+the contract in the file widens nothing.
+
+Verdicts are matched **case-insensitively** (`na` is `NA`, `MANUAL` is `manual`) — a spelling
+accident is not a disagreement about accessibility. A verdict outside the vocabulary is still
+refused, and the message names the four that are not.
+
+`manual` is the honest verdict for anything that genuinely needs a rendered page. It keeps
+the criterion in `residualRisks`, where the report declares it as a residual risk. **Never
+map an undecided criterion to `C`** — that is the one way to turn this pipeline back into
+the thing it replaces.
+
+## Filing findings on a tracker that is not GitHub
+
+`--gh-issues` shells out to the `gh` CLI. For any other board, take the same items as JSON:
+
+```sh
+$ENGINE prd --in "$RUN/audit-latest.json" --out "$RUN" --issues-json --lang en
+# → $RUN/issues-<date>.json
+```
+
+```jsonc
+{
+  "tool": "ultra11y", "kind": "issues", "schemaVersion": 1,
+  "standard": "wcag", "date": "2026-08-12", "count": 4,
+  "issues": [{
+    "criteriaId": "1.1.1",
+    "title": "[a11y] WCAG 1.1.1 — Non-text Content",   // the de-dupe grain: stable across runs
+    "body": "…",                                       // the auditor block, rendered
+    "labels": ["accessibility", "wcag", "bloquant"],
+    "severity": "bloquant",
+    "advisory": false,                                 // true ⇒ a good practice, NOT a non-conformity
+    "occurrences": [{ "file": "src/Page.tsx", "line": 4, "selector": "img", "message": "…" }]
+  }]
+}
+```
+
+One issue per criterion, not per occurrence — a missing `alt` on forty images is one item
+with forty `occurrences`, not forty tickets. De-dupe on `title` and re-running files nothing
+twice. `advisory: true` marks a non-normative recommendation: it must not be triaged as a
+non-conformity, and it never enters the conformance rate.
+
+## Where output lands
+
+`--out <dir>` fully contains what a command writes: pointed outside the checkout, an audit
+leaves the target repository byte-identical. That matters when the orchestrator audits a
+repo it does not own — write the run's intermediates out-of-tree and let only the final
+dated report land in the project, if at all.
+
+`.ultra11y/pages/` is written only by the page-snapshot commands (`scan`, `snapshot`,
+`dev`); `--root` relocates it. `audit`, `report`, `prd`, `verify` and `check` never touch it.
+
+## Exit codes
+
+| | 0 | 1 | 2 |
+|---|---|---|---|
+| `audit` | reported (no `--fail-on`), or clean | findings ≥ `--fail-on` | usage / bad input |
+| `verify --apply` | folded | the adjudication was refused (see `issues[]`) | usage / bad input |
+| `check` | report is sound | integrity failure | report not found / bad input |
+| `prd` | written | `--gh-*` had failures | usage / bad input |
+
+Read exit codes from the process, **not** from a pipeline — `cmd --json | head` reports
+`head`'s status, which is how a failing gate reads as a pass.
+
+## What the JSON tells you
+
+- `audit --json` → the `AuditResult` (also at `<out>/audit-latest.json`): `findings[]` with
+  stable `findingId`, `criteriaId`, `severity`, `file`, `line`; `residualRisks[]`;
+  `conformancePct` — the **automatic static pass rate**, not a conformance rate.
+- `verify --apply --json` → `{ ok, auditPath, applied, stillManual, conformancePct, findings, grounding }`
+  on success; `{ ok: false, issues[], audit }` when refused.
+- `check --json` → `{ ok, issues[] }`.
+
+## Honesty rules an orchestrator has to carry
+
+The engine is explicit about what it did not decide; a wrapper that flattens that away
+produces exactly the false clean bill of health this design exists to prevent.
+
+1. **A missing engine is a failure, never an empty finding set.**
+2. **Report the residual criteria.** The rendering criteria (contrast, focus, zoom, reflow)
+   are undecided until `scan` runs. Say so; do not let a step summary imply full coverage.
+3. **`conformancePct` is the static pass rate.** Label it as such.
+4. **Never let a model write the counts.** Take them from the JSON — the numbers exist
+   precisely so nothing has to be re-derived by a model that may drop a field.

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join45, relative as relative5, sep as sep7, dirname as dirname1
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "2.31.3";
+var VERSION = "2.32.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -49698,6 +49698,22 @@ function issueBody(unit, lang, standard = "wcag", format = "audit") {
   }
   return lines.join("\n");
 }
+function issueLabels(unit, standard = "wcag") {
+  const { tag } = standardTag(standard);
+  return unit.advisory ? ["accessibility", tag, "recommendation", unit.severity] : ["accessibility", tag, unit.severity];
+}
+function issueSet(units, lang, standard = "wcag", format = "audit") {
+  const { label } = standardTag(standard);
+  return units.map((u) => ({
+    criteriaId: u.criteriaId,
+    title: issueTitle(u, label),
+    body: issueBody(u, lang, standard, format),
+    labels: issueLabels(u, standard),
+    severity: u.severity,
+    advisory: u.advisory === true,
+    occurrences: u.findings.map((f) => ({ file: f.file, line: f.line, selector: f.selectorHint, message: resolveMessage(f, lang) }))
+  }));
+}
 function createIssue(title2, body2, labels) {
   const base = ["issue", "create", "--title", title2, "--body-file", "-"];
   try {
@@ -49717,7 +49733,7 @@ function recordFailure(result, reason) {
   if (reason && !result.errors.includes(reason)) result.errors.push(reason);
 }
 function pushIssues(units, lang, standard = "wcag", format = "audit") {
-  const { label, tag } = standardTag(standard);
+  const { label } = standardTag(standard);
   const existing = existingIssueTitles();
   const result = { created: 0, skipped: 0, failed: 0, createdTitles: [], errors: [] };
   for (const u of units) {
@@ -49726,8 +49742,7 @@ function pushIssues(units, lang, standard = "wcag", format = "audit") {
       result.skipped++;
       continue;
     }
-    const labels = u.advisory ? ["accessibility", tag, "recommendation", u.severity] : ["accessibility", tag, u.severity];
-    const r = createIssue(title2, issueBody(u, lang, standard, format), labels);
+    const r = createIssue(title2, issueBody(u, lang, standard, format), issueLabels(u, standard));
     if (r.ok) {
       result.created++;
       result.createdTitles.push(title2);
@@ -51629,6 +51644,18 @@ var adjudication_default = {
 
 // src/adjudicate.ts
 var ADJUDICATE_MAX_EVIDENCE = 30;
+function adjudicationContract() {
+  return {
+    verdicts: [...VERDICTS],
+    manualReasons: [...MANUAL_REASON_VALUES],
+    requires: {
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      NA: "a non-empty justification",
+      NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
+      manual: `a reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`
+    }
+  };
+}
 var selectorFor = (el) => {
   const id = el.attribs.id ? `#${el.attribs.id}` : "";
   const cls = el.attribs.class ? `.${el.attribs.class.trim().split(/\s+/)[0]}` : "";
@@ -51830,6 +51857,31 @@ function buildAdjudicationWorklist(audit2, opts = {}) {
 }
 var NC_SEVERITY_DEFAULT = "majeur";
 var MANUAL_REASONS = /* @__PURE__ */ new Set(["needs-rendered-dom", "undecidable"]);
+var VERDICTS = ["C", "NC", "NA", "manual"];
+var MANUAL_REASON_VALUES = ["needs-rendered-dom", "undecidable"];
+function normalizeVerdict2(v) {
+  if (typeof v !== "string") return void 0;
+  const k = v.trim().toLowerCase();
+  return VERDICTS.find((x) => x.toLowerCase() === k);
+}
+function normalizeManualReason(r) {
+  if (typeof r !== "string") return void 0;
+  const k = r.trim().toLowerCase();
+  return MANUAL_REASON_VALUES.find((x) => x === k);
+}
+function canonicalizeAdjudication(adj) {
+  for (const it of adj.items) {
+    if (it.verdict !== null) {
+      const v = normalizeVerdict2(it.verdict);
+      if (v !== void 0) it.verdict = v;
+    }
+    if (it.reason !== null && it.reason !== void 0) {
+      const r = normalizeManualReason(it.reason);
+      if (r !== void 0) it.reason = r;
+    }
+  }
+  return adj;
+}
 function normativeRefResolves(ref, standard, itemCriterionId) {
   const r = (ref ?? "").trim();
   if (!r) return false;
@@ -51852,6 +51904,7 @@ function normativeRefResolves(ref, standard, itemCriterionId) {
 }
 function applyAdjudication(audit2, adj, opts = {}) {
   const issues = [];
+  canonicalizeAdjudication(adj);
   const byId2 = new Map(adj.items.map((it) => [it.criteriaId, it]));
   const packMode = !isCore(adj.standard);
   const open = /* @__PURE__ */ new Set();
@@ -51913,9 +51966,9 @@ function applyAdjudication(audit2, adj, opts = {}) {
       }
     } else if (v === "manual") {
       if (!it.reason || !MANUAL_REASONS.has(it.reason))
-        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason \u2208 {needs-rendered-dom, undecidable}`);
+        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`);
     } else {
-      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}"`);
+      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}" \u2014 expected one of ${VERDICTS.join(" | ")}`);
     }
     for (const rec of it.recommendations ?? []) groundInputs.push({ file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
   }
@@ -52173,6 +52226,7 @@ function writeAdjudication(items, outDir, opts) {
     schemaVersion: SCHEMA_VERSION,
     standard: opts.standard,
     auditDate: opts.auditDate,
+    contract: adjudicationContract(),
     items
   };
   writeFileSync10(todoPath, JSON.stringify(file, null, 2) + "\n");
@@ -57796,6 +57850,9 @@ Options:
                      technique + Contexte de reproduction) for a pure-auditor block
   --gh-issues        prd: also create one GitHub issue per criterion via the gh CLI (opt-in)
   --gh-single        prd: file the whole audit as ONE consolidated GitHub issue (opt-in; wins over --gh-issues)
+  --issues-json      prd: write the issue set (one item per criterion: title, body, labels,
+                     severity, occurrences) to <out>/issues-<date>.json for a non-GitHub
+                     tracker to file \u2014 same items --gh-issues would create, no gh needed
   --scaffold         render: write an SSR-snapshot harness (default: ultra11y-render.tsx)
   --setup            render: install the zero-touch test-render capture harvester (.ultra11y/capture-setup.mjs) + print the runner wiring
   --coverage         render: report rendered-capture coverage (covered vs blind-spot components); with --json emits the coverage object
@@ -58012,6 +58069,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "no-technical",
   "gh-issues",
   "gh-single",
+  "issues-json",
   "override",
   "local",
   "docker",
@@ -58785,6 +58843,19 @@ async function cmdPrd(p) {
   const paths = writePrd(result, { out: out2, lang, split, format, standard, technical });
   const json = p.flags.json === true;
   if (!json) for (const path of paths) console.log(path);
+  let issuesPath;
+  if (p.flags["issues-json"] === true) {
+    const issueFormat = format === "remediation" ? "remediation" : "audit";
+    const issues = issueSet(prdUnits(result, standard, lang), lang, standard, issueFormat);
+    mkdirSync15(out2, { recursive: true });
+    issuesPath = join45(out2, `issues-${result.date}.json`);
+    writeFileSync17(
+      issuesPath,
+      `${JSON.stringify({ tool: "ultra11y", kind: "issues", schemaVersion: 1, standard, date: result.date, count: issues.length, issues }, null, 2)}
+`
+    );
+    if (!json) console.log(issuesPath);
+  }
   const ghMode = p.flags["gh-single"] === true ? "single" : p.flags["gh-issues"] === true ? "per-criterion" : null;
   let gh2;
   if (ghMode) {
@@ -58808,7 +58879,8 @@ async function cmdPrd(p) {
       }
     }
   }
-  if (json) console.log(JSON.stringify({ paths, units: prdUnits(result, standard, lang), ...gh2 ? { gh: gh2 } : {} }, null, 2));
+  if (json)
+    console.log(JSON.stringify({ paths, ...issuesPath ? { issuesPath } : {}, units: prdUnits(result, standard, lang), ...gh2 ? { gh: gh2 } : {} }, null, 2));
   return gh2 && gh2.failed > 0 ? 1 : 0;
 }
 function depsAt(root) {
@@ -59204,7 +59276,22 @@ function applyAdjudicationFile(p, adj, lang) {
   mkdirSync15(out2, { recursive: true });
   const auditPath = join45(out2, "audit-latest.json");
   writeFileSync17(auditPath, JSON.stringify(r.audit, null, 2) + "\n");
-  if (p.flags.json) console.log(JSON.stringify({ ok: true, auditPath, applied: r.applied, stillManual: r.stillManual, grounding: r.grounding }, null, 2));
+  if (p.flags.json)
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          auditPath,
+          applied: r.applied,
+          stillManual: r.stillManual,
+          conformancePct: r.audit.conformancePct,
+          findings: r.audit.findings.length,
+          grounding: r.grounding
+        },
+        null,
+        2
+      )
+    );
   else
     console.log(
       lang === "fr" ? `\u2713 ${r.applied} crit\xE8re(s) adjug\xE9(s), ${r.stillManual} laiss\xE9(s) en r\xE9siduel \u2192 ${auditPath}` : `\u2713 ${r.applied} criterion(ia) adjudicated, ${r.stillManual} left residual \u2192 ${auditPath}`

package/src/adjudicate.ts

@@ -102,9 +102,37 @@ export interface AdjudicationFile {
   schemaVersion: number;
   standard: StandardId;
   auditDate: string;
+  // The contract, carried BY the worklist. Whoever fills this file — an agent in a coding
+  // harness, an orchestrator's tool node, a script — reads the file, not ultra11y's source,
+  // so the file has to say what a verdict may be and what each one additionally requires.
+  // Advisory to the reader, never read back by `applyAdjudication` (which validates against
+  // its own constants), so a hand-edited or stale header can never widen what is accepted.
+  contract?: AdjudicationContract;
   items: AdjudicationItem[];
 }
 
+/** What the filler of an adjudication file is allowed to write, stated in the file. */
+export interface AdjudicationContract {
+  verdicts: readonly string[];
+  manualReasons: readonly string[];
+  requires: Record<string, string>;
+}
+
+/** The contract as written into every worklist. Derived from the same constants the gate
+ *  validates against, so the two cannot drift. */
+export function adjudicationContract(): AdjudicationContract {
+  return {
+    verdicts: [...VERDICTS],
+    manualReasons: [...MANUAL_REASON_VALUES],
+    requires: {
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      NA: "a non-empty justification",
+      NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
+      manual: `a reason ∈ {${MANUAL_REASON_VALUES.join(", ")}}`,
+    },
+  };
+}
+
 // ---- evidence harvesters ----
 // Each harvester answers "for this SC, what did the engine see that the agent needs to
 // rule?" — bounded, source-anchored, language-neutral. A criterion with no harvester gets
@@ -390,6 +418,53 @@ export interface ApplyAdjudicationResult {
 const NC_SEVERITY_DEFAULT: Severity = "majeur";
 const MANUAL_REASONS = new Set(["needs-rendered-dom", "undecidable"]);
 
+/** The verdicts an adjudication may carry, in the exact spelling the file must use. Exported
+ *  because it is a CONTRACT, not an implementation detail: the worklist declares it in its own
+ *  header and the rejection message names it, so whoever fills the file never has to read this
+ *  source to learn what they are allowed to write. */
+export const VERDICTS = ["C", "NC", "NA", "manual"] as const;
+/** The reasons a still-`manual` verdict may cite — same contract, same reason to export it. */
+export const MANUAL_REASON_VALUES = ["needs-rendered-dom", "undecidable"] as const;
+
+/** Canonicalise a verdict written in any case ("na", "Nc", "MANUAL" → "NA", "NC", "manual").
+ *
+ *  Three of the four verdicts are upper-case and the fourth is not, which is exactly the kind
+ *  of detail an agent filling the worklist gets wrong — and it used to cost the entire run,
+ *  because `applyAdjudication` fail-closes on an unknown verdict. Case carries no meaning
+ *  here: "na" can only ever mean NA. What stays rejected is a verdict outside the vocabulary,
+ *  which is a real disagreement about the contract rather than a spelling accident. Returns
+ *  undefined when there is no match. */
+export function normalizeVerdict(v: unknown): Exclude<CriterionVerdict, null> | undefined {
+  if (typeof v !== "string") return undefined;
+  const k = v.trim().toLowerCase();
+  return VERDICTS.find((x) => x.toLowerCase() === k);
+}
+
+/** The same tolerance for a `manual` verdict's reason. */
+function normalizeManualReason(r: unknown): string | undefined {
+  if (typeof r !== "string") return undefined;
+  const k = r.trim().toLowerCase();
+  return MANUAL_REASON_VALUES.find((x) => x === k);
+}
+
+/** Rewrite an adjudication's verdicts and manual reasons into their canonical spelling, in
+ *  place. Anything unrecognised is left untouched, so the per-item validation below still
+ *  reports it as the contract violation it is — this normalises spelling, it never invents a
+ *  decision the file did not carry. */
+export function canonicalizeAdjudication(adj: AdjudicationFile): AdjudicationFile {
+  for (const it of adj.items) {
+    if (it.verdict !== null) {
+      const v = normalizeVerdict(it.verdict);
+      if (v !== undefined) it.verdict = v;
+    }
+    if (it.reason !== null && it.reason !== undefined) {
+      const r = normalizeManualReason(it.reason);
+      if (r !== undefined) it.reason = r;
+    }
+  }
+  return adj;
+}
+
 /** Does an NC finding's `normativeRef` resolve against the ACTIVE standard?
  *
  *  Core: a real success-criterion id (reuses `hasSC`).
@@ -433,6 +508,9 @@ function normativeRefResolves(ref: string | undefined, standard: StandardId, ite
  *  a shrunk residual set, and the `adjudicated` marker. */
 export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opts: { cwd?: string } = {}): ApplyAdjudicationResult {
   const issues: string[] = [];
+  // Spelling first, decisions second: "na" is NA, and rejecting the run over the case of a
+  // verdict taught the caller nothing about accessibility. Everything below stays fail-closed.
+  canonicalizeAdjudication(adj);
   const byId = new Map(adj.items.map((it) => [it.criteriaId, it]));
 
   // Coverage. Under the core that means every residual success criterion; under a pack it
@@ -520,9 +598,12 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
       }
     } else if (v === "manual") {
       if (!it.reason || !MANUAL_REASONS.has(it.reason))
-        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason ∈ {needs-rendered-dom, undecidable}`);
+        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason ∈ {${MANUAL_REASON_VALUES.join(", ")}}`);
     } else {
-      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}"`);
+      // Name the vocabulary in the rejection. The caller is usually a model that has just
+      // spent a whole worklist filling this file; "unknown verdict" alone told it nothing
+      // about how to be right on the retry.
+      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}" — expected one of ${VERDICTS.join(" | ")}`);
     }
     // Recommendations are independent of the verdict (a C criterion may still carry a good
     // practice) and are grounded exactly like an NC finding — no normativeRef required, as
@@ -912,6 +993,7 @@ export function writeAdjudication(
     schemaVersion: SCHEMA_VERSION,
     standard: opts.standard,
     auditDate: opts.auditDate,
+    contract: adjudicationContract(),
     items,
   };
   writeFileSync(todoPath, JSON.stringify(file, null, 2) + "\n");

package/src/cli.ts

@@ -6,7 +6,7 @@ import { runAudit } from "./audit.js";
 import { decide, type PreToolUsePayload } from "./hook.js";
 import { writeReport, untestedNeedsRendering, partialAuditBanner } from "./report.js";
 import { writePrd, prdUnits, type PrdFormat } from "./prd.js";
-import { ghAvailable, pushIssues, pushPrComment, pushSingleIssue } from "./gh.js";
+import { ghAvailable, issueSet, pushIssues, pushPrComment, pushSingleIssue, type IssueFormat } from "./gh.js";
 import {
   detectFrameworks,
   renderPlan,
@@ -294,6 +294,9 @@ Options:
                      technique + Contexte de reproduction) for a pure-auditor block
   --gh-issues        prd: also create one GitHub issue per criterion via the gh CLI (opt-in)
   --gh-single        prd: file the whole audit as ONE consolidated GitHub issue (opt-in; wins over --gh-issues)
+  --issues-json      prd: write the issue set (one item per criterion: title, body, labels,
+                     severity, occurrences) to <out>/issues-<date>.json for a non-GitHub
+                     tracker to file — same items --gh-issues would create, no gh needed
   --scaffold         render: write an SSR-snapshot harness (default: ultra11y-render.tsx)
   --setup            render: install the zero-touch test-render capture harvester (.ultra11y/capture-setup.mjs) + print the runner wiring
   --coverage         render: report rendered-capture coverage (covered vs blind-spot components); with --json emits the coverage object
@@ -527,6 +530,7 @@ const BOOLEAN_FLAGS = new Set([
   "no-technical",
   "gh-issues",
   "gh-single",
+  "issues-json",
   "override",
   "local",
   "docker",
@@ -1557,6 +1561,23 @@ async function cmdPrd(p: ParsedArgs): Promise<number> {
   const json = p.flags.json === true;
   if (!json) for (const path of paths) console.log(path);
 
+  // Tracker-agnostic export: the same de-duplicated items `--gh-issues` files, as JSON, so a
+  // board that is not GitHub can file them itself. Written to a file (not stdout) so it
+  // composes with --json, and so an orchestrator reads one stable path instead of parsing
+  // a payload that also carries the markdown paths.
+  let issuesPath: string | undefined;
+  if (p.flags["issues-json"] === true) {
+    const issueFormat: IssueFormat = format === "remediation" ? "remediation" : "audit";
+    const issues = issueSet(prdUnits(result, standard, lang), lang, standard, issueFormat);
+    mkdirSync(out, { recursive: true });
+    issuesPath = join(out, `issues-${result.date}.json`);
+    writeFileSync(
+      issuesPath,
+      `${JSON.stringify({ tool: "ultra11y", kind: "issues", schemaVersion: 1, standard, date: result.date, count: issues.length, issues }, null, 2)}\n`,
+    );
+    if (!json) console.log(issuesPath);
+  }
+
   // GitHub: always-written markdown above; issues are opt-in + best-effort.
   // --gh-single → one consolidated issue; --gh-issues → one issue per criterion.
   const ghMode: "single" | "per-criterion" | null = p.flags["gh-single"] === true ? "single" : p.flags["gh-issues"] === true ? "per-criterion" : null;
@@ -1586,7 +1607,8 @@ async function cmdPrd(p: ParsedArgs): Promise<number> {
       }
     }
   }
-  if (json) console.log(JSON.stringify({ paths, units: prdUnits(result, standard, lang), ...(gh ? { gh } : {}) }, null, 2));
+  if (json)
+    console.log(JSON.stringify({ paths, ...(issuesPath ? { issuesPath } : {}), units: prdUnits(result, standard, lang), ...(gh ? { gh } : {}) }, null, 2));
   // Markdown was written above regardless; but if issue creation was attempted and had
   // any failures, exit non-zero so a CI step / caller sees the GitHub push did not fully
   // succeed (a total failure previously exited 0 and looked green).
@@ -2076,7 +2098,26 @@ function applyAdjudicationFile(p: ParsedArgs, adj: AdjudicationFile, lang: Lang)
   mkdirSync(out, { recursive: true });
   const auditPath = join(out, "audit-latest.json");
   writeFileSync(auditPath, JSON.stringify(r.audit, null, 2) + "\n");
-  if (p.flags.json) console.log(JSON.stringify({ ok: true, auditPath, applied: r.applied, stillManual: r.stillManual, grounding: r.grounding }, null, 2));
+  // Carry the numbers the fold produced. The failure payload has always described its own
+  // outcome (`issues`); the success one described only the mechanics, so a caller that gates
+  // on the adjudicated result — a CI step, an orchestrator's tool node — had to re-read and
+  // re-parse the file it had just been handed the path to.
+  if (p.flags.json)
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          auditPath,
+          applied: r.applied,
+          stillManual: r.stillManual,
+          conformancePct: r.audit.conformancePct,
+          findings: r.audit.findings.length,
+          grounding: r.grounding,
+        },
+        null,
+        2,
+      ),
+    );
   else
     console.log(
       lang === "fr"

package/src/gh.ts

@@ -1,8 +1,19 @@
-// Optional GitHub issue creation for `prd --gh-issues`. Shells out to the `gh`
-// CLI (which handles its own auth) — NO npm dependency, no tokens in ultra11y.
-// Everything is best-effort: if gh is absent/unauthenticated, the caller still
-// wrote the markdown and we just report that issues were skipped. De-dupes by
-// issue title so re-running never creates duplicates.
+// The issue set an audit turns into, plus GitHub as one transport for it.
+//
+// The SET is tracker-agnostic — `issueSet()` renders one de-duplicated item per
+// criterion (title, body, labels, severity) and is what `prd --issues-json`
+// emits, so a board that is not GitHub (a native kanban, GitLab, Jira, Linear)
+// files the same items without shelling out to anything. `pushIssues` /
+// `pushSingleIssue` are the GitHub TRANSPORT for that set: they shell out to the
+// `gh` CLI (which handles its own auth) — NO npm dependency, no tokens in
+// ultra11y. Both paths build their titles, bodies and labels through the same
+// three functions, so the exported JSON and the filed GitHub issue can never
+// drift apart.
+//
+// Everything on the transport side is best-effort: if gh is absent or
+// unauthenticated, the caller still wrote the markdown and we just report that
+// issues were skipped. De-dupes by issue title so re-running never creates
+// duplicates.
 import { execFileSync } from "node:child_process";
 import type { Lang, Severity } from "./types.js";
 import type { PrdUnit } from "./prd.js";
@@ -99,6 +110,43 @@ export function issueBody(unit: PrdUnit, lang: Lang, standard: StandardId = "wca
   return lines.join("\n");
 }
 
+/** The labels an issue carries: `accessibility`, the active standard's tag, its severity —
+ *  plus `recommendation` when the unit is advisory, so a good practice is never triaged as a
+ *  non-conformity. Shared by the GitHub transport and the tracker-agnostic export. */
+export function issueLabels(unit: PrdUnit, standard: StandardId = "wcag"): string[] {
+  const { tag } = standardTag(standard);
+  return unit.advisory ? ["accessibility", tag, "recommendation", unit.severity] : ["accessibility", tag, unit.severity];
+}
+
+/** One issue, rendered for whatever tracker is going to file it. */
+export interface TrackerIssue {
+  criteriaId: string;
+  /** The de-dupe grain: stable across runs, so re-filing is a no-op on any tracker. */
+  title: string;
+  body: string;
+  labels: string[];
+  severity: Severity;
+  /** A non-normative good practice, not a non-conformity. Never counts toward conformance. */
+  advisory: boolean;
+  /** Occurrences behind this issue — a tracker that wants inline anchors reads them here. */
+  occurrences: { file: string; line: number; selector: string; message: string }[];
+}
+
+/** Render the audit's units as a tracker-agnostic issue set — the exact items `pushIssues`
+ *  would file, minus the transport. This is what `prd --issues-json` emits. */
+export function issueSet(units: PrdUnit[], lang: Lang, standard: StandardId = "wcag", format: IssueFormat = "audit"): TrackerIssue[] {
+  const { label } = standardTag(standard);
+  return units.map((u) => ({
+    criteriaId: u.criteriaId,
+    title: issueTitle(u, label),
+    body: issueBody(u, lang, standard, format),
+    labels: issueLabels(u, standard),
+    severity: u.severity,
+    advisory: u.advisory === true,
+    occurrences: u.findings.map((f) => ({ file: f.file, line: f.line, selector: f.selectorHint, message: resolveMessage(f, lang) })),
+  }));
+}
+
 export interface CreateResult {
   ok: boolean;
   /** Concise `gh` stderr reason when the creation failed (both attempts). */
@@ -141,7 +189,7 @@ function recordFailure(result: PushResult, reason?: string): void {
 
 /** Create a GitHub issue per unit, skipping titles that already exist. */
 export function pushIssues(units: PrdUnit[], lang: Lang, standard: StandardId = "wcag", format: IssueFormat = "audit"): PushResult {
-  const { label, tag } = standardTag(standard);
+  const { label } = standardTag(standard);
   const existing = existingIssueTitles();
   const result: PushResult = { created: 0, skipped: 0, failed: 0, createdTitles: [], errors: [] };
   for (const u of units) {
@@ -151,9 +199,8 @@ export function pushIssues(units: PrdUnit[], lang: Lang, standard: StandardId =
       continue;
     }
     // Advisory units get the `recommendation` label so they can be triaged apart from
-    // real non-conformities (which they are not).
-    const labels = u.advisory ? ["accessibility", tag, "recommendation", u.severity] : ["accessibility", tag, u.severity];
-    const r = createIssue(title, issueBody(u, lang, standard, format), labels);
+    // real non-conformities (which they are not). Shared with the JSON export.
+    const r = createIssue(title, issueBody(u, lang, standard, format), issueLabels(u, standard));
     if (r.ok) {
       result.created++;
       result.createdTitles.push(title);

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 = "2.31.3";
+export const VERSION = "2.32.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,