Files

ci/woodpecker/push/ci Pipeline failed

Details

docs(fleet): DRAFT PRD proposal — Jarvis HMI main agent, Matrix-first transport, webUI fleet control, permission relay, backlog providers, Hermes decommission

Ratification draft (Jason, 2026-07-09) extending NORTH_STAR.yaml with NS-10..NS-13
and workstreams J/K/W/P/Q/X. Written against origin/main's fleet suite (F4/F6
anchors, H2 profiles, native backlog per ASM-1). Homelab is the trial
environment (D12); USC/web1 adopts post-trial. See proposals/mosaic-platform-prd/README.md
for the full decision record D1-D12.

Not yet merged into NORTH_STAR.yaml — landing and card decomposition are the
homelab orchestrator's mission.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-09 14:19:05 -05:00

2.7 KiB

Raw Blame History

PRD — Backlog Provider Sync Adapters · Workstream Q

Status: DRAFT for ratification · Goals: Q1–Q3 · Doctrine: NS-12 (ratified D3)

Mission

Users choose where they see and touch work — Gitea, GitHub, a local kanban — while the Mosaic Backlog on native Postgres stays the sole record and dispatch engine (upholds ASM-1; NS-3/NS-4/NS-5 guarantees never depend on an external provider). Providers attach as bidirectional sync adapters.

Requirements

Adapter interface + Gitea (Q1)

ID	Requirement
Q-R1	A `BacklogProviderAdapter` interface: map card ⇄ external item (create/update/close/comment/label), with stable external-id linkage stored on the card.
Q-R2	Sync is bidirectional and conflict-safe: native record wins on divergence; external edits arrive as proposed mutations (applied if non-conflicting, else surfaced).
Q-R3	Claims, TTLs, depends_on DAG, and dispatch state live only in the native record; adapters project them (e.g. as labels/comments) but never own them.
Q-R4	Gitea adapter first (webhook + API), configured per workspace: repo mapping, label conventions, direction (mirror-out / mirror-in / full).
Q-R5	Adapter enable/disable is workspace configuration; zero adapters is a fully supported mode.

GitHub (Q2)

ID	Requirement
Q-R6	Same interface, GitHub Issues backend. Existing `packages/cli-tools` platform detection informs but does not implement this (that is dev tooling, not product runtime).

Local kanban (Q3)

ID	Requirement
Q-R7	A webUI kanban board over the native backlog (no external provider needed) — the "local kanban" choice. Builds on W3's card views and/or the existing `KanbanBoard` component upgraded from demo-grade to live data.

Acceptance criteria

A card created by Jarvis (J3) appears as a Gitea issue within one sync interval; closing the issue in Gitea marks the card for review, not silent closure; dispatch/claims never round-trip through Gitea.
Killing the adapter mid-mission: dispatch continues unaffected (record is native); on restart, sync converges without duplicates.
The same mission can be mirrored to Gitea and viewed on the local kanban simultaneously without state divergence.

Non-goals

External provider AS the backlog (vetoed — "truly swappable backends" option declined 2026-07-09).
Two-way sync of claims/TTL semantics (external systems can't express them; projection only).

Assumptions

ASSUMPTION: the delivery fleet's engineering PR/issue flow on the stack repo itself continues to use cli-tools/Gitea directly — workstream Q is the product feature for user workspaces, not a replacement for the dev workflow.

2.7 KiB Raw Blame History Unescape Escape