## Workplan Convention (ADR-001) File location: `workplans/{WP_PREFIX}-NNNN-.md` ID prefix: `{WP_PREFIX}-` Work items originate as files in this repo **before** being registered in the hub. Canonical workplan frontmatter statuses are: `proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`. Use `proposed` for a newly drafted plan, `ready` after review against current repo state, and `finished` when implementation is complete. `stalled` and `needs_review` are derived health labels, not stored statuses. Closed workplans may be moved to `workplans/archived/` with a completion-date prefix: `YYMMDD-{WP_PREFIX}-NNNN-.md`. The frontmatter id remains unchanged; the prefix is only for quick visual reference. Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: `workplans/ADHOC-YYYY-MM-DD.md`, workplan id `{WP_PREFIX}-ADHOC-YYYY-MM-DD`, and task ids `{WP_PREFIX}-ADHOC-YYYY-MM-DD-T01`, `T02`, etc. `{WP_PREFIX}` includes its final `-WP` token. Unqualified historic `ADHOC-*` ids are grandfathered and must not be copied into new records. Use adhocs only for low-risk work completed directly. Promote anything requiring analysis, design, approval, dependencies, or multiple planned phases into a normal workplan. Ecosystem todos from other agents arrive as `[repo:{REPO_SLUG}]` hub tasks — visible at session start. Pick one up by creating the workplan file, then run the fast authoritative projection path: ```bash uv run --project ~/repo-manager rmgr sync --path . --push ``` Repo Manager assigns only missing deterministic identifiers. Central reads the exact pushed Forgejo commit and updates its replaceable projection. Never register by hand with `create_workplan` or `create_task`. Use `statehub fix-consistency` separately for a deep audit. Task blocks use this shape: ```task id: {WP_PREFIX}-NNNN-T01 status: wait | todo | progress | done | cancel priority: high | medium | low state_hub_task_id: "" # written by fix-consistency — do not edit ``` Status progression is `todo` → `progress` → `done`; use `wait` for waiting or blocked work and `cancel` for stopped work. ### Residuals (role, not kind) When finishing a workplan, **actionable leftovers must become live work records** before `status: finished`. Residual is not a registered kind and must not be parked only in `SCOPE.md` or finished-file prose. | Shape | Capture as | Links | | --- | --- | --- | | Small Green/Blue parkable | intake (queue YAML / `*-IN-*`) | `origin: residual`, `origin_ref: {WP_PREFIX}-NNNN` | | Multi-step | next workplan | name parent WP; optional promote from residual intake | | Founder gate / time | decision / engagement | same origin fields when from residual intake | Fleet listing of residuals is a State Hub concern (`list_intakes` + origin filters; planned `statehub residuals`). Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals. Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name kept for compatibility; it holds the hub workplan UUID and is written by fix-consistency. Do not edit or rename it. ### Legacy terminology (compatibility footnote) **Workplan** is the fleet term — see `the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. **Workstream** is legacy only: some API routes (`/workstreams/`), params (`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new examples and scripts. ### Task refinement after substantial work (required) At each substantive checkpoint and before session close, compare the completed work and new knowledge with the current task structure. If substantial work was completed while the workplan's task granularity stayed unchanged, **add completed task records for those evidenced outcomes and refine the remaining tasks**. A long progress note inside the same broad open task does not satisfy this rule. - Give each substantial completed deliverable a task with its actual outcome, completion date, evidence and limits. Retrospective recording is allowed; do not invent completion dates, deliveries, native acceptance or approvals. - Split remaining work into independently manageable deliverables with an owner, next action, completion criteria and real dependencies. Use `todo` for work that can start; use `wait` only with a concrete prerequisite and unblock condition. - Preserve existing task IDs, Hub UUIDs and history. When narrowing an umbrella task, explain the split and map moved scope to the new task IDs. Do not mark the umbrella done unless its retained scope is complete; preserve externally referenced acceptance gates until their dependencies are satisfied. - Keep task counts honest: extracting completed scope must not count the same outcome twice or imply an effort-based completion percentage. Distinguish source/fixture proof, actual operational proof and owner acceptance. - Record new risks and out-of-scope findings as explicit disposition/handoff tasks or linked live work records; do not silently expand authorization. Make these changes in the repository source, commit/push, run the repository's required projection sync, and verify the actual projected task counts, statuses and dependencies. Progress events supplement the task structure; they do not replace it. A checkpoint report must show both substantive outcomes and newly refined remaining work when this rule is triggered.