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
- Write workplan in instructions, orientation steps, and error messages aimed at humans or coding agents.
- Mention workstream only in an explicit compatibility footnote, e.g.: > Legacy term: State Hub still exposes
/workstreamsandworkstream_id> aliases until legacy-meter retires them (STATE-WP-0069). - Leave unchanged in code or docs when the string is a wire key, route, legacy-meter registry entry, or
state_hub_workstream_idfrontmatter field. - Prefer
GET /workplans/andworkplan_idin 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_idin workplan frontmatter. - Database table or ORM model renames (completed in
STATE-WP-0065). - Rewriting archived workplan bodies in bulk (
CUST-WP-0055T07).
References
canon/architecture/adr-001-workplans-as-repo-artefacts.mdstate-hub/docs/workplan-terminology-transition.mdstate-hub/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.mdstate-hub/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.mdworkplans/CUST-WP-0055-workplan-terminology-fleet-refactor.md