phase1-B: build-catalog + validate-catalog (TDD)

[rafael5]

Summary

Phase-1 Track B of the AI-discoverability plan: ship the two scripts that turn profile/tools.json from hand-curated to generated, plus the catalog-level validator that enforces the post-P1-A contract.

• profile/build/validate-catalog.py — strict Draft2020-12 validation of tools.json against tools.schema.json + task_index.json against task_index.schema.json, plus a key-collision guard between the two top-level shapes (post-P1-A invariant).
• profile/build/build-catalog.py — fetches each of the six onboarded repos' dist/repo.meta.json, validates it, translates it to a summary tools.<key> entry (one *_url per exposes.<kind>), and emits a deterministic tools.json carrying the hand-curated org / workflow / discovery_protocol narrative from the prior file.
• TDD throughout: RED tests written first, then GREEN implementations. 22 pytest cases (10 + 12), all green.

TDD coverage

test_validate_catalog.py (10 tests)

• Baseline pair validates clean (smoke).
• Unknown top-level key in tools.json fails under additionalProperties: false (covers re-inlined task_index, generic unknown key, inlined-facts block in a tool entry).
• Unknown top-level key in task_index.json fails.
• Malformed typed ID in primary fails the typedID regex.
• Malformed typed ID in see_also fails.
• Missing required field in a tool entry fails.
• Missing file reports a clean error.
• main(argv) exits 0 against the committed baseline.

test_build_catalog.py (12 tests)

• Three synthetic repo.meta.json fixtures — minimal, rich, extra-exposes-kind — exercise the translation surface.
• Required top-level keys emitted; task_index is NOT emitted; hand-curated org/workflow/discovery_protocol/description carried verbatim.
• Single-element language arrays collapse to strings; multi-element stay as arrays.
• Each exposes.<kind> → <kind>_url resolving against the manifest's repo-root raw URL.
• agent_instructions resolves to a github.com/.../blob/<branch>/... URL.
• Tools key strips the tool: prefix; entry id keeps it.
• Extra-exposes-kind passes through (proves the script is data-driven from manifests, not from a hardcoded allow-list).
• Generated output validates clean against tools.schema.json.
• dumps() is deterministic across input-order shuffles; sorted keys; trailing newline.
• B5 two-run determinism: building twice → byte-identical output.
• Invalid manifest raises a clear error rather than emitting a malformed entry.

Verification (all green)

pytest profile/build/                                                  # 22 passed
python3 profile/build/validate-catalog.py                              # exits 0 on committed pair
python3 profile/build/build-catalog.py | python3 -m json.tool >/dev/null  # parses
python3 profile/build/build-catalog.py > out1.json
python3 profile/build/build-catalog.py > out2.json && diff out1.json out2.json  # byte-identical
python3 profile/build/validate-catalog.py --tools out1.json --task-index profile/task_index.json  # exits 0
make phase0-smoke                                                      # PASS — manifests unchanged

Drift vs. committed profile/tools.json (what P1-D's drift gate will need to address)

Running build-catalog.py against the live TIER_1 + TIER_2 manifests produces a tools.json that diverges from the committed hand-curated baseline in four categorical ways. This is expected — the build script's job is to produce a regenerated version, and the drift is exactly what the P1-D drift gate (make catalog && git diff --exit-code) will need to reconcile. Documenting here so P1-D's reviewer can plan it.

1. Four hand-curated entries dropped (no dist/repo.meta.json on any of them):

• m-cli-extras — tier-3, no manifest.
• m-stdlib-vscode — tier-3, no manifest.
• tree-sitter-m-vscode — tier-3, no manifest.
• m-tools — archived seed repo.

These need a decision in P1-D: either (a) keep them as hand-merged additions overlaid on the generator output, (b) onboard them to the Phase-0 contract first (T3-* tasks per current-state-inventory-priority.md §3.2), or (c) drop them and add a top-level unonboarded list elsewhere.

2. consumed_by lost on all 6 onboarded tools. repo.meta.schema.json has consumes but not consumed_by — the inverse edge is currently hand-maintained in tools.json only. P1-D options: (a) compute consumed_by in build-catalog.py from the inverse consumes graph, or (b) extend repo.meta.schema.json to allow consumed_by (less clean — consumers shouldn't know who consumes them).

3. role text drifts on all 6 tools. The manifests (post-Phase-0) have shorter role strings; the committed tools.json carries the original longer descriptions:

• m-cli: "Canonical CLI toolchain — m fmt / lint / test / coverage / watch / lsp / doc / new / ..." → "Canonical M CLI — fmt / lint / test / coverage / watch / lsp / doc / new"
• m-stdlib: "Pure-M (and selectively $ZF-bound) runtime standard library — STD* modules" → "Pure-M runtime standard library — STD* modules"
• m-standard: "Citable, machine-readable M language reference reconciling AnnoStd / YottaDB / IRIS / VA SAC" → "Machine-readable M language reference"
• m-modern-corpus, m-test-engine, tree-sitter-m — similar drift.

The manifest is canonical going forward; P1-D should let the generator overwrite.

4. exposes key naming drift (one instance and one addition):

• m-stdlib: manifest exposes modules (→ modules_url); committed baseline calls the pointer manifest_url. Manifest is canonical.
• m-modern-corpus: manifest exposes licenses (→ licenses_url); committed baseline doesn't carry it. Generator additively picks it up.

Deferred to P1-D (per the plan and the task brief)

• Makefile targets catalog and a strict validate-catalog replacing the current python -m json.tool parse-only target.
• CI workflow make catalog && git diff --exit-code profile/tools.json profile/task_index.json drift gate, plus the make validate-catalog step.
• Resolving the drift catalogued above (one of: regenerate tools.json from the generator output and reconcile, or extend the generator's surface, or both).

Files added

• profile/build/build-catalog.py (executable, 274 lines)
• profile/build/validate-catalog.py (executable, 128 lines)
• profile/build/test_build_catalog.py (236 lines, 12 tests)
• profile/build/test_validate_catalog.py (135 lines, 10 tests)

No existing files modified — Track-B work is purely additive in profile/build/. profile/tools.json and profile/task_index.json are untouched (the drift question is P1-D's call, not this PR's).

Test plan

• Both pytest profile/build/test_validate_catalog.py and pytest profile/build/test_build_catalog.py green.
• python3 profile/build/validate-catalog.py exits 0 against the committed tools.json + task_index.json.
• python3 profile/build/build-catalog.py | python3 -m json.tool >/dev/null parses.
• Running build-catalog.py twice produces byte-identical output (B5 determinism).
• make phase0-smoke still green (manifests unchanged).
• CI green on this branch.

Do not auto-merge — drift catalogued above needs P1-D-level reconciliation before this generator should overwrite profile/tools.json.

🤖 Generated with Claude Code