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

Add workflow.start(), workflow.advance(), workflow.cancel(), workflow.submit_signoff() to the Starlark module. Extract engine interface to break circular import.

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

Core libraries and remaining extensions. llm-bridge is the key 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.

Version	Title
v0.13.0	vector-store Library
v0.13.1	llm-bridge Core Library
v0.13.2	llm-bridge → Chat: Multi-Persona Context + Tool Meta-Tool
v0.13.3	llm-bridge → Notes: AI Toolbar Actions
v0.13.4	file-share Extension
v0.13.5	code-workspace Extension
v0.13.6	image-gen + image-edit Extensions
v0.13.7	Tool Meta-Tool Hardening + Scoping
v0.13.8	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.
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.