Complete workplan state model cleanup

docs/cron-migration.md

@@ -16,7 +16,7 @@ keeps the underlying scripts; only the *scheduling* moves.
 | # | Source              | Trigger today                                            | Script invoked                                           | What it does                                                                                       |
 | - | ------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | 1 | systemd user timer  | every 15 min                                             | `scripts/consistency_check.py --remote --all`            | Pull every registered repo, reconcile workplan files ↔ DB, run C-15 writeback + C-16 pull gate    |
-| 2 | manual / daily cron | `make cleanup-stale` (suggested `0 3 * * *`)             | `scripts/cleanup_stale_tasks.py`                         | Cancel tasks still open in completed/archived workstreams; emits `org.statehub.task.stale`        |
+| 2 | manual / daily cron | `make cleanup-stale` (suggested `0 3 * * *`)             | `scripts/cleanup_stale_tasks.py`                         | Cancel tasks still open in finished/archived workstreams; emits `org.statehub.task.stale`         |
 | 3 | git post-commit     | every commit in a registered repo                        | `make fix-consistency REPO=<slug>`                       | Per-repo workplan ↔ DB sync immediately after a commit                                            |
 
 Honourable mentions (not currently scheduled, on-demand only — listed for
@@ -79,7 +79,7 @@ Notes:
 id: the-custodian.state-hub-stale-task-cleanup
 description: |
   Daily sweep that cancels tasks still 'todo|in_progress|blocked' inside
-  completed or archived workstreams. Each cancellation also emits
+  finished or archived workstreams. Each cancellation also emits
   org.statehub.task.stale on NATS for downstream reaction.
 trigger:
   trigger_type: cron

docs/nats-event-subjects.md

@@ -42,7 +42,7 @@ those publishers from colliding on the same `{noun}.{verb}` shape.
 | Subject                              | When                                                         | Required attributes                                                                                                          |
 | ------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
 | `org.statehub.repo.registered`       | A new repo is registered via `POST /repos/`                  | `repo_id`, `repo_slug`, `domain_slug`, `remote_url?`, `local_path?`                                                          |
-| `org.statehub.workstream.completed`  | A workstream transitions to status `completed`               | `workstream_id`, `slug`, `title`, `topic_id`, `repo_id?`, `repo_goal_id?`                                                    |
+| `org.statehub.workstream.completed`  | A workstream transitions to canonical status `finished`      | `workstream_id`, `slug`, `title`, `topic_id`, `repo_id?`, `repo_goal_id?`                                                    |
 | `org.statehub.decision.resolved`     | A decision is resolved via `POST /decisions/{id}/resolve`    | `decision_id`, `title`, `topic_id?`, `workstream_id?`, `decided_by`, `rationale_snippet`                                     |
 | `org.statehub.domain.goal.activated` | A domain goal transitions to `active`                        | `goal_id`, `domain_id`, `domain_slug`, `title`, `superseded_goal_ids[]`                                                      |
 | `org.statehub.task.stale`            | `scripts/cleanup_stale_tasks.py` cancels an out-of-date task | `task_id`, `workstream_id`, `workstream_status`, `task_title`, `task_status_before`                                          |

docs/task-flow-engine-spec.md

@@ -129,10 +129,10 @@ blocking_assertions:
     passed: false
     reason: "Expected all values at tasks.*.status to be in ['done', 'cancelled']; got ['done', 'todo']."
 reachable:
-  - todo
+  - ready
   - active
 unreachable:
-  - workstation: completed
+  - workstation: finished
     blocking:
       id: tasks.all_done
       passed: false
@@ -151,9 +151,9 @@ Schema:
 
 ### Workstreams
 
-Workstreams can express readiness for completion by asserting that child tasks
+Workstreams can express readiness for closure by asserting that child tasks
 are `done` or `cancelled`. They can express dependency blocking by checking that
-all dependency workstreams have reached `completed`.
+all dependency workstreams have reached `finished` or `archived`.
 
 ### Tasks
 

docs/workplan-convention.md

@@ -14,7 +14,7 @@ type: workplan
 title: "Short Title"
 domain: custodian
 repo: state-hub
-status: active
+status: proposed
 owner: custodian
 topic_slug: custodian
 ```
@@ -22,3 +22,14 @@ topic_slug: custodian
 During extraction, legacy `CUST-WP-*` plans may be bridged or migrated with
 their existing `state_hub_workstream_id` values. Write files first, then run
 State Hub consistency sync after this repo is registered.
+
+Canonical workplan/workstream statuses are:
+
+```text
+proposed, ready, active, blocked, backlog, finished, archived
+```
+
+Use `proposed` for a new plan that still needs review, `ready` after it has
+been checked against the current repo state, and `finished` when implementation
+is complete. `stalled` and `needs_review` are derived health labels, not stored
+frontmatter statuses.