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

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 — 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 — Reference Extensions (Remaining)

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.

Version	Title
v0.12.0	vector-store Library
v0.12.1	llm-bridge Library
v0.12.2	file-share Extension
v0.12.3	code-workspace Extension
v0.12.4	image-gen + image-edit Extensions
v0.12.5	Chat System

---

v0.13.x — Sidecar Tier + Polish

Version	Title
v0.13.0	Sidecar Tier
v0.13.1	Native Dialog Audit
v0.13.2	Stability + Migration Tooling

---

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
• Notes reference extension shipped with all v0.11.x features
• Notes UI/UX reviewed against v0.11.0 design principles — no placeholder UI
• At least 1 panel shipped and consumed cross-package (notes.reference → chat)
• Panel lifecycle test coverage in SDK test runner

---

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.13.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 v0.11.0	Every feature version 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 remaining reference extensions	Notes proves the full primitive surface. Other extensions build on proven patterns.