docs-disc phase1a: docs.schema.json + validate-docs.py (TDD)

[rafael5]

Summary

Lands rows P1.1, P1.2, P1.3 from the docs-discoverability phases tracker. Foundation for Phase 1 — schema + validator that the 7 tier-1/2 repos will adopt in their own P1.4/P1.5 sessions.

• P1.1 — profile/docs.schema.json: Draft 2020-12 schema for prose-doc frontmatter. 23-type doc_type enum + 5-state lifecycle enum + 6-vocab connections. Two variants (prose vs generated) gated on the generated field via if/then per spec §5.1.
• P1.2 — profile/repo.meta.schema.json: extended with optional docs.generated_paths array (enables §5.1 exclusion rule). Additive; no schema_compat bump (this schema isn't routing-layer).
• P1.3 — profile/build/validate-docs.py + 13 TDD'd cases: covers spec §9 checks 0–4 (generated-doc bidirectional path↔marker check, frontmatter present, required keys, doc_type enum, lifecycle enum). Skips docs/recipes/ (own schema; covered by recipes-check). --warn-only flag for the Phase 1 rollout.
• P1.3b (bonus self-check) — Makefile + .github/workflows/ci.yml: the meta-repo dogfoods the validator. make check-docs runs in CI in warn-only mode against .github/docs/. Surfaces 21 legitimate gaps (this repo wasn't in Phase 0's 7-repo backfill — to be addressed in P1.6) plus 1 real bug: cli-ux-plan.md uses SUMMARY, not in the 23-vocab.
• Tracker — P1.1/2/3/3b → done; Phase 1 row → in-progress; CI checks #0-4 → done; docs: add phase1-plan.md (org routing layer) #5-8 carved into new row P1.11 (validator-side follow-up).

Out of scope (separate sessions per "one session ↔ one repo" rule):

• P1.4 / P1.5 — per-repo make check-docs + CI step in each of the 7 tier-1/2 repos
• P1.6 / P1.7 — lifecycle / owner backfill across 108 docs
• P1.8 / P1.9 — m-stdlib docs.generated_paths declaration
• P1.11 — validator §9 checks 5–8 (git-derived field drift, README existence, orphan/dangling refs)

Test plan

• 13 new TDD cases in profile/build/test_validate_docs.py pass
• Full suite green: 129/129 (was 116; +13 new)
• `make check-docs` runs end-to-end against `.github/docs/` — exits 0 in `--warn-only` mode, surfaces 21 expected gaps + 1 real `SUMMARY` bug
• CI green on this PR (the new `docs frontmatter gate` step is wired warn-only so the existing 21 gaps won't fail the build)

🤖 Generated with Claude Code