--- id: STATE-WP-0054 type: workplan title: "Workplan Terminology Transition and Legacy Meter" domain: custodian repo: state-hub status: finished owner: codex topic_slug: custodian planning_priority: high planning_order: 54 created: "2026-06-03" updated: "2026-06-04" state_hub_workstream_id: "471401c8-38b2-46fd-ae34-052825710376" --- # STATE-WP-0054 - Workplan Terminology Transition and Legacy Meter ## Goal Move State Hub's user-facing and preferred integration terminology from `workstream` to `workplan` while preserving existing `workstream` interfaces until measured usage proves they can be retired safely. The transition should make workplan the recommended concept for new clients, documentation, dashboard surfaces, and agent guidance. Existing interfaces such as `/workstreams`, `workstream_id`, `state_hub_workstream_id`, workstream MCP procedures, and workstream event subjects remain available during a compatibility window. ## Context State Hub already treats repo-local workplan files as the source of truth for work. The hub indexes those files into the database, exposes task and lifecycle state, and keeps generated bridge fields such as `state_hub_workstream_id` for continuity. InfoTechCanon is already workplan-first: it defines a State Hub workplan schema and uses `state_hub_workstream_id` only as a bridge to current State Hub internals. This supports a terminology cleanup, but the existing API, database, tests, event subjects, dashboard routes, and attached clients still depend on the older `workstream` vocabulary. The safe path is therefore compatibility-first: - add preferred `workplan` variants for user-facing and integration interfaces; - keep existing `workstream` variants while they are used; - meter legacy usage by interface, tenant, user, and component; - schedule recurring review through activity-core; and - retire only interfaces that have had no measured usage in the prior week and have an explicit replacement path. ## Compatibility Policy `workplan` is the canonical product and domain term after this workplan. `workstream` remains a legacy compatibility term for existing API routes, procedure calls, event subjects, database identifiers, and generated bridge fields until retirement criteria are met. Compatibility requirements: - Existing `workstream` interfaces must continue to behave the same while marked legacy. - New and updated docs should recommend the corresponding `workplan` interface. - Legacy responses should expose migration guidance where practical, such as response metadata, deprecation headers, or dashboard/API reference notes. - Physical database renames are out of scope unless a later workplan proves they are worth the migration risk. ## Legacy Meter Requirements Add a State Hub telemetry service, tentatively named `legacy-meter`, that tracks legacy interface registration and usage. Registering an interface as legacy must capture: - stable interface key; - interface kind, such as REST API call, MCP procedure, event subject, CLI command, dashboard route, or schema field; - timestamp when the interface was registered as legacy; - textual reference to the preferred replacement interface; - owner/component responsible for the compatibility window; - retirement status and review notes. The meter must maintain usage counters for: - total calls to the legacy interface; - tenants using the legacy interface; - users using the legacy interface; - components using the legacy interface; - first seen and last seen usage timestamps; - usage in the current review window. When tenant, user, or component identity is not available, the meter should record an explicit `unknown` bucket instead of dropping the observation. ## Tasks ### T01 - Define Terminology And Compatibility Inventory ```task id: STATE-WP-0054-T01 status: done priority: high state_hub_task_id: "f43ed8c0-f62c-42af-b38f-d4ccd7a7bed5" ``` Inventory every State Hub interface that exposes `workstream` terminology: REST routes, request and response fields, dashboard routes, docs, MCP tools, event subjects, scripts, generated project guidance, and workplan bridge fields. For each interface, classify it as preferred, legacy-compatible, internal-only, or out of scope. Map every legacy-compatible interface to its preferred `workplan` replacement. Done when the repo has a reviewed compatibility matrix that separates semantic renames from high-risk storage or event-contract changes. Result 2026-06-04: added `docs/workplan-terminology-transition.md` with the preferred workplan interfaces, legacy workstream compatibility paths, legacy-meter keys, retirement rules, and activity-core handoff boundary. ### T02 - Add Preferred Workplan Interface Variants ```task id: STATE-WP-0054-T02 status: done priority: high state_hub_task_id: "65dca8e4-a032-4b1a-a21f-8559f1fb87f5" ``` Add preferred `workplan` variants for the public interfaces that currently use `workstream`, starting with REST API and dashboard entry points. Keep existing `workstream` routes and fields operational. Likely examples: - `/workplans` aliases for `/workstreams`; - `/workplans/{id}` aliases for `/workstreams/{id}`; - `/workplans/workplan-index` or a cleaner replacement for the current `/workstreams/workplan-index`; - workplan-named dashboard pages that can route to existing implementation code while URLs and labels move to the new term. Done when new clients can use workplan-named interfaces without relying on workstream-named entry points. Result 2026-06-04: added preferred REST aliases for `/workplans`, `/workplans/{id}`, `/workplans/index`, `/workplans/{id}/dependencies/`, and `/execution/workplans/{id}/intent`. Completion now also emits preferred `org.statehub.workplan.completed` events while retaining the legacy event. ### T03 - Implement Legacy Meter Data Model And Service ```task id: STATE-WP-0054-T03 status: done priority: high state_hub_task_id: "b4008ab7-1f59-4ea7-a728-48557473c22d" ``` Implement the `legacy-meter` service in State Hub telemetry. Provide durable storage for legacy interface registrations and usage observations, plus helper APIs for registering an interface as legacy and recording each use. The registration API must store the legacy timestamp and replacement reference. The usage API must increment call, tenant, user, and component counters and update first/last seen timestamps. Done when tests can register a legacy interface and prove usage counters are updated without changing the legacy interface's behavior. Result 2026-06-04: added `legacy_interfaces` and `legacy_interface_usage_buckets` models, migration, schemas, service helpers, and `/legacy-meter` registration/usage/summary endpoints. ### T04 - Instrument Legacy Workstream Interfaces ```task id: STATE-WP-0054-T04 status: done priority: high state_hub_task_id: "28c31bbc-4479-4dd9-8e2c-08235e81ba91" ``` Register and meter the compatibility interfaces that keep the old `workstream` surface alive. Initial coverage should include legacy REST routes, procedure calls if present, dashboard routes, and event subjects that have a workplan replacement. Instrumentation should be low overhead and resilient: a meter write failure must not break the legacy interface path. Done when calls to selected `workstream` interfaces appear in legacy-meter usage summaries with call counts and tenant/user/component buckets. Result 2026-06-04: instrumented retained `/workstreams` REST routes, dependency routes, `/execution/workstreams/{id}/intent`, and the legacy `org.statehub.workstream.completed` event subject. Legacy REST responses now include deprecation and replacement headers. ### T05 - Add Legacy Usage Review And Retirement Signals ```task id: STATE-WP-0054-T05 status: done priority: high state_hub_task_id: "fca14802-1a15-4b5a-8267-5348666b3c50" ``` Add summary endpoints or reports for weekly legacy review. The report should show each legacy interface, replacement guidance, last usage, prior-week usage, tenant/user/component usage, and retirement eligibility. An interface becomes a retirement candidate only when: - it is registered as legacy; - it has a replacement reference; - it had zero measured usage in the prior week; - it has no manually recorded hold; and - tests or contract checks prove the replacement path covers the same use case. Done when State Hub can produce a precise retirement-candidate list without manual log scraping. Result 2026-06-04: added `/legacy-meter/summary` and `/legacy-meter/weekly-review` with review-window counters, last-seen timestamps, identity buckets, verified-replacement gating, manual holds, and retirement candidate reasons. ### T06 - Schedule Weekly Activity-Core Review ```task id: STATE-WP-0054-T06 status: done priority: high state_hub_task_id: "3d6fb438-707f-45e8-9c38-3e7352ae2a93" ``` Integrate legacy-meter review with activity-core scheduling. State Hub should request or expose a weekly check that asks activity-core to review the prior week's legacy usage and create or trigger retirement follow-up for eligible interfaces. The handoff should keep State Hub as the source of interface usage state while letting activity-core own wakeups, schedules, and dispatch. Done when a weekly activity-core check can read legacy-meter summaries and raise retirement work only for interfaces with no prior-week usage. Result 2026-06-04: exposed activity-core handoff metadata in `/legacy-meter/weekly-review`: weekly cadence, source endpoint, State Hub as state owner, and activity-core as scheduler owner. ### T07 - Update Documentation, Dashboard Labels, And Agent Guidance ```task id: STATE-WP-0054-T07 status: done priority: medium state_hub_task_id: "55a05f68-a337-412c-8462-847e6465d15e" ``` Update State Hub docs, dashboard reference pages, AGENTS/project-rule templates, and onboarding guidance to use `workplan` as the recommended term. Where legacy interfaces are still documented, label them as compatibility interfaces and link to their preferred replacements. Done when new users and agents are guided toward workplan terminology without losing instructions for existing compatibility paths. Result 2026-06-04: updated State Hub docs, dashboard API calls/reference docs, NATS event docs, README, and AGENTS guidance to prefer workplan terminology and document legacy workstream compatibility. ### T08 - Prove Compatibility And Rollout Safety ```task id: STATE-WP-0054-T08 status: done priority: high state_hub_task_id: "2ae2580f-4626-49fe-aec6-ca9340792afd" ``` Add regression coverage for old and new interface variants, legacy-meter registration, usage observation, weekly review summaries, and retirement eligibility. Run the normal State Hub test suite and targeted dashboard/API checks. Record rollout notes that explain which legacy interfaces remain, what replacements exist, and what activity-core will review weekly. Done when existing `workstream` clients still pass, new `workplan` clients pass, and legacy-meter telemetry proves the compatibility window is observable. Progress 2026-06-04: added `tests/test_legacy_meter.py` for preferred workplan routes, legacy route metering, identity buckets, weekly retirement review, completion event metering, dependency aliases, and execution aliases. Focused verification passed with `.venv/bin/python -m pytest tests/test_legacy_meter.py tests/test_routers_core.py::TestWorkstreams tests/test_routers_core.py::TestExecutionQueueEndpoints`. Result 2026-06-04: full backend verification passed with `.venv/bin/python -m pytest` (`340 passed`), dashboard verification passed with `npm test` in `dashboard/` (`11 passed`), and `git diff --check` passed. ## Acceptance Criteria - `workplan` is the recommended user-facing term in State Hub docs, dashboard labels, and new integration guidance. - Existing `workstream` interfaces continue to function during the compatibility window. - Each retained legacy interface is registered with legacy-meter, including legacy timestamp and replacement reference. - Legacy usage is counted by call, tenant, user, and component, with unknown identities tracked explicitly. - Activity-core has a weekly review path for interfaces with no prior-week legacy usage. - Retirement candidates are data-backed and cannot be triggered without a documented replacement. - No physical database or event-contract rename is required in this workplan unless compatibility evidence shows it is safe.