Architecture decision records
Every architectural decision is an ADR in this directory: one file per decision, with Status, Context, Decision and Consequences sections. An ADR starts as a GitHub issue labelled adr; the accepted text is committed here. An accepted ADR is never edited — a change of mind is a new ADR that supersedes it, and the old one's status line says which superseded it.
Numbers
Blocks keep parallel work from colliding: 0000–0099 the harness (core, language, engine, CLI), 0100–0199 steps and adapters, 0200–0299 the hosted venture. The next ADR takes the next free number in its block.
Conventions
A file named NNNN-kebab-title.md — the number, then the title in lowercase kebab-case — with a heading that matches it, e.g. 0000-record-architecture-decisions.md begins # ADR 0000: Record architecture decisions.
A guard test (cargo test -p ks-testing --test adr_guard) checks every ADR below: the file exists, the heading matches the filename, and it is linked in the index exactly once.
Index
| ADR | Title | Status |
|---|---|---|
| 0000 | Record architecture decisions | Accepted |
| 0001 | Typed values and secret references | Accepted |
| 0002 | Ports and adapters | Accepted |
| 0003 | Workflow syntax | Accepted |
| 0004 | Secrets | Accepted |
| 0005 | Local-first core with optional hosted services | Accepted |
| 0006 | Licence and open-source model | Accepted |
| 0008 | GitHub Actions first | Accepted |
| 0009 | TypeScript escape-hatch runtime | Accepted |
| 0010 | Image build backend | Proposed |
| 0011 | Block distribution | Accepted |
| 0012 | Policy authority | Proposed |
| 0013 | Rust workspace | Accepted |
| 0014 | Release and contract versioning | Accepted |
| 0015 | Telemetry policy | Accepted |
| 0100 | Step contract and composition checks | Accepted |
| 0200 | Hosted venture on the Cratefield harness | Accepted |
| 0201 | Hosted on Cloudflare | Proposed |
| 0202 | Billing through Polar | Accepted |