[jvanheerikhuize]

Supersedes #5, which was cut from a pre-#3 base and measured against a tree that no longer exists. Everything below was re-measured against current main.

What the rebuild already fixed

Before #3, role version lived in three hand-maintained places — index.yaml, the > **Version:** line in prompt.md, and the same line in README.md — and 12 roles disagreed with themselves. Generating index.yaml and dist/ from role.md frontmatter, plus the stale-artifact git-diff gate in CI, ended that for two of the three copies. 11 of the 12 drift cases are genuinely resolved.

The defect that survived, and the one the migration introduced

The migration sourced its role.md frontmatter versions from the stale index.yaml rather than from the prompt bodies. That silently reverted nine roles from 1.1 back to 1.0 (cra, qave, dice, heist, frank, psy, agora, agl, prime) and spray from 2.0 to 1.0.

spray is consumer-visible: its README and its own <MASTER_PROMPT version="2.0"> body say 2.0, while index.yaml said 1.0 — so ./resolve.sh --id spray, the consumer-facing API, disagreed with the index on main today.

Nothing caught it because every check in validate-index.sh is existence-shaped ("the referenced file is present"). None was agreement-shaped ("these files say the same thing"), and a hand-written copy going stale is only ever caught by the second kind. The per-role README.md is still hand-written per REBUILD_PLAN §3.1 — the one unguarded copy left.

Which value is authoritative

Determined from history, not guessed. 73d2285 bumped 19 prompt.md files to 1.1 while touching neither index.yaml nor any README.md; 24525e9 bumped spray to 2.0 in prompt.md + README.md only. The prompt files record real content changes and the bump commits simply forgot the other files — so reconciliation goes toward the prompts.

Commits

fix(roles)	Restores the nine 1.1s and spray 2.0 in frontmatter + README, regenerates index.yaml. dist/ is unchanged — prompt bodies don't embed the version.
feat(validate)	Agreement-shaped check: each role README vs. its role.md frontmatter, on version and category.
fix(catalog)	catalog.yaml still said name: agent-roledefinitions-submodule after the repository URL had moved. Resolves open decision #2. 2.0.0-alpha.1 → 2.0.0-alpha.2, PATCH-equivalent per VERSIONING.md ("metadata corrections").
docs(roadmap)	The old roadmap promoted SemantiCode as "current focus"; the rebuild archived it. Replaced with what shipped, the gap Phase 1 left, and the Phase 2–4 ordering.

No new workflow file — the existing .github/workflows/validate.yml from #3 already runs the improved validator.

Verification

• The new check was run against a pristine origin/main checkout before being trusted: it failed with exactly FAIL: spray: README says version 2.0, role.md frontmatter says 1.0. That was the point.
• On this branch: validate-index.sh --check-crisis → OK — all checks passed.
• test-roles.sh → OK — all role smoke tests passed (4 warning(s)) — pre-existing WARNs for psy, frank, vita, agora about crisis numbers hardcoded outside config/, unchanged by this PR and targeted by Phase 2 config templating.
• tools/build.py regenerates cleanly; ./resolve.sh --id spray and index.yaml now agree at 2.0.

Prompt bodies are untouched. No persona text changed.

Where the roadmap diverges from REBUILD_PLAN

Opinions, flagged for review, not corrections:

• Generate the README metadata header too (§3.1 keeps it hand-written). The README is the only remaining participant in the drift; leaving it hand-written preserves the problem the rebuild set out to remove. The new check is the interim guard until then.
• Two build targets, not six (§3.1/§3.6 specify six plus an MCP server; §5 itself warns about scope creep). Add a target when a real consumer asks.
• Behavioural evals (§3.5) before the health-role rewrites, not after.

Also outstanding from Phase 1: the final v1.x tag has still not been pushed, and pinned submodule consumers need it before the layout moves further.

🤖 Generated with Claude Code