4.2 KiB
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-0048 | workplan | UI State Change Reconciliation | custodian | state-hub | proposed | codex | custodian | high | 48 | 2026-05-23 | 2026-05-23 | 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
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
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
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
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
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
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
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.