generated from coulomb/repo-seed
211 lines
8.0 KiB
Markdown
211 lines
8.0 KiB
Markdown
---
|
|
id: STATE-WP-0048
|
|
type: workplan
|
|
title: "UI State Change Reconciliation"
|
|
domain: custodian
|
|
repo: state-hub
|
|
status: finished
|
|
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.
|
|
|
|
## Reconciliation Classes
|
|
|
|
| Class | Meaning | Default follow-up |
|
|
|-------|---------|-------------------|
|
|
| `write_through` | The change can be represented directly in the workplan file. | Patch the file first, then sync the DB from file state. |
|
|
| `deferred` | The change cannot safely touch the file immediately. | Create a visible reconciliation record or task. |
|
|
| `human_confirmation` | The change may hide work, require a blocker reason, or move archived context. | Ask for confirmation or gather missing intent before writing. |
|
|
|
|
## Initial Transition Classification
|
|
|
|
| Target | Safe write-through | Deferred | Human confirmation |
|
|
|--------|--------------------|----------|--------------------|
|
|
| Workstream status | Open, file-backed transitions among `proposed`, `ready`, `active`, and `backlog`; `finished` only when known tasks are terminal. | Non-file-backed workstreams, unsupported statuses, unavailable file links. | Archived files, `blocked` without explicit blocker/dependency context, `finished` with open/unknown tasks, `archived`. |
|
|
| Task status | Linked task blocks in active workplan files for `todo`, `in_progress`, `done`, `cancelled`, and `blocked` with a blocking reason. | Non-file-backed workstreams or DB tasks without a linked task block. | Archived files and `blocked` task changes without a blocking reason. |
|
|
|
|
## T01 - Classify UI State Changes
|
|
|
|
```task
|
|
id: STATE-WP-0048-T01
|
|
status: done
|
|
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.
|
|
|
|
Result 2026-05-23: added the initial classification matrix and
|
|
`api.services.reconciliation` helpers for workstream/task status changes. Tests
|
|
pin the write-through, deferred, and human-confirmation decisions.
|
|
|
|
## T02 - Add Reconciliation API Contract
|
|
|
|
```task
|
|
id: STATE-WP-0048-T02
|
|
status: done
|
|
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.
|
|
|
|
Progress 2026-05-23: added a classify-only
|
|
`POST /reconciliation/state-change` API contract. It returns actor, intent,
|
|
current/target status, file-backed flags, reconciliation class, reason,
|
|
follow-up action, and `write_through_result: not_attempted`. Dashboard wiring
|
|
and write-through execution remain for the next slice.
|
|
|
|
Result 2026-05-23: the API contract now also supports `apply: true` for safe
|
|
write-through changes. Unsafe classifications return `not_applicable` instead
|
|
of mutating files or DB state.
|
|
|
|
## T03 - Implement File Write-Through For Safe Changes
|
|
|
|
```task
|
|
id: STATE-WP-0048-T03
|
|
status: done
|
|
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.
|
|
|
|
Result 2026-05-23: added workplan-file helpers and write-through support for
|
|
file-backed workstream status and linked task status changes. The endpoint
|
|
patches the workplan file first, then updates the DB status, and returns the
|
|
relative workplan path plus `write_through_result: applied`.
|
|
|
|
## T04 - Queue Reconciliation For Deferred Changes
|
|
|
|
```task
|
|
id: STATE-WP-0048-T04
|
|
status: done
|
|
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.
|
|
|
|
Result 2026-05-23: attempted `apply: true` changes that classify as deferred
|
|
or human-confirmation now create an unread message for `state-hub` with actor,
|
|
intent, target id, current/target status, reason, follow-up, and workplan path
|
|
when known.
|
|
|
|
## T05 - Surface Reconciliation State In Dashboard
|
|
|
|
```task
|
|
id: STATE-WP-0048-T05
|
|
status: done
|
|
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.
|
|
|
|
Result 2026-05-23: dashboard status controls now submit state changes through
|
|
`POST /reconciliation/state-change` with `apply: true` instead of direct DB
|
|
patches. The control reports `synced` when the repo file and cached DB state
|
|
were updated, `queued` for deferred reconciliation, and `needs review` for
|
|
human-confirmation cases.
|
|
|
|
## T06 - Add Conflict Handling
|
|
|
|
```task
|
|
id: STATE-WP-0048-T06
|
|
status: done
|
|
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.
|
|
|
|
Result 2026-05-23: apply-mode reconciliation now blocks stale UI requests,
|
|
repo file/cache drift, missing host-path access, and failed file patch attempts
|
|
before DB mutation. These cases create reconciliation messages with actionable
|
|
reasons and return `conflict: true` for dashboard display.
|
|
|
|
## T07 - Tests And Consistency Integration
|
|
|
|
```task
|
|
id: STATE-WP-0048-T07
|
|
status: done
|
|
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.
|
|
|
|
Progress 2026-05-23: added API tests for classify-only responses, safe
|
|
write-through, missing-file deferral, and human-confirmation message creation.
|
|
|
|
Progress 2026-05-23: routed dashboard status controls through the
|
|
reconciliation API so UI-originated changes exercise the same write-through and
|
|
deferred-record path as API clients.
|
|
|
|
Result 2026-05-23: added API coverage for stale expected status, workplan
|
|
file/cache drift, and unavailable host paths. Added a dependency-free dashboard
|
|
component test that verifies status controls post the reconciliation contract,
|
|
include `expected_current_status`, keep local state on conflicts, and surface
|
|
`out of sync` to the user.
|
|
|
|
## 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.
|