propose(STATE-WP-0069): workplan terminology legacy retirement plan
Child workplan for CUST-WP-0055-T02. Phased retirement of metered /workstreams routes, MCP aliases, dashboard labels, and legacy event subjects after STATE-WP-0054 compatibility window.
This commit is contained in:
parent
612ec66a00
commit
d8808bf567
1 changed files with 244 additions and 0 deletions
|
|
@ -0,0 +1,244 @@
|
|||
---
|
||||
id: STATE-WP-0069
|
||||
type: workplan
|
||||
title: "Workplan terminology legacy retirement (State Hub)"
|
||||
domain: infotech
|
||||
repo: state-hub
|
||||
status: proposed
|
||||
owner: codex
|
||||
topic_slug: custodian
|
||||
planning_priority: medium
|
||||
planning_order: 69
|
||||
created: "2026-07-08"
|
||||
updated: "2026-07-08"
|
||||
state_hub_workstream_id: ""
|
||||
---
|
||||
|
||||
# STATE-WP-0069 — Workplan terminology legacy retirement
|
||||
|
||||
**Parent coordination:** `the-custodian/workplans/CUST-WP-0055-workplan-terminology-fleet-refactor.md`
|
||||
(T02-T01 deliverable).
|
||||
|
||||
**Prerequisite (finished):** `STATE-WP-0054` added preferred `/workplans` routes,
|
||||
dual-published completion events, `legacy-meter`, and weekly review payloads.
|
||||
Canonical guide: `docs/workplan-terminology-transition.md`.
|
||||
|
||||
## Goal
|
||||
|
||||
Retire State Hub's **metered legacy `workstream` interfaces** in safe phases after
|
||||
`legacy-meter` weekly review shows zero callers. Make `workplan` the only
|
||||
user-facing and integration term inside this repo without breaking ADR-001 file
|
||||
sync or workplan frontmatter bridges.
|
||||
|
||||
## Context
|
||||
|
||||
A fleet scan on **2026-07-08** (`the-custodian/tools/scan_workstream_terminology.py`)
|
||||
shows `state-hub` carries ~13,418 `workstream` string hits — mostly compat
|
||||
routers, tests, dashboard labels, MCP aliases, and legacy-meter registry entries.
|
||||
That volume is expected until this workplan retires interfaces deliberately.
|
||||
|
||||
Retirement rule (unchanged from STATE-WP-0054):
|
||||
|
||||
- interface registered as legacy;
|
||||
- replacement reference verified;
|
||||
- no manual hold;
|
||||
- **zero measured calls** in the review window.
|
||||
|
||||
Activity-core owns the weekly wakeup; State Hub owns usage state and removal.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Renaming workplan frontmatter field `state_hub_workstream_id` (separate bridge
|
||||
migration).
|
||||
- Physical database table/column renames (STATE-WP-0065 completed the spine).
|
||||
- Fleet-wide domain repo prose sweeps (CUST-WP-0055 T04).
|
||||
- activity-core `org.workstream.completed` catalog alignment (CUST-WP-0055 T03).
|
||||
- Removing `/workstreams` before legacy-meter proves zero callers for each key.
|
||||
|
||||
## Grep budget (non-compat prose)
|
||||
|
||||
Track via `scan_workstream_terminology.py --repo state-hub --json` with
|
||||
`the-custodian` scan allowlist (archives, legacy-meter registry, compat routers
|
||||
excluded once documented in T01).
|
||||
|
||||
| Phase | Target |
|
||||
| --- | --- |
|
||||
| After T02 | Dashboard nav + `dashboard/src/index.md` prose at zero `prose:workstream` |
|
||||
| After T03 | MCP tool docstrings and error messages workplan-first |
|
||||
| After T04 | Public OpenAPI lists `/workplans` only; `/workstreams` removed or 410 |
|
||||
| After T07 | Total repo hits reduced ≥50% from 2026-07-08 baseline |
|
||||
|
||||
## Task: Refresh inventory and ranked retirement backlog
|
||||
|
||||
```task
|
||||
id: STATE-WP-0069-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: ""
|
||||
```
|
||||
|
||||
Reconcile `docs/workplan-terminology-transition.md` against the live codebase.
|
||||
Produce `docs/workplan-terminology-legacy-retirement-backlog.md` ranking every
|
||||
remaining legacy interface by:
|
||||
|
||||
- legacy-meter key;
|
||||
- replacement ref;
|
||||
- risk (REST > MCP > events > dashboard prose);
|
||||
- last-seen and prior-week usage from `/legacy-meter/weekly-review`.
|
||||
|
||||
Include explicit allowlist paths for grep/scan tooling (compat routers, test
|
||||
fixtures, migration history). Store 2026-07-08 baseline JSON reference from
|
||||
CUST-WP-0055 T01.
|
||||
|
||||
Done when the backlog is reviewed and each interface has a phase assignment (T02–T06).
|
||||
|
||||
## Task: Dashboard and operator docs — workplan-first labels
|
||||
|
||||
```task
|
||||
id: STATE-WP-0069-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: ""
|
||||
```
|
||||
|
||||
Update Observable dashboard navigation, page titles, chart empty-state copy, and
|
||||
operator docs to say **workplan** in user-facing prose:
|
||||
|
||||
- `dashboard/observablehq.config.js` nav entries (`/workstreams` → `/workplans`
|
||||
where routes exist);
|
||||
- `dashboard/src/index.md` and workplan detail pages;
|
||||
- `README.md` legacy table footnotes.
|
||||
|
||||
Keep URL redirects or compat notes for bookmarked `/workstreams` paths until T04.
|
||||
Add dashboard tests for renamed labels.
|
||||
|
||||
Done when dashboard `npm test` passes and scan shows zero `prose:workstream` in
|
||||
`dashboard/src/` (excluding explicit legacy footnotes).
|
||||
|
||||
## Task: MCP legacy alias retirement
|
||||
|
||||
```task
|
||||
id: STATE-WP-0069-T03
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: ""
|
||||
```
|
||||
|
||||
Retire MCP surfaces that still lead with `workstream` terminology:
|
||||
|
||||
- `state://workstreams/{topic_slug}` resource;
|
||||
- any `create_workstream` / `update_workstream` / `list_workstreams` aliases if
|
||||
still registered alongside `create_workplan` variants;
|
||||
- prose in `get_domain_summary` (`open_workstreams`, `needs_workplan` messages).
|
||||
|
||||
Phase 1: deprecation warnings in tool responses pointing to workplan-named tools.
|
||||
Phase 2: remove aliases when legacy-meter shows zero MCP procedure calls for
|
||||
seven consecutive review windows.
|
||||
|
||||
Done when MCP clients use workplan-named tools only and legacy MCP keys are
|
||||
removed from the registry or marked `retired` with zero usage.
|
||||
|
||||
## Task: REST `/workstreams` compat router retirement
|
||||
|
||||
```task
|
||||
id: STATE-WP-0069-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: ""
|
||||
```
|
||||
|
||||
Highest-risk phase. Remove or hard-deprecate legacy REST routes in
|
||||
`api/routers/workstreams.py` once `/workplans` parity is proven and
|
||||
legacy-meter reports zero calls per key:
|
||||
|
||||
- `GET/POST /workstreams/`, `GET/PATCH/DELETE /workstreams/{id}`;
|
||||
- dependency and execution intent aliases under `/workstreams/`;
|
||||
- `workstream_id` query param aliases where `workplan_id` is sufficient.
|
||||
|
||||
Retain deprecation headers until removal. Update OpenAPI snapshot, router tests,
|
||||
and `tests/test_legacy_meter.py` retirement cases.
|
||||
|
||||
Done when OpenAPI documents `/workplans` as the public CRUD surface and
|
||||
`/workstreams` returns 410 Gone or is unmounted, with regression tests green.
|
||||
|
||||
## Task: Legacy completion event — stop dual-publish
|
||||
|
||||
```task
|
||||
id: STATE-WP-0069-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: ""
|
||||
```
|
||||
|
||||
After activity-core subscribers migrate (CUST-WP-0055 T03), stop emitting
|
||||
`org.statehub.workstream.completed` from `api/routers/workstreams.py`. Keep
|
||||
`org.statehub.workplan.completed` as the sole completion subject.
|
||||
|
||||
Register the legacy subject as `retired` in legacy-meter. Update
|
||||
`docs/nats-event-subjects.md` and envelope tests.
|
||||
|
||||
Done when only `org.statehub.workplan.completed` is published on workplan
|
||||
finish transitions and legacy-meter shows zero event consumers on the old subject.
|
||||
|
||||
## Task: Internal flows and cache identifiers
|
||||
|
||||
```task
|
||||
id: STATE-WP-0069-T06
|
||||
status: todo
|
||||
priority: low
|
||||
state_hub_task_id: ""
|
||||
```
|
||||
|
||||
Rename internal non-wire identifiers when no external client depends on them:
|
||||
|
||||
- `flows/workstream.yaml` → workplan entity type (or successor flow id);
|
||||
- `open_workstreams` keys in state summary cache → `open_workplans`;
|
||||
- test module names and comments that mislead new contributors.
|
||||
|
||||
Coordinate with hub-core if shared types leak the old term.
|
||||
|
||||
Done when internal code reads workplan-first and grep budget for
|
||||
`api:open_workstreams` hits zero.
|
||||
|
||||
## Task: Closeout — registry cleanup and verification
|
||||
|
||||
```task
|
||||
id: STATE-WP-0069-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: ""
|
||||
```
|
||||
|
||||
Final verification:
|
||||
|
||||
1. `make test` and `cd dashboard && npm test` pass.
|
||||
2. `scan_workstream_terminology.py --repo state-hub` meets phase grep budget.
|
||||
3. `legacy-meter` registry lists retired interfaces with retirement dates.
|
||||
4. `docs/workplan-terminology-transition.md` updated with retirement completion
|
||||
notes and pointers to CUST-WP-0055 T08 fleet gate.
|
||||
|
||||
Post State Hub progress note linking completion; notify CUST-WP-0055 T02 closeout.
|
||||
|
||||
Done when STATE-WP-0069 can move to `finished` and CUST-WP-0055 T02-T02 is `done`.
|
||||
|
||||
## Sequencing
|
||||
|
||||
```
|
||||
T01 inventory + backlog (blocking)
|
||||
T02 dashboard/docs (low risk, start early)
|
||||
T03 MCP aliases (parallel with T02 after T01)
|
||||
T04 REST retirement (after ≥1 zero-usage review window per route key)
|
||||
T05 event dual-publish stop (after CUST-WP-0055 T03)
|
||||
T06 internal renames (anytime after T04)
|
||||
T07 closeout
|
||||
```
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- `workplan` is the only recommended term in State Hub dashboard, README, and
|
||||
new MCP/REST docs.
|
||||
- Legacy interfaces are removed only with legacy-meter evidence, not by schedule
|
||||
alone.
|
||||
- ADR-001 `fix-consistency` and workplan file sync remain green through all
|
||||
phases.
|
||||
- No frontmatter `state_hub_workstream_id` renames in this workplan.
|
||||
Loading…
Add table
Add a link
Reference in a new issue