From c6bf33a398115e2c3c89c893ab45cdc171f11231 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 23 May 2026 15:54:47 +0200 Subject: [PATCH] Workplan consistency improvement workplans --- ...STATE-WP-0046-workplan-id-normalization.md | 140 ++++++++++++++++ ...ifecycle-assertions-and-renormalization.md | 153 ++++++++++++++++++ ...-WP-0048-ui-state-change-reconciliation.md | 147 +++++++++++++++++ .../STATE-WP-0049-workplan-execution-queue.md | 148 +++++++++++++++++ 4 files changed, 588 insertions(+) create mode 100644 workplans/STATE-WP-0046-workplan-id-normalization.md create mode 100644 workplans/STATE-WP-0047-lifecycle-assertions-and-renormalization.md create mode 100644 workplans/STATE-WP-0048-ui-state-change-reconciliation.md create mode 100644 workplans/STATE-WP-0049-workplan-execution-queue.md diff --git a/workplans/STATE-WP-0046-workplan-id-normalization.md b/workplans/STATE-WP-0046-workplan-id-normalization.md new file mode 100644 index 0000000..2e9f29e --- /dev/null +++ b/workplans/STATE-WP-0046-workplan-id-normalization.md @@ -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. diff --git a/workplans/STATE-WP-0047-lifecycle-assertions-and-renormalization.md b/workplans/STATE-WP-0047-lifecycle-assertions-and-renormalization.md new file mode 100644 index 0000000..b24915c --- /dev/null +++ b/workplans/STATE-WP-0047-lifecycle-assertions-and-renormalization.md @@ -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. diff --git a/workplans/STATE-WP-0048-ui-state-change-reconciliation.md b/workplans/STATE-WP-0048-ui-state-change-reconciliation.md new file mode 100644 index 0000000..2b5dce0 --- /dev/null +++ b/workplans/STATE-WP-0048-ui-state-change-reconciliation.md @@ -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. diff --git a/workplans/STATE-WP-0049-workplan-execution-queue.md b/workplans/STATE-WP-0049-workplan-execution-queue.md new file mode 100644 index 0000000..b1455ac --- /dev/null +++ b/workplans/STATE-WP-0049-workplan-execution-queue.md @@ -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.