generated from coulomb/repo-seed
148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
---
|
|
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.
|