the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md

---
id: canon-workplan-terminology-fleet
type: standard
title: "Workplan Terminology (Fleet) v0.1"
domain: custodian
status: accepted
version: "0.2"
owner: the-custodian
revision: "accepted-1"
last_reviewed: "2026-08-31"
review_interval: 6m
created: "2026-07-08"
updated: "2026-07-20"
scope: fleet
related_workplans:
  - CUST-WP-0055
  - STATE-WP-0054
  - STATE-WP-0069
  - CUST-WP-0060
supersedes: none
---

# Workplan Terminology (Fleet) v0.1

## 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:

```bash
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`