diff --git a/comms/artifacts/mosaic-web-control-plane-north-star-rev4-1fb890ca.md b/comms/artifacts/mosaic-web-control-plane-north-star-rev4-1fb890ca.md new file mode 100644 index 0000000..db64c9c --- /dev/null +++ b/comms/artifacts/mosaic-web-control-plane-north-star-rev4-1fb890ca.md @@ -0,0 +1,682 @@ +# Mosaic Web Control Plane North Star — Oppositional Planning + +Status: REV4 FACTUAL REFRESH CANDIDATE — USC independent exact-artifact re-review pending; not canonical; no implementation authority +Owner: Homelab Mos with USC coordination +Rev4 authority: current-facts reconciliation 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 plus owner-workflow-closed #755 and merged #757), 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; closed #755; merged #757 foundation)** | The intended domain is an exclusive **connector lease/epoch** and short-lived execution grant binding logical agent, channel binding, harness holder, scope and effect. Stack #757 reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` was squash-merged to `main` as `eb4e14ae5cef873098251336310aded58e2d3f1e`; descendant `main` pipeline #1818 is terminal `SUCCESS`, with postgres, install, sanitization, typecheck, lint, format, test, build, publish, and gateway/appservice/web builds all successful. Issue #755 is closed by its owner-controlled workflow. | This merged evidence does not grant #754 authority or canonicalization. #754 remains open for checkpoints, exactly-once receipts/journal, concrete adapters, failover/rollback E2E, connector/channel consumers, cutover, and production activation. 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 the reviewed and merged M1 foundation for now-closed #755: reviewed head +`b7302a94c316e56f24b8021426e2fc12cf990067` was squash-merged to `main` as +`eb4e14ae5cef873098251336310aded58e2d3f1e`, and descendant `main` pipeline #1818 is terminal +`SUCCESS`. Preserve its migration `0016`; after rebasing, KBN-100 must regenerate its combined migration +as `0017`. #754 remains open for checkpoints, exactly-once receipts/journal, concrete adapters, +failover/rollback E2E, connector/channel consumers, cutover, and production activation; #757 and #755 +closure grant it no authority or canonicalization. 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 rev4 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 #754/#64 policy, checkpoint, exactly-once receipt/journal, concrete-adapter, failover/rollback E2E, connector/channel-consumer, cutover, and production-activation evidence passes; #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 open** as the runtime-neutral continuation parent after owner-workflow closure of #755; Gateway/runtime owners. It retains checkpoints, exactly-once receipts/journal, concrete adapters, failover/rollback E2E, connector/channel consumers, cutover, and production activation. Merged #757 does not grant #754 authority or canonicalization, and #754 does not depend on KBN task leases. | +| **#755 / #757** | **Merged/closed foundation evidence, not #754 authority.** Stack #757 reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` was squash-merged to `main` as `eb4e14ae5cef873098251336310aded58e2d3f1e`; descendant `main` pipeline #1818 is terminal `SUCCESS`, with postgres, install, sanitization, typecheck, lint, format, test, build, publish, and gateway/appservice/web builds successful. Issue #755 is closed by its owner-controlled workflow. Preserve migration `0016`; KBN-100 must regenerate its combined migration as `0017` after rebasing. #754 remains open with its separately gated scope. No universal lease or canonicalization follows. | +| **#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 reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` was squash-merged to +`main` as `eb4e14ae5cef873098251336310aded58e2d3f1e`, descendant `main` pipeline #1818 is terminal +`SUCCESS`, and #755 is closed by its owner-controlled workflow, 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 defines the remaining continuity requirements while #757 reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` was squash-merged to `main` as `eb4e14ae5cef873098251336310aded58e2d3f1e`, descendant `main` pipeline #1818 is terminal `SUCCESS`, and #755 is closed by its owner-controlled workflow; no #754 authority, canonicalization, consumer, cutover, or production activation follows; #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, reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` was squash-merged to +`main` as `eb4e14ae5cef873098251336310aded58e2d3f1e`; descendant `main` pipeline #1818 is terminal +`SUCCESS`, and #755 is closed by its owner-controlled workflow. Migration `0016` remains preserved; after +rebasing, KBN-100 must regenerate its combined migration as `0017`. This evidence grants no #754 authority +or canonicalization, and #754's retained consumer, cutover, activation, receipt/journal, adapter, and failover work remains separately gated. 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, with #757 reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` merged as `eb4e14ae5cef873098251336310aded58e2d3f1e` and descendant `main` pipeline #1818 terminal `SUCCESS`, but that evidence grants no #754 authority or canonicalization; (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 open; #755 is owner-workflow closed; #757 is reviewed and merged foundation evidence.** Stack #757 reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` was squash-merged to `main` as `eb4e14ae5cef873098251336310aded58e2d3f1e`; descendant `main` pipeline #1818 is terminal `SUCCESS` across postgres/install/sanitization/typecheck/lint/format/test/build/publish and gateway/appservice/web builds. Preserve migration `0016`; KBN-100 must regenerate its combined migration as `0017` after rebasing. | #754 retains checkpoints, exactly-once receipts/journal, concrete adapters, failover/rollback E2E, connector/channel consumers, cutover, and production activation. Neither #757 merge nor #755 closure grants #754 authority or canonicalization. | +| #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 the merged #757 foundation and open #754 work. 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 (with #757 merged foundation evidence but #754 consumer/cutover/activation authority still separately gated); 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; merged #757 foundation (`b7302a94c316e56f24b8021426e2fc12cf990067` → `eb4e14ae5cef873098251336310aded58e2d3f1e`) and terminal-success descendant `main` pipeline #1818; #754 checkpoint, exactly-once receipt/journal, concrete-adapter, failover/rollback E2E, consumer, cutover, and activation 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; preserve merged #757's migration `0016`, and KBN-100 must regenerate its combined migration as `0017` after +rebasing; connector consumer work remains under open #754's checkpoints, exactly-once receipts/journal, concrete +adapters, failover/rollback E2E, connector/channel consumers, cutover, and production activation, 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; +- preservation of #757 migration `0016` and KBN-100 regeneration of its combined migration as `0017` after + rebasing; #754 remains open and separately gated for checkpoints, exactly-once receipts/journal, concrete + adapters, failover/rollback E2E, connector/channel consumers, cutover, and production activation; +- 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 migration `0016`, KBN-100's post-rebase combined migration `0017` requirement, #754's separate open scope, #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 rev4 exact artifact and all applicable blocking gates are explicitly passed. + +## Rev4 Terra finding-closure matrix + +Line ranges below refer to this rev4 artifact's current numbered text. They are traceability pointers, not +implementation or canonicalization authority. + +| Terra finding | Current section / lines | Rev4 disposition | Remaining owner-controlled gate | +| --- | --- | --- | --- | +| **T1 — Legal/privacy facts and public/privileged surfaces lacked a responsible decision gate.** | `Legal/privacy owner-decision gate` (lines 235–252); `Decisions and unresolved questions` (lines 636–668). | 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 293–338); Terra issue table (lines 410–424); reconciled epics/migration (lines 583–634). | Closed at planning level: #753/KBN-010 completion; #756 foundation-only status; #757 reviewed head `b7302a94c316e56f24b8021426e2fc12cf990067` squash-merged as `eb4e14ae5cef873098251336310aded58e2d3f1e`; descendant `main` pipeline #1818 terminal `SUCCESS` across the named job set; #755 owner-workflow closure; preservation of migration `0016`; KBN-100's post-rebase combined migration `0017` requirement; #754's retained open scope and non-authority/non-canonicalization boundary; #758 milestones/no web authority; and #482 non-supersession are stated. | #754's checkpoints, exactly-once receipts/journal, concrete adapters, failover/rollback E2E, connector/channel consumers, cutover, and production activation remain separately gated. 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 254–265). | 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–194, 346–367); `Migration, non-goals, and documentation` (lines 607–634). | 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 593–599); unresolved owner gates (lines 636–668). | 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 — Rev4 exact-artifact closure traceability and non-authority.** | Rev4 authority header (lines 3–5); this matrix (lines 670–682). | 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. |