Last reviewed: 2026-07-08; corrected in review 2026-07-09. Base branch: main.
Review correction (2026-07-09). The original sweep's link checker ran on a case-insensitive filesystem, so it passed two links in
docs/README.md(ROADMAP.md,ACCESSIBILITY.md) that resolve to nothing on GitHub's case-sensitive hosting; both are fixed. The sweep also edited the vendoreddocs/standards/README.md, which is pinned byte-identical toChelseaKR/portfolio-standards(tagv1.0.1at the time of this audit;v2.0.0since 2026-08-09) and must never be edited in-repo (DOC-03;standards-pin.ymlenforces this once its token exists). That edit is reverted here. Its two relative links (AUDIT-2026-06-21.md,IMPROVEMENTS-BACKLOG.md) resolve in the upstream repo, not this one; that is a property of vendoring, is excluded from this audit's unresolved-link count, and any fix belongs upstream. A case-sensitive re-check on 2026-07-09 over root Markdown,.githubtemplates, anddocs/**minus the vendoreddocs/standards/found 208 relative links, 0 unresolved after these fixes.
This audit records the documentation sweep and remediation loop for this repository. It 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.
| Area | Result | Evidence |
|---|---|---|
| Entry docs | pass | README.md present |
| Security/process docs | pass | CONTRIBUTING.md, SECURITY.md, CHANGELOG.md |
| Architecture/planning docs | pass | 2 architecture/interface docs; 17 planning/research docs |
| Safety/privacy/audit docs | pass | 5 safety/privacy/accessibility/audit docs |
| Validation surface | pass | 102 test files; 23 workflow files |
| Local doc links | pass | 208 relative links re-checked case-sensitively 2026-07-09 (vendored docs/standards/ excluded); 0 unresolved |
This section covers hand-authored documentation at the repository root and root-adjacent GitHub templates. It is separate from the docs/ inventory so README, process, legal, release, and project-specific root files do not get hidden inside the larger docs tree.
| Surface | Result | Evidence |
|---|---|---|
| Root README | pass | Present: README.md |
| Root process docs | pass | Present: CONTRIBUTING.md, SECURITY.md, CHANGELOG.md |
| Root legal, citation, and conduct docs | pass | Present: LICENSE, NOTICE, CITATION.cff, CODE_OF_CONDUCT.md |
| Other root project docs | info | CLAUDE.md |
| Root-adjacent GitHub templates | pass | .github/PULL_REQUEST_TEMPLATE.md, .github/CODEOWNERS, .github/ISSUE_TEMPLATE/accessibility.md |
| Root/template doc links | pass | 63 root-level/template links checked; 0 unresolved |
Root-level files checked:
CHANGELOG.mdCITATION.cffCLAUDE.mdCODE_OF_CONDUCT.mdCONTRIBUTING.mdLICENSENOTICEREADME.mdSECURITY.md
Root-adjacent template files checked:
.github/PULL_REQUEST_TEMPLATE.md.github/CODEOWNERS.github/ISSUE_TEMPLATE/accessibility.md
- Added missing root-level remediation docs found by the audit loop, including legal, conduct, contribution, or security files where absent.
- Added
docs/PROJECT-SCOPE.mdas the plain-language project and boundary map. - Added this audit record so future doc changes have a dated baseline.
- Added or refreshed the docs index so scope, audit, and primary docs are easy to find.
- Fixed or added root/doc remediation files:
.github/PULL_REQUEST_TEMPLATE.md,NOTICE. - Did not keep the sweep's edit to
docs/standards/README.md: that file is vendored and pinned; the edit was reverted in review (see the correction note above).
Package and workspace metadata:
pipeline/pyproject.toml(the Python package and single version source; seeREADME.mdVersioning). The web frontend is vanilla JS with no package manifest.
Source and operations surfaces seen at the repo root:
data/infra/Makefilepipeline/scripts/web/
Workflow files checked:
.github/workflows/a11y.yml.github/workflows/canada-equity.yml.github/workflows/ci.yml.github/workflows/codeql.yml.github/workflows/dataset-release.yml.github/workflows/discover.yml.github/workflows/e2e.yml.github/workflows/equity.yml.github/workflows/mutation.yml.github/workflows/onboard.yml.github/workflows/openssf-scorecard.yml.github/workflows/otp-qa.yml.github/workflows/pages.yml.github/workflows/refresh.yml.github/workflows/rt-archive.yml.github/workflows/rt-monitor.yml.github/workflows/scorecard.yml.github/workflows/security.yml.github/workflows/standards-pin.yml.github/workflows/tiles.yml.github/workflows/trufflehog.yml.github/workflows/validator-canary.yml.github/workflows/watchdog.yml
| Category | Count | Representative files |
|---|---|---|
| architecture and interfaces | 2 | docs/api.md, docs/decisions/0013-static-public-api.md |
| entry points and repo process | 11 | .github/CODEOWNERS, .github/ISSUE_TEMPLATE/accessibility.md, .github/PULL_REQUEST_TEMPLATE.md, CHANGELOG.md, CITATION.cff, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, plus 3 more |
| operations and release | 3 | docs/deploy.md, docs/fixes/fast_travel_between_consecutive_stops.md, docs/fixes/fast_travel_between_far_stops.md |
| other docs | 94 | CLAUDE.md, docs/OTP_WIRING_PATTERN.md, docs/PROJECT-SCOPE.md, docs/README.md, docs/SIDE_BY_SIDE_COMPARE_DESIGN.md, docs/add-your-agency.md, docs/ci-action.md, docs/conformance.md, plus 86 more |
| planning and research | 17 | docs/INTERACTIVITY-ROADMAP.md, docs/RESEARCH-ROADMAP.md, docs/USER-RESEARCH.md, docs/decisions/0030-data-plane-history-remediation.md, docs/expansion-ideation-2026-07.md, docs/expansion-research-2026-07.md, docs/expansion-research.md, docs/feature-roadmap.md, plus 9 more |
| safety, privacy, accessibility, and audits | 5 | docs/DOCUMENTATION-AUDIT.md, docs/accessibility-testing.md, docs/accessibility.md, docs/decisions/0006-accessibility-sub-score.md, docs/standards-proposal-2026-07-05-accessibility.md |
| grouped generated/source content | 12 | docs/standards/ counted as a content group, not listed file by file |
| grouped generated/source content | 41 | pipeline/tests/fixtures/golden_site/ counted as a content group, not listed file by file |
| grouped generated/source content | 1 | web/agencies/ counted as a content group, not listed file by file |
| grouped generated/source content | 4532 | web/agency/ counted as a content group, not listed file by file |
| grouped generated/source content | 1 | web/data/ counted as a content group, not listed file by file |
Full hand-authored doc inventory checked by this pass:
.github/CODEOWNERS.github/ISSUE_TEMPLATE/accessibility.md.github/PULL_REQUEST_TEMPLATE.mdCHANGELOG.mdCITATION.cffCLAUDE.mdCODE_OF_CONDUCT.mdCONTRIBUTING.mdLICENSENOTICEREADME.mdSECURITY.mddocs/DOCUMENTATION-AUDIT.mddocs/INTERACTIVITY-ROADMAP.mddocs/OTP_WIRING_PATTERN.mddocs/PROJECT-SCOPE.mddocs/README.mddocs/RESEARCH-ROADMAP.mddocs/SIDE_BY_SIDE_COMPARE_DESIGN.mddocs/USER-RESEARCH.mddocs/accessibility-testing.mddocs/accessibility.mddocs/add-your-agency.mddocs/api.mddocs/ci-action.mddocs/conformance.mddocs/crosswalk.mddocs/decisions/0001-validator-runtime.mddocs/decisions/0002-artifacts-to-s3.mddocs/decisions/0003-fan-out-compute.mddocs/decisions/0004-opt-in-alerts.mddocs/decisions/0005-competitive-positioning.mddocs/decisions/0006-accessibility-sub-score.mddocs/decisions/0007-gtfs-flex-awareness.mddocs/decisions/0008-fares-v2-awareness.mddocs/decisions/0009-pathways-levels-awareness.mddocs/decisions/0010-update-cadence.mddocs/decisions/0011-mobility-feed-api-reuse.mddocs/decisions/0012-realtime-monitoring-cron.mddocs/decisions/0013-static-public-api.mddocs/decisions/0014-routing-qa-without-otp.mddocs/decisions/0015-equity-overlay-state-level.mddocs/decisions/0016-ntd-id-alignment.mddocs/decisions/0017-persona-surfaces.mddocs/decisions/0018-national-rt-and-ntd-crosswalk.mddocs/decisions/0019-national-problems-kb.mddocs/decisions/0020-national-quality-trend.mddocs/decisions/0021-ridership-weighting.mddocs/decisions/0022-equity-choropleth.mddocs/decisions/0023-national-all-routes-pmtiles.mddocs/decisions/0024-validator-rule-links.mddocs/decisions/0025-access-to-opportunity-scope.mddocs/decisions/0026-internationalization.mddocs/decisions/0027-canada-equity-cimd.mddocs/decisions/0028-global-south-pilot.mddocs/decisions/0029-instant-score-funnel.mddocs/decisions/0030-data-plane-history-remediation.mddocs/decisions/0030-honesty-primitives-standard.mddocs/decisions/0030-signage-visual-identity.mddocs/decisions/0031-observability-tier.mddocs/decisions/0032-repo-layout.mddocs/decisions/0033-branch-protection-ruleset.mddocs/deploy.mddocs/expansion-ideation-2026-07.mddocs/expansion-research-2026-07.mddocs/expansion-research.mddocs/expansion.mddocs/feature-roadmap.mddocs/feed-discovery.mddocs/feed-supersessions.mddocs/feeds.mddocs/fixes/README.mddocs/fixes/expired_calendar.mddocs/fixes/fast_travel_between_consecutive_stops.mddocs/fixes/fast_travel_between_far_stops.mddocs/fixes/feed_expiration_date30_days.mddocs/fixes/feed_expiration_date7_days.mddocs/fixes/invalid_currency_amount.mddocs/fixes/missing_feed_contact_email_and_url.mddocs/fixes/missing_recommended_field.mddocs/fixes/missing_recommended_file.mddocs/fixes/missing_required_column.mddocs/fixes/missing_timepoint_value.mddocs/fixes/mixed_case_recommended_field.mddocs/fixes/route_color_contrast.mddocs/fixes/scorecard_feed_expired.mddocs/fixes/scorecard_feed_expiring_soon.mddocs/fixes/scorecard_flex_no_booking_rules.mddocs/fixes/scorecard_missing_feed_info_dates.mddocs/fixes/scorecard_missing_headsigns.mddocs/fixes/scorecard_no_fare_data.mddocs/fixes/scorecard_no_feed_contact.mddocs/fixes/scorecard_rt_service_alerts_unreachable.mddocs/fixes/scorecard_rt_trip_coverage.mddocs/fixes/scorecard_rt_trip_updates_unreachable.mddocs/fixes/scorecard_rt_vehicle_positions_unreachable.mddocs/fixes/scorecard_station_no_pathways.mddocs/fixes/scorecard_stop_names_all_caps.mddocs/fixes/scorecard_wheelchair_accessible_unknown.mddocs/fixes/scorecard_wheelchair_boarding_unknown.mddocs/fixes/service_has_no_active_day_of_the_week.mddocs/fixes/service_window_outside_feed_period.mddocs/fixes/stop_too_far_from_shape.mddocs/fixes/stop_too_far_from_shape_using_user_distance.mddocs/fixes/stop_without_stop_time.mddocs/fixes/trip_coverage_not_active_for_next7_days.mddocs/fixes/trip_distance_exceeds_shape_distance_below_threshold.mddocs/fixes/unknown_column.mddocs/fixes/unknown_file.mddocs/fixes/unused_shape.mddocs/follow-ups.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/lint-complexity-ratchet.mddocs/listing-policy.mddocs/mcp.mddocs/mutation-testing.mddocs/product-roadmap.mddocs/roadmap.mddocs/rubric.mddocs/section-508-plan.mddocs/service-plan.mddocs/standards-conformance-gaps.mddocs/standards-contribution/HONESTY-AS-A-FEATURE.mddocs/standards-proposal-2026-07-05-accessibility.mddocs/supersession-flagging.mddocs/vpat.mdinfra/README.mdpipeline/tests/goldens/robots.txtweb/llms.txtweb/robots.txt
Grouped content counts:
docs/standards/: 12 filespipeline/tests/fixtures/golden_site/: 41 filesweb/agencies/: 1 filesweb/agency/: 4532 filesweb/data/: 1 files
- Original sweep (2026-07-08): 328 local links checked in authored Markdown docs, case-insensitively.
- Review re-check (2026-07-09): 208 relative links checked case-sensitively across root Markdown,
.githubtemplates, anddocs/**excluding the vendoreddocs/standards/; the count differs from the original sweep because the scopes differ (the re-check excludes vendored standards and counts only relative links, not anchors or external URLs). - Unresolved authored-doc links after remediation and review fixes: 0.
- Root-level/template unresolved links after remediation: 0.
Audit scope notes:
- Generated sites, deployed app routes, raw third-party HTML captures, and golden fixture websites were inventoried as product or data surfaces but excluded from authored-doc link failure counts.
- The vendored
docs/standards/*.mdfiles are pinned byte-identical to upstream and excluded from in-repo link remediation; their relative links resolve inChelseaKR/portfolio-standards. - Grouped content directories are counted rather than listed file by file, so they stay visible without flooding the inventory.
- The audit was generated from a clean worktree based on
origin/mainfor this PR branch. - Ran a local relative-link check over hand-authored Markdown and MDX docs.
- Ran an explicit root-level documentation presence and link check for README, process, legal, project, and template docs.
- Ran
git diff --checkacross the PR worktrees after remediation. - Product test suites remain the authority for runtime behavior; this PR changes documentation only.