mosaicstack/stack
21
0
Fork 1
Code Issues 336 Pull Requests 14 Actions Packages Projects Releases 15 Wiki Activity

docs: PRD rev1 review Q90 — Prettier-format the bundle, add rev0 archive README
ci/woodpecker/pr/ci Pipeline failed
Details

Browse Source 
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.
This commit is contained in:
jason.woltje
2026-09-02 09:40:46 -05:00
parent ad21ad7ac5
commit 13968e9a8b
19 changed files with 279 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PRDs/2026-08-26_PRD_rev0/README.md
+35
View File
@@ -0,0 +1,35 @@
---
kind: record
status: superseded
---
# PRD rev0 — archive record
`PRD.md` in this directory is the 2026-08-26 North Star PRD, archived **verbatim** at
ratification of rev1 (2026-09-01). It is byte-identical to `origin/next:docs/PRD.md` at
commit `9aa4983c` (SHA-256
`60cc2f98697471850caa3440d79139d70f67eda585a2ee465fdcd517bc36afdf`). Per GOV.1 the archived
bytes are never edited — not even to repair links — so the digest stays verifiable.
**Its relative links were written for `docs/PRD.md` and do not resolve from this directory.**
That is an accepted, intentional consequence of archive-never-edit (owner disposition: the
control-plane-surfaces lane, 2026-09-02, review `CPS-PRD-REV1-REVIEW-Q90` F3). Resolve them
with this table; every target still exists in the tree.
| Link text in `PRD.md` (lines) | Resolves to |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `./archive/PRD-v0.1.md` (17) | [../../archive/PRD-v0.1.md](../../archive/PRD-v0.1.md) |
| `./ROADMAP.md` (18) | [../../ROADMAP.md](../../ROADMAP.md) |
| `./requirements/native-kanban-sot.md` (98) | [../../requirements/native-kanban-sot.md](../../requirements/native-kanban-sot.md) |
| `./fleet/NORTH_STAR.md` (181) | [../../fleet/NORTH_STAR.md](../../fleet/NORTH_STAR.md) |
| `./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md` (444) | [../../fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](../../fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) |
| `./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` (444) | [../../fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](../../fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) |
| `./TASKS.md` (462) | [../../TASKS.md](../../TASKS.md) |
| `./native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` (623) | [../../native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md](../../native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md) |
| `./requirements/cli-capability-migration.md` (906) | [../../requirements/cli-capability-migration.md](../../requirements/cli-capability-migration.md) |
Rule for future archives (recorded here; GOV.1 carries the general archive contract): every
`docs/PRDs/<date>_PRD_revN/` archived from a different original location ships a `README.md`
like this one — digest, original path, and a link-resolution table — instead of edited bytes.
Current revision: see [`docs/PRD.md`](../../PRD.md).
docs/PRDs/2026-08-31_PRD_rev1/AUTHN.1-auth-accounts.md
+7 -6
View File
@@ -12,13 +12,13 @@ is out of this section's scope.)
## Authentication configuration surface (WebUI page + CLI)
| Control | Notes |
|---|---|
| Control | Notes |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| in-browser OAuth establishment | the OAuth flow runs in-browser; whether the backing terminal flow is tmux-bridged is open: [[GOV.5-open-questions]] Q-N1 |
| configured accounts list | provider, mode (OAuth/API), status, holder |
| force renew | |
| deactivate | deactivated accounts drop out of every seat/harness selector |
| allowed harnesses | which harnesses may use this account |
| configured accounts list | provider, mode (OAuth/API), status, holder |
| force renew | |
| deactivate | deactivated accounts drop out of every seat/harness selector |
| allowed harnesses | which harnesses may use this account |
## Custody rules
@@ -31,6 +31,7 @@ is out of this section's scope.)
multi-account enrollment).
- Account shape in the seat record (single account vs per-provider map) is
open: [[GOV.5-open-questions]] Q-D2.
## Credential-broker custody rules (pulled 2026-08-31, generalized from the vault draft)
- Reads require a token scoped to the needed paths; provisioning and writes go
docs/PRDs/2026-08-31_PRD_rev1/AUTHZ.1-capability-authority.md
+17 -16
View File
@@ -13,7 +13,7 @@ L2 authorization contracts, `mosaic-core` (measured 2026-08-31), and the lane's
## Glossary
**Privilege escapation** *(Jason, 2026-08-31)* — the outcome class in which an
**Privilege escapation** _(Jason, 2026-08-31)_ — the outcome class in which an
agent exercises authority it was never granted, regardless of mechanism.
Deliberately collapses escalation and misdirection: the outcome is identical;
the distinction matters only when choosing a control.
@@ -60,7 +60,7 @@ canary phase (gap G7 — by design for now; L2-D21 is the end state).
capability-adding edge.
**Accepted within reason: misdirection.** A rogue or colluding orchestrator can
still *route work* to a seat that already legitimately holds a capability. The
still _route work_ to a seat that already legitimately holds a capability. The
authority is genuine, so no structural control can refuse it. Jason's ruling:
escalation and misdirection are tiered **by outcome — identically**; locking
down far enough to mechanically prevent misdirection cripples the system to
@@ -71,11 +71,11 @@ see the audit surface in [[UI.1-webui-surfaces]] and gap G3 below.
Design intent (not yet enforced by any manifest — gap C3 in the lane ledger):
| Role | Must NOT |
|---|---|
| coding agent | create remote git repositories |
| gate agent | code |
| review agent | code |
| Role | Must NOT |
| -------------- | -------------------------------- |
| coding agent | create remote git repositories |
| gate agent | code |
| review agent | code |
| interact agent | code, create remote repositories |
Breaking the monopoly means no single seat holds an exit path; escape requires
@@ -85,20 +85,21 @@ role taxonomy this matrix projects onto.
## Gap register (measured 2026-08-31)
| ID | Gap | Status |
|---|---|---|
| G1 | No least-privilege language anywhere in L1/L2/NORTH-STAR (grep-verified) | **L2-D52 amendment drafted** |
| G2 | Assignment issuance criteria unspecified (renewal names criteria; issuance does not) — full-ceiling requests validate cleanly | **L2-D52 amendment drafted** |
| G3 | No misdirection audit exists — no tooling, agent, or surface | open → [[UI.1-webui-surfaces]] §Audit |
| G4 | Coordinator-as-seat would collapse the model | firewall — never violate |
| G5 | Seat config mixes authority classes (role binding beside a model dropdown) | open → [[SEAT.1-seat-profile]] |
| G6 | `role-harness-config/DESIGN.md` scope defect (unstated surface) | fix drafted (amendment in `proposed/docs/`) |
| G7 | Capability map closed/hardcoded | by design (canary phase) |
| ID | Gap | Status |
| --- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| G1 | No least-privilege language anywhere in L1/L2/NORTH-STAR (grep-verified) | **L2-D52 amendment drafted** |
| G2 | Assignment issuance criteria unspecified (renewal names criteria; issuance does not) — full-ceiling requests validate cleanly | **L2-D52 amendment drafted** |
| G3 | No misdirection audit exists — no tooling, agent, or surface | open → [[UI.1-webui-surfaces]] §Audit |
| G4 | Coordinator-as-seat would collapse the model | firewall — never violate |
| G5 | Seat config mixes authority classes (role binding beside a model dropdown) | open → [[SEAT.1-seat-profile]] |
| G6 | `role-harness-config/DESIGN.md` scope defect (unstated surface) | fix drafted (amendment in `proposed/docs/`) |
| G7 | Capability map closed/hardcoded | by design (canary phase) |
Amendments staged in `proposed/docs/` per the lane convention; ledger items
A3/A4 track ratification. The auditor-identity question (an auditor agent is
itself a seat, itself subject to misdirection) is on the grill:
[[GOV.5-open-questions]] Q-A1.
## E2 inputs (triage 2026-08-31; see [[GOV.2-docs-inventory]])
**Canonical ground truth**: `DEVELOPER-GUIDE/architecture/mutator-class-gate.md`
docs/PRDs/2026-08-31_PRD_rev1/CLI.1-parity.md
+22 -21
View File
@@ -44,15 +44,15 @@ launchers dispatch to bash tools under `packages/mosaic/framework/tools/`
Control-plane-relevant families, by rev1 domain:
| Domain | Families (measured) |
|---|---|
| SEAT | `fleet` (init/install/systemd/lifecycle/roster/add/remove/verify/ps), `fleet` roster-v2 CRUD (`get/plan/create/update/delete`), `fleet apply`/`reconcile`/`doctor`/`regen`, `fleet provision`, `fleet migrate-v1 preview`, `agent` (configs + enroll + nested fleet-agent commands), `promote`, `comms send` |
| ROLE | `fleet persona` (`list/show/customize` — baseline ⊕ `roles.local/` overrides), `fleet profile` (`list/show` topology templates) |
| HARN | `config` (framework config + hooks), `compose-contract <harness>`, `skill`, `seq`, `init`/`sync`/`bootstrap`, `doctor`, runtime launchers (`claude`/`codex`/`opencode`/`pi`, experimental `claudex`, `yolo`) |
| PROV | `gateway config` (raw provider API-key env vars only), `wizard` (setup-time provider config) |
| AUTHN | `login`, `auth users {list,create,delete}`, `auth sso {list,test}` (stubbed — see gaps), `auth sessions list` (stubbed), `gateway` token lifecycle (`config rotate-token/recover-token`) |
| SESS | `tui`, `sessions {list,resume,destroy}`, `interaction` (durable-session surface: enroll/attach/send/chat/stop/recover), `coord`, `watch`, `mission` |
| Governance/other | `prdy {init,update,validate,status}`, `federation {grant,peer}`, `macp tasks gate`, `telemetry`, `upgrade`/`update`/`restore`/`uninstall`, `q`, sibling-package families |
| Domain | Families (measured) |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SEAT | `fleet` (init/install/systemd/lifecycle/roster/add/remove/verify/ps), `fleet` roster-v2 CRUD (`get/plan/create/update/delete`), `fleet apply`/`reconcile`/`doctor`/`regen`, `fleet provision`, `fleet migrate-v1 preview`, `agent` (configs + enroll + nested fleet-agent commands), `promote`, `comms send` |
| ROLE | `fleet persona` (`list/show/customize` — baseline ⊕ `roles.local/` overrides), `fleet profile` (`list/show` topology templates) |
| HARN | `config` (framework config + hooks), `compose-contract <harness>`, `skill`, `seq`, `init`/`sync`/`bootstrap`, `doctor`, runtime launchers (`claude`/`codex`/`opencode`/`pi`, experimental `claudex`, `yolo`) |
| PROV | `gateway config` (raw provider API-key env vars only), `wizard` (setup-time provider config) |
| AUTHN | `login`, `auth users {list,create,delete}`, `auth sso {list,test}` (stubbed — see gaps), `auth sessions list` (stubbed), `gateway` token lifecycle (`config rotate-token/recover-token`) |
| SESS | `tui`, `sessions {list,resume,destroy}`, `interaction` (durable-session surface: enroll/attach/send/chat/stop/recover), `coord`, `watch`, `mission` |
| Governance/other | `prdy {init,update,validate,status}`, `federation {grant,peer}`, `macp tasks gate`, `telemetry`, `upgrade`/`update`/`restore`/`uninstall`, `q`, sibling-package families |
Notable structural facts: there is **no top-level `mosaic role` verb** — role
management lives at `fleet persona`, three levels deep; and `doctor`/`status`
@@ -63,17 +63,17 @@ exist twice (top-level framework-scoped vs `fleet`-scoped), shadowing by name.
Rows are the [[UI.1-webui-surfaces]] page domains; measured against
`apps/web/src/spa/pages/` and the gateway controllers on the same commit.
| Surface function | WebUI today | CLI today | Parity state |
|---|---|---|---|
| Seat lifecycle & roster (SEAT) | **no Seats page** (routes are only /admin, /settings, /projects, /tasks, /chat) | complete (`fleet`/`agent` families) | CLI-ahead — page is D2's work, tooling exists |
| Role/persona config (ROLE) | no page | `fleet persona` | CLI-ahead; naming mismatch: no `mosaic role` verb for the ROLE page to mirror |
| User role/ban (AUTHN) | admin UsersTab toggles role/ban via admin endpoints directly | `auth users` lacks `set-role`/`ban`/`unban` | **WebUI-only mutation — violates the D12 rule as implemented** |
| SSO admin (AUTHN) | SsoProviderSection reads *public* `/api/sso/providers` discovery | `auth sso list/test` stubbed: "admin endpoint missing" | **blocked on gateway tooling**; CLI and WebUI don't even hit the same surface |
| Auth-session admin (AUTHN) | — | `auth sessions list` stubbed (no server endpoint) | blocked on gateway tooling |
| Provider list/test (PROV) | settings ProvidersTab: `GET /api/providers`, `POST /api/providers/test` | none — only `gateway config` raw env-var writes | **WebUI-only read/test — no `mosaic provider` family exists** |
| Default harness/provider/model selection (HARN/SESS) | `GET/PUT /api/chat/preferences/selection` per user | none persists the stored preference (`tui --model` is per-session only) | WebUI-only mutation |
| Authorization hierarchy & grants (UI-audit) | **no page** | **no command** | **the largest D12 gap**: `hierarchy.controller.ts` exposes full CRUD (companies, estates, platform-projects, grants incl. `grants/:id/change`) with audit repository and grant evaluation behind it — reachable only by raw API |
| Federation grants/peers | no page | `federation grant/peer` | CLI-ahead (posture pending Q-T1) |
| Surface function | WebUI today | CLI today | Parity state |
| ---------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Seat lifecycle & roster (SEAT) | **no Seats page** (routes are only /admin, /settings, /projects, /tasks, /chat) | complete (`fleet`/`agent` families) | CLI-ahead — page is D2's work, tooling exists |
| Role/persona config (ROLE) | no page | `fleet persona` | CLI-ahead; naming mismatch: no `mosaic role` verb for the ROLE page to mirror |
| User role/ban (AUTHN) | admin UsersTab toggles role/ban via admin endpoints directly | `auth users` lacks `set-role`/`ban`/`unban` | **WebUI-only mutation — violates the D12 rule as implemented** |
| SSO admin (AUTHN) | SsoProviderSection reads _public_ `/api/sso/providers` discovery | `auth sso list/test` stubbed: "admin endpoint missing" | **blocked on gateway tooling**; CLI and WebUI don't even hit the same surface |
| Auth-session admin (AUTHN) | — | `auth sessions list` stubbed (no server endpoint) | blocked on gateway tooling |
| Provider list/test (PROV) | settings ProvidersTab: `GET /api/providers`, `POST /api/providers/test` | none — only `gateway config` raw env-var writes | **WebUI-only read/test — no `mosaic provider` family exists** |
| Default harness/provider/model selection (HARN/SESS) | `GET/PUT /api/chat/preferences/selection` per user | none persists the stored preference (`tui --model` is per-session only) | WebUI-only mutation |
| Authorization hierarchy & grants (UI-audit) | **no page** | **no command** | **the largest D12 gap**: `hierarchy.controller.ts` exposes full CRUD (companies, estates, platform-projects, grants incl. `grants/:id/change`) with audit repository and grant evaluation behind it — reachable only by raw API |
| Federation grants/peers | no page | `federation grant/peer` | CLI-ahead (posture pending Q-T1) |
**Consequences for the build order** (D8: tool first, then surface):
`mosaic provider {list,test}`, `auth users {set-role,ban,unban}`, a stored
@@ -92,6 +92,7 @@ boundary — register OD-09), `mosaic prdy` (PRD creation/acceptance — registe
OD-22), role management (one canonical API, L2-D14), seat lifecycle
(launch/relaunch per register OD-59), `mosaic doctor` (drift detection classes,
e.g. the #1194 framework-tool drift addendum in [[GOV.4-workstream-contracts]]).
## `mosaic config` v1 subset (pulled 2026-08-31 from the minimal-subset spec)
The Q14 ruling (2026-08-29) fixes the current scope: shipped surface
@@ -145,7 +146,7 @@ Full extraction record: lane `S2-EXTRACTION-2026-08-31.md` (per-contract cores,
counterpart (A5 rank 5) — the taxonomy precedent for read-only surfaces in
the parity matrix.
- **Mandated removals** the CLI inventory must track: `mosaic auth users
delete` (with the hard-delete endpoint) is required to be disabled/removed
delete` (with the hard-delete endpoint) is required to be disabled/removed
by contract 4.
## Parity freshness ruling (Q-C1, Jason 2026-09-01)
docs/PRDs/2026-08-31_PRD_rev1/DATA.1-record-authority.md
+34 -32
View File
@@ -18,17 +18,17 @@ Merges J1 (2026-08-23), operator register OD-13/OD-48/OD-49–OD-52, and the lan
## Authority table
| Record | Authority | Rationale |
|---|---|---|
| Role Definition / Role Revision | **Git** | reviewed governance; revisions immutable and digested |
| `mosaic-core.manifest.json` | **Git** | committed, non-symlink, trusted-path — the loader refuses anything else |
| PRD revision bundles (`docs/PRDs/`) | **Git** | immutable accepted versions (register OD-17) |
| Portable config blueprint | **Git** (`fleet/configuration/installation.yaml`, register OD-50) | declarative desired state |
| Host bindings | ignored `config/installation.local.yaml` (OD-50) | host-local, never authority over roles/gates (OD-52) |
| Role Binding (seat → revision) | **Postgres** | runtime state; control-plane mutable |
| Seat record (harness, model, workdir, auth account) | **Postgres**, projected to flat files | runtime state |
| Leases, checkpoints, session/incarnation state | **Postgres** / coordinator (register OD-57–OD-60) | runtime state with fencing |
| `settings.json`, `launch.env` | **generated projection** | L2-D19; no writer may treat them as source |
| Record | Authority | Rationale |
| --------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Role Definition / Role Revision | **Git** | reviewed governance; revisions immutable and digested |
| `mosaic-core.manifest.json` | **Git** | committed, non-symlink, trusted-path — the loader refuses anything else |
| PRD revision bundles (`docs/PRDs/`) | **Git** | immutable accepted versions (register OD-17) |
| Portable config blueprint | **Git** (`fleet/configuration/installation.yaml`, register OD-50) | declarative desired state |
| Host bindings | ignored `config/installation.local.yaml` (OD-50) | host-local, never authority over roles/gates (OD-52) |
| Role Binding (seat → revision) | **Postgres** | runtime state; control-plane mutable |
| Seat record (harness, model, workdir, auth account) | **Postgres**, projected to flat files | runtime state |
| Leases, checkpoints, session/incarnation state | **Postgres** / coordinator (register OD-57–OD-60) | runtime state with fencing |
| `settings.json`, `launch.env` | **generated projection** | L2-D19; no writer may treat them as source |
Transition rule: the WebUI may edit flat files during the transition, but the
end state is exactly the table above — every flat file regenerated from Git or
@@ -38,12 +38,12 @@ Postgres, never authored directly.
Current flat-file state (measured 2026-08-31):
| File | Carries |
|---|---|
| `fleet/agents/<seat>/launch.env` | model, workdir, reasoning level (hand-maintained, git-ignored) |
| `fleet/agents/<seat>/profile.json` | role — read by `mosaic-core`'s trusted-path loader |
| `fleet/roles/<role>/.pi/agent/settings.json` | provider, model, extensions, skills paths |
| `fleet/roles/<role>/mosaic-core.manifest.json` | capability/tool authority (schema v3) |
| File | Carries |
| ---------------------------------------------- | -------------------------------------------------------------- |
| `fleet/agents/<seat>/launch.env` | model, workdir, reasoning level (hand-maintained, git-ignored) |
| `fleet/agents/<seat>/profile.json` | role — read by `mosaic-core`'s trusted-path loader |
| `fleet/roles/<role>/.pi/agent/settings.json` | provider, model, extensions, skills paths |
| `fleet/roles/<role>/mosaic-core.manifest.json` | capability/tool authority (schema v3) |
Proposal: one `profile.json` rules seat information (role, harness, model,
reasoning, workdir, overlay, authentication account); `launch.sh` reads it
@@ -80,16 +80,17 @@ reconciliation and attestation.
`MOSAIC_SEAT_HOME=1` while the `MOSAIC_SEAT_CONFIG=1` seed fires on `! -s`,
which the symlink satisfies). Settle ownership before the WebUI becomes a third
writer. Grill: [[GOV.5-open-questions]] Q-D3.
## Configuration file authority (pulled 2026-08-31 from the mosaic-config v1 spec)
Four config records with fixed authority (brain spec `2026-08-29_mosaic-config-minimal-subset.md`, register OD-49–OD-55):
| Record | Path | Authority |
|---|---|---|
| Central registry | `~/.config/mosaic/config.json` | resolves brainHome/socket/paths |
| Portable blueprint | `<brainHome>/fleet/configuration/installation.yaml` | tracked, secret-free desired state |
| Host bindings | `<brainHome>/config/installation.local.yaml` | git-ignored; **runtime and working directory only** |
| Packaged presets | immutable, versioned (`bootstrap-minimal@1`) | never `latest` |
| Record | Path | Authority |
| ------------------ | --------------------------------------------------- | --------------------------------------------------- |
| Central registry | `~/.config/mosaic/config.json` | resolves brainHome/socket/paths |
| Portable blueprint | `<brainHome>/fleet/configuration/installation.yaml` | tracked, secret-free desired state |
| Host bindings | `<brainHome>/config/installation.local.yaml` | git-ignored; **runtime and working directory only** |
| Packaged presets | immutable, versioned (`bootstrap-minimal@1`) | never `latest` |
Precedence, high to low: constitution/safety (deny-wins, OD-51) → framework
schema/profile/role/roster contracts → blueprint/preset → host bindings →
@@ -100,7 +101,7 @@ reviews, gates, or safety (OD-52) — the data-model enforcement of the
**valid** (structurally sound) from **conformant** (observed == desired) with
distinct exit codes.
*Triage note:* the intended-state reconciler spec was judged **operator
_Triage note:_ the intended-state reconciler spec was judged **operator
host-ops tooling** on full read (systemd/tmux monitoring of the operator
estate) — not product scope; its conformance idea is already covered by the
validate/plan model above. E2-inputs pull downgraded to SKIP.
@@ -109,12 +110,13 @@ validate/plan model above. E2-inputs pull downgraded to SKIP.
**Canonical ground truth**: `requirements/native-kanban-sot.md` (ratified, the
D13 base), `native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` + `KBN-101-ENVELOPE-A.md`
+ `SHARED-CONTRACT.md` (frozen contracts), `ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md`
(PGlite tier support boundary), `fleet/reference/roster-v2-fields.md`.
**Pending pulls**: DRAFT S2 contracts `hierarchy-schema.md`, `custody-schema.md`,
`rollup-projection.md`, `mode-conversion.md` (**predates D15 — reconcile first**,
Q-T4); brain `docs/specs/2026-08-28_intended-state-reconciler.md` (reconciler spec).
**Conflicts on the grill**: deployment/federation posture, Q-T1.
- `SHARED-CONTRACT.md` (frozen contracts), `ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md`
(PGlite tier support boundary), `fleet/reference/roster-v2-fields.md`.
**Pending pulls**: DRAFT S2 contracts `hierarchy-schema.md`, `custody-schema.md`,
`rollup-projection.md`, `mode-conversion.md` (**predates D15 — reconcile first**,
Q-T4); brain `docs/specs/2026-08-28_intended-state-reconciler.md` (reconciler spec).
**Conflicts on the grill**: deployment/federation posture, Q-T1.
## S2 contract feed (extraction 2026-08-31)
@@ -133,13 +135,13 @@ Full extraction record: lane `S2-EXTRACTION-2026-08-31.md` (per-contract cores,
statement — non-authoritative, recomputable, never gates work, enforced by
read-only DB transactions (mechanical, not conventional). Direct precedent
for this section's record-authority chain.
- **Route metadata records (contract 9)**: metadata as *registration input* —
- **Route metadata records (contract 9)**: metadata as _registration input_ —
auth guard derived from the record makes record-vs-code divergence on those
fields structurally impossible; generated OPENAPI.yaml is committed and
PR-reviewed yet strictly non-authoritative ("generation documents the code;
it does not ratify it") — drafting precedent: "generated" ≠ "uncommitted".
- **Authoritative DB settings rows** — ruled (Q-T5, Jason 2026-09-01):
generated settings *files* are projections of the active Role Revision,
generated settings _files_ are projections of the active Role Revision,
never authority (L2-D19); DB settings records written through audited
Gateway commands (`platform_mode`, `registration_mode`, `custody_config`,
`bootstrap.seed-company-name`, and successors) are records of authority
docs/PRDs/2026-08-31_PRD_rev1/GOV.1-prd-lifecycle.md
+1
View File
@@ -73,6 +73,7 @@ is a separate, future decision.
Related: [[PRD.0-index]] for naming and ordering; the lane `proposed/README.md`
for draft-stage conventions.
## Registry mechanics (pulled 2026-08-31 from the prd-registry draft)
The operator draft `operations/prd-registry.md` independently specifies the
docs/PRDs/2026-08-31_PRD_rev1/GOV.2-docs-inventory.md
+28 -27
View File
@@ -18,12 +18,12 @@ Full per-file verdict tables live in the lane evidence record
## Corpora
| # | Corpus | Files | Scanned at |
|---|--------|-------|-----------|
| 1 | `mosaicstack/stack` `origin/next:docs/` | 346 | commit `9aa4983c`, triaged 2026-08-31 (141 live files per-file; archive dirs swept for orphaned decisions) |
| 2 | `~/.mosaic/docs/` (excl. guides/proposed) | ~76 | triaged 2026-08-31 |
| 3 | `~/.mosaic/docs/guides/proposed/` | 79 | triaged 2026-08-31 |
| 4 | `fleet/lanes/agent-runtime-ng/` + `fleet/lanes/control-plane-surfaces/` | — | live lanes, canonical by definition for their scope |
| # | Corpus | Files | Scanned at |
| --- | ----------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `mosaicstack/stack` `origin/next:docs/` | 346 | commit `9aa4983c`, triaged 2026-08-31 (141 live files per-file; archive dirs swept for orphaned decisions) |
| 2 | `~/.mosaic/docs/` (excl. guides/proposed) | ~76 | triaged 2026-08-31 |
| 3 | `~/.mosaic/docs/guides/proposed/` | 79 | triaged 2026-08-31 |
| 4 | `fleet/lanes/agent-runtime-ng/` + `fleet/lanes/control-plane-surfaces/` | — | live lanes, canonical by definition for their scope |
## Corpus 1 — stack `origin/next:docs/` — conclusions
@@ -57,12 +57,12 @@ Q-T5 — projection-rule scope vs authoritative DB settings records).
**Conflicts requiring a ruling** (all carried in [[GOV.5-open-questions]] Q-T1):
| Document | Conflict |
|---|---|
| root `MISSION-MANIFEST.md` (2026-07-14) | makes federated-tier the "canonical MVP deployment topology", Federation v1 top-priority — vs D3 (deferred) and D15 (compose standalone canonical) |
| `federation/MISSION-MANIFEST.md` (2026-04-21) | Federation v1 as active in-progress M3 — vs D3 and ROADMAP P5 "deliberately undesigned" |
| `guides/deployment.md` | blocks Compose activation pending KBN-101 gates — vs D15's `docker compose up` v1 bar |
| `scratchpads/mvp-20260312.md` | records a *completed* Federation M2 milestone (peer certs, grants, ScopeService, Step-CA) — vs D3's "deferred" framing |
| Document | Conflict |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| root `MISSION-MANIFEST.md` (2026-07-14) | makes federated-tier the "canonical MVP deployment topology", Federation v1 top-priority — vs D3 (deferred) and D15 (compose standalone canonical) |
| `federation/MISSION-MANIFEST.md` (2026-04-21) | Federation v1 as active in-progress M3 — vs D3 and ROADMAP P5 "deliberately undesigned" |
| `guides/deployment.md` | blocks Compose activation pending KBN-101 gates — vs D15's `docker compose up` v1 bar |
| `scratchpads/mvp-20260312.md` | records a _completed_ Federation M2 milestone (peer certs, grants, ScopeService, Step-CA) — vs D3's "deferred" framing |
Code reality, verified 2026-08-31 at `9aa4983c` (dossier: lane
`FEDERATION-DOSSIER-2026-08-31.md`): federation M1–M3 are shipped and wired
@@ -83,6 +83,7 @@ consistent with their own README disclaimers.
**Orphaned decisions found in the archive sweep** (ratified once, absent from
D1–D15 and every live doc; disposition on the grill, Q-T2):
1. "No Python" monorepo ruling (`archive/planning/monorepo-consolidation/board-review.md:742`).
2. Matrix/MACP "exactly three supported modes" install-topology ruling, Mode A
split-domain primary; its DNS/domain prerequisite ruling still open
@@ -132,19 +133,19 @@ contracts, never the reverse.
## Naming defects register (mandate item 4)
| # | Defect | Fix proposed |
|---|--------|--------------|
| N1 | `~/.mosaic/docs/PRD.md` is the pi goal-extension PRD wearing the project-PRD name (confirmed 2026-08-31) | rename to a goal-extension-scoped name during return |
| N2 | Stack local `main` is a divergent unpushed fork that shadows `next` | already a lane convention; PRD states trunk identity explicitly |
| N3 | Pre-2026-08-26 pattern: `docs/PRD.md` overwritten per milestone | retired by [[GOV.1-prd-lifecycle]] shim model |
| N4 | Two decision registries share the D-prefix ID space (stack D1–D15 vs operator D01–D65); "D8" is ambiguous without registry name | OD- prefix applied in rev1 (Q-G2 ruled 2026-09-01); collision rule in [[GOV.3-decision-map]] |
| N5 | Triple "PRD" collision in the stack tree: root `PRD.md` vs superseded `fleet/PRD.md` and `fleet/PRD-fleet-suite.md`, with no local supersession signal on the latter two | supersession banner in-file; long-term, the GOV.1 rule that the bare name `PRD.md` is reserved for the shim |
| N6 | "Tess" and "Ultron" each name two different things: non-authoritative roster-class display aliases (fleet how-tos) vs the named product agent / validator identity (TESS workstream, native-kanban-sot) | rev1 text always qualifies which sense is meant; flag for upstream rename of the aliases |
| N7 | Six stack `TASKS.md` files under three authority regimes (banner-superseded / explicitly-not-superseded / silently active) — the filename signals nothing | uniform status frontmatter on every TASKS.md; superseded ones point at NORTH_STAR.yaml |
| N8 | Duplicate basenames across stack dirs: `gateway-security-20260313.md` (qa vs code-review, different content), `2026-08-10-docs-catalog-audit.md` (plan vs report), `1099-pipefail-sweep.md` (report vs scratchpad copy) | disambiguate on next touch; prune the unpromoted scratchpad copy |
| N9 | `guides/` is outside the canonical tree per `docs/README.md` yet "protected current authority" per `SITEMAP.md` — contract and sitemap disagree | reconcile the documentation contract; likely fold the four guides into the guide trees |
| N10 | Two live front-matter schemas (`type`/`status: current…` per docs/README.md vs the newer `kind`/`status: active…` used by most files) — collision documented in the w4 worklist, unresolved | settle the schema in the documentation contract as part of E6 return |
| N11 | Three uncross-referenced descriptions of the `/goal` capability: brain `docs/PRD.md`, `operations/goals.md`, and GOV.4 §#1150 | reconcile under the #1150 identity; brain docs cite it |
| N12 | Brain-side: `MOSAIC-CANON.md` vs `STRUCTURE-CANON.md` both claim canon status | operator ruling (Q-T3); retire or fold the unreferenced copy |
| N13 | Forward-looking: rev0 Part II (RI-N3) rules `docs/PRD.md` "not a peer authority" once `docs/prdy/` lands — a third contender in "which PRD is real" | GOV.1 disambiguation: prdy is tooling-facing storage; the shim + bundle remain the human-facing SOT chain |
| # | Defect | Fix proposed |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| N1 | `~/.mosaic/docs/PRD.md` is the pi goal-extension PRD wearing the project-PRD name (confirmed 2026-08-31) | rename to a goal-extension-scoped name during return |
| N2 | Stack local `main` is a divergent unpushed fork that shadows `next` | already a lane convention; PRD states trunk identity explicitly |
| N3 | Pre-2026-08-26 pattern: `docs/PRD.md` overwritten per milestone | retired by [[GOV.1-prd-lifecycle]] shim model |
| N4 | Two decision registries share the D-prefix ID space (stack D1–D15 vs operator D01–D65); "D8" is ambiguous without registry name | OD- prefix applied in rev1 (Q-G2 ruled 2026-09-01); collision rule in [[GOV.3-decision-map]] |
| N5 | Triple "PRD" collision in the stack tree: root `PRD.md` vs superseded `fleet/PRD.md` and `fleet/PRD-fleet-suite.md`, with no local supersession signal on the latter two | supersession banner in-file; long-term, the GOV.1 rule that the bare name `PRD.md` is reserved for the shim |
| N6 | "Tess" and "Ultron" each name two different things: non-authoritative roster-class display aliases (fleet how-tos) vs the named product agent / validator identity (TESS workstream, native-kanban-sot) | rev1 text always qualifies which sense is meant; flag for upstream rename of the aliases |
| N7 | Six stack `TASKS.md` files under three authority regimes (banner-superseded / explicitly-not-superseded / silently active) — the filename signals nothing | uniform status frontmatter on every TASKS.md; superseded ones point at NORTH_STAR.yaml |
| N8 | Duplicate basenames across stack dirs: `gateway-security-20260313.md` (qa vs code-review, different content), `2026-08-10-docs-catalog-audit.md` (plan vs report), `1099-pipefail-sweep.md` (report vs scratchpad copy) | disambiguate on next touch; prune the unpromoted scratchpad copy |
| N9 | `guides/` is outside the canonical tree per `docs/README.md` yet "protected current authority" per `SITEMAP.md` — contract and sitemap disagree | reconcile the documentation contract; likely fold the four guides into the guide trees |
| N10 | Two live front-matter schemas (`type`/`status: current…` per docs/README.md vs the newer `kind`/`status: active…` used by most files) — collision documented in the w4 worklist, unresolved | settle the schema in the documentation contract as part of E6 return |
| N11 | Three uncross-referenced descriptions of the `/goal` capability: brain `docs/PRD.md`, `operations/goals.md`, and GOV.4 §#1150 | reconcile under the #1150 identity; brain docs cite it |
| N12 | Brain-side: `MOSAIC-CANON.md` vs `STRUCTURE-CANON.md` both claim canon status | operator ruling (Q-T3); retire or fold the unreferenced copy |
| N13 | Forward-looking: rev0 Part II (RI-N3) rules `docs/PRD.md` "not a peer authority" once `docs/prdy/` lands — a third contender in "which PRD is real" | GOV.1 disambiguation: prdy is tooling-facing storage; the shim + bundle remain the human-facing SOT chain |
| N14 | Commit `a480ee83` (2026-08-21) mass-stamped `status: active` frontmatter across stack docs without content review — status metadata rubber-stamps stale docs as current (root MISSION-MANIFEST's "Last Updated: 2026-07-14" is likewise cosmetic; true content edit 2026-04-19) | status/date frontmatter changes only alongside content review; triage dates by git content edits, never frontmatter |
docs/PRDs/2026-08-31_PRD_rev1/GOV.3-decision-map.md
+34 -33
View File
@@ -13,13 +13,13 @@ IDs overlap — a reader seeing "D8" could not know which law was meant.
## The registries
| Registry | IDs | Ratified | Where | Scope |
|---|---|---|---|---|
| Stack PRD registry | **D1–D15** | 2026-08-25/30 | rev0 §12 → [[GOV.3-decision-map]] (this file, below) | product north star |
| Registry | IDs | Ratified | Where | Scope |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Stack PRD registry | **D1–D15** | 2026-08-25/30 | rev0 §12 → [[GOV.3-decision-map]] (this file, below) | product north star |
| Operator decision register | **OD-01–OD-65** (renamed from D01–D65 per Q-G2, 2026-09-01; the brain-side source doc renames on its next touch and carries a redirect table) | 2026-08-28 (Q1–Q92 review) | the operator DECISION-REGISTER (estate brain `docs/guides/proposed/DECISION-REGISTER.md`, snapshot 2026-08-28, sha256 `2cc81be1…aabec`; operator-only corpus, not shipped) | roles, coordination, PRD lifecycle, configuration, checkpoints |
| L2 authorization decisions | **L2-D01–L2-D51** (+ proposed **L2-D52**) | rolling | `fleet/lanes/agent-runtime-ng/MECHANICAL-AGENT-RUNTIME-L2-AUTHORIZATION.md` | mechanical agent-runtime authorization |
| Control-plane rulings | **J1–J5** | 2026-08-23 | `fleet/lanes/docs/mosaic-control-plane/rulings-J1-J5.md` | record-class authority |
| PRD structural rulings | (unnumbered, 8 rulings) | 2026-08-31 | [[PRD.0-index]] §Structural rulings | this bundle's lifecycle |
| L2 authorization decisions | **L2-D01–L2-D51** (+ proposed **L2-D52**) | rolling | `fleet/lanes/agent-runtime-ng/MECHANICAL-AGENT-RUNTIME-L2-AUTHORIZATION.md` | mechanical agent-runtime authorization |
| Control-plane rulings | **J1–J5** | 2026-08-23 | `fleet/lanes/docs/mosaic-control-plane/rulings-J1-J5.md` | record-class authority |
| PRD structural rulings | (unnumbered, 8 rulings) | 2026-08-31 | [[PRD.0-index]] §Structural rulings | this bundle's lifecycle |
**Collision rule:** zero-padded `D01`-form IDs = operator register; bare `D1`-form
= stack PRD registry; `L2-D` = L2; `J` = control-plane rulings. Writing a bare
@@ -28,23 +28,23 @@ IDs overlap — a reader seeing "D8" could not know which law was meant.
## Stack PRD registry D1–D15 (carried from rev0 §12)
| ID | Decision (short form) |
|---|---|
| D1 | Open-source, AI-first, self-hosted platform for agentic management + life OS |
| D2 | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC |
| D3 | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred. **Amended 2026-09-01 (Q-T1 ruling B, "shipped but frozen")**: federation M1–M3 exist in code behind `tier === 'federated'` (M3 landed 2026-06-24/25), are excluded from the v1 bar and frozen; tracked as a dormant workstream in `docs/fleet/NORTH_STAR.yaml`; the frozen cert/auth code carries a security re-audit gate before any resumption; the design itself stays deferred and unforeclosed |
| D4 | Re-runnable, extensible, per-mode onboarding wizards |
| D5 | North star = docs/PRD.md rewrite; stack docs/ = product SSOT |
| D6 | Only product-relevant material migrates from brains; operational records stay and link |
| D7 | Spec-inventory sweep (executed; T2 baseline frozen 2026-08-25) |
| D8 | webUI sits over official framework tooling; CLI primary |
| D9 | Not a hosted business; company = organizational separation for one operator |
| D10 | better-auth is the account system of record; external IdPs via OIDC |
| D11 | Small v1 slice; ALL phases on the documented roadmap from day one |
| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first |
| D13 | workspace_id stays the hard isolation unit; kanban SOT amended, not rewritten |
| D14 | Sensitive profile data in the user's own brain only |
| D15 | Tiered containerized deployment: compose standalone + phase-gated k8s |
| ID | Decision (short form) |
| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| D1 | Open-source, AI-first, self-hosted platform for agentic management + life OS |
| D2 | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC |
| D3 | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred. **Amended 2026-09-01 (Q-T1 ruling B, "shipped but frozen")**: federation M1–M3 exist in code behind `tier === 'federated'` (M3 landed 2026-06-24/25), are excluded from the v1 bar and frozen; tracked as a dormant workstream in `docs/fleet/NORTH_STAR.yaml`; the frozen cert/auth code carries a security re-audit gate before any resumption; the design itself stays deferred and unforeclosed |
| D4 | Re-runnable, extensible, per-mode onboarding wizards |
| D5 | North star = docs/PRD.md rewrite; stack docs/ = product SSOT |
| D6 | Only product-relevant material migrates from brains; operational records stay and link |
| D7 | Spec-inventory sweep (executed; T2 baseline frozen 2026-08-25) |
| D8 | webUI sits over official framework tooling; CLI primary |
| D9 | Not a hosted business; company = organizational separation for one operator |
| D10 | better-auth is the account system of record; external IdPs via OIDC |
| D11 | Small v1 slice; ALL phases on the documented roadmap from day one |
| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first |
| D13 | workspace_id stays the hard isolation unit; kanban SOT amended, not rewritten |
| D14 | Sensitive profile data in the user's own brain only |
| D15 | Tiered containerized deployment: compose standalone + phase-gated k8s |
Full texts: rev0 §12 and the operator decision log (USC estate brain,
webui-audit lane, `GRILL.md`).
@@ -53,22 +53,22 @@ webui-audit lane, `GRILL.md`).
Full set: the operator DECISION-REGISTER (estate brain `docs/guides/proposed/DECISION-REGISTER.md`, snapshot 2026-08-28, sha256 `2cc81be1…aabec`; operator-only corpus, not shipped). Load-bearing here:
| ID | Ruling (short) | Consumed by |
|---|---|---|
| OD-02/OD-03 | one role per seat; role change = clean session, ephemeral context discarded | [[SEAT.1-seat-profile]], [[SESS.1-session-continuity]] |
| OD-08/OD-09 | coordinator service owns leases/deployment; orchestrators never deploy seats directly | [[AUTHZ.1-capability-authority]] |
| ID | Ruling (short) | Consumed by |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| OD-02/OD-03 | one role per seat; role change = clean session, ephemeral context discarded | [[SEAT.1-seat-profile]], [[SESS.1-session-continuity]] |
| OD-08/OD-09 | coordinator service owns leases/deployment; orchestrators never deploy seats directly | [[AUTHZ.1-capability-authority]] |
| OD-16–OD-23 | PRD owns requirements; immutable accepted versions; `docs/PRD.md` = generated pointer under `docs/PRDs/`; missions pin PRD version+digest; `mosaic prdy` owns PRD creation | [[GOV.1-prd-lifecycle]] — **independently re-derived in the 2026-08-31 grill before this register was consulted; the two agree** |
| OD-48 | instance contract: `profile.json` structured identity, `overlay.json` generated composition | [[SEAT.1-seat-profile]] |
| OD-49–OD-53 | `mosaic config` desired-state engine; blueprint + host-binding split; precedence chain; **all interfaces (CLI/TUI/WebUI/API) share one CLI-backed engine** | [[DATA.1-record-authority]], [[CLI.1-parity]], [[UI.1-webui-surfaces]] |
| OD-54 | WebUI drafts are revisioned server-side desired-state; no effect until planned and applied | [[UI.1-webui-surfaces]] |
| OD-57–OD-61 | checkpoints tied to incarnation+lease; coordinator-run relaunch (checkpoint→stop→apply→clean incarnation→restore); fencing; full restart recovery | [[SESS.1-session-continuity]] — **this is the ratified mechanism for mid-stream harness/model/provider switching** |
| OD-62–OD-65 | watchdog, outage fail-closed, failure isolation/reporting | [[AUTHZ.1-capability-authority]], [[UI.1-webui-surfaces]] (audit/alerts) |
| OD-48 | instance contract: `profile.json` structured identity, `overlay.json` generated composition | [[SEAT.1-seat-profile]] |
| OD-49–OD-53 | `mosaic config` desired-state engine; blueprint + host-binding split; precedence chain; **all interfaces (CLI/TUI/WebUI/API) share one CLI-backed engine** | [[DATA.1-record-authority]], [[CLI.1-parity]], [[UI.1-webui-surfaces]] |
| OD-54 | WebUI drafts are revisioned server-side desired-state; no effect until planned and applied | [[UI.1-webui-surfaces]] |
| OD-57–OD-61 | checkpoints tied to incarnation+lease; coordinator-run relaunch (checkpoint→stop→apply→clean incarnation→restore); fencing; full restart recovery | [[SESS.1-session-continuity]] — **this is the ratified mechanism for mid-stream harness/model/provider switching** |
| OD-62–OD-65 | watchdog, outage fail-closed, failure isolation/reporting | [[AUTHZ.1-capability-authority]], [[UI.1-webui-surfaces]] (audit/alerts) |
## Reconciliation notes
- Register OD-13 (repository-backed mission state canonical first, DB later behind
the same interface) and J1 (Git owns governance, PostgreSQL owns runtime
state) are compatible: OD-13 governs *mission* state migration order; J1 governs
state) are compatible: OD-13 governs _mission_ state migration order; J1 governs
steady-state record classes. [[DATA.1-record-authority]] carries the merged
table.
- Register OD-18's "generated pointer" is stricter than the 2026-08-31 grill's
@@ -76,6 +76,7 @@ Full set: the operator DECISION-REGISTER (estate brain `docs/guides/proposed/DEC
not hand-edited ([[GOV.1-prd-lifecycle]] inherits this).
- Proposed, not yet ratified: **L2-D52** (least-privilege Assignment issuance),
staged at `proposed/docs/MECHANICAL-AGENT-RUNTIME-L2-AUTHORIZATION--least-privilege-issuance.md`.
## Extraction cross-check notes (2026-08-31)
- Five highly product-normative operator drafts carry **no decision-register
docs/PRDs/2026-08-31_PRD_rev1/GOV.4-workstream-contracts.md
+1 -2
View File
@@ -11,7 +11,6 @@ Carried verbatim from rev0 ([rev0 PRD](../2026-08-26_PRD_rev0/PRD.md) lines
revision moves no text and changes no requirement in them. They graduate out
individually when their workstreams close.
The sections below are normative, in-flight workstream contracts carried over
verbatim from the previous revision of this file. Open issues bind to them.
This rewrite moved no text and changed no requirement in them; they are
@@ -196,7 +195,7 @@ gateway-backed agent catalog.
| `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities. |
| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note. |
| `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model. |
| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](../../fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](../../fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence. |
| `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](../../fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](../../fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence. |
### Acceptance criteria
docs/PRDs/2026-08-31_PRD_rev1/GOV.5-open-questions.md
+5 -5
View File
@@ -142,8 +142,8 @@ bundle.
rev1 blocker.
- **Q-T4** — **RULED, Jason 2026-09-01, two parts.**
**(a) Two independent axes**: "Standalone/Enterprise" in the S2 corpus is a
multi-tenancy/isolation *mode* (`platform_mode`, D3/D11); D15's "compose
standalone tier" is deployment *packaging*. Orthogonal. rev1 text always
multi-tenancy/isolation _mode_ (`platform_mode`, D3/D11); D15's "compose
standalone tier" is deployment _packaging_. Orthogonal. rev1 text always
says "standalone mode" vs "compose tier"; mode-conversion.md needs a
terminology note only, not a rewrite.
**(b) Own track, rev1 cites**: rev1 ratifies citing the nine contracts as
@@ -151,7 +151,7 @@ bundle.
own PR when its family lands. Extraction record: lane
`S2-EXTRACTION-2026-08-31.md`.
- **Q-T5** — **RULED, Jason 2026-09-01: scope to files.** Adopted wording:
"Generated settings *files* are projections of the active Role Revision,
"Generated settings _files_ are projections of the active Role Revision,
never authority (L2-D19). DB settings records written through audited
Gateway commands (`platform_mode`, `registration_mode`, `custody_config`,
`bootstrap.seed-company-name`, and their successors) are records of
@@ -165,7 +165,7 @@ bundle.
## Deferred-by-scope (recorded, not blocking rev1)
- Federation design (D3 — roadmap placeholder; nothing in v1 may foreclose it).
*Q-T1 ruled B (2026-09-01): D3 to be amended — M1–M3 acknowledged, frozen,
security re-audit gate before resumption; design itself stays deferred.*
_Q-T1 ruled B (2026-09-01): D3 to be amended — M1–M3 acknowledged, frozen,
security re-audit gate before resumption; design itself stays deferred._
- OS/kernel-level seat sandboxing (explicit lane non-goal; role-lane
discipline, not process containment).
docs/PRDs/2026-08-31_PRD_rev1/HARN.1-harness-config.md
+9 -8
View File
@@ -12,17 +12,18 @@ hooks, and settings live in runtime adapters (register OD-38).
## Harness configuration surface (WebUI page + CLI)
| Control | Notes |
|---|---|
| install harness | single button push; installer runs server-side through official tooling |
| enable / disable | disabled harnesses are not selectable on any seat page |
| available models | an **allowlist** a seat may select from — not a selection. Whether `enabledModels` is role policy or harness/seat preference is open: [[GOV.5-open-questions]] Q-H1 |
| reasoning level defaults | |
| provider | which provider(s) back this harness ([[PROV.1-providers]]) |
| linked auth accounts | which accounts may drive this harness ([[AUTHN.1-auth-accounts]]) |
| Control | Notes |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| install harness | single button push; installer runs server-side through official tooling |
| enable / disable | disabled harnesses are not selectable on any seat page |
| available models | an **allowlist** a seat may select from — not a selection. Whether `enabledModels` is role policy or harness/seat preference is open: [[GOV.5-open-questions]] Q-H1 |
| reasoning level defaults | |
| provider | which provider(s) back this harness ([[PROV.1-providers]]) |
| linked auth accounts | which accounts may drive this harness ([[AUTHN.1-auth-accounts]]) |
Enable/disable and install are runtime state (Postgres-owned) projected into
whatever flat state the launcher needs ([[DATA.1-record-authority]]).
## Runtime adapter contract (pulled 2026-08-31 from adapter-contract draft)
Every harness adapter binds a required capability set or **fails closed**:
docs/PRDs/2026-08-31_PRD_rev1/PRD.0-index.md
+14 -14
View File
@@ -30,21 +30,21 @@ the directory is **not** authoritative; this index is.
## Domain registry (append-only)
| Code | Domain |
|-------|--------|
| PRD | The PRD assembly itself: index, preamble, revision log |
| GOV | Governance: document lifecycle, decision registers, amendment process, ratification |
| VIS | Vision / north star: what the Stack is, premises, non-goals |
| Code | Domain |
| ----- | ----------------------------------------------------------------------------------------------- |
| PRD | The PRD assembly itself: index, preamble, revision log |
| GOV | Governance: document lifecycle, decision registers, amendment process, ratification |
| VIS | Vision / north star: what the Stack is, premises, non-goals |
| AUTHZ | Authorization & enforcement: capabilities, role policy, mosaic-core, L2 contracts, gap register |
| AUTHN | Authentication: provider accounts, OAuth/API keys, renewal, deactivation, allowed harnesses |
| ROLE | Roles: manifests, role config surfaces, role/seat separation |
| SEAT | Seats: profiles, launch config, seat config surfaces, profile.json consolidation |
| HARN | Harnesses: install/enable, model availability, reasoning, linked auth |
| PROV | Providers: supported providers, local providers (Ollama, LM Studio), provider config |
| SESS | Sessions: Stack session identity, continuity, mid-stream harness/model/provider switching |
| UI | WebUI: pages, page-scope rules, interaction patterns, audit surfaces |
| CLI | mosaic CLI: command surface, CLI↔WebUI parity |
| DATA | Record classes & storage: J1 git/DB authority split, flat-file vs DB, reconciliation |
| AUTHN | Authentication: provider accounts, OAuth/API keys, renewal, deactivation, allowed harnesses |
| ROLE | Roles: manifests, role config surfaces, role/seat separation |
| SEAT | Seats: profiles, launch config, seat config surfaces, profile.json consolidation |
| HARN | Harnesses: install/enable, model availability, reasoning, linked auth |
| PROV | Providers: supported providers, local providers (Ollama, LM Studio), provider config |
| SESS | Sessions: Stack session identity, continuity, mid-stream harness/model/provider switching |
| UI | WebUI: pages, page-scope rules, interaction patterns, audit surfaces |
| CLI | mosaic CLI: command surface, CLI↔WebUI parity |
| DATA | Record classes & storage: J1 git/DB authority split, flat-file vs DB, reconciliation |
New domains append below this line with a dated note.
docs/PRDs/2026-08-31_PRD_rev1/PRD.md
+22 -22
View File
@@ -26,10 +26,10 @@ reference it (register OD-16/OD-19); they never usurp it. rev0 ([rev0 PRD](../20
## Revision log
| Rev | Date | State | Notes |
|-----|------|-------|-------|
| rev0 | 2026-08-26 | superseded 2026-09-01; archived verbatim as `docs/PRDs/2026-08-26_PRD_rev0/PRD.md` | North Star PRD (Part I product north star from D1–D14 + D15; Part II workstream contracts) |
| rev1 | 2026-08-31 | **ratified 2026-09-01** (Jason; grill rounds 1–8 closed the GOV.5 frontier) | rev0 + control-plane surfaces (seats, roles, harnesses, providers, authentication, sessions, WebUI/CLI), consolidated decision map, authorization gap register, docs-estate consolidation |
| Rev | Date | State | Notes |
| ---- | ---------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rev0 | 2026-08-26 | superseded 2026-09-01; archived verbatim as `docs/PRDs/2026-08-26_PRD_rev0/PRD.md` | North Star PRD (Part I product north star from D1–D14 + D15; Part II workstream contracts) |
| rev1 | 2026-08-31 | **ratified 2026-09-01** (Jason; grill rounds 1–8 closed the GOV.5 frontier) | rev0 + control-plane surfaces (seats, roles, harnesses, providers, authentication, sessions, WebUI/CLI), consolidated decision map, authorization gap register, docs-estate consolidation |
## Mandate (2026-08-31 drafting directive)
@@ -57,32 +57,32 @@ preserved as base text with marked rev1 annotations.
## Part II — Platform model (control plane)
| Section | Owns |
|---|---|
| [[DATA.1-record-authority]] | record-class authority (J1), the configuration data model, seat-file consolidation, reconciliation obligation |
| Section | Owns |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [[DATA.1-record-authority]] | record-class authority (J1), the configuration data model, seat-file consolidation, reconciliation obligation |
| [[AUTHZ.1-capability-authority]] | intersection authority model, `mosaic-core` enforcement, firewalls, privilege escapation, accepted risk, gap register G1–G7 |
| [[ROLE.1-role-governance]] | role definitions/revisions, manifest invariants, role surface, seat/role separation rule |
| [[SEAT.1-seat-profile]] | instance contract, seat surface, the separated role-binding control (G5), OD-02/OD-03 semantics |
| [[HARN.1-harness-config]] | harness install/enable, model allowlists, adapter boundary (register OD-38) |
| [[PROV.1-providers]] | hosted and local providers, named instances, activation |
| [[AUTHN.1-auth-accounts]] | agent-side provider accounts, OAuth/API, custody rules, broker boundary |
| [[SESS.1-session-continuity]] | Stack session id, incarnation layering, mid-stream switching via register OD-57–OD-61, the two-operations rule |
| [[ROLE.1-role-governance]] | role definitions/revisions, manifest invariants, role surface, seat/role separation rule |
| [[SEAT.1-seat-profile]] | instance contract, seat surface, the separated role-binding control (G5), OD-02/OD-03 semantics |
| [[HARN.1-harness-config]] | harness install/enable, model allowlists, adapter boundary (register OD-38) |
| [[PROV.1-providers]] | hosted and local providers, named instances, activation |
| [[AUTHN.1-auth-accounts]] | agent-side provider accounts, OAuth/API, custody rules, broker boundary |
| [[SESS.1-session-continuity]] | Stack session id, incarnation layering, mid-stream switching via register OD-57–OD-61, the two-operations rule |
## Part III — Surfaces
| Section | Owns |
|---|---|
| Section | Owns |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| [[UI.1-webui-surfaces]] | governing rules and the complete page/function inventory, including the authorization-audit page |
| [[CLI.1-parity]] | CLI primacy, the one-engine rule (OD-53), the parity-matrix obligation, command families |
| [[CLI.1-parity]] | CLI primacy, the one-engine rule (OD-53), the parity-matrix obligation, command families |
## Part IV — Governance
| Section | Owns |
|---|---|
| [[GOV.1-prd-lifecycle]] | SOT rule, shim, frozen revision bundles, archival |
| [[GOV.2-docs-inventory]] | corpus inventory, supersession verdicts, naming-defects register |
| [[GOV.3-decision-map]] | every binding decision registry, collision rule, reconciliation notes |
| [[GOV.5-open-questions]] | the grill list; ratification gate |
| Section | Owns |
| ------------------------ | --------------------------------------------------------------------- |
| [[GOV.1-prd-lifecycle]] | SOT rule, shim, frozen revision bundles, archival |
| [[GOV.2-docs-inventory]] | corpus inventory, supersession verdicts, naming-defects register |
| [[GOV.3-decision-map]] | every binding decision registry, collision rule, reconciliation notes |
| [[GOV.5-open-questions]] | the grill list; ratification gate |
## Part V — Active workstream contracts (preserved unchanged)
docs/PRDs/2026-08-31_PRD_rev1/PROV.1-providers.md
+8 -7
View File
@@ -11,17 +11,18 @@ or local (Ollama, LM Studio, other).
## Provider configuration surface (WebUI page + CLI)
| Control | Notes |
|---|---|
| provider selection | dropdown of supported providers |
| name | user-chosen instance name (multiple named instances of one provider type are expected) |
| auth mode | OAuth or API key — the account itself lives in [[AUTHN.1-auth-accounts]] |
| local provider setup | endpoint/port for Ollama, LM Studio, other local providers |
| activate / deactivate | inactive providers are not selectable downstream |
| Control | Notes |
| --------------------- | -------------------------------------------------------------------------------------- |
| provider selection | dropdown of supported providers |
| name | user-chosen instance name (multiple named instances of one provider type are expected) |
| auth mode | OAuth or API key — the account itself lives in [[AUTHN.1-auth-accounts]] |
| local provider setup | endpoint/port for Ollama, LM Studio, other local providers |
| activate / deactivate | inactive providers are not selectable downstream |
Provider records are runtime state (Postgres-owned, projected). Credentials
never enter provider records; they live with the credential broker
([[AUTHN.1-auth-accounts]]).
## E2 inputs (triage 2026-08-31; see [[GOV.2-docs-inventory]])
**Canonical ground truth**: `DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md`
docs/PRDs/2026-08-31_PRD_rev1/ROLE.1-role-governance.md
+7 -6
View File
@@ -25,12 +25,12 @@ meaning. The staged amendment names the surface explicitly.
## Role configuration surface (WebUI page + CLI)
| Control | Notes |
|---|---|
| manifest editing | capability grants against the C1–C8 (later open) registry; schema-validated before commit |
| revision management | create revision, diff against active, activate, roll back — every revision immutable and digested |
| role links | which seats bind this role (read-only here; binding happens on the seat surface — see [[SEAT.1-seat-profile]]) |
| projection status | whether each bound seat's on-disk projection matches the active revision (`role check` class) |
| Control | Notes |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| manifest editing | capability grants against the C1–C8 (later open) registry; schema-validated before commit |
| revision management | create revision, diff against active, activate, roll back — every revision immutable and digested |
| role links | which seats bind this role (read-only here; binding happens on the seat surface — see [[SEAT.1-seat-profile]]) |
| projection status | whether each bound seat's on-disk projection matches the active revision (`role check` class) |
All writes go through the one canonical role-management API (L2-D14) shared
with the CLI — the WebUI holds no separate role logic. Role management is
@@ -44,6 +44,7 @@ operations, and the API enforces that, not the page.
- Nothing env-overridable, nothing cwd-relative.
- `tools[]` equals exactly the bound bindings of granted capabilities.
- Role cross-checked against path at load.
## Specialization model (pulled 2026-08-31 from SPECIALIZATION-MODEL draft)
Four layers: **Role** (decision ownership and prohibited actions — few,
docs/PRDs/2026-08-31_PRD_rev1/SEAT.1-seat-profile.md
+17 -16
View File
@@ -8,24 +8,24 @@ ratified: 2026-09-01 (Jason Woltje; PRD rev1 ratification PR)
## Instance contract (register OD-48)
| File | Carries |
|---|---|
| `profile.json` | structured identity — and, post-consolidation, the full seat record ([[DATA.1-record-authority]] §consolidation) |
| `overlay.json` | generated composition |
| seat-local `AGENTS.md` | narrative specialization |
| `SOUL.md` | persona |
| File | Carries |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `profile.json` | structured identity — and, post-consolidation, the full seat record ([[DATA.1-record-authority]] §consolidation) |
| `overlay.json` | generated composition |
| seat-local `AGENTS.md` | narrative specialization |
| `SOUL.md` | persona |
## Seat configuration surface (WebUI page + CLI)
| Control | Notes |
|---|---|
| harness | from **enabled** harnesses only ([[HARN.1-harness-config]]) |
| model | constrained by the harness's available-models allowlist |
| reasoning level | |
| work dir | |
| Control | Notes |
| ---------------------- | ------------------------------------------------------------------------------------- |
| harness | from **enabled** harnesses only ([[HARN.1-harness-config]]) |
| model | constrained by the harness's available-models allowlist |
| reasoning level | |
| work dir | |
| authentication account | from configured, active accounts allowed for that harness ([[AUTHN.1-auth-accounts]]) |
| overlay | per-seat overlay only — never the role file (ROLE separation rule) |
| role binding | **separated section — see below** |
| overlay | per-seat overlay only — never the role file (ROLE separation rule) |
| role binding | **separated section — see below** |
## The role-binding control (gap G5)
@@ -44,14 +44,15 @@ dropdown. Requirements:
- Role-transition history is recorded: old role, new role, reason, authorizer,
checkpoint, activation time (register OD-04).
Role changes are therefore a *different operation* from harness/model/provider
Role changes are therefore a _different operation_ from harness/model/provider
changes ([[SESS.1-session-continuity]]) and must not share a code path.
## Seat identity and credential rules (pulled 2026-08-31 from seat-identity draft)
- **One seat = one identity = one token slot.** A second copy of a token
anywhere is drift and is removed without reading it.
- Agents never mint their own tokens; provisioning, rotation, and scope changes
are operator authority. Credential refusal is *correct behavior* — the fix is
are operator authority. Credential refusal is _correct behavior_ — the fix is
the seat's identity, never another seat's or a shared credential.
- Fail-closed everywhere: an empty/unreadable slot is a designed state reported
at launch; the credential helper refuses, records, notifies — never falls
docs/PRDs/2026-08-31_PRD_rev1/SESS.1-session-continuity.md
+8 -7
View File
@@ -15,12 +15,12 @@ intervention and no noticeable performance degradation.
## Two operations, two code paths — never merged
| | Harness / model / provider switch | Role switch |
|---|---|---|
| Session id | preserved | seat identity preserved; session is **clean** |
| Context | fully transferred | **ephemeral context discarded** (register OD-03) |
| Governed by | this section | [[SEAT.1-seat-profile]] §role-binding |
| Why | continuity requirement | an active session never switches roles (register OD-02) |
| | Harness / model / provider switch | Role switch |
| ----------- | --------------------------------- | ------------------------------------------------------- |
| Session id | preserved | seat identity preserved; session is **clean** |
| Context | fully transferred | **ephemeral context discarded** (register OD-03) |
| Governed by | this section | [[SEAT.1-seat-profile]] §role-binding |
| Why | continuity requirement | an active session never switches roles (register OD-02) |
## The ratified mechanism already exists: register OD-57–OD-61
@@ -39,7 +39,7 @@ The 2026-08-28 register confirms the machinery this requirement needs:
A mid-stream harness switch is therefore an OD-59 relaunch keyed to a persistent
Stack session id: checkpoint → stop → reconfigure → new incarnation →
restore → resume. What OD-59 does not yet promise is the *experience* bar — no
restore → resume. What OD-59 does not yet promise is the _experience_ bar — no
user intervention, no noticeable degradation — which is this PRD's addition.
## Identity layering
@@ -63,6 +63,7 @@ Context-transfer fidelity between harnesses with different context formats,
tool-call encodings, and system-prompt injection points. The checkpoint (OD-57)
is the transfer vehicle; whether a checkpoint alone meets "no noticeable
degradation" across harness families is unproven: [[GOV.5-open-questions]] Q-S3.
## Session lifecycle state machine (pulled 2026-08-31 from the session-lifecycle draft — with one required extension)
The operator draft (`workflows/session-lifecycle.md`, the densest
docs/PRDs/2026-08-31_PRD_rev1/UI.1-webui-surfaces.md
+9 -9
View File
@@ -36,14 +36,14 @@ actions performed on-page.
## Page inventory
| Page | Section doc | Functions |
|---|---|---|
| Seat configuration | [[SEAT.1-seat-profile]] | harness, model, reasoning, workdir, auth account, overlay; separated role-binding section |
| Role configuration | [[ROLE.1-role-governance]] | manifest editing, revision create/diff/activate/rollback, role links, projection status |
| Harness configuration | [[HARN.1-harness-config]] | install (button), enable/disable, available-models allowlist, reasoning defaults, provider link, linked accounts |
| Provider configuration | [[PROV.1-providers]] | provider dropdown, named instances, OAuth/API mode, local providers, activate/deactivate |
| Authentication | [[AUTHN.1-auth-accounts]] | in-browser OAuth establishment, account list, force renew, deactivate, allowed harnesses |
| Authorization audit | below | effective grants, escapation potential, drift |
| Page | Section doc | Functions |
| ---------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Seat configuration | [[SEAT.1-seat-profile]] | harness, model, reasoning, workdir, auth account, overlay; separated role-binding section |
| Role configuration | [[ROLE.1-role-governance]] | manifest editing, revision create/diff/activate/rollback, role links, projection status |
| Harness configuration | [[HARN.1-harness-config]] | install (button), enable/disable, available-models allowlist, reasoning defaults, provider link, linked accounts |
| Provider configuration | [[PROV.1-providers]] | provider dropdown, named instances, OAuth/API mode, local providers, activate/deactivate |
| Authentication | [[AUTHN.1-auth-accounts]] | in-browser OAuth establishment, account list, force renew, deactivate, allowed harnesses |
| Authorization audit | below | effective grants, escapation potential, drift |
## Page: Authorization audit (closes gap G3)
@@ -54,7 +54,7 @@ Surfaces, per seat, to the user:
- **Misdirection potential** — which seats hold capabilities that would let
another seat's work be routed around its own role lane.
- **Escalation potential** — any path that would add capability. Should be
provably empty; the audit's job is proving it *stays* empty.
provably empty; the audit's job is proving it _stays_ empty.
- **Drift** — seats whose on-disk projection diverges from their active role
revision (`role check` class).
- **Failure/blocked surfacing** (register OD-64) — the canonical alert stream's
docs/PRDs/2026-08-31_PRD_rev1/VIS.1-north-star.md
+1 -3
View File
@@ -10,7 +10,6 @@ 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
@@ -52,7 +51,7 @@ required); git tracking is always on locally.
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
_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
@@ -199,7 +198,6 @@ 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)