This audit checks the docs as a system: entry points, root-level process and legal files, project scope, setup and validation notes, safety and privacy posture, architecture and planning docs, local links, and the places where code, tests, workflows, and docs meet.
Everything below the marker is generated from the tree by
tools/doc_audit.py. Run make docs-audit to regenerate it;
make docs-audit-check and tests/test_doc_audit.py fail the build if
the committed block has drifted from the repository. The counts are therefore never older than the
commit that ships them.
That is the point of this rewrite. The previous version of this file was hand-typed on 2026-07-08 and
nothing regenerated or checked it, so its pass verdicts stayed while its evidence went stale. By
2026-08 its test-file count was low by roughly 3x, its workflow list named four of six — omitting the
daily live-site sentinel and the signed release pipeline, the two an outside reviewer would most want
to see audited — and its architecture-doc count was smaller than the ADR directory alone. A document
published to show that this project's process claims are real had become a validation surface
reporting success about records it no longer inspected, which is the exact failure this repository's
other gates exist to prevent.
Two things the generator deliberately does not do:
- It does not print
passfor a count. A presence check and a link check are predicates and can pass or fail. "100 test files" is an inventory number, not a verdict, and the old table's standingpasson a "Validation surface" row whose evidence was a test-file count borrowed authority the number never had. Counts are reported as inventory. - It does not stamp a date. A generated timestamp would drift every day and make the drift check meaningless; git already dates the file. The dated narrative of the original sweep is kept below, outside the generated block, where it reads as history rather than as a current verdict.
- Generated sites, deployed app routes, raw third-party HTML captures, and golden fixture websites are product or data surfaces, not authored documentation, and are excluded from the inventory and the link counts.
docs/standards/is vendored from the portfolio standards repository. It is counted as a content group rather than listed file by file, so it stays visible without swamping the inventory.- The link check covers relative Markdown links only. External URLs are not fetched: this gate is about links that must resolve inside the tree, and a network check would make it non-deterministic.
2026-07-08 sweep (historical record, not a current verdict). That pass:
- added the missing root-level legal, conduct, contribution, and security files it found absent;
- added
docs/PROJECT-SCOPE.mdas the plain-language project and boundary map; - added the first version of this audit record so future doc changes had a dated baseline;
- added or refreshed the docs index so scope, audit, and primary docs were easy to find;
- added
docs/standards/README.md.
2026-08-14. Replaced the hand-typed tables with the generated block below, after the counts were found to be roughly 3x out of date with nothing in the repository able to refresh or contradict them.
Everything between these markers is generated by tools/doc_audit.py from the tree at this commit. Do not edit it by hand: run make docs-audit. make docs-audit-check (and tests/test_doc_audit.py) fail if it has drifted.
These are real predicates, so they can pass or fail.
| Check | Result | Evidence |
|---|---|---|
| Entry doc | pass | README.md |
| Root process docs | pass | CONTRIBUTING.md, SECURITY.md, CHANGELOG.md |
| Root legal, citation, and conduct docs | pass | LICENSE, NOTICE, CITATION.cff, CODE_OF_CONDUCT.md |
| Root-adjacent GitHub templates | pass | .github/PULL_REQUEST_TEMPLATE.md, .github/CODEOWNERS |
| Local doc links resolve | pass | 446 relative links checked in 91 Markdown files; 0 unresolved |
Counts, not verdicts. A count cannot pass or fail; it can only be current, which is what generating it from the tree buys.
| Surface | Count | Evidence |
|---|---|---|
| Hand-authored docs | 95 | Markdown at the repository root and under docs/, data/, infra/, notebooks/, schema/, src/, tests/, web/, plus the root legal and template files |
| Test files | 107 | tests/test_*.py |
| Workflow files | 6 | .github/workflows/*.yml |
| Grouped/vendored doc content | 16 | docs/standards/ (16) |
Up to 5 representative files per category; the complete list follows below.
| Category | Count | Representative files |
|---|---|---|
| architecture and interfaces | 16 | docs/adr/0000-record-architecture-decisions.md, docs/adr/0002-exposure-normalization-and-confidence-intervals.md, docs/adr/0003-pure-python-statistics-and-planar-geometry.md, docs/adr/0004-standards-applicability.md, docs/adr/0005-build-pages-artifact-before-deployment.md, plus 11 more |
| entry points and repo process | 11 | .github/CODEOWNERS, .github/PULL_REQUEST_TEMPLATE.md, CHANGELOG.md, CITATION.cff, CODE_OF_CONDUCT.md, plus 6 more |
| examples and guides | 4 | docs/teaching/FACILITATOR-GUIDE.es.md, docs/teaching/FACILITATOR-GUIDE.md, notebooks/README.md, notebooks/teaching/README.md |
| other docs | 43 | benchmarks/README.md, benchmarks/SCORECARD.md, data/README.md, data/published/davis-ranked.md, data/published/davis-sensitivity.md, plus 38 more |
| planning and research | 9 | docs/RESEARCH-ROADMAP.md, docs/ROADMAP.md, docs/ideation/01-deep-dive.md, docs/ideation/02-large-scale-fixes.md, docs/ideation/03-expansions.md, plus 4 more |
| safety, privacy, accessibility, and audits | 12 | docs/ACCESSIBILITY.md, docs/DOCUMENTATION-AUDIT.md, docs/DPIA.md, docs/INTAKE-AND-ABUSE.md, docs/RE-IDENTIFICATION.md, plus 7 more |
.github/workflows/ci.yml.github/workflows/live-integrity.yml.github/workflows/mutation.yml.github/workflows/release.yml.github/workflows/scorecard.yml.github/workflows/secret-scan-scheduled.yml
- Node workspace
web/package.json(scripts: axe, contract, rtl). - Python package
nearmiss(>=3.11).
.github/CODEOWNERS.github/PULL_REQUEST_TEMPLATE.mdCHANGELOG.mdCITATION.cffCODE_OF_CONDUCT.mdCONTRIBUTING.mdDEFINITION_OF_DONE.mdLICENSENOTICEREADME.mdSECURITY.mdbenchmarks/README.mdbenchmarks/SCORECARD.mddata/README.mddata/published/davis-ranked.mddata/published/davis-sensitivity.mddata/published/preregistration/README.mddata/published/riverside-ranked.mddata/published/riverside-sensitivity.mddocs/ACCESSIBILITY.mddocs/ADAPTING.mddocs/BRAND.mddocs/CLAIMS.mddocs/COUNTY-DRILLDOWN-IMPLEMENTATION-PLAN.mddocs/COVERAGE-TIERS.mddocs/DATA-CARD.mddocs/DECISION-DOSSIER-TEMPLATE.mddocs/DECISION-DOSSIER.mddocs/DOCUMENTATION-AUDIT.mddocs/DPIA.mddocs/I18N.mddocs/INGESTION.mddocs/INTAKE-AND-ABUSE.mddocs/LIMITATIONS.mddocs/LIVE-INTEGRITY.mddocs/METHODOLOGY.mddocs/MUTATION-TESTING.mddocs/PERFORMANCE.mddocs/PREREGISTRATION.mddocs/PRIVATE-COUNTY-CROSSWALK-REVIEW.mddocs/PRODUCT-EXPANSION-PLAN.mddocs/PROJECT-SCOPE.mddocs/PUBLIC-COUNTY-ARTIFACT-CONTRACT.mddocs/PUBLIC-COUNTY-BOUNDARY-CONTRACT.mddocs/PUBLIC-COUNTY-RELEASE-INDEX-CONTRACT.mddocs/RE-IDENTIFICATION.mddocs/README.mddocs/REAL-DATA.mddocs/RESEARCH-ROADMAP.mddocs/RESPONSIBLE-TECH-AUDITS.mddocs/ROADMAP.mddocs/STATE-MAP-DRILLDOWN-PLAN.mddocs/SUBMISSIONS.mddocs/THREAT-MODEL.mddocs/USER-RESEARCH.mddocs/accessibility/ACR.mddocs/adr/0000-record-architecture-decisions.mddocs/adr/0002-exposure-normalization-and-confidence-intervals.mddocs/adr/0003-pure-python-statistics-and-planar-geometry.mddocs/adr/0004-standards-applicability.mddocs/adr/0005-build-pages-artifact-before-deployment.mddocs/adr/0006-separate-official-outcomes-from-contributor-reports.mddocs/adr/0007-content-addressed-fail-closed-ingestion.mddocs/adr/0008-normalize-local-fars-into-private-verified-artifacts.mddocs/adr/0009-separate-source-declaration-verification-and-triangulation.mddocs/adr/0010-schedule-read-only-live-integrity-verification.mddocs/adr/0011-version-public-fars-provenance-corrections.mddocs/adr/0012-solo-maintainer-provisional-review-attestation.mddocs/adr/0013-keep-python-311-floor.mddocs/adr/0014-county-fars-context-requires-a-verified-public-projection.mddocs/adr/0015-a-singleton-gi-star-neighborhood-is-labeled-and-never-significant.mddocs/audits/2026-06-16-verification.mddocs/audits/2026-07-16-national-evidence-studio-a11y.mddocs/audits/README.mddocs/findings/2026-08-15-potsdam-real-run.mddocs/findings/README.mddocs/ideation/01-deep-dive.mddocs/ideation/02-large-scale-fixes.mddocs/ideation/03-expansions.mddocs/ideation/04-impact-and-sequencing.mddocs/ideation/README.mddocs/privacy/exp-05-dp-segment-time-bands.mddocs/research/2026-06-17-bug-review-and-user-research.mddocs/research/2026-06-20-synthetic-user-interviews.mddocs/teaching/FACILITATOR-GUIDE.es.mddocs/teaching/FACILITATOR-GUIDE.mdinfra/README.mdintegrations/qgis/README.mdnotebooks/README.mdnotebooks/teaching/README.mdschema/dataset.schema.mdsrc/honest_rates/README.mdsrc/nearmiss/README.mdtests/README.mdweb/README.md