Skip to main content

Local QA Docs Index Verification

Script: scripts/qa/verify_docs_index.py

The docs-index verifier guards discoverability of the QA system. Every top-level QA doc and every manual checklist must be linked from docs/private-docs/docs/qa/checklists/README.md, so a tester can start from one place and find the whole local QA battery.

Command​

./scripts/local-validation/qa.sh test docs-index

This scope is also part of:

./scripts/local-validation/qa.sh test governance

Retired ledger docs are intentionally not included in the index contract. The canonical entry point is scripts/test-local.sh; the checklist README links the retained lower-level QA docs and every manual checklist.

What It Checks​

  • every docs/private-docs/docs/qa/*.md file is linked under Supporting QA docs
  • every checklist file under docs/private-docs/docs/qa/checklists/ is listed in the Checklist Index table
  • the checklist index does not point at missing top-level QA docs
  • the checklist index does not point at missing checklist docs
  • local Markdown links inside QA docs resolve to existing files
  • repository-root Markdown links to docs/private-docs/ or docs/public-docs/ resolve to existing files
  • QA Markdown has balanced fenced code blocks, non-skipping heading levels, and no duplicate headings within a file

Manual Follow-Up​

When docs content, static assets, sidebars, generated API docs, or MDX component usage changes, complete docs-build-render.md after this command. Record the private docs Bazel build, any public docs build command used, direct URL render checks, sidebar/category traversal, and image/MDX evidence.

Boundary​

This proves that QA documentation is reachable from the checklist index. It also catches common Docusaurus-adjacent render drift before a docs build. It does not prove the checklist contents are complete or that every Docusaurus plugin transforms successfully; those stay covered by ./scripts/local-validation/qa.sh test checklists, the manual docs build/render checklist, docs build validation, and lane owner handoff.