comms: publish North Star rev3 artifact
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jarvis
@@ -0,0 +1,679 @@
|
|||||||
|
# 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. |
|
||||||
Reference in New Issue
Block a user