state-hub/docs/workplan-convention.md

State Hub Workplan Convention

New workplans in this repository use:

STATE-WP-0001-short-title.md

Workplan frontmatter should include:

id: STATE-WP-0001
type: workplan
title: "Short Title"
domain: custodian
repo: state-hub
status: proposed
owner: custodian
topic_slug: custodian
flavor: planning
depends_on: []

flavor is planning | implementation | refactoring | extension | residual. Unset is not residual. Default State Hub open views omit flavor: residual until demand or risk promotes it (STATE-WP-0092). depends_on lists blocker workplan ids; C-20 indexes that field.

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.

When a workplan is blocked, record the unblock condition in frontmatter:

status: blocked
blocked_on: message-from:llm-connect

blocked_on uses the message-from:<agent> form so fix-consistency can cross-check unread inbox messages from that counterpart and warn when the blocker may have cleared.

Canonical workplan/workstream statuses are:

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.

Residuals when finishing

If work remains after a plan is complete, do not leave it only as prose or in SCOPE.md. Before status: finished, hand off each actionable residual as a live work record:

• parkable Green/Blue → intake with origin: residual, origin_ref: <WP-id>
• multi-step → new workplan (optional promote from residual intake)
• founder gate/time → decision / engagement

Canon: the-custodian/canon/standards/work-record-types_v0.1.md § Residuals. Hub index/list: State Hub (not domain-local residual files).

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.