Software Constitution.
A language-agnostic, provider-agnostic, domain-agnostic standard for projects that want to enforce their own design principles at CI time — versioned rules, an implementation registry, drift gates that block merges on violation, zero-deviation mandate. Apache 2.0. KYE Protocol™ is the canonical reference implementation.
softwareconstitution.com → Read the spec → Run the SCCT → Constitution Kit → ★ Star on GitHub
Drop it into any repo in seconds: node public/oss/software-constitution/kit/init.mjs /path/to/target. The kit scaffolds your constitution-kit.json manifest with the registry, single-value-concept, recipe and drift-gate seams declared by the standard; from then on, every PR that violates your declared rules fails CI.
If this is useful, a star helps other engineering teams find the standard.
What it is
A specification you point at your repo to answer: "is this project governed by an explicit, machine-enforceable constitution?"
The standard ships with:
- The spec — 12 sections, 6 required rule classes, 5 conformance levels (L0 / L1 / L2 / L3 / L4).
- Templates — copy-paste starting points for the four required canonical artefacts (00-INDEX, DEVIATIONS, DECAY-WINDOWS, implementation-registry).
- Schemas — JSON Schema 2020-12 files that validate the structured artefacts.
- Reference gates — drop-in CI implementations in multiple languages. Node.js and Python shipping today; Go and Rust ports planned.
- SCCT — Software Constitution Conformance Test CLI. Runs against any candidate repo and emits a JSON verdict (L0 / L1 / L2 / L3 / L4).
The six rule classes
Every conforming constitution MUST address all six. Naming and numbering of individual rules is project-specific; the existence of at least one rule per class is the conformance bar. Canonical definitions live in SPEC.md §4.
| Class | What it locks |
|---|---|
| §RULE-1 — Zero Competing Systems | Single-Implementation Mandate: every named capability has EXACTLY ONE canonical implementation. |
| §RULE-2 — Zero Repo↔Prod Drift | What runs in production MUST be exactly what's in the repo. No out-of-band deploys. |
| §RULE-3 — Zero Stubs / Placeholders / Mocks | No TODO, FIXME, "coming soon", mock data in any production-reachable code path. |
| §RULE-4 — Self-Governance + Canonical-First | Every privileged action emits a canonical evidence event. Every event family declared before the code that references it. |
| §RULE-5 — Zero-Deviation Mandate | Active deviations are a regression. DEVIATIONS.md MUST keep its Active section empty by default. |
| §RULE-6 — Coherent Integration / No Orphans | Every named component is bidirectionally referenced — registry → component AND component → registry. Orphans on either side are violations. |
Why standard, not framework
- Protocol doesn't fit: there's no wire format, no two parties communicating through it.
- Framework is too low-stakes: implies "install this and inherit conventions" — people upgrade past frameworks.
- Standard is right: a spec that says "to call yourself a conforming software constitution, you MUST have …". Multiple implementations can conform. Procurement teams understand "standard"; engineers understand the conformance bar.
Closest analogues: 12-Factor App (heroku.com, 2011), OpenAPI (Linux Foundation), ADR (Architecture Decision Records).
Adoption path
# 1. Copy the templates into your repo cp -r software-constitution/templates/* your-repo/constitution/ # 2. Author your rules (one document per rail, numbered 01..NN) $EDITOR your-repo/constitution/00-INDEX.md $EDITOR your-repo/constitution/01-YOUR-FIRST-RAIL.md # 3. Declare your implementation registry $EDITOR your-repo/internal # 4. Wire the reference gates into your CI cp software-constitution/gates/*.mjs your-repo/scripts/gates/ # 5. Run the conformance test npx scct your-repo
Reference implementation: KYE Protocol™
The KYE Protocol™ monorepo is the canonical reference implementation. Current state (validated by SCCT on this repo): L4 (Platform-bijected) — every named surface is tracked in a generated meta-index, and every privileged action emits a canonical evidence event. Precise live counts ship in the auto-generated registry, not in prose.
IP safety
The Apache 2.0 license grants explicit IP rights for the methodology, schemas, templates, and reference gates published here. This is general engineering methodology — like 12-Factor or ADR — not IP-sensitive.
The reference implementation (KYE Protocol™) carries its own trademarks and IP portfolio covering AI-agent governance mechanisms — those are licensed separately and are NOT covered by this standard.