jason.woltje
13968e9a8b
ci/woodpecker/pr/ci Pipeline failed
Addresses CPS-PRD-REV1-REVIEW-Q90 findings F1 and F3 on PR #1491: F1 (format gate): `prettier --write` on the 18 rev1 bundle documents. Whitespace, table padding, list markers and emphasis delimiters only — a normalized token comparison of every file before/after shows zero content difference, so the ratified text is unchanged and no re-ratification applies. F3 (rev0 relative links): the archived rev0 PRD stays byte-identical (sha256 60cc2f98...36afdf verified) per GOV.1 archive-never-edit. A sibling docs/PRDs/2026-08-26_PRD_rev0/README.md records the digest, the original location, the owner disposition that the in-file links are intentionally historical, and a resolution table for all 9 targets (11 occurrences), each verified to exist. Future relocated archives ship the same README instead of edited bytes. F2 (test step) is investigated separately against the CI log.
215 lines
11 KiB
Markdown
215 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.
|