ci: generate registry.yaml and the README table from front matter

[phipsae]

Third of three pull requests implementing #29. Based on #31, which is based on #30. Review those first. The diff shown here is only this change.

Makes front matter the only place spec metadata is written down. The index table in the README and registry.yaml are derived from it, so they cannot drift from the specs they describe.

What runs

scripts/build_registry.py writes registry.yaml and splices the README table between two markers. With --check it writes nothing and fails if the committed output is stale. CI runs that on every pull request touching specs/, the script or either generated file, and on every push to main.

Run against the specs as #31 leaves them, it reproduces the hand-written README table byte for byte.

What it rejects

The same pass validates front matter against process/front-matter.md and fails the build on any of these.

Check	Example failure
Folder naming	a folder that is not the number plus the shortname in lowercase
Parseable front matter	missing, invalid YAML, or not a mapping
Required fields	no shortname, no editor
Identity	id not a whole number or disagreeing with the folder number, a duplicate id, a shortname that is not upper-case letters, digits and hyphens
Allowed values	a status outside the lifecycle, an unknown type, role or domain
Provenance	mirrored or indexed with no upstream
References	depends_on, replaces or a numeric replaced_by naming a spec that does not exist
Indexing rule	an indexed entry without index_reason, a dependency no hosted spec lists in depends_on, or a moved with no upstream

The last row is the rule from #30 that stops the repository slowly becoming a catalogue of every interesting spec in the world. index_reason takes exactly two values and each has one condition CI can check. A sentence of your own is not a reason.

Two things are validated but not listed. The legacy bare-number folders specs/1/ to specs/5/ are pointers kept so old links resolve, not specs. And a spec still at 0000-shortname while in review goes through every check, references and indexing rule included, but stays out of the table and registry.yaml until a maintainer assigns its number on merge and regenerates, see process/intake.md. While such a draft is in the tree, 0 is a valid reference target meaning the draft in the same pull request, so a new spec and the external standard it depends on can be proposed together. Once no 0000 folder is left, a leftover 0 fails.

I tested each failure mode by breaking the repository on purpose. Sample output:

Front matter problems:

  4-excubiae: folder must end in the shortname in lowercase, something-else
  2-anon-aadhaar-v2: status 'idea' is not one of ['deprecated', 'draft', 'living', 'review',
    'stable', 'stagnant', 'withdrawn']
  5-zk-proof-of-personhood: an indexed entry needs index_reason set to one of
    ['dependency', 'moved'], see process/front-matter.md

Also here

Two sentences in process/ change because the generator now exists. front-matter.md loses "until the generator lands, the README table is edited by hand", and intake steps 4 and 5 say how a dependency is proposed alongside a new spec as 0, that the merging maintainer replaces the 0 and runs the script, and that a 0000 draft is validated but not listed.

Note on cost

This is the one pull request of the three that the repository does not strictly need. It is worth having before the sixth spec arrives rather than after, because a hand-kept index is the thing that quietly goes wrong. If you would rather not carry a Python dependency yet, close this and #30 and #31 still stand on their own. The index table in the README stays hand-kept, as it is today.

🤖 Generated with Claude Code

[Meyanis95]

lgtm