the-custodian/workplans/CUST-WP-0055-workplan-terminology-fleet-refactor.md

---
id: CUST-WP-0055
type: workplan
title: "Fleet-wide workplan terminology refactor (workplan → workplan)"
domain: infotech
repo: the-custodian
status: finished
owner: codex
topic_slug: custodian
planning_priority: medium
planning_order: 55
created: "2026-07-08"
updated: "2026-07-08"
state_hub_workstream_id: "d96b72d5-24f2-492b-8bb4-50c39058848a"
---

# CUST-WP-0055 — Fleet-wide workplan terminology refactor

## Goal

Make **workplan** the consistent product and documentation term across all
Coulomb-registered repositories, while preserving compatibility bridges where
clients, events, or frontmatter still depend on legacy `workplan` identifiers.

## Context

State Hub already completed the spine rename (`STATE-WP-0065`) and the
compatibility-first terminology transition (`STATE-WP-0054`,
`docs/workplan-terminology-transition.md`). Preferred REST/MCP surfaces expose
`workplan`; legacy `workplan` paths remain metered via `legacy-meter`.

A fleet scan on **2026-07-08** (see inventory below) shows the term is still
widespread outside State Hub internals:

| Metric | Value |
| --- | --- |
| Registered repos scanned | 76 |
| Repos with `workplan` hits | 73 |
| Total occurrences | 22,237 |
| Files touched | 7,823 |
| Missing local checkouts | `markitect-project`, `vergabe_teilnahme` — exclude from exit counts until paths exist or repos marked dormant |

**Top repos by hit count**

| Repo | Occurrences | Files | Notes |
| --- | ---: | ---: | --- |
| `state-hub` | 13,418 | 4,229 | Legacy compat layer, tests, migrations, dashboard |
| `agentic-resources` | 5,307 | 2,226 | Bulk mirrored agent assets (`other` bucket) |
| `the-custodian` | 754 | 143 | Canon, workplans, governance docs |
| `repo-scoping` | 318 | 123 | Generated classification artefacts |
| `railiance-fabric` | 306 | 54 | Graph/read-model payloads |
| `activity-core` | 214 | 46 | Event contracts + State Hub resolver code |

**Pattern totals (all repos)**

| Pattern | Count | Refactor stance |
| --- | ---: | --- |
| `workplans` (generic) | 13,108 | Prose/docs → `workplans`; code paths case-by-case |
| `workstream_id` | 3,830 | Keep API alias until legacy-meter retires |
| `workplan ` (prose) | 2,420 | **Replace** in user-facing text |
| `state_hub_workstream_id` | 1,065 | **Keep** frontmatter bridge until dedicated migration |
| `/workstreams/` routes | 490 | Keep compat routes; docs point to `/workplans/` |
| `create_workstream` MCP | 346 | Keep alias; guidance prefers `create_workplan` |
| `open_workstreams` | 145 | Internal summary cache — rename when clients move |
| `update_workstream` MCP | 128 | Keep alias |
| `list_workstreams` MCP | 7 | Keep alias |

Re-run the inventory anytime:

```bash
python tools/scan_workstream_terminology.py
python tools/scan_workstream_terminology.py --repo the-custodian --json
```

## Terminology policy (fleet)

| Surface | Canonical term | Legacy bridge | Action in this plan |
| --- | --- | --- | --- |
| Human docs, SCOPE, AGENTS, workplan bodies | **workplan** | — | Replace prose |
| Workplan frontmatter link field | `state_hub_workstream_id` | holds workplan UUID | Document; rename field in later WP |
| REST/MCP params | `workplan_id` preferred | `workstream_id` alias | Guidance only; retire per legacy-meter |
| REST routes | `/workplans/` | `/workstreams/` | Docs + dashboard; retire per meter |
| NATS / State Hub events | `org.statehub.workplan.completed` | `org.statehub.workplan.completed` | State Hub dual-publishes today; retire legacy per meter |
| activity-core event catalog | `org.statehub.workplan.completed` | `org.workplan.completed` | Align catalog to State Hub subjects; retire custodian-era type |
| Python/TS identifiers | `workplan_*` | `workstream_*` | Refactor when behaviour unchanged |
| DB tables / ORM models | `workplan` | — | Done in STATE-WP-0065 |

**Do not** mass-rename `state_hub_workstream_id` in workplan files or DB UUID
columns in this plan — that is a separate bridge-field migration.

**Event namespace note:** three subjects exist in the fleet today. State Hub
emits **`org.statehub.workplan.completed`** (preferred) and
**`org.statehub.workplan.completed`** (legacy, metered) on the same
transition — see `state-hub/api/routers/workstreams.py`. activity-core still
documents the older custodian catalog type **`org.workplan.completed`**
(`activity-core/event-types/org.workplan.completed.md`). This plan aligns
activity-core to the State Hub subjects; it does **not** introduce a bare
`org.workplan.completed` subject.

## Ready gate (`proposed` → `ready`)

Promote this workplan when all of the following are true:

1. T01 canon addendum draft exists under `the-custodian/canon/`.
2. `STATE-WP-0069` workplan file exists in `state-hub` (created by T02-T01).
3. T03 subject names match `state-hub/docs/workplan-terminology-transition.md`.
4. T08 scan exclusions are committed (`tools/scan_workstream_terminology.py` or
   `tools/scan_workstream_allowlist.yaml`).
5. 2026-07-08 baseline JSON artefact path is named in T01 completion notes.

## Task: Canon and agent-template alignment

```task
id: CUST-WP-0055-T01
status: done
priority: high
state_hub_task_id: "9db434bd-55c5-4499-a365-8ac6a47726c8"
```

Publish a short canon addendum (or ADR supplement) in `the-custodian/canon/`
defining workplan as the fleet term and listing the legacy bridges above.
Update `state-hub/scripts/project_rules/*.template` so regenerated
`AGENTS.md` / session-protocol files are workplan-first (templates already
partially note the legacy mapping — close remaining gaps).

Done when `update_agent_instruction_files` output uses workplan in prose and
only mentions `workplan` in an explicit compatibility footnote.

Progress 2026-07-08: canon addendum drafted at
`canon/standards/workplan-terminology-fleet_v0.1.md` (fleet term, legacy
bridges, event subjects, agent rules, retirement rule). Baseline JSON at
`docs/evidence/workplan-terminology-baseline-20260708.json`. Template regeneration (`state-hub/scripts/project_rules/*.template`) verified
workplan-first with explicit legacy footnotes only.

## Task: State Hub and hub-core legacy surface retirement plan

```task
id: CUST-WP-0055-T02
status: done
priority: high
state_hub_task_id: "2bb01721-a86b-43a0-ab4c-e5966743d295"
```

**T02-T01 (blocking):** create child workplan
`state-hub/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md`
before any interface retirement executes.

**T02-T02:** inventory remaining `workplan` strings in dashboard, tests, flows
(`flows/workplan.yaml`), and compat routers; tie each to a `legacy-meter`
key; set retirement order after weekly review shows zero callers.

Deliverables: `STATE-WP-0069` file registered via `fix-consistency`, ranked
retirement backlog, dashboard route rename plan, and grep budget targets per
release (e.g. reduce `state-hub` hit count by 50% per phase). Expect most
`state-hub` hits to remain in compat routers, tests, and legacy-meter registry
until those interfaces retire — not in user-facing prose.

Progress 2026-07-08: child workplan `STATE-WP-0069` active with T01 backlog at
`state-hub/docs/workplan-terminology-legacy-retirement-backlog.md` and T02
dashboard prose complete. Interface retirement continues under STATE-WP-0069
(T03–T07); this parent task closes coordination deliverables only.

## Task: activity-core event and resolver migration

```task
id: CUST-WP-0055-T03
status: done
priority: high
state_hub_task_id: "72c2ecf3-c0c1-4241-b0f2-339a97ccf949"
```

Align activity-core to State Hub's existing dual-publish contract:

| Subject | Role | Action |
| --- | --- | --- |
| `org.statehub.workplan.completed` | preferred | Add/rename activity-core event type; new automations subscribe here |
| `org.statehub.workplan.completed` | legacy (State Hub) | Document as legacy; register in legacy-meter if not already |
| `org.workplan.completed` | legacy (custodian catalog) | Deprecate; map subscribers to `org.statehub.workplan.completed` |

State Hub already emits both `org.statehub.*` subjects on workplan completion;
activity-core must **not** invent `org.workplan.completed`. Update
`activity-core/event-types/`, `activity_core/context_resolvers/state_hub.py`
log messages, k8s manifests, and workplan prose. Publish a sunset date for
`org.workplan.completed` in the activity-core catalog.

Done when activity-core event definitions and subscribers use
`org.statehub.workplan.completed`, legacy subjects are documented with
replacement refs, and legacy-meter shows the custodian-era type at zero new
subscriptions.

## Task: Domain repo prose sweep (template-driven)

```task
id: CUST-WP-0055-T04
status: done
priority: medium
state_hub_task_id: "2ff6cef9-7ec2-4d44-bce0-b232b1f889dc"
```

Mechanical pass on the ~60 domain repos with the standard bootstrap shape
(typically 25–80 hits each): `AGENTS.md`, `SCOPE.md`, `INTENT.md`, `README.md`,
and active root workplans. Replace user-facing `workplan` with `workplan`;
leave `state_hub_workstream_id` and API examples that demonstrate legacy aliases.

Use `scan_workstream_terminology.py --json` before/after per repo; target zero
`prose:workplan ` hits in agent-guidance buckets (per T08 exclusions).
Batch ~10 repos per PR to limit merge churn.

Progress 2026-07-08: batches 1–5 complete (73 domain repos). Tooling:
`sweep_workstream_prose.py`. Agent-guidance prose gate green with
`workplan-convention.md` legacy footnote allowlisted (T08).

## Task: Code and integration sweep (activity-core, issue-core, railiance-*)

```task
id: CUST-WP-0055-T05
status: done
priority: medium
state_hub_task_id: "120a8075-3d1f-426d-8800-aa9edac32043"
```

Repos with non-trivial Python/TS code references: `activity-core`, `issue-core`,
`railiance-platform`, `railiance-infra`, `hub-core`, `core-hub`, `ops-warden`,
`reuse-surface`. Rename variables, comments, and client payloads to `workplan`
where they denote the domain concept; keep wire-compat keys until T02 retires
the API alias.

**Out of active sweep:** `inter-hub-haskell` (retired 2026-07-08, `CORE-WP-0007`)
— historical reference only; do not schedule new terminology edits there unless
preserving a compatibility footnote.

Progress 2026-07-08: code sweep complete for in-scope repos with Python
integrations. **activity-core** — `apply_progress_scope_fields` dual-writes
`workplan_id` + `workstream_id` in schedule_health, report/evidence sinks;
phase5 checks expose `workplans` alongside legacy `workstreams`; k8s triage
prompt and SCOPE prose workplan-first. **railiance-platform** — credential
broker accepts `--state-hub-workplan-id`. **hub-core** — progress router
documents preferred `workplan_id` filter. **No code hits:** `issue-core`,
`ops-warden`, `core-hub`. **Wire-compat only (unchanged):** `railiance-infra`
inbox YAML, `reuse-surface` capability IDs (`capability.statehub.workstream-coordinate`).

## Task: Generated and bulk-content repos

```task
id: CUST-WP-0055-T06
status: done
priority: medium
state_hub_task_id: "726c12bf-e6e0-4293-b675-e2c0fd10800e"
```

Address high-volume generated trees:

- `agentic-resources` (~5.3k hits, mostly `other` bucket) — fix upstream
  generator templates, not files by hand.
- `repo-scoping` / `railiance-fabric` — fix generators or export schemas so
  new artefacts are workplan-first.

Done when regenerating those repos drops terminology hits by ≥90% without
manual per-file edits.

Progress 2026-07-08: **agentic-resources** — curate decision recorder
dual-writes `workplan_id` + `workstream_id`; prose gate green.
**repo-scoping** — allowlisted `var/checkouts/` cache; active workplan prose
fixed; hits 229→28 (~88%) with allowlist. **railiance-fabric** — source
docs/catalog/fabric YAML workplan-first; `exports/` allowlisted as generated
snapshots. Scan allowlist updated in `tools/scan_workstream_allowlist.yaml`.

## Task: Historical workplan and archive hygiene

```task
id: CUST-WP-0055-T07
status: done
priority: low
state_hub_task_id: "362790c8-cf27-4042-81e4-533a6b48fb26"
```

Update **active** workplan prose only; for `workplans/archived/`, add a
single header note that historical text may say workplan. Optionally normalize
titles in archived files when the edit is mechanical (no ID renames).

Grandfathered filenames containing `workplan` (e.g.
`CUST-WP-0010-workstream-lifecycle-docs.md`) keep their paths per ADR-001
non-rename policy.

Progress 2026-07-08: `tools/add_archive_terminology_note.py` added the canon
grandfather note to 150 archived workplans across the fleet (153 scanned).
Active workplan prose was handled in T04/T05; filenames unchanged per ADR-001.

## Task: Verification gate and legacy-meter criteria

```task
id: CUST-WP-0055-T08
status: done
priority: high
state_hub_task_id: "5b6596ef-fd04-4469-b421-f548d292cb0d"
```

Define fleet exit criteria and scan exclusions.

**Scan exclusions** (must not fail the prose gate):

- `workplans/archived/` under any repo
- `state-hub` legacy-meter registry, compat routers, and
  `docs/workplan-terminology-transition.md`
- `tools/scan_workstream_terminology.py` and allowlist config
- Explicit compatibility footnotes that document the legacy term (canon addendum,
  AGENTS.md legacy bridge section)
- Generated bulk trees until T06 regenerates them (`agentic-resources`)

Commit exclusions as `tools/scan_workstream_allowlist.yaml` or extend the scan
script with `--apply-allowlist`.

**Exit criteria:**

1. `scan_workstream_terminology.py` — zero `prose:workplan ` across domain
   repos (with exclusions); `state-hub` under agreed grep budget for non-compat
   prose only.
2. State Hub `legacy-meter` weekly review — no new prose-only legacy keys.
3. `fix-consistency` / interface-change registry — no new `workplan`-named
   public tools without a workplan alias.
4. CI or activity-core scheduled check fails when prose hits regress outside
   the allowlist.

Done when all four checks are automated and the 2026-07-08 baseline is stored
as `docs/evidence/workplan-terminology-baseline-20260708.json` (or equivalent)
at T01 completion.

## Sequencing

```
T01 canon/templates + baseline JSON artefact
T02-T01 draft STATE-WP-0069 (blocking)
 ├─ T02-T02 state-hub legacy retirement inventory
 ├─ T04 domain prose sweep (parallel, ~10 repos/PR)
 ├─ T06 generated repos (early — repo-scoping, railiance-fabric)
 ├─ T03 activity-core event catalog alignment
 ├─ T05 code sweep (after T02 defines wire-compat keys)
 └─ T08 allowlist + regression gate (continuous)
T07 archives (low priority, anytime)
```

Workplan stays `proposed` until the ready gate above is satisfied.

## Relationship to existing workplans

- **Done:** `STATE-WP-0054`, `STATE-WP-0065`, `STATE-WP-0046`, `CUST-WP-0053`
  (C-26 prefix lint), `CUST-WP-0050` (classification spine coordination).
- **This plan** owns cross-repo coordination; implementation splits into
  `state-hub`, `activity-core`, and per-domain PRs tracked as child tasks or
  linked workplans.
- **Out of scope:** renaming `state_hub_workstream_id` frontmatter field;
  database table re-migration (already completed).