--- id: canon-workplan-terminology-fleet type: standard title: "Workplan Terminology (Fleet) v0.1" domain: custodian status: accepted version: "0.3" owner: the-custodian revision: "accepted-2" last_reviewed: "2026-09-14" review_interval: 6m created: "2026-07-08" updated: "2026-09-14" scope: fleet related_workplans: - CUST-WP-0055 - STATE-WP-0054 - STATE-WP-0069 - CUST-WP-0060 - STATE-WP-0092 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. ## Flavor and depends_on (v0.3 addendum, STATE-WP-0092) Workplans and tasks may carry **flavor**: `planning`, `implementation`, `refactoring`, `extension`, or `residual`. Flavor is a bucket, not a kind and not a status. `residual` leftovers are live records but are **not** equal to main functional/non-functional demand. Default State Hub open views omit them until demand or risk promotes the flavor. Workplan frontmatter `depends_on` is the canonical list of blocker workplan ids. Prefer that spelling over `depends_on_workplans`. Normative detail: `work-record-types_v0.1.md` § Flavor. 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 --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`