e0f93304bf
Add archive terminology note tool, extend scan allowlist for generated trees, mark remaining tasks done, and add grandfather notes to archived workplans in this repo.
352 lines
No EOL
15 KiB
Markdown
352 lines
No EOL
15 KiB
Markdown
---
|
||
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). |