-
-
main screen
Inspiration
Accessibility complaints often arrive as a single sentence: “The donate button is dead on keyboard” or “The contrast is terrible.” They contain no reliable reproduction steps and no evidence that a proposed fix actually solved the problem.
ProofPatch was built to close that gap. It turns a messy complaint into a measurable, reviewable workflow: reproduce the issue, collect evidence, propose a bounded change, wait for human approval, apply the change once, and verify the result with the same exact check.
ProofPatch is a Taskmaster entry built around two durable jobs and two focused specialists. The reproducer uses Playwright and pinned axe-core to establish what is actually wrong. The patcher proposes typed file operations based only on those findings. The model is never allowed to declare that a website is “WCAG-clean.”
What it does
A user files a natural-language complaint against the owned Harbor Commons fixture. Job 1 opens the page in Chromium, runs axe-core 4.10.3, and stores a before.png screenshot together with the axe JSON in a private Cloud Storage bucket. Gemini 3.5 Flash then proposes typed file replacements using only the measured fingerprints and the fixture’s HTML/CSS.
A human must approve the proposal. Job 2 applies the patch once for the (run_id, patch_sha256) pair and runs the same exact check again. VERIFIED is deliberately narrow: it means the targeted fingerprints are no longer present in the post-patch measurement. It is not a WCAG certification. A repeated approval attempt returns DUPLICATE_BLOCKED.
The operations desk is available at /. Individual run truth is stored in Firestore, and screenshots and axe evidence are retained in private Cloud Storage. The live service is available at:
• Live application: https://proofpatch-api-295478535981.us-central1.run.app
• Demo token: dev-token, available under Hi, Demo
• Repository: https://github.com/Ritesh-Root/proofpatch
How we built it
Google ADK 2.7.1 coordinates a focused agent with three tools: measure the owned fixture, read its HTML/CSS, and propose typed operations. FastAPI on Cloud Run handles intake, approval, retry, artifact access, and run state. The Playwright worker runs as a Cloud Run Job so the API remains lightweight. Firestore is the source of truth for run state, while private Google Cloud Storage holds the evidence artifacts.
The public workflow cannot write to arbitrary repositories. All mutations are fixture-only, and mutating actions require the demo token in the X-Demo-Token header.
Challenges we ran into
The first challenge was operational rather than theoretical: the README documented dev-token while an earlier Cloud Run deployment used a rotated value. A judge following the instructions received a 401 response. We aligned the documentation and deployment so the first documented request works.
The hosted image and the public GitHub branch also drifted during development. That made it possible for a source audit and a live audit to describe different systems. We added deployment SHA reporting and treated source/runtime alignment as a release requirement.
An early worker path used stub findings. That was unacceptable for the product’s central promise, so Job 1 and Job 2 were moved onto real Playwright and axe measurement. The system now stores the measurement version, browser version, viewport, findings, and evidence artifacts that support the decision.
Vertex access created another boundary: user ADC credentials returned 403 errors even though the Cloud Run Job service account could use Vertex AI. We configured the deployed worker with the appropriate service-account path and kept a Gemini API key in Secret Manager as a controlled fallback.
Finally, the first operations desk remembered run IDs only in browser session storage. A fresh browser appeared empty even though Firestore already contained the runs. We addressed the history experience so persisted records can be inspected rather than treating the browser as the database.
Accomplishments we are proud of
ProofPatch is live on an existing Google Cloud billing account rather than depending on the separate hackathon credit. It uses scale-to-zero Cloud Run services and Cloud Run Jobs, with no GPUs required.
A load wave of nine intakes reached VERIFIED. We also exercised the recovery path from FAILED to RETRYING to VERIFIED without auto-approval, and duplicate approval remained blocked. Historical Firestore records, including run 7303fba9… at NEEDS_APPROVAL, remain inspectable through the live system.
We restyled the Harbor Commons fixture as a dock kitchen and measured it again. The planted accessibility defects remained deliberately reproducible: an unnamed donate button and low-contrast .fine-print. This gives the system a stable, honest target rather than a moving demo page.
What we learned
Judges copy the first command in the README. If that command uses the wrong token, the product effectively does not exist for them.
VERIFIED must be a stored, reproducible exact check—not a persuasive paragraph generated by a model. The evidence needs to include the measurement details and artifacts that support the state transition.
We also learned that source/runtime alignment is part of the product. If GitHub and Cloud Run describe different versions, even a working hosted path becomes difficult to trust.
What is next for ProofPatch
After the hackathon, the product roadmap is to add real ownership so dev-token is no longer the entire authentication model, implement Firestore retention and archival to match the 14-day Cloud Storage lifecycle, and maintain an isolated crash-demo revision for demonstrating FAILED → RETRYING → VERIFIED without exposing failure injection to every user.
ProofPatch’s core principle will remain unchanged: an agent may investigate and propose, but durable evidence, human approval, deterministic application, and exact re-measurement decide whether a patch is verified.
Log in or sign up for Devpost to join the conversation.