diff --git a/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md b/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md new file mode 100644 index 0000000..f1d0ffe --- /dev/null +++ b/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md @@ -0,0 +1,273 @@ +--- +id: STATE-WP-0054 +type: workplan +title: "Workplan Terminology Transition and Legacy Meter" +domain: custodian +repo: state-hub +status: proposed +owner: codex +topic_slug: custodian +planning_priority: high +planning_order: 54 +created: "2026-06-03" +updated: "2026-06-03" +--- + +# 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: todo +priority: high +``` + +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. + +### T02 - Add Preferred Workplan Interface Variants + +```task +id: STATE-WP-0054-T02 +status: todo +priority: high +``` + +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. + +### T03 - Implement Legacy Meter Data Model And Service + +```task +id: STATE-WP-0054-T03 +status: todo +priority: high +``` + +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. + +### T04 - Instrument Legacy Workstream Interfaces + +```task +id: STATE-WP-0054-T04 +status: todo +priority: high +``` + +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. + +### T05 - Add Legacy Usage Review And Retirement Signals + +```task +id: STATE-WP-0054-T05 +status: todo +priority: high +``` + +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. + +### T06 - Schedule Weekly Activity-Core Review + +```task +id: STATE-WP-0054-T06 +status: todo +priority: high +``` + +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. + +### T07 - Update Documentation, Dashboard Labels, And Agent Guidance + +```task +id: STATE-WP-0054-T07 +status: todo +priority: medium +``` + +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. + +### T08 - Prove Compatibility And Rollout Safety + +```task +id: STATE-WP-0054-T08 +status: todo +priority: high +``` + +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. + +## 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. +