--- id: STATE-WP-0070 type: workplan title: "Workplan terminology phase-2 legacy retirement" domain: infotech repo: state-hub status: active owner: codex topic_slug: custodian planning_priority: medium planning_order: 70 created: "2026-07-09" updated: "2026-07-10" state_hub_workstream_id: "9aa92529-6ee8-4b3f-b573-78b0ef8d9788" --- # STATE-WP-0070 — Workplan terminology phase-2 legacy retirement **Parent:** `STATE-WP-0069` (finished 2026-07-08, archived). **Prerequisite:** Caller migrations shipped (`b05ca2c+`), identity headers on fix-consistency and dashboard loaders, activity-core progress dual-write stopped. ## Goal Drive legacy-meter counts to zero per key, then retire remaining `/workstreams` routes, MCP aliases, and internal dual-keys. All removals remain **meter-gated** (seven consecutive zero-usage windows). ## Context Live meter (2026-07-09) still shows ~150k weekly legacy GET calls — attributed to `unknown` until identity headers deploy and remote fix-consistency hosts pull latest `state-hub`. Evidence: `docs/evidence/legacy-meter-weekly-review-20260708.json`, caller inventory: `docs/evidence/workstream-caller-inventory-20260708.md`. ## Task: Deploy caller migrations and verify meter attribution ```task id: STATE-WP-0070-T01 status: done priority: high state_hub_task_id: "04cb3a3a-fe52-480b-816b-37c8f8fbe5ee" ``` 1. Pull `state-hub` ≥ `b05ca2c` on all fix-consistency hosts (railiance01 sweep, WSL workstation, cluster runners). 2. Run full `statehub fix-consistency --all` (or scheduled sweep). 3. Capture weekly review; confirm `X-StateHub-Component` buckets name `state-hub.fix-consistency` instead of `unknown`. 4. Expect `GET /workstreams/*` window counts to fall sharply. Done when a post-deploy capture shows attributed components and declining legacy REST counts. Progress 2026-07-09: identity headers landed on fix-consistency, custodian_cli, dashboard loaders, cleanup_stale_tasks, validate_repo_adr. Local sweep attributes `state-hub.fix-consistency` on task-create metering. railiance01 still at `050cbbc`; `git pull` blocked (`.git/FETCH_HEAD` permission denied) — needs operator deploy. Hub message posted to `ops-warden` (2026-07-09); runbook at `docs/evidence/railiance01-state-hub-deploy-20260709.md`. Operational deploy tracked in **`STATE-WP-0071`** (finished 2026-07-09 via Ralph loop). Deploy evidence: `docs/evidence/legacy-meter-weekly-review-20260709.json`; railiance01 SHAs `state-hub@1382992`, `activity-core@1a06368`; k8s rollout healthy. Legacy GET decline monitoring continues week-over-week per acceptance gate. ## Task: Retire remaining REST `/workstreams` routes per key ```task id: STATE-WP-0070-T02 status: done priority: high state_hub_task_id: "13122195-3b7e-4e22-a5e8-4ebe7e9a093f" ``` For each key in `docs/workplan-terminology-legacy-retirement-backlog.md` phase 1–2 still showing usage: - `GET/POST/PATCH /workstreams/*` - dependency and execution intent aliases Return **410 Gone** (matching DELETE pattern) when legacy-meter shows seven consecutive zero-usage windows. Update tests and capture evidence per retirement. Progress 2026-07-09: `GET /workstreams/workplan-index` → **410 Gone** (zero-usage candidate in 1-day capture). `DELETE /workstreams/{id}` already 410 from STATE-WP-0069. Next candidates when meter clears: `POST .../dependencies/` (0 calls in 1-day window). Progress 2026-07-10 (8h captures): phase-1 `GET/POST /workstreams/*` keys show **0 calls** and are retirement candidates (`legacy-meter-weekly-review-20260710.json`). Streak ~**2/7** consecutive 8h zero windows per key (since post-0072 decline). Residual: `POST /progress/ workstream_id` — 3 calls/window (`unknown`). Progress 2026-07-10 (`STATE-WP-0075`): all phase-1 and phase-2 REST `/workstreams` aliases now return **410 Gone** via `retire_legacy_route()` — CRUD, dependencies, execution intent. Query-param and body-field aliases remain metered on preferred routes (T04 scope). Backlog updated; tests green. ## Task: MCP alias removal (Phase 2) ```task id: STATE-WP-0070-T03 status: progress priority: medium state_hub_task_id: "e2b9015a-d157-4677-b700-165f1cf7e2af" ``` Remove `create_workstream`, `update_workstream`, `list_workstreams`, `update_workstream_status`, and `state://workstreams/{topic_slug}` when MCP procedure keys hit zero usage for seven windows. Keep `TOOLS.md` migration notes. Progress 2026-07-10: gate was unstartable — MCP alias usage was never metered (deprecation notices only, no `mcp:*` interfaces registered). Fixed: `_meter_legacy_mcp()` in `mcp_server/server.py` posts `/legacy-meter/usage` (kind `mcp_tool`, component `state-hub.mcp`) from all four legacy tools and the legacy resource; all five backlog phase-3 keys registered on the meter, so zero-window streaks accrue from 2026-07-10. Note: `mcp:list_workstreams` shows 1 verification call in the 2026-07-10 window — streak counts from the next window. Removal remains gated on 7 consecutive zero windows. Recheck 2026-07-10: pytest was recording real alias usage on the live meter (tests monkeypatch `_get`/`_post` but the meter helper uses `_client()`), which would reset streaks every run. Guarded with `STATEHUB_MCP_LEGACY_METER=off`, set in `tests/conftest.py`; verified before/after counts flat across the alias test suite. Stray counts from verification + first test run (create=2, list=2, resource=1) clear at next window rollover. **Deploy note:** the long-running dev-hub MCP process (:8001) predates this change and must be restarted (`make mcp-http`) before its zero windows are trustworthy — unmetered live usage would look like zero. ## Task: Internal dual-key and param alias cleanup ```task id: STATE-WP-0070-T04 status: progress priority: low state_hub_task_id: "18af98bf-c74e-47c8-948a-e713cff88bb8" ``` - Drop `open_workstreams` from `/state/summary` when meter clears. - Remove `workstream_id` query/body aliases on preferred routes. - Retire `flows/workstream.yaml` when no callers remain. Progress 2026-07-10: residual `POST /progress/ workstream_id` (3 calls/8h, `unknown`) traced to `.custodian-brief.md` files labelling workplans `workstream_id:` — agents copy the field name into session-close curl posts. Brief generator fixed (`consistency_check.py` → `workplan_id:`); briefs regenerate on each repo's next fix-consistency sweep. Expect this key to decay to zero once briefs refresh fleet-wide. ## Task: Closeout and fleet gate ```task id: STATE-WP-0070-T05 status: todo priority: medium state_hub_task_id: "dcc81665-ef84-4c0a-a88f-d8afc0d1bbb9" ``` Re-run `scan_workstream_terminology.py`, grep budget check, full test suite, archive this workplan, notify CUST-WP-0055 fleet gate complete. Done when legacy-meter weekly review shows no active legacy REST keys and MCP aliases are removed or marked retired.