state-hub/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
STATE-WP-0054	workplan	Workplan Terminology Transition and Legacy Meter	custodian	state-hub	finished	codex	custodian	high	54	2026-06-03	2026-06-04	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

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

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

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

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

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

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

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

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.