coulomb/state-hub
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Workplan consistency improvement workplans

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-23 15:54:47 +02:00
parent c12091c2eb
commit c6bf33a398
4 changed files with 588 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
workplans/STATE-WP-0046-workplan-id-normalization.md Normal file
View File

@@ -0,0 +1,140 @@
---
id: STATE-WP-0046
type: workplan
title: "Workplan ID Normalization and Legacy Cleanup"
domain: custodian
repo: state-hub
status: proposed
owner: codex
topic_slug: custodian
planning_priority: high
planning_order: 46
created: "2026-05-23"
updated: "2026-05-23"
state_hub_workstream_id: "2370b7cb-affd-4bf2-a193-84e73ec53cd3"
---
# STATE-WP-0046 - Workplan ID Normalization and Legacy Cleanup
## Goal
Reduce broken-window drift in State Hub workplan management by normalizing
workplan prefixes, task IDs, filenames, and references where migration is safe,
while preserving State Hub DB continuity and leaving explicit legacy exceptions
where renaming would create more confusion than it removes.
## Context
State Hub is now a standalone repository, but it still carries extracted
`CUST-WP-*` files and short task IDs such as `T01`. The runtime consistency
checker passes, but strict ADR validation still reports task-ID format warnings
for migrated workplans. Documentation also disagrees on the new local prefix:
`AGENTS.md` uses `STATE-WP-*`, while older State Hub docs mention `SHUB-WP-*`.
The cleanup should prefer deterministic renames and mechanical reference
updates, but it must not break existing `state_hub_workstream_id` or
`state_hub_task_id` links.
## T01 - Inventory ID And Prefix Drift
```task
id: STATE-WP-0046-T01
status: todo
priority: high
state_hub_task_id: "e966289f-bb27-4da0-b00c-2bba2751fad7"
```
Build an inventory of all local State Hub workplan files, frontmatter IDs,
filenames, task IDs, State Hub workstream IDs, task IDs, and references from
docs/tests/scripts.
Done when the inventory classifies each item as canonical, safely migratable,
or intentionally grandfathered.
## T02 - Decide Canonical Prefix Policy
```task
id: STATE-WP-0046-T02
status: todo
priority: high
state_hub_task_id: "ee965266-4578-4ad1-b5b7-481e243a67dc"
```
Record the canonical State Hub-local prefix decision and update conflicting
guidance so new workplans consistently use `STATE-WP-*`.
Done when `AGENTS.md`, `SCOPE.md`, `README.md`, templates, and docs no longer
disagree on `STATE-WP-*` versus `SHUB-WP-*`.
## T03 - Normalize Safe Workplan IDs And Filenames
```task
id: STATE-WP-0046-T03
status: todo
priority: high
state_hub_task_id: "fd753850-93ba-4daa-9664-466f07097af5"
```
Rename safely migratable local files and frontmatter IDs to canonical
`STATE-WP-*` names, preserving existing State Hub UUID links and updating
references in docs, tests, scripts, dashboard docs, and workplan dependency
text.
Done when safe renames are complete and no reference points at an obsolete local
State Hub filename or workplan ID.
## T04 - Normalize Safe Task IDs
```task
id: STATE-WP-0046-T04
status: todo
priority: high
state_hub_task_id: "6d60cd2c-0b0c-41e8-a957-b04a5fe0b31e"
```
Replace short extracted task IDs such as `T01` with full canonical IDs such as
`STATE-WP-NNNN-T01` where the mapping is unambiguous, preserving
`state_hub_task_id` links.
Done when strict ADR validation has no task-ID-format warnings for workplans
that were safe to normalize.
## T05 - Encode Legacy Exceptions
```task
id: STATE-WP-0046-T05
status: todo
priority: medium
state_hub_task_id: "a5a77bbe-4aa5-4e9a-9387-400a0093ed39"
```
For items that should remain legacy, add explicit machine-readable or
documented exceptions so future agents understand that the drift is intentional
and not fresh neglect.
Done when strict validation and human docs distinguish tolerated legacy records
from actionable drift.
## T06 - Verify Consistency And ADR Compliance
```task
id: STATE-WP-0046-T06
status: todo
priority: high
state_hub_task_id: "69a3255c-1cc9-47d0-9947-350a443173d8"
```
Run State Hub consistency sync/checks and strict ADR validation after the
migration. Confirm the DB still points at the intended workstreams and tasks.
Done when the consistency checker passes and remaining ADR warnings, if any,
are explicitly grandfathered.
## Acceptance Criteria
- New State Hub-local workplans consistently use `STATE-WP-*`.
- Safe legacy IDs and short task IDs are normalized without losing State Hub
UUID links.
- Remaining legacy exceptions are explicit and auditable.
- `make fix-consistency REPO=state-hub` and strict ADR validation no longer
produce avoidable ID-format noise.

153
workplans/STATE-WP-0047-lifecycle-assertions-and-renormalization.md Normal file
View File

@@ -0,0 +1,153 @@
---
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.

147
workplans/STATE-WP-0048-ui-state-change-reconciliation.md Normal file
View File

@@ -0,0 +1,147 @@
---
id: STATE-WP-0048
type: workplan
title: "UI State Change Reconciliation"
domain: custodian
repo: state-hub
status: proposed
owner: codex
topic_slug: custodian
planning_priority: high
planning_order: 48
created: "2026-05-23"
updated: "2026-05-23"
state_hub_workstream_id: "8cb9d9d3-ec8f-4690-bb22-b9b0b52b4125"
---
# STATE-WP-0048 - UI State Change Reconciliation
## Goal
Make State Hub UI state changes safe in an ADR-001 world: if a human changes a
workstream or task state in the dashboard, the file-backed workplan must either
be updated, queued for reconciliation, or explicitly marked as requiring human
follow-up.
## Context
State Hub is a live coordination surface, but workplan files remain the origin
of truth. Today a dashboard user can push a workstream back to `backlog` in the
DB while the repository file remains unchanged. The same mismatch can happen
for other workstream and task state transitions.
This workplan defines the reconciliation path between UI actions, DB state,
repo files, and scheduled cleanup.
## T01 - Classify UI State Changes
```task
id: STATE-WP-0048-T01
status: todo
priority: high
state_hub_task_id: "0332be96-ebc7-4a7b-97c6-bbe6ae3a66ac"
```
Define which dashboard state changes are safe to write through immediately to
repo files, which require a queued reconciliation task, and which require human
confirmation.
Done when each workstream/task transition has a reconciliation class and a
reason.
## T02 - Add Reconciliation API Contract
```task
id: STATE-WP-0048-T02
status: todo
priority: high
state_hub_task_id: "50c20ddf-f039-418b-a763-7a8f581be5b0"
```
Design and implement an API contract for UI-originated state changes that
captures intent, actor, target state, file-backed status, write-through result,
and follow-up action.
Done when dashboard actions no longer perform ambiguous direct status patches
without reconciliation metadata.
## T03 - Implement File Write-Through For Safe Changes
```task
id: STATE-WP-0048-T03
status: todo
priority: high
state_hub_task_id: "c0a4e976-81fb-4fe3-a8a9-b8262e2c1c85"
```
For safe transitions, update the relevant workplan frontmatter or task block in
the repo file, then sync the DB. Preserve formatting and existing
`state_hub_*_id` links.
Done when common dashboard transitions such as `active -> backlog` or task
status updates can update the file representation deterministically.
## T04 - Queue Reconciliation For Deferred Changes
```task
id: STATE-WP-0048-T04
status: todo
priority: high
state_hub_task_id: "2ed06c09-7b92-4b82-bcd3-090a1e320a88"
```
For changes that cannot be written immediately, create a reconciliation record,
message, or task that makes the pending file update visible and schedulable.
Done when UI changes that cannot write through are never silent DB-only drift.
## T05 - Surface Reconciliation State In Dashboard
```task
id: STATE-WP-0048-T05
status: todo
priority: medium
state_hub_task_id: "04025e9f-b1cc-4b73-b95a-2a53bad6b360"
```
Show whether a workstream/task is file-synced, pending write-through, blocked
on human review, or out of sync.
Done when a dashboard user can tell whether their state change has reached the
repo file or still needs reconciliation.
## T06 - Add Conflict Handling
```task
id: STATE-WP-0048-T06
status: todo
priority: high
state_hub_task_id: "b1769ce0-de21-4faf-9db4-75ebc8506044"
```
Handle cases where the repo file changed after the UI loaded, the workplan is
missing, the workplan is archived, or the State Hub host path is unavailable.
Done when reconciliation failures produce clear, actionable records instead of
partially applied state.
## T07 - Tests And Consistency Integration
```task
id: STATE-WP-0048-T07
status: todo
priority: high
state_hub_task_id: "7d7e36e8-783d-494f-9691-5213e35c7539"
```
Add API, dashboard, and consistency tests for UI-originated state changes and
deferred reconciliation.
Done when UI state changes are covered as first-class ADR-001 workflows.
## Acceptance Criteria
- Dashboard state changes never create silent DB/file divergence.
- Safe changes write through to workplan files and then sync to the DB.
- Deferred changes become visible reconciliation work.
- Conflicts and host-path failures are explicit and recoverable.

148
workplans/STATE-WP-0049-workplan-execution-queue.md Normal file
View File

@@ -0,0 +1,148 @@
---
id: STATE-WP-0049
type: workplan
title: "Workplan Execution Queue and Activity-Core Handoff"
domain: custodian
repo: state-hub
status: proposed
owner: codex
topic_slug: custodian
planning_priority: medium
planning_order: 49
created: "2026-05-23"
updated: "2026-05-23"
state_hub_workstream_id: "dd06578f-20b3-4473-bab3-8810eae29f39"
---
# STATE-WP-0049 - Workplan Execution Queue and Activity-Core Handoff
## Goal
Create a controlled way to prioritize, sequence, parallelize, and schedule
ready/active workplans, while keeping State Hub responsible for observable
state and leaving autonomous execution orchestration ready to move to
activity-core.
## Context
Changing a workplan from `proposed` to `active` can mean several different
things: start coding now, put it at the top of a queue, run in parallel with
other work, or wait for a human-selected launch window. State Hub should model
that intent cleanly without becoming an unbounded task factory.
The likely long-term split is: State Hub stores and exposes queue state,
priorities, dependencies, and handoff records; activity-core owns schedules,
automations, and agent dispatch.
## T01 - Define Queue Semantics
```task
id: STATE-WP-0049-T01
status: todo
priority: high
state_hub_task_id: "b69e3c7d-46be-4e88-b039-7aa82d653b53"
```
Define execution queue states, ordering fields, concurrency hints, and launch
modes for workplans. Include at least manual, queued, scheduled, immediate,
sequential, and parallel intent.
Done when queue semantics are documented without overloading lifecycle status.
## T02 - Separate Lifecycle From Execution Intent
```task
id: STATE-WP-0049-T02
status: todo
priority: high
state_hub_task_id: "4f48b4d4-7232-4e36-b4a2-03aaef684ab4"
```
Design schema/API changes so `status` remains the canonical lifecycle field and
execution intent lives in separate planning/execution fields.
Done when `active` no longer has to imply "dispatch a coding agent right now."
## T03 - Add Prioritized Workplan Stack
```task
id: STATE-WP-0049-T03
status: todo
priority: high
state_hub_task_id: "9237b778-4c83-4ebe-942e-79bae29aaa45"
```
Implement a prioritized stack or queue view for candidate workplans using
planning priority, planning order, dependencies, readiness, blockers, and
optional concurrency grouping.
Done when a human can choose what starts next from a clear ordered list.
## T04 - Add Launch Request Records
```task
id: STATE-WP-0049-T04
status: todo
priority: medium
state_hub_task_id: "a8366495-fd66-436e-b423-e24c3ffadbc9"
```
Introduce a durable launch-request or handoff record for "please start this
workplan" events, including requested actor, mode, priority, repo, branch
preference, and whether immediate agent pickup is desired.
Done when UI/API actions can request implementation without losing intent in a
plain status patch.
## T05 - Define Activity-Core Boundary
```task
id: STATE-WP-0049-T05
status: todo
priority: high
state_hub_task_id: "2ebf5186-9a92-476a-ac62-3588cc51fb31"
```
Document which responsibilities belong in State Hub and which should move to
activity-core. State Hub should expose state and requests; activity-core should
own scheduling, wakeups, and agent dispatch when available.
Done when the boundary is explicit enough that implementation can proceed in
State Hub now without trapping orchestration there permanently.
## T06 - Dashboard Controls
```task
id: STATE-WP-0049-T06
status: todo
priority: medium
state_hub_task_id: "7d1c9ec7-8130-4f26-92ae-754c6f28ea48"
```
Add dashboard controls for queue ordering, launch mode, parallel/sequential
intent, and manual versus immediate pickup.
Done when a user can move a workplan into the queue without accidentally
starting work, or explicitly request immediate pickup when desired.
## T07 - Handoff And Scheduling Tests
```task
id: STATE-WP-0049-T07
status: todo
priority: medium
state_hub_task_id: "f819907b-0409-411e-82d1-564c2d543f86"
```
Add tests for queue ordering, launch-request creation, dependency-aware
eligibility, and the State Hub/activity-core boundary contract.
Done when execution intent can evolve without contaminating lifecycle state.
## Acceptance Criteria
- Workplan lifecycle status is separate from execution intent.
- A prioritized workplan stack supports sequential and parallel pickup.
- UI/API actions can request immediate or deferred work explicitly.
- State Hub remains the state and handoff layer; activity-core remains the
natural owner for scheduling and agent dispatch.