Roadmap

energy-system is developed milestone by milestone, with no dates attached. The project practices what it argues: output is a function of capacity, not calendar. Milestones are ordered; the top unfinished one is what's being worked on now.

The canonical, always-current version lives in ROADMAP.md in the repository.

Shipped

v0.0.x - Foundations

The 5-level model with immutable, revisioned state; the framework-agnostic engine with strategy resolution; the first three built-in strategies (UI visibility, notifications, task complexity); the DOM adapter; React provider, hooks, and headless components; localStorage/memory persistence with external observation; deterministic clocks for testing; derived metrics; legacy-level compatibility mapping; published to npm.

M1 - Identity and polish (v0.1) - complete

Renamed and published as @kumbatio/energy-system (old name deprecated), an API review pass for naming consistency and exhaustive level handling, and CI running typecheck, lint, and tests on every PR.

v0.4 - Presence annotation and behavioral runtime - complete

Patterns studied in a field ADHD app (an email client that shipped focus mode, universal snooze, and notification batching) and reimplemented as first-class, tested primitives - including guarantees against the two failure modes observed in the wild: suppressed reminders destroyed instead of deferred, and focus suppression that never auto-expired. This shipped presence annotation, the notification gate with its defer-not-drop guarantee, focus sessions with auto-expiry, deferral presets with energy-aware ordering, the interaction forgiveness strategy, and prefers-reduced-motion handling in the stylesheet.

M3 - Reference integration - complete

kumbat.io migrated from its inline energy provider to this package and remains the living integration test. Since then the SDK has shipped in two real apps: Anasa (Kumbatio's writing workspace, public alpha - custom persistence, energy-gated AI surfaces, notification filtering) and Meltemi (an email client in private beta from entro314 labs, built outside the Kumbatio product line - notification gate, focus sessions, deferral, and interaction forgiveness, integrated without the React adapter). The case study of which adaptation strategies survived contact with real use is written: Production Patterns.

v0.6 - Autonomy and inbound demand - complete

The recipient's capacity applied to the queue that ignores it. Every triage system in general use is organised around properties of the message; this asks the same question about the receiver. Two additions: the autonomy strategy, which narrows what automation may do unattended as energy falls - the mirror of interaction forgiveness, since forgiveness protects against the user's mistakes and autonomy against the agent's - and inbound demand admission, a pure policy deciding whether an arrival that asks something of you reaches you now, is acknowledged and queued, or is queued in silence.

Policy only, and deliberately so: the effects an acknowledgment implies leave the process and cannot be made transactional by an in-process runtime, so the orchestration stays with the consuming app until a second consumer proves what the shared machinery actually is. That is the same order the v0.4 primitives arrived in - shipped in a real app first, generalised second.

v1.0 - Specification, conformance, and the API freeze - complete

The model is now specified independently of this implementation, so an implementation in another language is an implementation of the same model rather than a port of this one. SPEC.md is the normative, language-independent definition; spec/energy-state.schema.json is the interchange format for sharing one person's state across processes; conformance.json is 252 vectors plus every strategy table, generated on each build and shipped in the package, so the vectors cannot drift from the behavior they describe.

The freeze covers more than type signatures: a shipped strategy table's values are API, and so is the reconciliation rule - now exported as isPreferredEnergyState rather than buried in the engine, because it is the hardest part of the model to reimplement correctly. The accessibility review landed prefers-contrast: more and forced-colors: active handling, an honest statement of where the resting opacities stand against WCAG 1.4.11, and the requirements written into the spec so they bind ports too. Coverage now runs all 20 level transitions in both directions plus the model's directional invariants - protection never decreases and automation never gains discretion as capacity falls.

v2.0 - Corrections to the freeze - complete

Four correctness bugs found in 1.0 after it was frozen, and shipped as a major because for this package behavior is API even when no type signature moves.

The notification gate classified an intent once, when it was published, and then delivered an open batch window under whatever policy happened to be in force later - so something admitted at Steady could arrive mid-focus-session, and something batched at Steady could surface at Rest with every channel disabled. It now re-judges what it is holding whenever energy or suppression changes, in both directions, and flush() overrides the wait rather than the policy. External state is validated against the published schema exactly, so a state carrying unknown properties is rejected rather than silently trimmed - two implementations can no longer exchange a state and disagree about what they exchanged. A configured originId no longer corrupts the unproduced sentinel. And api-surface.json was missing EnergyEngine.resolve(), because the declaration parser did not recognise generic members: a method absent from the freeze is a method nobody notices removing.

The most uncomfortable of the four was in the guard itself. pnpm test ran the full build first, so the drift check compared conformance.json against a copy it had just written - it could not fail, whatever was committed. Both generators now take --check, generation belongs to build, and the suite verifies rather than regenerates.

The React peer range also moved to >=19.2.0: the React entry point imports <Activity>, so the previous >=19 advertised a compatibility that throws on first render.

In progress

M2 - Documentation for real adoption

• Docs readable at energy 25: short pages, one concept each, optional depth (this site is that effort)
• An example gallery: navbar, dashboard, form, and notification patterns at each level
• An adaptation strategy authoring guide

Upcoming

M5 - Beyond the current adapters

Web-component and vanilla examples, plus an additional framework adapter chosen by adopter demand - open an issue to vote.

A first non-JavaScript implementation belongs here too, when a real consumer needs one. The spec and vectors are what make that a small job rather than a fork, and the bet is that the first genuine demand is server-side rather than another UI framework - that is where the energy models which did not adopt this one already live.

Continuous work

• Issues and PRs from adopters take priority over roadmap order when they unblock a real shipped use.
• Research translation: mapping the model against cognitive load and occupational health literature, and correcting the model where it oversimplifies.

How to influence this

Open an issue. Adopters shipping real features get the loudest voice; sponsors get roadmap input, never veto - the decision filter outranks money.