state-hub/workplans/STATE-WP-0047-lifecycle-assertions-and-renormalization.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
STATE-WP-0047	workplan	Lifecycle Assertions and Renormalization	custodian	state-hub	proposed	codex	custodian	high	47	2026-05-23	2026-05-23	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

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

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

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

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

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

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

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.