state-hub/workplans/STATE-WP-0070-workplan-terminology-phase2-retirement.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
STATE-WP-0070	workplan	Workplan terminology phase-2 legacy retirement	infotech	state-hub	finished	codex	custodian	medium	70	2026-07-09	2026-07-14	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

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

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.

Staged 2026-07-13 (branch state-wp-0070-legacy-retirement, unmerged): T03 removal committed (ef62cb3) — deleted create_workstream, list_workstreams, update_workstream, update_workstream_status MCP tools + state://workstreams/{topic_slug} resource + dead helpers (_LEGACY_MCP_*, _meter_legacy_mcp, _attach_legacy_deprecation, _legacy_mcp_deprecation, _update_workplan_legacy_impl). TOOLS.md keeps a retired→preferred migration map. Full suite green (495 passed). Merge gate: 7th documented zero-usage window — meter shows 0 across all phase-3 keys, but only ~3 discrete 8h zero windows are captured in docs/evidence/ (per-day snapshots, not 7 windows). Hold merge until the weekly-review sweep accrues the 7th window.

Task: MCP alias removal (Phase 2)

id: STATE-WP-0070-T03
status: done
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

id: STATE-WP-0070-T04
status: done
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.

Progress 2026-07-11: caller audit (docs/evidence/workstream-caller-status-20260711.md) — 8h meter shows 0 legacy REST traffic; weekly ~10k is pre-07-08 history. Fixed the-custodian/runtime/actions.py + daily triage prompt to emit workplan_id; rebuilt dashboard dist/ (removed stale extensions.html /workstreams/ caller).

Progress 2026-07-12: Fresh 8h capture (legacy-meter-weekly-review-20260712.json) — 0 calls in window for all 18 legacy interfaces; retirement candidates at max. Dashboard apiFetch now sends X-StateHub-Component: state-hub.dashboard; dist/ rebuilt. MCP alias removal (T03) still gated on 7 consecutive 8h zero windows (streak ≥3 since 2026-07-10 decline).

Staged 2026-07-13 (branch state-wp-0070-legacy-retirement, unmerged): low-risk half committed (6d3de59) — dropped the redundant open_workstreams mirror from /state/summary (schema, router, MCP reader, dashboard consumers, tests). Full suite green. Deferred (still have live callers, not retirement-ready): (1) workstream_id query/body field alias on preferred routes — external session-close curls/scripts fleet-wide still send it, so removal waits one more cycle after briefs/scripts refresh fleet-wide; (2) flows/workstream.yaml — /flows/workstream/{id} routes are still served and tested. Merge gate same as T03: 7th documented zero-usage window.

Task: Closeout and fleet gate

id: STATE-WP-0070-T05
status: done
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.

Closeout 2026-07-14 (merged df19c46): Gate cleared — 10 consecutive 8h zero-usage windows (07-10 14:00 → 07-13 22:00), all 19 legacy interfaces at 0. Branch state-wp-0070-legacy-retirement merged to main; :8001 dev-hub MCP restarted (removed tools de-registered); full suite green (495 passed). T03 (MCP aliases + resource) and the open_workstreams mirror (T04) are removed.

Deferred to a phase-3 followup (handed to CUST-WP-0055 fleet gate): two T04 sub-items still have live fleet callers and were intentionally NOT removed:

1. workstream_id query/body field alias on preferred routes (/tasks, /decisions, /progress, /execution, /token-events) — external session-close curls and scripts still send it; scan shows ~4.1k api:workstream_id occurrences fleet-wide. Retire after briefs/scripts refresh and the meter key holds 7 zero windows.
2. flows/workstream.yaml — the /flows/workstream/{id} routes are still served and tested. Retire when no callers remain. Backlog: docs/workplan-terminology-legacy-retirement-backlog.md (phase-3 rows).