docs(plan): ROADMAP.md - M16 release self-determination, M17 ms-tools skill, M18 seat-role restriction, M19 auth tooling; CI deferred per owner

docs/plans/ROADMAP.md

@@ -0,0 +1,116 @@
+# 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 (central tooling documentation)
+
+Problem: tooling knowledge lives in docs/TOOLS.md + README + this file's
+history — agents must be told where to look every session.
+
+Design:
+- A pi skill: `skills/ms-tools/SKILL.md` (frontmatter: name, description;
+  body: the tool surface — scripts, exit codes, safety notes, pointers into
+  docs/TOOLS.md for depth). Skills load on demand, so the always-in-context
+  cost stays in AGENTS.md (one pointer line).
+- AGENTS.md gains: "tooling reference: invoke the ms-tools skill."
+- Workers deliberately run `--no-skills` — the skill serves conductor-level
+  and vanilla sessions, same boundary as AGENTS.md.
+- docs/TOOLS.md remains the source of truth; the skill references it rather
+  than duplicating content.
+
+## 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.
+
+## 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.