Skip to content

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

Open

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

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