Skip to content

Commit 2e098b3

Browse files
committed
docs: add RSR_COMPLIANCE.adoc at root per RSR-H9 / RSR-S4
Required root-level compliance statement. Summarises 15 HARD rules from MUST.contractile + RSR_OUTLINE.adoc with citations, notes three out-of-template adaptations (STATE.a2ml location, polyglot src/ layout, extracted crates/), and points readers to the canonical contractile and .machine_readable policy files for the authoritative rules. https://claude.ai/code/session_01YPqu7gti4azBach6ZvpRFJ
1 parent e94542a commit 2e098b3

1 file changed

Lines changed: 73 additions & 0 deletions

File tree

RSR_COMPLIANCE.adoc

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
3+
4+
= ECHIDNA — RSR / CCCP Compliance Statement
5+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
6+
:revdate: 2026-05-25
7+
:toc:
8+
9+
Status: living document, regenerated as policy changes.
10+
Canonical state: `.machine_readable/6a2/STATE.a2ml`.
11+
Canonical policy: `MUST.contractile`, `ADJUST.contractile`,
12+
`.machine_readable/policies/*.a2ml`.
13+
14+
This file satisfies RSR-H9 / RSR-S4 (required root-level compliance
15+
statement). It is a *summary* — the authoritative ruleset lives in
16+
the contractiles and the machine-readable policies above.
17+
18+
== Hard rules (HARD; enforced by CI)
19+
20+
[cols="1,3,2",options="header"]
21+
|===
22+
| ID | Rule | Source
23+
| RSR-H1 | `.machine_readable/` and `0-AI-MANIFEST.a2ml` preserved at root | `MUST.contractile:34`
24+
| RSR-H2 | No `.scm` metadata files in `.machine_readable/` (deprecated; use `.a2ml`). `guix.scm` exempt. | `.claude/CLAUDE.md`
25+
| RSR-H3 | Generated code lives only in `generated/` | `MUST.contractile:39`
26+
| RSR-H4 | No Python, TypeScript, Go anywhere | `MUST.contractile:31`
27+
| RSR-H5 | SPDX-License-Identifier header on every source file | `MUST.contractile:28`
28+
| RSR-H6 | `unsafe {}` only with `// SAFETY:` comment; no `believe_me` / `assert_total` / `Admitted` / `sorry` | `MUST.contractile:22`
29+
| RSR-H7 | CI workflows not removed without approval; all Actions SHA-pinned | `MUST.contractile:30`
30+
| RSR-H8 | No OWASP Top-10 vulnerabilities introduced | `MUST.contractile:37`
31+
| RSR-H9 | Required root files: `.editorconfig`, `.gitignore`, `Justfile`, `README.adoc`, this file, `LICENSE`, `.well-known/{security,ai,humans}.txt`, `guix.scm` | `RSR_OUTLINE.adoc` (echidna-playground)
32+
| RSR-H10 | Prohibited: Python outside `salt/`; TypeScript/JS (use AffineScript); `Dockerfile` (use `Containerfile`); CUE (use Nickel) | `RSR_OUTLINE.adoc`
33+
| RSR-H11 | Canonical dirs: `config/`, `docs/`, `docs/generated/`, `docs/man/`, `src/`, `tests/` | `RSR_OUTLINE.adoc`
34+
| RSR-H12 | `just validate-rsr` passes on every PR | `MAINTENANCE-CHECKLIST.adoc:69`
35+
| RSR-H13 | Guix is primary package manager; sealed-container escape only; no Nix fallback (estate ruling 2026-05-18) | `.claude/CLAUDE.md`
36+
| RSR-H14 | Justfile is the primary build system (no Make, etc.) | `MUST.contractile:42`
37+
| RSR-H15 | Podman, not Docker, for containers | `MUST.contractile:44`
38+
|===
39+
40+
== Soft conventions (SOFT; aspirational)
41+
42+
* Language tiers: Tier-1 = Rust, Elixir, Zig, Ada, Haskell, ReScript/AffineScript; Tier-2 = Nickel, Racket, Guile, Nix.
43+
* Coverage above 80 %.
44+
* Performance benchmarks show no regression PR-over-PR.
45+
* Generated docs in `docs/generated/`; man pages in `docs/man/`.
46+
47+
== Out-of-template adaptations
48+
49+
ECHIDNA diverges from the strict RSR template in three places:
50+
51+
1. *State file location*: RSR template puts `STATE.scm` at root; echidna
52+
places it at `.machine_readable/6a2/STATE.a2ml` per the `.scm → .a2ml`
53+
migration documented in `.claude/CLAUDE.md`.
54+
2. *Polyglot source layout*: `src/` contains per-language subdirectories
55+
(`src/rust/`, `src/julia/`, `src/abi/`, `src/chapel/`, `src/zig_ffi/`,
56+
`src/ada/`, `src/rescript/`, `src/ui/`, `src/interfaces/`) rather than
57+
a single language tree. The split is intentional — see CLAUDE.md.
58+
3. *Extracted Rust crates*: workspace-member crates live in `crates/`
59+
alongside `src/rust/`. The split between `src/rust/` (binary + main
60+
library) and `crates/` (extracted workspace members like `echidna-mcp`,
61+
`echidna-wire`, `echidna-core-spark`, `typed_wasm`) is intentional and
62+
documented in `Cargo.toml`.
63+
64+
== Verifying compliance locally
65+
66+
[source,bash]
67+
----
68+
just validate-rsr # primary gate
69+
just check # broader sweep (rust + julia + idris2 + ...)
70+
just test # 1067+ unit tests, 6 integration tests
71+
----
72+
73+
Run any of these before submitting a PR. CI runs all three on every push.

0 commit comments

Comments
 (0)