From 41c11388e4e0f2eee4df1875c5a08fa8319ca215 Mon Sep 17 00:00:00 2001 From: marcie Date: Sat, 29 Aug 2026 23:24:56 -0500 Subject: [PATCH 1/4] docs: containerization plan + PRD D15 (tiered deployment, standalone v1 bar) --- docs/PRD.md | 19 +++++- docs/plans/2026-08-30_containerization.md | 77 +++++++++++++++++++++++ 2 files changed, 95 insertions(+), 1 deletion(-) create mode 100644 docs/plans/2026-08-30_containerization.md diff --git a/docs/PRD.md b/docs/PRD.md index 36965619..a8efc381 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -197,7 +197,24 @@ conflict must amend one of them explicitly, never fork a third document - A second writable task store beside PostgreSQL (native-kanban-sot invariants). - Fully-designed federation in v1 (D3 — roadmap placeholder only). -### 12. Decision registry +# +### 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. + +## 12. Decision registry | ID | Decision (short form) | | --- | ------------------------------------------------------------------------------------------------------------------ | diff --git a/docs/plans/2026-08-30_containerization.md b/docs/plans/2026-08-30_containerization.md new file mode 100644 index 00000000..ad2101c4 --- /dev/null +++ b/docs/plans/2026-08-30_containerization.md @@ -0,0 +1,77 @@ +# Plan — Stack Containerization (tiered deployment) + +Status: DRAFT for review. Charter: fleet/lanes/stack-containerization +(brain) NORTH-STAR.md; PRD amendment in the same PR adds D15. +Supersedes nothing; sequences the absorbed M4 remainder per its lane. + +## Measured baseline (origin/next @ 143ba0f5, 2026-08-30) + +- `docker-compose.yml`: dev infrastructure only — postgres (pgvector), + valkey, otel-collector, jaeger. No application services. +- `docker-compose.federated.yml`: standalone overlay for the FEDERATED + storage tier (own postgres/valkey; port-conflicts the base stack by + design). Not an app deployment. +- `docker/gateway.Dockerfile`, `docker/appservice.Dockerfile`: + multi-stage production builds (node:22-alpine) EXIST; the gateway image + includes the web SPA bundle (#1444). +- CI (`publish.yml`) builds and publishes these images (next-channel + prereleases + main stable), and runs `verify:release` fail-closed. +- Gap: no stack-level composition wires gateway+appservice+data plane + into one deployable unit; no blessed install/upgrade path; no + in-container agent-runtime story for the dogfood loop. + +## Target (PRD D15 amendment) + +Tiered deployment, additive to the existing architecture: + +1. **Standalone tier (v1 bar)**: `docker compose up` on one host brings + postgres, valkey, openbao, gateway, appservice (and the webUI the + gateway serves) to healthy; migrations apply; the webUI hosts agent + chat; an in-stack agent can read this repo and open a PR; CI + validates; the deployment adopts merged images (pull + restart). +2. **Enterprise tier (post-v1)**: Kubernetes manifests (or Helm) for the + same service set, phase-gated on the standalone bar holding. + +## Phases + +### Phase A — blessed standalone compose +- A1 Compose service definitions for gateway + appservice joining the + existing infra compose (profiles: `dev` keeps today's behavior; + `stack` adds the app tier), with health checks and dependency order. +- A2 Migrations on boot (or an explicit migrate step) with idempotency + and version pinning; init-db.sql folded into pg-init. +- A3 Openbao in the compose set (secret plumbing for the app tier). +- A4 `.env.example` + `mosaic.config.json` defaults documented for the + standalone mode; mode recorded per the mode-conversion contract. +- A5 Smoke: `docker compose --profile stack up` green on a scratch host; + webUI served; agent chat reachable; failures catalogued and fixed. +- Acceptance: the five-point NORTH-STAR bar measured live. + +### Phase B — component completion +- Decompose JIT from A5's catalogue. Known candidates: agent runtime + bits (brain/tool access paths in-container), repo credentials for the + dogfood agent, watch/comms surfaces inside the deployment. + +### Phase C — CI/CD parity +- Publish pipeline is the only image source (already true); add the + deployment-side pull/upgrade path (compose pull + migrate + restart = + next iteration); document the promotion flow next -> registry -> + deployment. + +### Phase D — coordinator integration (GATED) +- Blocked until the guides-proposed control-plane refactor lands; then + wire `mosaic coord` service lifecycle per that design. + +### Phase E — enterprise tier +- k8s manifests/Helm for the same set; phase-gated on Phase A holding. + +### Absorbed M4 remainder +- M4-3 pivot: KBN-101 foundation first (per ruling R6), then expand DDL. +- M4-5: lands inside Phase B/C where natural. +- M4-6 (composes M4-1+M4-4): last, as designed. + +## Non-goals (v1) + +- No Kubernetes in v1; no multi-host federation; no replacement of the + fleet's brain-based seats (the stack is an additional operator + surface); no on-host image builds for deployment (registry only). -- 2.54.0 From 1ad328af63977bc8ba28c59444063124c6634078 Mon Sep 17 00:00:00 2001 From: marcie Date: Sat, 29 Aug 2026 23:31:02 -0500 Subject: [PATCH 2/4] docs: fold velma R5 verdict (C1 typed-ops scope, C2 checkpoint-lease gate, seat-grade identity) --- docs/plans/2026-08-30_containerization.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/plans/2026-08-30_containerization.md b/docs/plans/2026-08-30_containerization.md index ad2101c4..9a9c016f 100644 --- a/docs/plans/2026-08-30_containerization.md +++ b/docs/plans/2026-08-30_containerization.md @@ -48,6 +48,11 @@ Tiered deployment, additive to the existing architecture: - Acceptance: the five-point NORTH-STAR bar measured live. ### Phase B — component completion +- Interface assumption (velma verdict A1, P5-RM-005/006): in-stack + dogfood agents inherit SEAT-GRADE identity — credential-slot + isolation, wrapper-first enforcement, no privileged coordination + identity, evidence by references that resolve outside the container + lifetime. - Decompose JIT from A5's catalogue. Known candidates: agent runtime bits (brain/tool access paths in-container), repo credentials for the dogfood agent, watch/comms surfaces inside the deployment. @@ -59,8 +64,19 @@ Tiered deployment, additive to the existing architecture: deployment. ### Phase D — coordinator integration (GATED) -- Blocked until the guides-proposed control-plane refactor lands; then - wire `mosaic coord` service lifecycle per that design. +- Gate (velma verdict C2): blocked until the checkpoint-and-lease child + of the guides-proposed control-plane refactor — core + WU-P1-CHECKPOINT + (schema, freshness, incarnation, clean-replacement resume; D57-D60 + lineage) — carries an independent target-bound PASS. Wiring restarts + against the core alone re-creates the stale-incarnation failure class + D57-D60 closed. Transitive: inherits the T108 gates (P0 exit + Jason + P1 authorization). +- Scope (velma verdict C1): lifecycle actions (start/stop/restart/ + health/recovery) executed by the SHIPPED coord client over the one + typed coordination contract (request id, actor identity, epoch, + revision, lease, correlation; typed stale rejection; worker role + boundary). No second coordination interface gets designed here — + containerization consumes the coordination contract, never defines it. ### Phase E — enterprise tier - k8s manifests/Helm for the same set; phase-gated on Phase A holding. -- 2.54.0 From ab2c15c0bf2bf2003ed5559b56cb9cf2859e2b0a Mon Sep 17 00:00:00 2001 From: marcie Date: Sat, 29 Aug 2026 23:56:25 -0500 Subject: [PATCH 3/4] docs: prettier + A3R F1 (stray #/heading) + F2 (D15 registry row) --- docs/PRD.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/PRD.md b/docs/PRD.md index a8efc381..d394144c 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -197,7 +197,6 @@ conflict must amend one of them explicitly, never fork a third document - A second writable task store beside PostgreSQL (native-kanban-sot invariants). - Fully-designed federation in v1 (D3 — roadmap placeholder only). -# ### D15 — Tiered containerized deployment (2026-08-30, containerization lane) The stack ships a tiered deployment target, additive to the architecture @@ -232,6 +231,7 @@ docs/plans/2026-08-30_containerization.md. | D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first | | D13 | workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten | | D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers | +| D15 | Tiered containerized deployment: compose standalone tier (five-point v1 bar) + phase-gated k8s enterprise tier; registry-only image source | 2026-08-30 containerization lane; plan docs/plans/2026-08-30_containerization.md | The full decision texts are recorded in the operator decision log (USC estate brain, webui-audit lane, `GRILL.md`). -- 2.54.0 From f5ab5161db101e35fa19499e5675eacfb69c9c99 Mon Sep 17 00:00:00 2001 From: marcie Date: Sat, 29 Aug 2026 23:56:44 -0500 Subject: [PATCH 4/4] docs: apply prettier formatting (CI format step) --- docs/PRD.md | 32 +++++++++++------------ docs/plans/2026-08-30_containerization.md | 6 +++++ 2 files changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/PRD.md b/docs/PRD.md index d394144c..1139634d 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -215,22 +215,22 @@ docs/plans/2026-08-30_containerization.md. ## 12. Decision registry -| 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 | -| D4 | Re-runnable, extensible, per-mode onboarding wizards | -| D5 | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT | -| D6 | Only product-relevant material migrates from brains; operational records stay and link | -| D7 | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 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; hierarchy is parent structure above; kanban SOT amended, not rewritten | -| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers | +| 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 | +| D4 | Re-runnable, extensible, per-mode onboarding wizards | +| D5 | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT | +| D6 | Only product-relevant material migrates from brains; operational records stay and link | +| D7 | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 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; hierarchy is parent structure above; kanban SOT amended, not rewritten | +| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers | | D15 | Tiered containerized deployment: compose standalone tier (five-point v1 bar) + phase-gated k8s enterprise tier; registry-only image source | 2026-08-30 containerization lane; plan docs/plans/2026-08-30_containerization.md | The full decision texts are recorded in the operator decision log (USC estate diff --git a/docs/plans/2026-08-30_containerization.md b/docs/plans/2026-08-30_containerization.md index 9a9c016f..0b2ca598 100644 --- a/docs/plans/2026-08-30_containerization.md +++ b/docs/plans/2026-08-30_containerization.md @@ -35,6 +35,7 @@ Tiered deployment, additive to the existing architecture: ## Phases ### Phase A — blessed standalone compose + - A1 Compose service definitions for gateway + appservice joining the existing infra compose (profiles: `dev` keeps today's behavior; `stack` adds the app tier), with health checks and dependency order. @@ -48,6 +49,7 @@ Tiered deployment, additive to the existing architecture: - Acceptance: the five-point NORTH-STAR bar measured live. ### Phase B — component completion + - Interface assumption (velma verdict A1, P5-RM-005/006): in-stack dogfood agents inherit SEAT-GRADE identity — credential-slot isolation, wrapper-first enforcement, no privileged coordination @@ -58,12 +60,14 @@ Tiered deployment, additive to the existing architecture: dogfood agent, watch/comms surfaces inside the deployment. ### Phase C — CI/CD parity + - Publish pipeline is the only image source (already true); add the deployment-side pull/upgrade path (compose pull + migrate + restart = next iteration); document the promotion flow next -> registry -> deployment. ### Phase D — coordinator integration (GATED) + - Gate (velma verdict C2): blocked until the checkpoint-and-lease child of the guides-proposed control-plane refactor — core + WU-P1-CHECKPOINT (schema, freshness, incarnation, clean-replacement resume; D57-D60 @@ -79,9 +83,11 @@ Tiered deployment, additive to the existing architecture: containerization consumes the coordination contract, never defines it. ### Phase E — enterprise tier + - k8s manifests/Helm for the same set; phase-gated on Phase A holding. ### Absorbed M4 remainder + - M4-3 pivot: KBN-101 foundation first (per ruling R6), then expand DDL. - M4-5: lands inside Phase B/C where natural. - M4-6 (composes M4-1+M4-4): last, as designed. -- 2.54.0