Evidence-aware document accessibility remediation in AlloFlow

Architecture, standards context, privacy boundaries, delivery paths, and the limits of automated assurance.

Prepared August 13, 2026 · AlloFlow open-source project · This paper is technical information, not legal advice or a conformance certification.

1. Executive summary

Document remediation is not a file conversion problem. An accessible result must preserve the source's information while exposing meaningful headings, lists, tables, links, image alternatives, language, reading order, navigation, and interaction to people using different sensory and input modes. Automated tools can identify and repair some failures, but they cannot decide whether every description is useful, every table conveys its intended relationships, or every page remains faithful to the author.

AlloFlow therefore treats remediation as a staged, evidence-producing workflow. It assesses and extracts the source; rebuilds a semantic HTML representation; applies deterministic and AI-supported repairs; checks the exact HTML with multiple evidence sources; stops or reverts when an improvement loop plateaus or regresses; then creates a native tagged PDF and, when the local validator is available, runs veraPDF against the final PDF bytes. The output is a package for review rather than a blanket declaration of compliance.

Central claim. AlloFlow is designed to produce a more accessible, reviewable document package with source-bound evidence. It does not claim that automation alone establishes WCAG, PDF/UA, Section 508, or legal compliance.

2. Standards and current public-sector timeline

2.1 Why WCAG matters

The Web Content Accessibility Guidelines are a shared international technical standard for making digital content more accessible to people with disabilities. WCAG 2 organizes its requirements under four principles: content should be perceivable, operable, understandable, and robust. Testable success criteria are grouped at Levels A, AA, and AAA. W3C encourages use of WCAG 2.2, which adds criteria while retaining the earlier WCAG 2 requirements, apart from a documented obsolete parsing criterion.

AlloFlow's engineering work is aimed toward WCAG 2.2 Level AA. That target should not be confused with the legal baseline selected in a particular regulation or with a product-wide conformance claim.

2.2 U.S. Department of Justice Title II rule

The Department of Justice's 2024 Title II rule adopted WCAG 2.1 Level AA as the technical standard for covered web content and mobile applications provided by state and local governments. Public schools, public universities, libraries, and other public entities can fall within its scope. The rule also contains definitions, exceptions, and entity-specific considerations that require direct review of official guidance.

An interim final rule effective April 20, 2026 extended the compliance dates. Public entities with a population of 50,000 or more generally have a compliance date of April 26, 2027. Public entities with a population below 50,000 and special district governments generally have a date of April 26, 2028. DOJ emphasizes that accessibility obligations under Title II continue independently of those dates.

Planning implication. A later date should not be treated as permission to delay inventory and remediation. Accessible content requires ownership, training, procurement standards, repeatable authoring practice, user testing, and a sustainable way to handle new material.

3. The remediation problem

Conventional documents often encode appearance more reliably than meaning. A heading may be only large bold text. A table may be a group of positioned words. A scanned PDF may contain no text layer. Reading order can diverge from visual order. Form fields can be unlabeled. Images may lack text alternatives or may require context that cannot be inferred safely.

A robust process must address at least four kinds of risk:

Extraction risk: text or relationships can be lost, duplicated, or placed in the wrong order.
Semantic risk: a visually plausible output can expose weak or incorrect structure to assistive technology.
Transformation risk: an attempted fix can alter meaning or introduce a new defect.
Assurance risk: a clean automated scan can be mistaken for complete accessibility evidence.

AlloFlow's architecture addresses these risks by separating source recovery, semantic authoring, browser-level checks, PDF structural checks, and human review.

4. Pipeline architecture

This section describes the pipeline at decision level. Reviewers who want the mechanisms stated precisely, including the keep-best loop, the verifier stack, and the no-egress configuration, should continue to Appendix A.

PDF / DOCX / PPTX ↓ source assessment + text/layout extraction + OCR when needed ↓ semantic HTML rebuild ↓ deterministic repair → AI-diagnosed surgical repair → complex rewrite only when needed ↓ fresh rubric review + axe-core + IBM Equal Access on exact HTML bytes ↓ bounded keep-best loop with plateau stop and regression rollback ↓ reviewable HTML + evidence report + native tagged PDF ↓ internal PDF preflight + optional local veraPDF PDF/UA-1 validation ↓ human source comparison and usability review

4.1 Assessment and extraction

The pipeline begins by identifying the source format, page characteristics, text availability, images, links, and likely reading-order or structure risks. Text-native pages are extracted directly. Image-based pages can be routed through OCR. Extraction remains an evidence source, not an authority: recovered tokens and order must be compared with the source.

4.2 Semantic rebuild

The primary intermediate representation is semantic HTML. This creates an inspectable structure for headings, paragraphs, lists, tables, figures, links, language, navigation, and accessible names. Deterministic fixes are preferred because they are reproducible. More invasive AI-supported repair is used for defects that require diagnosis or rewriting.

4.3 Bounded improvement

Verification results feed a keep-best loop. The process can apply a candidate repair, re-run evidence, keep an improvement, revert a regression, and stop when the results plateau. This is safer than an unbounded “self-healing” claim because every iteration is conditional on fresh evidence.

4.4 Output and PDF validation

The application can produce accessible HTML, an audit/evidence report, and native tagged PDF for PDF inputs. Office, image, and text-family inputs (markdown, plain text, CSV/TSV, and spreadsheets) in the local connector produce accessible HTML rather than pretending that a generic HTML-to-PDF step reconstructs an editable Office source. Editable and alternate exports include DOCX, ODT, EPUB 3, DAISY 3, and uncontracted Grade-1 BRF, each with its own disclosed validation boundary.

5. Evidence model

5.1 HTML evidence

Complete application-level HTML evidence combines a rubric-based accessibility review with axe-core and IBM Equal Access checks. These are not three interchangeable scores. The rubric can address contextual requirements that rule engines may not decide; rule engines provide deterministic findings for supported machine-testable patterns.

5.2 Exact-output binding

Evidence is useful only when it corresponds to the artifact being delivered. AlloFlow binds verification to the exact HTML output and, in the portable workflow, binds the repair plan to a SHA-256 digest of the source. Stamped reports and verification worksheets are intended to make stale or altered evidence detectable.

5.3 PDF evidence

A tagged PDF and a browser-accessible HTML rendering are different artifacts. PDF output receives an internal structural preflight. When local Java and veraPDF are available, the final PDF bytes can receive independent PDF/UA-1 validation. A veraPDF pass evaluates the rules in its profile; it does not prove that every description is meaningful or every reading-order choice matches author intent.

5.4 Human review

A qualified reviewer still compares the source and output; checks reading order, tables, equations, forms, and image descriptions; tests keyboard and assistive-technology use where relevant; and resolves cautions that automation cannot decide. Legal, signed, and interactive form records receive additional restrictions in the portable workflow.

6. Delivery paths

6.1 Application pipeline

The full AlloFlow application presents an interactive document workflow with preview, audit, repair, verification, export, and review controls. It is available through the project's broader runtime paths, whose AI and storage boundaries differ.

6.2 Portable Agent Skill v0.2.9

The portable Skill is the simplest public remediation distribution. A user attaches a document in a compatible AI workspace. The selected host model analyzes the attachment and creates a strict, source-bound repair plan. Bundled scripts perform deterministic rebuild and validation, then produce HTML, tagged PDF when local capability is present, a scoped report, and a privacy receipt. A fresh-context second reader or human reviewer verifies the result. Source files are never overwritten; automatic rebuild is blocked for interactive forms, signed documents, certificates, and legal records.

The neutral Skill is the ordinary direct-use package. The OpenAI package supports the publisher and submission flow, while the Claude Code wrapper supports that plugin environment. They are versioned, checksum-listed assets in the portable-v0.2.9 GitHub Release, not the Claude Desktop MCP connector. Baseline scripts require Python 3.9 or newer; tagged PDF needs local Node, Playwright, and Chromium capability; PDF/UA validation needs a separate local Java and veraPDF setup.

6.3 Local MCP connector

The local MCP source exposes 31 tools for remediation, auditing, extraction, redaction, form conversion, validation, and alternate-format work. It includes a companion Skill that teaches a compatible client how to use the connector. The connector runs as local standard input/output; offline document tools keep document data local. Setup and some export helpers can download public dependencies without intentionally sending document content; credential checking sends only the key. Gemini-dependent operations may send the full selected document or derived content using the user's configured key.

A public MCPB binary is now published as a versioned GitHub Release. Each release is built in CI from a tagged commit and must pass parity tests and artifact verification before publication; it ships with a SHA-256 checksum record, a CycloneDX SBOM, and a GitHub build-provenance attestation binding the downloadable bytes to the workflow that produced them.

6.4 Institution-owned remote pilot architecture

The repository also contains a fail-closed remote MCP design using institution-owned Cloudflare infrastructure for OAuth, opaque identifiers, private storage, durable workflows, isolated containers, quotas, and retention. It has not been provisioned as a public service and should not be confused with the Cloudflare Pages browser application.

7. Privacy boundaries

“Local” and “private” must name the system boundary. AlloFlow uses different boundaries for different workflows:

Portable Skill: the attachment is processed by the chosen host agent under its terms and settings. Bundled scripts make no document request to AlloFlow, Cloudflare, a remote MCP, another model API, or telemetry.
Local MCP: offline document tools keep document data local. Some setup and export helpers fetch public dependencies without intentionally sending document content; credential checking sends only the key. Gemini-dependent operations may send the full selected document or derived content using the user's key. Local job metadata can persist for up to 30 days.
Cloudflare-hosted browser app: Cloudflare Pages delivers static application assets. Ordinary web configuration, including a configured provider key, is stored in that browser's unencrypted local storage; shared or student devices should be avoided and keys removed after use. AI requests go to the selected provider. Cloudflare Pages is not the remediation document service.
Packaged Electron Desktop: provider keys can use OS-backed encrypted storage, and supported local models can avoid a remote model provider for compatible operations.

Protected-data caution. No path should be used for student records, health information, or other protected content solely because it is described as local or portable. Institutions must approve the host, account, provider, retention, device, storage, and human workflow together.

8. Case-study evidence

Repository test reports provide useful examples of the pipeline under specific conditions. They are not general accuracy estimates.

8.1 Five-document cross-validation

A dated five-document corpus report recorded agreement between two PDF/UA validation pathways across all five tested outputs and recorded zero failed rules in those runs. The same report included corroborating axe-core and IBM Equal Access results on the tested HTML. The correct interpretation is that these five artifacts passed the described tests—not that every future document will do so.

8.2 Large-document verification

A 126-page case recorded 1,663 of 1,663 verification items in its round report. A separate 40-page, 17-image teacher-guide case recorded 388 of 388 items after the verification process exposed seven authoring discrepancies and they were corrected. These examples illustrate why the verification loop matters: a useful evaluator must be able to block or revise output, not merely produce a positive score.

9. Current limitations and non-claims

Automated output is not a legal opinion, accessibility certification, or substitute for an organization's conformance evaluation.
A zero-finding axe or Equal Access run covers only the rules and rendered state tested.
AI review can be inconsistent and must be corroborated by deterministic checks and people.
OCR can misrecognize characters, order, mathematical notation, or language.
Alternative-text quality, source fidelity, and reading-order intent require human judgment.
EPUB checking is structural and is not an epubcheck result.
DAISY output is not currently backed by a contracted DAISY validator.
BRF output is uncontracted Grade 1 and requires qualified review; Grade 2 UEB is not claimed.
AI-assisted runs depend on the operator's own provider key and quota. Under provider rate limiting, a run can apply and verify repairs yet still fail to produce a final whole-document score.
The remote institutional MCP is code for a pilot architecture, not a live public service.

10. Adoption guidance

Inventory before bulk conversion. Classify active, archived, duplicate, exempt-candidate, and high-impact content with counsel and accessibility leadership.
Prioritize services and current learning content. Focus first on documents people need to participate, apply, learn, communicate, or receive support.
Fix authoring upstream. Pair remediation with accessible templates, procurement requirements, training, and publishing gates.
Choose a documented data boundary. Approve the complete host/provider/device path before uploading protected documents.
Require artifact-bound evidence. Keep the source digest, output digest, check versions, findings, cautions, and review record together.
Include disabled users and assistive-technology testing. Technical checks are necessary but cannot represent the full experience of accessing a document.

Appendix A. Engineering deep dive

Sections 4 and 5 describe the pipeline at the level a program decision needs. This appendix is for the reviewer who wants to know how the machine actually works, and it is written to the same rule as the rest of this paper: no claim without a mechanism behind it.

A.1 The verifier stack, and why there are three

Every candidate output is scored by independent checkers with different failure models: axe-core and IBM Equal Access run against the exact HTML bytes that would ship (never a simplified copy), and veraPDF validates the tagged PDF against PDF/UA-1 as a separate, locally runnable step. Three verifiers matter because each has blind spots: rule engines disagree at the margins, and a repair that satisfies one can regress another. The loop below therefore scores against the verifiers jointly rather than optimizing any single number.

A.2 The keep-best loop, precisely

The improvement loop maintains a best-so-far record: the best HTML bytes seen and the verification results that earned them (in the implementation these are literally state variables named for the role: the best HTML, the best axe result, the best Equal Access result, the best issue count). Each iteration proposes a repair, re-runs the verifiers on the candidate, and then makes a conditional decision:

Improvement replaces the best-so-far record.
Regression is rolled back; the candidate is discarded and the prior best stands. A repair can never make the shipped output worse than the best already achieved.
Plateau ends the loop: when fresh evidence stops improving, the process stops instead of spending further model calls chasing noise. The plateau rule is what makes "bounded" a mechanism rather than a promise.

Repairs themselves are tiered by invasiveness, and the loop exhausts cheaper tiers first: deterministic transforms (reproducible, reviewed once, trusted thereafter), then AI-diagnosed surgical repairs scoped to a named defect, and only lastly rewrites of a region whose structure cannot be repaired in place.

A.3 Spending model calls honestly

AI calls are the pipeline's scarcest resource, so their use is instrumented rather than assumed. The current implementation records the HTTP trail of failed calls, captures provider Retry-After signals instead of hammering a throttled endpoint, and skips re-verification passes when a fix round changed nothing, because re-auditing an unchanged document is three model calls for zero information. These are small rules with a large cumulative effect: the pipeline degrades gracefully under provider throttling rather than failing loudly or silently burning quota.

A.4 Provenance, or why the report can be trusted

The evidence report is bound to artifacts, not narrated: source digest, output digest, checker versions, and findings travel together, so a report cannot drift away from the bytes it describes. The same discipline applies internally, and it is enforced in the development process itself: the project's own regression gates treat a checker that could pass vacuously as a defect, and verification steps are required to fail loudly on inputs designed to trip them before their green results are believed.

A.5 The no-egress configuration

Every stage of the pipeline can run against a locally hosted model (LM Studio, Ollama, LocalAI and compatible servers) instead of a cloud provider, and the verifier stack is local by construction: axe-core and Equal Access run in the page, and veraPDF runs from a local JAR. In this configuration a confidential document is processed end to end with no content leaving the machine, which is the deployment posture the case-study work in section 8 used for sensitive material. The tradeoff is stated rather than hidden: smaller local models diagnose less reliably than frontier cloud models, so the deterministic tier carries more of the load and the human review pass matters more.

A.6 The portable implementations

The same pipeline design ships in portable form for teams that live in other tools: a Claude Code plugin, an OpenAI-compatible plugin, and an agent skill (v0.2.9 at this writing, downloadable from this site). These share the rubric, the tiered-repair philosophy, and the evidence model with the in-app pipeline; they exist because the district staff member who remediates documents all day often works in an editor or an agent environment, not in a browser tab. Each portable build discloses its own validation boundary the same way section 6 does for export formats.

A.7 What this appendix deliberately does not claim

No fixed success percentage is quoted for the AI repair tiers, because the honest number varies with document pathology, model choice, and configuration; section 8's case studies are offered instead, with their artifacts. "Self-healing," "fully automatic," and "guaranteed compliant" do not appear in this paper because no such mechanism exists here or, to our knowledge, anywhere: the pipeline's claim is narrower and checkable — bounded, evidence-conditional improvement with a human decision at the end.