Repository navigation
docs: enforce tab membership and redirect coverage in CI #398
Copy link
Copy link
Open
Labels
automationWorkflow / CI automation tasksWorkflow / CI automation taskscontentWriting, adding, or updating doc pagesWriting, adding, or updating doc pagesdxDeveloper experience, tooling, processDeveloper experience, tooling, process
Description
Phase 4 of #393. Make the structure hold without anyone policing it.
What's wrong
Two failure modes have already happened once and nothing prevents a repeat:
- The junk drawer re-forms.
audit_navigation.pychecks integrity and shape, but nothing checks that a page belongs in the tab it sits under.Documentationgrew to 61 pages across 8 groups with no rule to stop it. - Redirect discipline slips silently.
/getting_started/service-accountshas a redirect and is still linked as a broken internal link fromtutorials/working_with_controls.mdx, becausemint broken-linksdoes not follow redirects. Nothing in CI catches the inverse either: a moved page with no redirect at all.
Why it matters
Phases 0 to 3 are one-off cleanups. Without this phase they decay, and the next contributor faces the same "where does this go?" question the parent issue exists to answer.
Tasks
- Extend
scripts/audit_navigation.pywith a per-tab membership check. Each tab declares its one-sentence test and the page-path prefixes that satisfy it; a page under a tab it does not match is a finding. Advisory at first, promoted to--checkonce the noise is understood. - Add redirect coverage to
tests/: for every path inconfig/redirects.json, the destination resolves to a real page; and no page file has been moved in git history without a corresponding redirect. - Add a test asserting the load-bearing labels still exist, so an innocent rename cannot break the CLI doc sync:
tab == "Reference"anditem == "CLI Reference"(update-cli-nav.py:154-158). - Consider a test that every URL referenced from
kosli-dev/cliandkosli-dev/serverresolves. It needs a checked-in list rather than a live grep of sibling repos. - Update
.claude/skills/doc-write/SKILL.mdandCLAUDE.mdwith the new tab set and membership tests, and delete the warning telling authors to ignore theTutorialslabel once that group no longer exists.
URL impact
- No page files move — tooling only
- Page files move
Out of scope
- Do not add checks that fail the build on advisory shape findings. Shape has always been advisory and there are legitimate exceptions, notably the generated
Reference > CLI Referencesubtree.
Verification
-
python3 scripts/audit_navigation.py— the new membership check reports against the current tree -
python3 scripts/audit_navigation.py --check— still exit 0 on a clean tree -
python3 -m pytest tests/— new redirect and label tests pass, and fail when deliberately broken -
doc-writeskill andCLAUDE.mddescribe the tab set that actually exists
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
automationWorkflow / CI automation tasksWorkflow / CI automation taskscontentWriting, adding, or updating doc pagesWriting, adding, or updating doc pagesdxDeveloper experience, tooling, processDeveloper experience, tooling, process
Activity
docs: document the seven tabs and their membership tests
docs: document the seven tabs and their membership tests
docs: document the seven tabs and their membership tests