SPORE roadmap — milestones

Project: sloev/spore · Version: 0.6.0 (Cargo.toml).

This is the single forward-looking plan, organised as milestones rather than a flat PR map. Each milestone is a coherent body of work with a clear definition of done; PRs are the merge units inside a milestone, not the plan itself.

"What shipped" lives in exactly one place — Changelog ## Unreleased and the Status column in each milestone — so no second progress table can drift. Shipped work keeps its CHANGELOG entry and loses its spec here; the code is the truth.

Read order for agents: Mission → this file → Changelog → SPEC/CONTINUITY only as needed. See Dev guide for the full repo map.

Hard rules (do not violate)

• Frozen: wire format, C ABI (bindings/spore.h), reference/vectors.json, and the API surface in tests/api_freeze.rs. No change without the allow-frozen-change label.
• Honesty over polish: 🧪 markers, "Still open", served-vs-fetching language, and no fake UI — never a control whose backend is missing.
• HARDBRUT upstream (supernihil/hardbrut) is normative for colour, contrast, motion and components — SPORE no longer maintains its own design-language document; web/vendor/hardbrut/hardbrut.css is vendored at build time and trusted as-is. The one SPORE-specific rule HARDBRUT has no opinion on: the icon system is Antenna + Seed. Never signal failure by colour alone.
• Zero external network requests in web/spore-standalone.html (CI greps for it).
• Motion fully static under reduced motion / ANIMATOR_DURATION_SCALE == 0. Sound and particle bursts stay off until the user enables them.
• One concern per PR (CI-green alone). Security and design-language work are orthogonal when independent.
• Distinguish Verified (code/CHANGELOG) vs Reasoned vs Needs device run. Do not claim hardware verification that was not run, or invent protocol features.
• No icon, no mascot. SPORE's brand is the wordmark — plain "SPORE" text — on every surface. Nothing stands in for it, not even a monogram; Android's ic_spore.xml is a plain HARDBRUT accent swatch because the platform requires an icon file to exist, not because it represents anything.

Milestone 0 — Repo & docs hygiene ✅

Goal: a clean root and a docs/ folder that holds every doc except README.md.

Definition of done: ls at repo root shows only README.md, source dirs, build files (Cargo.*, deny.toml, rustfmt.toml), LICENSE, spore.example.yaml, and essential config (.github/, .gitignore). Site build + token generation green.

Milestone 1 — Security & correctness

Goal: close the last forward-secrecy and store-bounds gaps; make every spec claim the code actually honours.

Definition of done: every SPEC claim about forward secrecy and store bounds is backed by a test; the ## Unreleased SECURITY_FINDINGS Still-open list has no P0 items that are not either fixed or honestly marked deferred-to-hardware.

Milestone 2 — Core functionality & reliability

Goal: the phone node and daemon are credible daily drivers on the transports that are verified, with honest limits on the ones that aren't.

Carried-forward functional gaps (still real, not regressions):

• Multiple files per send (v1 is one attachment per message)
• ExoPlayer audio/video inline preview + playback
• Edit / remove an attachment after send
• Merge the bubble for public/unsealed files (needs nativeEnvId at route() time)
• Edit a bridge in place (today Remove + re-add; needs a native mutate helper)

Definition of done: a minimum-credible phone node — M1 + attachments usable end-to-end + bridges stoppable/removable + one device-matrix pass (backup exclusion + migration). Direct connects on a LAN and degrades honestly on a WAN.

Milestone 3 — Design language implementation

Goal: every surface adopts Antenna + Seed, the three control sizes, the density rules, and the screen structures the design language called for at the time. Superseded by Milestone 6 (HARDBRUT); kept here as a historical record — the old SPORE-authored design document this milestone shipped is retired.

This is a first-class milestone, not scattered "nice-to-have" items. The tokens already exist and are generated (C3/C5-token half shipped #118/#119); the work below is the code half that changes what is on screen.

Acceptance (across the milestone):

• Only three interactive control heights exist, in the tokens and in the code.
• Bridges uses uniform list rows; no heterogeneous full-width button stack.
• Advanced is sectioned rows, not a tall card stack.
• No working screen opens with more than one short instructional sentence.
• Status chrome is compact — 0 peers · 65 stored.
• The site has persistent, clear navigation.
• The web node has a persistent identity + status header.
• Reduced motion is fully static; the standalone still makes zero external requests.
• Baud appears only on empty states and completions. Superseded: Baud is removed entirely — brand is the SPORE wordmark only, no mascot (see the hard rules).
• The only brand icon is Antenna + Seed; no mushroom anywhere.

Definition of done: every surface passes visual review and the mushroom icon is gone from the repo's rendered assets. (Historical: at the time this milestone shipped, the checklist lived in the now-retired docs/VISUALDESIGN.md §8; superseded by M6/M7, which hold HARDBRUT upstream normative instead.)

Milestone 4 — Webnode as daily driver

Goal: the browser is a full daily-driver peer (Chats / Feed / Files / Bridges / Seed), not a transport demo. The first runtime to consume M1's storage seam and the communicator-as-façade pattern.

Surfaces (locked IA): Chats (unified: 1:1 DMs + open groups + private groups) · Feed (personal microblog + subscribed feeds) · Files · Bridges · Seed. The old Mail / Topics / Sealed-Topics panels are merged into Chats; the old shared spore/feed topic is replaced by per-address feeds.

Guardrail: this stays a reference client, not "the" SPORE app. No feature here requires the standalone HTML specifically; a bridge, a Python script, or the daemon CLI must remain equally capable.

Terminology (locked): the communication surfaces map to known idioms, not protocol jargon. The protocol primitives are unchanged — this is IA and UI only.

Two communication surfaces: Chats — a unified list of all conversations (1:1, open groups, private groups — the authorized channel) with type badges and a new-conversation picker — and Feed — your personal microblog (feed::<your_addr>) plus subscribed feeds. Files, Bridges, and Seed remain separate surfaces.

Private group vs. public microblog — locked. A private group is an authorized feed: posts are sealed with a shared PSK, so "member" means "holds the key," never "on a verified roster." There is no separate "authorized feed" surface — the private group in the Chats list is the authorized channel. Revocation is by key rotation and is forward-only (SPEC §7.1): rotation denies going-forward reads but cannot recall a copied key, and SPORE holds no member list, so a "revoked member" is never claimed. The invite flow shares the key blob safely; this and the documented revoke limit are W7.

UI across runtimes (locked decision): two UI implementations over three shared layers — browser/desktop share the web UI (in-process wasm vs localhost HTTP to daemon); Android stays Compose. Desktop is daemon + web UI, optionally wrapped in Wry (not Tauri). Do not wrap the standalone in a window and call it desktop.

Definition of done: two browsers on a LAN can DM, open group chat, private group chat (with key), microblog-post (to their own feed::<addr>) and subscribe to each other's feeds, publish + fetch a file — all through the standalone HTML, no daemon involved — and still be a full node (store, bridges, same envelopes). Chats is one unified list; Feed is personal + subscribed.

Milestone 5 — Polish & hardening

Goal: the sweep-up after the above. Only start this milestone once M1–M4 are done. Nothing here is load-bearing for a credible node.

Milestone 6 — HARDBRUT visual language

Goal: replace the Neo-Tokyo Tactical Wasteland design language with HARDBRUT (supernihil/hardbrut, v0.6) across all three surfaces — the web node, the Pages site, and the Android app. HARDBRUT is a light-first neubrutalist system: cream paper #fdfaf2, black ink, yellow #ffd23f actions, zero border-radius (except true circles), and hard offset shadows (5px 5px 0 #000, no blur) that stay on every element and vanish only during a press. Two button kinds — default (yellow) and cancel (white). Auto dark mode.

Locked decisions (so the three surfaces cannot drift):

Tasks (each a PR; tokens first, then surfaces, then the spec):

Definition of done: all three surfaces render HARDBRUT (cream paper, black ink, yellow primary / white cancel, zero radius, hard no-blur shadows held on every element); Antenna + Seed persists ink-on-paper; Baud is restyled; the standalone still makes zero external requests and is fully static under reduced motion; the drift job regenerates HARDBRUT tokens into all three surfaces and passes.

Milestone 7 — HARDBRUT as the framework (build-time import), not a copy ✅

Goal: stop maintaining a forked copy of HARDBRUT inside SPORE's own CSS. Today design/tokens.json + generate.py re-emit a subset of HARDBRUT tokens into site/style.css, the standalone's inline <style>, and Android's Chrome.kt — a hand-maintained clone that forks the moment supernihil/hardbrut moves. M7 replaces all of it with the real hardbrut.css vendored at build time, and rebuilds both web surfaces' markup around HARDBRUT's actual classes (.navbar, .hero, section, button, markdown, data-accent, data-theme).

Build-time import (locked). The web build pulls hardbrut.css from supernihil/hardbrut during the build and inlines it into the Pages site (site/build.mjs) and the standalone (build-standalone.mjs) — there is no site/style.css anymore. A change to the HARDBRUT repo is reflected on the next rebuild — no runtime @import, so the standalone keeps its zero-external- request CI guarantee. The vendoring dir and the remote/ref are pinned and documented so the import is reproducible, not a silent network dependency of every CI run.

Android (locked). Compose has no CSS to @import, so Android gets its own vendored source instead: android/app/src/main/kotlin/org/spore/node/vendor/ Hardbrut.kt, supernihil/hardbrut's official Compose port, pulled live by android/hardbrut-sync.py — same "always latest, pinned ref, no runtime fetch" contract as the CSS side. Chrome.kt's tokens alias that file's HardbrutTokens directly; only dark mode (which that file doesn't define) still comes from the vendored CSS. Chrome.kt keeps the Compose primitives that XML cannot express and that the drop-in file doesn't provide — press-feedback shadows, touch targets, Chip/ListRow/ToughbookField/CrateSwitch/SegmentedLed — but now builds their static shadow-drawing on the vendored hardShadow() rather than a third hand-rolled copy of the same offset-rect math.

Tasks (each a PR):

Definition of done: site/build.mjs and the standalone's CSS are the vendored hardbrut.css (plus a thin SPORE-asset layer), not a fork; editing supernihil/hardbrut and rebuilding SPORE changes all three surfaces — the two web surfaces on the next hardbrut-sync.mjs + rebuild, Android on the next hardbrut-sync.py + design/generate.py; the standalone still makes zero external requests; Android's Chrome.kt aliases the vendored Hardbrut.kt's tokens and shadow primitive rather than maintaining its own copy, keeping only the product-specific primitives (touch targets, press feedback, Chip/ListRow/etc.) that file doesn't provide. (Antenna + Seed and Baud were later retired entirely — see the hard rules: the brand is the wordmark, nothing stands in for it.)

Milestone 8 — Embedded ESP32 runtime (raw-802.11 relay)

Goal: the first real implementation of the Embedded (ESP32) runtime docs/DESIGN.md already names ("little memory, no filesystem, one or two bridges") — a standalone, headless ESP32-S3 that relays real envelopes over raw 802.11 frames, persists its store to flash, and bridges to a phone or laptop over USB or BLE when one is nearby. Filed as #149.

Flash it and it works; a tether is just another bridge (locked). There is no standalone build and no tethered build, no mode switch, no pairing and no configuration step. A board that has been flashed and given power is already a working node. Binding on every task below:

• Untethered and unconfigured is the normal state. The board boots and carries traffic with nothing attached and nothing set up — the radio comes up on a fixed default so that two boards out of the same box find each other with no intervention. A board dropped in a field with a battery is the design target, not a degraded case.
• A connection to another device is a bridge, not a mode. USB serial, BLE — these register on the hub exactly like the radio does, and the core floods between all of them because that is what it already does for every other bridge. Nothing in the firmware knows the word "tether". Plugging a cable in adds an interface to a node that was already running; unplugging removes it and changes nothing else.
• So gateway behaviour is emergent, not a feature. A phone on USB OTG serial gets the raw-802.11 mesh through the board, and the mesh gets the phone's internet, Bluetooth and folder bridges back — because the board floods between its two interfaces and the phone floods between its several. Neither end has a "gateway" code path; it is two ordinary nodes each doing the one thing the core has always done. If a gateway role ever needs writing, something has gone wrong — the design has stopped being bridges-on-a-hub.
• Neither role is a build-time choice. Selecting behaviour with a cargo feature would mean two firmwares to test, two ways to be wrong, and "which one is on this board?" as a question anyone ever has to ask.
• Configuration cannot require a tether. Defaults have to be good enough to relay out of the box, anything persistent lives in flash, and nothing waits on a companion app — otherwise the tether is load-bearing by the back door.

The ordering follows from this rather than the other way round: E2/E3 (radio, store) come before E4/E5 (USB, BLE) because a bridge attaches to a working node, so there has to be one to attach to.

The daemon speaks the same air interface (locked). Raw 802.11 is not an embedded-only bridge. A Linux daemon with a monitor-mode-capable card runs the same frame format (E2d below), so a laptop is a peer of the boards rather than just something they tether to — which is what makes a mixed deployment of cheap relays and a real machine one mesh instead of two. The frame layout is written into Bridges before either side is finished, because board-to-board interop happens by accident when both run our code, and board-to-laptop interop only happens if the framing is specified.

This is less new architecture than it might look. The bridge-shape taxonomy already lists LoRa/Meshtastic as "message pipe" examples (docs/DESIGN.md §"Bridges & bindings") — raw 802.11 is another one, not a new shape. The storage nutrient (SpillBackend trait, M2, #87) already shipped specifically to unblock browser/ESP spill — this milestone writes a littlefs-backed implementation of an existing contract, not a new one. The USB bridge reuses the existing KISS byte-stream framing (bridge::kiss_stream), same as the serial/Meshtastic bridges. The new work is genuinely just the radio driver (promiscuous RX filter + esp_wifi_80211_tx injection) and the BLE fallback.

Toolchain (locked): esp-idf-sys, not bare-metal esp-hal. ESP-IDF's std-like environment (newlib) means the core likely compiles close to as-is. A bare-metal no_std port would very likely reopen "Compile-time max_core gating," declined elsewhere in this document with the explicit exception "revisit only if a real MCU target proves it necessary" — this milestone is that target, but starting from esp-idf-sys avoids forcing the reopening on day one. Bare-metal esp-hal is an explicit non-goal for M8; a future milestone can attempt it if esp-idf-sys proves too heavy for the target board.

Regulatory posture (locked): documented, not enforced. Raw 802.11 frame injection/monitor mode outside normal association, and running encrypted traffic over any band whose rules restrict it (amateur radio's no-encryption rule, most notably), are the operator's compliance problem, not SPORE's to police. The bridge's BRIDGES.md entry states plainly what it does and names the regulatory considerations that follow from that — same as disclosing a mix mode's limits — but SPORE does not gate, strip, or weaken encryption to comply with a band's rules on anyone's behalf. Silent non-compliance would be dishonest; refusing to build the feature over a rule the operator may not even be subject to is not this project's call to make.

Tasks (each a PR). Work is tagged E1–E6 and ordered on three principles:

• Biggest risk first. E1 answers does the core compile, link, and actually run on this board, in this much RAM, under esp-idf-sys? Nothing else in M8 is worth building until that answers yes.
• Nutrient work stays distinct from bridge work. E1 and E3 supply the four nutrients this runtime owes the existing core contract (randomness, time, scheduling, storage — Design); E2, E4 and E5 put the board on the open bridge list. Conflating the two is how a runtime ends up inventing protocol.
• Solo before paired. Each phase names what one board alone can prove, so the work is not blocked on owning two of everything. Only the rows that say so need a second device.

None of the three bridges is new. Raw 802.11, BLE GATT and USB/serial-over-KISS are all already specified in Bridges — BLE down to the Nordic UART UUIDs, USB as byte-for-byte KISS, and 802.11 with the ESP32 path and regulatory note added alongside Envelope::probe. Two of them already have a working browser half (web/transports/webbluetooth.mjs, webserial.mjs), so E4 and E5 are making the board the peer for clients that already exist and already speak the framing. That is why no row below is a design task: the shapes are decided, and what is missing is the firmware side of each.

Issue #149's own phase order (env setup → radio harnessing with a mock envelope → wire to Node::on_rx → USB-CDC) maps onto E1 + E2 + E4. The flash store (E3) and the BLE fallback (E5) go beyond what the issue scoped.

Toolchain checkpoint (E1) — measured, and the decision stands. The scaffold plus one signed envelope costs, on a release build:

Comfortable, and measured before the 802.11 driver, littlefs and a BLE stack pile on top — which was the point of checking here rather than later. esp-idf-sys stays the locked toolchain, bare-metal esp-hal stays a non-goal, and compile-time max_core gating stays declined: its stated exception ("revisit only if a real MCU target proves it necessary") is exactly what these numbers fail to trigger. The CI job prints both figures on every run, so the headroom is tracked as E2–E5 land rather than measured once and assumed.

Three caveats on what this does not say. These are static sections, not live heap — runtime headroom is a device-run number the smoke test still owes. The flash figure excludes the bootloader, partition table, and any littlefs partition E3 adds. And the flash total is approximate on purpose: it moves by ~100 bytes between build environments because panic messages bake in absolute source paths, so CARGO_HOME being one directory deeper changes it. Compare runs, not the last digits.

Definition of done: an ESP32-S3 running this firmware relays real SPORE envelopes over raw 802.11 to at least one other node, bridges to a phone or laptop over USB (KISS) with BLE as the low-bandwidth fallback, and its store survives a power cycle via flash — with HARDWARE.md recording a real device-pair run, not just green CI. 🧪 until then.

Explicitly out of scope / non-goals (locked)

Product decisions (locked, not proposals)

Anonymity — an explicit, non-default toggle

The primitives exist (src/mix.rs); the toggle + a runnable mix-operator example (P-Mix-Runner) make the path operable. Clearnet exit is a separate, off-by-default convenience feature, never described as anonymity.

Direct NAT traversal — settled

iroh is the NAT answer; the hand-rolled punch is demoted to an optimisation. The ladder, each rung only where a runtime can supply it: LAN → global IPv6 → overlay → reflexive (punch) → iroh relay/fallback → fail honestly. CGNAT-to-CGNAT with no working relay still fails sometimes; a relay is the permanent escape hatch, not a cleverer punch. Claim exactly what the ladder covers, never "arbitrary NAT traversal."

Priority compass (when picking up new work)

1. M1 — Security & correctness (no P0 stays open)
2. M2 — Core functionality (credible phone + daemon node)
3. M3 — Design language (Antenna + Seed, three sizes, density, screen structures)
4. M4 — Webnode as daily driver (first runtime on the storage seam)
5. M5 — Polish & hardening (only after the above)
6. M6 — HARDBRUT visual language (replaces M3's language across all surfaces; tokens first, then surfaces, then the spec)
7. M7 — HARDBRUT as the framework (vendored at build time, not a copy; all three surfaces done)
8. M8 — Embedded ESP32 runtime (raw-802.11 relay; first real MCU target) — after the still-open carried-forward items in M2/M4/M5, not ahead of them, unless deliberately reprioritized

Hardware/community work (the former "Track H" — lived-in prototype, solar cyberdeck, wear language, community harvest, maintainer culture) is deliberately not a milestone, and is a different thing from M8: Track H is aesthetic/cultural — objects and vibes, nothing a protocol change depends on — while M8 is a real runtime implementation the design already committed to. Track H: every row is ⬜ concept, nothing in the compass depends on it, and no row earns a 🧪 until something exists a person could hold or run. It was written up as inspiration in the now-retired docs/VISUALDESIGN.md §6b, not in this plan as a promise; no replacement doc is planned — HARDBRUT upstream has no opinion on hardware/community concepts, so there is nothing for it to be normative about.

Tasks removed or heavily changed from the old PR-map

Actionable plan derived from the 0.6.0 tree, the audit tour, and the new design language. Update when work lands or hardware results arrive.