generated from coulomb/repo-seed
tegwick
166aedfa8d
Adds preferred workplan REST/event surfaces, legacy-meter telemetry and weekly review summaries, documentation/dashboard terminology updates, dashboard API loading fixes, and close-out sync for STATE-WP-0052 and STATE-WP-0054.
324 lines
12 KiB
Markdown
324 lines
12 KiB
Markdown
---
|
|
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.
|