From cdc56544c94d63fff595e4db397f459d46303d2b Mon Sep 17 00:00:00 2001 From: rachaelrenk Date: Fri, 10 Jul 2026 08:05:15 +0000 Subject: [PATCH] AFDocs fixes: refresh known-exceptions allowlist for page-size and parity The AFDocs audit (score 74/100, C) surfaced page-size-markdown and page-size-html hard-fails driven by intentionally-long pages (open-source-licenses auto-generated licenses, current-year changelog, privacy legal text), plus a single-page markdown-content-parity fail (Turndown escaping false positive). All automatable remediations (llms.txt directive, .md URLs, content-negotiation middleware, mcp.json, 100% coverage) are already in place; the remaining failures are allowlisted platform limits or editorial page-size decisions the afdocs-fix skill explicitly does not auto-fix. Updates the stale known-exceptions.md so future audits classify these correctly. Co-Authored-By: Oz --- .../references/known-exceptions.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/.agents/skills/afdocs-audit/references/known-exceptions.md b/.agents/skills/afdocs-audit/references/known-exceptions.md index 05eb819d1..a233305e0 100644 --- a/.agents/skills/afdocs-audit/references/known-exceptions.md +++ b/.agents/skills/afdocs-audit/references/known-exceptions.md @@ -22,8 +22,8 @@ This file lists checks from the afdocs-audit skill that may flag as warnings or ## markdown-content-parity -**Expected status**: warn (several pages, ~2% average difference) -**Reason**: False positive. The "missing" segments are numbered heading text like "2. Tabbed File Viewer" where Turndown correctly escapes the period (`### 2\. Tabbed File Viewer`) to prevent markdown parsers from interpreting it as a list item. The content IS present in the markdown — the AFDocs checker's text comparison doesn't account for markdown escaping. +**Expected status**: warn or fail (varies by sample; a single flagged page can tip the check to fail) +**Reason**: False positive. The "missing" segments are numbered heading text like "2. Tabbed File Viewer" where Turndown correctly escapes the period (`### 2\. Tabbed File Viewer`) to prevent markdown parsers from interpreting it as a list item. The content IS present in the markdown — the AFDocs checker's text comparison doesn't account for markdown escaping. The specific page(s) flagged vary run to run because AFDocs samples a subset of pages. **Affected pages** (as of 2026-05-05): - `/platform/triggers/scheduled-agents-quickstart/` — step headings - `/platform/integrations/github-actions/` — numbered use case headings @@ -45,11 +45,15 @@ This file lists checks from the afdocs-audit skill that may flag as warnings or ## page-size-markdown / page-size-html -**Expected status**: pass for page-size-markdown; warn for page-size-html (`all-settings.mdx` only) -**Reason**: The changelog was split into yearly pages in May 2026, resolving the markdown page-size issue. `all-settings.mdx` may still appear in `page-size-html` at 50,088 markdown chars — 88 chars over the 50K warn threshold. This is the comprehensive settings reference page; splitting it would harm usability for a trivial overage. -**Affected pages** (as of 2026-06-24): -- `/terminal/settings/all-settings/` — settings reference (50,088 md chars, borderline warn) -**Action**: Monitor. If it grows substantially past 50K, consider splitting by TOML section. For now, accept as a known exception for the borderline HTML page-size warning. +**Expected status**: fail (both checks can fail as intentionally-long reference pages grow) +**Reason**: A small set of pages are intentionally long and cannot be meaningfully split. They now exceed the AFDocs 100K-char hard-fail threshold, so `page-size-markdown` and/or `page-size-html` fail on any run that samples one of them. The `afdocs-fix` skill explicitly treats page-size as a do-not-auto-fix editorial concern. +**Affected pages** (as of 2026-07-10): +- `/support-and-community/community/open-source-licenses/` — auto-generated third-party license text (~1.37M md chars). Regenerated by the `release_updates` skill; any manual split would be overwritten. Drives the `page-size-html` max (396K HTML → 121K markdown). +- `/changelog/2026/` — current-year changelog (~113–130K md chars). Already split by year; the current year grows until year-end rollover. Drives the `page-size-markdown` failure. +- `/support-and-community/privacy-and-security/privacy/` — comprehensive privacy/legal content (~113K md chars). Kept whole for legal completeness. +- `/terminal/settings/all-settings/` — comprehensive settings reference. Below the 100K threshold as of this date but historically borderline; monitor. +**Sampling note**: AFDocs samples ~49–50 of ~345 sitemap pages per run, so which of these large pages surfaces (and whether a check reports fail or warn) varies between runs. Counts in the report will fluctuate accordingly. +**Action**: No fix. These pages are intentionally long (auto-generated, current-year changelog, or legal). Do not split. Re-evaluate `/changelog/2026/` at year-end when it rolls over to `/changelog/2027/`. ## section-header-quality