How we write specifications
One template, one lifecycle, one way to version.
Every specification here is a draft (version below 1.0). Build to them and comment on them, knowing they may change. No licence is granted yet.
In short
Every CRIS specification follows one template, moves through the same states, and is versioned the same way, so that a reader who knows one can read them all. These are proposals for Systems Engineering to adopt (Q1, Q2).
The template
| # | Section | What goes in it | Required |
|---|---|---|---|
| — | Header | From data: state, version, date, owner, licence, side of the line, relies on, comment link | Always |
| 1 | Purpose | What it is for and which design principle it serves, in one paragraph | Always |
| 2 | What it is, and is not | Its scope; what it never covers; any money or personal-data line | Always |
| 3 | Terms | Only words a reader would not know | When needed |
| 4 | The format, rule or method | The heart: a field table, a statement, or numbered steps | Always |
| 5 | Rules | Numbered, each one testable | Always |
| 6 | Illustrative example | With the standard “Illustrative only” label | From 0.2 |
| 7 | Conformance | Levels and test vectors, from data | Before 1.0 |
| 8 | Security, privacy, protected line | What it never carries; signatures; who may see what | Always (may be one line) |
| 9 | Open questions and deferred values | Each with an owner, from data | While 0.x |
| 10 | Changelog | Printed from the changelog data | Always |
The states
| State | Version | Licence | What it means for a builder |
|---|---|---|---|
| Planned | none | — | Named so you know it is coming; nothing to build to yet |
| Draft | 0.x | may be to be confirmed | Build to it and comment; it may change without notice |
| Candidate | 1.0.0-rc.n | required | Frozen for public review; only fixes |
| Stable | 1.x and above | required | Changes follow the versioning rules |
| Retired | last version kept | as published | Kept for reference; its successor is named |
Moving from draft to candidate needs a published licence, open questions closed or moved to a later version, test vectors, and a public review period of [30] days (proposed). Candidate to stable needs nothing but fixes during review, and the owner’s and the Founder’s signatures.
Versions
| Change | From 1.0 | Below 1.0 |
|---|---|---|
| Major (1.x → 2.0) | Something that conformed may no longer conform | — |
| Minor (x.1 → x.2) | Something added; anything that conformed still does | May break: that is what draft means |
| Patch (x.y.1 → x.y.2) | Wording, examples or fixes; conformance unchanged | Same |
The developer hub changelog is the one record of every version. Each specification prints its own changelog from it; no page types a changelog line.
Our rules
- Drafts are 0.x. (enforced by the build today)
- Stable is 1.0 or above. (enforced by the build today)
- No licence, no exit from draft. (enforced by the build today)
- Published side only, and a changelog entry for every version. (enforced by the build today)
- One shape: every specification follows the ten-section template.
- Examples are labelled: every example says example, and every example block says “Illustrative only. Not from a running system.”
- Deferred values are tracked: each is listed with its owner.
- Dependencies are declared, from data.
- A named owner who answers: an owner in post, or a named interim owner while the role is recruited.
- One changelog, printed from data, never typed.
- Status from data: a specification never says the system it describes is running.
- Board-only changes stay board-only: a change that would weaken the Continuity Invariant or either gate goes to the board under the proposed AI Constitution.
