ci: guard docs drift — mkdocs --strict as a PR check + link/anchor validation#126
Merged
Conversation
Full-lane spec (design.md + plan.md) plus a decision recording why doc code-fence validation is deliberately out of scope. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The guard binds on the longest derived identifier (an index/constraint name like <table>_pending_idx), not the shorter NOTIFY channel outbox_<table>. Same wording fixed in docs/operations/checklist.md by the 2026-07-05 docs audit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a PR-time guard against the documentation-drift class that the 2026-07-05 docs audit (#125) surfaced. Spec + rationale in
planning/changes/2026-07-05.01-docs-ci-drift-guard/.Problem
mkdocs build --strictruns only indocs.ymlon push tomain(for deploy), so a PR that breaks an internal link or orphans a page isn't caught until after merge. Broken#anchorfragments aren't caught at all, anddocs/requirements.txtis unpinned (CI already warned about a breaking MkDocs 2.0).Change
mkdocs.yml— add avalidation:block (omitted_files/absolute_links/unrecognized_links/anchors: warn); under--strictthese become errors, so broken links and#anchorfragments now fail the build. (mkdocs 1.6.1.) Verified with a negative test: a bad anchor aborts the build; the clean tree passes..github/workflows/_checks.yml— new paralleldocsjob runningjust docs-build, the same command as the deploy build, so PR-time and deploy-time can't diverge.docs/requirements.txt— pinmkdocs>=1.6,<2,mkdocs-material>=9,<10for a reproducible, MkDocs-2.0-proof build.faststream_outbox/schema.py— fix themake_outbox_tabledocstring: the 63-byte guard binds on the longest derived identifier (an index name like<table>_pending_idx), not the shorter NOTIFY channel. Closes at the source the same wording the audit fixed inchecklist.md.Deliberately out of scope
No validation of Python inside
docs/code fences (syntax/type/execute) — the cost and false-positive noise on intentional fragments outweigh the value. Recorded with a revisit trigger inplanning/decisions/2026-07-05-no-doc-code-fence-validation.md.README audit (#3)
Audited
README.md(outsidedocs_dir, so not covered by the guard) against source + docs: all code samples, symbols, kwargs, extras, and links verified — no drift found. One non-blocking note: README says idle latency "sub-100ms" where the docs give the tighter "~10ms"; left as a conservative claim.🤖 Generated with Claude Code