Repository navigation
Conversation
phipsae
force-pushed
the
process/supersede-coss
branch
from
September 14, 2026 22:22
a49a64a to
a490f6e
Compare
phipsae
force-pushed
the
specs/normalize-front-matter
branch
from
September 14, 2026 22:22
afc78b0 to
3269bdd
Compare
phipsae
force-pushed
the
process/supersede-coss
branch
from
September 14, 2026 22:23
a490f6e to
0736307
Compare
phipsae
changed the base branch from
specs/normalize-front-matter
to
ci/registry-generator
September 14, 2026 22:24
phipsae
force-pushed
the
ci/registry-generator
branch
from
September 14, 2026 22:46
7e3d247 to
c232a3a
Compare
phipsae
force-pushed
the
process/supersede-coss
branch
from
September 14, 2026 22:46
0736307 to
0d4d771
Compare
Puts the five existing specs on the schema in process/front-matter.md and renames their folders so listings are readable. Spec text is unchanged apart from the fixes listed below. Folders: specs/1 -> specs/1-coss specs/2 -> specs/2-anon-aadhaar-v2 specs/3 -> specs/3-semaphore-v4 specs/4 -> specs/4-excubiae specs/5 -> specs/5-zk-proof-of-personhood Fixes carried in the same pass: - spec 2's front matter sat below a heading, so it never parsed as front matter at all. It is now at the top of the file, and the heading became a normal H1 with the spec's name. - specs 2 and 4 declared slug CS-02 and CS-04 while their folders and titles said 2 and 4. The id now matches the folder in every case. - specs 2, 3 and 4 carried a nested "- tags:" entry inside contributors, which made every tag part of the contributor list. Tags are now a top-level field. - spec 4's contributor list held a literal "...". - spec 3 linked to 1/COSS at github.com/zkspecs/zkspecs, which only resolves through a redirect. Spec 1 linked to itself at "spec/1", which never existed. Both are now relative. Statuses map old to new: raw becomes idea, draft stays draft, and COSS becomes living because a process doc is never meant to freeze. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two fixes from review. The folder rename 404s every existing link to specs/1 through specs/5. A repo rename redirects the repo, not renamed file paths, and the zkID repo links to specs/1 right now. Each old path keeps a one-line pointer at the new folder. Spec 5 was tagged mirrored while holding no copy, only a link, which is the definition of indexed rather than mirrored. It is now indexed, with an index_reason recording that the text was written here in March, imported into zkID in May, and removed here in #24. Its upstream also pointed at privacy-ethereum/zkID, which now only resolves by redirect. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
index_basis: formerly-hosted is exactly this case, a spec whose text was hosted here and moved to another repository. The reason line stays as the human explanation. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Makes front matter the only place spec metadata is written down. The index table and registry are derived, so they cannot drift from the specs they describe. scripts/build_registry.py writes registry.yaml and splices the README table between markers. With --check it writes nothing and fails if the committed output is stale, which is what CI runs on every pull request touching specs, the script, or either generated file. The same pass validates front matter and fails on: - a folder not named number-slug - front matter that is missing, unparseable, or not a mapping - a missing required field - an id that disagrees with its folder number, or a duplicate id - a role, type, status or domain outside the allowed set - a mirrored or indexed spec with no upstream URL - depends_on or replaces naming a spec that does not exist - an indexed entry that no hosted spec depends on That last one is the guardrail from process/front-matter.md, which stops the repo becoming a catalogue of every spec in the world. Adds an optional description field so the table keeps the one-line summaries the README already had. Without it the table falls back to the spec title. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three defects found in review. The indexing guardrail accepted an entry only when a hosted spec named it in depends_on. That made graduation impossible, because a spec nothing depends on could never flip to indexed on its way out to another body, which is exactly what #29 promises graduated specs can do. An indexed entry now qualifies either that way or by carrying index_reason, one line saying why it is here. replaced_by was never checked at all. A pointer at spec 9999 passed. A numeric target is now validated like replaces, while an external id or a repo path is left alone. Bare-number spec folders are skipped rather than rejected. They are the legacy pointers kept so links from before the folder rename still work. Any other misnamed folder still fails. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The previous fix let any non-empty index_reason satisfy the guardrail, which is the original hole wearing a different hat. Reproduced with an unrelated external standard carrying 'index_reason: interesting', and it passed. An indexed entry now qualifies one of three ways, each with a field behind it. A hosted spec names it in depends_on, or index_basis is graduated with replaced_by set, or index_basis is formerly-hosted with upstream set. Either basis also requires an index_reason. Any other index_basis value is rejected. Ten cases tested, covering both bases with and without their required field, a missing reason, an unknown basis, the free-text hole, and the earlier replaced_by, folder naming and legacy pointer checks. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The repo now defines its working rules in process/, and 1/COSS defines a different set. Two process documents governing one repo is the kind of thing nobody notices until a spec is promoted under the wrong rules. COSS stays in place, at status deprecated with replaced_by pointing at process/, and gains a note at the top saying where the current rules live. Specs 2, 3 and 4 said they were governed by 1/COSS, so they now point at process/ while still naming COSS as what came before. Where the two agree, on incremental numbering and on a functional change getting a new number rather than an edit in place, process/ inherited the rule from COSS rather than replacing it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
phipsae
force-pushed
the
ci/registry-generator
branch
from
September 14, 2026 23:02
c232a3a to
8484514
Compare
phipsae
force-pushed
the
process/supersede-coss
branch
from
September 14, 2026 23:02
0d4d771 to
370fe70
Compare
phipsae
added a commit
that referenced
this pull request
Sep 16, 2026
The five existing specs go onto the schema #30 defines, and their folders are renamed from a bare number to the number plus the spec's shortname in lowercase. No spec text is rewritten, apart from spec 5's one-sentence pointer. 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, and status: draft, which is what the upstream calls itself in its own front matter (COSS status: 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. 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 #33 repoints those lines to process/. The bare-number folders stay as one-line pointers so links made before the rename keep resolving. Pre-existing bugs fixed on the way, all in lines being touched anyway. Spec 2's front matter sat below a heading so it never parsed. Specs 2 and 4 declared slug CS-02 and CS-04 against folders and titles saying 2 and 4. Specs 2, 3 and 4 nested tags inside contributors, and specs 3 and 4 wrote multi-word tags with spaces where the others used hyphens. Spec 4 listed a literal ... as a contributor. Spec 3 linked to 1/COSS at the old zkspecs org and spec 1 linked to itself at spec/1, a path that never existed.
phipsae
force-pushed
the
ci/registry-generator
branch
from
September 16, 2026 22:05
8484514 to
74cb2bd
Compare
phipsae
force-pushed
the
ci/registry-generator
branch
from
September 16, 2026 23:09
74cb2bd to
8740432
Compare
Collaborator
Author
|
Folded into #31, which already migrates every spec's front matter and rewrites the same three governed-by lines. Keeping it separate made a reviewer read those lines twice. The change is unaltered, 1/COSS at |
phipsae
added a commit
that referenced
this pull request
Sep 17, 2026
The five existing specs go onto the schema #30 defines, and their folders are renamed from a bare number to the number plus the spec's shortname in lowercase. No spec text is rewritten, apart from spec 5's one-sentence pointer. 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, and status: draft, which is what the upstream calls itself in its own front matter (COSS status: 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. 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 #33 repoints those lines to process/. The bare-number folders stay as one-line pointers so links made before the rename keep resolving. Pre-existing bugs fixed on the way, all in lines being touched anyway. Spec 2's front matter sat below a heading so it never parsed. Specs 2 and 4 declared slug CS-02 and CS-04 against folders and titles saying 2 and 4. Specs 2, 3 and 4 nested tags inside contributors, and specs 3 and 4 wrote multi-word tags with spaces where the others used hyphens. Spec 4 listed a literal ... as a contributor. Spec 3 linked to 1/COSS at the old zkspecs org and spec 1 linked to itself at spec/1, a path that never existed.
phipsae
added a commit
that referenced
this pull request
Sep 17, 2026
…ame (#31) * specs: normalise front matter and rename folders to number and shortname The five existing specs go onto the schema #30 defines, and their folders are renamed from a bare number to the number plus the spec's shortname in lowercase. No spec text is rewritten, apart from spec 5's one-sentence pointer. 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, and status: draft, which is what the upstream calls itself in its own front matter (COSS status: 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. 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 #33 repoints those lines to process/. The bare-number folders stay as one-line pointers so links made before the rename keep resolving. Pre-existing bugs fixed on the way, all in lines being touched anyway. Spec 2's front matter sat below a heading so it never parsed. Specs 2 and 4 declared slug CS-02 and CS-04 against folders and titles saying 2 and 4. Specs 2, 3 and 4 nested tags inside contributors, and specs 3 and 4 wrote multi-word tags with spaces where the others used hyphens. Spec 4 listed a literal ... as a contributor. Spec 3 linked to 1/COSS at the old zkspecs org and spec 1 linked to itself at spec/1, a path that never existed. * specs: retire 1/COSS in favour of process/ #30 adds process/, which defines how this repository works. 1/COSS already defines that, differently, so two process documents govern one repository. This settles which one wins. 1/COSS goes to status: deprecated with replaced_by: process/ and gets a note at the top pointing at the current rules. Every word of the text stays in place, so links keep resolving and the specs written under it can still be read against it. Specs 2, 3 and 4 declared themselves governed by 1/COSS, so they now point at process/ while still naming COSS as what came before. 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. Folded in here rather than kept as its own pull request, because this branch already migrates every spec's front matter and rewrites the same three governed-by lines. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * README: COSS row shows deprecated Same change as the previous commit, in the hand-kept index table that #32 later replaces with a generated one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A question with a proposed answer, not a decision. Needs agreement before it merges. Based on #32, so it is last in the stack.
#30 adds
process/, which defines how this repository works. 1/COSS already defines that, differently. Two process documents governing one repository is the kind of thing nobody notices until a spec gets promoted under the wrong rules, so it needs settling either way.Where they actually disagree
process/stableWhere they agree
Worth saying plainly, because it is most of the substance.
So
process/inherited from COSS more than it replaced.What this pull request does
Sets 1/COSS to
status: deprecatedwithreplaced_by: process/, adds a note at the top pointing at the current rules, and leaves every word of the text in place so links keep resolving. Specs 2, 3 and 4 declared themselves governed by 1/COSS, so they now point atprocess/while still naming COSS as what came before.It sits on top of #32 rather than #31 so it can carry its own regenerated
registry.yamland README row. Without that ordering, merging this would leave the generated files stale and turn main red, which is the check in #32 doing its job. If #32 is dropped, drop the two generated files from this branch and it rebases onto #31 cleanly.The alternative
Keep 1/COSS as the process and cut
process/lifecycle.mdback to a pointer. That is a real option and it keeps continuity. It costs the evidence gate forstable, thereviewstage, and thestagnantandlivingstatuses, which are the parts #29 argued for on the grounds that builders need to know what is safe to build against. Saying "used by third parties" does not answer that question.This changes the governed-by line in specs 2, 3 and 4.
🤖 Generated with Claude Code