state-hub/workplans/STATE-WP-0048-ui-state-change-reconciliation.md

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	finished	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.

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

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

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

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

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

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

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

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.