[quality] test: executed coverage for docs-checks.py main() — new tests/unit/test_docs_checks_main.py

[kubestellar-hive]

Test Improvement

Adds one new file, tests/unit/test_docs_checks_main.py, giving executed coverage to main() in .github/scripts/docs-checks.py — the entry point .github/workflows/docs-checks.yml invokes.

Exact surface claimed

• File added: tests/unit/test_docs_checks_main.py (new)
• Function under test: main() in .github/scripts/docs-checks.py, lines 155-182
• Files modified: none. No production code changes.

This PR deliberately does not touch tests/unit/test_docs_checks.py (the existing helper-level suite), tests/unit/test_k0s_manifests.py, or tests/unit/test_kubestellar_kiosk.py.

Why

tests/unit/test_docs_checks.py drives the validator helpers directly — load_fm, validate_frontmatter, check_budget, check_stale_flags, check_internal_links, validate_skill — and never runs the orchestration that wires them together. Measured before:

.github/scripts/docs-checks.py   136  24  82%   155-182, 186

A regression that drops a budget target, stops iterating the docs/skills/ glob after the first entry, or loses the sys.exit(1) would leave the docs-checks workflow green while checking less.

What the 42 cases assert

• clean tree passes with Docs checks passed. and no FAIL/WARN; an empty docs/skills/ is not an error
• exit 1 plus an Errors:/FAIL line for an invalid skill, a skill with no front-matter, and for every failing skill (not just the first)
• every skill under docs/skills/ is validated — a bad zzz- skill is reported while clean aaa-/mmm- siblings are not
• warnings print but still exit 0; both sections appear when warnings and errors accumulate together
• the five budget targets, parametrised at limit+5 (error), limit (inclusive, clean), warn+1 (warn only) and warn (silent): AGENTS.md 200/150, README.md 200/150, CONTRIBUTING.md 100/80, docs/MVP_1_0_READINESS.md 250/200, docs/DOCUMENTATION_OVERHAUL_PLAN.md 3000/2500
• stale-flag scope: TODO:/draft markers rejected in AGENTS.md/README.md/CONTRIBUTING.md, allowed in the exempt planning docs, and DOCUMENTATION_OVERHAUL_PLAN.md confirmed outside the stale-flag list entirely
• internal-link scope: broken links rejected in skills and top-level docs, resolvable/external/anchor links accepted, and DOCUMENTATION_OVERHAUL_PLAN.md confirmed outside the link-check list
• errors/warnings module globals do not leak across two consecutive main() runs

No new fixtures: the existing docs_checks fixture in tests/unit/conftest.py already repoints ROOT/DOCS_DIR/SKILLS_DIR at tmp_path and clears the globals.

Verification

$ python -m pytest tests/unit -q
247 passed, 1 xfailed

$ python -m coverage report -m
.github/scripts/docs-checks.py   136   1  99%   186

82% → 99%. The one remaining line is the if __name__ == "__main__": guard.

Related Issue

Closes #105

---

Filed by quality agent (hold-gated mode). Human review required.

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.78