diff --git a/.2119/verdicts/REQ-003.4.2.json b/.2119/verdicts/REQ-003.4.2.json index d1ad49c..3d6cf2d 100644 --- a/.2119/verdicts/REQ-003.4.2.json +++ b/.2119/verdicts/REQ-003.4.2.json @@ -1,8 +1,8 @@ { - "reviewId": "REQ-003.4.2--0ba9b9c05c15", + "reviewId": "REQ-003.4.2--2558ff342f6b", "requirementId": "REQ-003.4.2", - "hash": "0ba9b9c05c15", + "hash": "2558ff342f6b", "verdict": "pass", - "summary": "Risks section states the self-pass residual risk plainly and names the committed-verdict, hash-invalidation, and CI re-run mitigations explicitly", - "timestamp": "2026-08-08T07:28:03.328Z" + "summary": "Risks section states the self-pass residual risk plainly and names the committed-verdict, hash-invalidation, and CI re-run mitigations", + "timestamp": "2026-08-08T08:53:49.315Z" } diff --git a/.2119/verdicts/REQ-005.2.6.json b/.2119/verdicts/REQ-005.2.6.json index 01854dd..07de5d4 100644 --- a/.2119/verdicts/REQ-005.2.6.json +++ b/.2119/verdicts/REQ-005.2.6.json @@ -1,8 +1,8 @@ { - "reviewId": "REQ-005.2.6--1c79c4f2f0d0", + "reviewId": "REQ-005.2.6--403de8d5f77f", "requirementId": "REQ-005.2.6", - "hash": "1c79c4f2f0d0", + "hash": "403de8d5f77f", "verdict": "pass", - "summary": "Verify-tag docs state arbitrary-shell execution and package.json-script trust equivalence in the section documenting [verify]", - "timestamp": "2026-08-08T07:28:03.467Z" + "summary": "Verify-tag docs state arbitrary-shell execution and package.json-script trust equivalence beside the [verify] semantics", + "timestamp": "2026-08-08T08:53:49.450Z" } diff --git a/.2119/verdicts/REQ-008.1.2.json b/.2119/verdicts/REQ-008.1.2.json index 2e45411..55f18a6 100644 --- a/.2119/verdicts/REQ-008.1.2.json +++ b/.2119/verdicts/REQ-008.1.2.json @@ -1,8 +1,8 @@ { - "reviewId": "REQ-008.1.2--1fcd1a57103b", + "reviewId": "REQ-008.1.2--664c5abc793a", "requirementId": "REQ-008.1.2", - "hash": "1fcd1a57103b", + "hash": "664c5abc793a", "verdict": "pass", - "summary": "Boundaries paragraph names all three exclusions with rationales and the design.md link, in the intro before the adoption instructions", - "timestamp": "2026-08-08T07:28:09.788Z" + "summary": "Header block states all three exclusions bolded with the design.md link before any install command; numbered trio restates them before the adoption section", + "timestamp": "2026-08-08T08:53:49.587Z" } diff --git a/.2119/verdicts/REQ-008.2.2.json b/.2119/verdicts/REQ-008.2.2.json index 1874a93..175555b 100644 --- a/.2119/verdicts/REQ-008.2.2.json +++ b/.2119/verdicts/REQ-008.2.2.json @@ -1,8 +1,8 @@ { - "reviewId": "REQ-008.2.2--456734b19776", + "reviewId": "REQ-008.2.2--5308de176d8b", "requirementId": "REQ-008.2.2", - "hash": "456734b19776", + "hash": "5308de176d8b", "verdict": "pass", "summary": "README's Diversify-then-audit bullet and scaling.md's cross-provider audit section both advise periodic sweeps plus targeted audits of challenging or high-consequence requirements", - "timestamp": "2026-08-08T07:57:56.365Z" + "timestamp": "2026-08-08T08:53:49.719Z" } diff --git a/README.md b/README.md index 948e20b..8273478 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,22 @@ # 2119 -**Spec-driven test enforcement for coding agents.** Named for -[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) · [unsupervised.com/2119](https://unsupervised.com/2119) - -2119 makes the planning → building → testing loop hard to cheat: - -1. **Plans become requirements.** Features start as specs in `specs/` — RFC 2119 - documents where every requirement is a numbered, individually addressable - statement with exactly one normative keyword. `2119 lint` enforces the format. -2. **Requirements become tests.** Every MUST-level requirement needs at least one - test annotated with its ID (`// 2119: REQ-001.2.3` — a comment, so it works in - any language). `2119 cover` fails on any gap, in either direction. -3. **Tests get judged.** `2119 review` generates one instruction file per - requirement asking a *fresh-context* reviewer — one that did not write the - code — a single question: **would these tests fail if this requirement were - violated?** Verdicts are recorded with `2119 pass` / `2119 fail`. -4. **One gate.** `2119 check` = lint + coverage + verdict freshness (a verdict - counts only while its hash still matches the content it vouched for). Exit - code 0 or it isn't done. Agent hooks, git, and CI all call the same command. +**Spec-driven test enforcement for coding agents — a gate your agent can't quietly game.** Named for [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +- **Plans become numbered requirements** — specs where every MUST is individually addressable, and `2119 lint` enforces the format. +- **Every requirement gets a test that could actually fail** — `2119 cover` fails on missing tests; a *fresh-context* reviewer judges each one: *would these tests fail if this requirement were violated?* +- **"Done" becomes one exit code** — `2119 check` gates agent hooks, pre-commit, and CI identically. Verdicts are committed, hash-bound artifacts: edit the code or the requirement, and the approval visibly dies. + +2119 is **not** a test runner, **not** a CI replacement, and **not** a security boundary ([why](docs/design.md)). + +```bash +npx rfc2119 init +``` + +[unsupervised.com/2119](https://unsupervised.com/2119) · [design decisions](docs/design.md) · [scaling guide](docs/scaling.md) · [live adoption example](https://github.com/tylerwillis/panopticon) + +═══════════════════════════════════════════════════════════════════ + +## 2119 makes the planning → building → testing loop hard to cheat Here is the gate catching an untested requirement and a stale review: @@ -38,15 +37,18 @@ see the full gate running in another codebase — specs, committed verdicts, and the CI check on every PR — browse [panopticon](https://github.com/tylerwillis/panopticon). -Three things 2119 is deliberately **not**: a test runner (`check` never -executes your suite — compose them: `npm test && npx rfc2119 check`), a CI -replacement (it's one exit code your CI calls), and a security boundary (a -deliberate cheater is made *conspicuous*, not impossible — see -[Risks](#risks)). These boundaries are -[enforced as reviewed requirements](specs/REQ-008-honest-boundaries.md); the -reasoning lives in [docs/design.md](docs/design.md), and -[docs/scaling.md](docs/scaling.md) covers hardening for larger or more formal -projects. +Three things 2119 is deliberately **not** — each +[enforced as a reviewed requirement](specs/REQ-008-honest-boundaries.md): + +1. **Not a test runner** — `check` never executes your suite; compose them: + `npm test && npx rfc2119 check`. +2. **Not a CI replacement** — it's one exit code your CI calls. +3. **Not a security boundary** — a deliberate cheater is made *conspicuous*, + not impossible (see [Risks](#risks)). + +The reasoning lives in [docs/design.md](docs/design.md); +[docs/scaling.md](docs/scaling.md) covers hardening for larger or more +formal projects. ## Use it in your repo