# UI v2 Rewire Sprint Planning Guide

Status: Planning-only guidance
Date: 2026-02-20

This guide defines how to decompose the canonical redesign into many implementation sprints.

## 1) Required reading order for planners

1. `source-of-truth.md`
2. `authority-matrix.md`
3. `pack-22.md` plus authoritative fallback packs for selected capability area
4. Current UI/backend implementation (`src/Web/**`, `src/**/WebService/**`) for feasibility and contract checks

Do not start sprint writing from raw pack text alone.

## 2) Planning constraints

- Higher pack number is authoritative for overlaps.
- Keep redesign deterministic and offline-capable.
- Treat IA route migration and backend contract/migration work as separate tasks.
- Backend dependency sprints (contracts + DB migrations) must complete before FE cutover tasks are marked `DONE`.
- Preserve migration safety with redirect/alias tasks in rollout sprints.

## 3) Recommended multi-sprint decomposition

Use independent streams so multiple teams can run in parallel.

| Stream | Scope | Primary packs |
| --- | --- | --- |
| `S0-SpecFreeze` | lock canonical IA terms, ownership, endpoint ledger baseline | `pack-22.md`, `source-of-truth.md`, `authority-matrix.md` |
| `S1-BackendFoundation` | global context, releases read models, topology, security disposition, migrations | `pack-22.md`, `S00_endpoint_contract_ledger_v2_pack22.md` |
| `S2-NavShell` | root nav rename and global context top bar | `pack-22.md`, `pack-16.md` |
| `S3-Releases` | release list/detail/activity/approvals consolidation | `pack-22.md`, `pack-12.md`, `pack-13.md`, `pack-14.md`, `pack-17.md` |
| `S4-TopologyOps` | topology module and operations boundary cleanup | `pack-22.md`, `pack-18.md`, `pack-15.md` |
| `S5-SecurityEvidence` | findings/disposition/sbom explorer + evidence linkage | `pack-22.md`, `pack-19.md`, `pack-20.md` |
| `S6-IntegrationsAdmin` | feeds/vex sources config + governance surfaces | `pack-22.md`, `pack-10.md`, `pack-21.md` |
| `S7-CutoverQA` | redirects, deep links, Playwright conformity, release readiness | all active authority packs |

## 4) Endpoint and contract investigation workflow

Backend coverage is incomplete for Pack 22. Every sprint must include an explicit endpoint contract pass.

### 4.1 For each planned screen, classify backend status

Use one of these states:

- `EXISTS_COMPAT` - endpoint exists and contract matches target UI
- `EXISTS_ADAPT` - endpoint exists but response/request shape or semantics must be adapted
- `MISSING_NEW` - endpoint does not exist and must be specified/implemented

### 4.2 Required investigation steps

1. Locate current route/component wiring in UI.
2. Locate current API client call(s) in UI client layer.
3. Locate backend endpoint(s) across service modules.
4. Compare current contract to target pack behavior.
5. Record status (`EXISTS_COMPAT` / `EXISTS_ADAPT` / `MISSING_NEW`) in the ledger.
6. If `MISSING_NEW`, write contract + DB migration tasks with request/response schema, auth scope, and deterministic behavior requirements.

### 4.3 Search anchors (read-only references)

- UI routing and nav:
  - `src/Web/StellaOps.Web/src/app/app.routes.ts`
  - `src/Web/StellaOps.Web/src/app/layout/app-sidebar/app-sidebar.component.ts`
  - `src/Web/StellaOps.Web/src/app/routes/*.ts`
- UI API clients:
  - `src/Web/StellaOps.Web/src/app/core/api/*.ts`
- Backend endpoint surfaces:
  - `src/**/WebService/Endpoints/*.cs`
  - `src/**/Infrastructure/**` for data dependencies
- Platform DB migrations:
  - `src/Platform/__Libraries/StellaOps.Platform.Database/Migrations/Release/*.sql`

## 5) Mandatory sprint ticket fields (for every UI feature ticket)

Use this minimum structure in planning docs:

```md
### <Ticket ID> - <Feature>
- Canonical source: <source-of-truth section + authority-matrix row + pack sections>
- UI scope: <routes/components>
- Backend contract status: EXISTS_COMPAT | EXISTS_ADAPT | MISSING_NEW
- Endpoint(s): <current or proposed>
- DB migration impact: <existing migration or new migration file>
- Auth scope impact: <new/changed scopes>
- Offline/determinism impact: <none or required behavior>
- Redirect/deprecation impact: <legacy paths>
- Evidence required: <tests, screenshots, contract tests>
```

## 6) First planning backlog (must be created before build sprints)

1. Backend dependency sprint for global context and releases read-model contracts (`/api/v2/context/*`, `/api/v2/releases/*`).
2. Backend dependency sprint for topology inventory contracts (`/api/v2/topology/*`) and migrations.
3. Backend dependency sprint for security disposition contracts (`/api/v2/security/findings`, `/api/v2/security/disposition`).
4. FE nav migration sprint from old roots to `Dashboard/Releases/Security/Evidence/Topology/Operations/Integrations/Administration`.
5. Route alias/deprecation sprint from legacy domains and paths.

## 7) Definition of ready for implementation sprint

A capability is ready only when:

- authoritative pack sections are listed,
- endpoint status is classified for each screen,
- missing contracts are specified,
- DB migrations are identified,
- scope/permission changes are identified,
- migration/redirect handling is scoped,
- test evidence expectations are explicit.