# Mosaic Web Control Plane North Star — Oppositional Planning

Status: REV3 CURRENT PLANNING CANDIDATE — USC independent exact-artifact re-review pending; not canonical; no implementation authority
Owner: Homelab Mos with USC coordination
Rev3 authority: editorial planning correction only. This artifact grants no reservation, canonicalization, consumer, connector, implementation, rebase, remediation, merge, supersession, cutover, production, service, session, or live-fleet authority. No implementation may proceed from it before USC exact-artifact re-review and the applicable owner-controlled gates below are recorded as passed.

## 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 and completed #753/KBN-010),
logical identity/fencing (#754/#755 plus #757, whose maintainer remediation is awaiting fresh exact-head re-review), shipped immutable channel code-contract
foundation (#756), local fleet configuration (#758, M1-001 merged and M1-002 still prerequisite to M2), 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. These are targets for later qualification, not claims about current
product performance.

#### Five critical user journeys and 30-second targets

Measurement starts only in an approved prototype or release-candidate environment with representative,
pre-seeded scenarios and an authenticated participant whose role is stated. Each run records a correlated
journey ID, start/end monotonic timestamps, workspace and build revision, authorization/policy revision,
read-model/event cursor ages, command/receipt IDs where applicable, outcome, and any denial or timeout.
Telemetry is diagnostic evidence only; it cannot authorize a result. Targets are readiness/outcome criteria
that remain **unproven** until independently tested.

| Journey | Truthful readiness/outcome target | Required evidence | Failure-state behavior |
| --- | --- | --- | --- |
| **J1 — Morning oversight** | Within 30 seconds of Command Center readiness, the portfolio operator correctly identifies what changed, unhealthy/stale resources, blocked work, and every seeded human decision. | Journey timing, build/read-model revisions, cursor age, selected attention items, and scorer comparison to the seeded canonical state. | Show stale/partial/unavailable provenance; do not display an all-clear state or synthesize missing health. Provide retry and authoritative-detail links. |
| **J2 — Task-to-proof trace** | Within 30 seconds of task-detail readiness, a project lead locates accountable owner, assignment, exact typed task lease/fence, runtime session, evidence, review/certification state, and causal timeline. | Journey timing plus entity/revision IDs, relationship-query spans, event cursor, and scorer confirmation that no authority domains were conflated. | Mark each unresolved relation unknown/stale independently; disable dependent actions and never infer ownership, readiness, or completion. |
| **J3 — Privileged action readiness/outcome** | Within 30 seconds of selecting a qualified typed action, an authorized operator either receives a durable success/denial receipt or sees an explicit pending/ambiguous state; no success is inferred from terminal text. | Authorization decision ID, step-up result when required, exact target/fence/policy revision, operation/idempotency digest, semantic event, outbox/delivery receipt, and elapsed time. | Fail closed on stale authority or unavailable proof; disable raw fallback and blind retry. Offer evidence-led reconcile/quarantine/retry only when policy permits. |
| **J4 — Channel continuity** | Within 30 seconds of opening Communications for a seeded continuation, the interaction user identifies the logical agent, verified workspace/project/thread binding, latest durable receipt, and whether sending is currently authorized. | Binding and logical-agent IDs, connector epoch/holder status, replay/dedup result, receipt cursor, authorization decision, and elapsed time across the qualified adapter. | Show unverified/stale/conflicting binding explicitly, keep content read-only, and prohibit send/rebind or fallback injection. |
| **J5 — Incident/audit reconstruction** | Within 30 seconds of Activity readiness, a reviewer/auditor reconstructs actor, target, cause, policy/fence revision, denial or effect outcome, and current recovery state for a seeded incident. | Correlation/causation chain, append-only semantic event revisions, redaction/classification decision, restore/recovery evidence reference, and scorer result. | State gaps, redactions, cursor lag, or unavailable recovery evidence visibly; never fill gaps from lossy OTEL, terminal output, or operator notes. |

### 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. M1-001 is merged at `aa5b43b…`; M1-002 must complete before M2. | It does not assign canonical tasks, authenticate users, converge the Gateway agent catalog during M1–M5, or grant live/web fleet authority. |
| **Connector execution (#754/#755; #757 under exact-head verification)** | The intended domain is an exclusive **connector lease/epoch** and short-lived execution grant binding logical agent, channel binding, harness holder, scope and effect. Maintainer `web1:coder1` owns #757 remediation; the rebase and scope-substitution RoR remediation are complete and pushed at exact head `b7302a9`. | Pipeline 1817 is terminal green and a fresh independent exact-head re-review is pending. Until both are terminal green/passed and the normal merge gate lands #757, it authorizes no consumer use, merge, supersession, connector cutover, or claim that #755 is implemented. 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 a **candidate**, not yet an accepted or merged, M1 implementation of #755. Its migration
`0016` collision/disposition must be verified at exact head `b7302a9`; pipeline 1817 is terminal green;
fresh independent exact-head re-review must pass; and merge must follow the normal gate. #754 remains the
parent for checkpoint, receipt, adapters and failover work; #755 may not close, and #754 consumer or
connector cutover work may not proceed on the basis of #757 before those gates complete. Later work must
extend the typed authority 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.

### Legal/privacy owner-decision gate (implementation-blocking)

The accountable role is the **owner-designated Legal/Privacy Decision Owner**. This names a responsible
role, not an inferred or invented person. Before any affected public page, authenticated identity/session
surface, semantic-audit surface, terminal-derived-data surface, export, deletion, incident, or privileged
control is implemented or activated, owner-controlled authority must record decisions for:

1. applicable jurisdiction(s) and Mosaic's controller/processor roles;
2. data classification for semantic audit, SSO/session data, and terminal-derived data;
3. retention periods and deletion/export rules for each class;
4. subject/access request handling and incident processes;
5. required public legal pages, their approved content, publication owner, and update process.

Every non-inferable fact and legal conclusion in those areas remains unresolved. This artifact supplies no
jurisdiction, role, classification, retention period, legal basis, notice text, or compliance conclusion.
Affected public or privileged surfaces remain implementation-blocked until the decision record is approved
by owner-controlled authority and independently traced into requirements and acceptance evidence. #623
remains deferred post-MVP and gains no authority from this gate.

### Progressive 30/60/90-day outcomes

The clock starts only after USC exact-artifact re-reviews this rev3 artifact, applicable owner-controlled gates pass, and
a separately authorized 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. Record #753/KBN-010 as complete via PR #765 squash `2e228007…`, with PR pipeline 1812 and descendant `main` pipeline 1813 terminal green; its KBN-100 dependency is released. Correct the umbrella PRD contradictions at G0. Establish contract-backed read-only prototypes for Command Center, Work and Fleet; legal/footer and affected auth/session/audit/terminal-data surfaces remain blocked until the Legal/Privacy Decision Owner gate is recorded. | Every visible datum names its authority/provenance; all duplicate docs/issues have disposition; five critical journeys have instrumented prototype evidence against their unproven 30-second targets; keyboard/mobile/contrast checks pass; no web, file, Valkey or channel writer exists. |
| **60 days — useful vertical slice** | After G0 and legal/privacy decisions applicable to the 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; independently measured daily oversight target 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 after #757's migration `0016` collision/disposition is accepted by fresh independent exact-head re-review, pipeline 1817 is terminal green, #757 is merged, and #754/#64 policy and receipt evidence pass; #756 alone is not cutover authority. Expose #758 configuration provenance/drift read-only only after M1-002 and its subsequent gates; no live/web fleet authority is implied. 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 browser-to-tmux/systemd/DB access; 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.** Only after USC exact-artifact re-review and applicable owner-controlled gates pass may a separately authorized effort propose approved decisions in a canonical requirements/tracking PR. Freeze this artifact by hash for that independent review; this disposition itself grants no conversion or implementation authority. |

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 / KBN-010** | **Complete.** PR #765 was squash-merged at `2e228007…`; PR pipeline 1812 and descendant `main` pipeline 1813 are terminal green. KBN-100 dependency is released. This evidence does not bypass later consumer gates. |
| **#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** | **Verification/merge hold:** maintainer `web1:coder1` owns #757 remediation; rebase is complete; and the scope-substitution RoR finding is remediated and pushed at exact head `b7302a9`. Pipeline 1817 is terminal green and fresh independent exact-head re-review is pending. Preserve the migration `0016` collision/disposition for that review. No consumer use, merge, supersession, #755 closure, or #754 connector cutover may proceed until exact-head review passes, pipeline 1817 is terminal green, and the normal merge gate lands #757. Retain #754 for checkpoints, receipts, adapters and deferred failover. No universal lease. |
| **#756** | **Shipped/closed immutable code-contract foundation, not production cutover.** Keep its harness-neutral channel/plugin contract as foundation evidence. Any shared Discord/Matrix consumer or dynamic administration work remains separately gated by resolved connector authority, receipts/replay, qualification, and owner-approved activation. |
| **#758** | **Keep** under its M0–M5 DAG as local roster/config/lifecycle authority. M1-001 is merged at `aa5b43b…`; M1-002 must complete before M2. FCM owner ships local compiler/reconcile/docs only through that DAG; this plan grants no live/web fleet authority, Gateway/UI convergence, arbitrary commands, or channel mutation. 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** | **Keep on hold pending owner ratification; do not supersede from this plan.** Its Portainer/Swarm assumptions appear inconsistent with the intended pipeline-driven disposable two-gateway test environment, but only owner-controlled authority may amend, re-plan, or supersede it. No manual image/deploy path is authorized. |
| **#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** | **Reconcile against #756’s shipped immutable foundation** for Discord/CLI transport behavior, then retain only Tess-specific same-session E2E acceptance. This is a proposed dependency disposition, not consumer or cutover authority; avoid a second Discord plugin. |

**Dependency spine:** canonical docs/reconciliation and G0 contradiction removal → completed #753/KBN-010
(PR #765, `2e228007…`, pipelines 1812/1813 green) → released KBN-100 → KBN-105 → parallel KBN
Gateway/CLI/web P1 → P1 integration → deterministic KBN P2. Applicable legal/privacy owner decisions are
blocking inputs to affected public and privileged surfaces. In parallel, #44 and #64 establish human and
runtime safety; #757 remediation is owned by `web1:coder1` and pushed after rebase at exact head
`b7302a9`, with pipeline 1817 terminal green and fresh independent exact-head re-review pending, while #756 is only the
shipped immutable code-contract foundation, not cutover. #758 proceeds on its isolated local DAG from
M1-001 `aa5b43b…` through M1-002 before M2, with no live/web fleet authority. The web Command Center may
consume approved read contracts only after G0; 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/KBN-010 completed through PR #765 (`2e228007…`) with pipelines 1812 and 1813 terminal green, releasing KBN-100, but its threat/authorization discipline still constrains consumers; #754/#755 define continuity requirements while #757 remediation is owned by maintainer `web1:coder1`, rebased, and pushed at exact head `b7302a9`, with pipeline 1817 terminal green and fresh independent exact-head re-review pending; no merge, #755 closure, consumer, or cutover authority follows yet; #758 correctly excludes remote/UI/connector mutation, with M1-001 merged at `aa5b43b…` and M1-002 required before M2. Those boundaries 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. The intended 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. For #757, maintainer `web1:coder1` owns remediation; the rebase and
scope-substitution RoR remediation are complete and pushed at exact head `b7302a9`. Pipeline 1817 is terminal green,
and a fresh independent exact-head re-review is pending. The migration `0016` collision/disposition remains review
scope, and #757 cannot be consumed, merged, used to close #755, or used for #754 connector cutover until that
review passes, CI is terminal green, and the normal merge gate lands it. 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) the intended connector lease + short execution grant would govern the exclusive current consumer of one logical-agent channel binding, but #757 remains non-consumable pending fresh independent exact-head re-review of `b7302a9`, terminal-green pipeline 1817, and merge; (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 / KBN-010 | **Complete evidence, continuing consumer constraint.** PR #765 was squash-merged at `2e228007…`; PR pipeline 1812 and descendant `main` pipeline 1813 are terminal green, releasing KBN-100. | Completed #752 canon → completed #753/KBN-010 → KBN-100 released; later consumers still pass their own gates. |
| #754, #755, #757 | **Keep #754 as failover umbrella and #755 pending; verification/merge hold on #757.** Maintainer `web1:coder1` owns #757 remediation; rebase and scope-substitution RoR remediation are complete at exact head `b7302a9`. Pipeline 1817 is terminal green and fresh independent exact-head re-review is pending. Preserve the migration `0016` collision/disposition under review. No consumer use, merge, supersession, #755 closure, or #754 cutover until exact-head review passes, CI is terminal green, and #757 merges through the normal gate. | The candidate connector identity/fence/grant contract must clear those gates before consumer work; #754 retains receipts, adapters and real failover/rollback E2E. |
| #756 | **Shipped/closed immutable code-contract foundation, not production cutover.** | Consumer/channel activation requires resolved connector authority plus #754 receipt/adapter, replay, qualification, and owner activation gates. |
| #758, #636 | **Keep distinct.** #758 owns local roster desired-state, safe generated projections and local lifecycle; M1-001 is merged at `aa5b43b…`, and M1-002 must finish before M2. #636’s web-editable launch config is deferred/re-scoped behind #758 validation/quarantine and a separate web auth threat model. | No live/web fleet authority; no 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). #482 remains held; this plan does not supersede or re-plan it. Owner ratification is required before changing its disposition or adopting a pipeline-provisioned isolated two-instance replacement. | Federation control remains read-only until M7 abuse/revocation/tenant evidence passes; no manual deployment path is authorized. |
| #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:** the completed #753/KBN-010 evidence—PR #765 squash `2e228007…`, PR pipeline 1812 and descendant `main` pipeline 1813 terminal green—covers its ratified authorization/constraint scope and released KBN-100. Each web/CLI/WS/MCP/Discord/Matrix/federation/runtime consumer must still trace its principal/action/target, tenant relationship, denial, audit evidence, abuse tests, and any new schema/API impact; completion is not blanket implementation authority.
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; intended connector
lease/epoch/execution grant (not consumable until #757 exact-head review, terminal-green CI, and merge); 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, legal/privacy owner decisions, and issue/doc disposition. | G0 stale-language correction; completed #753/KBN-010 evidence; #44 and #64; USC-re-reviewed 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 exact head `b7302a9` accepted by fresh independent re-review, pipeline 1817 terminal green, and #757 merged; #754 receipt and identity work; #756 immutable foundation plus separately qualified consumer activation. |
| **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 correction** | Before any later implementation, owner-controlled authority must correct or explicitly retire every stale umbrella-PRD statement that grants Valkey writable/authorization authority or permits raw browser/operator barge-in to tmux/PTY. A line-by-line contradiction inventory, corrected canonical text, provenance, consumer links, authority glossary, ResetSession ordering, issue/doc disposition, and independent reconciliation must be recorded. While any contradictory stale text remains, G0 is failed and E1–E4 implementation may not proceed. |
| **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. Matrix/federation
does **not** universally replace local tmux. Same-host, exact-target tmux remains a bounded runtime execution
transport behind an allowlisted adapter, scoped grant, fence, receipt, and audit; it is never exposed raw to
the browser and is not identity or authority. Matrix/federation may replace temporary cross-host/operator
messaging such as `mos-comms-live` where qualified, but not local process supervision or exact-target
execution merely by being available. Static cross-host/operator messaging bridges remain temporary,
audited, non-authoritative compatibility paths until a qualified replacement is owner-activated; 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, with
M1-002 before M2 and no live/web authority from this plan; connector consumer work waits for fresh independent
exact-head acceptance of #757's migration `0016` collision/disposition at `b7302a9`, terminal-green pipeline 1817,
and #757 merge, plus #754 receipts, while #756 remains immutable foundation rather than
cutover authority; 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

Planning may continue, but implementation and canonicalization may not. Owner-controlled decisions remain
required for the following blocking facts and dispositions:

- the Legal/Privacy Decision Owner record for jurisdiction and controller/processor roles; classification
  of semantic audit, SSO/session, and terminal-derived data; retention, deletion, export; subject/access and
  incident processes; and approved public legal pages;
- correction or retirement of every stale umbrella-PRD statement granting Valkey authority or raw
  browser/operator tmux/PTY barge-in, with G0 independently evidenced;
- #757 exact head `b7302a9` migration `0016` collision/disposition acceptance by fresh independent re-review,
  terminal-green pipeline 1817, and normal-gate merge before any consumer use, supersession, #755 closure,
  or #754 cutover;
- owner ratification before any amendment, re-plan, or supersession of #482;
- owner activation for any production connector, channel, Matrix/federation, public, privileged, or web
  fleet surface after its dependencies and independent evidence pass.

Bounded planning defaults—none of which grant implementation authority—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;
- keep #623 deferred; treat #756 as shipped immutable contract foundation rather than production cutover;
- preserve #757's exact-head review/terminal-green CI/merge hold, #758 local-control scope and M1-002-before-M2 dependency, #482's
  non-supersession hold, and USC read-only posture until their respective owner-controlled gates converge.

Non-inferable business, legal, privacy, recovery, ownership, and activation facts are unresolved. Escalation
to their designated owner-controlled authority is required before affected implementation; this artifact
must not manufacture a default. No canonical requirements/tracking conversion, implementation reservation,
consumer adoption, source change, service/session action, or live-fleet mutation is authorized until USC
re-reviews this rev3 exact artifact and all applicable blocking gates are explicitly passed.

## Rev3 Terra finding-closure matrix

Line ranges below refer to this rev3 artifact's current numbered text. They are traceability pointers, not
implementation or canonicalization authority.

| Terra finding | Current section / lines | Rev3 disposition | Remaining owner-controlled gate |
| --- | --- | --- | --- |
| **T1 — Legal/privacy facts and public/privileged surfaces lacked a responsible decision gate.** | `Legal/privacy owner-decision gate` (lines 233–250); `Decisions and unresolved questions` (lines 633–665). | Closed at planning level: responsible role, required decision set, non-inference rule, affected-surface block, and #623 deferral are explicit. | Legal/Privacy Decision Owner must approve the decision record; USC must verify traceability. |
| **T2 — Issue and dependency facts were stale or authority-expanding.** | Sol issue table/dependency spine (lines 291–335); Terra issue table (lines 407–421); reconciled epics/migration (lines 580–630). | Closed at planning level: #753/KBN-010 completion; #756 foundation-only status; maintainer `web1:coder1` ownership of #757 remediation; completed rebase and scope-substitution RoR remediation at exact head `b7302a9`; terminal-green pipeline 1817; pending fresh independent exact-head re-review; preservation of #757 migration `0016` and its competing-migration disposition; #758 milestones/no web authority; and #482 non-supersession are stated. | #757 fresh independent exact-head re-review, terminal-green pipeline 1817, and normal-gate merge; then separately gated #755 closure and #754 consumer/cutover. Owner ratification for #482; normal independent gates for all consumers; USC exact-artifact re-review. |
| **T3 — The five 30-second journeys were unnamed, uninstrumented, or presented as achieved.** | `Five critical user journeys and 30-second targets` (lines 78–93); progressive outcomes (lines 252–263). | Closed at planning level: five named readiness/outcome targets, telemetry/evidence, failure behavior, and unproven status are defined. | Product/security owners approve test fixtures and thresholds; independent qualification must produce evidence. |
| **T4 — Matrix/federation was written as a universal replacement for local tmux.** | Trust/runtime boundaries (lines 136–192, 343–364); `Migration, non-goals, and documentation` (lines 604–631). | Closed at planning level: bounded same-host exact-target tmux remains an execution transport; Matrix/federation replaces suitable cross-host/operator messaging only; raw browser-to-tmux remains prohibited. | Adapter/security qualification and owner activation for each transport. |
| **T5 — Stale umbrella PRD could still authorize Valkey or raw barge-in.** | `G0 — Canon/contract correction` (lines 590–596); unresolved owner gates (lines 633–665). | Closed at planning level by an explicit stop gate: E1–E4 cannot proceed while contradictory stale text remains. | Umbrella-PRD owner corrects/retires text; independent reconciliation and USC exact-artifact re-review pass G0. |
| **T6 — Rev3 exact-artifact closure traceability and non-authority.** | Rev3 authority header (lines 3–5); this matrix (lines 667–679). | Closed at planning level: each finding maps to a current range and remaining gate; non-authority is explicit. | USC validates ranges/content and decides whether a separate canonical requirements change may be proposed. |
