docs(roadmap): M17 skill lifecycle (skills-enabled/available, role-scoped subsets, --skill negates --no-skills); M20 stack succession path + monorepo question

docs/plans/ROADMAP.md

@@ -39,21 +39,30 @@ Design:
   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)
+## M17 — ms-tools skill + role-scoped skill lifecycle (DESIGN REVISED per owner)
 
-Problem: tooling knowledge lives in docs/TOOLS.md + README + this file's
-history — agents must be told where to look every session.
+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:
-- 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.
+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
 
@@ -98,7 +107,26 @@ Design direction (pi-first checkpoint):
 - Claude/Codex/OpenCode adapters stay parked; the auth tooling is
   harness-neutral so it serves them when they arrive.
 
-## Explicitly deferred
+## 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.
+
+Open decision at usurpation time: whether v2 reorganizes to the stack
+monorepo layout (`packages/*` — continuity with existing tooling) or keeps
+its flat structure and defines the new convention (clean break). Reference
+for either: 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).
 
 - CI runners (owner: Gitea hardware is slow; local suites are the gate) —
   revisit as code volume grows.