waggle-os/docs/ux-refactor/deltas/coverage-check.md

# Coverage Check — Waggle OS UX Refactor (Adversarial Completeness Audit)

> **Role:** Coverage Critic. This document is a skeptical, traceability audit of whether the
> UX-refactor analysis (22 gap cards `S00–S21` + 3 deltas) is **complete** against the PRD's three
> contract axes: **§12 screens (1–21)**, **§16 API endpoints (65)**, and **§26 Definition of Done (11)**.
> It also flags PRD surfaces that fall **outside** the §12 numbered-screen list (§9.2/§11 objects,
> §13 journeys, §17 RBAC, §10.4 Extend nodes) that no card owns.
>
> **Method:** every row is grounded in the PRD, the gap cards, `backend-api-delta.md`, and the
> source-grounded `_inventory/backend-routes.md` §16 cross-reference (which the delta draws from).
> "COVERED" = some card/delta explicitly owns the requirement with a build target. "GAP" = skipped,
> implicit-only, or owned by no artifact.
>
> **Sources read:** PRD `docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md`
> (§9, §10, §11, §12 lines 371–662, §13 lines 666–832, §14, §16 lines 1060–1158, §17, §19, §26 lines
> 1485–1500); all `docs/ux-refactor/gap-cards/S00–S21.md`; `docs/ux-refactor/deltas/{backend-api-delta,
> design-system-delta,shared-types-delta}.md`; `docs/ux-refactor/_inventory/{backend-routes,frontend,
> substrate-types}.md`.

---

## Table 1 — PRD Screens (the 21 numbered screens + AppShell)

The 21 numbered screens are the blueprint deck expansion of PRD §12.1–§12.13. AppShell (S00) is the
chrome the PRD §1 spine mounts inside (not a §12 screen, but required by §19.1 + §20.3). **Verdict: all
21 numbered screens + the shell are COVERED by a gap card.** No numbered screen is missing.

| # | PRD screen (§ ref) | Status | Gap card |
|---|---|---|---|
| — | AppShell / IA / Navigation (§1, §19.1, §20.3) | COVERED | **S00** appshell-ia |
| 1 | Home Cockpit (§12.1) | COVERED | **S01** home-cockpit |
| 2 | Workspace Desktop (§12.2) | COVERED (with sub-gaps, see notes) | **S02** workspace-desktop |
| 3 | Command Center (Ctrl+K) (§12.3) | COVERED | **S03** command-center |
| 4 | Memory Center (§12.4) | COVERED | **S04** memory-center |
| 5 | Artifact Center (§12.5) | COVERED | **S05** artifact-center |
| 6 | Skills Hub + Skill Builder (§12.6) | COVERED | **S06** skills-hub (+ **S19** skill-builder) |
| 7 | Connector Hub (§12.7) | COVERED | **S07** connector-hub |
| 8 | MCP Hub (§12.8) | COVERED | **S08** mcp-hub |
| 9 | Agent Center + Agent Builder (§12.9) | COVERED | **S09** agent-center (+ **S18** agent-builder) |
| 10 | Automation Center + Builder (§12.10) | COVERED | **S11** automation-center (+ **S20** automation-builder) |
| 11 | Team Workspace (§12.11) | COVERED | **S10** team-workspace |
| 12 | Onboarding · First Launch (§12.12 step 1) | COVERED | **S12** first-launch |
| 13 | Onboarding · Who Are You (§12.12 step 2) | COVERED | **S13** who-are-you |
| 14 | Onboarding · Tool Discovery (§12.12 step 3) | COVERED | **S14** tool-discovery |
| 15 | Onboarding · Memory Import (§12.12 step 4) | COVERED | **S15** memory-import |
| 16 | Onboarding · Memory Review (§12.12 step 5) | COVERED | **S16** memory-review |
| 17 | Onboarding · Workspace Creation (§12.12 step 6) | COVERED | **S17** workspace-creation |
| 18 | Agent Builder (§12.9 stepper) | COVERED | **S18** agent-builder |
| 19 | Skill Builder (§12.6 stepper) | COVERED | **S19** skill-builder |
| 20 | Automation Builder (§12.10 stepper) | COVERED | **S20** automation-builder |
| 21 | Marketplace / Extend Waggle (§12.13) | COVERED | **S21** marketplace-extend |

**Note — Home Cockpit (§12.12 step 7 "Home Cockpit").** The 7th onboarding step is "land in Home
Cockpit," which is S01 (not a separate screen). Correctly folded. ✔

**Screen-level sub-gaps (not whole-screen misses, but skipped requirements inside a covered screen):**

- **G1 — Workspace Desktop tab parity (S02).** PRD §12.2 (line 426 + 436) names **8 tabs**: Overview,
  Chat, Research/Notes, Artifacts, Memory, Tasks, Timeline, **Settings**. The S02 card's tab bar (line
  20) lists **7** and omits a **Settings** tab; the card later maps "Settings → existing component" (line
  86) but never lists Settings in the §12.2 tab enumeration it reproduces. Minor, but the per-workspace
  Settings tab (needed by Journey 19 "Archive workspace" → "opens workspace settings") should be an
  explicit S02 tab, not implied.
- **G2 — Sessions as a first-class navigable object.** PRD §9.2 + §11 glossary list **Session** as a
  primary product object ("Should be navigable and related to memory/artifacts"). No gap card surfaces a
  Sessions list/navigation view; S02 collapses sessions into the **Timeline** tab + Chat. The session
  substrate is rich and unused at the screen level (`GET /api/workspaces/:id/sessions`,
  `/sessions/search`, `/sessions/:id/timeline`, `/sessions/:id/export` all EXIST per
  `_inventory/backend-routes.md:42–46`). Ctrl+K (S03) does federate session search, so sessions are
  *findable* but not *browsable as an object class*. PRD §13 Journey 3 ("user reviews… sessions") and the
  object hierarchy §9.2 imply a Sessions surface. **Decide:** explicit Sessions tab/sub-view in S02, or
  document that Timeline+Ctrl+K is the intended session UX and amend the §11 "navigable" claim.

---

## Table 2 — PRD §16 Endpoints (all 65) — addressed in `backend-api-delta.md`?

`backend-api-delta.md` deliberately lists **only NET-NEW + EXTEND** backend work (49 of 65) and
**excludes the 16 EXISTS endpoints** (they need FE wiring only). For audit completeness, "addressed"
below = **either** carried in the delta's master table **or** explicitly enumerated as EXISTS-and-excluded
in the delta's de-dup note (lines 46–48) / counts cross-reference (line 372). Counts reconcile to the
`_inventory/backend-routes.md` §16 table (16 EXISTS / 30 PARTIAL / 19 MISSING = 65).

| §16 group | PRD endpoint | In delta? | Disposition / where |
|---|---|:--:|---|
| 16.1 Home | `GET /api/home/briefing` | YES | NET-NEW `home.ts` (delta 1a) |
| 16.1 | `POST /api/quick-capture` | YES | EXTEND → memory write (delta 1a) |
| 16.1 | `GET /api/home/overnight` | YES | NET-NEW `home.ts` (delta 1a) |
| 16.2 Workspaces | `GET /api/workspaces` | YES (EXISTS-excluded) | exists; FE wiring only (delta line 46) |
| 16.2 | `POST /api/workspaces` | YES | EXTEND richer body (delta 2c) |
| 16.2 | `GET /api/workspaces/:id` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.2 | `PATCH /api/workspaces/:id` | YES (EXISTS-excluded) | exists (also PUT); FE wiring only |
| 16.2 | `GET /api/workspaces/:id/state` | YES | EXTEND thin route (delta 1b) |
| 16.2 | `GET /api/workspaces/:id/context` | YES (EXISTS-excluded) | exists; the Home/Workspace seed |
| 16.2 | `GET /api/workspaces/:id/activity` | YES | EXTEND thin alias (delta 1b) |
| 16.3 Command | `GET /api/command/search?q=` | YES | NET-NEW `command.ts` (delta 1c) |
| 16.3 | `POST /api/command/execute` | YES | EXTEND over `/commands/execute` (delta 1c) |
| 16.3 | `GET /api/command/recent` | YES | NET-NEW / client-derive (delta 1c) |
| 16.3 | `GET /api/command/suggestions` | YES | NET-NEW (delta 1c) |
| 16.4 Memory | `GET /api/memory` | YES | EXTEND alias (delta 2a) |
| 16.4 | `GET /api/memory/:id` | YES | NET-NEW thin read (delta 2a) |
| 16.4 | `POST /api/memory` | YES | EXTEND alias (delta 2a) |
| 16.4 | `PATCH /api/memory/:id` | YES | EXTEND (PATCH+bare id) (delta 2a) |
| 16.4 | `POST /api/memory/:id/archive` | YES | NET-NEW thin (delta 2a) |
| 16.4 | `DELETE /api/memory/:id` | YES | EXTEND alias (delta 2a) |
| 16.4 | `POST /api/memory/merge` | YES | NET-NEW (delta 2a) |
| 16.4 | `GET /api/memory/graph` | YES (EXISTS-excluded) | exists (`knowledge.ts`); FE wiring only (delta line 47) |
| 16.5 Harvest | `POST /api/harvest/preview` | YES | EXTEND (confidence+items) (delta 2a) |
| 16.5 | `POST /api/harvest/commit` | YES | EXTEND (`selectedIds`) (delta 2a) |
| 16.5 | `GET /api/harvest/sources` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.5 | `POST /api/harvest/sources/:id/sync` | YES | NET-NEW thin (delta 2d) |
| 16.6 Artifacts | `GET /api/artifacts` | YES | NET-NEW `artifacts.ts` (delta 2b) |
| 16.6 | `POST /api/artifacts` | YES | NET-NEW (delta 2b) |
| 16.6 | `GET /api/artifacts/:id` | YES | NET-NEW (delta 2b) |
| 16.6 | `PATCH /api/artifacts/:id` | YES | NET-NEW (delta 2b) |
| 16.6 | `DELETE /api/artifacts/:id` | YES | NET-NEW (delta 2b) |
| 16.6 | `GET /api/artifacts/search-related?q=` | YES | NET-NEW (delta 2b) |
| 16.7 Agents | `GET /api/agents` | YES | NET-NEW `agents.ts` (delta 3a) |
| 16.7 | `POST /api/agents` | YES | NET-NEW (delta 3a) |
| 16.7 | `GET /api/agents/:id` | YES | NET-NEW (delta 3a) |
| 16.7 | `PATCH /api/agents/:id` | YES | NET-NEW (delta 3a) |
| 16.7 | `POST /api/agents/:id/run` | YES | EXTEND → fleet/spawn (delta 3a) |
| 16.7 | `POST /api/agents/:id/pause` | YES | EXTEND → fleet pause (delta 3a) |
| 16.7 | `GET /api/agents/:id/traces` | YES | NET-NEW over `execution_traces` (delta 3a) |
| 16.8 Skills | `GET /api/skills` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.8 | `POST /api/skills` | YES (EXISTS-excluded) | exists (+ `/skills/create`); Builder target |
| 16.8 | `PATCH /api/skills/:id` | YES | EXTEND (PATCH+id alias) (delta 3b) |
| 16.8 | `POST /api/skills/:id/test` | YES | EXTEND (:id variant) (delta 3b) |
| 16.8 | `POST /api/skills/:id/install` | YES | NET-NEW dispatcher (delta 3b) |
| 16.9 Conn/MCP/Mkt | `GET /api/connectors` | YES | EXISTS + optional payload EXTEND (delta 4a) |
| 16.9 | `POST /api/connectors/:id/connect` | YES | EXISTS + audit EXTEND (delta 4a) |
| 16.9 | `POST /api/connectors/:id/sync` | YES | NET-NEW (delta 4a) |
| 16.9 | `POST /api/connectors/:id/revoke` | YES | EXTEND alias → disconnect (delta 4a) |
| 16.9 | `GET /api/mcps` | YES | NET-NEW `mcps.ts` (delta 4b) |
| 16.9 | `POST /api/mcps/install` | YES | EXTEND via marketplace installer (delta 4b) |
| 16.9 | `POST /api/mcps/:id/test` | YES | NET-NEW (delta 4b) |
| 16.9 | `POST /api/mcps/:id/revoke` | YES | NET-NEW (delta 4b) |
| 16.9 | `GET /api/marketplace` | YES | EXTEND bare-path alias (delta 4c) |
| 16.9 | `POST /api/marketplace/install` | YES (EXISTS-excluded) | exists (PRO, SecurityGate); FE wiring |
| 16.10 Automations | `GET /api/automations` | YES | EXTEND alias → cron (delta 3c) |
| 16.10 | `POST /api/automations` | YES | EXTEND alias → cron (delta 3c) |
| 16.10 | `PATCH /api/automations/:id` | YES | EXTEND alias (+ FE PUT/PATCH bug fix) (delta 3c) |
| 16.10 | `POST /api/automations/:id/run` | YES | EXTEND alias → cron trigger (delta 3c) |
| 16.10 | `POST /api/automations/:id/pause` | YES | NET-NEW thin / EXTEND (delta 3c) |
| 16.10 | `GET /api/automations/:id/logs` | YES | EXTEND alias → cron history (delta 3c) |
| 16.11 Team/RBAC | `GET /api/teams/:id` | YES (EXISTS-excluded) | exists; FE wiring only |
| 16.11 | `POST /api/teams/:id/invite` | YES | EXTEND alias → `/members` (delta 5) |
| 16.11 | `PATCH /api/teams/:id/members/:memberId` | YES | EXTEND (role-gate bug fix) (delta 5) |
| 16.11 | `GET /api/teams/:id/audit` | YES | EXTEND alias → `/activity` (delta 5) |
| 16.11 | `POST /api/share` | YES | NET-NEW (delta 5) |

**Verdict: 65/65 PRD §16 endpoints are addressed** — 49 with explicit build targets, 16 acknowledged as
EXISTS-and-excluded (FE-wiring-only). **No §16 endpoint is silently dropped.** The delta additionally
adds ~16 blueprint-implied endpoints beyond the §16 literal set (MCP start/stop/logs/permissions/custom,
connector health/activity, automations/test, team governance, artifact-share, extend/audit) — over-, not
under-, coverage.

**Audit caveats on Table 2 (skeptical reads — these are scope decisions hidden as "addressed"):**

- **C1 — `POST /api/connectors/:id/sync` is "phased to a stub" (delta 4a, line 214).** Marked NET-NEW but
  the MVP is explicitly only `healthCheck()` + a `lastSyncAt` stamp; "full data re-pull is a larger
  connector-SDK addition." So the headline §12.7 acceptance ("**whether data is flowing**") is met only
  cosmetically in v1. This is the load-bearing S07 gap and the delta admits it does not truly close it.
- **C2 — `GET /api/mcps/:id/logs` deferred (delta 4b, line 238).** No log-capture infra exists; PRD §12.8
  lists "view logs" as a functional requirement and §16 implies logs visibility. Deferred to "a later
  phase." So MCP "auditable" (§12.8 acceptance) is partially unmet at the route level for v1.
- **C3 — `POST /api/mcps/:id/test` open question unresolved (delta 4b, line 233).** "live spawn-and-
  handshake vs static manifest validation" is undecided. The endpoint is listed but its semantics are not.
- **C4 — Boot-time `mcpRuntime` population (delta 4b, line 240).** This is flagged as "the foundational
  non-route work item that unblocks all of [MCP]" — but it is **not an endpoint and not phased into a
  sprint**. It is the single biggest hidden-effort item in the Extend layer and should be an explicit
  Phase-4 task, not a footnote.

---

## Table 3 — PRD §26 Definition of Done (all 11) — addressed by a phase/card?

**Headline finding (CRITICAL): no gap card or delta references the Definition of Done by name.** A
grep for "Definition of Done" / "DoD" across all 22 cards + 3 deltas returns **0 matches**. The DoD is
the PRD's release-acceptance contract; the analysis satisfies most items *implicitly* but ships **no
DoD→phase/card traceability artifact**. The next planner must not assume DoD is closed just because the
screens are covered. Per-item mapping below.

| # | DoD item (§26) | Status | Where addressed / GAP |
|---|---|---|---|
| 1 | Home Cockpit replaces blank-chat launch behavior | COVERED (implicit) | S01 builds Home Cockpit; but **no card/delta states the launch-default flip** (today launch = workspace/chat per `frontend.md`). The *behavioral replacement* (boot route → Home) is an **S00 AppShell routing change** that S00 does not explicitly own. **GAP-D1:** name the default-route change. |
| 2 | Workspace Desktop is default runtime for workspace work | COVERED | S02 (`create-new` tabbed runtime); S00 routes to it. |
| 3 | Ctrl+K can search/launch/create/run/navigate/extend | COVERED | S03 + S00 (global provider); `CommandResult.kind` enum covers all 6 verbs (S03 line 136). |
| 4 | Memory Center exposes source/confidence/evidence/scope/edit/delete | COVERED (1 conditional dep) | S04 + S16; ConfidenceBadge/EvidenceChip/EvidencePanel in design-delta; **depends on M1 `memory_frames.metadata` migration** if confidence/scope become real filter axes (delta §M1). If M1 is skipped, "confidence/scope" is in-app-only — verify against §12.4 AC. |
| 5 | Artifact Center supports outcome search + related objects | COVERED | S05 + `GET /api/artifacts/search-related` (delta 2b). |
| 6 | Onboarding leads profile→tool-discovery→import→review→first workspace | COVERED | S12–S17 chain; S00/onboarding shell. |
| 7 | Agents, skills, automations, connectors, MCPs, marketplace have coherent IA | COVERED | S06–S11, S18–S21 all map to the Work/Intelligence/Extend IA (S00 §IA). |
| 8 | Team workspace supports shared intelligence + roles | COVERED (RBAC UI partial) | S10; **but RBAC UI is an open question** — `GET /api/teams/:id/governance` is "optional/NET-NEW" (delta 5) and PRD §17 role matrix has **no dedicated card** (see GAP-D2). |
| 9 | Sensitive actions are approval-gated and audited | COVERED (cross-cutting, no owner card) | ApprovalModal in design-delta; S03/S08/S18/S19/S20 reference approval; `/extend/audit` (delta 4c). **GAP-D3:** the approval+audit *pattern* is cross-cutting but **owned by no single card** — risk of inconsistent per-screen implementation. |
| 10 | All screens have required states (§14) | PARTIAL — **the weakest-traced DoD item** | design-delta builds EmptyState/ErrorState/Skeleton/StatusBadge (the *primitives*), but **no card carries a per-screen §14 state matrix**. State-keyword density is uneven across cards (S02, S18, S20, S21 are thin; S00/S12 are rich). §14.1 mandates 9 global states (Loading/Empty/Populated/Error/Offline/Syncing/Permission-denied/Partial/Approval) on *every* major screen. **GAP-D4:** no screen×state coverage grid exists. |
| 11 | Claude Code can continue from PRD without product interpretation | COVERED (this artifact set is the evidence) | The 22 cards + 3 deltas + this check are the interpretation layer; this is met by the existence of the analysis itself, modulo the open questions below. |

---

## Concrete gaps to fix (prioritized)

**CRITICAL (close before the impl plan is "done"):**

1. **GAP-D4 — No screen × §14-state coverage matrix.** DoD #10 requires *every* major screen to
   implement the 9 global states (§14.1) plus its screen-specific states (§14.2–§14.7). The design-delta
   ships the state *primitives* but no artifact proves each of S01–S21 wires Loading/Empty/Error/Offline/
   Permission-denied/Approval. Cards S02, S18, S20, S21 are visibly thin on state enumeration. **Fix:**
   add a 21×9 state-coverage grid (per-screen) to the impl plan; it is the single most under-traced DoD
   item.
2. **GAP-D3 — Approval-gating + audit is cross-cutting but owned by no card.** DoD #9 + PRD §17.3 +
   §18.1. ApprovalModal (design-delta #7) and `/extend/audit` (delta 4c) exist, but no card defines the
   canonical "which actions are sensitive, what the approval payload is, what gets audited" contract.
   Risk: each builder (S18/S19/S20) and S03/S08 re-implements approval differently. **Fix:** a dedicated
   cross-cutting "Approval & Audit" spec section (or an S00 sub-card) naming the gated-action taxonomy.
3. **C4 — MCP boot-time runtime population is a hidden foundational task, not a sprint item.** Without it
   none of the MCP routes function. **Fix:** elevate `mcpRuntime` population (`local/index.ts:911`) to an
   explicit Phase-4 task with its own estimate.

**HIGH:**

4. **GAP-D1 — The blank-chat→Home launch-default flip (DoD #1) is unowned.** S01 builds the screen; no
   card changes the boot route. **Fix:** assign the default-route change to S00 explicitly.
5. **GAP-D2 — PRD §17 RBAC role matrix (Owner/Admin/Contributor/Viewer × 6 capabilities) has no
   dedicated card.** S10 covers Team Workspace and mentions RBAC, but the role×permission enforcement UI
   + the `GET /api/teams/:id/governance` route are "optional." DoD #8 ("supports… roles") and §17.2 are
   only partially traced. PRD §20.3 lists `RBAC/Audit components` under Create. **Fix:** confirm S10 owns
   the §17.2 matrix UI, or add an RBAC/Audit card.
6. **G2 — Sessions has no first-class screen** despite being a §9.2/§11 primary object. Collapsed into
   S02 Timeline + Ctrl+K search. **Fix:** either add an explicit Sessions sub-view to S02 or document that
   Timeline+Ctrl+K is the intended UX and soften the §11 "navigable" claim.
7. **C1 — Connector `/sync` MVP is a cosmetic stub** that does not meet §12.7's "whether data is
   flowing" acceptance. **Fix:** flag in the plan that S07's headline AC is only partially met in v1;
   schedule the real connector-SDK data-pull.

**MEDIUM:**

8. **G1 — S02 omits the §12.2 Settings tab** from its tab enumeration (7 vs PRD's 8). Needed for
   Journey 19 (Archive workspace). **Fix:** add Settings to the S02 tab list.
9. **C2 — MCP `/:id/logs` deferred** vs §12.8 "view logs" functional requirement. **Fix:** confirm
   v1-acceptable, or schedule the stderr ring-buffer.
10. **C3 — MCP `/:id/test` semantics undecided** (live handshake vs static validation). **Fix:** resolve
    the open question before S08 build.
11. **Journeys §13 (20 journeys) are not cross-referenced to cards.** The analysis is screen-oriented;
    no artifact maps the 20 user journeys (esp. J15 agent-approval, J16 automation-failure→Home-attention,
    J19 archive, J20 delete-memory) to the screens that must implement each step. Most are implicitly
    covered, but **J16** (overnight failure surfacing in Home "attention required") spans S01+S11+S20 and
    is not explicitly owned end-to-end. **Fix:** a journey→screen trace table.

**LOW / acknowledged-by-design (not true gaps, listed so they are not re-litigated):**

12. **Models / External-tools Extend nodes (§10.4)** have no standalone Hub card — folded into S21
    (Models = marketplace category federated from Settings→Models; external_tool = `ExtensionType`).
    S21 line 132 raises the `ExtensionType` reconciliation open question (agent vs external_tool). This is
    a deliberate fold, not a miss — but the `ExtensionType` union must be resolved (shared-types-delta).
13. **§16 EXISTS endpoints (16) excluded from the delta** — correct by design (FE-wiring-only), and
    acknowledged in the delta de-dup note. Not a gap.
14. **Schema migrations** — at most M1 ships; M2 (install_audit CHECK) is a real latent bug the delta
    caught (good); M3 (agents table) correctly deferred. No gap.

---

## Bottom line

- **Screens:** 21/21 numbered screens + AppShell COVERED. 2 intra-screen sub-gaps (S02 Settings tab;
  Sessions-as-object).
- **§16 endpoints:** 65/65 addressed (49 build targets + 16 EXISTS-excluded). Coverage is complete; 4
  scope caveats (connector-sync stub, MCP logs/test/boot) are admitted-but-soft.
- **§26 DoD:** 11/11 items map to *some* artifact, but **DoD is never named** and **2 items are only
  partially traced** (#10 states matrix, #9 approval/audit owner) plus #1 (launch-flip) and #8 (RBAC
  matrix) have unowned slices. **The biggest completeness risk is not a missing screen — it is the
  absence of two cross-cutting traceability grids (screen×state, journey×screen) and an explicit
  approval/audit + RBAC owner.**