docs(CUST-WP-0055): fix review gaps before ready promotion

Clarify State Hub vs activity-core event subjects, require STATE-WP-0069
draft in T02, add scan exclusions and ready gate, drop inter-hub-haskell
from active sweep, and reorder sequencing.

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

@@ -7,7 +7,7 @@ repo: the-custodian
 status: proposed
 owner: codex
 topic_slug: custodian
-planning_priority: high
+planning_priority: medium
 planning_order: 55
 created: "2026-07-08"
 updated: "2026-07-08"
@@ -38,7 +38,7 @@ widespread outside State Hub internals:
 | Repos with `workstream` hits | 73 |
 | Total occurrences | 22,237 |
 | Files touched | 7,823 |
-| Missing local checkouts | `markitect-project`, `vergabe_teilnahme` |
+| Missing local checkouts | `markitect-project`, `vergabe_teilnahme` — exclude from exit counts until paths exist or repos marked dormant |
 
 **Top repos by hit count**
 
@@ -80,13 +80,34 @@ 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 / activity events | `org.statehub.workplan.completed` | `org.workstream.completed` | Dual-publish then retire |
+| 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 |
 | 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.workstream.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
+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
@@ -114,13 +135,19 @@ 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
+**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 `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).
+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.
 
 ## Task: activity-core event and resolver migration
 
@@ -131,13 +158,24 @@ 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.
+Align activity-core to State Hub's existing dual-publish contract:
 
-Done when new automations subscribe to the workplan subject and the workstream
-subject is marked legacy with a published sunset date.
+| 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` |
+
+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.
+
+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)
 
@@ -154,7 +192,8 @@ 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.
+`prose:workstream ` 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-*)
 
@@ -167,9 +206,13 @@ 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.
+`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.
 
 ## Task: Generated and bulk-content repos
 
@@ -216,31 +259,52 @@ priority: high
 state_hub_task_id: "5b6596ef-fd04-4469-b421-f548d292cb0d"
 ```
 
-Define fleet exit criteria:
+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:workstream ` across domain
-   repos; `state-hub` under agreed grep budget.
+   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
    public tools without a workplan alias.
-4. Add a CI or activity-core scheduled check that fails when prose hits regress.
+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
-in the scan JSON artefact committed beside this workplan's T01 completion.
+as `docs/evidence/workstream-terminology-baseline-20260708.json` (or equivalent)
+at 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
+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)
-T08 verification gate (continuous; closes plan)
 ```
 
+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`