ROADMAP — agreed path forward

Status: planning aligned with owner 2026-09-03. Feature work follows this order unless the owner re-orders. Design notes below are commitments about intent, not implementation — each milestone still gets its own issue, tests, and BUILD-LOG phase.

Standing decisions (owner, 2026-09-03)

Pi is the main TUI harness and the reference checkpoint. Multi-harness (Codex, Claude, OpenCode) comes after pi is stable as the primary seat.
CI is deferred. Gitea runs on slow hardware; local suites + verify are the quality gate. Revisit when code volume justifies runners.
The user never manually runs release.sh. The system determines what is installed and self-aligns (M16).
Tooling documentation is agent-accessible via the ms-tools skill (M17), referenced from AGENTS.md.
Capability restriction becomes progressive and role-based (M18), porting prior Mosaic Stack concepts where they fit the file-based runtime.

M16 — Release self-determination

Problem: after reset.sh the activation pointer is gone and the owner had to know about scripts/release.sh activate. The system must determine what is actually installed.

Design:

New release.sh ensure (also invoked automatically by the launchers via common.sh): compares desired (RELEASE) vs packaged image vs active pointer.
Fast path (drift = pointer missing/mismatched, image already packaged): restore the pointer without a health gate — the release was previously health-gated; reset is data loss, not a new release.
Slow path (new version in RELEASE, or image missing): package beside → full health gate (exact-marker model run) → atomic pointer swap. This is the M3 gate-then-flip, now automatic.
Acceptance: post-reset.sh, the next hello.sh/agent.sh self-restores activation with zero manual release commands; a bumped RELEASE auto- activates after its health gate; a failing health gate leaves the previous release active and records the refusal.

M17 — ms-tools skill + role-scoped skill lifecycle (DESIGN REVISED per owner)

Problem: agents without supplied tooling invent their own, even when a functional method exists. Skills must reach non-conductor seats as role-scoped subsets, with an explicit lifecycle.

Design (owner-specified):

Two machine-scoped directories under the data root:
- <dataRoot>/skills-enabled/ — loadable by agents
- <dataRoot>/skills-available/ — installed but disabled
Lifecycle: install → available · activate → enabled · deactivate → back to available · uninstall → removed. A skill not in skills-enabled is not enabled or available for use.
Launch resolution: role contracts declare skill NAMES; the runner resolves each against skills-enabled and passes --skill <path> explicitly. --skill necessarily negates --no-skills (explicit provision wins). Contracted-but-not-enabled → refuse the launch loudly (a silently under-equipped seat is the exact failure mode this prevents).
Containerization removes ambiguity: agents get only what is explicitly provided; no discovery, no ambient skill leakage.
Interfaces: CLI first (mosaic skill install|activate|deactivate|uninstall|list), TUI and WebUI frontends call the same tooling later.
The ms-tools skill is the first shipped skill (tooling reference for conductor/vanilla sessions); role contracts then grant subsets per seat.

M18 — Seat-role progressive capability restriction

Problem: capability restriction exists but is per-task/per-mission only. Seats (agent identities) need governing ceilings that tasks cannot escalate past — the M9 intersection chain extended: role ceiling ∩ mission grant ∩ task grant = effective.

Design:

roles/<role>.json (role contracts, tracked): roleVersion, name, tools ceiling (subset of pi built-ins), network: "none"|"api-only"| "open" (declared now, enforced when network policy lands), paths (future).
Resolution chain in the runner: seat role contract ∩ mission capabilities ∩ task capabilities → effective tools (existing intersection logic, one more link). Empty at any stage = tool-free run, loudly recorded.
agent.json keeps role (already shipped in M15) — it now binds to roles/<role>.json.
Porting note: prior Mosaic Stack role/policy concepts inform this design, but implementation is fresh on the file-based runtime (the standing repository exclusion applies until the owner points at specific prior files to port).
Adapters unchanged: MOSAIC_TOOLS already carries the effective set.

M19 — Harness auth tooling (pi checkpoint)

Problem: auth is manual (/login, auth.json); multi-account and multi-harness stacking have no tooling.

Current facts (observed): one auth.json holds multiple providers (anthropic, openai-codex, zai observed on the host) — provider stacking already works. Multiple accounts per provider is the open question (the owner runs two Claude accounts; openai-codex multi-account desired).

Design direction (pi-first checkpoint):

scripts/auth.sh status — per-provider auth report (which providers have credentials, source: auth.json vs env), no secrets printed.
Multi-account: investigate pi's auth schema for per-provider account entries; if unsupported natively, model accounts as named auth files (auth.<account>.json) with a conductor-level selector — runtime-injected per launch, same pattern as the read-only credential mount.
Claude/Codex/OpenCode adapters stay parked; the auth tooling is harness-neutral so it serves them when they arrive.

M20+ — Unified `mosaic` CLI and the stack succession path

Direction (owner): a unified mosaic CLI (mosaic --check, mosaic tui, mosaic yolo <harness>, mosaic skill ..., mosaic release ensure, ...). Much larger task; channel-dispatcher doctrine harvested from fleet/bin/mosaic (HARVEST.md #1).

Succession trajectory (owner): the v2 line is actively building the REPLACEMENT for the mosaicstack/stack repo. At the appropriate level of usurpation, v2 content becomes THE next-branch content on mosaicstack/stack — a full refactor-and-replace with a functional system. Not ready yet.

DECIDED (owner, 2026-09-03): v2 reorganizes to the packages/* monorepo structure for continuity with the existing stack tooling and expectations. Reference: harvest worktree ~/src/mosaic-stack-worktrees/v2-harvest (branch next @ 0db2d19a) and packages/mosaic (CLI), packages/auth. Usurpation criteria to be defined before any replacement (proposed: functional parity of P0 operations on the v2 runtime + owner sign-off).

Restructure sequencing (decided 2026-09-03, owner question)

The monorepo restructure is NOT done first. Reason: the bash entry points' final home is replacement by packages/mosaic commands, not containment - moving them into packages/ now, then replacing them at M20, migrates everything twice and churns the suites (the safety net) during peak feature work. Instead:

Layout doctrine frozen now (this file + AGENTS.md): nothing new lands at root; features build in their durable homes (skills/, roles/, docs/, adapters/, src/).
M20 phase 1 = restructure: packages/ monorepo skeleton absorbs the script entry points as CLI commands (packages/mosaic), with packages/agent, packages/auth following the harvested anatomy. The bash scripts retire as they are absorbed.
Succession: at usurpation, v2 content (already in packages/* shape) becomes the next-branch content of mosaicstack/stack.

Target tree (post-M20-phase-1)

/                        bootstrap + entry docs (unchanged)
+-- packages/
|   +-- mosaic/          the CLI: tui, yolo, skill, release, onboard, check
|   +-- agent/           seat/session runtime (absorbs src/ + adapters/)
|   +-- auth/            provider slots, account ensure (absorbs M19)
|   +-- config/          schema + policy validation (absorbs config tooling)
+-- contracts/ roles/ missions/ tasks/ templates/   declarative inputs
+-- skills/              shipped skills (installed to dataRoot on activate)
+-- docs/                plans, harvest, SESSIONS, TOOLS
+-- src/                 container runtime (loader, dispatcher)

Skills as discipline encoding (owner insight, 2026-09-03)

Skills are not tool menus - they encode operational discipline: order of operations, gotchas, and failure history. The tool-race lesson and every catalogued defect become skill content per role (e.g. a conductor skill carries: sequential dependent calls; verify writes before claiming; symlink-ensure before TUI; path pre-checks before pi flags). Role contracts (M17) declare which skill subsets each seat receives.

Explicitly deferred

CI runners (owner: Gitea hardware is slow; local suites are the gate) — revisit as code volume grows.
Network egress policy enforcement (declared in role contracts at M18; enforcement is its own milestone).
Push automation (push stays an explicit act).
Second real adapter; fleet/multi-agent; knowledge storage; portal.

Completed reference (see docs/plans/CURRENT.md log)

M1 config-driven hello · M2 missions/tasks · M3 release model · M4 adapter seam · M5 workspaces/capabilities · M6 sessions · M7 ergonomics · M8 conductor loop · M9 mission capability policy · M10 retention · M11 session forking · M12 auto-apply policy · M13 interactive TUI agent · M14 live user context · M15 agent seats + roles/ convention.

9.4 KiB Raw Blame History