No workplan data yet.
`);
} else {
display(Inputs.table(rows.map((r, i) => ({...r, _ref: i})), {
columns: ["_ref", "label", "tokens_in", "tokens_out", "tokens_total", "event_count"],
- header: {_ref: "REF", label: "Workstream", tokens_in: "Tokens In", tokens_out: "Tokens Out", tokens_total: "Total", event_count: "Events"},
+ header: {_ref: "REF", label: "Workplan", tokens_in: "Tokens In", tokens_out: "Tokens Out", tokens_total: "Total", event_count: "Events"},
format: {
- _ref: (_, i) => refCell(i + 1, "workstreams", rows[i].scope_id),
+ _ref: (_, i) => refCell(i + 1, "workplans", rows[i].scope_id),
label: d => nameCell(d, d),
tokens_in: d => d.toLocaleString(),
tokens_out: d => d.toLocaleString(),
diff --git a/dashboard/src/tools.md b/dashboard/src/tools.md
index d9d5314..5083b7d 100644
--- a/dashboard/src/tools.md
+++ b/dashboard/src/tools.md
@@ -65,7 +65,7 @@ Connected applications, services, and local tools used across the Custodian ecos
display(html`
${appCard({
icon: "🗄️", name: "State Hub API", status: apiUp,
- desc: "FastAPI backend — the source of truth for all workstream, task, and decision data.",
+ desc: "FastAPI backend — the source of truth for all workplan, task, and decision data.",
url: "http://127.0.0.1:8000/docs", label: "127.0.0.1:8000 · Swagger UI",
})}
${appCard({
diff --git a/dashboard/src/workplan-queue.md b/dashboard/src/workplan-queue.md
index ca20bd0..052fef9 100644
--- a/dashboard/src/workplan-queue.md
+++ b/dashboard/src/workplan-queue.md
@@ -62,7 +62,7 @@ function statusCell(row) {
function blockers(row) {
const parts = [];
- if (row.blocked_by_workstream_ids?.length) parts.push(`${row.blocked_by_workstream_ids.length} workstream`);
+ if (row.blocked_by_workstream_ids?.length) parts.push(`${row.blocked_by_workstream_ids.length} workplan`);
if (row.blocked_by_task_ids?.length) parts.push(`${row.blocked_by_task_ids.length} task`);
return parts.length ? parts.join(", ") : "—";
}
diff --git a/dashboard/src/workstreams.md b/dashboard/src/workstreams.md
index 20fee33..e3faa2c 100644
--- a/dashboard/src/workstreams.md
+++ b/dashboard/src/workstreams.md
@@ -8,7 +8,7 @@ import {WORKSTREAM_STATUSES, isClosedWorkstream, normalizeWorkstreamStatus} from
```
```js
-// Fetch workstreams + topics + dep edges in parallel; /state/deps replaces the
+// Fetch workplans + topics + dep edges in parallel; /state/deps replaces the
// heavier /state/summary which was only used here to extract dependency edges.
const wsState = (async function*() {
let failures = 0;
@@ -50,7 +50,7 @@ const _ts = wsState.ts;
```
```js
-// ── Workstream Health Index (WHI) ────────────────────────────────────────────
+// ── Workplan Health Index (WHI) ────────────────────────────────────────────
const _idToDomain = Object.fromEntries(data.map(w => [w.id, w.domain ?? "unknown"]));
const _closedIds = new Set(data.filter(w => isClosedWorkstream(w.status)).map(w => w.id));
const _openCount = openWs.length;
@@ -63,7 +63,7 @@ const _DD = _openCount > 0 ? _totalEdges / _openCount : 0;
// Blocked Ratio
const _BR = _openCount > 0 ? openWs.filter(w => w.status === "blocked").length / _openCount : 0;
-// Single-Point Risk — max inbound edges on one incomplete workstream
+// Single-Point Risk — max inbound edges on one incomplete workplan
const _inbound = {};
for (const e of _allEdges) {
if (!_closedIds.has(e.to)) _inbound[e.to] = (_inbound[e.to] ?? 0) + 1;
@@ -72,7 +72,7 @@ const _SPR = _openCount > 0
? (Object.keys(_inbound).length > 0 ? Math.max(...Object.values(_inbound)) : 0) / _openCount
: 0;
-// Parallel Execution Potential — ready/active workstreams with all deps finished
+// Parallel Execution Potential — ready/active workplans with all deps finished
const _PEP = _openCount > 0
? openWs.filter(w => ["ready", "active"].includes(normalizeWorkstreamStatus(w.status)) && w.depends_on.every(d => _closedIds.has(d.workstream_id))).length / _openCount
: 0;
@@ -282,7 +282,7 @@ display(Plot.plot({
display(_filtersForm);
{
- // Enrich each workstream with tasks/deps data from open_workstreams summary
+ // Enrich each workplan with tasks/deps data from open_workstreams summary
const _openWsMap = Object.fromEntries(openWs.map(w => [w.id, w]));
const _wsTable = buildEntityTable(
filtered,
@@ -290,12 +290,12 @@ display(_filtersForm);
{label: "Title", key: "title", cls: "et-title-col et-title-cell",
render: w => w.title},
{label: "Domain", key: "domain"},
- {label: "Status", render: w => statusControl({entity: w, type: "workstream", statuses: WORKSTREAM_STATUSES})},
+ {label: "Status", render: w => statusControl({entity: w, type: "workplan", statuses: WORKSTREAM_STATUSES})},
{label: "Owner", render: w => w.owner ?? "—"},
{label: "Due", render: w => w.due_date ?? "—"},
{label: "Updated", render: w => new Date(w.updated_at).toLocaleDateString()},
],
- w => openEntityModal({...w, ..._openWsMap[w.id]}, "workstream"),
+ w => openEntityModal({...w, ..._openWsMap[w.id]}, "workplan"),
);
display(_wsTable);
}
diff --git a/dashboard/src/workstreams/[id].md b/dashboard/src/workstreams/[id].md
index dae777b..dcc56f6 100644
--- a/dashboard/src/workstreams/[id].md
+++ b/dashboard/src/workstreams/[id].md
@@ -1,5 +1,5 @@
---
-title: Workstream
+title: Workplan
---
```js
@@ -18,8 +18,8 @@ const [raw, taskRows, workplanIndex] = await Promise.all([
.then(r => r.ok ? r.json() : [])
.catch(() => []),
fetch(`${API}/workplans/index`)
- .then(r => r.ok ? r.json() : {workstreams: {}})
- .catch(() => ({workstreams: {}})),
+ .then(r => r.ok ? r.json() : {workplans: {}})
+ .catch(() => ({workplans: {}})),
]);
```
@@ -27,16 +27,16 @@ const [raw, taskRows, workplanIndex] = await Promise.all([
if (raw.error) {
display(html`
⚠️ ${raw.error}
`);
} else {
- const workplan = (workplanIndex.workstreams ?? {})[wsId] ?? {};
+ const workplan = (workplanIndex.workplans ?? workplanIndex.workstreams ?? {})[wsId] ?? {};
const name = raw.title || raw.slug || wsId;
const shortName = name.length > 60 ? name.slice(0, 60) + "…" : name;
- display(html`
Workstream · ${shortName}
`);
+ display(html`
Workplan · ${shortName}
`);
display(html`
← Overview | ← Workplans | ← Token Cost
`);
display(html`
Status${statusControl({
entity: raw,
- type: "workstream",
+ type: "workplan",
statuses: WORKSTREAM_STATUSES,
onSaved: () => setTimeout(() => location.reload(), 450),
})}
@@ -53,7 +53,7 @@ if (raw.error) {
display(html`
Tasks
`);
if (sortedTasks.length === 0) {
- display(html`
No tasks are attached to this workstream.
`);
+ display(html`
No tasks are attached to this workplan.
`);
} else {
display(html`
| Status | Priority | Task | Human |
|---|
diff --git a/dashboard/src/wsjf-triage.md b/dashboard/src/wsjf-triage.md
index a1569f2..c593923 100644
--- a/dashboard/src/wsjf-triage.md
+++ b/dashboard/src/wsjf-triage.md
@@ -23,7 +23,7 @@ import {
const triageState = (async function*() {
let failures = 0;
while (true) {
- let events = [], workplanIndex = {workstreams: {}}, ok = false;
+ let events = [], workplanIndex = {workplans: {}}, ok = false;
try {
const [reportsResp, indexResp] = await Promise.all([
apiFetch("/progress/?event_type=daily_triage&limit=14"),
@@ -31,7 +31,7 @@ const triageState = (async function*() {
]);
ok = reportsResp.ok && indexResp.ok;
events = reportsResp.ok ? await reportsResp.json() : [];
- workplanIndex = indexResp.ok ? await indexResp.json() : {workstreams: {}};
+ workplanIndex = indexResp.ok ? await indexResp.json() : {workplans: {}};
} catch {}
failures = ok ? 0 : failures + 1;
yield {events, workplanIndex, ok, ts: new Date()};
@@ -42,7 +42,7 @@ const triageState = (async function*() {
```js
const reports = normalizeTriageReports(triageState.events ?? []);
-const candidateIndex = buildCandidateIndex(triageState.workplanIndex ?? {workstreams: {}});
+const candidateIndex = buildCandidateIndex(triageState.workplanIndex ?? {workplans: {}});
const _ok = triageState.ok ?? false;
const _ts = triageState.ts;
const latestReport = reports[0] ?? null;
@@ -140,7 +140,7 @@ function renderPatterns(reports, index) {
${rows.length === 0
? html`No repeated recommendations are visible in the loaded 14-day window.
`
: html`
- | Workstream | Times Recommended | Most Frequent Action |
|---|
+ | Workplan | Times Recommended | Most Frequent Action |
|---|
${rows.map(row => html`
| ${candidateNode(row.candidate, index)} |
${row.count} / ${Math.max(1, windowReports.length)} reports |
diff --git a/dashboard/test/terminology-nav.test.mjs b/dashboard/test/terminology-nav.test.mjs
new file mode 100644
index 0000000..c191d80
--- /dev/null
+++ b/dashboard/test/terminology-nav.test.mjs
@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import {readFileSync} from "node:fs";
+import test from "node:test";
+import {fileURLToPath} from "node:url";
+import {dirname, join} from "node:path";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const config = readFileSync(join(root, "observablehq.config.js"), "utf8");
+const indexMd = readFileSync(join(root, "src/index.md"), "utf8");
+
+test("dashboard navigation uses workplan labels", () => {
+ assert.match(config, /name: "Workplans"/);
+ assert.doesNotMatch(config, /name: "Workstreams"/);
+});
+
+test("overview page uses workplan-first user-facing copy", () => {
+ assert.match(indexMd, /## Workplans by Repository/);
+ assert.match(indexMd, /Active Workplans/);
+ assert.doesNotMatch(indexMd, /No active workstreams\./);
+ assert.doesNotMatch(indexMd, /Active Workstreams/);
+});
\ No newline at end of file
diff --git a/docs/workplan-terminology-legacy-retirement-backlog.md b/docs/workplan-terminology-legacy-retirement-backlog.md
new file mode 100644
index 0000000..f946caa
--- /dev/null
+++ b/docs/workplan-terminology-legacy-retirement-backlog.md
@@ -0,0 +1,108 @@
+# 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/` | `GET /workplans/` | REST | T04 |
+| 1 | `rest_api:POST /workstreams/` | `POST /workplans/` | REST | T04 |
+| 1 | `rest_api:GET /workstreams/{workstream_id}` | `GET /workplans/{workplan_id}` | REST | T04 |
+| 1 | `rest_api:PATCH /workstreams/{workstream_id}` | `PATCH /workplans/{workplan_id}` | REST | T04 |
+| 1 | `rest_api:DELETE /workstreams/{workstream_id}` | `DELETE /workplans/{workplan_id}` | REST | T04 |
+| 1 | `rest_api:GET /workstreams/workplan-index` | `GET /workplans/index` | REST | T04 |
+| 2 | `rest_api:GET /workstreams/{workstream_id}/dependencies/` | `GET /workplans/{workplan_id}/dependencies/` | REST | T04 |
+| 2 | `rest_api:POST /workstreams/{workstream_id}/dependencies/` | `POST /workplans/{workplan_id}/dependencies/` | REST | T04 |
+| 2 | `rest_api:DELETE /workstreams/{workstream_id}/dependencies/{dep_id}` | `DELETE /workplans/{workplan_id}/dependencies/{dep_id}` | REST | T04 |
+| 2 | `rest_api:PATCH /execution/workstreams/{workstream_id}/intent` | `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 |
+| 4 | `event_subject:org.statehub.workstream.completed` | `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 | workplan successor flow | Internal | T06 |
+
+### Query-param aliases (not separately metered today)
+
+These accept `workstream_id` alongside `workplan_id` on preferred routes:
+
+- `GET /tasks/` — `api/routers/tasks.py`
+- `GET /decisions/` — `api/routers/decisions.py`
+- `GET /token-events/` — `api/routers/token_events.py`
+
+Retire param aliases in T04 after route retirement; document callers via
+weekly review component headers (`X-StateHub-Component`).
+
+## 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)
\ No newline at end of file
diff --git a/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md b/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md
index 5838bc7..b7e0de3 100644
--- a/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md
+++ b/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md
@@ -4,7 +4,7 @@ type: workplan
title: "Workplan terminology legacy retirement (State Hub)"
domain: infotech
repo: state-hub
-status: proposed
+status: active
owner: codex
topic_slug: custodian
planning_priority: medium
@@ -72,7 +72,7 @@ excluded once documented in T01).
```task
id: STATE-WP-0069-T01
-status: todo
+status: done
priority: high
state_hub_task_id: "ffc186e0-807d-4ee4-b11f-3f769af2ab2d"
```
@@ -96,7 +96,7 @@ Done when the backlog is reviewed and each interface has a phase assignment (T02
```task
id: STATE-WP-0069-T02
-status: todo
+status: done
priority: high
state_hub_task_id: "996e484e-8cfb-4c9e-8682-c9c3da0c1d72"
```