core/ROADMAP.md

# Armature — Roadmap

## Current: v0.9.x — Workflow Redesign + Multi-Surface Packages

Self-hosted extensible platform kernel. Auth, identity, packages, Starlark
sandbox, storage, realtime, and ops are kernel primitives. Everything else
is an extension.

**Kernel capabilities:** Auth (builtin/mTLS/OIDC) · Users/teams/groups/RBAC ·
Surfaces/extensions/libraries/workflows · Starlark sandbox (capability-gated) ·
Object storage (PVC/S3) + ext_data tables · WebSocket hub + realtime pub/sub ·
Audit log · Notifications · Scheduled tasks · Cluster registry + HA ·
Extension composability (slots/contributes/cross-package calls)

---

## Completed — v0.6.x through v0.8.x

All completed work is documented in `CHANGELOG.md`.

### v0.6.x — MVP + Hardening

| Version | Title |
|---------|-------|
| v0.6.0 | Cluster Registry + HA |
| v0.6.1 | Backup/Restore + Docs |
| v0.6.2 | Docs Polish + Dynamic OpenAPI |
| v0.6.3 | Dead Code Sweep + Registry Fix |
| v0.6.4 | Admin Health/Metrics + Cluster Merge |
| v0.6.5 | Renderer Pipeline + Docs Rewrite |
| v0.6.6 | Final Hardening |
| v0.6.7 | Native mTLS |
| v0.6.8 | Rebrand + Cookie Fix |
| v0.6.9 | Session Lifetime Config |
| v0.6.10 | Viewport Foundation |
| v0.6.11 | CSS Deduplication |
| v0.6.12 | Extension CSS Isolation |
| v0.6.13 | Responsive & Spacing |
| v0.6.14 | Visual Polish |
| v0.6.15 | User Display Audit |
| v0.6.16 | Usability Survey Gate |
| v0.6.17 | Bug Fixes & Welcome |
| v0.6.18 | CI Bundle Wiring |

### v0.7.x — Test Infrastructure + Quality Gate

| Version | Title |
|---------|-------|
| v0.7.0 | Shell Contract + Surface Audit + Rebrand |
| v0.7.1 | Surface Runner Framework |
| v0.7.2 | Package Runners + CI Gate |
| v0.7.3 | Extension Shell Migration |
| v0.7.4 | Documentation + Surface Work |
| v0.7.5 | Headless E2E + CI Gate |
| v0.7.6 | Code Hygiene + Test Coverage |
| v0.7.7 | API Tokens + Extension Permissions |
| v0.7.8 | Bug Fixes & Admin Gaps |
| v0.7.9 | Workflow Independence Audit |
| v0.7.10 | Workflow Handoff + Assignment UI |
| v0.7.11 | Query & HTTP Ergonomics |
| v0.7.12 | Concurrent Execution Primitive |

### v0.8.x — Storage Primitives + Composability (Kernel Complete)

| Version | Title |
|---------|-------|
| v0.8.0 | `files` Module |
| v0.8.1 | `workspace` Module |
| v0.8.2 | Capability Negotiation |
| v0.8.3 | Vector Column Type |
| v0.8.4 | Documentation Refresh + Surface Sizing Fix |
| v0.8.5 | Extension Composability |

---

## Planned

### v0.9.x — Multi-Surface Packages + Workflow Redesign

**v0.9.0 — Multi-Surface Packages** *(completed)*

Packages declare a `surfaces` array with per-path access controls,
titles, and layouts. Unified route tree dispatches between surface
rendering and ext API calls. `sw.navigate()` for client-side sub-path
routing. Design doc: `docs/DESIGN-multi-surface.md`.

**v0.9.1 — Server-Side Sub-Path Routing** *(completed)*

Consolidated root and catch-all route handlers into a unified dispatcher.
Added `aggregateAccess()` for early auth short-circuit on all-authenticated
packages. SDK seeds initial history state for back-button resilience.
8 handler integration tests + 5 aggregateAccess unit tests.

**v0.9.2 — Starlark Converter Consolidation + Snapshot Cleanup** *(completed)*

Consolidated duplicate Go↔Starlark converters into `sandbox/convert.go`
(4 exported functions) and snapshot parsers into `models/snapshot.go`.
Standardized on wrapped snapshot format. ~350 lines of duplication removed.
Design doc: `docs/DESIGN-workflow-redesign.md`.

**v0.9.3 — Team User Roles** *(completed)*

Many-to-many `team_user_roles` table. `RequireRole()` middleware.
Manifest `requires_roles` field (advisory). Starlark `teams` module
with `get_member_roles()` and `has_role()`. Team-admin UI with role
badge chips and assignment dropdown. 10 new tests.

**v0.9.4 — Package Adoption + Roles** *(completed)*

`adoptable` manifest field + `team_role_catalog` table. When a team
adopts an adoptable package, the package's `requires_roles` auto-populate
into the team's role catalog. Adopted packages reference the original via
`adopted_from` column (shared assets, no disk duplication).
`AdoptTeamWorkflow` deprecated in favor of package-level adoption.
4 new endpoints, migration 017, 11 new tests.

**v0.9.5 — Typed Forms → SDK Primitive** *(completed)*

Extracted `TypedFormTemplate`, `FormField`, `FormFieldset`, etc. from
`models/workflow.go` into a standalone `forms` package. REST endpoint
`POST /api/v1/forms/validate`. Starlark `forms.validate()` module.
FE SDK: `sw.forms.render()`, `sw.forms.validate()`, `sw.forms.validateRemote()`.
Manifest `form_template` accepted at package level. 16 new tests.

**v0.9.6 — Deprecate `stage_type`, Collapse `stage_mode`** *(completed)*

`stage_type` deprecated (no longer validated, defaults to "simple").
`stage_mode` collapsed from 4→3 values: form / delegated / automated.
"review" mapped to "form" on input; review surface removed (~110 lines).
Migration 018. 4 package manifests updated.

**v0.9.7 — Full Read/Write Workflow Starlark Module** *(completed)*

`WorkflowEngine` interface extracted in sandbox package to break
circular import. Four write builtins added: `workflow.start()`,
`workflow.advance()`, `workflow.cancel()`, `workflow.submit_signoff()`.
`instanceToDict` and `signoffToDict` helpers shared by read+write paths.
6 new tests.

**v0.9.8 — Conditional Routing → SDK Primitive**

Expose `routing.evaluate(rules, data)` as a Starlark SDK function.
Branch rules become a reusable decision engine for any extension.

**v0.9.9 — Surface Access via Roles**

Wire team roles (v0.9.3) into surface access declarations:
`access: role:approver`. Kernel middleware checks role membership.
Completes the workflow→package access story.

---

### v0.10.x — Panels + Composable Layout

Panels are a new kernel rendering tier between surfaces (full-page) and
block renderers (inline). They solve composable companion views — e.g.,
a notes reference panel inside chat. Design doc: `docs/DESIGN-panels.md`.

| Version | Title |
|---------|-------|
| v0.10.0 | Panel Manifest + Lifecycle |
| v0.10.1 | FloatingPanel Primitive |
| v0.10.2 | Docked Panels + Mode Transitions |
| v0.10.3 | Panel Communication Patterns |
| v0.10.4 | Reference Panel: Notes (basic) |

---

### v0.11.x — Notes Reference Extension

Notes becomes the first reference extension — a production-quality
knowledge base that exercises every kernel primitive. The UI/UX redesign
is front-loaded as v0.11.0 so every subsequent feature version builds on
a clean visual foundation. Design doc: `docs/DESIGN-notes-v011x.md`.

| Version | Title |
|---------|-------|
| v0.11.0 | UI/UX Foundation — visual redesign |
| v0.11.1 | Deep Folders + Navigation |
| v0.11.2 | Wikilinks + Backlinks |
| v0.11.3 | Live Preview + Rich Editing |
| v0.11.4 | Note Sharing + Permissions |
| v0.11.5 | Graph + Outline Hardening |
| v0.11.6 | Quick Switcher + Commands |
| v0.11.7 | Daily Notes + Templates |
| v0.11.8 | Transclusion + Embeds |
| v0.11.9 | Composability: Slots + Actions |
| v0.11.10 | Panel Enhancement + Quality Gate |

---

### v0.12.x — Chat Reference Extension

Chat becomes the second reference extension — human-to-human messaging
built entirely on Armature's extension architecture. Where notes proved
surfaces, panels, and storage, chat proves **realtime**, **cross-package
composition**, and **extensible data models**. Chat is human-to-human
first; AI participants arrive via `llm-bridge` (v0.13.x) extending chat
through folder attributes and slot contributions.
Design doc: `docs/DESIGN-chat-v012x.md`.

| Version | Title |
|---------|-------|
| v0.12.0 | UI/UX Foundation |
| v0.12.1 | Conversation Folders + Attributes |
| v0.12.2 | Reactions + Threads + Pins |
| v0.12.3 | Rich Compose + Attachments |
| v0.12.4 | @Mentions + Notifications |
| v0.12.5 | Link Previews + Message Formatting |
| v0.12.6 | Conversation Themes + Personality |
| v0.12.7 | Composability: Slots + Actions |
| v0.12.8 | Panels + Quality Gate |

---

### v0.13.x — Reference Libraries + Extensions

Custom public root surface unblocks everything — anonymous visitors,
landing pages, and the package registry. `llm-bridge` is the key
library delivery — extends both notes and chat through composability
primitives, and introduces the **tool meta-tool** pattern:
`sw.actions.list()` becomes the LLM tool registry, so installing an
extension = granting AI a new capability. Zero configuration.
`armature.run` deployment is the dogfood gate at the end of the series.

| Version | Title |
|---------|-------|
| v0.13.0 | Custom Public Root Surface |
| v0.13.1 | `vector-store` Library |
| v0.13.2 | `llm-bridge` Core Library |
| v0.13.3 | `llm-bridge` → Chat: Multi-Persona Context + Tool Meta-Tool |
| v0.13.4 | `llm-bridge` → Notes: AI Toolbar Actions |
| v0.13.5 | `file-share` Extension |
| v0.13.6 | Package Registry Extension |
| v0.13.7 | `code-workspace` Extension |
| v0.13.8 | `image-gen` + `image-edit` Extensions |
| v0.13.9 | Tool Meta-Tool Hardening + Scoping |
| v0.13.10 | `armature.run` Deployment |
| v0.13.11 | Integration Quality Gate |

---

### v0.14.x — Sidecar Tier

Connect-inward model: sidecars connect TO the kernel (no K8s RBAC, no
service mesh, no DNS discovery). Instance sidecars (shared infrastructure)
and user sidecars (personal local tools). Design doc:
`docs/DESIGN-sidecar-v014x.md`.

| Version | Title |
|---------|-------|
| v0.14.0 | Sidecar Registry + Auth |
| v0.14.1 | Capability Registration + Execution |
| v0.14.2 | Kernel API Access + Event Bus |
| v0.14.3 | Manifest Integration + Admin Polish |
| v0.14.4 | Reference Sidecar (`armature-embed`) + Instance Gate |
| v0.14.5 | User Sidecars + Reference (`user-bridge`) + User Gate |

---

### v0.15.x — Polish + Stability

| Version | Title |
|---------|-------|
| v0.15.0 | Native Dialog Audit |
| v0.15.1 | Versioned Migrations + `armature migrate` CLI |
| v0.15.2 | Pre-1.0 Schema Freeze + Upgrade Path Validation |

---

### v1.0.0 — Stable Release

Kernel API surface frozen. Extensions are the product.

Gate criteria:

- All kernel Starlark modules documented with examples
- All `api_routes` covered by OpenAPI spec
- Upgrade path tested from v0.8.0 → v1.0.0
- Notes reference extension shipped with all v0.11.x features
- Notes UI/UX reviewed against v0.11.0 design principles — no placeholder UI
- Chat reference extension shipped with all v0.12.x features
- `llm-bridge` extends both notes and chat through composability
- Tool meta-tool demonstrated: AI uses 3+ extension actions in a
  single conversation turn
- Multi-persona context archetypes demonstrated
- Admin safety rails validated
- At least 2 panels consumed cross-package
- At least 2 slot contributions per host surface demonstrated
- Note and conversation sharing functional end-to-end
- Headless E2E green on PG + SQLite
- `armature-ca.sh` + mTLS deployment guide
- Single-binary + Docker + K8s deployment paths documented
- Instance sidecar (`armature-embed`) deployed and functional
- User sidecar (`user-bridge`) functional on macOS/Linux/Windows
- Token + mTLS sidecar auth both tested
- `armature migrate` CLI functional

---

## Post-1.0 Horizon

These are candidates, not commitments. Each requires a design doc.

- **Federation** — cross-instance package sharing, identity federation
- **Package marketplace** — signing, review, discovery registry
- **Desktop app** — Tauri wrapper for local-first deployment
- **Offline/sync** — SQLite-first with PG sync for field deployments
- **Multi-tenant SaaS mode** — tenant isolation at the team boundary

---

## Design Principles

| Principle | Implication |
|-----------|-------------|
| Extensions are the product | Chat, tasks, LLM, vector search, file sharing — all extensions. Zero kernel awareness of domain logic. |
| Kernel stays thin | New kernel primitives require justification. If it can be an extension, it must be. |
| Progressive enhancement | Every feature works on SQLite. PG adds performance. pgvector adds native vectors. S3 adds scalable storage. |
| KISS-first | No unnecessary dependencies. Preact+htm (3KB), single binary, dual-DB from one codebase. |
| Changeset discipline | Each CS independently CI-green. Design docs as implementation contracts. |
| Pre-1.0 migration freedom | Schema changes fold into existing migrations. Post-1.0: proper versioned migrations. |

---

## Design Decisions Log

| Decision | Rationale |
|----------|-----------|
| Tasks → extension | Three trigger primitives replace the monolithic scheduler. |
| Sessions removed | Workflow instances with dedicated storage replace kernel sessions. |
| `custom` stage mode | Delegates to a surface package, proving extension composability. |
| Providers removed from kernel | Connections + Starlark `provider.complete` as the interface. |
| Kernel permissions simplified | 6 platform permissions. Extensions define their own. |
| Preact+htm retained | 3KB runtime, no build step, KISS. |
| Single Docker image | Go binary + assets + migrations. |
| Admin → RBAC group | Grant check replaces role check. |
| Settings cascade | Scope auth + `user_overridable`. Two orthogonal axes. |
| Chat as extension, not kernel | Zero kernel awareness. Proves extensibility thesis. |
| PG as consensus layer | UNLOGGED node_registry + LISTEN/NOTIFY. No etcd/Consul/Redis. |
| Two trigger tiers | Extension-declared (full sandbox) vs user ad-hoc (restricted). |
| Two-slot topbar model | Left slot (title/branding) + center slot (`flex: 1`, tabs/pickers). |
| `db` module is the structured store | No separate KV primitive. Extensions declare tables. |
| `files` module rides ObjectStore | No new kernel tables. Metadata as companion objects. |
| `workspace` for real filesystem | Flat blob store can't serve git/compilers/ffmpeg. Managed disk paths. |
| Capability negotiation at install | Fail loud with actionable message, not silently at runtime. |
| Vector column with three-tier fallback | Works everywhere, works fast with pgvector. |
| Sidecar deferred to v0.14.x | HTTP module covers external APIs. Sidecars connect inward (no k8s RBAC needed). |
| Workflow redesign before reference extensions | Clean up debt and promote primitives before building on top. |
| Panels as kernel primitive (v0.10.x) | Z-index coordination, drag/resize, layout negotiation are kernel concerns. |
| UI/UX redesign as first version in each reference series | Every feature builds on the visual foundation. Front-loading avoids double work. |
| Notes as dedicated v0.11.x series (11 versions) | Complex enough to need changeset discipline. Each version independently shippable. |
| Notes before chat | Notes is simpler (no realtime) and proves storage/rendering/composability. Chat adds realtime + llm-bridge story. |
| Chat human-to-human first (v0.12.x) | AI is an extension concern. Keeps chat testable and usable standalone. |
| Chat as dedicated v0.12.x series (9 versions) | Second reference extension. Proves realtime, extensible data models, cross-package composition. |
| Folder attributes as extension bridge | Chat stores attributes it doesn't understand. llm-bridge contributes definitions. Zero coupling. |
| Action registry as tool registry (meta-tool) | Dynamic, zero-config AI tool-use. Installed extensions = AI capabilities. Uniquely Armature. |
| Layered prompt architecture (6 layers) | Admin safety not overridable. Clear separation: platform → space → character → context → tools → user. |
| Personas in llm-bridge, not chat | Chat sees AI as just another participant_type. Persona identity is llm-bridge's concern. |
| llm-bridge after notes + chat (v0.13.x) | Proves the composability hooks work without being designed for a specific consumer. |
| Custom public root first in v0.13.x | Unblocks registry, landing page, and armature.run. Small kernel change, high leverage. |
| Package registry as reference extension | Proves public surfaces work. Needs files module for .pkg storage. Self-referential: Armature's registry runs on Armature. |
| armature.run as dogfood gate | If armature.run can't run on Armature, the platform isn't ready. Issues feed into quality gate fixes. |
| Sidecar connect-inward | No K8s RBAC, no service mesh, no DNS discovery. Works on any deployment target. |
| Sidecar HTTP/JSON, not gRPC | KISS. 4-endpoint contract. Every language has HTTP. |
| User sidecars in v0.14.5 | Prove instance contract first, extend to users with same mechanism. |
| Three-layer user sidecar RBAC | Admin controls who + what, user controls visibility. Defense in depth. |
| Separate polish (v0.15.x) | Security-critical sidecar infra and quality-of-life polish shouldn't share focus. |