jason.woltje
ad21ad7ac5
ci/woodpecker/pr/ci Pipeline failed
Ratifies the Mosaic Stack PRD rev1 (Jason Woltje, 2026-09-01) as project source of truth and installs the GOV.1 lifecycle model: - docs/PRD.md becomes a permanent shim (kind: shim, current_rev -> docs/PRDs/2026-08-31_PRD_rev1/). Its path never changes again. - docs/PRDs/2026-08-26_PRD_rev0/PRD.md archives the 2026-08-26 North Star verbatim (sha256 60cc2f98...36afdf unchanged). Archive, never delete. - docs/PRDs/2026-08-31_PRD_rev1/ is the frozen rev1 bundle: 18 sectioned documents (VIS, DATA, AUTHN, AUTHZ, SEAT, ROLE, HARN, PROV, SESS, UI, CLI, GOV.1-5) consolidating rev0 D1-D15, the fleet north star, the agent-runtime L1/L2 contracts and the control-plane-surfaces lane findings, with a single decision map (GOV.3) and a closed open-questions frontier (GOV.5, grill rounds 1-8). Drafting inputs (_source-* snapshots) are not shipped. Consequences of the ratified rulings carried in the same change: - Q-T1 (ruling B, "shipped but frozen"): D3 amended in GOV.3/VIS.1; federation M1-M3 acknowledged as shipped behind tier === 'federated', excluded from the v1 bar and frozen, with a security re-audit gate before any resumption. docs/MISSION-MANIFEST.md, docs/federation/MISSION-MANIFEST.md and docs/scratchpads/mvp-20260312.md get status: superseded + banners (content preserved verbatim); docs/guides/deployment.md gains a "Relationship to the PRD (D15)" section. NORTH_STAR.yaml adds dormant workstream M (projects no goals by design); NORTH_STAR.md regenerated. - Q-G2 (distinct registry prefixes): every citation of the operator DECISION-REGISTER in the bundle reads OD-nn; the stack registry stays D1-D15; L1-Dnn/L2-Dnn untouched. Prefix rule recorded in GOV.1. Follow-ups (not in this PR): CI parity drift-gate witness (Q-C1); brain-side DECISION-REGISTER rename to OD- with redirect table on its next touch.
217 lines
11 KiB
Markdown
217 lines
11 KiB
Markdown
---
|
||
id: VIS.1
|
||
status: ratified
|
||
ratified: 2026-09-01 (Jason Woltje; PRD rev1 ratification PR)
|
||
---
|
||
|
||
# VIS.1 — Product north star
|
||
|
||
Successor text to rev0 Part I ([rev0 PRD](../2026-08-26_PRD_rev0/PRD.md) lines
|
||
33–215, preserved there verbatim). Base text unchanged except marked **rev1**
|
||
annotations; the decision registry moves to [[GOV.3-decision-map]].
|
||
|
||
|
||
### 1. What Mosaic Stack is (D1)
|
||
|
||
Mosaic Stack is an **open-source, AI-first platform for people who want a
|
||
self-hosted environment for agentic management and a life operating system.**
|
||
It serves personal, business, and employee needs from one deployment, and the
|
||
work is offered freely.
|
||
|
||
"AI-first" means agents are first-class operators of the system, not a bolted-on
|
||
chat box: the platform exists to let humans direct fleets of agents over their
|
||
projects, tasks, communications, and infrastructure, with the same tools and
|
||
the same guarantees whether a human or an agent is acting.
|
||
|
||
### 2. Who it is for (D1, D9)
|
||
|
||
The operator of a deployment is its user. Mosaic Stack is **not a hosted
|
||
business**: running the system as a service for external customers is outside
|
||
the north star. Multi-tenancy exists WITHIN a deployment so that one operator
|
||
can separate their world — for example, several LLCs plus a personal domain —
|
||
while every deployment is self-hosted by its own operator.
|
||
|
||
"Company" in the hierarchy is organizational separation for one operator's
|
||
world, not a customer account.
|
||
|
||
### 3. Deployment modes (D3)
|
||
|
||
Two modes, chosen at install time:
|
||
|
||
| | Standalone / personal | Enterprise |
|
||
| ------------------- | -------------------------------------- | ----------------------------------------------------- |
|
||
| Brains | one mosaic-brain (system + user files) | system brain for config + one brain per user |
|
||
| User-data isolation | single user | no user-data leakage between users; sharing is opt-in |
|
||
| Secrets | OpenBao/Vault or flat files | OpenBao/Vault REQUIRED |
|
||
| Conversion | Standalone → Enterprise, **one-way** | terminal state |
|
||
|
||
Brains are configurable as external git repositories (recommended, not
|
||
required); git tracking is always on locally.
|
||
|
||
**Federation** (connecting deployments: system-level config, assigned users,
|
||
rights and data-access control, trusts with boundaries, exfiltration
|
||
monitoring) is intentionally not fully designed. It is deferred, appears on the
|
||
roadmap as a placeholder phase per D11, and nothing in v1 may foreclose it.
|
||
*D3 as amended 2026-09-01 (Q-T1 ruling B):* federation milestones M1–M3
|
||
(Step-CA, enrollment, grants, mTLS auth guard, ScopeService, list/get/
|
||
capabilities verbs) are **shipped but frozen** — present in code behind the
|
||
`tier === 'federated'` gate, dormant since 2026-06-25, absent from the canonical
|
||
compose topology (D15), excluded from the v1 bar, tracked as a dormant
|
||
workstream in `docs/fleet/NORTH_STAR.yaml`, and gated on a security re-audit
|
||
before any resumption. See [[GOV.5-open-questions]] Q-T1.
|
||
|
||
### 4. Structure and tenancy (D2, D9, D13)
|
||
|
||
The hierarchy:
|
||
|
||
```
|
||
company/organization (N per deployment)
|
||
└─ estate (each in exactly one company)
|
||
└─ project (each in exactly one estate)
|
||
└─ workspace (project-specific; carries the Kanban)
|
||
```
|
||
|
||
Rules:
|
||
|
||
- Users can create N companies, N estates, N projects.
|
||
- Tasks bubble UP the hierarchy so whole-system status is visible at every
|
||
level. Bubble-up is **read-only aggregation**, never a cross-workspace write.
|
||
- Granular RBAC: admins restrict access per company, estate, and project;
|
||
grants are evaluated down the chain. Assets are transferable subject to the
|
||
structure.
|
||
- **`workspace_id` remains the hard mechanical isolation unit** exactly as
|
||
ratified in
|
||
[docs/requirements/native-kanban-sot.md](../../requirements/native-kanban-sot.md)
|
||
(#751): PostgreSQL sole writable SOT, cross-workspace relationships rejected,
|
||
fail-closed mutations. The hierarchy is parent structure ABOVE workspaces,
|
||
used for RBAC evaluation and read-only roll-ups. The kanban SOT carries this
|
||
as Amendment A1, added by reviewed PR — an amendment, not a rewrite (D13).
|
||
|
||
### 5. Identity (D10)
|
||
|
||
Built-in auth (better-auth) is the **account system of record**. Authentik and
|
||
other external IdPs federate in via OIDC as login methods; they never become
|
||
the system of record. Perimeter shims (forward-auth in front of a web host) are
|
||
deployment workarounds, not the design.
|
||
|
||
### 6. Onboarding (D4)
|
||
|
||
Onboarding is a **wizard that differs by mode, is re-runnable (no lock-in), and
|
||
is extensible** — new wizards attach as tabs.
|
||
|
||
Standalone flow captures: system and company name; component choices (Mosaic
|
||
Comms/Matrix vs external; Mosaic SSO/Authentik vs external; Mosaic
|
||
DB/PostgreSQL vs external; vector DB); the initial user
|
||
(email/password/name/SSO); comms setup (Matrix/Discord/Slack); agent enrollment
|
||
(harness choice and install, OAuth or API-key login, multi-account, model
|
||
choice with recommendation, agent name and persona, account assignment,
|
||
optional comms auto-enroll); a user onboarding profile (disabilities including
|
||
ADHD/autism/PDA/vision, professional background, education, desired agent
|
||
communication style, optional voice-matching interview, family/pets/friends/
|
||
hobbies/likes-dislikes); email and drive connectors (Gmail/IMAP, Google
|
||
Drive/OneDrive/Dropbox) with granular agentic-access consent; SSO/OIDC
|
||
configuration; an initial estate, an initial project, and seeded example data.
|
||
|
||
Enterprise uses the same skeleton with personal data optional; the focus moves
|
||
to business structure, org chart, RBAC, M365 and external systems, immediate
|
||
OIDC, SSO prominent.
|
||
|
||
Profile answers feed `USER.md` and/or the user's data store subject to the
|
||
custody rule in §7.
|
||
|
||
### 7. Data custody (D6, D14)
|
||
|
||
- **Sensitive profile categories** (disabilities, family, communication style,
|
||
and similar) live in the **user's own brain ONLY**. PostgreSQL holds
|
||
structural data, consent records, and pointers — never the content. "User
|
||
data does not leak" is enforced by architecture, not policy (D14).
|
||
- Standalone (one user, one brain) **may** keep the same split — D14 makes it
|
||
optional in Standalone, not required. Keeping it is the recommended default
|
||
because it preserves forward-compatibility with the one-way Enterprise
|
||
conversion (D3).
|
||
- Estate brains hold operational records. Only product-relevant material
|
||
migrates into this repository's docs; operational records stay in their
|
||
brains and are linked (D6).
|
||
|
||
### 8. Architecture gate — the webUI sits OVER official tooling (D8, D12)
|
||
|
||
**HARD RULE:** every webUI operation goes through the Gateway API backed by the
|
||
same official framework tooling the CLI uses. The CLI remains the primary
|
||
execution method; the webUI uses the tools to operate and configure the
|
||
system. The webUI never bypasses tooling to reach the database or filesystem
|
||
directly.
|
||
|
||
Consequence for planning: when a desired webUI operation has no backing tool,
|
||
the gap is scored **"blocked on tooling"** and the tool is built first. The
|
||
product baseline therefore always includes all three D8 inputs: the tool
|
||
inventory (what exists and what is missing), the webUI→tool mapping, and the
|
||
measured current state of the `next` branch.
|
||
|
||
### 9. v1 slice (D11)
|
||
|
||
v1 is deliberately small:
|
||
|
||
1. **Standalone onboarding wizard** — system/company name, component choices,
|
||
initial user, initial estate + project, seeded examples, re-runnable.
|
||
2. **Hierarchy core** — company → estate → project → workspace → kanban, with
|
||
read-only task bubble-up.
|
||
3. **Basic RBAC** on the hierarchy.
|
||
4. **Minimal agent enrollment** — one harness, API key, name/persona.
|
||
|
||
Deferred beyond v1: connectors, comms integrations, voice-matching, M365,
|
||
Enterprise conversion, federation. Every deferred item appears in
|
||
[docs/ROADMAP.md](../../ROADMAP.md) per the D11 rule: nothing exists only in heads.
|
||
|
||
### 10. Relationship to the fleet north star
|
||
|
||
[docs/fleet/NORTH_STAR.md](../../fleet/NORTH_STAR.md) (generated from
|
||
`docs/fleet/NORTH_STAR.yaml`) is the **delivery-fleet** north star: how the
|
||
agent fleet that builds and operates the system should run (NS-1..NS-10,
|
||
workstreams A–L). This PRD is the **product** north star. They are not
|
||
competitors: the fleet north star is subordinate product-wise — its workstream
|
||
J ("Web control plane") is one consumer of this PRD's D8/D12 gate — and this
|
||
PRD does not redefine fleet invariants. The subordination rule is ratified in
|
||
the frozen audit-input baseline (T2 operator freeze, 2026-08-25: "the PRD must
|
||
cite and subordinate it, never fork it"). A change that would put the two in
|
||
conflict must amend one of them explicitly, never fork a third document
|
||
(drafting addition — see §12.1).
|
||
|
||
### 11. Explicit non-goals
|
||
|
||
- Hosted/SaaS operation for external customers (D9).
|
||
- A webUI that writes to the database or filesystem around the tooling (D12).
|
||
- A second writable task store beside PostgreSQL (native-kanban-sot invariants).
|
||
- Fully-designed federation in v1 (D3 — roadmap placeholder only; the shipped M1–M3 code is frozen, not a v1 feature).
|
||
|
||
### D15 — Tiered containerized deployment (2026-08-30, containerization lane)
|
||
|
||
The stack ships a tiered deployment target, additive to the architecture
|
||
gate (D8): (1) Standalone tier — docker compose is the canonical
|
||
single-host deployment: postgres, valkey, openbao, gateway, appservice
|
||
and the served webUI in one composition, with migrations, health checks,
|
||
and a documented install/upgrade path; the registry (CI-published
|
||
images) is the only deployment source. (2) Enterprise tier — Kubernetes
|
||
manifests for the same service set, phase-gated on the standalone tier
|
||
holding its acceptance bar. The v1 acceptance bar for the standalone
|
||
tier: compose-up healthy; webUI hosts agent chat; an in-stack agent can
|
||
open a PR to this repo; CI validates it; the running deployment adopts
|
||
the merged change (pull + restart). Federation (D3 clause) remains
|
||
deferred and unforeclosed. Implementation plan:
|
||
docs/plans/2026-08-30_containerization.md.
|
||
|
||
|
||
---
|
||
|
||
## rev1 annotations (2026-08-31)
|
||
|
||
- §8's architecture gate (webUI over official tooling, CLI primary) is
|
||
elaborated for the control plane by [[UI.1-webui-surfaces]] and
|
||
[[CLI.1-parity]]; register decision OD-53 confirms all interfaces share one
|
||
CLI-backed engine.
|
||
- §4's RBAC and §5's identity are joined by the **agent-side** authority model
|
||
in [[AUTHZ.1-capability-authority]]: role capability ceilings enforced at the
|
||
harness by `mosaic-core`, composed by pure intersection.
|
||
- The fleet north star subordination (§10) gains a control-plane consequence:
|
||
the WebUI workstream consumes this PRD's surface specifications
|
||
([[UI.1-webui-surfaces]]) rather than defining its own.
|