---
type: "Plan"
title: "API & Dashboard — Domain Plan"
description: "Durable domain plan for the mission-data API (#645) and dashboard/UX (#650): the open-core producer API, its consumers, and retiring the Feature-labelled UI drift."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-01T00:00:00Z"
---

# API & Dashboard — Domain Plan

> **Status note (2026-11-01, #6915).** The Mission Status Read API's Java service and the `mission-status` / `mission-write` contracts now live in `spec-kitty-events` (`service/`, `contracts/`; ADR [`2026-10-29-1`](/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events.md)), which releases them on the `service-v*` line. Core pins the read service (`pins/read-service.source.yaml`, `service-v0.1.0-rc.1`) for CI conformance only, and core's `services/` copy is removed. Where this document says the service is in-repo or is to start in-repo, read it as history.

**Audience:** the project maintainer — technical, time-pressed, wants signal over ritual.

> **Status: durable domain plan (throughline).** Unlike the release-scoped
> `docs/plans/` working notes that follow the distil-then-retire lifecycle, this
> document is one of the **standing domain throughlines** meant to persist across
> releases. It is the index and the "why" for the **application/mission-data API and
> the dashboard/UX** surface; the release milestones and epics it references are the
> "what ships when." Where a release plan and this plan disagree on *scope of the
> domain*, this plan is the canonical map; where they disagree on *what ships in a given
> tag*, the milestone roadmap and the owning epic win. Keep this plan factual and
> current; do not let it accrete release-scoped tracking that belongs in an epic.

---

## 1. Purpose & scope

**Purpose.** Give the **application/mission-data API and the dashboard** a single durable
home that states the *invariants* the surface must hold, groups the domain's lasting
sub-areas, and points at the epics and design records that carry the work. Before this
plan, this surface had no standalone throughline. This plan makes the throughline
explicit and becomes the domain's index. It is a sibling to the [Doctrine & Charter
Domain Plan](/plans/domains/doctrine-charter-domain-plan.md), the [Packs Extraction Domain
Plan](/plans/domains/packs-extraction-domain-plan.md), and (until its 2026-09-06 retirement,
Convergence #3881) the SaaS & Hosted Sync domain plan.

**In scope — the application surface.** "API & dashboard" here means the data surface the
project's own consumers read mission state from, and the UX that renders it:

- **The application / mission-data API (#645, Epic: Stable Application API Surface)** —
  the stable, versioned surface that exposes mission and work-package state (the status
  projection reduced from `status.events.jsonl` — see [status-model](/architecture/status-model.md))
  to the dashboard and any external application consumer, so consumers bind to a
  documented data contract, not to internal reducers or on-disk file shapes.
- **The dashboard / UX (#650)** — the mission dashboard that renders that data: the
  WP-lane board, the mission and work-package views, and the localhost daemon surface.
  **Direction (2026-10-01):** the CLI-bundled dashboard is deleted **first** (#5530,
  operator decision 2026-10-01), ahead of the read API; the Mission Status Read API
  (#5528), reader re-pointing (#5532) and route rehoming (#5533) continue afterwards as
  the replacement read path. A replacement UI is built in its own repository and consumes
  the Mission Status Read API ([ADR 2026-10-01-2](/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction.md), Accepted 2026-10-12).
  **Direction (2026-10-12):** that read API is the **open-core producer** surface (internally
  "Build Kitty") — the stable entry point to ledger and event data the free CLI exposes — and
  its **backend is now GA-gating**. The replacement UI and any multiplayer surface are the
  **consumer** side ("Multiplayer Mode," Team Kitty), consuming the producer API across its
  public contract (see §3.1, §6).
- **Terminology fidelity in the UI (#650)** — the dashboard renders the **Mission** canon
  end to end; the historical `Feature`-labelled UI drift is retired (see §3.3). This is a
  drift-elimination goal, not new vocabulary.

**Explicit boundary / non-goal (FR-004) — the two things called "API".**

> **This plan owns the application/mission-data API + dashboard. It is NOT the doctrine &
> charter *Python import surface*.** There are two distinct surfaces the corpus calls an
> "API," and conflating them is the load-bearing miscategorisation this boundary exists to
> prevent:
>
> 1. **The application/mission-data API — THIS plan (#645).** The *data* surface: mission
>    and WP state, the reduced status projection, consumed by the dashboard and external
>    application consumers over a documented data contract.
> 2. **The doctrine & charter public import surface — [Doctrine & Charter Domain Plan
>    §3.6](/plans/domains/doctrine-charter-domain-plan.md) ("Stable public API surface for doctrine &
>    charter"), design-spike #3179.** A *different* API: the **Python import / single-
>    entry-point** surface for the doctrine modules — the `runtime → charter → doctrine`
>    layering where the runtime reaches doctrine *through* the charter proxy, never
>    directly (`doctrine/__init__.py` declares 3 public names while ~79 files reach past it
>    across ~30 submodule paths, with no architectural test pinning the public surface).
>    That is a code-import boundary enforced by a layer test — **not** a data API consumed
>    by a UI.
>
> **The shared-epic subtlety.** §3.6 records that #3179 **reconciles its epic home to
> #645** because it is a direct instance of #645's single-entry-point *pattern* (the
> #645/#460 service-extraction → typed-contract → architectural-test sequence). #645 is
> therefore a **shared epic with two facets**: (a) the **application/mission-data API
> surface + dashboard** slice — **this plan's** — and (b) the **doctrine-module Python
> import surface** slice — **§3.6's**. The seam: **the importable Python entry-point for
> the doctrine modules is §3.6's and is not restated here; the application data contract
> the dashboard consumes is this plan's and is not restated there.** Cross-reference §3.6
> when a change touches both — do not duplicate it.

**Why a durable domain plan and not a release plan.** The surface is governed by standing
invariants — an application consumer binds to a documented, versioned data contract, never
to internal reducers or file shapes; the dashboard never asserts UI behaviour it cannot
prove (frontend can fail silently); and the UI speaks the Mission canon, never re-drifting
to a `Feature` label. Those invariants outlive any one tag; the experience-shaped delivery
(deferred to the 4.x line, see §5) churns beneath them.

---

## 2. Where API/dashboard planning lives today (honest inventory)

There has been **no standalone API/dashboard throughline** before this document. The
surface was distributed across two surfaces:

1. **[Status model architecture](/architecture/status-model.md)** — the append-only
   `status.events.jsonl` event log and its `reduce()` projection that any mission-data API
   must expose. It is the data source of record, not an API/dashboard plan.
2. **The epics themselves** — **#645** (Epic: Stable Application API Surface) and **#650**
   (dashboard/UX, including the `Feature`-label drift retirement). Issue-tracker groupings
   with scope bullets, **not written plans.** Experience-shaped delivery was deferred to
   3.3.x by the [3.2.x milestone roadmap](/plans/3-2-x-milestone-roadmap.md); 3.3.x was retired
   on 2026-08-23 without shipping. #645 is now on the **4.x Work** milestone and #650 in
   **Product backlog** (checked 2026-09-30), and the
   [4.0.0 Milestone Roadmap](/plans/4-0-0-milestone-roadmap.md) (Theme 3), as re-anchored
   2026-10-12, makes the **mission-status API backend GA-gating** (the open-core producer
   surface) and #645 GA-gating as the charter-extraction precondition.

**This plan now becomes the domain's index.** It ties #645 and #650 together under one set
of invariants and surfaces the gaps they leave open (§4), and it draws the boundary with
the doctrine-charter public-import surface (§1, §3.6-cross-ref) that shares the word "API"
and, now, the #645 epic home.

---

## 3. Standing concerns — the durable spine

The domain divides into three lasting sub-areas. Each states the **invariant** it must
hold (the durable "why"), then lists the **currently open work** (the release-scoped
"what," which turns over across versions).

### 3.1 The application/mission-data API contract

**Invariant.** External application consumers and the dashboard bind to **one documented,
versioned data contract** for mission and work-package state — never to internal reducers,
event-log internals, or on-disk file shapes. The contract exposes the reduced status
projection as its stable surface; internal churn behind it is not externally visible.

**Design of record.** Epic **#645** (Stable Application API Surface), whose
service-extraction → typed-contract → architectural-test single-entry-point pattern
(the #645/#460 precedent) is the shape of the contract; the
[status model](/architecture/status-model.md) projection as the data
source the contract exposes. [ADR 2026-10-01-2](/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction.md) (Accepted 2026-10-12) names the contract the
**Mission Status Read API** and frames it as the **open-core producer surface**, not a hosted
Team Kitty surface. It has two granularities: an **overview** built from `meta.json` and the
event ledger, and a **detail** view with each WP's authored and resolved state and its
assignment. It is read-only and independent of drain. The CLI's own read path is an in-process
Python module in the `specify_cli` layer behind one read seam; the external form is a
read-only Java service (`services/mission-status-api/`) that is to **start in-repo as a modular
component and be extracted as needed as an open-core surface — never into a Team Kitty repo**
(direction/target state: the service directory does not exist yet; `contracts/mission-status/`
and the conformance fixtures already ship and stay canonical beside the Python reducer, ADR
Amendment 2026-10-12). **The backend is now GA-gating** (roadmap, Theme 3).

**Open work.** Enumerate and version the mission-data contract (the #645 application-data
facet — *distinct from* the #3179 doctrine-import facet §3.6 owns), then pin it with a
contract test so a consumer can rely on it across versions. Then fold the existing readers
into it (#5532): `agent tasks status --json` and the orchestrator-api
`mission-state` and `list-ready` reads (the former `dashboard --json` reader was deleted
with the dashboard, #5530, before this step). Land a gate against bypassing it (ADR D-5).

### 3.2 The dashboard / UX surface

**Invariant.** The dashboard renders mission and WP state truthfully and **never asserts a
UI behaviour it cannot prove** — a frontend can fail silently (a caught 404 shows a
fallback), so dashboard behaviour is verified by a browser-level regression, not inferred
from an API response. The localhost daemon surface stays loopback-only.

**Design of record.** Epic **#650** (dashboard/UX); the browser-level UI regression
discipline recorded in the repository guidelines (the WP-modal Playwright guard is the
standing example — API responses do not prove the UI works).

**Open work.** The experience-shaped dashboard delivery deferred beyond 4.0.0 (§5): the
WP-lane board, mission/WP views, and their browser-verified regressions. These now land
in the replacement UI's own repository, which consumes the read API. In this repository
the order changed (operator decision 2026-10-01): `src/specify_cli/dashboard/` and
`spec-kitty dashboard` are deleted **first** (#5530), without a deprecation release; the
read API (#5528), reader re-pointing (#5532) and rehoming each former route (#5533)
follow as the replacement read path (ADR D-1, D-8). The localhost daemon invariant lapsed
with the deletion.

### 3.3 Terminology fidelity in the UI (retiring the `Feature` drift)

**Invariant.** The dashboard speaks the **Mission** canon end to end. The historical
`Feature`-labelled UI drift — a legacy label that leaked into the dashboard against the
Terminology Canon — is **retired**, and the UI never re-introduces a `Feature` label for
a Mission-domain object.

**Design of record.** Epic **#650** carries this as an explicit goal: kill the legacy
`Feature`-labelled UI drift in favour of the Mission canon. The Terminology Canon (Mission,
never "feature") is the standard the retirement restores; here it is a
**reviewer-verified** fidelity concern, since the terminology guard does not scan the UI
label surface.

**Open work.** Complete the #650 label-retirement sweep so no dashboard view renders the
legacy `Feature` label, and keep it retired as the dashboard delivery lands in the 4.x line.

---

## 4. Known gaps

1. **The #645 two-facet split is unreconciled in the tracker.** #645 now hosts both the
   application-data API facet (this plan, §3.1) and the doctrine-module import surface
   facet (doctrine-charter §3.6, #3179 reparented under #645). Without a facet split in the
   epic, a PO cannot tell which slice is the data contract and which is the Python import
   surface. §1's boundary statement is the reconciling map; the tracker should mirror it.
2. **The mission-data contract is unenumerated.** The §3.1 invariant asserts a versioned
   data contract, but no contract or contract test exists yet — the dashboard binds to the
   projection directly today. This is the domain's key structural gap, gated behind #645.
   The readers do not disagree about ordering: `reduce()`, `materialize_snapshot()` and the
   deleted dashboard's reads all reach the same wall-clock fold
   (`spec_kitty_events.diary.reduce_parsed`, ordered by `(at, event_id)` with the #4941
   approved-departure lift). What remains open is narrower than the two-reducer split this
   entry used to describe: a non-approval transition minted on a clock behind the event it
   follows still sorts before that event, and Lamport-primary ordering is a post-GA
   direction (#6609) that needs its own ADR.
3. **Dashboard delivery is deferred, its invariants are not.** The experience-shaped
   delivery is a post-4.0.0 concern (§5), but the invariants (contract-bound consumers,
   browser-proven UI, Mission-canon labels) are in force now and must not regress as the
   surface is built.
4. **Artifact and governance views have no home outside the dashboard.** The dashboard also
   serves mission artifacts (research, contracts, checklists, dossier) and governance views
   (charter, lint, glossary). They are not mission status. The dashboard is now deleted
   first (#5530), so these views have no read surface until each is rehomed in its own
   context (#5533; #954, #955 and a follow-up), as the ADR's route table lists.

---

## 5. Release-scoped view (the "what ships when")

This plan tracks the **why** (the API/dashboard invariants and sub-areas); the epics track
the **what-ships-when**. The table below is a snapshot for orientation, not a schedule.
Verify live state via `gh issue view <n> --repo spec-kitty/spec-kitty` before acting.

| Work | Sub-area (§3) | Owning epic | Milestone (epic, checked 2026-09-30) |
|---|---|---|---|
| Enumerate + version the mission-data API contract | Data API contract (3.1) | #645 (application-data facet) | 4.x Work |
| Mission Status Read API (overview + detail) and folding the existing readers into it | Data API contract (3.1) | #645 (#956, #957, #2789) | 4.x Work |
| Remove the CLI-bundled dashboard (deleted first; read API, re-pointing and rehoming follow) | Dashboard/UX (3.2) | #645 / #650 (#5530; then #5528, #5532, #5533) | 4.x Work |
| Dashboard WP-lane board + mission/WP views | Dashboard/UX (3.2) | #650 | Product backlog |
| Retire the legacy `Feature`-labelled UI drift | Terminology fidelity (3.3) | #650 | Product backlog |

*Read the WHY in §3; the epic tracks the WHAT-ships-when. The `Feature`-label row is the
drift being killed — not a live UI label.*

---

## 6. Cross-references

**Sibling domain throughlines (the durable spine of `docs/plans/`):**

- **Doctrine & charter** — [Doctrine & Charter Domain Plan](/plans/domains/doctrine-charter-domain-plan.md).
  Its **§3.6 (Stable public API surface for doctrine & charter)** is the **non-goal
  boundary** for this plan (§1): §3.6 owns the doctrine/charter **Python import / single-
  entry-point** surface (#3179), a *different* API from this plan's **application/mission-
  data** surface — even though #3179 now shares the #645 epic home as a separate facet.
  *(At this plan's commit the doctrine-charter plan still lives at
  `docs/plans/doctrine-charter-domain-plan.md`; the domains/ migration WP moves it and
  repoints these links.)*
- **Packs extraction** — [Packs Extraction Domain Plan](/plans/domains/packs-extraction-domain-plan.md).
- **SaaS & hosted sync** — domain plan retired 2026-09-06 (Convergence #3881). The former
  in-process sync projection no longer exists: hosted/team rendering is server-side in the
  authoritative upstream repos, and this repo's dashboard data surface is consumed locally,
  with hosted status delivered via `zeitgeist_client` (ephemeral by design). See the
  convergence-retirement ADR.

**Design of record:**

- [Status model architecture](/architecture/status-model.md) — the
  `status.events.jsonl` event log and `reduce()` projection the mission-data API exposes.
- [ADR 2026-10-01-2](/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction.md) — the Mission Status Read API and the removal of the CLI-bundled dashboard
  (**Accepted 2026-10-12**: the open-core producer surface; the service is to start in-repo and be extracted when frozen).
- [4.0.0 Milestone Roadmap](/plans/4-0-0-milestone-roadmap.md) — the active cycle; Theme 3 makes
  the mission-status API backend GA-gating (2026-10-12 re-anchor).
- [3.2.x milestone roadmap](/plans/3-2-x-milestone-roadmap.md) — *superseded, prior cycle.*
  Recorded the original deferral of experience-shaped (UX/dashboard) work to the retired
  3.3.x milestone.

**Epics:** #645 (Stable Application API Surface — application-data facet here; the #3179
doctrine-import facet is doctrine-charter §3.6), #650 (dashboard/UX + `Feature`-drift
retirement).

**Plans index:** [docs/plans/index.md](/plans/index.md).

## Related

- [ADR: a mission status read API replaces the CLI-bundled dashboard (extract and replace)](/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction.md)
- [Status Model: Operator Documentation](/architecture/status-model.md)
- [4.0.0 Milestone — Roadmap](/plans/4-0-0-milestone-roadmap.md)
- [Plans](/plans/index.md)
- [Doctrine & Charter — Domain Plan](/plans/domains/doctrine-charter-domain-plan.md)
- [Packs Extraction — Domain Plan](/plans/domains/packs-extraction-domain-plan.md)

## Audience

- [Stakeholder Persona: Maintainer](/context/audience/internal/maintainer.md) - Written for the Maintainer reader.

## References

- [3.2.x Open-Core Delivery Plan](https://github.com/spec-kitty/spec-kitty/blob/main/docs/archive/plans/3-2-x-open-core-delivery-plan.md)
