Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions CONSTITUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,10 @@ GPLv3 as permitted by the MIT licence.
**Language:** Rust. No exceptions beyond the minimal assembly required for boot
and context switching.

**Status:** Phase 1. The kernel boots on QEMU aarch64 `virt` and greets you;
scheduler, IPC, capabilities and MMU are the work in hand. The threat model is
the last outstanding Phase 0 deliverable.
**Status:** Phase 1. Phase 0 is complete — the constitution, the settled Borrow
Ledger, and the threat model (`docs/threat-model.md`) are all written. The
kernel boots on QEMU aarch64 `virt`, greets you, and reports its own faults;
scheduler, IPC, capabilities and MMU are the work in hand.

---

Expand Down Expand Up @@ -261,7 +262,7 @@ replacing Linux, supporting every board on earth.
people and language; naming and cultural use are checked with Noongar
language custodians before public release.

## 9. Threat Model (seed — to be expanded)
## 9. Threat Model (seed; expanded in `docs/threat-model.md`)

- **Assets:** app integrity, user data confidentiality, capability integrity,
update-channel authenticity.
Expand Down
8 changes: 8 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,14 @@ Number RFCs sequentially. Do not renumber or delete a rejected one: a rejected R
record of a question already settled, and is often more useful than an accepted one. Accepted RFCs are
never silently edited — changes go in an **Amendments** section, dated, with the reasoning.

### Amending the constitution

Only the maintainer may amend `CONSTITUTION.md`. When an amendment lands, it must leave no stale clause
behind: a constitution with two clauses contradicting each other is worse than one that is merely
wrong, because it makes every future reader guess which to obey. Check cross-references before merging —
`/check-coherence` automates exactly this sweep — and never renumber a section that other documents
cite, since the citations break silently.

---

## Development Setup
Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,9 @@ The paper trail lives in this repository, beside the code it governs:
rationale and the alternatives rejected.
- [docs/CHANGELOG.md](docs/CHANGELOG.md) — the amendment log for the
constitution and the design documents.
- `docs/threat-model.md` — expansion of the constitution's seed threat model.
*(to come — the last outstanding Phase 0 deliverable)*
- [docs/threat-model.md](docs/threat-model.md) — what Setonix defends and the
numbered obligations its design must discharge; expands the constitution's §9
seed.

## Status

Expand Down
6 changes: 3 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ Do not run it anywhere that matters.

## Threat Model

The project's threat model will live at `docs/threat-model.md` in this repository — it is the last
outstanding Phase 0 deliverable, and becomes the authoritative statement once written. Until then, the
seed in [the constitution §9](CONSTITUTION.md) is the statement of what Setonix defends against:
The project's threat model is [docs/threat-model.md](docs/threat-model.md), the authoritative
statement of what Setonix defends and the obligations (`O-1`, `O-2`, …) its design must discharge. It
expands the seed in [the constitution §9](CONSTITUTION.md):

**Assets:** app integrity, user-data confidentiality, capability integrity, update-channel
authenticity.
Expand Down
6 changes: 6 additions & 0 deletions STYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,12 @@ ATX-style, with blank lines before and after.

Always fenced, always with a language.

### Tables

Preferred for anything with two or more parallel attributes — the constitution's Borrow Ledger is the
model, and the threat model's obligations-by-phase table follows it. Tables are exempt from the
line-length limit.

### Trailing Whitespace

Markdown files are exempt from trailing-whitespace trimming (needed for line breaks).
Expand Down
26 changes: 26 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,21 @@ recorded is indistinguishable from law that was never agreed.

### Added

- **`docs/threat-model.md` — the last Phase 0 deliverable.** Expands the constitution's §9 seed into
the authoritative statement of what Setonix defends: five assets, five adversaries, six trust
boundaries, and twenty numbered obligations (`O-1` … `O-20`) the design must discharge. The
obligations are the contract between the model and the code — RFCs cite them by number ("this
mechanism discharges O-3 at B1"), and each carries an honest status: **Built** (three, today —
kernel memory safety, the pinned build, signed commits), **Designed** (most), or **Deferred** (with
a stated precondition, e.g. DMA confinement needs an IOMMU). §8 states which obligations bind at
which roadmap phase, so the gap between designed and built is never hidden. Writing it now, mostly
unbuilt, is §5.5: the capability, IPC and app-format RFCs are about to be argued, and this is the
paper they are argued against.
- Two pieces of guidance recovered from the retired docs repository during a completeness sweep, both
describing practices already followed but written down nowhere in this repository: `CONTRIBUTING.md`
gains **Amending the constitution** (leave no stale clause, check cross-references, never renumber a
cited section — the discipline `/check-coherence` automates), and `STYLE.md` gains a **Tables** rule
(preferred for parallel attributes; exempt from the line-length limit).
- `CLAUDE.md` — the founding document, placed under version control for the first time. This
repository is now its single canonical home; the organisation superfolder holds only a pointer to it,
so the two can never diverge.
Expand Down Expand Up @@ -41,6 +56,17 @@ recorded is indistinguishable from law that was never agreed.

### Changed

- **Constitution touched, twice, on the maintainer's authorisation, when the threat model landed.**
Both are factual or pointer updates rather than changes to any clause, and both are logged because
constitutional amendments always are, however small.
- The **Status line** no longer calls the threat model "the last outstanding Phase 0 deliverable" —
false the moment it merged — and now reads that Phase 0 is complete: the constitution, the settled
Borrow Ledger and the threat model are all written, with the kernel booting, greeting and
reporting its own faults.
- **§9's header** was "(seed — to be expanded)"; it now reads "(seed; expanded in
`docs/threat-model.md`)". §9's body is unchanged and remains the seed and the one-screen summary
the full document expands — the pointer just stops the header promising an expansion that now
exists.
- **The documents moved into the kernel repository, and the docs repository is retired** (2026-07-26,
maintainer's decision; RFC-0002 amended to record it). The two-repository split was double overhead
for a single maintainer — every cross-reference was a URL, every convention existed twice — and the
Expand Down
Loading