---
id: STATE-WP-0054
type: workplan
title: "Workplan Terminology Transition and Legacy Meter"
domain: infotech
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.
