From 609e4ddf235a2ab4776219dd00a4f10b5a30bc7a Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 28 Jun 2026 10:29:11 +0000 Subject: [PATCH 1/2] Generate weekly documentation drift report Create a new file `Documentation drift report [2026-06-28].md` comparing README.md with whitepaper, examples, and fr1-checker, formatted by artifact pair as requested. Co-authored-by: g0ldf7 <134113303+g0ldf7@users.noreply.github.com> --- Documentation drift report [2026-06-28].md | 86 ++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 Documentation drift report [2026-06-28].md diff --git a/Documentation drift report [2026-06-28].md b/Documentation drift report [2026-06-28].md new file mode 100644 index 0000000..5cf90f9 --- /dev/null +++ b/Documentation drift report [2026-06-28].md @@ -0,0 +1,86 @@ +# Documentation drift report [2026-06-28] + +## README.md vs docs/whitepaper.md + +### [QUESTION] Design Principles Discrepancy + +The prompt suggests that `README.md` lists "WCAG 2.2 AA" and "semantic HTML5 +landmarks" as core design principles. However, a review of the files shows these +are completely absent from the README, though they appear in the white paper. + +- **`README.md` (lines 106-107)**: + > `Layer 3: Structured Data (schema.org, JSON-LD) → Level 1-3` + > `Layer 2: Semantic Structure (HTML5, ARIA, headings) → Level 1-3` +- **`docs/whitepaper.md` (line 1450)**: + > `- **WCAG 2.2**: BiModal Design's Layer 2 directly builds on and extends WCAG` +- **`docs/whitepaper.md` (line 771)**: + > `Use HTML5 landmarks and ARIA to communicate content structure:` This raises + > a question of whether the README should be updated to explicitly include + > WCAG 2.2 AA. + +### [VARIATION] Framework Maturity Levels + +The tables defining the Maturity Levels match identically in structure, +coverage, and success thresholds. No drift found. + +- **`README.md` (lines 296-302)**: Table lists Levels 0-4 (Infrastructure Ready + to Agent-Native). +- **`docs/whitepaper.md` (lines 1564-1570)**: Table is identical. + +### [VARIATION] Foundational Requirements (FR-1) + +The definition of FR-1 is consistent between the entry-point summary and the +white paper. + +- **`README.md` (line 197)**: + > `The foundational requirement: critical content must exist in the initial HTTP response. This is Layer 1 of defense in depth — the floor, not the ceiling.` +- **`docs/whitepaper.md` (lines 403, 448)**: + > `FR-1 remains the foundational requirement of BiModal Design.` + > `FR-1 is the floor, not the ceiling.` + +### [VARIATION] Key Research Findings + +The baseline numbers and improvement statistics match perfectly between the +documents. No drift. + +- **`README.md` (line 128)**: + > `- **35-50% baseline success** for Browser Automation agents on conventional UI, improving to **55-72%** with semantic structure and up to **75-88%** with structured data.` +- **`docs/whitepaper.md` (line 105)**: + > `| Browser Automation Success | 35-50% | 55-72% | 75-88% |` + +### [VARIATION] Citations + +The arXiv IDs and cited papers match exactly across both documents. + +- **`README.md` (lines 340-368)**: Cites identical arXiv IDs (e.g., + 2503.23350v4). +- **`docs/whitepaper.md` (lines 2068-2082)**: Mirrors the README citations. + +## README.md vs tools/validators/fr1-checker.js + +### [VARIATION] FR-1 Checker Implementation + +The `fr1-checker.js` implementation explicitly validates all the aspects +described in the README. No drift found. + +- **`README.md` (line 204)**: + > `- **fr1-checker.js** — comprehensive audit covering semantic content, navigation accessibility, form labels, heading hierarchy, ARIA landmarks, image alt text, and agent-specific features.` +- **`tools/validators/fr1-checker.js` (lines 155, 191, 213, 237, 245, 254)**: + Functions check headings, navigation, forms, images, landmarks, and agent + features respectively. + +## README.md vs examples/ + +### [VARIATION] Core Pattern Snippets vs Real Examples + +The examples in the `examples/` directory use slightly different patterns than +the inline snippet in the README, though both are valid. + +- **`README.md` (lines 166-168)**: + > `
` + > `

Wireless Headphones

` + > `