specs: normalise front matter and rename folders to number and shortname

[phipsae]

Second of three pull requests implementing #29. Based on #30, so review that one first. The diff shown here is only this change.

Puts the five existing specs on the schema #30 defines, retires 1/COSS now that process/ replaces it, and renames their folders from a bare number to the number plus the spec's shortname in lowercase, specs/3-semaphore-v4/, so listings are readable. No spec text is rewritten, apart from spec 5's one-sentence pointer. The bare-number folders stay as one-line pointers so links made before the rename keep resolving.

Metadata assigned

#	Spec	role	type	status	domains
1	COSS	hosted	process	deprecated	none
2	Anon Aadhaar v2	hosted	protocol	draft	prove
3	Semaphore v4	hosted	protocol	draft	read, write, prove
4	Excubiae	hosted	protocol	draft	prove, delegate
5	ZK Proof of Personhood	indexed	protocol	draft	prove

Editors, please correct your own row. Two I am least sure about:

• Excubiae as protocol. It specifies contracts others build against, which could also read as interface, but the framework behaviour argues for protocol. 0xjei
• Semaphore carrying three domains. This is the case Meyanis95 raised on 14 September, that Semaphore is write when an identity joins a group, read when a leaf position is looked up, and prove on membership. Tagging all three is the point of the field, so nothing has to be split. vplasencia

Specs 2, 3 and 4 do not list 1/COSS in depends_on. They declare themselves governed by it, which is a governance link, not something they cannot be used without. The governed-by line in each spec's prose already says it, and this pull request repoints those lines.

1/COSS is retired

#30 adds process/, which defines how this repository works. 1/COSS already defines that, differently, so without this change two process documents would govern one repository.

1/COSS goes to status: deprecated with replaced_by: process/, which is the case process/front-matter.md names for the path form of that field. role stays hosted and every word of the text stays in place, so old links keep resolving and the specs written under it can still be read against it. A short note at the top of the file says the current rules live in process/, so a reader arriving from an old link is not misled.

The two differ on the lifecycle stages, on the evidence required to reach stable, and on editorial control. They agree on incremental numbering and on a functional change getting a new number rather than an edit, both of which process/ inherited from COSS rather than replacing.

This was open as its own pull request, #33. It is folded in here because this branch already migrates every spec's front matter and rewrites the same three governed-by lines, so keeping it apart made a reviewer read those lines twice.

Spec 5

Spec 5 is indexed rather than mirrored, because the file holds no copy of the spec, only a pointer. It carries index_reason: moved with upstream pointing at zkID, where the text was imported in May 2026, and status: draft, which is what the upstream calls itself in its own front matter (COSS raw, and #30 has no raw). Being a stub it has no contributors, and its editor is whoever keeps the link correct here rather than the people who wrote the text upstream. The text stays in zkID, where its authors and the implementation are.

Bugs found and fixed on the way

These are pre-existing and unrelated to #29, but they sit in the lines being touched anyway.

• Spec 2's front matter never parsed. It sat below a ## Anon-Aadhaar spec raw heading, so GitHub rendered the YAML as body text and no tool could read it. It now starts the file, and the heading became a normal H1 carrying the spec's name.
• Specs 2 and 4 declared slug: CS-02 and slug: CS-04 while their folders and titles said 2 and 4. Three different identifiers for two specs.
• Specs 2, 3 and 4 nested - tags: inside contributors, which made every tag a contributor. Tags are now a top-level field.
• Specs 3 and 4 wrote multi-word tags with spaces where the others used hyphens. All tags are now lower case with hyphens, as process: add repo process docs and rewrite README #30 states.
• Spec 4 listed a literal ... as a contributor.
• Two broken links to 1/COSS. Spec 3 pointed at github.com/zkspecs/zkspecs, which only resolves via redirect since the move to the ethereum org. Spec 1 pointed at itself as spec/1, a path that has never existed.

Checked

• Every spec's front matter parses as YAML and carries every required field with an allowed value.
• Every relative link in the repository resolves after the renames, images included, verified by crawling all of README.md, process/ and specs/.
• Each spec body is byte-identical to before apart from the link fixes, the two added headings, the governed-by line in specs 2, 3 and 4, and the note added at the top of 1/COSS.

Folder renames are git mv, so history follows the files.

🤖 Generated with Claude Code

[Meyanis95]

lgtm