ultra11y 2.32.0 → 3.0.0

package/skills/ultra11y/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: ultra11y
 description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibility and produce a dated auditor-conformance report, OR to AUTHOR/REVIEW accessible markup (native-HTML-first, ARIA last). An install-free engine (`node scripts/ultra11y.mjs`, no keys) runs 78 static checks tied to WCAG criteria — alt/lang/title, unlabeled fields, empty links/buttons, tables, headings, ARIA vocabulary, label-in-name, autocomplete — measured against the official W3C ACT corpus. The engine decides 3 of the 55 criteria; the AI agent adjudicates the 38 judgment ones from harvested evidence + a per-criterion decision protocol (`verify --manual`, gated, fannable via `orchestrate`), and the 14 rendering ones go to `scan` — never silently conforming. Library/SFC code is audited as RENDERED captures (`render --setup`); country standards are pluggable packs (`--standard rgaa`, `scan --sample`). check/verify reject invented non-conformities. Triggers: 'audit WCAG/a11y', 'make accessible', 'fix a11y', 'audit RGAA'."
-when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD 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."
+when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 2.32.0
+  version: 3.0.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -58,7 +58,7 @@ adjudicates. So the engine's clean run is a starting point, never a verdict —
 >    `<html lang>` → the active standard's default locale → English) — a scripted/CI
 >    fallback, not a substitute for passing `--lang` yourself.
 > 7. **Technical tokens stay in English, even in French prose.** In any French deliverable
->    you write (report commentary, PRD, GitHub issues, judgment verdicts), attribute/
+>    you write (report commentary, PRD, tracker tickets, judgment verdicts), attribute/
 >    element/role names and their values are code, not prose — never translate them:
 >    `aria-live` stays `aria-live` (never « région live »), same for `tabindex`, `alt`,
 >    `role="alert"`, landmark role names. The engine's own fr catalog follows this; match
@@ -90,7 +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/orchestrators.md` | Driving the engine from a workflow engine / non-GitHub CI: pinning, the six-step pipeline, exit codes, the ticket set as 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 |
@@ -99,7 +99,8 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 | `references/dynamic.md` | The `scan` tier: runtimes, probes, authenticated pages |
 | `references/scale.md` | Focusing an audit on a large repository |
 | `references/fix.md` · `references/correction.md` | Applying fixes, by priority, without regressions |
-| `references/prd.md` | The auditor block as a backlog, and GitHub issues |
+| `references/prd.md` | The auditor block as a backlog (markdown) |
+| `references/tickets.md` | Filing that backlog as tickets: GitHub, GitLab, Jira, and at which granularity |
 | `references/standards.md` · `references/packs.md` · `references/guidance.md` | Country standards, authoring a pack, implementation guidance |
 | `references/methodology.md` | Statuses, pass rate, severities, report format |
 | `references/cross-file.md` | `--graph`: imports and cross-file rules |
@@ -109,7 +110,7 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 
 - **"Audit / compliance report"** → `node scripts/ultra11y.mjs audit … --json`, then
   `report` (synthesis table + one **auditor conformance block** per NC criterion — same
-  block `prd`/`--gh-issues` use), then `check`; read **`references/audit.md`**.
+  block `prd` and `tickets` use), then `check`; read **`references/audit.md`**.
 - **"Code rendered by a library (DSFR, MUI…) or a `.vue`/`.svelte`/`.astro` SFC / avoid
   false negatives"** → audit the **produced HTML**, not the source template. Easiest:
   install the zero-touch **capture** harvester (`render --setup`) so your tests serialize
@@ -128,13 +129,17 @@ Domain knowledge first, then the tooling. Read the one that matches the question
   `audit --graph` resolves imports and applies cross-file rules (an icon-only component
   used without a name, an anchor target in another file…), no browser; read
   **`references/cross-file.md`**.
-- **"Generate the fix markdown / PRDs (→ GitHub issues)"** → `prd` (the SAME auditor
+- **"Generate the fix markdown / PRDs"** → `prd` (the SAME auditor
   conformance block `report`'s NC section renders — theme/criterion/test/WCAG+level/
   finding/expected/verification in the active standard's vocabulary — as a backlog);
   `--split criterion`, `--format doc` for a product-requirements doc, `--format remediation`
-  for the legacy dev backlog, `--gh-issues` for one issue per criterion (that block as the
-  body) or `--gh-single` for a single consolidated issue via the `gh` CLI); read
+  for the legacy dev backlog). It writes markdown only; read
   **`references/prd.md`**.
+- **"Open tickets / issues for this (GitHub · GitLab · Jira)"** → `tickets`, a separate
+  command that reads the audit and files it, writing no markdown. `--grain` picks what one
+  ticket is: per criterion (default), per page, per page+criterion, per file, or one
+  consolidated. De-dupe is by exact title, so re-running never duplicates. Always
+  `--dry-run` first; read **`references/tickets.md`**.
 - **"Plug or author a standards pack (RGAA & beyond), AI-ingest external rules"** →
   `--pack`/`.ultra11yrc.json` to load at runtime, `pack check` to gate it (the
   anti-hallucination guardrail), `pack scaffold` to start one; concrete before/after
@@ -273,7 +278,8 @@ node scripts/ultra11y.mjs verify --report audits/wcag-YYYY-MM-DD.md --in audits/
 node scripts/ultra11y.mjs verify --apply audits/ADJUDICATE.todo.json --in audits/audit-latest.json --out audits
 node scripts/ultra11y.mjs orchestrate --run audits                           # fan the judgment phases out (--eco for the sequential path)
 node scripts/ultra11y.mjs report --in audits/audit-latest.json --out audits  # → audits/wcag-YYYY-MM-DD.md
-node scripts/ultra11y.mjs prd    --in audits/audit-latest.json --gh-issues   # the same auditor block as a backlog
+node scripts/ultra11y.mjs prd     --in audits/audit-latest.json              # the same auditor block as a backlog
+node scripts/ultra11y.mjs tickets --in audits/audit-latest.json --dry-run    # file it: GitHub/GitLab/Jira
 node scripts/ultra11y.mjs check  --report audits/wcag-YYYY-MM-DD.md          # integrity gate
 node scripts/ultra11y.mjs criteria 1.4.3                                     # one success criterion (--list for all)
 node scripts/ultra11y.mjs fix "src/**/*.html" --write --iterate               # apply the safe codemods to a fixpoint
@@ -312,7 +318,7 @@ drive the judgment and content stages:
 4. **Re-audit** (on the render where relevant) and repeat.
 5. **Deliver the auditor block.** `report` (compliance doc: synthesis + one auditor
    conformance block — theme/criterion/test/WCAG+level/finding/expected/verification —
-   per NC criterion) and `prd` (the same blocks as an actionable backlog, `--gh-issues`
+   per NC criterion) and `prd` (the same blocks as an actionable backlog; `tickets`
    filing one GitHub issue per criterion with that identical block) are two views of the
    ONE building block, in the language of this conversation (pass `--lang` explicitly —
    Core rule 5).

package/skills/ultra11y/references/audit.md

@@ -42,7 +42,7 @@ non-conformity.
    → `audits/wcag-YYYY-MM-DD.md` (5 sections, see `references/methodology.md`); section 2
    renders one **auditor conformance block** per NC criterion (theme, criterion + official
    wording, test(s), WCAG mapping + level, finding, expected state, verification,
-   `file:line` occurrences), grouped by severity — the SAME block `prd` and `--gh-issues`
+   `file:line` occurrences), grouped by severity — the SAME block `prd` and `tickets`
    emit (see `references/prd.md`), so report and backlog never drift. For a country
    standard, add `--standard rgaa` (see `references/standards.md`). Pass `--lang` to match
    your conversation; without it, `auto` resolves the audit's `scope.langs` → the

package/skills/ultra11y/references/ci.md

@@ -53,6 +53,69 @@ run and an RGAA run coexist rather than overwriting each other. The Markdown rep
 through `check` before being uploaded, so CI cannot publish a report citing an invented
 criterion.
 
+## Adjudicating the judgment criteria in CI (`adjudicate`)
+
+Of the 55 WCAG 2.2 AA criteria the engine decides a handful; **38 are judgment calls**, and
+under RGAA **81 of 106** can only ever derive `manual`. Inside a coding agent the agent rules
+on them. In CI nobody does, so they stay « à évaluer » and the published conformance rate is
+partial by construction. `adjudicate` closes that — opt-in, in two modes.
+
+```yaml
+env:
+  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # the job's env, never an input
+steps:
+  - uses: maxgfr/ultra11y@v2
+    with:
+      standard: rgaa
+      adjudicate: api          # or `agent`
+```
+
+| input | default | |
+|---|---|---|
+| `adjudicate` | `none` | `api` · `agent` · `none` |
+| `adjudicate-model` | *(empty)* | model id for `api`; else `$ULTRA11Y_LLM_MODEL`, else the engine default |
+| `gate-adjudicated` | `false` | let a model-ruled NC fail the job |
+
+**`api`** sends the worklist to the Messages API in batches of 8 and folds the verdicts back.
+**`agent`** emits the worklist plus `orchestrate --eco`'s runbook and hands them to a
+`claude-code-action` run, then folds the same way. Both end in the **same fail-closed gate** an
+agent's verdicts pass through, so neither can assert a conformance the engine refuses.
+
+The difference between them is **evidence, not trust**. `judge` rules from the harvested
+evidence alone — capped at 30 items per criterion, snippets truncated — while the agent can
+open the cited files and read around them, which is what *link purpose **in context*** actually
+asks for. Expect the API mode to answer `manual` more often; that is it being honest, not
+broken. The metric that separates them is the count of criteria left to assess.
+
+**Both modes read `ANTHROPIC_API_KEY` from the job environment, never from an input** — a
+composite action's steps inherit it, and a secret that never travels through an input is one
+fewer secret to leak into a log. When the key is absent the tier **skips itself**: the job stays
+green, the report is still written, and the criteria stay « à évaluer ». That is not an edge
+case — it is precisely what a **fork's pull request** looks like, where secrets are never
+exposed. An adjudication that fails mid-flight (a rate-limited batch refuses the whole fold) is
+absorbed the same way, because losing the verdicts must never cost you the audit.
+
+**Cost is per run and does not amortise.** Roughly $0.20 for a WCAG run and $0.50 for RGAA at
+Sonnet pricing — the worklist is re-sent whole each time and no batch is large enough to earn
+prompt caching. On a busy repository that is real money per push; this belongs on the default
+branch or a schedule far more often than on every PR.
+
+**`gate-adjudicated` trades reproducibility for reach.** By default the gate re-audits the
+**source**, so the red/green is a pure function of the commit whatever a model said about it.
+Turn it on and the gate evaluates the adjudicated audit instead (`audit --in`), letting a
+model-ruled non-conformity fail the job — and accepting that two runs on the same commit may
+now disagree. Default off, deliberately.
+
+```sh
+# The same re-gate, outside the action:
+node scripts/ultra11y.mjs audit --in audits/audit-latest.json --fail-on blocking
+```
+
+`--in` re-gates an audit that already exists rather than computing one, which is the only way
+to gate on verdicts a second detection pass would not see. It refuses every flag that would
+change *what* is audited (`--since`, `--baseline`, paths…): a gate that silently dropped your
+scoping would be a gate nobody could trust.
+
 # The `--format` renderings
 
 A gate tells a developer *that* the build failed; it does not put the non-conformity **on the

package/skills/ultra11y/references/judgment.md

@@ -151,6 +151,14 @@ A rejected adjudication leaves `audit-latest.json` untouched.
 **Strictly opt-in.** With no key the command explains itself and exits 2; nothing else in the
 engine changes.
 
+**In the GitHub Action.** `adjudicate: api` runs exactly the command above; `adjudicate: agent`
+hands the same worklist — plus `orchestrate --eco`'s runbook and the adjudicator contract — to
+a `claude-code-action` run, then folds it with `verify --apply`. The agent mode exists because
+`judge` rules from the harvested evidence alone (30 items per criterion, snippets truncated)
+while an agent can open the cited files, which is what *link purpose in context* really needs.
+Both skip themselves when `ANTHROPIC_API_KEY` is absent from the job environment, and both
+absorb their own failure rather than taking the audit down with them. See `references/ci.md`.
+
 `--max` bounds the spend and says out loud which criteria it did not submit. It is **refused
 together with `--apply`**, before any call is made: the gate rejects an incomplete
 adjudication by design, so the pair could only ever bill you for a guaranteed failure. Drop

package/skills/ultra11y/references/methodology.md

@@ -54,7 +54,7 @@ content, so the verdict is provisional — confirm against the rendered DOM or r
 (C/NC/NA/to assess), (2) non-conformities by priority — one **auditor conformance block**
 per NC criterion (theme, criterion + official wording, test(s), WCAG mapping + level,
 finding, expected state, verification, `file:line` occurrences), the SAME block `prd` and
-`--gh-issues` emit (see `references/prd.md`), (3) conforming criteria, (4) justified
+`tickets` emit (see `references/tickets.md`), (3) conforming criteria, (4) justified
 not-applicable criteria, (5) criteria to assess manually.
 
 ## Worldwide: WCAG core, country standards as packs

package/skills/ultra11y/references/orchestrators.md

@@ -64,6 +64,13 @@ verdict with no justification, an NC with no resolvable `normativeRef`, a criter
 from the adjudication — each is refused by name, and the run stops. That is what keeps the
 final report defensible.
 
+**The shipped GitHub Action now runs this pipeline for you.** `adjudicate: agent` performs
+steps 2–4 — `verify --manual`, then `orchestrate --run audits --phase adjudicate --eco`, then a
+`claude-code-action` run pointed at the emitted `RUNBOOK.md`, then `verify --apply`. Reach for
+the raw pipeline above when your orchestrator is *not* GitHub Actions, or when you want to fan
+step 3 out across subagents rather than walk the eco path. Either way steps 1, 2, 4, 5 and 6
+stay deterministic, and only step 3 involves a model.
+
 ## The adjudication contract
 
 `ADJUDICATE.todo.json` declares what may be written into it, so the filler never has to read
@@ -102,34 +109,40 @@ the criterion in `residualRisks`, where the report declares it as a residual ris
 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
+## Filing findings on a tracker
 
-`--gh-issues` shells out to the `gh` CLI. For any other board, take the same items as JSON:
+`tickets` files into **GitHub, GitLab or Jira** directly (see `references/tickets.md`). For
+any other board — a native kanban, an internal tool — take the same items as JSON and file
+them yourself:
 
 ```sh
-$ENGINE prd --in "$RUN/audit-latest.json" --out "$RUN" --issues-json --lang en
-# → $RUN/issues-<date>.json
+$ENGINE tickets --in "$RUN/audit-latest.json" --out "$RUN" --lang en
+# → $RUN/issues-<date>.json   (writing the set files nothing; add --dry-run to be explicit)
 ```
 
+`--grain` decides what one item is: `criterion` (default), `page`, `page-criterion`,
+`single` or `file`. The envelope and the item shape are the same at every grain.
+
 ```jsonc
 {
   "tool": "ultra11y", "kind": "issues", "schemaVersion": 1,
-  "standard": "wcag", "date": "2026-08-12", "count": 4,
+  "standard": "wcag", "grain": "criterion", "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
+    "scope": { "grain": "criterion", "criteriaId": "1.1.1" },
     "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
+At the default grain, one issue per criterion, not per occurrence — a missing `alt` on forty
+images is one item with forty `occurrences`, not forty tickets. **De-dupe is on `title`**, so
+re-running files nothing twice; keep `--lang` stable across runs, since a criterion's wording
+is part of its title. `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
@@ -140,7 +153,8 @@ repo it does not own — write the run's intermediates out-of-tree and let only
 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.
+`dev`); `--root` relocates it. `audit`, `report`, `prd`, `tickets`, `verify` and `check`
+never touch it.
 
 ## Exit codes
 
@@ -149,7 +163,8 @@ dated report land in the project, if at all.
 | `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 |
+| `prd` | written | — (it writes markdown and files nothing) | usage / bad input |
+| `tickets` | filed, skipped, or nothing to file | a creation failed, the provider is unusable, or no page in scope | usage / bad input / past `--max-tickets` |
 
 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.

package/skills/ultra11y/references/prd.md

@@ -1,4 +1,4 @@
-# Auditor backlog (`prd`) + GitHub issues
+# Auditor backlog (`prd`)
 
 `prd` turns an `AuditResult` into an **auditor-legible conformance backlog**, grouped by WCAG
 success criterion (or, with `--standard <pack>`, by a country standard's criteria). It is the
@@ -6,15 +6,15 @@ success criterion (or, with `--standard <pack>`, by a country standard's criteri
 similar, they render the literal **same auditor block** (`src/auditor.ts` `renderAuditorUnit`,
 fed by the same `prdUnits`): `report`'s "Non-conformities by priority" section (§2) IS one of
 these blocks per NC criterion, grouped by severity exactly like the `prd` backlog and the
-`--gh-issues`/`--gh-single` issue bodies. Change the block once, all four deliverables change
-together — there is no separate "report wording" to keep in sync.
+ticket bodies `tickets` files (`references/tickets.md`). Change the block once, all four
+deliverables change together — there is no separate "report wording" to keep in sync.
+
+`prd` writes MARKDOWN and files nothing. Filing tickets is `tickets`.
 
 ```
 node scripts/ultra11y.mjs audit "src/**/*.tsx" --graph --json > audit.json
 node scripts/ultra11y.mjs prd --in audit.json                      # auditor backlog (default)
 node scripts/ultra11y.mjs prd --in audit.json --split criterion    # one file per criterion
-node scripts/ultra11y.mjs prd --in audit.json --gh-issues          # + one GitHub issue per criterion
-node scripts/ultra11y.mjs prd --in audit.json --gh-single          # + ONE consolidated GitHub issue (whole audit)
 node scripts/ultra11y.mjs prd --in audit.json --standard rgaa --lang fr   # rendered with the RGAA (fr) vocabulary
 node scripts/ultra11y.mjs prd --in audit.json --format doc         # product-requirements doc (epics/stories/AC)
 node scripts/ultra11y.mjs prd --in audit.json --format remediation # legacy dev fix-backlog
@@ -60,9 +60,8 @@ node scripts/ultra11y.mjs prd --in audit.json --format remediation # legacy dev
   grouped by theme, one **user story** per criterion, **Given/When/Then** acceptance criteria
   templated from the real SC title/techniques (anchored to W3C text), and the task list.
 - **`--split criterion`**: a `prd-<criterion>-YYYY-MM-DD.md` file per criterion (handy for batching).
-- The markdown is **always** written, even with `--gh-issues`.
 - **`--json`**: emits a machine-readable object instead of the file paths —
-  `{paths, units, gh?}` where `units` is the structured per-criterion backlog an agent can consume.
+  `{paths, units}` where `units` is the structured per-criterion backlog an agent can consume.
 
 ## Language of the prose (French deliverables)
 
@@ -72,33 +71,7 @@ attribute/element/role names and their values are code, not prose — `aria-live
 `aria-live` (never « région live »), same for `tabindex`, `alt`, `role="alert"`. Normative
 standard vocabulary (e.g. RGAA « lien d'évitement ») keeps its official French wording.
 
-## GitHub issues (`--gh-issues` / `--gh-single`, opt-in)
-
-- Uses the **`gh` CLI** (which handles its own auth) — **no** npm dependency, no key in
-  ultra11y.
-- **`--gh-issues` → one issue per criterion** (regardless of `--split`), stable title
-  `"[a11y] WCAG <sc> — <title>"` (or `"[a11y] <PACK> <id> — …"` under `--standard`), labels
-  `accessibility`, `wcag` (or the pack key), severity. The body is the **auditor conformance
-  block** (theme, criterion + wording, test(s), WCAG + level, finding, expected, verification,
-  `file:line` occurrences + definition site) — same as the default backlog, in the active
-  standard's vocabulary. `--format remediation` files the legacy dev body instead.
-- **`--gh-single` → ONE consolidated issue** for the whole audit, stable title
-  `"[a11y] WCAG — Accessibility audit"` (or `"[a11y] <PACK> — Accessibility audit"`). The body
-  is the full backlog **sectioned by severity** (🔴 blocking → 🟠 major → 🟡 minor), each
-  criterion carrying the auditor block. Labelled by the **most severe** criterion.
-- `--gh-single` **wins** if both flags are passed.
-- **De-dupe by title**: an existing issue (open or closed) is skipped, so re-running never
-  creates duplicates. The consolidated title carries **no count or date**, so it stays stable
-  across re-runs.
-- **Caveat — `--lang` changes the title**: the issue title embeds the localized criterion/pack
-  title (e.g. `[a11y] WCAG 1.4.3 — Contrast (Minimum)` vs `[a11y] WCAG 1.4.3 — Contraste (minimum)`).
-  Since de-dupe matches on the **exact title string**, re-running `prd --gh-issues` with a
-  **different `--lang`** than a previous run does **not** match the earlier issue and creates a
-  new one instead of updating it. Keep `--lang` consistent across re-runs against the same
-  repo, or accept the duplicate and close the stale one manually.
-- **Graceful degradation**: if `gh` is absent / unauthenticated, the command says so and exits
-  `0` — the markdown was still produced.
+## Filing these as tickets
 
-> `prd` reads the `AuditResult` produced by `audit` (ideally `--graph` for cross-file
-> coverage); it reuses the criterion titles, severities, messages, remediations and
-> `file:line` already computed.
+See **`references/tickets.md`**: `tickets` files the same auditor blocks into GitHub, GitLab
+or Jira, at a granularity you choose (per criterion, per page, per file, or one consolidated).

package/skills/ultra11y/references/tickets.md

@@ -0,0 +1,156 @@
+# Tracker tickets (`tickets`) — GitHub · GitLab · Jira
+
+`tickets` reads an `AuditResult` and **files it into a tracker**. It writes no Markdown.
+`prd` and `report` write Markdown and file nothing. That split is deliberate: you could
+previously not push without also producing a document, nor produce a document without
+risking a push.
+
+```
+node scripts/ultra11y.mjs audit "src/**/*.tsx" --graph --out audit.json
+
+node scripts/ultra11y.mjs tickets --in audit.json --dry-run                       # ALWAYS start here
+node scripts/ultra11y.mjs tickets --in audit.json                                 # one ticket per criterion
+node scripts/ultra11y.mjs tickets --in audit.json --grain page                    # one ticket per page
+node scripts/ultra11y.mjs tickets --in audit.json --grain page-criterion          # one per page × criterion
+node scripts/ultra11y.mjs tickets --in audit.json --grain single                  # one consolidated ticket
+node scripts/ultra11y.mjs tickets --in audit.json --grain file                    # one ticket per source file
+node scripts/ultra11y.mjs tickets --in audit.json --provider gitlab --standard rgaa --lang fr
+node scripts/ultra11y.mjs tickets --in audit.json --provider jira --max-tickets 20
+node scripts/ultra11y.mjs tickets --in audit.json --json                          # machine-readable plan + result
+node scripts/ultra11y.mjs tickets --in audit.json --out ./run                     # the ticket SET as JSON, for any other board
+```
+
+## Filing on a tracker ultra11y does not speak
+
+`--out <dir>` writes the tracker-agnostic set to `<dir>/issues-<date>.json` — a stable path a
+workflow engine can read without parsing a payload that also carries prose. It works at every
+grain, carries `occurrences[]` so a board with inline anchors needs nothing else, and writing
+it **files nothing**. `schemaVersion` is what lets a consumer pin. See
+`references/orchestrators.md`.
+
+The ticket **body** is the same auditor block `report` §2 and the `prd` backlog render
+(`src/auditor.ts`). There is one audit truth; the tracker sees exactly what the document says.
+
+## Granularity (`--grain`)
+
+What counts as ONE ticket. Default `criterion`.
+
+| Grain | One ticket is | Title |
+|---|---|---|
+| `criterion` | a criterion, across the whole scope | `[a11y] WCAG 1.1.1 — Non-text Content` |
+| `single` | the entire audit | `[a11y] WCAG — Accessibility audit` |
+| `page` | a page and every non-conformity on it | `[a11y] WCAG [page:accueil] — Accessibility audit` |
+| `page-criterion` | a criterion **on** a page | `[a11y] WCAG [page:accueil] 1.1.1 — Non-text Content` |
+| `file` | a source file | `[a11y] WCAG [file:src/Button.tsx] — Accessibility audit` |
+
+`WCAG` becomes the pack name under `--standard` (`[a11y] RGAA 1.1 — …`). A non-normative
+recommendation gets the ` (recommendation)` suffix and the `recommendation` label, so it is
+never triaged as a non-conformity.
+
+Pick by who does the work: `criterion` suits one person fixing one rule everywhere,
+`page`/`page-criterion` suit a team that owns pages, `file` suits a component owner,
+`single` suits "one tracking ticket, we'll work from the report".
+
+### The page grains keep the page honesty rules
+
+- A page whose real rendered DOM was audited (`basis: snapshot`) can be conforming. A page
+  assembled only by **source attribution** (`basis: attributed`) cannot: its ticket carries
+  the warning that absence of a finding is not conformity. See `references/pages.md`.
+- Findings **no page can claim** (shared components, files outside any route) get their OWN
+  ticket, `[a11y] WCAG [unattributed] — Accessibility audit`. They are never dropped and
+  never spread across pages — spreading would invent non-conformities.
+- With **no page in scope**, `--grain page` exits `1` and tells you to capture snapshots
+  (`render --e2e`) or scan a sample (`scan --sample`). It never files zero tickets in silence.
+
+A `file` ticket carries no conformance rate: a file is not a page.
+
+## De-duplication — the title IS the key
+
+There is no hidden marker, no state file, no id map. The **exact title** is the identity,
+compared client-side. That is the only key that survives all three trackers without
+persisting anything, and it means re-running never creates duplicates.
+
+Two consequences worth knowing before the first run:
+
+- **Upgrading from `--gh-issues` costs nothing.** The `criterion` and `single` titles are
+  byte-identical to the pre-v3 ones, so tickets already filed are recognised and skipped.
+- **`--lang` forks the title** for grains carrying a criterion wording (`[a11y] WCAG 1.4.3 —
+  Contrast (Minimum)` vs `— Contraste (minimum)`). Keep `--lang` consistent across runs
+  against the same tracker. The FRAME is never localized: "Accessibility audit" stays English
+  at `--lang fr`, precisely so it cannot fork.
+- Renaming a snapshot directory changes the page id, hence the title. Same caveat.
+
+If the tracker cannot be listed (permissions, rate limit), the run degrades to **create**
+rather than dropping the backlog, and says the skip count is unverified.
+
+## Providers and transports
+
+`--provider auto` (default) reads `ULTRA11Y_TICKET_PROVIDER`, then `.ultra11yrc.json`, then
+the `origin` git remote. **Jira is never auto-detected** — it owns no git remote — so name it.
+
+`--transport auto` (default) prefers the CLI, which owns its own auth so ultra11y never holds
+a token; it falls back to REST when only a token is available, and says what BOTH were
+missing when neither works.
+
+**REST is not redundant with the CLI.** `gh` ships on GitHub-*hosted* runners only: container
+jobs, self-hosted runners and every non-GitHub CI have a token and no binary. GHES works
+through `GITHUB_API_URL`, which Actions sets for you.
+
+| | GitHub | GitLab | Jira |
+|---|---|---|---|
+| CLI | `gh` | `glab` | — (REST only) |
+| token | `GH_TOKEN` → `GITHUB_TOKEN` | `GITLAB_TOKEN` | `JIRA_EMAIL`+`JIRA_API_TOKEN` (Cloud) or `JIRA_TOKEN` (Server/DC) |
+| target | `GITHUB_REPOSITORY` → `ULTRA11Y_GITHUB_REPO` → git remote | `CI_PROJECT_ID` → `ULTRA11Y_GITLAB_PROJECT` → git remote | `ULTRA11Y_JIRA_PROJECT` (the project KEY) |
+| API base | `GITHUB_API_URL` | `CI_API_V4_URL` | `ULTRA11Y_JIRA_URL` |
+
+Also for Jira: `ULTRA11Y_JIRA_ISSUE_TYPE` (default `Task`) and `ULTRA11Y_JIRA_API` (`2`|`3`).
+
+**Credentials live in the environment only.** A `token` / `apiToken` / `password` / `secret`
+key anywhere in the config's `tickets` block is a hard error (exit 2) — `.ultra11yrc.json` is
+committed, so a token in it is a leaked token.
+
+### Per-tracker specifics
+
+- **GitHub** — the issues endpoint also returns pull requests; they are filtered out, so a PR
+  title can never suppress a real ticket. A `422` on labels retries unlabelled rather than
+  losing the ticket. Bodies are clamped to 65 536 characters with a pointer to the PRD.
+- **GitLab** — `CI_JOB_TOKEN` **cannot create issues**; when that is the token in play, the
+  failure says so instead of returning a bare 403. Missing labels are auto-created by GitLab.
+- **Jira** — API v3 requires ADF, not Markdown, so the body is rendered as one ADF paragraph
+  per line: the text is faithful, the formatting is not. Set `ULTRA11Y_JIRA_API=2` for the v2
+  endpoint (plain string) on Server/DC. Severity maps to priority (Highest/High/Low); a
+  project that has not configured `priority` or `labels` gets a retry without them. Every
+  ticket carries a constant `ultra11y` label so the de-dupe JQL can bound its search — the
+  JQL only narrows candidates, the exact title match still decides.
+
+## Guards
+
+- **`--max-tickets`** (default 200) — `page-criterion` on a large RGAA audit runs to the
+  hundreds, and a creation is hard to undo. Past the limit the command **refuses** and names
+  the escape hatch. It never truncates silently.
+- **`--dry-run`** — resolves the transport, lists what exists, prints create-vs-skip, creates
+  nothing, exits 0. Run it first, every time.
+- **Exit codes** — `0` filed/skipped/nothing to file · `1` at least one creation failed, the
+  provider is unusable, or `--grain page*` with no page in scope · `2` usage, config, or the
+  `--max-tickets` guard.
+
+An unusable provider exits **1**, not 0. A push command that files nothing and reports green
+is a silent failure.
+
+## Configuration
+
+```jsonc
+// .ultra11yrc.json — flags always win
+{ "tickets": { "provider": "gitlab", "grain": "page", "maxTickets": 100 } }
+```
+
+## Migrating from `prd --gh-issues`
+
+| Before | Now |
+|---|---|
+| `prd --in a.json --gh-issues` | `tickets --in a.json --provider github --grain criterion` |
+| `prd --in a.json --gh-single` | `tickets --in a.json --provider github --grain single` |
+| `prd --in a.json --out d --issues-json` | `tickets --in a.json --out d --grain criterion` |
+
+All three old flags now exit `2` and print the replacement. `prd` still writes the same Markdown;
+its `--json` payload no longer carries a `gh` key.