KN-86 Architecture Decision Records
Canonical, numbered architectural decisions for the KN-86 Deckline platform. Each ADR captures the context, options considered, decision, and consequences for one architectural choice. Once accepted, an ADR is immutable — superseding changes are made by adding a new ADR and marking the prior one Superseded by ADR-NNNN.
| # | Title | Status | Scope |
|---|---|---|---|
| 0001 | Embedded Lisp as cartridge scripting layer | Accepted | Runtime, cartridges |
| 0002 | Player-facing Lisp — REPL, nEmacs, scripted missions | Accepted (slip canceled by ADR-0016) | UX, runtime |
| 0004 | Bytecode VM selection (Fe) | Accepted | Runtime |
| 0005 | NoshAPI FFI surface enumeration (54 prims) | Accepted (amended 2026-04-24) | Runtime, cartridge authoring |
| 0006 | Cartridge format v2.0 | Accepted (amended 2026-04-24) | Cart format, tooling |
| 0007 | Lisp-scripted mission FFI & contract model | Accepted | Missions, runtime |
| 0008 | nEmacs structural editor UX | Partially superseded by ADR-0016 | On-device authoring |
| 0009 | Token prediction v1 ranking model | Accepted (extended by ADR-0016) | nEmacs editor |
| 0010 | ICE Breaker Lisp re-expression (reference) | Accepted | Reference implementation |
| 0011 | Pi Zero 2 W system image update system | Draft | nOSh runtime, deployment |
| 0012 | Lisp handler slot table widening | Draft | Runtime, cartridge authoring |
| 0013 | Cartridge physical format (shell + pinout) | Superseded by ADR-0019 | Hardware, BOM, fiction |
| 0014 | Display profile redesign (12×24 / 960×600) | Accepted | Display, framebuffer, font |
| 0015 | CIPHER-LINE auxiliary OLED display | Approved | Hardware, Cipher voice, NoshAPI, Universal Deck State |
| 0016 | nEmacs + REPL + input model (post-CIPHER-LINE) | Approved | nEmacs, REPL, input, cart FFI, keypad layout |
| 0017 | Realtime I/O coprocessor (Pico 2 / RP2350) — PSG + OLED only after cart-bus removal | Approved (cart-bus responsibility partially superseded by ADR-0019; audio + OLED remain in scope) | Hardware, Pico firmware, BOM, runtime envelope |
| 0018 | Custom mechanical keyboard build for 30-key input | Accepted | Hardware, BOM, input construction model |
| 0019 | Cartridge storage and form factor (SD-card sled) | Accepted | Hardware, BOM, cart format, capability model |
Archived
Section titled “Archived”Documents kept for history, not on the active decision path. See docs/_archive/architecture/adr/.
| # | Title | Reason for archive |
|---|---|---|
| 0003 | nOSh runtime update mechanism (Pico 2) | Pico / RP2350 target dropped. Pi Zero 2 W is the sole hardware target; see ADR-0011. |
Numbering
Section titled “Numbering”ADRs are numbered monotonically. Drafts and spike outputs are assigned their
final ADR number before landing on main — we do not promote “Spike ADR-0001”
documents into real ADRs retroactively, which caused the numbering confusion
that ADRs 0004–0010 resolved. Numbers are never reused; an archived ADR keeps
its number.
Authoring
Section titled “Authoring”Use the engineering:architecture skill to scaffold new ADRs. Match the
Status / Context / Decision / Options / Consequences / Action Items format of
ADR-0001 and ADR-0002.