@binclusive/a11y 0.1.0

package/src/runner/providers/openai.ts

@@ -0,0 +1,191 @@
+/**
+ * A second ship-in-the-box {@link Provider} — OpenAI's Chat Completions API over
+ * global `fetch` (epic #2083, issue #2318).
+ *
+ * The {@link Provider} interface (`../provider`) is the BYO seam: nothing in the
+ * runner names a vendor. This module is the OpenAI twin of `./anthropic.ts` —
+ * ONE more concrete default so a customer with `LLM_PROVIDER=openai` + a bare
+ * `LLM_API_KEY` drives the AI lane end to end, no vendor SDK, no extra install.
+ * It maps the vendor-neutral {@link ProviderRequest} onto the Chat Completions
+ * request body and the reply back onto {@link ProviderResponse} (crucially its
+ * {@link TokenUsage} — the runner's token ceiling is only enforceable because
+ * usage is reported).
+ *
+ * Two vendor-shape differences from Anthropic, and nothing else changes:
+ *   - the system prompt is a leading `role: "system"` message, not a top-level
+ *     field; and
+ *   - usage is `prompt_tokens` / `completion_tokens`, the reply text is
+ *     `choices[].message.content`.
+ *
+ * Per the {@link Provider} contract, this SURFACES transport failures by
+ * REJECTING: a non-2xx, a malformed body, or a network error throws. The runner
+ * catches a rejected pass and records it as a non-fatal error, so a provider
+ * that throws degrades the run to "no agent findings for that pass", never a
+ * crash — the AI lane stays non-blocking.
+ *
+ * A HANG is a failure a `throw` alone does not cover, so the `fetch` is bounded
+ * by an {@link AbortController} + timeout (mirroring `./anthropic.ts`). A stalled
+ * provider — network stall, provider outage, no response — is aborted at the
+ * bound and surfaced as a rejection like any other transport failure, so the
+ * runner records the pass as errored and keeps going. Without this, a single hung
+ * request would hang the whole CI job, turning the non-blocking soft-degrade into
+ * a hard block on the customer's PR pipeline (issue #2192).
+ */
+import type { Provider, ProviderRequest, ProviderResponse, TokenUsage } from "../provider";
+
+/**
+ * The default model for the low-cap advisory CI lane: a fast, cost-appropriate
+ * model. Overridable via the provider config (wired to `LLM_MODEL`), so dialing
+ * up to a stronger model is one env var, not a code change.
+ */
+export const DEFAULT_OPENAI_MODEL = "gpt-4o-mini";
+
+const DEFAULT_BASE_URL = "https://api.openai.com";
+/** A pass is one short suggestion; cap output when the caller doesn't ask. */
+const DEFAULT_MAX_OUTPUT_TOKENS = 1024;
+
+/**
+ * The safe default wall-clock bound on one provider request (issue #2192). A
+ * low-cap advisory completion (≤ {@link DEFAULT_MAX_OUTPUT_TOKENS} output tokens
+ * on a fast model) returns in seconds; 60s leaves generous headroom for a slow
+ * healthy response while still bounding a genuine hang, so a stalled request
+ * aborts and degrades the AI lane softly instead of stalling CI. Override via
+ * {@link OpenAIProviderConfig.timeoutMs} (wired to `LLM_TIMEOUT_MS`).
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+
+export interface OpenAIProviderConfig {
+  /** The customer's OpenAI key (from `LLM_API_KEY`). Never logged. */
+  readonly apiKey: string;
+  /** Model id. Defaults to {@link DEFAULT_OPENAI_MODEL}. */
+  readonly model?: string;
+  /** Injectable for tests / alternate gateways. Defaults to `globalThis.fetch`. */
+  readonly fetchImpl?: typeof fetch;
+  /** Override the API origin (Azure OpenAI / self-hosted gateway / proxy). Defaults to OpenAI. */
+  readonly baseUrl?: string;
+  /**
+   * Wall-clock bound on one request before it aborts (from `LLM_TIMEOUT_MS`).
+   * Defaults to {@link DEFAULT_REQUEST_TIMEOUT_MS}. A non-finite or non-positive
+   * value falls back to the default — a bad knob can't disable the bound and
+   * re-open the hang hole (issue #2192).
+   */
+  readonly timeoutMs?: number;
+}
+
+/** OpenAI's `chat/completions` response, narrowed at the boundary — never trusted raw. */
+interface OpenAIResponseBody {
+  readonly choices?: ReadonlyArray<{ readonly message?: { readonly content?: string | null } }>;
+  readonly usage?: { readonly prompt_tokens?: number; readonly completion_tokens?: number };
+}
+
+/**
+ * The output-token request field for a given model id. OpenAI's reasoning-model
+ * families (`o1` / `o3` / `o4` … and `gpt-5`) REJECT the legacy `max_tokens`
+ * field with a 400 and require `max_completion_tokens`; the `gpt-4o` line and
+ * older still take `max_tokens`. Pick by id so a customer who points `LLM_MODEL`
+ * at a reasoning model gets a well-formed request instead of a soft-degrade on
+ * every pass. An unrecognized id falls through to `max_tokens` — the field the
+ * widest set of models (and the shipped default) accept, so an ambiguous id
+ * still runs (issue #2318).
+ */
+function outputTokenField(model: string): "max_tokens" | "max_completion_tokens" {
+  return /^(o[1-9]|gpt-5)/i.test(model) ? "max_completion_tokens" : "max_tokens";
+}
+
+/** Concatenate the message content of the returned choices into one string. */
+function textOf(body: OpenAIResponseBody): string {
+  if (!Array.isArray(body.choices)) return "";
+  return body.choices
+    .map((choice) => choice.message?.content)
+    .filter((content): content is string => typeof content === "string")
+    .join("");
+}
+
+/**
+ * A single reported token count, or `+Infinity` when the body reports it absent,
+ * non-numeric, `NaN`, or negative. OpenAI always reports both counts; a body
+ * that doesn't is malformed, so we parse-don't-validate at the boundary and map
+ * the bad count to a fail-closed sentinel rather than silently charging 0. The
+ * ledger meters `+Infinity` as at-or-over the ceiling, stopping the lane instead
+ * of letting a malformed response run past the cap (issue #2169).
+ */
+function meterableCount(raw: number | undefined): number {
+  return typeof raw === "number" && Number.isFinite(raw) && raw >= 0 ? raw : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * The token usage the runner meters against the per-PR ceiling — parsed from the
+ * untrusted body, never read raw. A missing or malformed count maps to `+Infinity`
+ * (see {@link meterableCount}) so the ceiling fails closed on a bad provider
+ * response rather than under-counting toward a silent overspend.
+ */
+function usageOf(body: OpenAIResponseBody): TokenUsage {
+  return {
+    inputTokens: meterableCount(body.usage?.prompt_tokens),
+    outputTokens: meterableCount(body.usage?.completion_tokens),
+  };
+}
+
+/**
+ * Build the ship-in-the-box OpenAI {@link Provider}. Inject into the runner's
+ * `RunInput.provider`; the harness meters every `complete` call against the token
+ * ceiling. Rejects on any transport / shape failure — the runner treats that as a
+ * non-fatal, recorded pass error.
+ */
+export function createOpenAIProvider(config: OpenAIProviderConfig): Provider {
+  const model = config.model ?? DEFAULT_OPENAI_MODEL;
+  const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+  const endpoint = `${config.baseUrl ?? DEFAULT_BASE_URL}/v1/chat/completions`;
+  const timeoutMs =
+    typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0
+      ? config.timeoutMs
+      : DEFAULT_REQUEST_TIMEOUT_MS;
+
+  return {
+    async complete(request: ProviderRequest): Promise<ProviderResponse> {
+      // Bound the whole exchange — connect AND body read: a hang at either stage
+      // aborts at the timeout and surfaces as a rejection, closing the
+      // non-blocking hole a bare `throw` can't (#2192). We own this controller,
+      // so any abort here IS our timeout. The signal cancels an in-flight body
+      // read too, so a stalled response can't slip past a resolved-headers fetch.
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImpl(endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${config.apiKey}`,
+          },
+          body: JSON.stringify({
+            model,
+            // Reasoning models require `max_completion_tokens`; the gpt-4o line
+            // and older take `max_tokens`. Pick the field by id (outputTokenField).
+            [outputTokenField(model)]: request.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+            // OpenAI carries the system framing as a leading message, not a
+            // top-level field (the one shape divergence from Anthropic).
+            messages: [
+              ...(request.system !== undefined ? [{ role: "system", content: request.system }] : []),
+              ...request.messages.map((m) => ({ role: m.role, content: m.content })),
+            ],
+          }),
+          signal: controller.signal,
+        });
+
+        if (!response.ok) {
+          // Surface as a rejection — the runner records the pass as a non-fatal
+          // error and keeps going. The key never reaches the message.
+          throw new Error(`OpenAI API returned HTTP ${response.status}`);
+        }
+
+        const body = (await response.json()) as OpenAIResponseBody;
+        return { text: textOf(body), usage: usageOf(body) };
+      } catch (error) {
+        if (controller.signal.aborted) throw new Error(`OpenAI request timed out after ${timeoutMs}ms`);
+        throw error;
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}

package/src/runner/reasoner.ts

@@ -0,0 +1,73 @@
+/**
+ * The reasoning seam — the AI-lane content the harness does NOT own.
+ *
+ * The harness drives ONE pass per deterministic finding and hands the reasoner a
+ * metered provider and a capped lookup tool. What the reasoner DOES with them —
+ * the prompt/skills (#2096), the code-graph queries (#2097), and the enrich +
+ * discover logic that turns a model response into agent findings (#2098) — is
+ * behind this interface. The harness stays content-free: it meters, loops, caps,
+ * and emits; the reasoner reasons.
+ *
+ * The reasoner owns NO budget logic. It calls `ctx.provider.complete` and
+ * `ctx.lookup.lookup` as if they were unbounded; the harness has already wrapped
+ * both so the token ceiling and the per-finding lookup cap are enforced
+ * underneath. This keeps #2096/#2098 free of cap plumbing.
+ */
+import type { EnrichedFinding } from "../evidence";
+import type { LookupTool } from "./lookup";
+import type { Provider } from "./provider";
+
+/**
+ * An agent finding is an {@link EnrichedFinding} on the `corpus-agent` arm — the
+ * recall lane the emit projection routes to the contract's `agent` provenance.
+ * Narrowing the provenance to the literal makes "an agent finding not tagged as an
+ * agent finding" unrepresentable: the type itself is the guarantee that whatever
+ * the reasoner returns will project to the contract's agent arm, never the
+ * deterministic one.
+ */
+export type AgentFinding = EnrichedFinding & { readonly provenance: "corpus-agent" };
+
+/** Everything one pass gets: the finding to reason about, plus the metered tools. */
+export interface ReasonContext {
+  /** The deterministic finding this pass enriches / discovers around. */
+  readonly finding: EnrichedFinding;
+  /** Metered against the per-PR token ceiling by the harness. */
+  readonly provider: Provider;
+  /** Capped at the per-finding lookup budget by the harness. */
+  readonly lookup: LookupTool;
+  /** The declared diff scope, carried onto every emitted finding. */
+  readonly scope: string;
+}
+
+/**
+ * What ONE pass produces — the two agent behaviors, kept structurally distinct so
+ * "enrich" and "discover" can never be confused (issue #2098):
+ *
+ *   - {@link enrichment} ENRICHES the source deterministic finding IN PLACE: a
+ *     prose note the harness folds onto that finding, which stays
+ *     `provenance: deterministic`. `null` means "nothing to add to this one".
+ *   - {@link discoveries} DISCOVERS new issues the deterministic engine missed —
+ *     standalone `corpus-agent` findings. `[]` means "found nothing new".
+ *
+ * Both come out of the SAME single model call, so a pass still costs one provider
+ * turn (the low-cap "one pass/finding" discipline the harness meters).
+ */
+export interface ReasonResult {
+  /** An in-place note for the SOURCE deterministic finding, or `null`. Prose, never a patch. */
+  readonly enrichment: string | null;
+  /** New `corpus-agent` findings the deterministic pass missed. `[]` is a normal empty pass. */
+  readonly discoveries: readonly AgentFinding[];
+}
+
+/** The empty pass — nothing to enrich, nothing discovered. */
+export const EMPTY_RESULT: ReasonResult = { enrichment: null, discoveries: [] };
+
+export interface AgentReasoner {
+  /**
+   * Reason about one deterministic finding, producing a {@link ReasonResult}.
+   * Returning {@link EMPTY_RESULT} is a normal "nothing to add" pass. Rejecting is
+   * allowed — the harness records the pass as a non-fatal error and continues; a
+   * reasoner failure never fails the run.
+   */
+  readonly reason: (ctx: ReasonContext) => Promise<ReasonResult>;
+}

package/src/runner/reasoning/index.ts

@@ -0,0 +1,53 @@
+/**
+ * The reasoning-core registry — how the AI lane selects which per-framework
+ * knowledge to consult for a given deterministic finding (issue #2096, #2319).
+ *
+ * React / TSX (epic #2083) and Shopify Liquid themes (#2319) are wired. Selection
+ * is intentionally narrow: a finding no wired framework claims gets NO guidance,
+ * and the reasoner treats "no guidance" as a normal "nothing to add" pass rather
+ * than reasoning blind. Adding a framework is one entry here plus one guidance
+ * module — the parked frameworks (React Native, iOS, Android, ASP.NET, Angular,
+ * Flutter) slot in the same way.
+ *
+ * Shopify is matched BEFORE React because the `liquid` provenance is the authority
+ * for a theme finding: a theme's `assets/*.js`/`*.css` file would otherwise be
+ * claimed by React's extension list. Provenance-first keeps the two seams disjoint.
+ */
+import type { Finding } from "../../core";
+import { REACT_GUIDANCE } from "./react";
+import { SHOPIFY_GUIDANCE } from "./shopify";
+import type { FrameworkGuidance } from "./types";
+
+export type { ChecklistArea, Discovery, FixSeverity, FixSuggestion, FixType, FrameworkGuidance, PatternCatalogEntry } from "./types";
+export { FIX_TYPES } from "./types";
+export { REACT_GUIDANCE } from "./react";
+export { SHOPIFY_GUIDANCE } from "./shopify";
+
+/** Source-static provenances that fire on React/web JSX. */
+const WEB_PROVENANCES: ReadonlySet<Finding["provenance"]> = new Set(["jsx-a11y", "enforce", "axe"]);
+
+/** File extensions React guidance applies to. */
+const REACT_EXTENSIONS: readonly string[] = [".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs"];
+
+function isReactFinding(finding: Finding): boolean {
+  if (WEB_PROVENANCES.has(finding.provenance)) return true;
+  const file = finding.file.toLowerCase();
+  return REACT_EXTENSIONS.some((ext) => file.endsWith(ext));
+}
+
+/** A Shopify theme finding — tagged `liquid`, or a `.liquid` template/section/snippet. */
+function isShopifyFinding(finding: Finding): boolean {
+  if (finding.provenance === "liquid") return true;
+  return finding.file.toLowerCase().endsWith(".liquid");
+}
+
+/**
+ * The framework knowledge for one finding, or `null` when no wired framework
+ * claims it. `null` is the reasoner's cue to add nothing — the honest floor when
+ * the corpus has no reasoning to ground a suggestion in.
+ */
+export function frameworkGuidanceFor(finding: Finding): FrameworkGuidance | null {
+  if (isShopifyFinding(finding)) return SHOPIFY_GUIDANCE;
+  if (isReactFinding(finding)) return REACT_GUIDANCE;
+  return null;
+}

package/src/runner/reasoning/prompt.ts

@@ -0,0 +1,200 @@
+/**
+ * Projecting the reasoning core into a model conversation and reading its answer
+ * back (issue #2096). Three pure pieces, no I/O:
+ *
+ *   - {@link buildSystemPrompt} folds a {@link FrameworkGuidance} (checklist +
+ *     pattern catalog) into the `system` framing — this is where the ported
+ *     skills prose actually reaches the model.
+ *   - {@link buildUserPrompt} states the one deterministic finding to reason about.
+ *   - {@link parseReasonResponse} reads the model's reply into a typed, patch-free
+ *     {@link ParsedReasonResponse} — an in-place {@link FixSuggestion} enrichment
+ *     (or none) plus a {@link Discovery} array — over a tolerant zod boundary
+ *     (issue #2098). Every layer degrades to the valid subset: an unparseable
+ *     reply, a malformed envelope, a bad enrichment, or bad discovery entries each
+ *     yield the empty/partial result, never a throw, so bad model output can't fail
+ *     the non-blocking run.
+ *
+ * The response contract asked of the model is SUGGESTION-ONLY: it returns prose
+ * fixes, never edits. {@link parseReasonResponse} has no path to a patch — it only
+ * ever produces prose, so "fix = suggestions only" survives the parse boundary.
+ */
+import { z } from "zod";
+import type { Finding } from "../../core";
+import {
+  type Discovery,
+  FIX_TYPES,
+  type FixSuggestion,
+  type FixType,
+  type FrameworkGuidance,
+  type PatternCatalogEntry,
+} from "./types";
+
+/** Render one pattern-catalog entry as the model sees it. */
+function renderPattern(p: PatternCatalogEntry): string {
+  const lines = [
+    `### ${p.id}: ${p.title}`,
+    `- Component type: ${p.componentType}`,
+    `- WCAG: ${p.wcag.join(", ")}`,
+    `- Severity default: ${p.severityDefault}`,
+    `- Fix type default: ${p.fixTypeDefault}${p.fixTypeNote ? ` (${p.fixTypeNote})` : ""}`,
+    `- Bad shape: ${p.badShape}`,
+    `- Detection hints: ${p.detectionHints}`,
+    `- Correct fix: ${p.correctFix}`,
+    `- Verification: ${p.verification}`,
+    `- False positives / exceptions: ${p.exceptions}`,
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * The `system` framing: the framework's checklist + pattern catalog, plus the
+ * suggestion-only output contract. This IS the reshaped skill — the reasoning
+ * prose the runner's AI lane consults, carried in-engine.
+ */
+export function buildSystemPrompt(guidance: FrameworkGuidance): string {
+  const checklist = guidance.checklist
+    .map((area) => `## ${area.title}\n${area.items.map((i) => `- ${i}`).join("\n")}`)
+    .join("\n\n");
+  const patterns = guidance.patterns.map(renderPattern).join("\n\n");
+
+  return [
+    `You are an accessibility auditor reviewing ${guidance.framework} code.`,
+    `Applies to: ${guidance.appliesTo}`,
+    "",
+    "Use the checklist and pattern catalog below as your reasoning core. Ground every",
+    "suggestion in a specific checklist item or catalogued pattern.",
+    "",
+    `# ${guidance.framework} Audit Checklist`,
+    checklist,
+    "",
+    "# Pattern Catalog",
+    patterns,
+    "",
+    "# Output contract",
+    "You SUGGEST fixes; you never apply them. Do TWO things for the finding below and",
+    "return ONLY a JSON object (no prose outside it) with this exact shape:",
+    "  {",
+    '    "enrichment": { "observation": string, "suggestedFix": string, "wcag": string[],',
+    `      "fixType": one of ${FIX_TYPES.map((t) => `"${t}"`).join(" | ")}, "patternId"?: string } | null,`,
+    '    "discoveries": [ { "observation": string, "suggestedFix": string, "rationale": string,',
+    '      "confidence": "low" | "medium" | "high", "wcag": string[],',
+    `      "fixType": one of ${FIX_TYPES.map((t) => `"${t}"`).join(" | ")}, "element"?: string, "patternId"?: string } ]`,
+    "  }",
+    "",
+    "ENRICHMENT enriches the GIVEN deterministic finding in place — a note/fix for",
+    "THAT exact issue. Use null when you have nothing to add to it.",
+    "DISCOVERIES are NEW accessibility problems the rule engine MISSED — compositional",
+    "or contextual issues (e.g. a broken focus order across components, a duplicated",
+    "landmark, a heading-level skip) that no single-element rule would catch. Use [] when",
+    "you find nothing new; do NOT restate the given finding as a discovery.",
+    "Never emit a diff, patch, or file edit — only described fixes. Set patternId to the",
+    "matching catalog id when one applies.",
+  ].join("\n");
+}
+
+/** The user turn: the single deterministic finding this pass reasons about. */
+export function buildUserPrompt(finding: Finding, evidenceFix: string | null, structural: string | null): string {
+  const lines = [
+    "Reason about this deterministic finding and suggest fixes:",
+    `- rule: ${finding.ruleId}`,
+    `- message: ${finding.message}`,
+    `- wcag: ${finding.wcag.length > 0 ? finding.wcag.join(", ") : "(none mapped)"}`,
+  ];
+  if (evidenceFix !== null) lines.push(`- corpus fix hint: ${evidenceFix}`);
+  if (structural !== null) lines.push(`- structural context: ${structural}`);
+  return lines.join("\n");
+}
+
+/** The prose an agent finding carries — the suggestion folded into one message. */
+export function suggestionMessage(s: FixSuggestion): string {
+  return `${s.observation} Suggested fix (${s.fixType}): ${s.suggestedFix}`;
+}
+
+/**
+ * Coerce a model-supplied `fixType` to a known label. An unknown/absent value
+ * defaults to the most conservative label — a fix we can't classify is one the
+ * developer must verify, never a silent "SAFE". Reuses {@link FIX_TYPES} as the
+ * single source of valid labels (no duplicated literal list to drift).
+ */
+function coerceFixType(value: unknown): FixType {
+  for (const t of FIX_TYPES) if (t === value) return t;
+  return "RUNTIME-CHECK";
+}
+
+/**
+ * The zod boundary for one suggestion. `.min(1)` rejects empty prose; `fixType`
+ * is coerced not rejected (a bad label degrades to RUNTIME-CHECK); `wcag` that
+ * isn't a clean string array degrades to `[]`. This is the structured-output
+ * parse the AC demands — malformed entries are rejected at `safeParse`, never
+ * trusted.
+ */
+const fixSuggestionSchema = z.object({
+  observation: z.string().min(1),
+  suggestedFix: z.string().min(1),
+  wcag: z.array(z.string()).catch([]),
+  fixType: z.unknown().transform(coerceFixType),
+  patternId: z.string().optional(),
+});
+
+/** A discovery is a suggestion plus the standalone-judgement fields (rationale + confidence). */
+const discoverySchema = fixSuggestionSchema.extend({
+  rationale: z.string().min(1),
+  confidence: z.enum(["low", "medium", "high"]),
+  element: z.string().optional(),
+});
+
+/**
+ * The top-level envelope. Deliberately PERMISSIVE — every field is `unknown` and
+ * the whole thing `.catch`es to empty — so a malformed enrichment can never sink
+ * an otherwise-good discoveries array (and vice versa). Each field is re-parsed
+ * INDEPENDENTLY below, so tolerance is per-entry, not all-or-nothing.
+ */
+const envelopeSchema = z
+  .object({ enrichment: z.unknown().optional(), discoveries: z.unknown().optional() })
+  .catch({ enrichment: undefined, discoveries: undefined });
+
+/** The parsed two-behavior response — an in-place enrichment (or none) plus discoveries. */
+export interface ParsedReasonResponse {
+  readonly enrichment: FixSuggestion | null;
+  readonly discoveries: readonly Discovery[];
+}
+
+/** Pull the first JSON object out of a model reply (fenced ```json block or bare). */
+function extractJsonObject(text: string): string | null {
+  const fenced = text.match(/```(?:json)?\s*(\{[\s\S]*\})\s*```/);
+  if (fenced) return fenced[1];
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  return start !== -1 && end > start ? text.slice(start, end + 1) : null;
+}
+
+function parseOne<T>(schema: z.ZodType<T>, value: unknown): T | null {
+  const parsed = schema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * Read a model reply into a typed {@link ParsedReasonResponse}. Tolerant on
+ * purpose and at every layer: an unparseable reply, a malformed envelope, a bad
+ * enrichment, or bad discovery entries all degrade to the valid subset — it never
+ * throws, because the AI lane must never fail the non-blocking run.
+ */
+export function parseReasonResponse(text: string): ParsedReasonResponse {
+  const json = extractJsonObject(text);
+  if (json === null) return { enrichment: null, discoveries: [] };
+  let root: unknown;
+  try {
+    root = JSON.parse(json);
+  } catch {
+    return { enrichment: null, discoveries: [] };
+  }
+  const envelope = envelopeSchema.parse(root);
+  const enrichment = parseOne(fixSuggestionSchema, envelope.enrichment);
+  const rawDiscoveries = Array.isArray(envelope.discoveries) ? envelope.discoveries : [];
+  const discoveries: Discovery[] = [];
+  for (const entry of rawDiscoveries) {
+    const discovery = parseOne(discoverySchema, entry);
+    if (discovery !== null) discoveries.push(discovery);
+  }
+  return { enrichment, discoveries };
+}

package/src/runner/reasoning/react.ts

@@ -0,0 +1,149 @@
+/**
+ * The React / Next.js reasoning core — ported from the
+ * `Binclusive-Accessibility-Skills` repo's `react-nextjs.md` audit checklist and
+ * `patterns/react-nextjs-patterns.md` catalog (issue #2096). The prose is carried
+ * over faithfully; only its FORMAT changed (loose markdown → typed data) so the
+ * runner's AI lane can consult it with no external agent harness.
+ *
+ * React / TSX is the first framework wired (epic #2083); the other frameworks the
+ * skills repo covers (React Native, iOS, Android, ASP.NET, Shopify) are parked.
+ */
+import type { FrameworkGuidance } from "./types";
+
+export const REACT_GUIDANCE: FrameworkGuidance = {
+  framework: "React / Next.js",
+  appliesTo: "React or Next.js web projects (.tsx / .jsx source, jsx-a11y / enforce / axe findings).",
+  checklist: [
+    {
+      title: "Framework-Specific Areas",
+      items: [
+        "Next.js App Router: audit `app/**/page.*`, `layout.*`, `template.*`, route groups, dynamic segments, loading/error/not-found files, and `[locale]` segments.",
+        "Next.js Pages Router: audit `pages/**` except API routes; include `_app`, `_document`, and layout wrappers for lang, landmarks, providers, and page title behavior.",
+        "React Router/Vite: audit route config, `<Routes>`, lazy route boundaries, layout components, and SPA route focus management.",
+      ],
+    },
+    {
+      title: "High-Risk React Patterns",
+      items: [
+        "non-semantic click targets: `div/span` with `onClick`",
+        "icon-only buttons without accessible names",
+        "custom controls without role/name/state and keyboard support",
+        "modals/drawers/popovers without focus management and accessible name",
+        "forms missing label/id pairing, error association, required/autocomplete signals",
+        "table components that render data with `<div>` grids, `<td>` headers, missing `<caption>`, missing `<th scope>`, or lost header relationships after responsive rendering",
+        "route changes without focus reset or announcement",
+        "hardcoded `aria-label`, `placeholder`, `title`, `alt`, and visible strings outside i18n",
+        "animation without reduced-motion handling",
+        "Suspense/loading/toast states without live region strategy",
+      ],
+    },
+    {
+      title: "React / Next.js Table Checks",
+      items: [
+        "Audit reusable table/data-grid components and inline `<table>` markup for a programmatic table name: prefer a visible `<caption>` for data tables, or use `aria-labelledby`/`aria-label` when the design intentionally has no visible caption.",
+        "Verify header cells are rendered as `<th>`, not styled `<td>`, `<div>`, or text-only wrappers.",
+        "For simple tables, verify column headers use `scope=\"col\"` and row headers use `scope=\"row\"` when applicable.",
+        "For grouped or multi-level headers, verify stable `id`/`headers` relationships or mark as `RUNTIME-CHECK` if the rendered structure cannot be proven statically.",
+        "Check component APIs such as `columns`, `header`, `accessor`, `renderHeader`, and `cell` so icon-only or custom header renderers still expose meaningful header text.",
+        "For sortable headers, verify a native `<button>` or equivalent keyboard support is used and the active sort state is exposed with `aria-sort` on the relevant header.",
+        "Check responsive table/card transforms, virtualization, sticky headers, and horizontal scroll wrappers for lost header relationships, clipped focus, or runtime-only keyboard/reader behavior.",
+        "Do not flag tables used purely for layout if they are hidden from table semantics with an appropriate presentation strategy; do flag layout tables exposed as data tables.",
+      ],
+    },
+    {
+      title: "Next.js Checks",
+      items: [
+        "`<html lang>` and locale-specific `dir` handling in root layout or document",
+        "page titles and metadata per route",
+        "skip-to-content link and stable `<main id=\"main-content\">`",
+        "server/client component boundaries that hide interactive behavior in client wrappers",
+        "image `alt` for `next/image`; decorative images use empty alt",
+        "Link usage: navigational links must have href and meaningful text",
+      ],
+    },
+    {
+      title: "Runtime-Only Checks",
+      items: [
+        "Mark as `RUNTIME-CHECK` when not statically provable:",
+        "color contrast and dark mode contrast",
+        "focus trap/restore inside third-party dialogs",
+        "actual screen-reader announcement order",
+        "browser zoom/reflow at 200%/400%",
+        "touch target measurements",
+        "route transition focus behavior",
+        "carousel autoplay pause behavior",
+        "responsive or virtualized table header relationships",
+      ],
+    },
+  ],
+  patterns: [
+    {
+      id: "PATTERN-REACT-001",
+      title: "Non-semantic click target",
+      componentType: "Button-like custom control",
+      wcag: ["2.1.1", "4.1.2"],
+      severityDefault: "Critical",
+      fixTypeDefault: "FUNCTIONAL-RISK",
+      badShape: "A `div`, `span`, layout component, or icon wrapper has `onClick` but no native semantics.",
+      detectionHints:
+        "`onClick` on non-interactive JSX elements; missing `role`, `tabIndex`, Enter/Space handler, and accessible name.",
+      correctFix:
+        "Render a native `<button type=\"button\">` for actions or `<a href>` for navigation. Use ARIA only when native replacement is not feasible.",
+      verification: "Tab reaches it, Enter/Space activates it, and screen reader announces name, role, and state.",
+      exceptions:
+        "Do not flag non-interactive containers where the handler is only delegated and an inner native control handles activation.",
+    },
+    {
+      id: "PATTERN-REACT-002",
+      title: "Icon-only control without accessible name",
+      componentType: "IconButton / close button / carousel arrow / menu trigger",
+      wcag: ["4.1.2"],
+      severityDefault: "Serious",
+      fixTypeDefault: "SAFE",
+      fixTypeNote: "SAFE when adding a real label; FUNCTIONAL-RISK when changing structure.",
+      badShape:
+        "A button or clickable icon contains only SVG/icon content and has no visible text, `aria-label`, or `aria-labelledby`.",
+      detectionHints: "icon children, empty text content, close/search/favorite/menu SVGs.",
+      correctFix:
+        "Provide a localized accessible name that describes the action, not the icon. Hide decorative SVGs from assistive tech.",
+      verification: "Screen reader announces the intended action plus role.",
+      exceptions:
+        "Do not add `aria-label` that conflicts with visible text; prefer visible text or `aria-labelledby` when available.",
+    },
+    {
+      id: "PATTERN-REACT-003",
+      title: "Form field label is visual only",
+      componentType: "Input / Textarea / Select",
+      wcag: ["1.3.1", "3.3.2"],
+      severityDefault: "Serious",
+      fixTypeDefault: "SAFE",
+      badShape:
+        "Visible label text is not programmatically associated with the form control, or placeholder is the only label.",
+      detectionHints: "`<label>` without `htmlFor`, input without `id`, custom label wrapper, placeholder-only fields.",
+      correctFix:
+        "Use a stable `id` plus `<label htmlFor>`, or `aria-labelledby`; associate help/error text with `aria-describedby`.",
+      verification: "Accessibility tree exposes the intended name and description.",
+      exceptions:
+        "A control can be validly named by `aria-label` or `aria-labelledby` when no visible label is appropriate.",
+    },
+    {
+      id: "PATTERN-REACT-004",
+      title: "Data table lacks semantic headers or caption",
+      componentType: "Table / Data grid",
+      wcag: ["1.3.1", "2.4.6"],
+      severityDefault: "Serious",
+      fixTypeDefault: "SAFE",
+      fixTypeNote: "SAFE when adding caption/header semantics; RUNTIME-CHECK for virtualized or third-party grids.",
+      badShape:
+        "A data table renders without `<caption>`, uses `<td>` for headers, omits `scope`/`headers`, or renders a visual table with `<div>` elements and no equivalent grid semantics.",
+      detectionHints:
+        "reusable `Table`, `DataTable`, `Grid`, `columns` configs, `renderHeader`, sortable headers, `<table>` without `<caption>`, `<thead>` containing `<td>`.",
+      correctFix:
+        "Use native table markup for tabular data; provide a table name, semantic `<th>` headers, `scope` for simple relationships, and `id`/`headers` for complex relationships.",
+      verification:
+        "Screen reader can identify the table name and announce the correct row/column headers for representative cells.",
+      exceptions:
+        "Do not require `<caption>` for layout tables that are correctly removed from table semantics; do not force native tables for interactive widgets that correctly implement the ARIA grid pattern.",
+    },
+  ],
+};