Repository navigation
Description
Is there an existing issue or feature request for this?
- I have searched the existing issues and feature requests.
What area does this improvement affect?
User Interface
What actions does this improvement affect?
Issue, Pull Request, Commit
Description of the idea or improvement
Let a household member use the existing permitted task transitions from Tasks.
Start assigned work, explain why eligible work is blocked, and explicitly make
blocked work available or assigned again according to its current assignees.
Show the saved blocking reason beside the task state. Use the current server
action hints, current command authority, exact reviewed revision and original
request recovery throughout.
Current limitations or challenges
The backend already validates and persists task.transition, exposes current
transition:<target> actions and returns the occurrence's state_reason.
The Tasks interface can create, claim, assign, complete, review and reopen work,
but members cannot start, block or unblock it there. The frontend drops the
blocking reason and its task journal has no transition command. The workspace
original-request allowlist also needs to admit this existing action through
the same recorded authorization boundary.
Expected impact
A member can make work in progress visible, retain a useful explanation when
it cannot proceed and deliberately resume it after resolving the obstacle.
Concurrent changes preserve the proposed reason for explicit review. An
interrupted response can be recovered once with its frozen original request.
Keyboard and narrow touch journeys remain understandable in English and Spanish.
Alternatives considered
The current task command, state policy, receipt, history and journal provide
the owning execution semantics and recovery path for this interface increment.
Version of copilot
Installed repository workflow.
Additional context or comments
This is the next bounded M2 task-interface increment after #141 / PR #142.
The reviewed base is develop at 50ddb2d60de4b4a53970ecdde70eb746ade38d30.
Retain the published owning contracts in specs/household-tasks.md,
specs/task-execution-foundation.md and specs/task-assignment-interface.md.
Publish this interface delta as the companion specs/task-progress-interface.md
under the existing household-tasks capability, retaining every earlier case ID.
The nine new case IDs below belong only to this companion. Let the Action
publish and verify the exact managed branch before implementation.
Use published @vypdev/ha-ui@0.1.0-next.2 presentation components and the existing
domain/application/adapter boundaries. Qualify complete supported coverage,
Ingress and standalone, English keyboard and Spanish narrow touch, both CPU
images and an immutable installed Edge candidate. Preserve schema 34 when
the implementation confirms that existing persisted formats cover the change.
All workflow actions retain full released version tags and the configured
self-hosted placement. Original-operation reads retain transaction-time grants.
Start, block and unblock tasks from Tasks
- Status: Draft
- Catalog capability ID: household-tasks
- Owners: Domus maintainers
- Scope: Existing task progress transitions and their user-facing recovery
- Open decisions blocking readiness: none
1. Executive summary
Connect the existing protected occurrence transition command to Tasks. A member
starts assigned work, blocks eligible work with a meaningful reason and
explicitly unblocks it to its permitted assigned or available state. Display
the authoritative reason while retaining the existing assignment, completion,
verification, point and material contracts.
2. Problem, current behavior, and evidence
At the selected base, TaskOccurrence.transition, TransitionTask,
TaskCommands.transition, the shared HTTP transition route and server-derived
action hints already exist. The task response includes state_reason.
The browser lacks these commands and controls, drops that reason and cannot
recover task.transition through the workspace original-request route.
The preceding assignment increment provides captured-revision conflict review
and a bounded durable task journal for this interface to reuse.
3. Actors, surfaces, and terminology
The current verified household member acts through the selected task's current
allowed actions. The application rechecks that member's existing grants and
household scope at commit and during original receipt access. A blocked reason
explains the current obstacle. Starting work records progress. Actual
performance continues through the existing completion command and cycle.
4. Goals, non-goals, and fixed invariants
| Requirement | Behavior |
|---|---|
| task-progress-interface-R01 | Offer Start for the permitted assigned-to-in-progress transition. Offer Block for permitted available, assigned and in-progress work. Offer Unblock for blocked work, targeting assigned when assignees remain and available when empty, subject to the server's current allowed action. Display the saved reason. |
| task-progress-interface-R02 | Enforce the existing state machine, human authority, household scope, exact selected revision and unchanged assignee identities. Current authority governs direct writes and original receipt disclosure. |
| task-progress-interface-R03 | Require a meaningful valid blocking reason within the existing 1,000-code-point multiline bound. Preserve a correctable reason and show distinct invalid, denied, unavailable and conflict outcomes. |
| task-progress-interface-R04 | Retain the captured task, target, reason and revision across a competing update. Show the current task and require explicit review before a fresh deliberate save. A newly unavailable target has an actionable cancellation or refresh path. |
| task-progress-interface-R05 | Freeze the original command body, key and scope before sending. A lost response recovers the same operation after reload or restart and an exact replay adds no transition, history, points or stock effect. |
| task-progress-interface-R06 | Provide English and Spanish keyboard and touch flows with clear labels, focus, cancellation, busy states, light/dark legibility and protected recovery. |
The retained owners continue to define state transitions, assignment authority,
completion cycles, verification, Points, Inventory and recurring work.
5. Current versus proposed product journey
Open an assigned task and start it. When an obstacle appears, choose Block,
enter the reason and save deliberately. Other permitted readers can see why
it is blocked. After resolving the obstacle, choose Unblock and review the
resulting assignment state. Complete performed work through the existing flow.
6. Functional behavior and state model
Reuse the existing state policy and POST /api/v1/tasks/occurrences/{id}/transition.
Capture occurrence identity, expected revision, supported target and exact reason
when preparing a command. Server-derived actions control discoverability and
current authority controls admission. Preserve assignees across these transitions.
For blocked work, the existing policy chooses a valid assigned or available
target from the current assignee set. Its existing authorization differences
remain observable through allowed actions and protected command rejection.
Every accepted change commits occurrence revision, state, reason, receipt,
audit and outbox atomically. Original reads use recorded authorization.
Replay returns its historical outcome with current facts displayed separately.
Starting and unblocking use the existing empty-reason command representation.
Blocking preserves the member's exact valid text, including multiline content.
7. User-facing configuration
Use existing household grants, selected task actions, locale, theme, bounded
journal and task text limits. The interface introduces the progress controls
under the same task scope and session lease as the existing task workspace.
8. Clean Architecture design
The domain validates a typed progress command and bounded reason. Application
controllers coordinate current reads, captured revision, original recovery
and semantic outcomes. HTTP adapters encode the existing route and bind the
returned operation to occurrence, resulting state and reason. Presentation
composes the form, progress controls and feedback from published ha-ui and
existing Domus task layout. SQLite and shared task services retain ownership
of transactional state and persisted history.
9. UI/UX and content contract
Keep the task's state and current blocking reason visible before its progress
controls. Label the primary state-appropriate action clearly. Give the reason
field a visible label, multiline instructions, character bound and associated
error. Cancel returns focus to its trigger. Invalid save focuses the form or
reason. Conflicts retain the draft, show current state and offer explicit
review before another save. Preserve corrected input during recoverable errors.
Use clear English and Spanish text and native narrow touch targets.
10. Failure, recovery, and cleanup
Invalid text leaves the draft available for correction. An unavailable read
preserves the draft for refresh. An unavailable command response remains an
uncertain original request until protected recovery establishes its outcome.
A competing revision never silently retargets or retries a prepared transition.
Revoked authority retires protected facts and mutation controls using the existing
session behavior. Cancel and completion retire the owned editor state. QA uses
identifiable synthetic data and scoped cleanup.
11. Security, permissions, and privacy
Reuse verified HA human proof, same-origin transport, CSRF, installation/channel
binding and current task authorization. Active membership and task scope are
rechecked at the transaction boundary. Original receipt access rechecks its
recorded action and target. A selected identifier or stale action hint grants
no authority. Render the reason as text under current task read access.
12. Observability and operational UX
Keep the existing attributable transition operation, revision and history.
Show a confirmed result, retained conflict or unresolved original request with
the relevant next action. The current task view remains distinct from an
older recovered operation. Recovery retains its original operation identity.
13. Compatibility, migration, rollout, and rollback
Reuse the existing task transition request, receipt and state-reason storage.
Preserve historical creation and assignment journal records beside progress
records. Confirm schema compatibility from implementation evidence. Verify
restart, activated compatible restore and preserved original receipts.
Qualify an immutable Edge candidate with a current compatible rollback.
14. Testing strategy and numeric budget
Minimum nine distinct companion cases.
{{SDD_CASE_BUDGET}}
| Case ID | Area | Requirements | Scenario |
|---|---|---|---|
| task-progress-interface-C01 | Progress journey | task-progress-interface-R01, task-progress-interface-R02 | Start assigned work, block it with a saved reason and unblock it to assigned. Retain the same task and assignees while revisions advance once per accepted change. Show the current saved reason. |
| task-progress-interface-C02 | Available work | task-progress-interface-R01, task-progress-interface-R02 | Block and unblock an unassigned task through its current permitted actions and return to available with an empty assignee set. Exercise an actor whose permissions expose only the valid existing targets. |
| task-progress-interface-C03 | Authority and scope | task-progress-interface-R02 | Respect current task actions, role/member grants and revocation. Reject a foreign task and a newly denied direct write. Revoke the original transition authority and deny receipt disclosure in both compositions. |
| task-progress-interface-C04 | Reason validation | task-progress-interface-R03 | Preserve exact multiline text and accept the existing bound. Reject blank required reasons, forbidden characters and over-bound Unicode text before a browser write and at the normal API boundary. Keep the correctable draft. |
| task-progress-interface-C05 | State and concurrency | task-progress-interface-R02, task-progress-interface-R04 | Compete at one selected revision in two sessions. Retain the losing reason and target, display current facts and require explicit review before another save. A target that becomes unavailable requires a deliberate new decision. |
| task-progress-interface-C06 | Original recovery | task-progress-interface-R05 | Commit a transition then lose its response. Reload, recover the frozen original operation and verify exact replay adds no history or effects. Reject key reuse with a different target or reason and retain earlier journal records. |
| task-progress-interface-C07 | Failure and rollback | task-progress-interface-R02, task-progress-interface-R03, task-progress-interface-R05 | Inject a late transactional failure and observe unchanged task and absent receipt. Exercise unavailable reads, unknown responses and denied current authority with truthful feedback and retained recoverable input. |
| task-progress-interface-C08 | Browser acceptance | task-progress-interface-R01, task-progress-interface-R04, task-progress-interface-R06 | Use English keyboard and Spanish 390 px touch through Ingress and standalone. Exercise start, reason validation, cancellation, block, conflict review and unblock, with focus and light/dark legibility. |
| task-progress-interface-C09 | Persistence and integrated acceptance | task-progress-interface-R01, task-progress-interface-R02, task-progress-interface-R05, task-progress-interface-R06 | Restart and activate a compatible restore containing blocked work and its original receipt. Inspect retained reason and audit, then complete through the existing performer flow. Qualify both CPU images and the exact installed Edge candidate with scoped QA cleanup. |
15. Documentation and discoverability
{{SDD_FILE_NAVIGATION}}
Update the task user guide, public original-request contract, roadmap and
companion qualification evidence. Map every new case reciprocally in the
existing catalog while preserving prior owner contracts and case identities.
16. Acceptance scenarios
An authorized member starts assigned work, blocks it with an explanation,
reviews a competing update deliberately and unblocks it after resolving the
obstacle. A lost successful reply recovers its same recorded operation after
restart. Existing completion records actual performers under its own rules.
17. Requirements traceability
{{SDD_REQUIREMENT_CASES}}
18. Implementation sequence
Publish and verify the companion through the Action. Start with focused command,
decoder, journal, controller and presentation regressions. Connect the retained
transition and original-recovery entry points. Qualify both browser compositions,
full supported coverage, current review, both CPU images and installed Edge.
19. Definition of Done
Verify all nine cases with explicit source, package, image and installed evidence.
Retain 100% supported global and per-file coverage. Merge the reviewed commit
with its applicable checks green, then verify the actual destination commit,
CI, Branch Sync, issue closure and owned temporary-resource cleanup.
20. References and decisions
The existing household task and execution contracts own the state machine,
current authority and history. PR #142 provides the preceding assignment
interface and recovery integration. This companion makes the already-defined
progress transitions usable through Tasks under those retained semantics.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
vypbot commentedon Nov 19, 2026
SDD work status
Current status: Waiting for specification answers. No SDD draft or branch exists yet.
Owning SDD:
specs/task-progress-interface.mdClarification round: 1
Suggested answer: Merge or verify the reviewed base before SDD drafting.
Suggested answer: Provide the package documentation or selected component inventory for @vypdev/ha-ui@0.1.0-next.2.
Suggested answer: Identify the existing workflow or acceptance evidence that establishes these rollout gates.
Suggested answer: Provide the nine identifiers and their intended acceptance behaviors.
Suggested answer: Specify eligibility and whether unblocking restores prior assignees, leaves work unassigned, or follows another rule.
Suggested answer: Define input limits and whether a saved reason remains visible after the task leaves the blocked state.
Suggested answer: Define when the interface refreshes, preserves proposed input for explicit review, and requires resubmission.
Suggested answer: Specify how the existing journal and authorization boundary should present and recover an interrupted transition.
Reply with
SDD Q1: your answer(one line per question). The Action will continue after the required people answer every question.[-]Start, block and unblock tasks from Tasks[/-][+]✨ - Start, block and unblock tasks from Tasks[/+]efraespada commentedon Nov 19, 2026
SDD Q1: The verified parent is develop at 50ddb2d. PR #142 is merged and its tree 480913a93a3fd4818109c2134d5a4a9d49601751 equals the reviewed head. CI 44483616692 and Branch Sync 44483616784 both succeeded on that exact parent. Publish and verify the new Action-owned issue branch from this parent as part of native SDD publication, then contributor implementation follows on that exact published ref. The current gate reports that branch publication is still pending.
SDD Q2: Use exactly @vypdev/ha-ui 0.1.0-next.2, pinned by frontend/package.json and pnpm-lock.yaml at the verified parent. The installed published package confirms version 0.1.0-next.2 and exports /button with registerButton, /button-contracts with buttonState, /feedback with registerFeedback, /feedback-contracts with feedbackState, /card with registerCard, /card-contracts with cardState, /field with registerField, /field-contracts with textFieldState, /select, /checkbox and /tabs. Use the released button, feedback and card contracts for the added progress controls and retain the existing task shell. The current published field is a controlled single-line input. The existing Domus multiline reason control and its bounded text semantics provide the reason editor. Existing adoption examples include frontend/src/presentation/domus-automation-execution.ts and frontend/src/presentation/domus-task-overview.ts. Package documentation and catalog are published at https://vypdev.github.io/ha-ui/ and the repository is https://github.com/vypdev/ha-ui .
SDD Q3: The verified parent .github/workflows/ci_check.yml owns backend and frontend full global/per-file coverage, compiled Ingress and standalone browser journeys, both amd64/aarch64 container jobs and actual-image journeys. tests/containers and frontend/tests/e2e/tasks.spec.ts provide executable acceptance. docs/evidence/task-assignment-qualification.md, addon-edge/artifact.json and docs/installation-home-assistant.md and docs/operations.md provide the preceding immutable Edge qualification and operation pattern. Destination CI https://github.com/vypdev/domus/actions/runs/44483616692 succeeded with 115 source journeys, 45 catalog journeys, 60 actual-image journeys per CPU, all 231 backend modules at 100% statements/branches and all 106 frontend authored files at 100% supported metrics. The final installed acceptance and cleanup evidence is #142 (comment) . Follow those existing gates for this increment and preserve the configured self-hosted placement and full released action versions.
SDD Q4: Preserve exactly task-progress-interface-C01 through task-progress-interface-C09 from the supplied seed table. C01 covers assigned start/block/unblock with one revision per accepted transition and preserved assignees. C02 covers unassigned block/unblock to available under current allowed targets. C03 covers action/authority revocation, household scope and original receipt access in both compositions. C04 covers exact multiline reason preservation, required content, Unicode/control validation and the 1000-code-point bound. C05 covers competing revisions, retained target/reason and explicit current-state review. C06 covers a committed lost response, frozen original recovery, exact inert replay, changed-key-payload conflict and earlier journal compatibility. C07 covers late transactional rollback, unavailable reads, unknown responses and current denial. C08 covers English keyboard and Spanish 390px touch, both compositions, focus/cancel/conflict and light/dark legibility. C09 covers restart, activated compatible restore, retained reason/audit/original receipt, existing completion, both CPU images and installed Edge with scoped cleanup. Retain every earlier owner's case identity and use this companion for these nine new cases.
SDD Q5: Follow the existing TaskOccurrence.transition, next_occurrence_state and TaskCommandAuthorization. Start is assigned to in_progress. Block is available, assigned or in_progress to blocked. Unblock is blocked to assigned when the current assignee set is nonempty, or blocked to available when it is empty. Each control requires the matching current transition: hint. Preserve the assignee identities. Preserve current authorization, including the existing tasks.complete authority for in_progress, blocked and assigned targets and tasks.manage for available. The existing state policy and application command remain authoritative at commit. Existing claim, assignment, completion, verification and reopening retain their owning semantics.
SDD Q6: Blocking requires meaningful valid multiline text within the existing maximum of 1000 Unicode code points, using validate_task_text with multiline=True and required=True. Preserve the exact submitted valid text. Reject blank required reasons, invalid Unicode and disallowed controls under the existing validator. Show the saved current state_reason to permitted task readers while the task is blocked. Start and unblock use the existing empty reason string, clearing the current reason through the accepted transition. The historical blocking reason remains in its original receipt and history. Preserve a correctable draft across validation and recoverable failure. Render the reason as text and associate labels, instructions and errors accessibly.
SDD Q7: Capture the selected occurrence identity, target, reason and revision. Refresh current session, scope, task detail and action hints before admission through the existing controller path. A changed revision or competing post-admission conflict retains the proposed target and reason and shows current facts. Require explicit review followed by a separate deliberate save at the reviewed revision while that target remains permitted. An unavailable target offers refresh or cancel and a deliberate new choice. Current revocation follows the existing protected-view retirement behavior. Current command authority and exact revision are rechecked transactionally for direct writes. A stale hint grants no authority.
SDD Q8: Prepare the bounded task journal with the original key, canonical body, selected revision and verified installation/channel/actor/household scope before the explicit send. An interrupted or unbound response remains uncertain. Check the existing original-request endpoint with the same frozen key/action/body binding after reload or restart, extending its typed workspace allowlist to task.transition through recorded_authorization. Repeated protected original reads return the same recorded operation. Exact replay creates one transition/history/receipt only, and a changed payload under that key conflicts. Show current task facts separately from the recovered historical result, including after activated restore. Preserve the existing prepared/uncertain request gate and journal compatibility with prior creation and assignment entries. Only an explicit deliberate save initiates a new transition.
All answers above derive from the issue's supplied nine-case seed and retained contracts or from the verified selected parent. They refine the existing progress interface scope for publication.
32 remaining items
vypbot commentedon Nov 19, 2026
Issue closed: synchronization recommendation retired
No branch synchronization is required for this closed issue.
The previous recommendation is historical. Issue closure does not certify that the branches are synchronized.