From 507139e34c4fb893549fbf86747b6e7e4a502522 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Tue, 14 Jul 2026 15:55:37 -0500 Subject: [PATCH] comms: transmit frozen control-plane planning artifact --- ...ntrol-plane-north-star__sha256-15e391ca.md | 582 ++++++++++++++++++ 1 file changed, 582 insertions(+) create mode 100644 comms/artifacts/20260714T205600Z__from-homelab__mosaic-web-control-plane-north-star__sha256-15e391ca.md diff --git a/comms/artifacts/20260714T205600Z__from-homelab__mosaic-web-control-plane-north-star__sha256-15e391ca.md b/comms/artifacts/20260714T205600Z__from-homelab__mosaic-web-control-plane-north-star__sha256-15e391ca.md new file mode 100644 index 0000000..3bb8a38 --- /dev/null +++ b/comms/artifacts/20260714T205600Z__from-homelab__mosaic-web-control-plane-north-star__sha256-15e391ca.md @@ -0,0 +1,582 @@ +# Mosaic Web Control Plane North Star — Oppositional Planning + +Status: FROZEN PLANNING CANDIDATE — independent reconciliation pending; no implementation authority +Owner: Homelab Mos with USC coordination + +## Durable user direction (2026-07-14) + +Mosaic Stack needs a usable, coherent web control plane spanning: + +- Kanban, projects, project creation, agents, personas, assignments, settings, configuration. +- Authentication, SSO, federation, session timeout, legal pages, footer information. +- Responsive design, multiple themes, and consistent mosaicstack.dev-derived branding. +- Oversight visibility into every fleet service, agent, and session. +- Event tracking as a mandatory platform capability. +- Secure web terminal/session management inspired by cmux interaction patterns. +- Protection against terminal/tmux session hijacking; explicit authorization and isolation. +- tmux and eventual Matrix communication boundaries, WAL/audit logging, recovery, and resumable sessions. +- PostgreSQL-backed source of truth for tasks, projects, and orchestration. + +## Constraints + +1. Reconcile rather than duplicate existing canonical work, especially #752/#753 Native Kanban/SOT, #756 channel/Discord, #757 logical identity/fencing, #758 fleet configuration, `docs/fleet`, `docs/PRD.md`, and `docs/TASKS.md`. +2. PostgreSQL is the sole writable project/task/orchestration source of truth. Files may be generated views, exports, plans, evidence, or break-glass proposals—not a second writer. +3. Planning pair is non-authoring. No repository edits or implementation branches until a canonical requirements/tracking PR is independently reviewed and merged. +4. Distinguish product inspiration from implementation dependencies. Assess cmux and Ghostty, but do not assume a desktop terminal is a server/web backend. +5. Preserve one authority per surface and collision holds across USC and homelab fleets. +6. Required delivery model: dependency-ordered cards, one card/branch/PR, independent review/security/certification, terminal-green CI, durable progress evidence, resumable agent sessions. + +## Planner Sol — Product/control-plane thesis + +### Product position: one place to understand, decide, and intervene + +Mosaic should present one **workspace control plane**, not a collection of feature dashboards. A user +should be able to move from objective → project → mission → task → assignment → live agent session → +evidence/review → outcome without changing vocabulary, losing context, or guessing which store is +current. The browser is a Gateway client and a projection of authoritative state; it is not a new +orchestrator, terminal daemon, configuration store, or fallback writer. + +The largest product risk is now fragmentation, not missing primitives. Native Kanban (#752/#753), +logical identity/fencing (#754/#755/#757), Discord (#756), local fleet configuration (#758), Tess +(#706–#709), federation, and the older Fleet documents each solve a real seam, but independently +shipping them would produce overlapping agent lists, multiple meanings of “session” and “lease,” +separate activity feeds, and settings pages that imply authority they do not possess. A feature is not +product-complete because its API and page exist. It is complete when it advances a coherent end-to-end +journey through the same navigation, identity model, event language, and source-of-truth rules. + +**North Star:** from one responsive, accessible, branded workspace, an authorized operator can see +what Mosaic is trying to achieve, what work is ready or blocked, which logical agents and runtime +sessions are involved, what needs attention, why the system made a decision, and which safe action is +available next. Most oversight should take seconds and require no terminal. Powerful intervention is +progressively disclosed and separately authorized. + +### Users and primary journeys + +Human product roles and agent execution roles must not be conflated. `admin`, `member`, `viewer`, +workspace membership, SSO session, project accountability, specialist role, and merge authority are +separate concepts. + +| User | Primary question | Required journey | +| --- | --- | --- | +| **Workspace owner/admin** | Is the instance safe, connected, and correctly configured? | Sign in through Authentik; choose workspace; review health, members, policies, federation, channels, recovery posture, legal/build information, and privileged-change history. | +| **Portfolio operator/orchestrator** | What needs a decision across all projects? | Open the attention queue; inspect blocked/at-risk work, capacity, budget, stale sessions, pending approvals, and cross-project impact; approve, reject, re-plan, or delegate through typed commands. | +| **Project lead/sub-orchestrator** | Will this project reach its next outcome? | Create/select a project; define milestone and mission; inspect dependency/readiness explanations; release bounded tasks; follow delivery through review and certification. | +| **Contributor/specialist** | What am I assigned and what proves completion? | Open “My work”; see acceptance criteria, dependencies, exact assignment and active task lease; enter the associated session; submit artifacts/checkpoints; hand off for review. | +| **Reviewer/SecReview/Certifier** | Is the evidence sufficient and independent? | Consume a focused evidence bundle, author identity, changes, tests, security triggers, prior findings, and event history; record pass/reject/escalate without gaining merge authority. | +| **Observer/auditor** | What happened, who caused it, and what is current? | Browse read-only projects, task timelines, authority changes, denials, recovery evidence, and correlated events without terminal access or hidden operational jargon. | +| **Interaction user** | Can I ask Mosaic and continue in the right context? | Converse through web/Discord/CLI with a stable logical agent; see the bound workspace/project/thread and transition into the same task/session detail without creating a second orchestration path. | + +The daily “morning view” is the product test: within 30 seconds an operator should know **what changed, +what is unhealthy, what is blocked, and what needs a human decision**. The delivery test is equally +important: from a task card, two clicks should reveal its accountable owner, specialist assignment, +current runtime session/lease, evidence, review gates, and causal event history without representing any +of those concepts as interchangeable. + +### Information architecture + +Use stable nouns and one global workspace/project context. Avoid top-level pages named after internal +packages, personas, or transports. + +1. **Home / Command Center** — outcomes, attention queue, active work, at-risk projects, unhealthy or + stale agents/sessions, pending approvals, budget horizon, and recent significant events. This is a + composed read model, never a new source of truth. +2. **Work** + - **Projects** — project creation, overview, milestones, missions, repositories, accountable owner. + - **Board** — Kanban/List over the canonical seven task states; saved filters by project, mission, + milestone, owner/specialist, tag, due state, readiness, and archive state. + - **Task detail** — acceptance, dependencies/readiness, accountable owner, assignment, task lease, + session, artifacts, reviews/certification, links, and timeline as distinct panels. + - **Missions** — objective, approval state, milestones, DAG/progress, decisions, and generated + document links. A full visual mission designer remains later scope. +3. **Fleet** + - **Agents** — stable logical identity, alias/persona, class/capabilities, desired local definition, + runtime/provider/model, current health, and assigned work. + - **Sessions** — host, harness, context/capacity, heartbeat, channel bindings, task association, + checkpoints, and explicit `Watch`, `Message`, `Interrupt`, `Stop`, or later break-glass actions. + - **Assignments & capacity** — pending approvals, specialist assignments, KBN task leases, and + team-leader capacity allocations with their actual typed labels. + - **Configuration** — initially read-only provenance and drift. Local roster mutation is not a web + feature until #758 completes and a separate gateway/UI convergence threat model is approved. +4. **Activity** — workspace event inbox plus entity timelines. Default views are `Needs attention`, + `Changes`, `Delivery`, `Security`, and `System`; raw telemetry is an advanced diagnostic view. +5. **Communications** — logical agent bindings and channel/thread health across web, Discord, CLI and + eventually Matrix. This configures transport bindings; it does not create agent or task authority. +6. **Administration** — members/teams/roles, Authentik/SSO and sessions, federation peers/grants, + policies/approvals, providers/budgets, recovery evidence, audit export, and retention. +7. **Personal settings** — profile, accessibility, notification preferences, timezone, density, and + theme. Public login/legal/privacy/terms/status pages and a consistent footer show instance name, + environment, version/revision, documentation/support links, and legal links without exposing secrets. + +Desktop and mobile use the same hierarchy. On narrow screens the Board has a list alternative and +single-column card detail; all drag operations have keyboard/menu equivalents; live changes use +semantic announcements rather than color alone. Mosaic design tokens and mosaicstack.dev branding +supply the common shell, with dark, light, and high-contrast themes. Persona branding may change the +friendly alias/avatar, never navigation or authorization semantics. + +### Cohesive control-plane boundaries and authority domains + +The web app calls typed Gateway query/command APIs. It never reaches PostgreSQL, Valkey, tmux sockets, +systemd, provider CLIs, or channel SDKs directly. Gateway composes read models, authorizes commands, +and delegates effects to the owning adapter. WebSocket/SSE streams accelerate display; reconnect always +backfills from an authoritative cursor/revision. + +PostgreSQL is the **only writable project/task/orchestration SOT**. Projects, missions, milestones, +tasks, assignment proposals/decisions, KBN execution leases/fences, checkpoints, artifacts/evidence, +semantic events, receipts, and outbox state follow the ratified Native Kanban contract. The Mechanical +Coordinator is deterministic and non-LLM: it explains eligibility and applies approved policy but does +not invent scope, waive gates, certify, merge, or become a second portfolio orchestrator. Markdown, +`mission.json`, issue trackers, browser state, Valkey, channel messages, and outage notes are projections, +external links, transport, or inert proposals—not writers. + +“Lease” must never become a universal abstraction. The UI can correlate these authorities while keeping +them typed and independently revocable: + +| Domain | Authority and product label | Explicit non-authority | +| --- | --- | --- | +| **Authentication** | BetterAuth/SSO **user session** establishes an actor; workspace membership and command policy authorize each action. | Login does not grant task, connector, fleet, federation, or terminal authority. | +| **Native Kanban** | KBN **assignment** records responsibility; KBN **task execution lease + fence** authorizes one specialist session to act on one task. | It does not authorize connector ownership, local fleet mutation, or merge. | +| **Local Fleet (#758)** | Roster is local desired-state SSOT; enabled/desired/observed state and class contracts govern local tmux/systemd projections; a team-leader **capacity lease** bounds delegated capacity. | It does not assign canonical tasks, authenticate users, or converge the Gateway agent catalog during M1–M5. | +| **Connector execution (#754/#755/#757)** | Exclusive **connector lease/epoch** and short-lived execution grant bind logical agent, channel binding, harness holder, scope and effect. | It does not imply task ownership, user login, or general terminal authority. | +| **Federation** | A peer certificate plus scoped/revocable **federation grant** authorizes a gateway-to-gateway read/query capability. | It is not an auth session, cross-instance writer, session-control grant, or cached authority. | +| **Merge/release** | Project Sub-Orchestrator/merge-gate acts only after required independent review, SecReview and Certifier evidence. | Certifier, Coordinator, task lease holder, and connector holder cannot merge. | + +#757 is therefore the M1 implementation of #755; after #757 merges and terminal validation passes, +#755 may close while #754 remains the parent for checkpoint, receipt, adapters and failover work. Later +work must extend those typed domains, not mint a “Mosaic lease” accepted everywhere. + +Local Fleet and Gateway catalog data should meet first through a **correlated read model**: logical agent +ID, local roster identity/provenance, runtime session, host and observed health are joined for display, +with “unknown/unmanaged/stale” shown honestly. Any future web mutation of local roster/systemd/tmux is a +new policy boundary after #758, not a silent extension of project-task CRUD. + +### Fleet/session and event experience + +An agent row answers: who is this logical agent, what role/persona/capabilities are intended, where is it +running, what task is it assigned, is it actually responsive, which channel is bound, and what action is +safe? Health is layered: desired state, process/pane, heartbeat, connector, assignment/task lease, and +provider health. A single green dot is prohibited because it hides partial failure. `Watch` remains the +default observation path; interactive takeover is not the default session page. + +A session detail page combines: + +- stable logical agent and ephemeral runtime/harness identifiers; +- workspace/project/task context and exact typed authority currently held; +- host, runtime/model, start/heartbeat/context/capacity and checkpoint state; +- redacted live output or structured progress, with reconnect/resume status; +- connected web/Discord/CLI/Matrix bindings and last delivery receipt; +- evidence, errors, policy denials and recovery options; +- typed actions with clear effect and scope. A message to an agent is not raw `tmux send-keys`; a stop is + not an ambiguous “terminate everything”; an expired grant visibly disables its control. + +Event tracking is a product capability, not a raw log viewer. Authoritative business events append in the +same PostgreSQL transaction as state and outbox. The Activity UI renders actor, time, workspace, entity, +plain-language change, old/new revision, cause/correlation, decision/evidence and outcome. Causal chains +connect “task released” → “assignment approved” → “lease acquired” → “checkpoint” → “review” without +forcing users to grep trace IDs. Denials, optimistic conflicts, transport uncertainty, retries and +quarantine have different language and next actions. + +Keep three data classes visibly separate: + +1. **Semantic audit/business events** — durable PostgreSQL truth; complete and attributable. +2. **Delivery events/receipts** — durable ingress/outbox/effect state and ambiguity reconciliation. +3. **Operational telemetry** — OTEL traces/metrics/logs for diagnosis; correlated but lossy and never + authority. SigNoz remains the deep diagnostic surface rather than being rebuilt inside the product. + +The event inbox supports per-user read/ack state without altering canonical events, saved filters, +retention labels, privacy-aware redaction, and “copy correlation ID.” Reconnect resumes from the last +seen event cursor. Notification policy summarizes routine success and elevates only human decisions, +failures, security changes, expiring authority, and recovery risk; otherwise event volume will make the +control plane unusable. + +### cmux and Ghostty verdict + +Research as of this plan supports **inspiration, not adoption**: + +- **cmux** is a GPL, native macOS Swift/AppKit terminal built on libghostty. Useful ideas are its + workspace/sidebar model, attention rings and unified notification queue, visible branch/PR/working + directory metadata, splits, command palette, and “jump to the agent needing me” flow. Its local socket + automation, desktop trust boundary, browser pane and direct terminal control are not a server-side web + control plane and should not become Gateway dependencies. +- **Ghostty** is a native terminal emulator; `libghostty` is a C/Zig embeddable terminal core, with + `libghostty-vt` usable from WebAssembly but API signatures still in flux. It supplies terminal parsing + and rendering primitives, not identity, PTY brokering, authorization, audit, resumability, or browser + session security. A later renderer spike may compare it with established web terminal components, but + neither Ghostty nor cmux belongs on the first 90-day dependency path. + +Adopt the interaction lessons—attention, spatial context, fast switching, keyboard control—while the +Gateway exposes typed observation and actions. Do not clone a desktop terminal in the browser and call it +a control plane. + +### Progressive 30/60/90-day outcomes + +The clock starts after the reconciled requirements/tracking PR is independently reviewed and merged. +Outcomes are dependency-gated; if a write/control prerequisite is not green, the product remains +truthfully read-only instead of shipping mock or alternate writes. + +| Horizon | Shippable outcome | Measurable evidence | +| --- | --- | --- | +| **30 days — one product contract** | Ratify one control-plane IA, event taxonomy, authority glossary, responsive design shell and issue/DAG map. Complete #753 and freeze KBN schema/API prerequisites before consumer work. Establish authenticated workspace shell, legal/footer/theme/accessibility patterns, and contract-backed read-only prototypes for Command Center, Work and Fleet. | Every visible datum names its authority/provenance; all duplicate docs/issues have disposition; five critical journeys pass prototype review; keyboard/mobile/contrast checks pass; no web, file, Valkey or channel writer exists. | +| **60 days — useful vertical slice** | Land KBN P1’s real Project/List/Kanban/task-detail journey through Gateway, including dependencies/readiness, ownership-versus-assignment-versus-lease, conflicts and audit timeline. Add read-only agent/session inventory and Activity inbox from durable cursors. Complete Authentik/session basics (#44) and session sandbox/tool-policy foundation (#64) before any control. | Create/move/archive/refresh shows one aggregate revision across web/CLI/MCP/projection; reconnect catches up without gaps; cross-workspace and stale-write journeys deny correctly; daily oversight answer is under 30 seconds; no duplicate task API/store/page. | +| **90 days — coordinated operations, not a shell** | If KBN P2 gates pass, add assignment approval, deterministic readiness explanation, retry/quarantine and evidence/review flow. Add safe typed session watch/message/interrupt/stop only where #757 identity/fencing and #64 policy evidence pass. Integrate #756 channel/thread visibility through the same logical-agent page; expose #758 configuration provenance/drift read-only. Federation administration may enter only behind its own grant/revocation DAG. | One task can traverse release → assignment → session → checkpoint → independent review/certification → merge evidence from one UI; stale holders lose actions; channel continuation preserves logical identity; zero raw tmux/systemd/DB access from web; WCAG keyboard and responsive journeys, fault/reconnect tests, independent product/security review, and terminal-green CI pass. | + +### Canonical documentation disposition + +There can be many scoped PRDs, but only one authority at each level. The future canonical control-plane +requirements/tracking PR should link rather than restate frozen contracts. + +| Artifact | Disposition | +| --- | --- | +| `docs/PRD.md` | **Keep** as umbrella Mosaic product requirements; amend by linking the reconciled web-control-plane workstream and Native Kanban canon, not copying either. | +| `docs/TASKS.md` | **Keep** as temporary orchestrator rollup; after KBN cutover it becomes a generated read-only projection. Correct stale M0/status notes through its owning orchestrator only. | +| `docs/requirements/native-kanban-sot.md`, `docs/native-kanban-sot/{INDEX.md,MISSION-MANIFEST.md,TASKS.md,SHARED-CONTRACT.md,contracts/*}` | **Keep authoritative** for project/task/orchestration P0–P3. Web work consumes KBN-105 contracts and does not redefine them. | +| `docs/fleet/NORTH_STAR.yaml` | **Keep authoritative only for the autonomous Fleet goal/backlog projection domain** until PG cutover. It is not the global web-product PRD and eventually becomes a generated/exported input under the PG-only SOT rule rather than a writable planning peer. | +| `docs/fleet/NORTH_STAR.md` | **Keep as deterministic generated projection** of `NORTH_STAR.yaml`; never hand-edit and never cite as an independent authority. | +| `docs/fleet/north-star.md` | **Supersede as a competing “North Star.”** Split durable fleet architecture decisions into scoped ADR/concept docs, mark historical phase statements, and point product/PG/KBN authority to the canonical requirements. It remains reference during extraction, not a second plan. | +| `docs/fleet/PRD-fleet-suite.md` | **Merge durable operator journeys into #758 and the control-plane workstream; then archive/supersede.** It is useful history but its Discord IDs, old phases, web hook assumptions and launch posture must not direct new implementation. | +| `docs/fleet/PRD.md` and `docs/fleet/TASKS.md` | **Archive as completed/stale Phase-2 observability evidence after extracting valid watch/attach/heartbeat contracts.** They cannot remain an active parallel roadmap. | +| `docs/fleet/FLEET-LAUNCH.md` | **Keep as current operator runbook, then revise under #758.** Its PATH-B arbitrary command/channel direction is superseded by #758’s generated-env quarantine and M1–M5 exclusions. | +| `docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md` and `LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` | **Keep as #758 acceptance evidence** until M5 closes; link from the eventual Fleet docs entry point. | +| `docs/fleet/f4-matrix-connector.md` | **Keep as transport history/contract input; reconcile with #756.** Matrix is a peer channel adapter, not control-plane authority. | +| `docs/fleet/backlog-conventions.md` | **Deprecate for canonical planning writes** when KBN migrates the legacy fleet backlog; retain only as migration/N-1 evidence. | +| `docs/scratchpads/north-star-doctrine.md` | **Archive as provenance** after its decisions are mapped to canonical requirements/ADRs; never cite the scratchpad as implementation authority. | +| This oppositional planning file | **Planning input only.** After reconciliation, convert approved decisions into one canonical requirements/tracking PR and freeze this artifact by hash for independent USC review. | + +This explicitly leaves only one active “North Star” per scope: umbrella product requirements, +Native Kanban’s frozen PG control-plane contract, and the scoped Fleet machine-readable projection +until it is migrated. Case-different filenames must not continue implying peer authority. + +### Issue disposition and dependency ownership + +These are proposed ownership/DAG boundaries, **not implementation reservations**. Canon owners and Mos +retain assignment authority; USC’s offered review is read-only and begins after the frozen artifact +hash/inventory. + +| Item | Disposition, owner, and DAG placement | +| --- | --- | +| **#752** | **Keep closed** as canon publication provenance. Its merged artifacts, not the PR discussion, are the implementation input. | +| **#753** | **Keep / hard prerequisite.** USC KBN security lane + independent SecReview; completes before KBN-100 and before writable control-plane scope expands. | +| **#754** | **Keep** as runtime-neutral identity/failover parent after #755; Gateway/runtime owners. Depends on typed connector authority and later checkpoints/receipts/adapters, not KBN task leases. | +| **#755 / #757** | **Reconcile:** #757 is the implementation PR for #755. Merge only through its independent gate; then close #755. Retain #754 for deferred failover. No universal lease or channel cutover. | +| **#756** | **Keep** as the one harness-neutral channel/plugin contract; channel owner after #757 foundation. Merge shared Discord work from #709 and Matrix history here; dynamic admin UI follows the contract, not in this slice. | +| **#758** | **Keep** under its M0–M5 DAG as local roster/config/lifecycle authority. FCM owner ships local compiler/reconcile/docs; no Gateway/UI store convergence or arbitrary commands/channels. A separately threat-modeled web binding can depend on M5. | +| **#44** | **Keep and move early** under auth owner; Authentik login/provisioning is a prerequisite to privileged admin/session surfaces, followed by explicit Mosaic authorization rather than IdP-group trust. | +| **#64** | **Keep and elevate** under agent-runtime/security owners; sandbox cwd, Mosaic prompt identity and tool policy are prerequisites to browser session control. | +| **#94** | **Supersede/merge into #756’s service-identity design.** Do not ship the proposed broad shared `PLUGIN_API_KEY` bypass; preserve the problem and tests, then close when scoped plugin authentication lands. | +| **#463** | **Keep/amend** in Federation M4. Federation search/audit/rate limits live under Admin/Federation; security-relevant audit cannot use silent drop-with-counter semantics and must remain distinct from lossy OTEL telemetry. | +| **#464** | **Keep** after #463. Cached/offline reads must display source age and never authorize mutations or session control. | +| **#465** | **Keep** after FED-M3, parallel with #464 as defined. Revocation/cert rotation is prerequisite to exposed federation administration. | +| **#466** | **Keep** after #463–#465; its peer/grant/audit UI is a section of Administration, not a standalone product shell. Independent security review remains mandatory. | +| **#482** | **Supersede/re-plan.** Its Portainer/Swarm deployment path is retired. Replace with pipeline-driven disposable two-gateway test infrastructure before federation E2E; no manual image/deploy path. | +| **#558** | **Keep/amend** as the PG-backed budget-policy/status workstream. The deterministic Coordinator consumes approved budget policy and explains defer/downgrade; budget state does not become a lease or hidden task-status rewrite. Surface in Command Center/Admin after canonical storage and policy freeze. | +| **#623** | **Defer post-MVP** as an opt-in privacy/consent-governed telemetry workstream. It cannot block local spend accounting and must not receive identifiable task/session/event content. | +| **#628** | **Keep but amend before implementation.** Reuse Forge’s pipeline logic, but its executor must dispatch through canonical Gateway/KBN assignment and task-lease commands; direct `agent-send.sh` cannot bypass PG SOT, policy, events or fencing. Sequence after KBN P2 contract alignment. | +| **#636** | **Supersede as written.** #758 absorbs safe roster-native runtime/model/lifecycle fields; arbitrary command/channel fields conflict with #758. Split any future web configuration binding into a post-M5, gateway-mediated, threat-modeled card. | +| **#706** | **Keep** as Tess/interaction epic, but present Tess as a configurable logical-agent persona inside shared Fleet/Communications pages, not a separate control plane. Reconcile stale milestone status. | +| **#707** | **Keep/reconcile evidence** as Tess security/runtime foundation; close completed subwork only against merged evidence. Its provider contracts feed shared session views. | +| **#708** | **Keep** for durable Pi state after #707; align checkpoints/inbox/outbox with #754 and KBN typed authorities without merging them. | +| **#709** | **Merge implementation dependency with #756** for Discord/CLI transport behavior, then retain only Tess-specific same-session E2E acceptance. Avoid a second Discord plugin. | + +**Dependency spine:** canonical docs/reconciliation → #753 → KBN-100 → KBN-105 → parallel KBN +Gateway/CLI/web P1 → P1 integration → deterministic KBN P2. In parallel, #44 and #64 establish human +and runtime safety; #757 completes #755 before #756 channel control; #758 proceeds on its isolated local +DAG. The web Command Center may consume approved read contracts early, but writable Work waits on KBN +and privileged Session actions wait on auth/runtime/connector evidence. Federation and FCM web mutation +remain later typed integrations rather than shortcuts around those spines. + +This sequencing deliberately challenges “feature-complete by issue count.” The release unit is a user +journey with one authority and complete evidence, not a bundle of independently green components. + +## Planner Terra — Security/recovery opposition + +### Thesis: the control plane is a privileged execution system, not merely a dashboard + +A coherent web UI is valuable, but a product-first shortcut that turns “view an agent” into a browser-accessible tmux shell would create the highest-risk surface in Mosaic: remote control of long-lived processes that possess repository, provider, channel, and sometimes operator credentials. The existing direction is promising but incomplete: #753 already holds Native Kanban schema work behind threat/authorization analysis; #754/#755 identify that current rebinding is replacement rather than identity-continuous failover; #758 correctly excludes remote/UI/connector mutation from its local-tmux control-plane scope. Those holds should remain. The release order is **identity and policy → durable state/evidence → narrowly mediated actions → rich web UX**, never the reverse. + +### Non-negotiable trust model + +| Boundary | Required rule | Shortcut to reject | +| --- | --- | --- | +| Browser, CLI, Discord, Matrix | Untrusted ingress; each request/socket is mapped by Gateway to an authenticated actor, active workspace membership, capability, target, and correlation ID. | A client-supplied tenant, agent, session, role, channel, or “admin” flag. | +| Gateway | Sole policy enforcement point for authz, action approval, lease/fence validation, redaction, audit and typed command dispatch. | Direct web/connector/runtime access to tmux, Postgres, Valkey, or a provider. | +| PostgreSQL | Sole writable SOT for projects, tasks, orchestration, leases, checkpoints, receipts, semantic audit and outbox; mutations require fresh transaction-local write proof. | Browser storage, `TASKS.md`, queue payloads, a Matrix room, tmux state, or an outage note as a second writer. | +| Runtime/terminal | An effect executor with no authority to extend its own scope. It acts only under a short-lived, server-minted, tenant/binding/epoch-scoped grant. | A durable tmux name, harness session ID, or channel binding treated as identity or authorization. | +| Valkey/Matrix/federation/egress | Derived transport infrastructure; loss is recoverable from PostgreSQL, and its events never authorize an action. | “Available” cache/transport health being treated as write permission. | + +`workspace_id` must be the hard tenant boundary from the first migration, with teams only authorization groups inside it. Enforce it redundantly: server-derived scope at every Gateway command, workspace-composite foreign keys/uniques for every relationship, no-existence-oracle denial behavior, and database role/RLS containment where feasible. The authorization decision must bind the *exact* logical agent, session, connector/binding, operation class, target, policy revision, expiry, and fence—not a broad user role checked once when a page loads. + +### Web terminal and tmux: oppose raw attachment + +The current fleet distinction is sound: `watch` is read-only and `attach` is an explicit interactive takeover. A web implementation must be **stricter**, not a websocket-to-PTY replica. + +1. Default web capability is inventory/status plus redacted read-only stream. Read access is workspace-scoped, attachment-scoped, revocable, short-lived, rate-limited, watermarked with actor/correlation, and must not leak scrollback, environment, alternate screen, clipboard/OSC sequences, prompts, tokens, or another user’s input. +2. No browser endpoint may expose a raw tmux socket, `send-keys`, arbitrary terminal bytes, host shell, filesystem mount, or long-lived attach token. Terminal escape/OSC injection, pasted control sequences, prompt injection, XSS/CSRF, session fixation, websocket origin confusion, and confused-deputy “resume this session” flows are first-class abuse cases. +3. “Control” is an explicit typed capability, not interactive shell ownership: `interrupt`, `send approved message`, `stop`, and narrowly declared recovery verbs each have a server-side policy, target/fence check, idempotency key, audit event and durable receipt. Shell/tool execution remains separately policy-bound and approval-gated. Destructive, credential-affecting, customer-visible, or cross-workspace operations require one-time, actor/tenant/action-digest-bound approval. +4. A temporary interactive break-glass path, if ever justified, needs reauthentication/MFA, an isolated single-use attachment grant (minutes, not a browser session), explicit owner/incident reason, rendered/recorded audit metadata, automatic revocation on lease/session/role change, and a tested kill switch. It is not MVP material. + +cmux and Ghostty may be useful interaction research, but neither should be assumed as a Mosaic dependency or security boundary. Desktop terminal integrations, local control sockets, plugins, clipboard integration, and terminal escape parsing belong to the local-user trust domain unless independently assessed. Mosaic should adopt only a capability-neutral, Gateway-mediated terminal contract; any cmux/Ghostty adapter must prove that it cannot bypass tenant scope, lease epoch, approval, redaction, audit, or revocation. + +### Authentication, SSO, sessions, and authorization + +“BetterAuth plus SSO buttons” is not session security. Before privileged web control is released, define and test: OIDC authorization-code + PKCE, issuer/discovery and audience validation, exact redirect allowlists, state/nonce binding, provider-claim-to-local-account mapping, JIT/provisioning policy, active-membership checks, and IdP/local deprovisioning behavior. Authentik/WorkOS/Keycloak are identity providers, not authorization sources; group claims may inform mappings but cannot silently grant a Mosaic workspace/admin capability. + +Use short idle and absolute session lifetimes for privileged surfaces, rotating/secure/httpOnly/same-site cookies, CSRF protection for cookie-authenticated mutations, origin-checked WebSocket handshakes, periodic socket reauthorization, and explicit revocation on logout, membership/role change, password/IdP session revocation, connector unlink, or risk escalation. Step-up authentication is required for terminal control, token/credential operations, tenant administration, break-glass, and policy changes. Every long-lived stream must be cut off when its authorization version changes; it may not survive merely because its original handshake succeeded. + +### Identity, leases, fencing, and exactly-once effects + +A stable agent display name and a harness/tmux ID are aliases, not principals. #755’s logical identity and PostgreSQL CAS lease/fencing model is the minimum foundation: server-derived `{workspace, logicalAgentId, bindingId, connectorId, harness, scopes, epoch, expiry}`; exclusive binding consumer; monotonic epoch; bounded TTL/heartbeat; explicit takeover/release; server-minted grants checked immediately before every connector/tool effect. A stale holder must be unable to reply, attach, send, checkpoint, approve, or execute after takeover—even if its process remains alive. + +A lease prevents concurrent authority; it does **not** create exactly-once delivery. Every ingress, tool call, outbound reply, Matrix transaction, tmux-compatible delivery, approval, and recovery operation needs a durable operation ID, immutable request/effect digest, state machine, and receipt. The transaction that changes canonical state must append its semantic event and outbox record. An acknowledgement lost after an external effect is *ambiguous*, not permission to retry: hold for authorized reconciliation with evidence. Current qualification records that tmux drops runtime idempotency keys and production coordination is in-memory; that blocks any claim of safe failover or web control continuity until corrected. + +### Audit, WAL, and recovery: evidence must survive the incident + +Audit is not a debug log. Mutations need append-only, attributable, workspace-scoped semantic events with actor/service identity, correlation and causation IDs, policy revision, target/version, action/effect digest, lease fence, and decision/denial outcome. Event, state, approval/evidence relation, and transactional outbox commit atomically; application roles are INSERT/SELECT-only for audit/evidence, normal flows archive rather than delete, and retention purge is separately authorized, audited break-glass. Do not record credentials, raw grants, tool payloads, terminal scrollback, prompt bodies, or sensitive approval material; redaction/classification occurs before persistence *and* before channel/browser egress. Security-critical audit may not be silently dropped for availability—non-authoritative telemetry may be separately buffered with visible loss counters. + +Recovery posture must be selected and mechanically verified, not claimed in a settings page. The already frozen contract is the floor: encrypted off-cluster backups in a separate failure domain; WAL/PITR only when their cadence supports the advertised RPO; restore tests and break-glass drills with retained evidence. High assurance means at least the stated 15-minute RPO/4-hour RTO, WAL at most every five minutes, 35-day PITR, monthly restore and quarterly break-glass drill. Test restore into an isolated environment, verify audit-chain/event/outbox/lease/checkpoint consistency, and prove a recovered system rejects stale grants/epochs. During a PostgreSQL write-health failure, mutation fails closed; operator notes return only as attributable, reviewable change proposals after recovery. + +Resume must reconstruct from PostgreSQL checkpoints, receipts, policy and current lease—not from browser state, a tmux pane, Valkey, or a raw transcript. Crashes before/after checkpoint, lease transfer, connector send, receipt persistence, acknowledgement, WAL archive, restore and policy revocation require fault-injection coverage. A host compromise, clock skew, expired/partitioned lease, duplicate outbox publish, Valkey loss, backup corruption, partial restore, IdP outage, and failed SSO/team deprovisioning are operational states with named safe behavior, alerts, owner runbooks and drills—not edge cases deferred to product polish. + +### Federation and Matrix: external identity and rooms are not authority + +Federation remains gateway-to-gateway, mTLS-authenticated and read-only; grants are tenant-scoped and intersect their subject’s native RBAC. Revocation/CRL/cert rotation must invalidate caches and in-flight authorization promptly, while an offline peer degrades to local reads only. It cannot carry session-control authority or create a cross-instance writable fallback. + +Matrix/Discord ingress must authenticate its service identity, bind a verified channel user/room/thread to one active Mosaic identity and workspace, authorize parent and child/thread context, deduplicate native event/transaction IDs durably, rate-limit, and emit correlation/audit evidence. Matrix room membership, appservice tokens, homeserver administration, and ghost identities are transport concerns—not proof of Mosaic authorization. Room/Space drift, replay, redaction failure, attachment malware/URL fetching, E2E key custody, server-admin visibility, retention divergence, and bridge reconnects all need explicit policy. Agents must not call Matrix directly; Gateway mediation is required. Do not promote Matrix from mocked parity to control-plane transport until production registration, identity/replay/tenant tests, fault injection, revocation, and recovery/rollback drills pass. + +### Canonical-source and authority reconciliation + +**North Star disposition — eliminate ambiguity before code.** `docs/fleet/NORTH_STAR.yaml` is the only canonical, machine-readable Fleet goal/backlog input. `docs/fleet/NORTH_STAR.md` is its deterministic generated projection and is never hand-edited or parsed as an input. `docs/fleet/north-star.md` is retained only as historical/strategic Fleet doctrine (including the pre-canon PoC and Forge discussion); it must be labelled non-authoritative and reconciled into either the YAML or a versioned ADR before it can drive a requirement. `docs/scratchpads/north-star-doctrine.md` is a merge-history artifact, not policy. `docs/requirements/native-kanban-sot.md` plus its frozen contract/manifest/task set are the current canonical requirements for project/task/orchestration SOT; `docs/PRD.md` is the umbrella product PRD and `docs/TASKS.md` is presently a rollup, then becomes a generated projection after the Kanban cutover. No duplicate North Star, PRD, scratchpad, roster, Matrix room, or provider issue can be a competing writable authority. + +**Do not mint a universal lease.** These typed grants have separate subjects, effects, storage and revocation paths: (1) #758 local roster/lifecycle and team-leader-capacity leases govern a local desired-state fleet and never grant remote execution; (2) KBN assignment/task leases and task fences govern one canonical task execution; (3) #757 connector lease + short execution grant governs the exclusive current consumer of one logical-agent channel binding; (4) an auth session proves a human/service can request a Gateway command but grants no task or connector ownership; and (5) a federation mTLS grant is remote, read-only data authority. Crossing any boundary requires a new Gateway authorization decision—none is convertible into another. + +### Open-issue disposition and dependency spine + +| Issues | Disposition / accountable boundary | Dependency | +| --- | --- | --- | +| #753 | **Keep; P0 KBN authorization/constraint gate**, owned by KBN/Gateway security review. | #752 canon → #753 → KBN-100. | +| #754, #755, #757 | **Keep #754 as failover umbrella; reconcile #755’s M1 tracking into delivered #757 evidence, then close/supersede #755 only after independent review.** #757 owns connector identity/fence/grant, not task leases. | #757 qualifies before connector cutover; #754 owns receipts, adapters and real failover/rollback E2E after it. | +| #756 | **Keep**, but channel UX/contracts only; no production control cutover until #757 and receipt/replay work provide authority. | #757 → #754 receipt/adapter gate → #756 production activation. | +| #758, #636 | **Keep distinct.** #758 owns local roster desired-state, safe generated projections and local lifecycle; #636’s web-editable launch config is deferred/re-scoped behind #758’s validation/quarantine boundary and a separate web auth threat model. | #758 M0→M1–M5; #636 cannot expose command/channel overrides or web mutation merely because roster fields exist. | +| #44, #64, #94 | **Merge into an Auth/remote-control foundation.** Keep #44’s OIDC work with explicit session/revocation/claim mapping; elevate #64 sandbox/tool isolation to a release blocker; supersede #94’s shared-key/localhost-bypass recommendation with tenant-scoped, rotated service identities and mTLS/attestation where applicable. | Foundation before any privileged web/connector attach or tool action. | +| #463–466, #482 | **Keep federation functional DAG** (#463 M4 → #464/#465 M5/M6 → #466 M7); defer #482 until a pipeline-provisioned, isolated two-instance test environment replaces its retired deployment assumptions. | Federation control remains read-only until M7 abuse/revocation/tenant evidence passes. | +| #558, #623 | **Keep separate and defer.** #558 is a typed budget-policy/read-model workstream, never a lease or autonomous authorization override. #623 requires privacy, re-identification, retention/consent and deletion threat modelling before any telemetry. | Neither blocks PG/KBN core; neither may become a shadow SOT. | +| #628 | **Defer/re-scope after canonical KBN authority exists.** Forge may propose/sequence through typed Gateway commands, but `agent-send` cannot itself claim, approve, lease, or complete canonical work. | KBN P1/P2 Gateway + deterministic Coordinator first. | +| #706–709 | **Keep #706 umbrella; reconcile stale ledger/issue status.** #707 security/runtime foundation → #708 durable state → #709 Discord/CLI, with production attach/control additionally gated by #757/#754. Tess remains interaction, never a competing orchestrator. | #707 → #708 → #709; #754 controls cross-harness continuity. | + +This is a release DAG, not implementation reservations. USC’s proposed final read-only reconciliation should compare a frozen artifact hash/inventory to these dispositions before the first implementation slice. + +### Minimum release gates (block product launch, not merely code merge) + +1. **Threat/constraint gate:** #753-quality authorization matrix covers web/CLI/WS/MCP/Discord/Matrix/federation/runtime paths, every principal/action/target, tenant relationship, denial, audit evidence, and abuse test; no unresolved schema or API impact. +2. **Authority gate:** logical identity, exclusive durable connector lease, monotonic fencing, server-minted scoped grants, revocation, and stale-holder denial work across every exposed adapter. No raw tmux/web terminal control. +3. **Data-integrity gate:** PostgreSQL is proven sole writer; transaction-local write proof, idempotency/version checks, append-only audit/outbox, durable receipt/reconciliation and generated-projection non-import tests pass under DB/Valkey/network faults. +4. **Identity/tenancy gate:** SSO/session lifecycle and step-up behavior are defined; active-membership, cross-workspace/no-oracle, guessed ID, replay, forged approval/grant, attachment/session fixation and WS reauthorization negatives pass across every transport. +5. **Recovery gate:** selected recovery posture is mechanism-verified; isolated restore plus WAL/PITR, stale-fence rejection after restore, crash/ambiguous-effect recovery, rollback and break-glass drills have independent evidence. +6. **Transport gate:** Matrix/Discord/tmux/web adapters pass the same contract suite, including binding/parent-thread authorization, replay/idempotency, redaction, outage and revocation tests; unqualified adapters remain disabled. +7. **Independent release gate:** author-independent functional and security review, certifier traceability decision, terminal-green CI, focused E2E/fault tests, runbooks and operational handoff are complete. A polished dashboard, passing unit tests, or a live demo cannot waive any of these. + +The defensible first release is therefore a **read-mostly, authenticated, workspace-scoped operations console** over Gateway-owned canonical state, with explicit status, audit, recovery posture and controlled typed actions. Browser terminal emulation, broad remote attach, autonomous failover, multi-tenant federation control, and desktop-terminal integrations are later increments only after the gates above are evidenced. + +## Cross-examination + +Sol and Terra completed an adversarial exchange outside this file and converged on the following bounded +position. This record is the traceable summary of that exchange; it does not create implementation +authority. + +### Terra's strongest objections to the product thesis + +1. A useful session page can become a remote privileged shell by accident. `Watch` must therefore remain + redacted and read-only by default, while every mutation is a typed Gateway command with exact target, + actor, workspace, policy revision, fence, expiry, idempotency key, and durable receipt. There is no + browser-to-PTY or browser-to-tmux attachment in the initial product. +2. A stable display name is not an identity or grant. Logical agent, runtime incarnation, context + generation, task execution lease/fence, connector epoch, user session, local fleet capacity lease, and + federation grant stay separate and independently revocable. +3. A reset, checkpoint, or acknowledgement inferred from pane text is unsafe. Runtime transitions require + structured adapter/supervisor receipts; free-form LLM output is never proof of reset, readiness, or + effect completion. +4. Delivery and recovery are not exactly-once. Lost acknowledgement after an external effect is + `ambiguous`, blocks blind retry, and requires evidence-driven reconciliation or quarantine. +5. Product completeness cannot precede tenant isolation, revocation, append-only semantic audit/outbox, + restore evidence, stale-fence rejection, and negative abuse/fault coverage. + +### Sol's strongest objections to security overconstraint + +1. A fresh process must be the mandatory fallback, not the universal path. A runtime-native reset may keep + a warm standing process only when the adapter can attest the primitive, the workspace/sandbox/tool + policy remains compatible, prior authority and effects are resolved, and generation checks succeed. +2. Routine, deterministic transitions should not require human approval. Human attention is reserved for + ambiguity, quarantine, policy exceptions, or other already-defined high-risk cases. +3. Mosaic must not claim impossible proof that a model has forgotten. It can prove only that an approved + reset primitive or process replacement occurred and that baseline/task context was reinjected under a + new fenced generation; the UI must label that evidence honestly. +4. Adapter mechanics and terminal-text interpretation do not belong in the Mechanical Coordinator. The + Coordinator consumes structured state and policy; the runtime adapter/supervisor invokes the primitive + and emits the receipt. +5. Freshness is not authorization. Reset must not silently substitute for task assignment, execution + leases/fences, independent review, checkpoint/effect reconciliation, or merge authority. + +### Ratified context-transition contract + +A task boundary is represented by a typed `ResetSession` / `reset_context` adapter operation, with `/new`, +`/clear`, or process replacement as runtime-specific implementations. The allowed transition is: + +`active → checkpointing → quiescent → reset_requested → reset_acknowledged → baseline_verified → lease_pending_ack → active` + +The safe order is normative: + +1. Fence and revoke the prior task's write/effect grants. The prior lease quiesces and releases only after + a checkpoint/effect receipt, or an explicit owner-authorized no-resume disposition. A worker cannot + declare no-resume for its own convenience. +2. Lock the approved next assignment for transition, but grant it no task execution authority yet. +3. Issue `ResetSession` bound to workspace, logical agent, current runtime incarnation, approved + assignment ID, next task ID/execution generation, expected context generation, transition operation + ID, policy revision, expiry, nonce, and idempotency key. It is deliberately **not** bound to a future + task lease/fence: verified clean context is a prerequisite to that lease. +4. The exact-target adapter invokes only its allowlisted native reset primitive or replaces the process. + Task, terminal, transcript, and user strings are never interpolated into the reset command. +5. A nonce-bound structured adapter/supervisor receipt attests the invoked primitive or replacement and + binds logical agent, runtime incarnation, workspace, expected-to-next context generation, reset nonce, + and primitive/policy digest. It does not claim metaphysical proof that model memory was erased. +6. Compare-and-swap advances the monotonic context generation and verifies the baseline + persona/contract/tool-policy digest. Reject every output/event from the old generation. +7. Only after reset and baseline verification may the Coordinator acquire the new pending-ACK task + execution lease/fence. Gateway then delivers the separately typed fenced task envelope and awaits a + mechanical task receipt before changing the session to active. No task effect is permitted earlier. + +A verified native reset may reuse a process only within the same compatible workspace, harness, sandbox, +workdir, privilege, persona/contract, and tool policy, with no unresolved effects and successful generation +CAS. Start a fresh process for workspace, harness/provider, sandbox, or privilege change; unsupported, +unverifiable, timed-out, or ambiguous reset; crash/contamination; stale generation; failed policy digest; +or any integrity uncertainty. On failure, the product offers `Retry reset`, `Replace process`, `Reassign`, +and `Inspect redacted diagnostics`; it never offers `Skip`. Quarantine integrity uncertainty and emit a +semantic transition event plus operator alert. + +The UI preserves stable logical-agent identity while visibly separating runtime incarnation and context +revision. It shows the old and new task IDs, reset method, context generation, brief/policy digests, +timestamps, and redacted receipt—not the prior transcript. Required fault coverage includes crash and +reset before/after checkpoint, acknowledgement loss, concurrent reset, forged/wrong-target receipt, +stale-output race, unsupported primitive, control-byte injection, timeout, and restart recovery. + +## Reconciled architecture and product plan + +### North Star and release sequence + +Mosaic is one authenticated, workspace-scoped control plane for understanding objectives, canonical work, +logical agents, runtime sessions, evidence, and safe next actions. PostgreSQL is the sole writable +project/task/orchestration source of truth. A deterministic non-LLM Coordinator applies eligibility, +dependency, lease, fence, retry, and quarantine policy. Browser, CLI, Discord, and Matrix are untrusted +Gateway clients. Runtime adapters execute exact typed effects but do not mint authority. + +Release in dependency order: + +1. **Authenticated visibility:** workspace-scoped Command Center, Work, Fleet, Activity, Communications, + Administration, and personal settings over authoritative read models and durable cursors. +2. **Low-risk typed actions:** Watch, Message, Interrupt, Stop, Approve/Reject, and recovery requests with + server-derived scope, idempotency, audit receipt, policy/fence validation, and explicit ambiguity. +3. **Privileged control:** risk-class step-up, short-lived exact-target grants, active revocation/policy + version enforcement, connector fencing, context-transition proof, rollback evidence, and no raw shell. +4. **Failover and federation:** Matrix/federation grants, no-oracle tenant boundaries, receipt-driven + recovery, WAL/PITR restore proof, stale-grant rejection, and qualified adapter cutover. + +The measurable 30/60/90-day outcomes remain those in Sol's progressive plan above, tightened by Terra's +release gates: first freeze the shared product/authority/event contracts; then ship one real canonical +Project/List/Kanban/task-detail vertical slice and read-only Fleet/Activity; then add assignment and +qualified typed session actions only where identity, authorization, fencing, reset, receipt, and recovery +evidence has passed. If a prerequisite is not green, the interface remains truthfully read-only. + +### Canonical information architecture + +- **Home / Command Center:** attention, changes, unhealthy/stale resources, blocked work, approvals, budget + horizon, recovery posture, and recent significant events. +- **Work:** Projects, Board/List, task detail, missions, dependencies/readiness, artifacts, evidence, + reviews, and delivery history. +- **Fleet:** logical agents, runtime sessions, capacity/assignment, and initially read-only local roster + provenance/drift. +- **Activity:** Needs attention, Changes, Delivery, Security, and System, backed by semantic events rather + than raw terminal output. +- **Communications:** web/CLI/Discord/Matrix bindings and delivery health without granting task or agent + authority. +- **Administration:** members, SSO sessions, policies, providers, federation, audit, recovery, retention, + legal/build/instance metadata. +- **Personal settings:** profile, accessibility, notifications, timezone, density, and dark/light/high- + contrast themes. + +Responsive views preserve the same nouns and authority labels. Mobile Board has a list alternative; every +pointer action has a keyboard/menu equivalent; status never depends on color alone. Public login, privacy, +terms, support/status, and instance metadata remain outside privileged workspace content. + +### Authority and data boundaries + +The five operational authority domains remain distinct: authentication/workspace membership; Native +Kanban assignment and task execution lease/fence; local Fleet roster/lifecycle/capacity; connector +lease/epoch/execution grant; and federation read grant. Merge/release is a sixth governed outcome whose +sole approve-to-land authority is merge-gate after independent review/security/certification evidence. +No grant is convertible into another. Every cross-domain effect requires a fresh Gateway authorization +decision. + +Canonical state, approval/evidence relationships, semantic event, and outbox record commit together in +PostgreSQL. Delivery operations carry durable IDs and immutable digests. Valkey, Matrix, Discord, tmux, +provider state, Markdown, browser storage, and files are transports, projections, external evidence, or +inert proposals—not writers. Operational telemetry is correlated but lossy and never authority. Recovery +uses encrypted off-cluster backup plus selected WAL/PITR posture, isolated restore drills, and evidence that +restored state rejects stale leases, grants, epochs, and context generations. + +### Epic and gate decomposition + +| Epic | Outcome | Principal dependencies | +| --- | --- | --- | +| **E0 — Canon and foundations** | Reconcile umbrella PRD/TASKS, Native Kanban contract, authority glossary, event taxonomy, auth/runtime foundations, context-transition contract, responsive shell, and issue/doc disposition. | #753, #44, #64; canonical planning PR before implementation. | +| **E1 — Visible control plane** | Authenticated Command Center, real Work P1 journey, read-only Fleet/session inventory, semantic Activity, themes/legal/settings. | E0; KBN-100/105 and Gateway read contracts. | +| **E2 — Governed coordination** | Assignment approval, deterministic readiness, evidence/review/certification, channel continuity, retry/quarantine. | E1; KBN P2; #757/#754 receipt and identity work; #756 contract. | +| **E3 — Privileged typed operations** | Qualified session actions and context reset with step-up, exact-target grants, active revocation, receipts, ambiguity handling, and rollback. | E2; #758 local completion; adapter/security/fault qualification. | +| **E4 — Failover/federation** | Matrix and gateway federation administration, durable continuity, recovery and stale-authority rejection. | E3; #463–#466 and qualified two-instance pipeline environment. | + +| Gate | Evidence required | +| --- | --- | +| **G0 — Canon/contract** | One source per scope; authority glossary and ResetSession ordering frozen; issue/doc disposition and consumer inventory independently reconciled. | +| **G1 — Tenant/auth/data** | Active membership, no-oracle cross-workspace constraints, PG-only writes, transaction-local proof, event/outbox atomicity, auth/session/revocation negatives. | +| **G2 — Delivery journey** | Canonical task lifecycle, dependencies, assignment/lease/fence, evidence, independent review/certification, reconnect cursor, and responsive/accessibility E2E. | +| **G3 — Privileged runtime** | Exact-target adapter, short grants, revocation, context-generation CAS, reset/baseline/task receipts, stale-output denial, ambiguity/quarantine, abuse/fault tests, rollback. | +| **G4 — Continuity/release** | WAL/PITR and isolated restore drills, stale-authority rejection after restore, adapter parity, federation/Matrix revocation/outage tests, independent product/security/certifier review, terminal-green CI. | + +Cards under each epic must be dependency-ordered and sized to one branch/PR. Source changes require a +separate author and exact-head reviewer-of-record; security-sensitive cards add independent SecReview; +release evidence adds a validator certificate but leaves merge-gate as sole merge authority. The canonical +tracking system records owner, dependencies, expected generation, lease/fence, artifact/review identity, +CI, merge, rollback, and closure so a restarted orchestrator can resume without transcript inference. + +### Migration, non-goals, and documentation + +Initial delivery does not include raw browser terminal attachment, arbitrary tmux/systemd/command/channel +mutation, direct client database writes, a second task store, autonomous cross-instance writes, universal +leases, exactly-once external-effect claims, or cmux/Ghostty as security dependencies. `mos-comms-live` and +static exact-target tmux wake remain a temporary audited compatibility bridge until qualified Matrix/ +federation replaces them; peer text is never injected as authority. + +Migration is additive and rollback-ready: read models before writers; typed commands shadowed and audited +before activation; adapters qualified independently; local Fleet mutation remains behind #758; connector +and channel cutover waits for #757/#754/#756 evidence; federation remains read-only. Feature flags disable +new commands without corrupting canonical state, while old projections can be regenerated from PG or the +local roster authority appropriate to their domain. + +Canonical requirements belong in `docs/PRD.md`, active dependencies in the canonical task system (with +`docs/TASKS.md` only as the temporary rollup/generated successor), Native Kanban contracts under +`docs/native-kanban-sot/`, Fleet operations under the accepted #758 documentation IA, security/threat and +recovery runbooks under scoped admin/developer guides, and API contracts in OpenAPI plus human-readable +indexes. This planning artifact is frozen evidence after independent reconciliation, never a competing +runtime source of truth. + +## Decisions and unresolved questions + +No owner decision is currently required to continue planning. Autonomous defaults are: + +- keep privileged control and federation behind their evidence gates; +- use risk-class step-up rather than prompting for every routine action; +- allow verified native reset only within compatible boundaries, with fresh process as mandatory fallback; +- keep Activity privacy-redacted and semantic, with raw OTEL/terminal data diagnostic-only; +- use PostgreSQL-backed durable transitions and receipts without claiming exactly-once external effects; +- preserve #757 ownership hold, #758 local-control scope, and USC read-only migration posture until their + respective gates converge. + +Escalate only if the owner changes the North Star/ranked outcomes, reserves an implementation owner, +changes material capacity/budget, supplies non-inferable business/legal constraints, or chooses a recovery +posture weaker than the release claim it is expected to support.