generated from coulomb/repo-seed
154 lines
4.6 KiB
Markdown
154 lines
4.6 KiB
Markdown
---
|
|
id: STATE-WP-0047
|
|
type: workplan
|
|
title: "Lifecycle Assertions and Renormalization"
|
|
domain: custodian
|
|
repo: state-hub
|
|
status: proposed
|
|
owner: codex
|
|
topic_slug: custodian
|
|
planning_priority: high
|
|
planning_order: 47
|
|
created: "2026-05-23"
|
|
updated: "2026-05-23"
|
|
state_hub_workstream_id: "1972d1d9-fc35-4912-8126-1fe64cc51425"
|
|
---
|
|
|
|
# STATE-WP-0047 - Lifecycle Assertions and Renormalization
|
|
|
|
## Goal
|
|
|
|
Make workplan and task lifecycle management deterministic: starting work should
|
|
advance the workplan/workstream to `active`, finishing all executable work
|
|
should make closure obvious, and any direct manipulation that violates the model
|
|
should be detected and repaired by clear helper functions.
|
|
|
|
## Context
|
|
|
|
The current canonical vocabulary is good, but enforcement is incomplete. A
|
|
workstream can remain `proposed` while tasks are actively worked, as seen with
|
|
`RAIL-FAB-WP-0016`. The flow engine can report blocked exit assertions, but the
|
|
state changes themselves do not consistently use a shared transition layer.
|
|
|
|
This workplan turns the vocabulary into executable rules and repair scaffolding.
|
|
|
|
## T01 - Define Lifecycle Invariants
|
|
|
|
```task
|
|
id: STATE-WP-0047-T01
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "28f28391-646c-4871-ae84-a1c1aae3f5bf"
|
|
```
|
|
|
|
Write a concise lifecycle invariant table for workplans/workstreams and tasks.
|
|
Include rules such as: active tasks imply an active workstream; finished
|
|
workstreams cannot have open tasks unless explicitly blocked/grandfathered;
|
|
archived files must have closed states; and `needs_review`/`stalled` remain
|
|
derived labels.
|
|
|
|
Done when the invariant table is documented and each rule is classified as
|
|
hard error, warning, automatic repair, or human-review item.
|
|
|
|
## T02 - Implement Shared Transition Helpers
|
|
|
|
```task
|
|
id: STATE-WP-0047-T02
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "56d9b6b9-fba1-4997-bdd5-875187cafa2d"
|
|
```
|
|
|
|
Add deterministic helper functions for task and workstream transitions instead
|
|
of scattering direct status writes. The helpers should normalize aliases, check
|
|
entry and exit assertions, and return concise repair/action results.
|
|
|
|
Done when API routes, consistency tooling, and future UI actions can call one
|
|
shared transition layer for lifecycle changes.
|
|
|
|
## T03 - Auto-Advance Workstream On Task Start
|
|
|
|
```task
|
|
id: STATE-WP-0047-T03
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "b0937fed-bd61-4f27-9586-8cebc6168827"
|
|
```
|
|
|
|
When a task moves from `todo` to `in_progress`, ensure the owning workstream
|
|
advances from `proposed`, `ready`, or `backlog` to `active`, unless an explicit
|
|
guard blocks the transition.
|
|
|
|
Done when starting real task work cannot leave the parent workstream parked in
|
|
planning states.
|
|
|
|
## T04 - Harden Flow Advancement Semantics
|
|
|
|
```task
|
|
id: STATE-WP-0047-T04
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "3f1e49fd-0600-4124-a7bc-0c75955bac8b"
|
|
```
|
|
|
|
Make flow advancement honor both current exit assertions and target entry
|
|
assertions. Return actionable blocking assertions when a transition is refused.
|
|
|
|
Done when `/flows/.../advance/...` cannot bypass the same assertions the flow
|
|
state endpoint reports as blocking.
|
|
|
|
## T05 - Add Renormalization Checks And Repairs
|
|
|
|
```task
|
|
id: STATE-WP-0047-T05
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "611f0c22-34bc-494e-b520-068b4c3f0fec"
|
|
```
|
|
|
|
Extend consistency tooling with invariant checks that detect drift from clean
|
|
workplan/task modelling and either repair it or report a precise fix. Include
|
|
the `proposed workstream with in_progress task` case.
|
|
|
|
Done when direct DB or file manipulation that breaks lifecycle invariants is
|
|
caught by a repeatable repair path.
|
|
|
|
## T06 - Record Drift As Learning Input
|
|
|
|
```task
|
|
id: STATE-WP-0047-T06
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "4b663fce-876c-4a52-955c-c754dbf44b0f"
|
|
```
|
|
|
|
When the system recognizes a new drift pattern, provide a lightweight way to
|
|
turn that pattern into a new invariant, test, or consistency repair.
|
|
|
|
Done when renormalization scaffolding has an explicit "add the next guard here"
|
|
pattern instead of relying on ad hoc fixes.
|
|
|
|
## T07 - Regression Tests
|
|
|
|
```task
|
|
id: STATE-WP-0047-T07
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "def5ce49-1938-4c45-807d-78ac15c995cb"
|
|
```
|
|
|
|
Add tests for transition helpers, task-start parent activation, flow assertion
|
|
enforcement, and consistency repairs.
|
|
|
|
Done when lifecycle drift is hard to reintroduce accidentally.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Starting task work deterministically activates the parent workstream.
|
|
- Flow transitions evaluate current exit assertions and target entry
|
|
assertions.
|
|
- Lifecycle invariants are documented, tested, and enforced through shared
|
|
helpers.
|
|
- Consistency tooling repairs or reports lifecycle drift with low-token,
|
|
deterministic messages.
|