@binclusive/a11y 0.1.0

package/src/runner/reasoning/shopify.ts

@@ -0,0 +1,214 @@
+/**
+ * The Shopify (Liquid theme) reasoning core — ported from the
+ * `Binclusive-Accessibility-Skills` repo's `shopify-theme-audit` skill:
+ * the `references/shopify-theme-a11y.md` audit reference (theme-structure
+ * signals, high-risk patterns, per-surface checks, severity + fix-type guidance)
+ * and its `SKILL.md` audit order (issue #2319). 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.
+ *
+ * The skills repo ships no dedicated `patterns/shopify-*.md` catalog, so the seed
+ * patterns below are drawn from the reference's own "High-Risk Shopify Patterns"
+ * and per-surface checks; each pattern's WCAG SC reuses the mapping the skills
+ * repo already assigned to the identical web patterns in
+ * `patterns/react-nextjs-patterns.md` (same failure, same SC).
+ *
+ * Shopify is the second framework wired; React / TSX was the first (epic #2083).
+ * The remaining frameworks the skills repo covers (React Native, iOS, Android,
+ * ASP.NET, Angular, Flutter) are parked.
+ */
+import type { FrameworkGuidance } from "./types";
+
+export const SHOPIFY_GUIDANCE: FrameworkGuidance = {
+  framework: "Shopify (Liquid theme)",
+  appliesTo:
+    "Shopify Online Store themes — Liquid layouts/templates/sections/snippets, JSON templates, theme assets/config/locales (`.liquid` source, `liquid` findings).",
+  checklist: [
+    {
+      title: "Theme Structure Signals",
+      items: [
+        "`layout/*.liquid`: global HTML shell, skip links, main content, global messages, SEO/title, locale direction, app embeds.",
+        "`templates/*.json` and `templates/*.liquid`: page composition, section ordering, setting values, customer/cart/product/collection/search/blog/password/404 pages.",
+        "`sections/*.liquid`: Online Store 2.0 sections, schema settings, block rendering, merchant-configurable headings, links, media, color schemes, and behavior flags.",
+        "`snippets/*.liquid`: shared controls and markup fragments.",
+        "`assets/*.{js,css,liquid}`: custom elements, focus management, keyboard support, dynamic rendering, live regions, focus styles, visually hidden utilities, reduced motion, responsive behavior.",
+        "`config/settings_schema.json` and `config/settings_data.json`: theme settings that affect colors, headings, social links, checkout/cart behavior, image behavior, labels, and optional features.",
+        "`locales/*.json`: visible strings, aria labels, hidden text, status messages, new-window warnings, error messages, and translation completeness.",
+        "`blocks/`, `customers/`, or app extension files when present.",
+      ],
+    },
+    {
+      title: "High-Risk Shopify Patterns",
+      items: [
+        "CTA links rendered as `<a>` without `href`, or with `role=\"link\" aria-disabled=\"true\"` as a published-state fallback.",
+        "Icon-only cart, search, account, menu, close, quantity, filter, sort, carousel, media, or social controls without localized accessible names.",
+        "Merchant-configurable image, slideshow, banner, collection, and product media that may lose meaning when alt text or nearby text is empty.",
+        "Product cards with duplicate links, inaccessible quick-add buttons, sale/badge text communicated only visually, or hidden product metadata that changes the accessible name.",
+        "Variant pickers, quantity selectors, recipient forms, cart notes, discount fields, and contact/newsletter forms without labels, error association, required state, or autocomplete.",
+        "Facets/filters/sort controls that update result counts without a status/live region or lose focus after AJAX updates.",
+        "Drawers, modals, predictive search, cart notifications, localization popovers, media modals, pickup availability dialogs, and quick-add flows without focus move, trap, Escape close, and focus restore.",
+        "Sliders/carousels without pause control, keyboard-operable controls, reduced-motion handling, or accessible slide names.",
+        "Native `<details>/<summary>` patterns over-customized with roles, click delegation, or state that diverges from the native open state.",
+        "Tooltip/help content available only on pointer hover or hidden with `aria-hidden` while carrying meaningful information.",
+        "CSS utilities such as `.focus-none`, `[hidden]`, `display: none`, `visibility: hidden`, opacity-only hiding, or offscreen techniques that remove focus visibility or expose hidden content incorrectly.",
+        "Dynamic HTML replacement that does not preserve focus, update status text, or reinitialize accessible behavior after cart/filter/search changes.",
+        "App embeds, remote scripts, reviews, subscriptions, chat, loyalty, cookie banners, and personalization widgets that render inaccessible controls outside the theme source.",
+      ],
+    },
+    {
+      title: "Layout and Global Shell",
+      items: [
+        "Verify a skip link exists and targets a real main container.",
+        "Verify one clear `<main>` landmark is present and repeated header/footer/navigation regions are not nested incorrectly.",
+        "Verify `<html lang>` and `dir` or locale direction are set when the theme supports multiple languages or RTL locales.",
+        "Verify global accessibility helper strings exist in locale files and are used for hidden messages such as refresh/new-window notices.",
+        "Check app embed placeholders and third-party script outputs as blind spots when source is unavailable.",
+      ],
+    },
+    {
+      title: "Templates, Sections, and Blocks",
+      items: [
+        "Read JSON templates with the Liquid section files they reference.",
+        "Treat `settings` and `blocks` as part of the audit evidence: empty link, heading, image, label, or accessibility text settings can change the result.",
+        "Verify section schema defaults do not encourage inaccessible published states.",
+        "Check heading level choices for hero/banner/slideshow sections. Mark content architecture concerns as `RUNTIME-CHECK` when final merchant composition determines the issue.",
+        "Verify optional buttons are not rendered as disabled fake links when a URL setting is blank.",
+      ],
+    },
+    {
+      title: "Links, Buttons, and Controls",
+      items: [
+        "Prefer real `<button type=\"button\">` for actions and real `<a href>` for navigation.",
+        "Flag non-semantic clickable elements and anchors used as buttons.",
+        "Verify custom controls expose name, role, state, focusability, and Enter/Space behavior.",
+        "Check quantity, variant, filter, sort, and carousel controls for visible labels or localized accessible names.",
+      ],
+    },
+    {
+      title: "Forms",
+      items: [
+        "Verify labels are programmatically associated with inputs, textareas, selects, checkboxes, and radios.",
+        "Verify error messages connect with `aria-describedby` and invalid state uses `aria-invalid` where applicable.",
+        "Verify required fields, autocomplete tokens, fieldsets/legends, and success/error live regions for customer, newsletter, contact, gift card, cart note, and recipient forms.",
+      ],
+    },
+    {
+      title: "Dynamic UI",
+      items: [
+        "Verify predictive search, cart drawer, quick add, filters, localization selectors, media modals, popovers, and drawers manage focus.",
+        "Verify dynamic updates use `role=\"status\"`, `aria-live`, or an equivalent announcement strategy.",
+        "Verify `aria-expanded`, `aria-controls`, selected/current states, and disabled states are synchronized with rendered state.",
+        "Mark minified or remote behavior as `RUNTIME-CHECK` when static source cannot prove it.",
+      ],
+    },
+    {
+      title: "Media and Visual Content",
+      items: [
+        "Verify informative images have meaningful alt text or nearby text that carries the same meaning.",
+        "Verify decorative images and icons are hidden from assistive technology.",
+        "Treat hero/banner/slideshow alt text as content-governance risk when merchant content determines whether the image is informative.",
+        "Verify video, model viewers, external embeds, and media galleries have accessible controls, captions/transcripts when relevant, and keyboard support.",
+      ],
+    },
+    {
+      title: "CSS, Motion, and Visual States",
+      items: [
+        "Verify focus is visible on interactive controls across theme color schemes.",
+        "Flag utilities that remove outline/box-shadow on focus when used on interactive elements.",
+        "Verify reduced-motion support for animations, drawers, sliders, carousels, parallax, and transitions.",
+        "Verify forced-colors/high-contrast support where CSS custom properties or box shadows carry essential state.",
+        "Mark contrast, zoom/reflow, and touch target measurements as `RUNTIME-CHECK` unless directly measured in a running storefront.",
+      ],
+    },
+  ],
+  patterns: [
+    {
+      id: "PATTERN-SHOPIFY-001",
+      title: "CTA link rendered as a disabled fake link",
+      componentType: "CTA link / button (section or block)",
+      wcag: ["2.1.1", "4.1.2"],
+      severityDefault: "Critical",
+      fixTypeDefault: "FUNCTIONAL-RISK",
+      badShape:
+        "A CTA is rendered as `<a>` without `href`, or with `role=\"link\" aria-disabled=\"true\"` as a published-state fallback, typically when a merchant URL setting is blank.",
+      detectionHints:
+        "`<a>` without `href` in a section/snippet, `aria-disabled=\"true\"` on an anchor, buttons rendered as disabled fake links when a URL setting is empty.",
+      correctFix:
+        "Prefer a real `<button type=\"button\">` for actions and a real `<a href>` for navigation; do not render optional buttons as disabled fake links when a URL setting is blank.",
+      verification:
+        "Tab reaches the control, it activates with Enter/Space (or navigates via a real href), and a screen reader announces its name and role.",
+      exceptions:
+        "Do not flag a genuinely omitted control; when a URL setting is blank the accessible resolution is to not render the control, not to render a disabled fake link.",
+    },
+    {
+      id: "PATTERN-SHOPIFY-002",
+      title: "Icon-only store control without localized accessible name",
+      componentType: "Icon-only cart / search / account / menu / close / filter / sort / carousel control",
+      wcag: ["4.1.2"],
+      severityDefault: "Serious",
+      fixTypeDefault: "SAFE",
+      badShape:
+        "An icon-only cart, search, account, menu, close, quantity, filter, sort, carousel, media, or social control has no localized accessible name.",
+      detectionHints:
+        "icon/SVG-only controls in header/snippet markup, empty text content, missing `aria-label`/locale-backed hidden text on cart/search/account/menu/close SVGs.",
+      correctFix:
+        "Provide a localized accessible name that describes the action, sourced from locale strings; hide decorative SVG/icon content from assistive technology.",
+      verification: "Screen reader announces the intended action plus role.",
+      exceptions:
+        "Do not recommend placeholder names such as `button`, `image`, `icon`, or `link`, or untranslated English labels in a localized theme.",
+    },
+    {
+      id: "PATTERN-SHOPIFY-003",
+      title: "Store form control without associated label or error state",
+      componentType: "Variant picker / quantity selector / newsletter / contact / cart-note form control",
+      wcag: ["1.3.1", "3.3.2"],
+      severityDefault: "Serious",
+      fixTypeDefault: "SAFE",
+      badShape:
+        "Variant pickers, quantity selectors, recipient forms, cart notes, discount fields, and contact/newsletter forms lack labels, error association, required state, or autocomplete.",
+      detectionHints:
+        "inputs/textareas/selects/checkboxes/radios without associated labels, missing `aria-describedby` for errors, missing `aria-invalid`, missing required/autocomplete tokens in customer/newsletter/contact/gift-card/cart-note forms.",
+      correctFix:
+        "Programmatically associate labels with each control; connect error messages with `aria-describedby` and set invalid state with `aria-invalid`; provide required fields, autocomplete tokens, fieldsets/legends, and success/error live regions.",
+      verification: "Accessibility tree exposes the intended name, description, required, and invalid state for each control.",
+      exceptions:
+        "A control can be validly named by `aria-label` or `aria-labelledby` when no visible label is appropriate.",
+    },
+    {
+      id: "PATTERN-SHOPIFY-004",
+      title: "Drawer or modal without focus management",
+      componentType: "Cart drawer / predictive search / quick-add / media modal / localization popover",
+      wcag: ["2.4.3", "4.1.2"],
+      severityDefault: "Serious",
+      fixTypeDefault: "FUNCTIONAL-RISK",
+      badShape:
+        "Drawers, modals, predictive search, cart notifications, localization popovers, media modals, pickup availability dialogs, and quick-add flows open without focus move, trap, Escape close, and focus restore.",
+      detectionHints:
+        "custom drawer/modal elements in assets/snippets, missing focus move on open, no Escape handler, no focus restore on close, missing `role=\"dialog\"`/`aria-modal`/`aria-labelledby`.",
+      correctFix:
+        "Move focus into the dialog on open, trap focus while open, close on Escape, and restore focus to the trigger on close; expose `role=\"dialog\"`, `aria-modal`, and an accessible name.",
+      verification:
+        "Keyboard focus enters the dialog on open, cannot leave it while open, Escape closes it, and focus returns to the trigger. Mark as `RUNTIME-CHECK` when behavior lives in minified/third-party scripts.",
+      exceptions:
+        "Do not flag native `<details>/<summary>` disclosure that is not over-customized; mark focus trap/restore as `RUNTIME-CHECK` when it cannot be proven from static source.",
+    },
+    {
+      id: "PATTERN-SHOPIFY-005",
+      title: "AJAX facet/cart update without status region or focus preservation",
+      componentType: "Facets / filters / sort / cart / predictive-search dynamic update",
+      wcag: ["4.1.3"],
+      severityDefault: "Serious",
+      fixTypeDefault: "FUNCTIONAL-RISK",
+      badShape:
+        "Facets/filters/sort controls update result counts, or dynamic HTML replacement re-renders cart/filter/search regions, without a status/live region, preserved focus, or reinitialized accessible behavior.",
+      detectionHints:
+        "AJAX section rendering / `fetch` replacing markup in assets, no `role=\"status\"`/`aria-live` region for updated counts, focus lost after re-render, behavior not reinitialized after cart/filter/search changes.",
+      correctFix:
+        "Announce dynamic updates with `role=\"status\"`, `aria-live`, or an equivalent strategy; preserve or move focus deliberately after the update; reinitialize accessible behavior on the replaced markup.",
+      verification:
+        "A screen reader announces the updated result/cart state and focus lands on a sensible element after the update. Mark as `RUNTIME-CHECK` when the behavior is minified or remote.",
+      exceptions:
+        "Mark minified or remote (app embed / third-party) behavior as `RUNTIME-CHECK` when static source cannot prove the announcement or focus handling.",
+    },
+  ],
+};

package/src/runner/reasoning/skills-reasoner.ts

@@ -0,0 +1,117 @@
+/**
+ * The concrete {@link AgentReasoner} — the audit-reasoning core wired into the
+ * runner's seam (issue #2096). It fills the seam #2095 left; it does NOT redesign
+ * the runner. The `AgentReasoner` interface needed no extension: the reasoning is
+ * injected as data (the framework guidance) and the output is already the
+ * seam's `AgentFinding[]`.
+ *
+ * One pass, per the harness contract:
+ *   1. Select the framework guidance for the finding; `null` ⇒ nothing to add.
+ *   2. Optionally ask ONE structural lookup (the #2097 seam) for context.
+ *   3. Consult the model with the guidance as `system` framing.
+ *   4. Parse the reply (zod boundary, issue #2098) into a patch-free enrichment of
+ *      the SOURCE finding plus zero+ DISCOVERIES, each folded onto a new
+ *      `corpus-agent` finding.
+ *
+ * Suggestions-not-patches is structural, not enforced here: this reasoner holds
+ * no filesystem handle (its `ReasonContext` grants a provider + lookup + finding,
+ * nothing else), and a {@link FixSuggestion} has no patch channel. Nothing it can
+ * do writes to the mounted source.
+ */
+import type { Finding } from "../../core";
+import { evidenceFix, type EnrichedFinding, enrich } from "../../evidence";
+import type { LookupTool } from "../lookup";
+import { type AgentFinding, type AgentReasoner, EMPTY_RESULT, type ReasonContext, type ReasonResult } from "../reasoner";
+import { frameworkGuidanceFor } from "./index";
+import { buildSystemPrompt, buildUserPrompt, parseReasonResponse, suggestionMessage } from "./prompt";
+import type { Discovery } from "./types";
+
+/** Tuning for the reasoner. All bounded — the harness meters spend underneath. */
+export interface SkillsReasonerOptions {
+  /** Upper bound on model output tokens per pass. Default 1024 — a suggestion is short. */
+  readonly maxOutputTokens?: number;
+  /** Ask one structural lookup for context before reasoning. Default true. */
+  readonly useLookup?: boolean;
+}
+
+const DEFAULT_OPTIONS: Required<SkillsReasonerOptions> = {
+  maxOutputTokens: 1024,
+  useLookup: true,
+};
+
+/** One structural lookup for context. Tolerant: a cap or a throw yields no context, never a failure. */
+async function structuralContext(lookup: LookupTool, finding: EnrichedFinding): Promise<string | null> {
+  try {
+    const result = await lookup.lookup({ kind: "renders", target: finding.selector ?? finding.ruleId });
+    if (result.status !== "ok") return null;
+    return JSON.stringify(result.data).slice(0, 500);
+  } catch {
+    return null;
+  }
+}
+
+/** The prose a discovered finding carries — observation + rationale + fix in one message. */
+function discoveryMessage(d: Discovery): string {
+  return `${d.observation} Rationale: ${d.rationale} Suggested fix (${d.fixType}): ${d.suggestedFix}`;
+}
+
+/**
+ * Fold one DISCOVERY onto a new `corpus-agent` finding. It anchors on the source
+ * finding's read-side locators (file/line, or the discovery's named element), and
+ * carries the two discovery fields the floor can't: `confidence` and the rationale
+ * (folded into the message). Advisory by construction — `enforcement: "warn"`,
+ * never inherited `block`, so it can never gate the exit code.
+ */
+function toAgentFinding(source: EnrichedFinding, d: Discovery): AgentFinding {
+  const base: Finding = {
+    file: source.file,
+    line: source.line,
+    ruleId: source.ruleId,
+    message: discoveryMessage(d),
+    wcag: d.wcag.length > 0 ? d.wcag : source.wcag,
+    enforcement: "warn",
+    provenance: "corpus-agent",
+    layer: "recall",
+    confidence: d.confidence,
+    ...(d.patternId !== undefined ? { patternId: d.patternId } : {}),
+    ...(d.element !== undefined
+      ? { selector: d.element }
+      : source.selector !== undefined
+        ? { selector: source.selector }
+        : {}),
+    ...(source.impact !== undefined ? { impact: source.impact } : {}),
+  };
+  return { ...enrich(base), provenance: "corpus-agent" };
+}
+
+/**
+ * Build the reasoning core as an {@link AgentReasoner}. The runner's AI lane
+ * consults the framework checklists + pattern catalogs through this — with no
+ * Claude-Code (or any external agent) harness dependency.
+ */
+export function createSkillsReasoner(options: SkillsReasonerOptions = {}): AgentReasoner {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+
+  const reason = async (ctx: ReasonContext): Promise<ReasonResult> => {
+    const guidance = frameworkGuidanceFor(ctx.finding);
+    if (guidance === null) return EMPTY_RESULT;
+
+    const structural = config.useLookup ? await structuralContext(ctx.lookup, ctx.finding) : null;
+    const system = buildSystemPrompt(guidance);
+    const user = buildUserPrompt(ctx.finding, evidenceFix(ctx.finding.corpus), structural);
+
+    const response = await ctx.provider.complete({
+      system,
+      messages: [{ role: "user", content: user }],
+      maxOutputTokens: config.maxOutputTokens,
+    });
+
+    const parsed = parseReasonResponse(response.text);
+    // Enrich the SOURCE finding in place (prose note); discover NEW findings around it.
+    const enrichment = parsed.enrichment !== null ? suggestionMessage(parsed.enrichment) : null;
+    const discoveries = parsed.discoveries.map((d) => toAgentFinding(ctx.finding, d));
+    return { enrichment, discoveries };
+  };
+
+  return { reason };
+}

package/src/runner/reasoning/types.ts

@@ -0,0 +1,99 @@
+/**
+ * The reasoning-knowledge types — the shape of the audit-reasoning core the AI
+ * lane consults. Ported from the `Binclusive-Accessibility-Skills` repo's
+ * per-framework checklists + pattern catalogs (issue #2096) and reshaped from
+ * loose markdown into typed, in-engine data, so the runner carries its own
+ * reasoning with NO external agent-harness dependency.
+ *
+ * Two omissions encode the epic's law that the AI lane SUGGESTS, never applies:
+ *   - {@link FixSuggestion} has no `patch` / `diff` / `edits` field. A suggestion
+ *     is PROSE, never an applicable change — "fix = suggestions only" is
+ *     unrepresentable to violate because this type carries no channel for a patch.
+ *   - The reasoner is handed a provider + lookup + finding (`ReasonContext`),
+ *     never a filesystem handle — so "nothing is written to the mounted source"
+ *     holds by construction, not by policy.
+ */
+
+import type { AgentConfidence } from "../../core";
+
+/** How safe applying a fix is — the trust label from the pattern catalog. */
+export type FixType = "SAFE" | "VISUAL-IMPACT" | "FUNCTIONAL-RISK" | "RUNTIME-CHECK";
+
+export const FIX_TYPES: readonly FixType[] = ["SAFE", "VISUAL-IMPACT", "FUNCTIONAL-RISK", "RUNTIME-CHECK"];
+
+/** The catalog's severity vocabulary (distinct from axe's runtime impact). */
+export type FixSeverity = "Critical" | "Serious" | "Moderate" | "Minor";
+
+/**
+ * One catalogued failure pattern — a ported pattern-catalog entry. The fields
+ * mirror the skills repo's Pattern Entry Template so the prose survives the port
+ * intact; the reasoner projects them into the system prompt.
+ */
+export interface PatternCatalogEntry {
+  /** Stable catalog id, e.g. `PATTERN-REACT-001`. Provenance back to the corpus slice. */
+  readonly id: string;
+  readonly title: string;
+  readonly componentType: string;
+  /** WCAG SCs / APG patterns this addresses, e.g. `["2.1.1", "4.1.2"]`. */
+  readonly wcag: readonly string[];
+  readonly severityDefault: FixSeverity;
+  /** The common-case trust label; the conditional nuance lives in {@link fixTypeNote}. */
+  readonly fixTypeDefault: FixType;
+  /** The catalog's "SAFE when …, FUNCTIONAL-RISK when …" conditional, preserved verbatim. */
+  readonly fixTypeNote?: string;
+  readonly badShape: string;
+  readonly detectionHints: string;
+  readonly correctFix: string;
+  readonly verification: string;
+  readonly exceptions: string;
+}
+
+/** A named group of checklist prose (e.g. "High-Risk React Patterns"). */
+export interface ChecklistArea {
+  readonly title: string;
+  readonly items: readonly string[];
+}
+
+/** The per-framework reasoning core: checklist prose + pattern catalog. */
+export interface FrameworkGuidance {
+  /** Human framework name, e.g. `"React / Next.js"`. */
+  readonly framework: string;
+  /** When this guidance applies — the ported "use this reference only for …" scope. */
+  readonly appliesTo: string;
+  readonly checklist: readonly ChecklistArea[];
+  readonly patterns: readonly PatternCatalogEntry[];
+}
+
+/**
+ * A single fix the reasoner proposes for a finding — SUGGESTION ONLY. It carries
+ * NO patch/diff: the fix is described in prose, never applied. This is the AI
+ * lane's whole output vocabulary, and it is patch-free on purpose.
+ */
+export interface FixSuggestion {
+  /** What the reasoner observed — grounds the suggestion in the finding. */
+  readonly observation: string;
+  /** The recommended fix in prose — the catalog's "correct fix" applied here. */
+  readonly suggestedFix: string;
+  /** WCAG SCs the suggestion addresses. */
+  readonly wcag: readonly string[];
+  /** How safe applying it is — the trust label carried onto the finding. */
+  readonly fixType: FixType;
+  /** The catalog pattern this matched, if any — provenance back to the corpus slice. */
+  readonly patternId?: string;
+}
+
+/**
+ * A NEW accessibility issue the deterministic engine missed — the agent lane's
+ * DISCOVER output (issue #2098). A {@link FixSuggestion} enriched with the two
+ * fields a standalone judgement needs: a `rationale` for why it is a real problem
+ * and the agent's `confidence` in that call. Still patch-free — a discovery is a
+ * described problem + described fix, never an edit.
+ */
+export interface Discovery extends FixSuggestion {
+  /** Why this is a genuine issue — the judgement the deterministic floor can't make. */
+  readonly rationale: string;
+  /** How sure the agent is (see {@link AgentConfidence}). */
+  readonly confidence: AgentConfidence;
+  /** The element the discovery is about, when the agent can name one (a CSS-ish locator). */
+  readonly element?: string;
+}

package/src/runner/runner.ts

@@ -0,0 +1,203 @@
+/**
+ * The low-cap pull loop — the runner harness.
+ *
+ * ONE pass per deterministic finding. Each pass gets a fresh per-finding lookup
+ * budget and a provider metered against the shared per-PR token ceiling. The loop
+ * is NON-BLOCKING by construction: {@link runAgentLane} returns a {@link RunOutcome}
+ * for every input and NEVER rejects. Hitting the token ceiling is the `capped`
+ * arm — a normal partial result (fewer findings), not an error. The caller can
+ * always `exit 0`.
+ *
+ * The three seams the harness leaves clean:
+ *   - #2096 reasoning skills   → the `AgentReasoner` (the prompt/system content).
+ *   - #2097 code-graph lookups → the `LookupTool` the harness caps per finding.
+ *   - #2098 enrich/discover    → the reasoner returns a `ReasonResult` (in-place
+ *     enrichment + discoveries); the harness folds notes onto the source findings
+ *     and dedups the discoveries against the deterministic floor.
+ *
+ * The emit boundary is the canonical contract: agent findings project through the
+ * SAME `emit-contract` projection the deterministic engine uses (#2093), so no
+ * file/line ever reaches the wire and there is one wire schema, not two. The
+ * lenient variant drops a single malformed finding rather than failing the run.
+ */
+import { dedupeRecall } from "../core";
+import type { EnrichedFinding } from "../evidence";
+import { toFindingPayloadLenient } from "../emit-contract";
+import type { FindingPayload } from "@binclusive/a11y-contract";
+import { type BudgetSnapshot, meterProvider, TokenCeilingExceeded, TokenLedger } from "./budget";
+import { LookupCounter, type LookupTool, meterLookup } from "./lookup";
+import type { Provider } from "./provider";
+import type { AgentFinding, AgentReasoner } from "./reasoner";
+
+/** The low-cap knobs. Start low; dialing up is a separate concern (epic #2083). */
+export interface RunnerConfig {
+  /** Hard per-PR ceiling on `input + output` model tokens across all passes. */
+  readonly tokenCeiling: number;
+  /** Soft cap on structural lookups PER deterministic finding (~3-5). */
+  readonly lookupsPerFinding: number;
+}
+
+export const DEFAULT_RUNNER_CONFIG: RunnerConfig = {
+  tokenCeiling: 100_000,
+  lookupsPerFinding: 5,
+};
+
+/**
+ * Why one pass ended. A pass is atomic: it produces, is empty, errors, or never
+ * ran. `produced` carries BOTH agent behaviors — how many findings it DISCOVERED
+ * and whether it ENRICHED the source finding in place — so a note-only pass still
+ * reads as productive, not empty.
+ */
+export type PassOutcome =
+  | { readonly kind: "produced"; readonly discovered: number; readonly enriched: boolean }
+  | { readonly kind: "empty" }
+  | { readonly kind: "errored"; readonly reason: string }
+  | { readonly kind: "skipped"; readonly reason: "token-ceiling" };
+
+/** A local-only diagnostic record of one pass. Never crosses the wire. */
+export interface PassReport {
+  /** The deterministic finding's rule id — local diagnostics only, no file/line. */
+  readonly ruleId: string;
+  readonly lookupsUsed: number;
+  readonly outcome: PassOutcome;
+}
+
+export interface RunInput {
+  /** The deterministic findings (from the engine, already `enrich`ed). */
+  readonly findings: readonly EnrichedFinding[];
+  readonly reasoner: AgentReasoner;
+  readonly provider: Provider;
+  readonly lookup: LookupTool;
+  /** The declared diff scope, carried onto every emitted finding. */
+  readonly scope: string;
+  readonly config?: RunnerConfig;
+}
+
+/**
+ * The total outcome. Both arms carry a contract-validated {@link FindingPayload}
+ * (possibly partial) AND the rich local findings (for local SARIF / PR comments).
+ * There is no `failed` arm — the loop is non-blocking.
+ *
+ * `findings` are the DISCOVERED agent findings (deduped). `enrichedFindings` are
+ * the input deterministic findings, in order, some now carrying an `agentNote`
+ * from an in-place enrichment — they stay `provenance: deterministic` and feed the
+ * deterministic (strict) emit + local render, never the agent payload.
+ */
+export type RunOutcome =
+  | {
+      readonly status: "complete";
+      readonly payload: FindingPayload;
+      readonly findings: readonly AgentFinding[];
+      readonly enrichedFindings: readonly EnrichedFinding[];
+      readonly passes: readonly PassReport[];
+      readonly usage: BudgetSnapshot;
+      /** Findings dropped at the emit boundary for failing the contract re-parse. */
+      readonly dropped: number;
+    }
+  | {
+      readonly status: "capped";
+      readonly cappedBy: "token-ceiling";
+      readonly payload: FindingPayload;
+      readonly findings: readonly AgentFinding[];
+      readonly enrichedFindings: readonly EnrichedFinding[];
+      readonly passes: readonly PassReport[];
+      readonly usage: BudgetSnapshot;
+      /** Deterministic findings whose pass completed before the ceiling. */
+      readonly processed: number;
+      /** Deterministic findings skipped once the ceiling was reached. */
+      readonly skipped: number;
+      readonly dropped: number;
+    };
+
+/**
+ * Drive the AI lane over the deterministic findings, capped and non-blocking.
+ * Returns a {@link RunOutcome} for every input; never rejects.
+ */
+export async function runAgentLane(input: RunInput): Promise<RunOutcome> {
+  const config = input.config ?? DEFAULT_RUNNER_CONFIG;
+  const ledger = new TokenLedger(config.tokenCeiling);
+  const provider = meterProvider(input.provider, ledger);
+
+  const discoveries: AgentFinding[] = [];
+  // Parallel to `input.findings`, in order: each finding as-is, or with an
+  // `agentNote` folded on when its pass enriched it in place.
+  const enrichedFindings: EnrichedFinding[] = [];
+  const passes: PassReport[] = [];
+  let processed = 0;
+  let capped = false;
+
+  for (let i = 0; i < input.findings.length; i += 1) {
+    const finding = input.findings[i];
+
+    // Pass boundary: a prior pass may have emptied the wallet. Skip the rest —
+    // an unprocessed finding keeps its shape (no note), never fails.
+    if (capped || ledger.exhausted()) {
+      capped = true;
+      enrichedFindings.push(finding);
+      passes.push({ ruleId: finding.ruleId, lookupsUsed: 0, outcome: { kind: "skipped", reason: "token-ceiling" } });
+      continue;
+    }
+
+    const counter = new LookupCounter(config.lookupsPerFinding);
+    const lookup = meterLookup(input.lookup, counter);
+
+    try {
+      const result = await input.reasoner.reason({ finding, provider, lookup, scope: input.scope });
+      // ENRICH in place: fold the note onto THIS deterministic finding (it stays
+      // deterministic). DISCOVER: collect the new agent findings for later dedup.
+      enrichedFindings.push(result.enrichment !== null ? { ...finding, agentNote: result.enrichment } : finding);
+      discoveries.push(...result.discoveries);
+      processed += 1;
+      const produced = result.enrichment !== null || result.discoveries.length > 0;
+      passes.push({
+        ruleId: finding.ruleId,
+        lookupsUsed: counter.used,
+        outcome: produced
+          ? { kind: "produced", discovered: result.discoveries.length, enriched: result.enrichment !== null }
+          : { kind: "empty" },
+      });
+    } catch (error) {
+      // Every non-cap failure leaves the finding un-enriched but present.
+      enrichedFindings.push(finding);
+      if (error instanceof TokenCeilingExceeded) {
+        // The ceiling blew mid-pass. Discard this pass's partial work and stop
+        // pulling new findings — the remaining ones are skipped, not failed.
+        capped = true;
+        passes.push({ ruleId: finding.ruleId, lookupsUsed: counter.used, outcome: { kind: "skipped", reason: "token-ceiling" } });
+        continue;
+      }
+      // Any other failure is this pass's problem alone: record it, keep going.
+      passes.push({ ruleId: finding.ruleId, lookupsUsed: counter.used, outcome: { kind: "errored", reason: reasonOf(error) } });
+    }
+  }
+
+  // DEDUP (issue #2098): drop any discovery the deterministic floor already caught
+  // (cross-dedup by file:line:sc) or that duplicates another discovery (self-dedup
+  // by file:line:patternId). Reuse the engine's `dedupeRecall` verbatim — one dedup
+  // discipline, not a second one. Survivors keep identity, so re-narrow to agent.
+  const survivors = new Set(dedupeRecall(discoveries, input.findings));
+  const agentFindings = discoveries.filter((d) => survivors.has(d));
+
+  const { payload, dropped } = toFindingPayloadLenient(agentFindings, input.scope);
+  const usage = ledger.snapshot();
+
+  if (capped) {
+    return {
+      status: "capped",
+      cappedBy: "token-ceiling",
+      payload,
+      findings: agentFindings,
+      enrichedFindings,
+      passes,
+      usage,
+      processed,
+      skipped: input.findings.length - processed,
+      dropped,
+    };
+  }
+  return { status: "complete", payload, findings: agentFindings, enrichedFindings, passes, usage, dropped };
+}
+
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}