Skip to content

docs: enforce tab membership and redirect coverage in CI #398

Description

@dangrondahl

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.py checks integrity and shape, but nothing checks that a page belongs in the tab it sits under. Documentation grew to 61 pages across 8 groups with no rule to stop it.
  • Redirect discipline slips silently. /getting_started/service-accounts has a redirect and is still linked as a broken internal link from tutorials/working_with_controls.mdx, because mint broken-links does 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.py with 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 --check once the noise is understood.
  • Add redirect coverage to tests/: for every path in config/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" and item == "CLI Reference" (update-cli-nav.py:154-158).
  • Consider a test that every URL referenced from kosli-dev/cli and kosli-dev/server resolves. It needs a checked-in list rather than a live grep of sibling repos.
  • Update .claude/skills/doc-write/SKILL.md and CLAUDE.md with the new tab set and membership tests, and delete the warning telling authors to ignore the Tutorials label 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 Reference subtree.

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-write skill and CLAUDE.md describe the tab set that actually exists

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    automationWorkflow / CI automation taskscontentWriting, adding, or updating doc pagesdxDeveloper experience, tooling, process

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions