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

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

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