Repository navigation
process: add repo process docs and rewrite README - #30
Merged
Merged
Conversation
Adds the process/ folder that #29 proposes, playing the role EIP-1 plays for EIPs, and rewrites the README around Access Layer scope rather than zkspecs scope. - lifecycle: idea, draft, review, stable, deprecated, plus stagnant, withdrawn and living, with the evidence gate for stable - front matter: the id, role, type, status, domains and relationship fields, and the versioning rule agreed on #29 - intake: issue first, then PR, and the numbering rule - spec template: copyable skeleton with RFC 2119 wording - governance: the four pieces that cannot be retrofitted, licence open No spec text is touched. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Specs here are already cited as 1/COSS and 3/SEMAPHORE-V4 in each other's bodies, and three specs carry tags today. Dropping both would lose information the repo already has, so document them as optional. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Sep 14, 2026
The rename asked for in #29 happened, so the pending note goes and the old pull request links point at the new name. Old links still redirect. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Review found two contradictions in these docs. lifecycle.md said a graduated spec keeps its content, while front-matter.md called every indexed entry a stub. Graduation is now named as the exception, and it gains an index_reason recording the move. The indexing guardrail only accepted an entry a hosted spec depends on, which blocked graduation outright, since a spec nothing depends on could never flip to indexed. An entry now earns its place either that way or by carrying index_reason. replaced_by was documented as 'a spec id or external standard' while being used for a repo path. All three forms are now written down, with which of them the validator checks. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The previous round fixed graduation by letting any non-empty index_reason satisfy the guardrail. That is worse than the bug it replaced, because 'index_reason: interesting' admits any external standard while looking like the rule is enforced. There are now exactly three ways an indexed entry qualifies, each with something the validator can check. A hosted spec depending on it, index_basis: graduated with replaced_by set, or index_basis: formerly-hosted with upstream set. index_reason stays as the human sentence required alongside index_basis. No other value is accepted and there is no free-text route in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The repository file switches from MIT to CC0. Specs 2 to 5 already ended with the CC0 waiver line, so this makes the repository match the specs. governance.md drops the open-licence flag and the contributor-agreement item, the waiver line in each spec is the agreement. Spec template now carries the exact waiver line. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- versioning example is Semaphore v3 to v4, there is no v5 - shortname: specs 2 to 4 cite 1/COSS, nothing cites each other - registry.yaml and the README table: say the table is hand-edited until the generator lands - folder is number plus slug, matching intake and the template - graduated entries require upstream, not replaced_by, matching lifecycle.md - replaced_by path form: reviewer confirms it opens, CI does not - editor is accountable for the entry, not for upstream text - governance: CC0 waiver is on specs 2 to 4, spec 5 is a stub - README: spec 5 is indexed with status idea, raw is not a lifecycle status - example front matter no longer repeats a domain value as a tag Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Both required upstream and differed only in whether the old text stays, which depends on dependants and status, not on where the text went. One value, moved, with the text kept when any spec depends on it or it had reached stable. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
dependency or moved, always set when role is indexed. The reason no longer lives only in another spec's depends_on, and a moved spec keeps its history even when something depends on it. The dependency check now reads in the right direction, a hosted spec must list the entry. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The free-text line duplicated depends_on and upstream, so it goes. The checked field keeps the name that says what it is. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- interface and schema bullets say how each is proven - shortname required, explained as citation handle and folder name - replaced_by rewritten, plus a paragraph on replaced versus moved - versioning section rewritten around the Semaphore v3 to v4 change Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Spec 1's licence origin corrected, it was copied from ZeroMQ's COSS text, not derived from C4. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- merge happens at draft, said explicitly in lifecycle.md and intake step 5 - two roles, editor and maintainer, and three approval rules replace the undefined reviewer - folder placeholder is 0000 plus the lowercase shortname - Labels section cut, step 1 already covers it Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ance - idea removed, draft is the first status, spec 5 is living - description field moved here from #32, where the generator needed it - governance no longer names a tie-breaker or an open item - zkID links point at the ethereum org - process/README.md opening line in plain words Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- decision chart is two questions, Access Layer scope and whether it changes a standard someone else owns, everything else is written here - indexing promises removed, the front-matter rule is the only one - profiles bullet in plain words, EIP process is now ERC process Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The map listed other teams' specs, which the indexing rule says the repo does not do. Spec 5's stub already says where its text lives. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
There is no slug field. The folder name is the number plus the shortname in lowercase, which is what the shortname section already says, so the opening line said it a second way with a word nothing else uses.
An indexed stub holds no text, so crediting contributors for it credits them for a pointer. Their names stay on the spec upstream. The editor row already says the editor owns the link and the context line, this says it where the role is defined.
Collaborator
|
Looks great! Only have minor comments:
|
The five existing specs write multi-word tags both ways, and spec 3 does both in one line. Either reading is fine for a human, but a search or a grouping would count "proof of membership" and "proof-of-membership" as two different tags.
…tees Moving to the ERC process is no longer described as the path a spec takes, only as something that can happen. What belongs here now names the Access Layer guarantees, censorship resistance, open source, privacy, security and self-sovereignty, in the prose and in the chart. Intake step 1 asks for the spec and its verbs, not for a case against other bodies. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
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.
Collaborator
Author
|
@Meyanis95 thx for the feedback, worked in your comments |
phipsae
added a commit
that referenced
this pull request
Sep 16, 2026
#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>
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
#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>
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
2 participants
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.
First of three pull requests implementing #29. This one adds the process docs, rewrites the README and switches the licence file to CC0. It touches no spec text.
What is here
process/README.mdprocess/lifecycle.mdstableprocess/front-matter.mdprocess/intake.mdprocess/spec-template.mdprocess/governance.mdDecisions this settles
The repo is the home for Access Layer specs. A spec belongs here when it strengthens at least one of the Access Layer guarantees, censorship resistance, open source, privacy, security or self-sovereignty. The only things turned away at the door are work outside the Access Layer and changes to a standard someone else already owns. If a spec ever moves to another body later, it keeps its number and a pointer here.
Domains are a front-matter tag, nothing more. No
domains/folder and no generated domain pages. Yanis raised cross-category specs on 14 Sep, Semaphore is read, write and prove at once. Values are the five verbsread,write,prove,delegate,exit, which andyguzmaneth agreed to in this comment.Spec numbers are assigned on merge, not taken from the pull request number. EIP-1, the ENSIP repo and PEP 1 all assign at merge, and 1/COSS already says specs carry an incremental number. A spec is merged as
draftand gets its number then. Later stages are status changes on the merged file.One rule for indexed entries. Every indexed entry names why it exists in
index_reason, eitherdependency(a hosted spec lists it independs_on) ormoved(its text started here and now lives elsewhere,upstreamset). CI checks the matching condition. There is no free-text route in, and a spec that is merely worth mentioning gets a plain link in prose.Roles and approvals. Two roles, the editor named in the front matter and the maintainers with write access. Merging a new spec or moving one to
revieworstableneeds one approval from a maintainer who is not the editor. Small text edits need none.Licence is CC0, the same as the EIP repository. Specs 2 to 4 already end with the CC0 waiver, spec 1 keeps the GPL of the ZeroMQ COSS text it was copied from.
Still open from #29
A repo owner and named maintainers have had no answer since 23 August. Neither blocks this pull request.
Next
process/.registry.yaml, its generator and the CI check.🤖 Generated with Claude Code