core/ROADMAP.md

Armature — Roadmap

Current: v0.9.x — Workflow Redesign

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

Design doc: docs/DESIGN-workflow-redesign.md

Three files contain near-identical Go↔Starlark converters; three copies of the snapshot parser exist. Consolidate into sandbox/convert.go and one exported snapshot function. Standardize on wrapped snapshot format.

v0.9.3 — Team User Roles

Promote the buried role system to a kernel primitive. New team_user_roles table (many-to-many). Manifest requires_roles field. Team admin UI for role assignment. Kernel middleware RequireRole(). Starlark SDK: teams.get_member_roles(), teams.has_role().

v0.9.4 — Package Adoption + Roles

scope: adoptable manifest field. When a team adopts an adoptable package, the package's requires_roles auto-populate into the team's role slots. Replaces AdoptTeamWorkflow clone mechanism.

v0.9.5 — Typed Forms → SDK Primitive

Extract TypedFormTemplate, FormField, FormFieldset, etc. from models/workflow.go into a forms package. FE SDK: sw.forms.render() and sw.forms.validate(). Starlark: forms.validate(). Any package can declare forms, not just workflow stages.

v0.9.6 — Deprecate stage_type, Collapse stage_mode

stage_type (simple/dynamic/automated) is redundant with starlark_hook presence. Remove from new manifests, keep parsing for backward compat. Collapse stage_mode from 4 to 3 values: form / delegated / automated.

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 — Reference Extensions

The kernel is complete. This series proves the platform by shipping first-party extensions that exercise every primitive. These are extensions, not kernel code — they ship as .pkg files and can be uninstalled.

v0.10.0 — vector-store Library

Document ingestion, chunk storage, embedding persistence, semantic similarity search. Consumes: db.write, files.read.

v0.10.1 — llm-bridge Library

Model abstraction, tool-use routing, provider BYOK via connections. Exposes complete(), embed(), classify(), register_tool(). Consumes: connections.read, api.http, db.write.

v0.10.2 — file-share Extension

File upload, storage via files module, download links, team/group ACLs via resource grants.

v0.10.3 — code-workspace Extension

Managed code repos via workspace module. Git operations, file browser surface, structural indexing. Consumes: workspace.manage, files.write.

v0.10.4 — image-gen + image-edit Extensions

Image generation/editing via external APIs. Composability demo: contributes to chat:image-actions slot.

v0.10.5 — Chat System

Generic 1-to-N messaging with slots. chat-core library + chat surface. Declares chat:message-actions, chat:image-actions, chat:composer-tools slots. Consumes: db.write, realtime.publish, files.write.

---

v0.11.x — Sidecar Tier + Polish

v0.11.0 — Sidecar Tier

Out-of-process extensions for workloads that can't run in Starlark (ML inference, media transcoding, language servers, local git). Sidecars are independent processes that connect inward to the kernel, following the cluster registry pattern. Authentication via mTLS or registration tokens.

v0.11.1 — Native Dialog Audit

Replace prompt()/confirm()/alert() with sw.dialog SDK primitives.

v0.11.2 — Stability + Migration Tooling

Versioned migrations, armature migrate CLI, backup/restore validation, pre-1.0 schema freeze.

---

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
• At least 3 reference extensions shipped (vector-store, llm-bridge, chat)
• At least 1 cross-extension composability demo (image-gen → chat:image-actions)
• Headless E2E green on PG + SQLite
• armature-ca.sh + mTLS deployment guide
• Single-binary + Docker + K8s deployment paths documented

---

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.11.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.