## Purpose

Define workplan as the canonical fleet term for repo-backed deliverable work indexed by State Hub. Preserve explicit legacy bridges where APIs, events, generated fields, or historical documents still say `workstream`, until metered retirement criteria are met.

This standard complements:

- ADR-001 — workplans originate as repo files; the hub indexes them.
- STATE-WP-0054 — State Hub compatibility layer and `legacy-meter`.
- STATE-WP-0069 — State Hub legacy interface retirement (child plan).
- CUST-WP-0055 — fleet-wide coordination and prose migration.

Authoritative interface matrix for State Hub: `state-hub/docs/workplan-terminology-transition.md`.

## Canonical term

Concept | Fleet term | Meaning
--- | --- | ---
Repo-backed body of work | workplan | Markdown file under `workplans/` per ADR-001
Workplan file id | `{PREFIX}-WP-NNNN` | e.g. `CUST-WP-0055`, `STATE-WP-0069`
Hub index row | workplan (product term) | DB entity keyed by UUID; may still use legacy column names internally
Task within a workplan | task | `id: {WP}-TNN` in workplan file blocks

## Work-record umbrella (v0.2 addendum, CUST-WP-0060)

The workplan and task definitions above are unchanged. Since v0.2 they are two kinds of the fleet umbrella term work record — any identified, lifecycle-bearing coordination artefact. The full kind registry (workplan, task, intake item, decision, engagement, register entry), the conventional spine, identity layering (UUIDv7 internal, canonical names external), and grandfathered legacy id schemes (`AWQ-`, `DEC-`, `OH-`) are normative in `work-record-types_v0.1.md` (+ machine registry `work-record-types.yaml`). Autonomy-lane vocabulary is normative in `autonomy-lanes_v0.1.md`. "Suggestion" is a legacy bridge name for the intake kind (state-hub suggestions table: read-only legacy pending close-out). This file keeps its `_v0.1` name for reference stability; the frontmatter `version` field is authoritative.

Use workplan in human-facing prose: `SCOPE.md`, `AGENTS.md`, `INTENT.md`, README, workplan bodies, operator runbooks, and agent session guidance.

## Legacy bridges (keep until retired)

Do not mass-rename these in the CUST-WP-0055 migration window:

Surface | Canonical | Legacy bridge | Retirement owner
--- | --- | --- | ---
Workplan frontmatter link | (implicit workplan UUID) | `state_hub_workstream_id` | Separate bridge-field migration
REST/MCP parameters | `workplan_id` | `workstream_id` | `STATE-WP-0069` + legacy-meter
REST routes | `/workplans/` | `/workstreams/` | `STATE-WP-0069`
MCP procedures | `create_workplan`, etc. | `create_workstream`, etc. | `STATE-WP-0069`
State Hub completion event | `org.statehub.workplan.completed` | `org.statehub.workstream.completed` | `STATE-WP-0069` T05
activity-core catalog (custodian-era) | `org.statehub.workplan.completed` | `org.workstream.completed` | `CUST-WP-0055` T03
Archived workplan prose | workplan (when editing) | historical "workstream" text | Grandfathered; header note only
Grandfathered filenames | — | paths containing `workstream` | ADR-001 non-rename policy

Do not introduce a bare `org.workplan.completed` event subject. State Hub uses the `org.statehub.*` namespace.

## Event subjects (normative)

Subject | Status | Notes
--- | --- | ---
`org.statehub.workplan.completed` | preferred | Emitted on workplan finish; subscribe here
`org.statehub.workstream.completed` | legacy (metered) | Dual-published today; retire per legacy-meter
`org.workstream.completed` | legacy (catalog) | activity-core custodian-era type; align to State Hub subject

## Agent and documentation rules

1. Write workplan in instructions, orientation steps, and error messages aimed at humans or coding agents.
2. Mention workstream only in an explicit compatibility footnote, e.g.: > Legacy term: State Hub still exposes `/workstreams` and `workstream_id` > aliases until legacy-meter retires them (`STATE-WP-0069`).
3. Leave unchanged in code or docs when the string is a wire key, route, legacy-meter registry entry, or `state_hub_workstream_id` frontmatter field.
4. Prefer `GET /workplans/` and `workplan_id` in new examples and scripts.

Regenerated agent files (`state-hub/scripts/update_agent_instruction_files.py`) should follow rules 1–2. Templates live under `state-hub/scripts/project_rules/*.template`.

## Retirement rule (unchanged)

A legacy interface may be removed only when all are true:

- registered in State Hub `legacy-meter`;
- replacement reference verified;
- no manual hold;
- zero measured calls in the review window.

State Hub owns usage evidence; activity-core may run weekly review activities. See `state-hub/docs/workplan-terminology-transition.md`.

## Verification

Fleet terminology drift is measured with:

    python tools/scan_workstream_terminology.py
    python tools/scan_workstream_terminology.py --repo <slug> --json

Baseline artefact (2026-07-08): `docs/evidence/workstream-terminology-baseline-20260708.json`.

Exit criteria and scan exclusions: `CUST-WP-0055` T08.

## Out of scope (this standard)

- Renaming `state_hub_workstream_id` in workplan frontmatter.
- Database table or ORM model renames (completed in `STATE-WP-0065`).
- Rewriting archived workplan bodies in bulk (`CUST-WP-0055` T07).

## References

- `canon/architecture/adr-001-workplans-as-repo-artefacts.md`
- `state-hub/docs/workplan-terminology-transition.md`
- `state-hub/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md`
- `state-hub/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md`
- `workplans/CUST-WP-0055-workplan-terminology-fleet-refactor.md`