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 (workplan → workplan)	infotech	the-custodian	finished	codex	custodian	medium	55	2026-07-08	2026-07-08	3339cc4e-da3e-5eb5-802a-f23d3176f021

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:

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

id: CUST-WP-0055-T01
status: done
priority: high
state_hub_task_id: "9ec4429e-54f5-5a6b-80ba-6c84afdd9cea"

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

id: CUST-WP-0055-T02
status: done
priority: high
state_hub_task_id: "040ba1e7-9ef6-5fde-b333-73c583c07c4a"

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

id: CUST-WP-0055-T03
status: done
priority: high
state_hub_task_id: "8c06b082-3348-5141-81ea-55a503c02561"

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)

id: CUST-WP-0055-T04
status: done
priority: medium
state_hub_task_id: "4decee88-ec91-5003-a438-a72ca4fc5951"

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

id: CUST-WP-0055-T05
status: done
priority: medium
state_hub_task_id: "da96f641-267b-59e9-9721-a9ae39a7bea6"

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

id: CUST-WP-0055-T06
status: done
priority: medium
state_hub_task_id: "40c84aba-ce98-5945-bb14-13df0f9abd4b"

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

id: CUST-WP-0055-T07
status: done
priority: low
state_hub_task_id: "18d9119f-71f0-59cd-8dbd-f89e0f973a7c"

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

id: CUST-WP-0055-T08
status: done
priority: high
state_hub_task_id: "90f9f731-5cb2-5a39-b593-a1b4d4e12b2b"

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