mosaicstack/stack
1
0
Fork 0
Code Issues 48 Pull Requests 2 Actions Packages Projects Releases 15 Wiki Activity
Files
12b58c3eaaf42fad531ff2cf287356681f502c68
stack/docs/native-kanban-sot/TASKS.md
Hermes Agent 12b58c3eaa docs(#769): start KBN-100 schema migration
2026-07-14 16:59:23 -05:00

20 KiB
Raw Blame History

Native Kanban/SOT P0–P3 — Dependency-Ordered Build Slices

Status: CANON INDEPENDENTLY APPROVED; PUBLICATION IN PROGRESS Tracking: Mosaic Stack issue #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

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

  • Status: COMPLETE — PR #752 squash-merged as 49e8a54; issue #751 closed; post-merge pipeline #1798 terminal success.
  • Owner: Mosaic publication control plane.
  • Mode: SERIAL; completed.
  • 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; Ultron GO; terminal-green CI.

KBN-010 — Threat, authorization, and constraint-impact gate

  • Status: COMPLETE — PR #765 squash-merged as 2e228007; issue #753 closed; post-merge pipeline #1813 terminal success.
  • Owner: kbn-coder3; independent Homelab schema/SecReview and web1:coder0 Codex-Ultron review.
  • Mode: SERIAL prerequisite of KBN-100; completed.
  • Exclusive files: docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md and task scratchpad 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

  • Status: IN PROGRESS — issue #769; implementation held until tracking commit and baseline evidence are pushed.
  • Owner: web1:kbn-schema-coder2 author lane; independent DB reviewer, SecReview, and Codex-Ultron required.
  • 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: TDD RED/GREEN; reviewed generated SQL/journal; real PostgreSQL empty/prod-shape/partial-resume/rollback tests; N-1 startup/read/write safety; legacy columns remain declared; workspace/project mismatch negatives; N100-01..50 including rc.4 candidate-before-FK and two-child foreign-workspace tests; proposal event-FK missing/foreign/unrelated tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; independent DB review, SecReview, Codex-Ultron, terminal-green PR/main CI.

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.

Reference in New Issue View Git Blame Copy Permalink