262 lines
19 KiB
Markdown
262 lines
19 KiB
Markdown
# Native Kanban/SOT P0–P3 — Dependency-Ordered Build Slices
|
||
|
||
**Status:** CANON INDEPENDENTLY APPROVED; PUBLICATION IN PROGRESS
|
||
**Tracking:** [Mosaic Stack issue #751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
|
||
**Execution:** USC web1 only; collision-free GPT coder2/3/4/5 lanes
|
||
**Contract:** `SHARED-CONTRACT.md` + four `contracts/*.v1.ts` files
|
||
**Implementation hold:** no feature slice starts until the canon PR is merged to `main` with terminal-green CI; after merge, each slice remains held until every declared KBN prerequisite is complete.
|
||
|
||
> This publication file is not a runtime task authority. After cutover, repository `TASKS.md` is generated read-only and never imported.
|
||
|
||
## Execution invariants
|
||
|
||
- PostgreSQL is the sole writable SOT; current-main Drizzle is the persistence foundation.
|
||
- Mutations require fresh internal PostgreSQL transaction-local write proof and fail closed otherwise.
|
||
- Public health DTOs, Valkey, files, browser state, providers, and outage notes cannot authorize writes.
|
||
- Outage notes return only through attributable `change_proposals`; proposal acceptance executes the normal command.
|
||
- Mechanical Coordinator is non-LLM and cannot invent scope, waive gates, certify, or merge.
|
||
- Certifier is final independent gate with no merge authority.
|
||
- Workspace is the hard tenant. Project hierarchy is project-congruent. Assignment, approval, lease, fence, checkpoint, and evidence are relationally bound.
|
||
- Recovery tiers change recovery posture only.
|
||
|
||
## 1. Collision-free ownership
|
||
|
||
| USC lane | Exclusive ownership | Must not edit |
|
||
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
|
||
| **coder2 — schema/recovery** | `packages/db/src/schema.ts`; `packages/db/drizzle/**`; DB tests; `packages/config/src/recovery-posture.ts`; `packages/config/src/recovery-posture.spec.ts`; `docs/runbooks/kanban-postgres-recovery.md` | Gateway, Brain repositories, Coordinator, web, CLI/importer |
|
||
| **coder3 — domain/Gateway/MCP server** | Kanban repositories under `packages/brain/src/`; Gateway workspace/project/mission/milestone/task/kanban/health/coord modules; **exact MCP files:** `apps/gateway/src/mcp/mcp.dto.ts`, `mcp.controller.ts`, `mcp.service.ts`, `mcp.module.ts`, `mcp.tokens.ts`, `mcp.service.spec.ts`; Gateway root wiring/tests | DB schema/migrations, `packages/coord`, web, CLI/importer |
|
||
| **coder4 — CLI → pure Coordinator → migration tooling** | In this one fixed lane order: KBN-120 (`packages/mosaic` CLI/projection) → KBN-200 (`packages/coord/src/mechanical/**`) → KBN-300/320 (`scripts/kanban-migration/**`) | DB, Gateway/MCP server, web |
|
||
| **coder5 — web** | `apps/web/src/app/(dashboard)/{tasks,projects}/**`; `apps/web/src/components/{tasks,projects}/**`; Kanban web API/types; later Coordinator/migration-review routes | DB, Gateway, Coordinator, CLI/importer |
|
||
| **Mos — publication/integration** | Contract amendments, exact endpoint registry publication, serialized root exports/manifests/lockfiles, integration gates | Active lane feature files |
|
||
|
||
Shared roots, package exports/manifests, lockfiles, and generated artifacts are integration-serialized. Contract changes stop affected lanes and require Mos approval.
|
||
|
||
## 2. Parallelization legend
|
||
|
||
- **SERIAL:** prerequisite must be complete and reviewed.
|
||
- **PARALLEL-GROUP:** disjoint files and exact frozen contract permit concurrent work.
|
||
- **LANE-SERIAL:** one lane's stated order cannot change.
|
||
- **INTEGRATION-SERIAL:** component heads green first; semantic findings return to owner.
|
||
|
||
## 3. Corrected dependency graph
|
||
|
||
```text
|
||
KBN-000 canon remediation
|
||
-> KBN-010 threat/auth/constraint-impact gate (MUST COMPLETE)
|
||
-> KBN-100 schema + concrete N-1 migration implementation
|
||
├─ KBN-105 exact endpoint/DTO/error/registry freeze (SERIAL)
|
||
│ ├─ KBN-110 domain + Gateway + MCP server implementation
|
||
│ ├─ KBN-120 CLI/projection implementation [coder4 first]
|
||
│ └─ KBN-130 web MVP implementation
|
||
└─ KBN-115 recovery parser/mechanism slice [coder2 lane-serial]
|
||
KBN-110 + KBN-120 + KBN-130 + KBN-115
|
||
-> KBN-140 P1 integration/SIT
|
||
-> KBN-200 pure decision engine [coder4 after KBN-120]
|
||
-> KBN-210 persistence/service adapter + approval/lease binding
|
||
-> KBN-220 Coordinator operations UI
|
||
-> KBN-230 P2 concurrency/fault/gate integration
|
||
KBN-230
|
||
-> KBN-300 importer dry-run/apply/verify [coder4 after KBN-200]
|
||
├─ KBN-310 migration reviewer UI
|
||
└─ KBN-320 cutover/rollback tooling [coder4 after KBN-300]
|
||
KBN-310 + KBN-320
|
||
-> KBN-330 rehearsal/reconciliation
|
||
-> KBN-340 owner-gated cutover/stabilization
|
||
```
|
||
|
||
No consumer implementation begins before KBN-105. No schema work begins before KBN-010 completes. The coder4 order is always KBN-120 → KBN-200 → KBN-300 → KBN-320.
|
||
|
||
## 4. P0 — Canon, threat gate, schema, and exact API freeze
|
||
|
||
### KBN-000 — Remediate and publish canon
|
||
|
||
- **Owner:** Mos / publication control plane.
|
||
- **Mode:** SERIAL; publication gate in progress.
|
||
- **IN:** Resolve KCR-001–016 in requirements, schema, health, Coordinator, recovery, migration map, and slices; independent re-review.
|
||
- **OUT:** Feature implementation.
|
||
- **Depends on:** none.
|
||
- **Contract surfaces:** all canon.
|
||
- **Evidence:** strict TS; Prettier; per-finding traceability; independent author≠reviewer GO.
|
||
|
||
### KBN-010 — Threat, authorization, and constraint-impact gate
|
||
|
||
- **Owner:** coder3; independent `secrev`.
|
||
- **Mode:** SERIAL prerequisite of KBN-100.
|
||
- **Exclusive files:** Mos-selected threat/auth docs only.
|
||
- **IN:** Cross-workspace owners/principals/evidence; active membership; stale/forged health; approval forgery; fence monotonicity; audit retention; proposal target/audit-event forgery; service tokens; DB/Valkey outage.
|
||
- **OUT:** Runtime/schema edits.
|
||
- **Depends on:** KBN-000 independent re-review GO.
|
||
- **Contract surfaces:** schema constraints, health proof, exact errors, command-family authorization.
|
||
- **Evidence:** signed constraint-impact matrix; no unresolved schema-impact finding; SecReview pass.
|
||
|
||
### KBN-100 — Unified Drizzle schema and concrete N-1 migration
|
||
|
||
- **Owner:** **coder2**.
|
||
- **Mode:** SERIAL.
|
||
- **Exclusive files:** `packages/db/src/schema.ts`, `packages/db/drizzle/**`, DB tests.
|
||
- **IN:** All frozen tables/joins/enums; workspace/project-congruent constraints; owners/principals; tags/archive; change proposals with both workspace-aware task-event composite FKs and frozen event-before-proposal DDL order; assignment approvals; durable execution/quarantine; monotonic bigint fence; exact checkpoint/evidence joins; RESTRICT/immutability; concrete current-main expand/backfill/switch/contract map.
|
||
- **OUT:** Repositories, Gateway, Coordinator behavior, UI, importer.
|
||
- **Depends on:** **KBN-010 completed**.
|
||
- **Contract surfaces:** `kanban-schema.v1.ts`; SHARED-CONTRACT current-main delta map.
|
||
- **Evidence:** reviewed SQL; empty/prod-shape/partial-resume/rollback tests; N-1 app safety; legacy columns remain declared; workspace/project mismatch negatives; proposal event-FK missing/foreign-workspace tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; SecReview.
|
||
|
||
### KBN-105 — Exact Gateway/MCP endpoint, DTO, and error freeze
|
||
|
||
- **Owner:** Mos + coder3 contract author; independent endpoint-alignment reviewer.
|
||
- **Mode:** SERIAL after KBN-100; prerequisite for KBN-110/120/130.
|
||
- **Exclusive files:** canonical endpoint-registry/DTO contract docs; no implementation.
|
||
- **IN:** Exact routes and methods from SHARED-CONTRACT §8; request/success/error fields; status codes; pagination/filter/revision envelopes; idempotency/expected-version headers/fields; proposal commands; health proof exclusion from public DTOs; MCP tool-to-route map.
|
||
- **OUT:** Controller/service/client implementation.
|
||
- **Depends on:** KBN-100.
|
||
- **Contract surfaces:** health/error unions; schema IDs/statuses; Gateway DTO freeze.
|
||
- **Evidence:** every FE/CLI/MCP call maps 1:1 to a route; 503/502-504/409 non-cross-map fixtures; contract digest published.
|
||
|
||
### KBN-115 — Recovery posture parser, mechanisms, and evidence
|
||
|
||
- **Owner:** **coder2**, lane-serial after KBN-100.
|
||
- **Mode:** PARALLEL with KBN-110/120/130 after KBN-105.
|
||
- **Exclusive files:** `packages/config/src/recovery-posture.ts`, `.spec.ts`, `docs/runbooks/kanban-postgres-recovery.md`; deployment-specific backup manifest changes are a separately enumerated Mos integration patch.
|
||
- **IN:** Wire normative `validateRecoveryPostureV1`; override audit; backup/WAL/PITR mechanism assertions; off-cluster encryption/failure-domain checks; restore and break-glass evidence procedure.
|
||
- **OUT:** SOT/gate/Coordinator policy knobs; DB business schema.
|
||
- **Depends on:** KBN-100, KBN-105.
|
||
- **Contract surfaces:** `recovery-posture.v1.ts` only.
|
||
- **Evidence:** impossible-combination tests; High-assurance weakening tests; selected-tier mechanism verification; restore and break-glass evidence; SecReview.
|
||
|
||
## 5. P1 — Thin native MVP
|
||
|
||
### KBN-110 — Workspace-safe domain, Gateway, MCP server, and proposal commands
|
||
|
||
- **Owner:** **coder3**.
|
||
- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
|
||
- **Exclusive files:** ownership map, including all exact MCP server files listed there.
|
||
- **IN:** Workspace-safe repositories; project/task/dependency/tag/archive CRUD; transitions; exact owners; assignment/approval/link/artifact queries; submit/query/accept/reject change proposals; health endpoint; internal write-proof mint/revalidation; event/outbox atomicity; frozen DTOs/routes.
|
||
- **OUT:** Scheduling algorithm, web, CLI, DB schema.
|
||
- **Depends on:** KBN-100, KBN-105.
|
||
- **Contract surfaces:** all four TypeScript contracts and exact registry.
|
||
- **Evidence:** DTO/service/controller/integration tests; active-membership and no-oracle negatives; proposal cannot mutate directly; submission event is the new proposal's exact `change_proposal.submitted` event; acceptance links the executed normal command for the locked proposal and same workspace/target; missing, foreign-workspace, unrelated-proposal/target/command event negatives; exact failure mapping; endpoint registry; SecReview.
|
||
|
||
### KBN-120 — CLI, MCP client mapping, and generated projection
|
||
|
||
- **Owner:** **coder4**; first coder4 slice.
|
||
- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
|
||
- **Exclusive files:** `packages/mosaic/src/commands/{kanban,tasks,projects}.ts`; `packages/mosaic/src/projections/**`; tests. **No `apps/gateway/src/mcp/**` edits.\*\*
|
||
- **IN:** Frozen query/mutation routes; proposal commands; compact context; generated `TASKS.md`; deliberate denial/transport/conflict handling.
|
||
- **OUT:** Gateway/MCP server, file importer, raw SQL/Valkey, Coordinator.
|
||
- **Depends on:** KBN-105; runtime integration later requires KBN-110.
|
||
- **Evidence:** contract fixtures; same revision; no import parser; same idempotency key on transport retry; 503 never auto-retried.
|
||
|
||
### KBN-130 — Writable Kanban/List and minimal Projects UI
|
||
|
||
- **Owner:** **coder5**.
|
||
- **Mode:** PARALLEL-GROUP P1-A after KBN-105.
|
||
- **Exclusive files:** web ownership map.
|
||
- **IN:** Workspace context; projects; tasks; tags; explicit archive; detail; accessible move/reorder; filters; dependency/readiness; owner/assignment/lease; audit; proposal visibility; conflict/loading/error/reconnect.
|
||
- **OUT:** Gateway/schema, Coordinator operations UI, migration UI.
|
||
- **Depends on:** KBN-105; runtime integration later requires KBN-110.
|
||
- **Evidence:** frozen contract mocks; real-Gateway journeys; keyboard/non-drag; tags/archive semantics; no-oracle tenant negatives; 503/transport/409 distinct UI.
|
||
|
||
### KBN-140 — P1 integration and situational gate
|
||
|
||
- **Owner:** Mos integration; independent reviewer/SecReview/Certifier.
|
||
- **Mode:** INTEGRATION-SERIAL.
|
||
- **IN:** KBN-110/120/130/115; unavoidable root exports only.
|
||
- **OUT:** P2 behavior.
|
||
- **Depends on:** KBN-110, KBN-120, KBN-130, KBN-115.
|
||
- **Evidence:** clean migration; web/CLI/MCP/projection revision parity; forged/expired health negatives; change-proposal event-chain success plus missing/foreign/unrelated-event negatives; tag/archive; tenant negatives; endpoint registry; author-independent review; Certifier pass.
|
||
|
||
## 6. P2 — Mechanical Coordinator
|
||
|
||
### KBN-200 — Pure deterministic decision engine
|
||
|
||
- **Owner:** **coder4**; second coder4 slice, strictly after KBN-120.
|
||
- **Mode:** SERIAL in coder4 lane.
|
||
- **Exclusive files:** `packages/coord/src/mechanical/**` and pure tests.
|
||
- **IN:** `MechanicalCoordinatorDecisionEngineV1`; complete immutable snapshots; eligibility/explanation; fairness/order; capability matching; expiry/retry/quarantine decisions.
|
||
- **OUT:** ID loading, PostgreSQL, Drizzle, Gateway, Valkey, health-proof minting, persistence, `recoverFromPostgres`, LLM calls.
|
||
- **Depends on:** KBN-140 (or Mos may release after KBN-120 + frozen types if no P1 semantic risk remains).
|
||
- **Evidence:** deterministic/property tests; snapshot completeness; no I/O/model imports; no authority methods.
|
||
|
||
### KBN-210 — Coordinator persistence/service adapter and approval-bound leases
|
||
|
||
- **Owner:** **coder3**.
|
||
- **Mode:** SERIAL after KBN-200.
|
||
- **Exclusive files:** Gateway `coord` and repositories.
|
||
- **IN:** `MechanicalCoordinatorServicePortV1`; snapshot loading; proposal persistence; manual/versioned policy approval; acquire by IDs; reload+lock task/assignment/approval/session; fresh txn-local write proof; atomic task fence increment; lease/ack/heartbeat/checkpoint/submit; durable retry/quarantine; outbox/Valkey wake; restart recovery.
|
||
- **OUT:** Pure algorithm, UI, DB schema.
|
||
- **Depends on:** KBN-110, KBN-200.
|
||
- **Evidence:** forged/stale approval rejection; target/session/version/expiry/policy checks; concurrent monotonic fences; same-workspace mismatch negatives; bigint precision; stale worker rejection; DB/Valkey faults; SecReview.
|
||
|
||
### KBN-220 — Coordinator operations UI
|
||
|
||
- **Owner:** **coder5**.
|
||
- **Mode:** after KBN-210 exact DTO freeze.
|
||
- **IN:** Roster; eligibility; persisted assignment state; approvals/overrides; exact lease/fence; durable retry/quarantine; role/gate/Certifier visibility.
|
||
- **OUT:** Scheduling decisions, schema, merge control for Certifier.
|
||
- **Depends on:** KBN-210.
|
||
- **Evidence:** authorized journeys; reason required; stale refresh; no Certifier merge; endpoint alignment/accessibility.
|
||
|
||
### KBN-230 — P2 concurrency/fault/gate integration
|
||
|
||
- **Owner:** Mos integration; independent reviewer/SecReview/Certifier.
|
||
- **Mode:** INTEGRATION-SERIAL.
|
||
- **Depends on:** KBN-200, KBN-210, KBN-220.
|
||
- **Evidence:** one lease; monotonic fences; exact relational mismatches rejected; expired proof; forged healthy; approval binding; restart; durable quarantine; outbox recovery; author≠reviewer; Certifier final/no merge.
|
||
|
||
## 7. P3 — Shadow migration and cutover
|
||
|
||
### KBN-300 — One-way importer dry-run/apply/verify
|
||
|
||
- **Owner:** **coder4**; third coder4 slice.
|
||
- **Mode:** after KBN-230.
|
||
- **Exclusive files:** `scripts/kanban-migration/import/**`.
|
||
- **IN:** Immutable jarvis-brain/Vikunja snapshots; deterministic mapping; source digest/lineage; Gateway writes; rejects; no dispatch.
|
||
- **OUT:** Bidirectional sync, direct DB/file canonical writes, unrelated brain data.
|
||
- **Depends on:** KBN-230.
|
||
- **Evidence:** idempotency; counts/fields; malformed/foreign rejects; no dispatch; SecReview.
|
||
|
||
### KBN-310 — Shadow reviewer UI
|
||
|
||
- **Owner:** **coder5**.
|
||
- **Mode:** PARALLEL-GROUP P3-A after KBN-300 report freeze.
|
||
- **IN:** Read-only counts/diffs/rejects/lineage/sign-off.
|
||
- **OUT:** Apply/cutover mutations.
|
||
- **Depends on:** KBN-300.
|
||
- **Evidence:** read-only and tenant tests; pagination/accessibility.
|
||
|
||
### KBN-320 — Cutover/rollback tooling
|
||
|
||
- **Owner:** **coder4**; fourth coder4 slice, after KBN-300.
|
||
- **Mode:** PARALLEL-GROUP P3-A with KBN-310.
|
||
- **Exclusive files:** `scripts/kanban-migration/cutover/**`.
|
||
- **IN:** Freeze assertion; backup/checksum; final delta; client switch; legacy writer/credential shutdown; rollback delta; stabilization.
|
||
- **OUT:** Destructive deletion, reverse sync, ungated production execution.
|
||
- **Depends on:** KBN-300.
|
||
- **Evidence:** fail-safe rehearsal; no dual writer; rollback authority; SecReview.
|
||
|
||
### KBN-330 — Migration rehearsal/reconciliation
|
||
|
||
- **Owner:** Mos + coder4 support + independent data reviewer.
|
||
- **Mode:** INTEGRATION-SERIAL.
|
||
- **Depends on:** KBN-310, KBN-320.
|
||
- **Evidence:** signed exceptions; selected-tier restore; backlog hold; no legacy changes; Certifier readiness.
|
||
|
||
### KBN-340 — Final cutover/stabilization
|
||
|
||
- **Owner:** Mos/control plane; owner-gated operation.
|
||
- **Mode:** SERIAL.
|
||
- **Depends on:** KBN-330 PASS and Jason authorization.
|
||
- **Evidence:** no legacy writer; scoped Gateway identities; no accidental dispatch; terminal green health/CI; Certifier evidence; owner retirement approval.
|
||
|
||
## 8. Consistent USC wave schedule
|
||
|
||
| Wave | coder2 | coder3 | coder4 | coder5 |
|
||
| ---- | ------------------------- | -------------------------------------- | ------------------------------ | ------------------------------ |
|
||
| 0 | Wait | **KBN-010** | Wait | Wait |
|
||
| 1 | **KBN-100** | Review constraint implementation | Wait | Wait |
|
||
| 2 | **KBN-115** after KBN-100 | **KBN-105** exact freeze, then KBN-110 | **KBN-120** only after KBN-105 | **KBN-130** only after KBN-105 |
|
||
| 3 | Review support | Finish KBN-110 | **KBN-200 after KBN-120** | Finish KBN-130 |
|
||
| 4 | — | **KBN-210 after KBN-200** | Review/support | **KBN-220 after KBN-210 DTOs** |
|
||
| 5 | — | P2 remediation | **KBN-300 then KBN-320** | **KBN-310** |
|
||
|
||
Mos alone releases slices and lifts the build hold after independent re-review GO.
|