feat(terminology): prose sweep tool and custodian workplan cleanup (CUST-WP-0055 T04)
Add sweep_workstream_prose.py for agent-guidance files, sweep active workplan prose in-repo, tighten scan allowlist exclusions, and update ADR-001 closure protocol to workplan-first terminology.
This commit is contained in:
codex
parent
3bdefb3c4a
commit
2e0deee2ef
42 changed files with 312 additions and 186 deletions
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
id: CUST-WP-0055
|
||||
type: workplan
|
||||
title: "Fleet-wide workplan terminology refactor (workstream → workplan)"
|
||||
title: "Fleet-wide workplan terminology refactor (workplan → workplan)"
|
||||
domain: infotech
|
||||
repo: the-custodian
|
||||
status: active
|
||||
|
|
@ -20,14 +20,14 @@ state_hub_workstream_id: "d96b72d5-24f2-492b-8bb4-50c39058848a"
|
|||
|
||||
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.
|
||||
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 `workstream` paths remain metered via `legacy-meter`.
|
||||
`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:
|
||||
|
|
@ -35,7 +35,7 @@ widespread outside State Hub internals:
|
|||
| Metric | Value |
|
||||
| --- | --- |
|
||||
| Registered repos scanned | 76 |
|
||||
| Repos with `workstream` hits | 73 |
|
||||
| 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 |
|
||||
|
|
@ -55,9 +55,9 @@ widespread outside State Hub internals:
|
|||
|
||||
| Pattern | Count | Refactor stance |
|
||||
| --- | ---: | --- |
|
||||
| `workstreams` (generic) | 13,108 | Prose/docs → `workplans`; code paths case-by-case |
|
||||
| `workplans` (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 |
|
||||
| `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` |
|
||||
|
|
@ -80,8 +80,8 @@ python tools/scan_workstream_terminology.py --repo the-custodian --json
|
|||
| 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.workstream.completed` | State Hub dual-publishes today; retire legacy per meter |
|
||||
| activity-core event catalog | `org.statehub.workplan.completed` | `org.workstream.completed` | Align catalog to State Hub subjects; retire custodian-era type |
|
||||
| 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 |
|
||||
|
||||
|
|
@ -90,10 +90,10 @@ 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.workstream.completed`** (legacy, metered) on the same
|
||||
**`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.workstream.completed`**
|
||||
(`activity-core/event-types/org.workstream.completed.md`). This plan aligns
|
||||
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.
|
||||
|
||||
|
|
@ -124,12 +124,12 @@ Update `state-hub/scripts/project_rules/*.template` so regenerated
|
|||
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.
|
||||
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/workstream-terminology-baseline-20260708.json`. Template regeneration (`state-hub/scripts/project_rules/*.template`) verified
|
||||
`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
|
||||
|
|
@ -145,8 +145,8 @@ state_hub_task_id: "2bb01721-a86b-43a0-ab4c-e5966743d295"
|
|||
`state-hub/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md`
|
||||
before any interface retirement executes.
|
||||
|
||||
**T02-T02:** inventory remaining `workstream` strings in dashboard, tests, flows
|
||||
(`flows/workstream.yaml`), and compat routers; tie each to a `legacy-meter`
|
||||
**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
|
||||
|
|
@ -169,14 +169,14 @@ 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.workstream.completed` | legacy (State Hub) | Document as legacy; register in legacy-meter if not already |
|
||||
| `org.workstream.completed` | legacy (custodian catalog) | Deprecate; map subscribers to `org.statehub.workplan.completed` |
|
||||
| `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.workstream.completed` in the activity-core catalog.
|
||||
`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
|
||||
|
|
@ -187,18 +187,18 @@ subscriptions.
|
|||
|
||||
```task
|
||||
id: CUST-WP-0055-T04
|
||||
status: todo
|
||||
status: progress
|
||||
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`;
|
||||
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:workstream ` hits in agent-guidance buckets (per T08 exclusions).
|
||||
`prose:workplan ` hits in agent-guidance buckets (per T08 exclusions).
|
||||
Batch ~10 repos per PR to limit merge churn.
|
||||
|
||||
## Task: Code and integration sweep (activity-core, issue-core, railiance-*)
|
||||
|
|
@ -249,10 +249,10 @@ 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
|
||||
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 `workstream` (e.g.
|
||||
Grandfathered filenames containing `workplan` (e.g.
|
||||
`CUST-WP-0010-workstream-lifecycle-docs.md`) keep their paths per ADR-001
|
||||
non-rename policy.
|
||||
|
||||
|
|
@ -282,17 +282,17 @@ script with `--apply-allowlist`.
|
|||
|
||||
**Exit criteria:**
|
||||
|
||||
1. `scan_workstream_terminology.py` — zero `prose:workstream ` across domain
|
||||
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 `workstream`-named
|
||||
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/workstream-terminology-baseline-20260708.json` (or equivalent)
|
||||
as `docs/evidence/workplan-terminology-baseline-20260708.json` (or equivalent)
|
||||
at T01 completion.
|
||||
|
||||
## Sequencing
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue