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

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
CUST-WP-0055	workplan	Fleet-wide workplan terminology refactor (workstream → workplan)	infotech	the-custodian	proposed	codex	custodian	high	55	2026-07-08	2026-07-08	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 workstream 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 workstream 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 workstream hits	73
Total occurrences	22,237
Files touched	7,823
Missing local checkouts	markitect-project, vergabe_teilnahme

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
workstreams (generic)	13,108	Prose/docs → workplans; code paths case-by-case
workstream_id	3,830	Keep API alias until legacy-meter retires
workstream (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:

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 / activity events	org.statehub.workplan.completed	org.workstream.completed	Dual-publish then retire
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.

Task: Canon and agent-template alignment

id: CUST-WP-0055-T01
status: todo
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 workstream in an explicit compatibility footnote.

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

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

Child implementation workplan in state-hub (proposed STATE-WP-0069): inventory remaining workstream strings in dashboard, tests, flows (flows/workstream.yaml), and compat routers; tie each to a legacy-meter key; set retirement order after weekly review shows zero callers.

Deliverables: ranked retirement backlog, dashboard route rename plan, and grep budget targets per release (e.g. reduce state-hub hit count by 50% per phase).

Task: activity-core event and resolver migration

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

Migrate org.workstream.completed → org.workplan.completed with a dual-publish window documented in activity-core/event-types/. Update activity_core/context_resolvers/state_hub.py log messages, k8s manifests, and workplan prose. Register legacy subject in State Hub legacy-meter.

Done when new automations subscribe to the workplan subject and the workstream subject is marked legacy with a published sunset date.

Task: Domain repo prose sweep (template-driven)

id: CUST-WP-0055-T04
status: todo
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 workstream 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:workstream hits in agent-guidance buckets.

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

id: CUST-WP-0055-T05
status: todo
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, inter-hub. Rename variables, comments, and client payloads to workplan where they denote the domain concept; keep wire-compat keys until T02 retires the API alias.

Task: Generated and bulk-content repos

id: CUST-WP-0055-T06
status: todo
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.

Task: Historical workplan and archive hygiene

id: CUST-WP-0055-T07
status: todo
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 workstream. Optionally normalize titles in archived files when the edit is mechanical (no ID renames).

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

Task: Verification gate and legacy-meter criteria

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

Define fleet exit criteria:

1. scan_workstream_terminology.py — zero prose:workstream across domain repos; state-hub under agreed grep budget.
2. State Hub legacy-meter weekly review — no new prose-only legacy keys.
3. fix-consistency / interface-change registry — no new workstream-named public tools without a workplan alias.
4. Add a CI or activity-core scheduled check that fails when prose hits regress.

Done when all four checks are automated and the 2026-07-08 baseline is stored in the scan JSON artefact committed beside this workplan's T01 completion.

Sequencing

T01 canon/templates
 ├─ T02 state-hub retirement plan (STATE-WP-0069)
 ├─ T03 activity-core events
 ├─ T04 domain prose sweep (parallel batches)
 ├─ T05 code sweep
 └─ T06 generated repos
T07 archives (low priority, anytime)
T08 verification gate (continuous; closes plan)

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).