US-PAGES requirements¶
Every requirement this specification owns, with the proof that closes it. Delivery state and
public evidence for each ID are recorded in status.json; this file defines what
each ID means. The design is in spec.md and plan.md, the test contract
in test-spec.md, and the work order in tasks.md.
| ID | Requirement | Verification |
|---|---|---|
US-PAGES-R002 |
Consolidate published documentation. GitHub Pages serves as the readable view of this repository's skill catalog, contribution workflow, and relevant specifications, while every page's content stays sourced from one canonical tracked file in Git rather than a duplicated copy. Caller chain: .github/workflows/pages.yml:13 calls the shared pages_pipeline.yml, which builds MkDocs with the hook on_files (scripts/pages_sources.py:118); the hook publishes root guides and the spec package from their tracked files through public_links (scripts/pages_sources.py:16) and status_markdown (:41). Shape: files scripts/pages_sources.py, mkdocs.yml (hooks at :55) and CONTRIBUTING.md; the build holds generated pages in memory only, so no second copy exists; reuse File.generated of MkDocs. |
A Pages build check confirms the navigation's internal links resolve and that editing the canonical tracked document updates the published view without a manual copy. Test: tests/pages_contracts.py::test_canonical_sources_and_existing_urls and tests/pages_contracts.py::test_invalid_sources_fail_closed. |
US-PAGES-R001 |
Shared documentation hierarchy across the fleet's sites. universal-skills' published skill catalog and specifications follow the same reusable navigation and content hierarchy, assembled from the shared Pages template and workflow, used by the documentation sites of the other core ecosystem repositories, so a reader moving between them finds the same structure. Caller chain: a push of a v* tag or a manual dispatch starts .github/workflows/pages.yml:13, which calls the shared pages_pipeline.yml; MkDocs then reads the navigation in mkdocs.yml and the hook on_files (scripts/pages_sources.py:118). Shape: add a navigation and link-structure check as a new test in tests/pages_contracts.py that compares the nav tree of mkdocs.yml with the shared template; align the nav entries in mkdocs.yml to that template; reuse the checkout and build fixtures (tests/pages_contracts.py:16, :48). |
A cross-site navigation and link-structure check confirms this repository's published hierarchy matches the shared template used across the fleet's documentation sites. Test: planned tests/pages_contracts.py::test_navigation_matches_shared_template (see test-spec.md). |