147 lines
6.1 KiB
Markdown
147 lines
6.1 KiB
Markdown
---
|
||
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`
|