# Workplan Terminology Legacy Retirement Backlog

Date: 2026-07-08  
Owner: `STATE-WP-0069` (child of `CUST-WP-0055`)  
Baseline: `the-custodian/docs/evidence/workstream-terminology-baseline-20260708.json`

This backlog ranks every metered legacy `workstream` interface still present in
State Hub. **Removal requires legacy-meter evidence** — zero measured calls in
the review window, replacement verified, no manual hold.

Authoritative interface matrix: `docs/workplan-terminology-transition.md`.

## Retirement rule (unchanged)

1. Registered in `legacy-meter`
2. Replacement reference verified
3. No manual hold
4. Zero measured calls in the review window

Activity-core runs the weekly review; State Hub owns usage state and removal.

## Scan allowlist (grep tooling)

Exclude these paths from non-compat prose counts (see
`the-custodian/tools/scan_workstream_allowlist.yaml`):

| Area | Paths |
| --- | --- |
| Compat REST | `api/routers/workstreams.py`, `api/routers/workstream_dependencies.py` |
| Legacy meter | `api/routers/legacy_meter.py`, `api/services/legacy_meter.py`, `api/models/legacy_meter.py`, `migrations/` |
| MCP aliases | `mcp_server/` |
| Transition docs | `docs/workplan-terminology-transition.md`, this file, `docs/nats-event-subjects.md` |
| Regression tests | `tests/test_legacy_meter.py`, `tests/test_routers_core.py` |
| CLI compat | `custodian_cli.py`, `scripts/consistency_check.py` |

Dashboard prose is **not** allowlisted — `STATE-WP-0069` T02 drives it to zero
`prose:workstream` in `dashboard/src/`.

## Ranked backlog

Risk order: REST > MCP > events > dashboard prose > internal identifiers.

| Phase | Legacy-meter key | Replacement | Risk | Owner task |
| ---: | --- | --- | --- | --- |
| 1 | `rest_api:GET /workstreams/` | `GET /workplans/` | REST | T04 |
| 1 | `rest_api:POST /workstreams/` | `POST /workplans/` | REST | T04 |
| 1 | `rest_api:GET /workstreams/{workstream_id}` | `GET /workplans/{workplan_id}` | REST | T04 |
| 1 | `rest_api:PATCH /workstreams/{workstream_id}` | `PATCH /workplans/{workplan_id}` | REST | T04 |
| 1 | `rest_api:DELETE /workstreams/{workstream_id}` | `DELETE /workplans/{workplan_id}` | REST | T04 |
| 1 | `rest_api:GET /workstreams/workplan-index` | `GET /workplans/index` | REST | T04 |
| 2 | `rest_api:GET /workstreams/{workstream_id}/dependencies/` | `GET /workplans/{workplan_id}/dependencies/` | REST | T04 |
| 2 | `rest_api:POST /workstreams/{workstream_id}/dependencies/` | `POST /workplans/{workplan_id}/dependencies/` | REST | T04 |
| 2 | `rest_api:DELETE /workstreams/{workstream_id}/dependencies/{dep_id}` | `DELETE /workplans/{workplan_id}/dependencies/{dep_id}` | REST | T04 |
| 2 | `rest_api:PATCH /execution/workstreams/{workstream_id}/intent` | `PATCH /execution/workplans/{workplan_id}/intent` | REST | T04 |
| 3 | `mcp:create_workstream` | `create_workplan` | MCP | T03 |
| 3 | `mcp:update_workstream` | `update_workplan` | MCP | T03 |
| 3 | `mcp:update_workstream_status` | `update_workplan_status` | MCP | T03 |
| 3 | `mcp:list_workstreams` | `list_workplans` | MCP | T03 |
| 3 | `state://workstreams/{topic_slug}` | `state://workplans/{topic_slug}` (proposed) | MCP resource | T03 |
| 4 | `event_subject:org.statehub.workstream.completed` | `org.statehub.workplan.completed` | Event | T05 |
| 5 | Dashboard nav label `Workstreams` | `Workplans` (URL compat retained) | Prose | T02 |
| 5 | `dashboard/src/index.md` user-facing copy | workplan-first strings | Prose | T02 |
| 6 | `open_workstreams` summary cache key | `open_workplans` | Internal | T06 |
| 6 | `flows/workstream.yaml` entity id | `flows/workplan.yaml` (`custodian.workplan.v1`) | Internal | T06 (workplan flow shipped; workstream yaml retained) |

### Query-param aliases (not separately metered today)

These accept `workstream_id` alongside `workplan_id` on preferred routes:

- `GET /tasks/` — `api/routers/tasks.py`
- `GET /decisions/` — `api/routers/decisions.py`
- `GET /token-events/` — `api/routers/token_events.py`

Retire param aliases in T04 after route retirement; document callers via
weekly review component headers (`X-StateHub-Component`).

## Grep budget by phase

Measured with:

```bash
python ~/the-custodian/tools/scan_workstream_terminology.py --repo state-hub --apply-allowlist --json
python ~/the-custodian/tools/scan_workstream_terminology.py --repo state-hub --check-prose-gate
```

| Phase | Target |
| --- | --- |
| After T02 | Zero `prose:workstream` in `dashboard/src/` |
| After T03 | MCP tool docstrings and error messages workplan-first |
| After T04 | OpenAPI lists `/workplans` only; `/workstreams` returns 410 or unmounted |
| After T07 | Total repo hits reduced ≥50% from 2026-07-08 baseline |

## Sequencing

```
T01 backlog (this document) ──► T02 dashboard prose
                           ├─► T03 MCP deprecation warnings → alias removal
                           ├─► T04 REST retirement (per-key zero usage)
                           ├─► T05 stop dual-publish (after CUST-WP-0055 T03)
                           ├─► T06 internal renames
                           └─► T07 closeout
```

## Related workplans

- `STATE-WP-0054` — compatibility layer and legacy-meter (finished)
- `STATE-WP-0069` — this retirement plan
- `CUST-WP-0055` — fleet coordination; activity-core catalog alignment (T03)