tegwick
b2640a1591
T03: MCP alias retirement gate was unstartable — deprecation notices existed
but no mcp:* interfaces were ever registered or metered. Add
_meter_legacy_mcp() posting /legacy-meter/usage (kind mcp_tool, component
state-hub.mcp) from create_workstream, list_workstreams, update_workstream,
update_workstream_status, and state://workstreams/{topic_slug}; register all
five phase-3 backlog keys so zero-window streaks accrue from today.
T04: trace residual POST /progress/ workstream_id (3 calls/8h, unknown) to
.custodian-brief.md labelling workplans "workstream_id:"; brief generator now
prints "workplan_id:". Briefs refresh on each repo's next fix-consistency run.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
120 lines
No EOL
6.5 KiB
Markdown
120 lines
No EOL
6.5 KiB
Markdown
# Workplan Terminology Legacy Retirement Backlog
|
|
|
|
Date: 2026-07-08
|
|
Owner: `STATE-WP-0069` (child of `CUST-WP-0055`)
|
|
Baseline: `the-custodian/docs/evidence/workstream-terminology-baseline-20260708.json`
|
|
|
|
This backlog ranks every metered legacy `workstream` interface still present in
|
|
State Hub. **Removal requires legacy-meter evidence** — zero measured calls in
|
|
the review window, replacement verified, no manual hold.
|
|
|
|
Authoritative interface matrix: `docs/workplan-terminology-transition.md`.
|
|
|
|
## Retirement rule (unchanged)
|
|
|
|
1. Registered in `legacy-meter`
|
|
2. Replacement reference verified
|
|
3. No manual hold
|
|
4. Zero measured calls in the review window
|
|
|
|
Activity-core runs the weekly review; State Hub owns usage state and removal.
|
|
|
|
## Scan allowlist (grep tooling)
|
|
|
|
Exclude these paths from non-compat prose counts (see
|
|
`the-custodian/tools/scan_workstream_allowlist.yaml`):
|
|
|
|
| Area | Paths |
|
|
| --- | --- |
|
|
| Compat REST | `api/routers/workstreams.py`, `api/routers/workstream_dependencies.py` |
|
|
| Legacy meter | `api/routers/legacy_meter.py`, `api/services/legacy_meter.py`, `api/models/legacy_meter.py`, `migrations/` |
|
|
| MCP aliases | `mcp_server/` |
|
|
| Transition docs | `docs/workplan-terminology-transition.md`, this file, `docs/nats-event-subjects.md` |
|
|
| Regression tests | `tests/test_legacy_meter.py`, `tests/test_routers_core.py` |
|
|
| CLI compat | `custodian_cli.py`, `scripts/consistency_check.py` |
|
|
|
|
Dashboard prose is **not** allowlisted — `STATE-WP-0069` T02 drives it to zero
|
|
`prose:workstream` in `dashboard/src/`.
|
|
|
|
## Ranked backlog
|
|
|
|
Risk order: REST > MCP > events > dashboard prose > internal identifiers.
|
|
|
|
| Phase | Legacy-meter key | Replacement | Risk | Owner task |
|
|
| ---: | --- | --- | --- | --- |
|
|
| 1 | ~~`rest_api:GET /workstreams/`~~ **retired** (410) | `GET /workplans/` | REST | T04 ✓ |
|
|
| 1 | ~~`rest_api:POST /workstreams/`~~ **retired** (410) | `POST /workplans/` | REST | T04 ✓ |
|
|
| 1 | ~~`rest_api:GET /workstreams/{workstream_id}`~~ **retired** (410) | `GET /workplans/{workplan_id}` | REST | T04 ✓ |
|
|
| 1 | ~~`rest_api:PATCH /workstreams/{workstream_id}`~~ **retired** (410) | `PATCH /workplans/{workplan_id}` | REST | T04 ✓ |
|
|
| 1 | ~~`rest_api:DELETE /workstreams/{workstream_id}`~~ **retired** (410) | `DELETE /workplans/{workplan_id}` | REST | T04 ✓ |
|
|
| 1 | ~~`rest_api:GET /workstreams/workplan-index`~~ **retired** (410) | `GET /workplans/index` | REST | T04 ✓ |
|
|
| 2 | ~~`rest_api:GET /workstreams/{workstream_id}/dependencies/`~~ **retired** (410) | `GET /workplans/{workplan_id}/dependencies/` | REST | T04 ✓ |
|
|
| 2 | ~~`rest_api:POST /workstreams/{workstream_id}/dependencies/`~~ **retired** (410) | `POST /workplans/{workplan_id}/dependencies/` | REST | T04 ✓ |
|
|
| 2 | ~~`rest_api:DELETE /workstreams/{workstream_id}/dependencies/{dep_id}`~~ **retired** (410) | `DELETE /workplans/{workplan_id}/dependencies/{dep_id}` | REST | T04 ✓ |
|
|
| 2 | ~~`rest_api:PATCH /execution/workstreams/{workstream_id}/intent`~~ **retired** (410) | `PATCH /execution/workplans/{workplan_id}/intent` | REST | T04 ✓ |
|
|
| 3 | `mcp:create_workstream` | `create_workplan` | MCP | T03 |
|
|
| 3 | `mcp:update_workstream` | `update_workplan` | MCP | T03 |
|
|
| 3 | `mcp:update_workstream_status` | `update_workplan_status` | MCP | T03 |
|
|
| 3 | `mcp:list_workstreams` | `list_workplans` | MCP | T03 |
|
|
| 3 | `state://workstreams/{topic_slug}` | `state://workplans/{topic_slug}` (proposed) | MCP resource | T03 |
|
|
|
|
Phase-3 MCP keys metered + registered 2026-07-10 (STATE-WP-0070 T03):
|
|
`_meter_legacy_mcp()` records usage from the alias tools/resource; zero-window
|
|
streaks accrue from registration.
|
|
| 4 | ~~`event_subject:org.statehub.workstream.completed`~~ **retired** | `org.statehub.workplan.completed` | Event | T05 ✓ |
|
|
| 5 | Dashboard nav label `Workstreams` | `Workplans` (URL compat retained) | Prose | T02 |
|
|
| 5 | `dashboard/src/index.md` user-facing copy | workplan-first strings | Prose | T02 |
|
|
| 6 | `open_workstreams` summary cache key | `open_workplans` | Internal | T06 |
|
|
| 6 | `flows/workstream.yaml` entity id | `flows/workplan.yaml` (`custodian.workplan.v1`) | Internal | T06 (workplan flow shipped; workstream yaml retained) |
|
|
|
|
### Query-param aliases (metered from 2026-07-09)
|
|
|
|
These accept `workstream_id` alongside `workplan_id` on preferred routes:
|
|
|
|
| Legacy-meter key | Route | Replacement |
|
|
| --- | --- | --- |
|
|
| `rest_api:GET /tasks/?workstream_id` | `GET /tasks/` | `GET /tasks/?workplan_id=` |
|
|
| `rest_api:GET /tasks/counts?workstream_id` | `GET /tasks/counts` | `GET /tasks/counts?workplan_id=` |
|
|
| `rest_api:GET /decisions/?workstream_id` | `GET /decisions/` | `GET /decisions/?workplan_id=` |
|
|
| `rest_api:GET /token-events/?workstream_id` | `GET /token-events/` | `GET /token-events/?workplan_id=` |
|
|
| `rest_api:GET /execution/launch-requests?workstream_id` | `GET /execution/launch-requests` | `GET /execution/launch-requests?workplan_id=` |
|
|
| `rest_api:GET /progress/?workstream_id` | `GET /progress/` | `GET /progress/?workplan_id=` |
|
|
| `rest_api:POST /progress/ workstream_id` | `POST /progress/` | `POST /progress/` with `workplan_id` body field |
|
|
| `rest_api:POST /tasks/ workstream_id` | `POST /tasks/` | `POST /tasks/` with `workplan_id` body field |
|
|
| `rest_api:POST /decisions/ workstream_id` | `POST /decisions/` | `POST /decisions/` with `workplan_id` body field |
|
|
|
|
Retire param aliases in T04 after zero-usage windows; callers surface via
|
|
`X-StateHub-Component` in weekly review.
|
|
|
|
## Grep budget by phase
|
|
|
|
Measured with:
|
|
|
|
```bash
|
|
python ~/the-custodian/tools/scan_workstream_terminology.py --repo state-hub --apply-allowlist --json
|
|
python ~/the-custodian/tools/scan_workstream_terminology.py --repo state-hub --check-prose-gate
|
|
```
|
|
|
|
| Phase | Target |
|
|
| --- | --- |
|
|
| After T02 | Zero `prose:workstream` in `dashboard/src/` |
|
|
| After T03 | MCP tool docstrings and error messages workplan-first |
|
|
| After T04 | OpenAPI lists `/workplans` only; `/workstreams` returns 410 or unmounted |
|
|
| After T07 | Total repo hits reduced ≥50% from 2026-07-08 baseline |
|
|
|
|
## Sequencing
|
|
|
|
```
|
|
T01 backlog (this document) ──► T02 dashboard prose
|
|
├─► T03 MCP deprecation warnings → alias removal
|
|
├─► T04 REST retirement (per-key zero usage)
|
|
├─► T05 stop dual-publish (after CUST-WP-0055 T03)
|
|
├─► T06 internal renames
|
|
└─► T07 closeout
|
|
```
|
|
|
|
## Related workplans
|
|
|
|
- `STATE-WP-0054` — compatibility layer and legacy-meter (finished)
|
|
- `STATE-WP-0069` — this retirement plan
|
|
- `CUST-WP-0055` — fleet coordination; activity-core catalog alignment (T03) |