tegwick
4ab66e363e
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a13eab-1e6a-7b33-9c37-372e90ada3a2
96 lines
4 KiB
Markdown
96 lines
4 KiB
Markdown
# State Hub Workplan Convention
|
|
|
|
New workplans in this repository use:
|
|
|
|
```text
|
|
STATE-WP-0001-short-title.md
|
|
```
|
|
|
|
Workplan frontmatter should include:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```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.
|
|
|
|
### 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.
|