From 58b96cb71542099a6680a4ff874ccc616c79d0ed Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Thu, 3 Sep 2026 12:57:26 -0500 Subject: [PATCH] docs(plan): ROADMAP.md - M16 release self-determination, M17 ms-tools skill, M18 seat-role restriction, M19 auth tooling; CI deferred per owner --- AGENTS.md | 1 + docs/plans/ROADMAP.md | 116 ++++++++++++++++++++++++++++++++++++++++ skills/ms-user/SKILL.md | 8 +++ 3 files changed, 125 insertions(+) create mode 100644 docs/plans/ROADMAP.md create mode 100644 skills/ms-user/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 6f9f17db..660ec222 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,6 +91,7 @@ Full reference — usage, fields, exit codes, safety notes: ## Pointers (depth lives here) - `docs/plans/CURRENT.md` — THE next action (single source of "what now") +- `docs/plans/ROADMAP.md` — agreed milestone path (M16+) - `docs/plans/CONDUCTOR.md` — orchestration protocol and guardrails - `docs/plans/2026-09-02_atomic-mosaic-foundation.md` — architecture, invariants - `docs/plans/2026-09-03_autonomous-run.md` — batch-run tracker diff --git a/docs/plans/ROADMAP.md b/docs/plans/ROADMAP.md new file mode 100644 index 00000000..4fc08697 --- /dev/null +++ b/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/.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/.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..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. diff --git a/skills/ms-user/SKILL.md b/skills/ms-user/SKILL.md new file mode 100644 index 00000000..f767b676 --- /dev/null +++ b/skills/ms-user/SKILL.md @@ -0,0 +1,8 @@ +--- +name: ms-user +description: Always use to update recorded information about the user +disable-model-invocation: false +--- + +# User +Info about the tooling and usage should be listed here. \ No newline at end of file