generated from coulomb/repo-seed
terminology transition workplan
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user