ultra11y 2.31.2 → 2.32.0

package/src/adjudicate.ts

@@ -77,6 +77,18 @@ export interface AdjudicationItem {
   justification: string; // REQUIRED for C and NA
   reason: string | null; // REQUIRED for a still-`manual` verdict ("needs-rendered-dom" | "undecidable")
   findings: AgentFinding[]; // REQUIRED (≥1, groundable, each with a normativeRef) for NC
+  // What the agent CLEARED, for a C (or ruled out of scope, for an NA). The mirror image of
+  // `findings`, and required for the same reason: without a slot to cite in, a conforming
+  // verdict was pure prose, and the gate could only ever check that the prose was non-empty
+  // — so a model answering "C" to everything with the justification "x" passed, and the
+  // report published 91 conformant criteria nobody had assessed.
+  //
+  // Each citation must ground (the file/line/snippet must resolve, exactly like an NC
+  // finding) AND match one of this item's own `evidence` anchors by file+line — that pairing
+  // is what turns "cite something real" into "cite the evidence you were shown". When the
+  // harvester found no evidence at all there is nothing to clear, and the honest verdicts
+  // are `manual` or `NA`, never `C`.
+  citations?: Evidence[];
   // Non-normative good practices the agent noted on this criterion — folded back into the
   // audit as ADVISORY findings (grounded exactly like an NC finding, but never affecting
   // status: they cannot flip the criterion to NC nor enter conformancePct). Optional.
@@ -90,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
@@ -378,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`).
@@ -421,18 +508,38 @@ 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
   // means every pack criterion that derives `manual` — the pack's own granularity, which is
   // what the worklist was built at.
   const packMode = !isCore(adj.standard);
+  const open = new Set<string>();
   if (packMode) {
     for (const pc of derivePackResults(audit, adj.standard)) {
-      if (pc.status === "manual" && !byId.has(pc.id)) issues.push(`criterion ${pc.id}: missing from the adjudication (coverage gap)`);
+      if (pc.status !== "manual") continue;
+      open.add(pc.id);
+      if (!byId.has(pc.id)) issues.push(`criterion ${pc.id}: missing from the adjudication (coverage gap)`);
     }
   } else {
-    for (const r of audit.residualRisks) if (!byId.has(r.criteriaId)) issues.push(`criterion ${r.criteriaId}: missing from the adjudication (coverage gap)`);
+    for (const r of audit.residualRisks) {
+      open.add(r.criteriaId);
+      if (!byId.has(r.criteriaId)) issues.push(`criterion ${r.criteriaId}: missing from the adjudication (coverage gap)`);
+    }
+  }
+
+  // …and the other direction. The coverage check above only proves every open criterion was
+  // ruled on; it says nothing about a SURPLUS item. That mattered: the fold resolved a
+  // criterion by id against the whole audit, so an extra `{criteriaId: "3.1.1", verdict:
+  // "C"}` overwrote a non-conformity the deterministic engine had decided — no finding, no
+  // citation, no normativeRef. Adjudication may only ever decide what the engine left open.
+  for (const it of adj.items) {
+    if (!open.has(it.criteriaId)) {
+      issues.push(`criterion ${it.criteriaId}: not open for adjudication — the engine already decided it, or it is not part of ${adj.standard}`);
+    }
   }
 
   // Per-item fail-closed validation.
@@ -443,6 +550,36 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
       issues.push(`criterion ${it.criteriaId}: unadjudicated (verdict is null)`);
     } else if (v === "C" || v === "NA") {
       if (!it.justification || !it.justification.trim()) issues.push(`criterion ${it.criteriaId}: a ${v} verdict requires a justification`);
+      // A clearing verdict is gated exactly like an accusing one. Before this, the only
+      // check was "the justification is a non-empty string", so `"x"` cleared a criterion —
+      // and a model answering C to everything published a conformance nobody had assessed.
+      const cites = it.citations ?? [];
+      if (it.evidence.length === 0) {
+        // Nothing was harvested for this criterion, so there is nothing the agent could have
+        // read to clear it. `NA` is still legitimate (the honest "no element in scope is
+        // concerned"); `C` is not — it must stay `manual` and be ruled on against the
+        // criterion's own tests, from a rendered capture or by hand.
+        if (v === "C") {
+          issues.push(
+            `criterion ${it.criteriaId}: a C verdict needs evidence to cite, and none was harvested for this criterion — record "manual" (reason "undecidable"), or "NA" if nothing in scope is concerned`,
+          );
+        }
+      } else if (cites.length === 0) {
+        issues.push(
+          `criterion ${it.criteriaId}: a ${v} verdict must cite at least one of the ${it.evidence.length} evidence item(s) it was shown (citations: [{file, line, …}])`,
+        );
+      } else {
+        // Each citation must name evidence THIS item carried. Grounding alone would only
+        // prove the anchor exists somewhere in the tree; the pairing proves the agent ruled
+        // on what it was actually given.
+        const anchors = new Set(it.evidence.map((e) => `${e.file}:${e.line}`));
+        for (const c of cites) {
+          if (!anchors.has(`${c.file}:${c.line}`)) {
+            issues.push(`criterion ${it.criteriaId}: citation ${c.file}:${c.line} is not among this criterion's harvested evidence (fabricated?)`);
+          }
+          groundInputs.push({ file: c.file, line: c.line, selector: c.selector, snippet: c.snippet });
+        }
+      }
     } else if (v === "NC") {
       if (!it.findings || it.findings.length === 0) issues.push(`criterion ${it.criteriaId}: an NC verdict requires at least one groundable finding`);
       for (const f of it.findings ?? []) {
@@ -461,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
@@ -471,7 +611,8 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
     for (const rec of it.recommendations ?? []) groundInputs.push({ file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
   }
 
-  // Content-level grounding of every agent NC finding + every recommendation.
+  // Content-level grounding of every agent NC finding, every C/NA citation, and every
+  // recommendation — the same check, whichever direction the verdict points.
   const grounding = groundItems(groundInputs, { cwd: opts.cwd });
   for (const gi of grounding.issues) issues.push(gi);
 
@@ -596,7 +737,12 @@ function recomputeTallies(a: AuditResult): void {
     g.na = inG.filter((c) => c.status === "NA").length;
     g.manual = inG.filter((c) => c.status === "manual").length;
   }
-  const decided = a.criteria.filter((c) => c.status === "C" || c.status === "NC");
+  // `conformancePct` is labelled everywhere as the AUTOMATIC static-check pass rate, so an
+  // agent's C must not enter it — otherwise one adjudication pass turns a judgement into a
+  // machine-verified number, which is exactly the claim the label denies. An agent NC does
+  // count: a non-conformity is evidenced (grounded finding + normativeRef) and reporting
+  // it lowers the rate, which is the safe direction.
+  const decided = a.criteria.filter((c) => c.status === "NC" || (c.status === "C" && c.decidedBy !== "agent"));
   const conform = decided.filter((c) => c.status === "C").length;
   a.conformancePct = decided.length === 0 ? 100 : Math.round((conform / decided.length) * 100);
 }
@@ -611,13 +757,13 @@ const T = {
     intro:
       "Pour CHAQUE critère, lisez les évidences ci-dessous (extraites de la source auditée) et attribuez un verdict dans `ADJUDICATE.todo.json` (champ `verdict`) :",
     verdicts: [
-      "- `C` — conforme (renseignez `justification`) ;",
+      "- `C` — conforme (renseignez `justification` ET `citations[]` : les évidences que vous avez levées, `file`/`line` recopiés depuis la liste du critère) ;",
       "- `NC` — non conforme (ajoutez au moins un `findings[]` : file/line/message, avec un `snippet` groundable ET un `normativeRef` citant le test précis échoué) ;",
-      "- `NA` — non applicable (renseignez `justification`) ;",
+      "- `NA` — non applicable (renseignez `justification` ; si des évidences sont présentées, citez-les aussi dans `citations[]` pour dire lesquelles sortent du périmètre) ;",
       "- `manual` — indécidable statiquement (renseignez `reason` : `needs-rendered-dom` → `scan`, ou `undecidable`).",
     ],
-    rule: "> Ne signalez une NC que si un test précis du référentiel actif échoue — citez-le (`normativeRef`). Une bonne pratique sans test normatif est une recommandation (`recommendations[]`, non normative). Une simple préoccupation UX n'est ni l'un ni l'autre.",
-    then: "Puis : `ultra11y verify --apply ADJUDICATE.todo.json --in <audit.json> --out <dir>` (échoue si un verdict manque une justification/finding/reason).",
+    rule: "> Ne signalez une NC que si un test précis du référentiel actif échoue — citez-le (`normativeRef`). Une bonne pratique sans test normatif est une recommandation (`recommendations[]`, non normative). Une simple préoccupation UX n'est ni l'un ni l'autre.\n>\n> Symétriquement, un `C` se cite comme une NC : il faut nommer dans `citations[]` les évidences levées. **Un critère présenté sans aucune évidence ne peut pas être `C`** — c'est `manual` (`undecidable`), ou `NA` si rien n'est concerné.",
+    then: "Puis : `ultra11y verify --apply ADJUDICATE.todo.json --in <audit.json> --out <dir>` (échoue si un verdict manque sa justification, ses citations, son finding ou sa raison).",
     evidence: "Évidences",
     none: "(aucune évidence automatique — décidez depuis la source, ou laissez `manual` avec une raison)",
     questions: "À vérifier manuellement",
@@ -635,13 +781,13 @@ const T = {
     title: "# Criteria adjudication (ultra11y)",
     intro: "For EACH criterion, read the evidence below (harvested from the audited source) and set a verdict in `ADJUDICATE.todo.json` (field `verdict`):",
     verdicts: [
-      "- `C` — conformant (fill `justification`);",
+      "- `C` — conformant (fill `justification` AND `citations[]`: the evidence you cleared, `file`/`line` copied from the criterion's own list);",
       "- `NC` — non-conformant (add at least one `findings[]`: file/line/message, with a groundable `snippet` AND a `normativeRef` citing the precise failed test);",
-      "- `NA` — not applicable (fill `justification`);",
+      "- `NA` — not applicable (fill `justification`; when evidence is presented, cite it too in `citations[]` to say which items are out of scope);",
       "- `manual` — not statically decidable (fill `reason`: `needs-rendered-dom` → `scan`, or `undecidable`).",
     ],
-    rule: "> Report NC only if a precise test of the active standard fails — cite it (`normativeRef`). A good practice without a normative test is a recommendation (`recommendations[]`, non-normative). A purely UX concern is neither.",
-    then: "Then: `ultra11y verify --apply ADJUDICATE.todo.json --in <audit.json> --out <dir>` (fails if any verdict lacks its justification/finding/reason).",
+    rule: "> Report NC only if a precise test of the active standard fails — cite it (`normativeRef`). A good practice without a normative test is a recommendation (`recommendations[]`, non-normative). A purely UX concern is neither.\n>\n> A `C` is cited the same way an NC is: name the evidence you cleared in `citations[]`. **A criterion presented with no evidence at all cannot be `C`** — record `manual` (`undecidable`), or `NA` if nothing in scope is concerned.",
+    then: "Then: `ultra11y verify --apply ADJUDICATE.todo.json --in <audit.json> --out <dir>` (fails if any verdict lacks its justification, citations, finding or reason).",
     evidence: "Evidence",
     none: "(no automatic evidence — decide from source, or leave `manual` with a reason)",
     questions: "To verify manually",
@@ -847,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/auditor.ts

@@ -11,7 +11,7 @@ import type { AuditResult, Finding, Lang, Severity } from "./types.js";
 import { prdUnits, partitionUnits, effortOf, guidanceFor, guidanceExampleBlock, acceptanceCriteria, type PrdUnit, type PrdFile } from "./prd.js";
 import { getSC, guidelineTitle, principleTitle, techniques as scTechniques } from "./wcag.js";
 import { resolveMessage, resolveRemediation, resolveNote } from "./messages.js";
-import { type StandardId, isCore, loadPack, standardLabel, themeName, vocabularyFor } from "./standards/index.js";
+import { type StandardId, isCore, loadPack, packTestIds, standardLabel, themeName, vocabularyFor } from "./standards/index.js";
 
 const SEV_ORDER: Severity[] = ["bloquant", "majeur", "mineur"];
 const ICON: Record<Severity, string> = { bloquant: "🔴", majeur: "🟠", mineur: "🟡" };
@@ -186,7 +186,7 @@ export function renderAuditorUnit(unit: PrdUnit, standard: StandardId, lang: Lan
     const pc = pack.criteria.find((c) => c.id === unit.criteriaId);
     if (pc) out.push(`**${v.theme}** : ${pc.theme}. ${themeName(pack, pc.theme, lang) ?? ""}`.trimEnd());
     out.push(`**${v.criterion}** : ${unit.criteriaId} — ${unit.title}`);
-    const testNums = pc?.tests ? Object.keys(pc.tests).map((k) => `${unit.criteriaId}.${k}`) : [];
+    const testNums = packTestIds(pack, unit.criteriaId);
     if (testNums.length) out.push(`**${v.test}(s)** : ${testNums.join(" · ")}`);
     if (unit.refs.length) out.push(`**WCAG** : ${unit.refs.map((sc) => `${sc}${scLevel(sc)}`).join(" · ")}`);
   }

package/src/cli.ts

@@ -1,4 +1,4 @@
-import { realpathSync, writeFileSync, mkdirSync, existsSync, readFileSync, appendFileSync } from "node:fs";
+import { realpathSync, writeFileSync, mkdirSync, existsSync, readFileSync, appendFileSync, copyFileSync } from "node:fs";
 import { join, relative, sep, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { VERSION, type Lang, type AuditResult, type DynamicResult, type SampleConfig, type Severity } from "./types.js";
@@ -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",
@@ -1157,14 +1161,30 @@ async function cmdPages(p: ParsedArgs): Promise<number> {
   const split = p.flags.split === "page";
   const outDir = typeof p.flags.out === "string" && p.flags.out ? (p.flags.out as string) : undefined;
 
-  // The screenshot lives beside the snapshot, on disk. Reference it relatively from wherever
-  // the file lands — a copy would double the repo's weight for no gain, and an absolute path
-  // would break the moment the report is read anywhere else.
-  const shotsFor = (fileDir: string): Map<string, string> => {
+  // The screenshot lives beside the snapshot, in `.ultra11y/pages/`. Referencing it
+  // relatively is right when the report is read in place, and wrong the moment the report
+  // DIRECTORY travels on its own: CI uploads `audits/` as the artifact, and a
+  // `../../.ultra11y/…` link then points outside it — every image broken in the artifact
+  // the reviewer actually opens. So when writing to a directory we copy each screenshot
+  // into it (`assets/<page-id>.png`) and link that; stdout mode keeps the relative
+  // reference, since there is no output directory to be self-contained.
+  const shotOf = (id: string): string => join(PAGES_DIR, id, "screen.png");
+  const shotsRelative = (fileDir: string): Map<string, string> => {
     const m = new Map<string, string>();
     for (const pg of derived) {
-      const shot = join(PAGES_DIR, pg.id, "screen.png");
-      if (existsSync(shot)) m.set(pg.id, relative(fileDir, shot).split("\\").join("/"));
+      if (existsSync(shotOf(pg.id))) m.set(pg.id, relative(fileDir, shotOf(pg.id)).split("\\").join("/"));
+    }
+    return m;
+  };
+  const shotsCopiedInto = (dir: string): Map<string, string> => {
+    const m = new Map<string, string>();
+    const assets = join(dir, "assets");
+    for (const pg of derived) {
+      const src = shotOf(pg.id);
+      if (!existsSync(src)) continue;
+      mkdirSync(assets, { recursive: true });
+      copyFileSync(src, join(assets, `${pg.id}.png`));
+      m.set(pg.id, `./assets/${pg.id}.png`);
     }
     return m;
   };
@@ -1172,19 +1192,19 @@ async function cmdPages(p: ParsedArgs): Promise<number> {
   if (!outDir) {
     // No --out: stream the whole document to stdout. Screenshots are resolved against the
     // CWD, which is where a reader piping this would sit.
-    console.log(renderPagesDocument(result, derived, { standard, lang, screenshots: shotsFor(".") }));
+    console.log(renderPagesDocument(result, derived, { standard, lang, screenshots: shotsRelative(".") }));
     return 0;
   }
 
   mkdirSync(outDir, { recursive: true });
   if (!split) {
     const file = join(outDir, `pages-${result.date}.md`);
-    writeFileSync(file, `${renderPagesDocument(result, derived, { standard, lang, screenshots: shotsFor(outDir) })}\n`);
+    writeFileSync(file, `${renderPagesDocument(result, derived, { standard, lang, screenshots: shotsCopiedInto(outDir) })}\n`);
     console.log(file);
     return 0;
   }
 
-  const shots = shotsFor(outDir);
+  const shots = shotsCopiedInto(outDir);
   // Sheets are `page-<id>.md`, never `<id>.md`: a page whose id is `index` — the ordinary id
   // for an `index.html` target — would otherwise be written to the same path as the index and
   // one of the two would silently vanish. The prefix makes the collision impossible by
@@ -1541,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;
@@ -1570,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).
@@ -2060,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/data/standards/rgaa.json

@@ -1258,7 +1258,8 @@
       "wcag": ["1.4.2"],
       "appliesTo": {
         "ruleIds": ["autoplay-media", "axe:no-autoplay-audio"]
-      }
+      },
+      "judgment": true
     },
     {
       "id": "4.11",
@@ -1897,7 +1898,8 @@
       "wcag": ["3.1.1"],
       "appliesTo": {
         "ruleIds": ["axe:html-lang-valid", "lang-invalid"]
-      }
+      },
+      "judgment": true
     },
     {
       "id": "8.5",
@@ -1933,7 +1935,8 @@
       "wcag": ["2.4.2"],
       "appliesTo": {
         "ruleIds": []
-      }
+      },
+      "judgment": true
     },
     {
       "id": "8.7",
@@ -3327,7 +3330,8 @@
       "wcag": ["1.1.1", "1.3.1", "1.3.2", "2.4.1", "2.4.3", "3.1.1", "4.1.2"],
       "appliesTo": {
         "ruleIds": []
-      }
+      },
+      "judgment": true
     },
     {
       "id": "13.4",
@@ -3349,7 +3353,8 @@
       "wcag": ["1.1.1", "1.3.1", "1.3.2", "2.4.1", "2.4.3", "3.1.1", "4.1.2"],
       "appliesTo": {
         "ruleIds": []
-      }
+      },
+      "judgment": true
     },
     {
       "id": "13.5",

package/src/data/wcag-universe.json

@@ -2,7 +2,7 @@
   "wcagVersion": "2.2",
   "source": "https://www.w3.org/TR/WCAG22/",
   "criteriaSource": "https://github.com/w3c/wcag",
-  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-11 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
+  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-12 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
   "criteria": [
     {
       "id": "1.1.1",

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);