From 0b1e65d877f5312e3499a20e5bccde01559237ac Mon Sep 17 00:00:00 2001
From: "copilot-action[bot]"
<41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 19 Nov 2026 09:59:22 +0100
Subject: [PATCH 1/9] docs(sdd): specify issue contract in
specs/task-progress-interface.md
---
specs/CATALOG.md | 4 +-
specs/catalog.json | 3 +-
specs/task-progress-interface.md | 281 +++++++++++++++++++++++++++++++
3 files changed, 285 insertions(+), 3 deletions(-)
create mode 100644 specs/task-progress-interface.md
diff --git a/specs/CATALOG.md b/specs/CATALOG.md
index 7360916..8e51b56 100644
--- a/specs/CATALOG.md
+++ b/specs/CATALOG.md
@@ -12,7 +12,7 @@ debt or convert unknown historic intent into a design decision.
|---|---|---|---|---|
| `platform-foundation` | Proposed | One local modular application serves the complete household product in both a Supervisor-managed App and standalone Docker from the first release. Home Assistant owns user authentication; Domus owns its business records. | [Local application platform and persistence](./platform-foundation.md) + 2 companion | 189 paths · 2026-11-01 |
| `household-identity` | Proposed | Each participating person uses their own Home Assistant account. Domus associates that verified user with one household member and applies explicit backend permissions independently of an optional person entity. | [Household members, Home Assistant identity and permissions](./household-identity.md) + 4 companion | 222 paths · 2026-11-02 |
-| `household-tasks` | Proposed | Members create and perform household responsibilities with explicit assignments, actual performers and history. A recurring definition survives completion of each individual occurrence. | [Task definitions, occurrences and household execution](./household-tasks.md) + 3 companion | 62 paths · 2026-11-19 |
+| `household-tasks` | Proposed | Members create and perform household responsibilities with explicit assignments, actual performers and history. A recurring definition survives completion of each individual occurrence. | [Task definitions, occurrences and household execution](./household-tasks.md) + 4 companion | 62 paths · 2026-11-19 |
| `recurrence-calendar` | Proposed | A bounded scheduler turns task definitions into stable occurrences and a family calendar distinguishes planned start, deadline and actual completion. Original recurrence outcomes bind receipt status, action, result and source-cycle identity before replay and snapshot acceptance. | [Recurrence engine and family calendar](./recurrence-calendar.md) + 3 companion | 37 paths · 2026-11-09 |
| `points-rewards` | Proposed | Task completion produces auditable point entries. Household-configurable collaboration policies determine each share and the actual award total; corrections preserve history and optional rewards never control basic participation. | [Auditable points, participation and optional rewards](./points-rewards.md) | 54 paths · 2026-11-11 |
| `shopping-management` | Proposed | Shopping combines manual intent, replenishment and task materials without losing provenance. Buying an item and physically receiving it are separate recorded facts. | [Shared shopping demand, purchases and receipt](./shopping-management.md) | 47 paths · 2026-11-17 |
@@ -50,7 +50,7 @@ debt or convert unknown historic intent into a design decision.
- Owner: Domus maintainers (review assignment pending)
- Last verified: 2026-11-19
-- Specifications: [`specs/household-tasks.md`](./household-tasks.md) · [`specs/task-execution-foundation.md`](./task-execution-foundation.md) · [`specs/household-task-categories.md`](./household-task-categories.md) · [`specs/task-assignment-interface.md`](./task-assignment-interface.md)
+- Specifications: [`specs/household-tasks.md`](./household-tasks.md) · [`specs/task-execution-foundation.md`](./task-execution-foundation.md) · [`specs/household-task-categories.md`](./household-task-categories.md) · [`specs/task-assignment-interface.md`](./task-assignment-interface.md) · [`specs/task-progress-interface.md`](./task-progress-interface.md)
- Workflows: [`.github/workflows/ci_check.yml`](../.github/workflows/ci_check.yml)
- Entrypoints: [`backend/src/domus/entrypoints/task_http.py`](../backend/src/domus/entrypoints/task_http.py) · [`backend/src/domus/entrypoints/schedule_creation_http.py`](../backend/src/domus/entrypoints/schedule_creation_http.py)
- Core code: [`backend/src/domus/domain/task_values.py`](../backend/src/domus/domain/task_values.py) · [`backend/src/domus/domain/task_policy.py`](../backend/src/domus/domain/task_policy.py) · [`backend/src/domus/domain/tasks.py`](../backend/src/domus/domain/tasks.py) · [`backend/src/domus/application/task_ports.py`](../backend/src/domus/application/task_ports.py) · [`backend/src/domus/infrastructure/sqlite_task_records.py`](../backend/src/domus/infrastructure/sqlite_task_records.py) · [`backend/src/domus/infrastructure/sqlite_task_schema.py`](../backend/src/domus/infrastructure/sqlite_task_schema.py) · [`backend/src/domus/infrastructure/sqlite_tasks.py`](../backend/src/domus/infrastructure/sqlite_tasks.py) · [`backend/src/domus/infrastructure/sqlite_task_integrity.py`](../backend/src/domus/infrastructure/sqlite_task_integrity.py) · [`backend/src/domus/application/task_authorization.py`](../backend/src/domus/application/task_authorization.py) · [`backend/src/domus/application/task_commands.py`](../backend/src/domus/application/task_commands.py) · [`backend/src/domus/application/task_creation.py`](../backend/src/domus/application/task_creation.py) · [`backend/src/domus/application/task_requests.py`](../backend/src/domus/application/task_requests.py) · [`backend/src/domus/application/task_queries.py`](../backend/src/domus/application/task_queries.py) · [`frontend/src/application/task-overview.ts`](../frontend/src/application/task-overview.ts) · [`frontend/src/adapters/task-http.ts`](../frontend/src/adapters/task-http.ts) · [`frontend/src/domain/tasks.ts`](../frontend/src/domain/tasks.ts) · [`frontend/src/application/task-controller.ts`](../frontend/src/application/task-controller.ts) · [`frontend/src/presentation/domus-tasks.ts`](../frontend/src/presentation/domus-tasks.ts) · [`frontend/src/presentation/domus-task-overview.ts`](../frontend/src/presentation/domus-task-overview.ts) · [`frontend/src/adapters/task-values.ts`](../frontend/src/adapters/task-values.ts) · [`frontend/src/adapters/task-journal.ts`](../frontend/src/adapters/task-journal.ts)
diff --git a/specs/catalog.json b/specs/catalog.json
index d74615d..0287c3f 100644
--- a/specs/catalog.json
+++ b/specs/catalog.json
@@ -482,7 +482,8 @@
"specs/household-tasks.md",
"specs/task-execution-foundation.md",
"specs/household-task-categories.md",
- "specs/task-assignment-interface.md"
+ "specs/task-assignment-interface.md",
+ "specs/task-progress-interface.md"
],
"workflows": [
".github/workflows/ci_check.yml"
diff --git a/specs/task-progress-interface.md b/specs/task-progress-interface.md
new file mode 100644
index 0000000..e2cfa53
--- /dev/null
+++ b/specs/task-progress-interface.md
@@ -0,0 +1,281 @@
+# Start, block and unblock tasks from Tasks
+
+- Status: Draft
+- Catalog capability: household-tasks
+
+## 1. Executive summary
+
+Add Start, Block, and Unblock actions to the existing Tasks workspace so members can make eligible work visible as in progress, record why work is blocked, and deliberately resume blocked work. Show the saved blocking reason beside a blocked task. Preserve the selected task’s assignees and use current server-provided transition hints, current command authority, and the exact reviewed revision for every change. The retained contracts and cases in `specs/household-tasks.md`, `specs/task-execution-foundation.md`, `specs/household-task-categories.md`, and `specs/task-assignment-interface.md` remain authoritative; this companion specifies the progress interface delta.
+
+```text
+Open task -> review current actions -> choose Start, Block, or Unblock -> review any conflict -> deliberately save -> see current task state and, when blocked, its saved reason
+```
+
+## 2. Problem, current behavior, and evidence
+
+### 2.1 Problem
+
+Members can manage tasks in the existing Tasks workspace, but cannot use it to start assigned work, explain a blocker, or resume blocked work. The interface also needs to preserve the reason and proposed change through validation errors, concurrent updates, and interrupted responses so members can tell what was saved and what still needs action.
+
+### 2.2 Current behavior
+
+The selected source includes the task workspace and presentation, controller, HTTP adapter, and journal boundaries documented by the existing task contracts. The issue describes task transitions and current action hints as existing backend capabilities, while this interface delta is prospective. The selected source evidence cited here does not independently establish every backend transition behavior; the retained execution contract remains the authority for lifecycle and command semantics.
+
+The selected tree contains `frontend/src/presentation/domus-task-overview.ts` and `frontend/src/presentation/domus-automation-execution.ts` as presentation references. The issue identifies `@vypdev/ha-ui` version `0.1.0-next.2` as the intended released component package, pinned through `frontend/package.json` and `pnpm-lock.yaml`; its use for this delta is a proposed implementation constraint, not evidence of completed integration.
+
+### 2.3 Evidence
+
+The retained task lifecycle, authorization, revision, receipt, and history contracts are in `specs/household-tasks.md` and `specs/task-execution-foundation.md`; the existing Tasks assignment journey is in `specs/task-assignment-interface.md`. The catalog registers task presentation evidence including `frontend/src/presentation/domus-task-overview.ts`. `specs/README.md` defines the specification and catalog publication goals. No implementation, acceptance run, or publication outcome for this proposed delta is asserted here.
+
+## 3. Actors, surfaces, and terminology
+
+Household members use the existing Tasks workspace to act on a selected task occurrence. The selected task’s current detail and action hints determine which progress actions are offered. The existing task command remains responsible for enforcing lifecycle policy, household scope, revision, and authority; the interface is not an authorization boundary.
+
+“Start” moves assigned work to In progress. “Block” moves eligible Available, Assigned, or In progress work to Blocked and requires a reason. “Unblock” moves blocked work to Assigned when its current assignee set is nonempty, or to Available when it is empty. “Current hint” means the action advertised for the selected task after refreshing its current details; a stale hint alone never authorizes a change. “Blocking reason” is the exact submitted text saved as the task’s current `state_reason` while blocked. “Selected occurrence identity” and “revision” identify the task and version the member reviewed before acting.
+
+## 4. Goals, non-goals, and fixed invariants
+
+### 4.1 Goals
+
+Let a member start an assigned task only when the current `transition:in_progress` hint is present. Let a member block an Available, Assigned, or In progress task only when the current `transition:blocked` hint is present. Let a member unblock a blocked task to Assigned when current assignees exist, or to Available when none exist, and require the matching current target hint. Preserve assignee identities. Enforce current `tasks.complete` authority for In progress, Blocked, and Assigned targets, and `tasks.manage` authority for Available.
+
+For blocking, require meaningful valid multiline text within the existing 1000 Unicode code point limit, validated with `validate_task_text(multiline=True, required=True)`. Preserve the exact valid submission and a correctable draft across validation errors and recoverable failures. Reject blank reasons, invalid Unicode, disallowed controls, and over-limit text. Show the saved reason as text to permitted readers while the task is blocked, with accessible labels, instructions, and errors. Start and Unblock use the existing empty reason string; the historical blocking reason remains in its receipt and history.
+
+Before admitting an action, capture the selected occurrence identity, target, reason, and revision, then refresh current session, scope, task detail, and action hints through the existing controller path. A changed revision or competing post-admission conflict must retain the proposed target and reason and show current facts. Require explicit review and a separate deliberate save at the reviewed revision while the target remains permitted. If the target is unavailable, offer refresh or cancel and require a deliberate new choice. Follow existing protected-view retirement behavior when authority is revoked. Direct writes must transactionally recheck current command authority and exact revision.
+
+### 4.2 Non-goals
+
+This delta does not redefine task lifecycle, transition policy, authorization, receipts, history, or journal semantics, and does not replace the retained task owners. It does not introduce new task states, broaden available actions, or let the client’s visible controls grant authority.
+
+### 4.3 Fixed product/safety invariants
+
+Current server state and command checks govern every mutation; hints are not authority. A rejected or conflicted action must not silently change the task or discard the member’s proposed target or reason. Any interrupted request remains bound to its original key, action, body, and scope; recovery must use the existing recorded-authorization boundary, produce at most one transition/history/receipt, and reject a changed payload under the same key. Keep current task facts distinct from any recovered historical result, including after restore. Preserve the existing prepared/uncertain request gate and compatibility with prior creation and assignment journal entries.
+
+Publication completion requires that the specification satisfy the required format, that internal and cross-document consistency is checked, and that reciprocal catalog ownership, paths, and evidence agree with the generated view. These are publication constraints, not product goals or claims that checks have run.
+
+| Requirement | Behavior |
+| --- | --- |
+| SDD-I143-U4-R1 | The increment MUST follow the existing CI acceptance gates and preserve the configured self-hosted runner placement and full released action versions. |
+| SDD-I143-U6-R1 | Start transitions an assigned task to in_progress only when the current transition:in_progress hint is present. |
+| SDD-I143-U6-R2 | Block transitions an available, assigned, or in_progress task to blocked only when the current transition:blocked hint is present. |
+| SDD-I143-U6-R3 | Unblock transitions a blocked task to assigned when its current assignee set is nonempty, or to available when that set is empty; it requires the matching current transition: hint. |
+| SDD-I143-U6-R4 | Start, block, and unblock preserve assignee identities and use current authorization: tasks.complete for in_progress, blocked, and assigned targets, and tasks.manage for available. |
+| SDD-I143-U7-R1 | Blocking requires meaningful valid multiline text within the existing 1000 Unicode code point maximum, validated with validate_task_text(multiline=True, required=True); preserve the exact valid submission, reject blank required reasons, invalid Unicode, and disallowed controls, and preserve a correctable draft across validation and recoverable failures. |
+| SDD-I143-U8-R1 | A start, block, or unblock action captures the selected occurrence identity, target, reason, and revision; refreshes current session, scope, task detail, and action hints through the existing controller path before admission; and never treats a stale hint as authority. |
+| SDD-I143-U8-R2 | On a changed revision or competing post-admission conflict, retain the proposed target and reason and show current facts; require explicit review followed by a separate deliberate save at the reviewed revision while the target remains permitted. |
+| SDD-I143-U8-R3 | When a target is unavailable, offer refresh or cancel and require a deliberate new choice; when authority is revoked, follow existing protected-view retirement behavior. |
+| SDD-I143-U8-R4 | Recheck current command authority and exact revision transactionally for direct writes. |
+
+## 5. Current versus proposed product journey
+
+The retained task lifecycle, transition policy, assignment, authorization, revision, receipt, and history contracts remain in `specs/household-tasks.md` and `specs/task-execution-foundation.md`. This companion adds controls to the existing Tasks experience: members can start assigned work, block eligible work with a reason, and deliberately unblock it according to the task’s current assignee set.
+
+| Stage | Current Tasks experience | Proposed Tasks experience | User effect |
+|---|---|---|---|
+| Find and select | The task overview groups work and emits a selection intent for an occurrence. | Keep that entry point; show permitted progress actions with the selected task’s current state and action hints. | The member can see which actions are currently offered for this occurrence. |
+| Start or block | The interface does not offer these transitions from Tasks. | Start assigned work, or block available, assigned, or in-progress work. Blocking requires a meaningful multiline explanation. | Work status and the reason it cannot proceed are visible to permitted readers. |
+| Unblock | The interface does not offer this transition from Tasks. | Explicitly choose the currently permitted target: assigned when assignees remain, otherwise available. | The member understands whether responsibility remains with the existing assignees or work becomes available. |
+| Resolve changes and observe | The retained command contract governs revision conflicts and original-request receipts. | Refresh facts before admission; on conflict preserve the proposed action and reason for review, and recover uncertain requests using their frozen original request. | A stale action cannot silently apply, and a retry cannot create a second transition. |
+
+Flow: select occurrence -> refresh session, scope, detail, and hints -> choose an offered action -> review and deliberately save -> see the current result or review/recover. A changed revision or competing conflict requires reviewing current facts and a separate deliberate save. An unavailable target requires refresh or cancel and a new deliberate choice. Revoked authority follows the existing protected-view retirement behavior.
+
+## 6. Functional behavior and state model
+
+### Normal transitions
+
+- Start is available only for an assigned task with the current `transition:in_progress` hint. It moves the task to `in_progress` and preserves assignee identities.
+- Block is available only for an available, assigned, or in-progress task with the current `transition:blocked` hint. It moves the task to `blocked`, preserves assignee identities, and saves the exact validated reason as the current `state_reason`.
+- Unblock is available only for a blocked task and the matching current hint. With a nonempty current assignee set, `transition:assigned` returns it to `assigned`; with an empty set, `transition:available` returns it to `available`. Preserve assignee identities.
+- Start, block, and unblock use the retained transition command and state policy. Start and unblock submit the existing empty reason, clearing the current reason through the accepted transition. Historical reasons remain in their original receipt and history.
+- Current authorization is target-specific: `tasks.complete` is required for `in_progress`, `blocked`, and `assigned` targets; `tasks.manage` is required for `available`. A visible control or stale hint grants no authority.
+
+### Blocking reason and feedback
+
+Require meaningful multiline text validated with `validate_task_text(multiline=True, required=True)` and the existing 1000 Unicode code point maximum. Reject blank required reasons, invalid Unicode, disallowed controls, and over-limit input. Preserve valid submitted text exactly. Preserve the correctable draft after validation errors and recoverable failures. Render the saved current reason as text beside the blocked state for permitted readers, with associated accessible labels, instructions, and errors.
+
+Show clear loading, unavailable, denied, invalid, conflict, uncertain, and confirmed states. On conflict, show current task facts without discarding the proposed target or reason; require explicit review and then a separate deliberate save at the reviewed revision while the target remains permitted. If the target is no longer available, offer refresh or cancel and require a new action choice. Do not imply an unconfirmed transition succeeded.
+
+The task overview in `frontend/src/presentation/domus-task-overview.ts` already groups tasks and emits occurrence selection intents. The existing bilingual presentation in `frontend/src/presentation/domus-automation-execution.ts` demonstrates released button, card, and feedback components and localized status/action rendering; use the declared `@vypdev/ha-ui` package version in `frontend/package.json` and lockfile. Keep keyboard focus, readable labels, and narrow touch layouts usable in English and Spanish.
+
+## 7. User-facing configuration
+
+This interface increment adds no user-configurable settings. Keep the blocking reason’s existing fixed 1000 Unicode code point limit and validator behavior; it is a correctness and safety constraint, not a preference. Keep action eligibility, target selection, and authorization derived from current task facts and server-provided hints. Do not let users configure transition rules, permissions, revision checks, or request-recovery behavior.
+
+## 8. Clean Architecture design
+
+### Responsibilities and dependency direction
+
+| Boundary | Responsibility for this delta | Must not own |
+|---|---|---|
+| Domain | Retained `TaskOccurrence` transition policy and `next_occurrence_state` rules determine valid state changes and reason semantics. | UI visibility, provider or DOM concerns. |
+| Application | Reuse the existing task transition command, current authorization, exact revision check, receipt, history, and transaction boundary. | Duplicated presentation policy or provider DTOs. |
+| Adapters and infrastructure | Preserve existing persistence, composition, and original-request recovery boundaries; map outcomes to semantic results. | Client-selected authority or relaxed revision checks. |
+| Entrypoint/controller | Refresh current session, scope, task detail, and action hints before admitting an action; bind the request to the selected occurrence and frozen original request. | Treating a cached hint as authorization or rebuilding a changed request for replay. |
+| Presentation | Render current state, permitted actions, reason editor, review/conflict, uncertainty, and result; emit user intents. | Performing mutations or deciding authorization. |
+
+The existing architecture contract in `specs/task-execution-foundation.md` keeps pure task policy in Domain, orchestration and semantic ports in Application, provider/storage details outside those layers, and presentation limited to view models and rendering. Preserve those dependency directions in both supported compositions.
+
+### Request, concurrency, and trust boundaries
+
+Capture the selected occurrence identity, target, reason, and revision. Before admission, use the existing controller path to refresh session, scope, detail, and action hints. Direct writes must transactionally recheck current command authority and exact revision. A stale revision or competing post-admission conflict retains the proposal and displays current facts; only explicit review followed by a separate deliberate save may proceed at the reviewed revision while the target remains permitted.
+
+Prepare the task journal with its original key, canonical body, selected revision, and verified installation, channel, actor, and household scope before explicit send. For an interrupted or unbound response, keep the outcome uncertain and check the existing original-request endpoint with the same frozen key, action, and body binding. Extend its typed workspace allowlist for `task.transition` through `recorded_authorization`; repeated protected reads return the same recorded operation. Exact replay creates one transition, history entry, and receipt; a changed payload under that key conflicts. Show current task facts separately from a recovered historical result, including after activated restore. Preserve the prepared/uncertain request gate and journal compatibility with prior creation and assignment entries. Only an explicit deliberate save initiates a new transition.
+
+If authority is revoked, follow existing protected-view retirement behavior. Treat task input and returned facts as untrusted at presentation boundaries; render reasons as text and preserve household scoping. Keep schema 34 if implementation confirms existing persisted formats cover this change; migration needs remain subject to implementation evidence.
+
+### Verification constraints
+
+Preserve the existing CI acceptance gates, configured self-hosted runner placement, and full released action versions. The selected source declares the frontend package manager and scripts in `frontend/package.json`; declaration alone does not establish execution or specification coverage. Follow the existing task browser journeys and applicable container jobs, with acceptance covering Ingress and standalone, both CPU images, English keyboard and Spanish narrow touch journeys, and an immutable installed Edge candidate. The precise invocation and prerequisites for SDD format, consistency, catalog, and product validation remain unverified here; require those observable outcomes without treating a different documentation check as SDK consistency verification. Do not infer passing acceptance from command declarations.
+
+## 9. UI/UX and content contract
+
+### UI/UX and content contract
+
+Add start, block, and unblock actions to the existing Tasks detail experience. Render only actions permitted by the current task detail and transition hints. Show the current task state and assignees, then the available action and any required reason. While blocked, show the saved current `state_reason` as readable text to permitted task readers. Start and unblock submit the existing empty reason value; a successful transition clears the current reason while its historical value remains in the existing receipt and history.
+
+Blocking uses a labeled multiline reason editor. Explain that a reason is required and limited to 1000 Unicode code points. Preserve a valid entered draft if validation or a recoverable request failure prevents saving. Associate instructions and validation errors with the editor, expose errors in text, and do not rely on color alone. The existing task interface owns the shell and interaction boundaries in `specs/task-assignment-interface.md`; the selected presentation examples in `frontend/src/presentation/domus-task-overview.ts` and `frontend/src/presentation/domus-automation-execution.ts` demonstrate the project's task overview and button, card, feedback, focus, and bilingual presentation patterns.
+
+Use one clear primary action at a time. Confirmation must identify the task, proposed state, reason when present, and revision being saved. Conflict review presents current facts and the retained proposal; the user reviews those facts and then makes a separate deliberate save. If the target is no longer available, offer refresh or cancel and require a new deliberate choice. Present pending, unavailable, denied, rejected, conflict, uncertain, recovered historical result, and completed states in plain language, separating current task facts from historical operation results. Keep diagnostics secondary and omit protected details after access is revoked.
+
+Use the existing English and Spanish locale behavior and provide keyboard operation, visible focus, programmatic labels, and readable narrow-screen layouts. Controls and feedback should follow the released `@vypdev/ha-ui` contracts already used by the selected presentation components; retain the existing task shell and multiline reason semantics.
+
+## 10. Failure, recovery, and cleanup
+
+### Failure, recovery, and cleanup
+
+A validation failure leaves the task unchanged and preserves the editable reason for correction. A rejected or unavailable request must state its impact, cause, next action, and retained draft. Do not report a transition as failed after a committed result has been recovered.
+
+Before admission, refresh the current session, household scope, task detail, and action hints through the existing controller path. A stale hint alone never admits a command. On revision change or a competing post-admission conflict, retain the proposed target and exact reason, display current task facts, and require explicit review followed by a separate save against the reviewed revision if the target remains permitted. If the target becomes unavailable, offer refresh or cancel; do not select a replacement automatically. If authority is revoked, use the existing protected-view retirement behavior.
+
+Prepare the task journal with the original request key, canonical body, selected revision, and verified installation, channel, actor, and household scope before sending. Treat interrupted or unbound responses as uncertain. On reload or restart, recover through the existing original-request endpoint with the same frozen key, action, body, and authorization binding; extend its typed workspace allowlist for the existing `task.transition` action through recorded authorization. Repeated protected original reads return the same recorded operation. Exact replay produces one transition, history entry, and receipt; a changed payload under that key conflicts. Show current task facts separately from a recovered historical result, including after activated restore. Only an explicit deliberate save starts a new transition. Preserve the prepared/uncertain request gate and compatibility with earlier creation and assignment journal entries.
+
+## 11. Security, permissions, and privacy
+
+### Security, permissions, and privacy
+
+Transition hints describe current permitted actions but do not grant authority. The server remains authoritative: it rechecks current command authority and exact revision transactionally for direct writes. Preserve assignee identities. Require `tasks.complete` for in-progress, blocked, and assigned targets, and `tasks.manage` for the available target. Unblock chooses assigned only when the current assignee set is nonempty; otherwise it chooses available and requires the corresponding current transition hint.
+
+Treat reason text and all client-supplied task, revision, target, and journal data as untrusted. Validate blocking text with the existing `validate_task_text(multiline=True, required=True)` semantics: require meaningful valid multiline text within 1000 Unicode code points and reject blank required reasons, invalid Unicode, and disallowed controls. Preserve valid submitted text exactly. Render saved and proposed reasons as text, not executable markup. A journal record or cached hint is recovery context, never authorization. Original-operation reads retain transaction-time grants and the recorded authorization boundary. On revocation, retire the protected view and do not disclose task or member details no longer authorized.
+
+## 12. Observability and operational UX
+
+### Observability and operational UX
+
+Show users the current task state, the action outcome, and whether review, refresh, correction, or recovery is required. Keep operation identity and revision available in the existing authorized receipt/history experience; distinguish the current task from a historical recovered result. Do not expose reason text or task details to unauthorized readers. Operational diagnostics should identify the operation and sanitized failure category without copying protected request content into logs or user-facing diagnostics.
+
+Acceptance evidence must exercise start, block, both unblock destinations, validation and draft retention, changed-revision and competing-conflict review, unavailable targets, authority retirement, exact replay, changed-payload conflict, and transactional rejection of stale revision or revoked authority. Validate English keyboard and Spanish narrow-touch journeys, plus supported ingress and standalone coverage, both CPU images, and an immutable installed Edge candidate. Follow the existing CI acceptance gates and preserve configured self-hosted runner placement and full released action versions. The selected tree includes `frontend/tests/e2e/tasks.spec.ts` and `.github/workflows/ci_check.yml`; their complete applicability to this new increment and the concrete installed Edge invocation remain to be verified during implementation.
+
+## 13. Compatibility, migration, rollout, and rollback
+
+### Compatibility, migration, rollout, and rollback
+
+Keep the existing task states, transition policy, receipts, history, authorization, and journal recovery semantics as the owning contract in `specs/household-tasks.md`, `specs/task-execution-foundation.md`, and `specs/task-assignment-interface.md`. This companion defines only the Tasks interface delta. Preserve schema 34 if implementation evidence confirms existing persisted formats cover the change; otherwise document the required migration and restart/restore behavior before readiness. Journal changes must continue to read prior creation and assignment entries and must not reinterpret an uncertain original request as permission to issue a new command.
+
+Qualify the increment on supported ingress and standalone surfaces, English keyboard and Spanish narrow touch journeys, both CPU images, and an immutable installed Edge candidate. Follow existing installation and operations guidance in `docs/installation-home-assistant.md` and `docs/operations.md`; keep rollback compatible with the existing paired application and database restore approach. The concrete migration need, rollout procedure, rollback evidence, and invocation/prerequisites for installed acceptance remain unverified in the selected source and must be resolved as implementation outcomes.
+
+## 14. Testing strategy and numeric budget
+
+The minimum distinct-case budget is ten, with one case for each defined scenario in the host-maintained inventory; repeated executions do not increase the count. Cover the three state transitions and their current authorization, blocking-reason validation and draft retention, refreshed admission and stale-hint rejection, revision and competing-write review, unavailable targets and revoked authority, transactional command checks, and the configured CI acceptance gates. Exercise normal UI paths and direct writes, including invalid input, recovery after recoverable failure, and current versus historical task facts. The retained contracts and cases in `specs/household-tasks.md`, `specs/task-execution-foundation.md`, `specs/household-task-categories.md`, and `specs/task-assignment-interface.md` remain authoritative references; this companion does not redefine them. The selected project declares `pnpm@10.34.0` and Node `>=24.20.0 <25` in root `package.json`; frontend scripts are declared in `frontend/package.json`. `specs/README.md` names `pnpm run validate:specifications` and `pnpm run generate:specifications`, but the validator definitions and execution prerequisites were not inspected here. Their availability and scope therefore remain unverified. Do not treat a declaration as execution or passing evidence. Validate this specification’s required format and internal and cross-document consistency as outcomes; retain actual applicable product and CI acceptance evidence with its observed scope.
+
+| Area | Minimum distinct cases | Behaviors/risks covered |
+|---|---:|---|
+| workflows/setup/schema | 1 | Observable scenarios in the case inventory. |
+| start | 1 | Observable scenarios in the case inventory. |
+| block | 1 | Observable scenarios in the case inventory. |
+| unblock | 2 | Observable scenarios in the case inventory. |
+| blocking reason | 1 | Observable scenarios in the case inventory. |
+| task-progress-interface | 4 | Observable scenarios in the case inventory. |
+| Total | 10 | Distinct inventory cases; repeated executions do not add cases. |
+
+| Case ID | Area | Requirements | Scenario |
+| --- | --- | --- | --- |
+| inventory4-C01 | workflows/setup/schema | SDD-I143-U4-R1 | The increment's CI workflow retains the configured self-hosted placement and full released action versions, and its acceptance run exercises the existing task browser journeys and applicable container jobs. |
+| inventory6-C01 | start | SDD-I143-U6-R1, SDD-I143-U6-R4 | Starting an assigned task with the current transition:in_progress hint changes its state to in_progress, preserves assignee identities, and requires tasks.complete authority. |
+| inventory6-C02 | block | SDD-I143-U6-R2, SDD-I143-U6-R4 | Blocking an available, assigned, or in_progress task with the current transition:blocked hint changes its state to blocked, preserves assignee identities, and requires tasks.complete authority. |
+| inventory6-C03 | unblock | SDD-I143-U6-R3, SDD-I143-U6-R4 | Unblocking a blocked task with a nonempty current assignee set and transition:assigned hint changes its state to assigned, preserves assignee identities, and requires tasks.complete authority. |
+| inventory6-C04 | unblock | SDD-I143-U6-R3, SDD-I143-U6-R4 | Unblocking a blocked task with an empty current assignee set and transition:available hint changes its state to available and requires tasks.manage authority. |
+| inventory7-C01 | blocking reason | SDD-I143-U7-R1 | Submit valid multiline text and verify the exact text is saved as current state_reason and shown to permitted readers while blocked; verify blank, invalid Unicode, disallowed controls, and over-limit text are rejected, with the draft preserved for correction after validation and recoverable failure. |
+| inventory8-C01 | task-progress-interface | SDD-I143-U8-R1 | For start, block, and unblock, inspect the admitted action and confirm it records the selected occurrence identity, target, reason, and revision after the existing controller path refreshes current session, scope, task detail, and action hints; a stale hint alone does not admit the action. |
+| inventory8-C02 | task-progress-interface | SDD-I143-U8-R2 | Change the revision and separately create a competing post-admission conflict; each outcome retains the proposed target and reason and displays current facts, and saving is unavailable until explicit review followed by a separate deliberate save at the reviewed revision while the target is permitted. |
+| inventory8-C03 | task-progress-interface | SDD-I143-U8-R3 | Make the selected target unavailable and confirm refresh and cancel are offered and no replacement is selected without deliberate new choice; revoke authority and confirm the existing protected-view retirement behavior occurs. |
+| inventory8-C04 | task-progress-interface | SDD-I143-U8-R4 | Attempt direct writes with stale revision and with revoked or otherwise non-current command authority; each is rejected transactionally, while a write with current authority and exact revision is accepted. |
+
+## 15. Documentation and discoverability
+
+Document the Tasks journey for starting assigned work, explaining a block, and deliberately resuming blocked work. Explain the visible state and saved blocking reason, current action availability, conflict review, correction of a reason draft, and what happens when authority or a target changes. Provide accessible, localized English keyboard and Spanish narrow-touch guidance. Keep state, transition, and authorization rules in the retained owners, including `specs/household-tasks.md` and `specs/task-execution-foundation.md`; this companion describes only the interface and recovery delta. The selected project pins `@vypdev/ha-ui` at `0.1.0-next.2` in `frontend/package.json` and `pnpm-lock.yaml`. Existing presentation examples are `frontend/src/presentation/domus-automation-execution.ts` and `frontend/src/presentation/domus-task-overview.ts`. Use the released button, feedback, and card contracts for progress controls and the existing multiline reason control and text validation semantics. Render the saved reason as text for permitted readers while blocked. The companion specification at `specs/task-progress-interface.md` is a proposed create, not an existing file.
+
+| Path | Change |
+| --- | --- |
+| frontend/package.json | reference |
+| pnpm-lock.yaml | reference |
+| frontend/src/presentation/domus-automation-execution.ts | reference |
+| frontend/src/presentation/domus-task-overview.ts | reference |
+| specs/task-progress-interface.md | create |
+
+[frontend/package.json](../frontend/package.json) · [pnpm-lock.yaml](../pnpm-lock.yaml) · [frontend/src/presentation/domus-automation-execution.ts](../frontend/src/presentation/domus-automation-execution.ts) · [frontend/src/presentation/domus-task-overview.ts](../frontend/src/presentation/domus-task-overview.ts) · [specs/task-progress-interface.md](task-progress-interface.md)
+
+## 16. Acceptance scenarios
+
+These are prospective acceptance outcomes, not claims of implementation or execution.
+
+1. In Tasks, start an assigned task only when the current `transition:in_progress` hint is present. The state becomes `in_progress`, assignee identities remain unchanged, and current `tasks.complete` authority is required. (inventory6-C01)
+2. For available, assigned, or in-progress work, block only when the current `transition:blocked` hint is present. Preserve assignee identities and require `tasks.complete` authority for the blocked target. (inventory6-C02)
+3. Require meaningful multiline block text within the existing 1000 Unicode code-point maximum, validated with `validate_task_text(multiline=True, required=True)`. Preserve the exact accepted text as `state_reason` and show it as text to permitted readers while blocked. Reject blank required text, invalid Unicode, disallowed controls, and over-limit input; retain a correctable draft after validation or recoverable failure. (inventory7-C01)
+4. Unblock a task with current assignees to `assigned` only with `transition:assigned`; unblock one without assignees to `available` only with `transition:available`. Preserve assignee identities and enforce `tasks.complete` for the assigned target and `tasks.manage` for the available target. Start and unblock use the existing empty reason behavior; the historical block reason remains in its receipt and history. (inventory6-C03, inventory6-C04)
+5. For each action, capture the selected occurrence identity, target, reason, and revision. Refresh session, scope, task detail, and action hints through the existing controller path before admission. A stale hint alone never admits an action. (inventory8-C01)
+6. On changed revision and, separately, a competing post-admission conflict, retain the proposed target and reason and show current facts. Require explicit review and then a separate deliberate save at the reviewed revision while the target remains permitted. (inventory8-C02)
+7. If the target is unavailable, offer refresh or cancel and require a deliberate new choice without silently selecting a replacement. If authority is revoked, follow the existing protected-view retirement behavior. (inventory8-C03)
+8. Reject direct writes transactionally when command authority is revoked or otherwise not current, or the revision is not exact; accept a write with current authority and exact revision. (inventory8-C04)
+9. The increment retains the existing CI workflow’s configured self-hosted placement and full released action versions; its acceptance run exercises the existing task browser journeys and applicable container jobs. (inventory4-C01)
+
+The selected project’s current suite, installed Edge qualification, and complete supported-coverage evidence remain prospective acceptance evidence for this increment; this draft does not claim they have been run for it.
+
+## 17. Requirements traceability
+
+The host-maintained traceability inventory maps each requirement only to cases that exercise it, reciprocally with the case definitions. Start state, current transition hint, assignee preservation, and `tasks.complete` authority map to inventory6-C01. Blocking state, hint, assignee preservation, and authority map to inventory6-C02. Unblock target selection from the current assignee set and target-specific hint and authority map to inventory6-C03 and inventory6-C04. Blocking-text validation, exact saved reason, permitted display, and correctable draft map to inventory7-C01. Refreshed action admission and rejection of stale hints map to inventory8-C01. Changed-revision and competing-write review map to inventory8-C02. Unavailable target handling and revoked-authority retirement map to inventory8-C03. Transactional current-authority and exact-revision enforcement maps to inventory8-C04. CI workflow placement, action versions, and acceptance-job coverage map to inventory4-C01. Existing owning case IDs remain references, never new definitions. Structural counts and reciprocal mappings establish inventory consistency only, not semantic completeness or executed acceptance.
+
+Publication acceptance must make all three outcomes observable: the specification satisfies the required format; internal and cross-document consistency is checked; and reciprocal catalog ownership, paths, and evidence agree with the generated view. These are publication constraints, not additional product goals or test cases. The concrete invocation and prerequisites for the specification and catalog validation outcomes remain unverified in the selected source.
+
+| Requirement | Cases |
+|---|---|
+| SDD-I143-U4-R1 | inventory4-C01 |
+| SDD-I143-U6-R1 | inventory6-C01 |
+| SDD-I143-U6-R2 | inventory6-C02 |
+| SDD-I143-U6-R3 | inventory6-C03, inventory6-C04 |
+| SDD-I143-U6-R4 | inventory6-C01, inventory6-C02, inventory6-C03, inventory6-C04 |
+| SDD-I143-U7-R1 | inventory7-C01 |
+| SDD-I143-U8-R1 | inventory8-C01 |
+| SDD-I143-U8-R2 | inventory8-C02 |
+| SDD-I143-U8-R3 | inventory8-C03 |
+| SDD-I143-U8-R4 | inventory8-C04 |
+
+## 18. Implementation sequence
+
+1. Publish this companion through the existing managed Action on the exact reviewed parent and verify the resulting branch before implementation; the retained execution contract requires publication and exact-branch validation first (`specs/task-execution-foundation.md`).
+2. Implement the Tasks presentation using the existing domain, application, and adapter boundaries and the pinned `@vypdev/ha-ui` 0.1.0-next.2 contracts. Preserve existing task-shell behavior and use the bounded multiline reason control; consult the package declaration and lockfile in `frontend/package.json` and `pnpm-lock.yaml`. Existing presentation adoption references are `frontend/src/presentation/domus-automation-execution.ts` and `frontend/src/presentation/domus-task-overview.ts`.
+3. Add current action-hint admission, refresh and revision review, reason draft retention, protected-view retirement, and transactional authority/revision checks. Keep task transition, authorization, receipt, history, and original-request recovery semantics owned by the retained contracts in `specs/household-tasks.md`, `specs/task-execution-foundation.md`, and `specs/task-assignment-interface.md`.
+4. Extend the bounded task journal and original-request allowlist for `task.transition` through the recorded authorization boundary. Preserve frozen key/action/body/scope on recovery; exact replay yields one transition, history entry, and receipt, while a changed payload conflicts. Keep the prepared/uncertain request gate and compatibility with existing journal entries.
+5. Deliver the start, block, and both unblock outcomes; multiline blocking reason validation/display; and refreshed admission, conflict review, unavailable-target, revocation, and direct-write behavior. Preserve keyboard access, English and Spanish content, and narrow touch usability. Keep the existing schema when implementation confirms persisted formats already cover the change.
+6. Qualify the complete supported coverage: Ingress and standalone, both CPU images, and an immutable installed Edge candidate. Follow the existing CI acceptance gates, preserve configured self-hosted runner placement and full released action versions, and collect the corresponding UX, image, and installed-artifact evidence. The parent workflow is `.github/workflows/ci_check.yml`; its actual job scope must remain intact.
+
+## 19. Definition of Done
+
+- [ ] Every requirement is covered by an observable case and reciprocal traceability; each declared case exercises only the requirements it actually covers, including transition eligibility and authority, reason validation and retention, refreshed admission, reviewed conflict recovery, target unavailability/revocation, and transactional direct-write checks.
+- [ ] Start, block, and unblock use current matching transition hints, preserve assignee identities, apply the specified target authority, and retain the existing task command and state-policy semantics.
+- [ ] Blocking validates required meaningful multiline text with `validate_task_text(multiline=True, required=True)`, enforces the 1000 Unicode code point limit and existing Unicode/control rules, preserves correctable drafts, and shows the saved reason as text to permitted readers. Start and unblock clear current reason as specified while history retains prior reasons.
+- [ ] Admission refreshes current session, scope, task detail, and action hints through the existing controller path. Stale hints never authorize a change. Conflicts retain proposed target and reason, show current facts, and require explicit review followed by a separate save at the reviewed revision. Unavailable targets require a deliberate new choice; authority revocation follows protected-view retirement; direct writes transactionally recheck current authority and exact revision.
+- [ ] Original-request recovery preserves frozen request binding and scope, admits the existing `task.transition` action through recorded authorization, and proves exact replay, changed-payload conflict, and one-time transition/history/receipt behavior after interruption or restart. Current task facts remain distinguishable from the recovered historical result, including after activated restore.
+- [ ] Existing CI acceptance gates pass with the configured self-hosted runner placement and full released action versions. Acceptance covers the Tasks journeys, applicable container jobs, Ingress and standalone, both CPU images, and an immutable installed Edge candidate. Preserve existing repository coverage thresholds and qualify complete supported coverage without exclusions or denominator reduction.
+- [ ] Accessibility, keyboard use, narrow touch behavior, English and Spanish, and reason-control labels, instructions, and errors are reviewed against implemented journeys.
+- [ ] The specification satisfies the required format; internal and cross-document consistency is checked; reciprocal catalog ownership, paths, and evidence agree with the generated view. These are observable publication outcomes, not generic maintainer acceptance. The installed root and frontend package declarations expose no `validate:specifications` or `generate:specifications` script; the concrete SDD validation invocation and prerequisite therefore remain unverified. A documentation check alone does not establish these outcomes.
+- [ ] No readiness-blocking decision remains unresolved.
+
+## 20. References and decisions
+
+- Issue: https://github.com/vypdev/domus/issues/143
+- Selected source revision: `50ddb2d60de4b4a53970ecdde70eb746ade38d30`.
+- Retained owning contracts: `specs/household-tasks.md`, `specs/task-execution-foundation.md`, `specs/household-task-categories.md`, and `specs/task-assignment-interface.md`. This companion defines only the Tasks progress-interface delta; existing owner contracts and cases remain in force.
+- UI package declaration and lock: `frontend/package.json` and `pnpm-lock.yaml`. Existing presentation references: `frontend/src/presentation/domus-automation-execution.ts` and `frontend/src/presentation/domus-task-overview.ts`.
+- Existing acceptance workflow: `.github/workflows/ci_check.yml`; preserve its current gates, runner placement, and full action versions. The concrete invocation/prerequisite for SDK specification validation was not observed in the selected project declarations.
+- Decisions: use the existing task transition command, current server action hints and authorization, controller refresh path, reason validator, journal, and original-request recovery boundary. Retain schema 34 only if implementation confirms current persisted formats suffice. Publish and verify the managed issue branch from the reviewed parent before contributor implementation.
+- Deferred work: no change to the owning task contracts or unrelated task operations.
From 09401f49be3ad10e52c63f935b9355b960ea5c52 Mon Sep 17 00:00:00 2001
From: Efra Espada
Date: Thu, 19 Nov 2026 10:10:25 +0100
Subject: [PATCH 2/9] docs: preserve supplied task progress acceptance
identities
---
specs/task-progress-interface.md | 113 ++++++++++++++++---------------
1 file changed, 59 insertions(+), 54 deletions(-)
diff --git a/specs/task-progress-interface.md b/specs/task-progress-interface.md
index e2cfa53..51dc0b7 100644
--- a/specs/task-progress-interface.md
+++ b/specs/task-progress-interface.md
@@ -54,17 +54,13 @@ Current server state and command checks govern every mutation; hints are not aut
Publication completion requires that the specification satisfy the required format, that internal and cross-document consistency is checked, and that reciprocal catalog ownership, paths, and evidence agree with the generated view. These are publication constraints, not product goals or claims that checks have run.
| Requirement | Behavior |
-| --- | --- |
-| SDD-I143-U4-R1 | The increment MUST follow the existing CI acceptance gates and preserve the configured self-hosted runner placement and full released action versions. |
-| SDD-I143-U6-R1 | Start transitions an assigned task to in_progress only when the current transition:in_progress hint is present. |
-| SDD-I143-U6-R2 | Block transitions an available, assigned, or in_progress task to blocked only when the current transition:blocked hint is present. |
-| SDD-I143-U6-R3 | Unblock transitions a blocked task to assigned when its current assignee set is nonempty, or to available when that set is empty; it requires the matching current transition: hint. |
-| SDD-I143-U6-R4 | Start, block, and unblock preserve assignee identities and use current authorization: tasks.complete for in_progress, blocked, and assigned targets, and tasks.manage for available. |
-| SDD-I143-U7-R1 | Blocking requires meaningful valid multiline text within the existing 1000 Unicode code point maximum, validated with validate_task_text(multiline=True, required=True); preserve the exact valid submission, reject blank required reasons, invalid Unicode, and disallowed controls, and preserve a correctable draft across validation and recoverable failures. |
-| SDD-I143-U8-R1 | A start, block, or unblock action captures the selected occurrence identity, target, reason, and revision; refreshes current session, scope, task detail, and action hints through the existing controller path before admission; and never treats a stale hint as authority. |
-| SDD-I143-U8-R2 | On a changed revision or competing post-admission conflict, retain the proposed target and reason and show current facts; require explicit review followed by a separate deliberate save at the reviewed revision while the target remains permitted. |
-| SDD-I143-U8-R3 | When a target is unavailable, offer refresh or cancel and require a deliberate new choice; when authority is revoked, follow existing protected-view retirement behavior. |
-| SDD-I143-U8-R4 | Recheck current command authority and exact revision transactionally for direct writes. |
+|---|---|
+| 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. |
## 5. Current versus proposed product journey
@@ -175,30 +171,35 @@ Qualify the increment on supported ingress and standalone surfaces, English keyb
## 14. Testing strategy and numeric budget
-The minimum distinct-case budget is ten, with one case for each defined scenario in the host-maintained inventory; repeated executions do not increase the count. Cover the three state transitions and their current authorization, blocking-reason validation and draft retention, refreshed admission and stale-hint rejection, revision and competing-write review, unavailable targets and revoked authority, transactional command checks, and the configured CI acceptance gates. Exercise normal UI paths and direct writes, including invalid input, recovery after recoverable failure, and current versus historical task facts. The retained contracts and cases in `specs/household-tasks.md`, `specs/task-execution-foundation.md`, `specs/household-task-categories.md`, and `specs/task-assignment-interface.md` remain authoritative references; this companion does not redefine them. The selected project declares `pnpm@10.34.0` and Node `>=24.20.0 <25` in root `package.json`; frontend scripts are declared in `frontend/package.json`. `specs/README.md` names `pnpm run validate:specifications` and `pnpm run generate:specifications`, but the validator definitions and execution prerequisites were not inspected here. Their availability and scope therefore remain unverified. Do not treat a declaration as execution or passing evidence. Validate this specification’s required format and internal and cross-document consistency as outcomes; retain actual applicable product and CI acceptance evidence with its observed scope.
+Nine distinct cases cover progress, authority, reason validation, concurrent
+review, original recovery, rollback, browser use and persistence. Each supplied
+case retains its exact identity and observable assertions. Repeated executions
+add evidence for the same cases. The retained task owner cases remain in force.
| Area | Minimum distinct cases | Behaviors/risks covered |
|---|---:|---|
-| workflows/setup/schema | 1 | Observable scenarios in the case inventory. |
-| start | 1 | Observable scenarios in the case inventory. |
-| block | 1 | Observable scenarios in the case inventory. |
-| unblock | 2 | Observable scenarios in the case inventory. |
-| blocking reason | 1 | Observable scenarios in the case inventory. |
-| task-progress-interface | 4 | Observable scenarios in the case inventory. |
-| Total | 10 | Distinct inventory cases; repeated executions do not add cases. |
+| Progress journey | 1 | Observable scenarios in the case inventory. |
+| Available work | 1 | Observable scenarios in the case inventory. |
+| Authority and scope | 1 | Observable scenarios in the case inventory. |
+| Reason validation | 1 | Observable scenarios in the case inventory. |
+| State and concurrency | 1 | Observable scenarios in the case inventory. |
+| Original recovery | 1 | Observable scenarios in the case inventory. |
+| Failure and rollback | 1 | Observable scenarios in the case inventory. |
+| Browser acceptance | 1 | Observable scenarios in the case inventory. |
+| Persistence and integrated acceptance | 1 | Observable scenarios in the case inventory. |
+| Total | 9 | Distinct inventory cases; repeated executions do not add cases. |
| Case ID | Area | Requirements | Scenario |
-| --- | --- | --- | --- |
-| inventory4-C01 | workflows/setup/schema | SDD-I143-U4-R1 | The increment's CI workflow retains the configured self-hosted placement and full released action versions, and its acceptance run exercises the existing task browser journeys and applicable container jobs. |
-| inventory6-C01 | start | SDD-I143-U6-R1, SDD-I143-U6-R4 | Starting an assigned task with the current transition:in_progress hint changes its state to in_progress, preserves assignee identities, and requires tasks.complete authority. |
-| inventory6-C02 | block | SDD-I143-U6-R2, SDD-I143-U6-R4 | Blocking an available, assigned, or in_progress task with the current transition:blocked hint changes its state to blocked, preserves assignee identities, and requires tasks.complete authority. |
-| inventory6-C03 | unblock | SDD-I143-U6-R3, SDD-I143-U6-R4 | Unblocking a blocked task with a nonempty current assignee set and transition:assigned hint changes its state to assigned, preserves assignee identities, and requires tasks.complete authority. |
-| inventory6-C04 | unblock | SDD-I143-U6-R3, SDD-I143-U6-R4 | Unblocking a blocked task with an empty current assignee set and transition:available hint changes its state to available and requires tasks.manage authority. |
-| inventory7-C01 | blocking reason | SDD-I143-U7-R1 | Submit valid multiline text and verify the exact text is saved as current state_reason and shown to permitted readers while blocked; verify blank, invalid Unicode, disallowed controls, and over-limit text are rejected, with the draft preserved for correction after validation and recoverable failure. |
-| inventory8-C01 | task-progress-interface | SDD-I143-U8-R1 | For start, block, and unblock, inspect the admitted action and confirm it records the selected occurrence identity, target, reason, and revision after the existing controller path refreshes current session, scope, task detail, and action hints; a stale hint alone does not admit the action. |
-| inventory8-C02 | task-progress-interface | SDD-I143-U8-R2 | Change the revision and separately create a competing post-admission conflict; each outcome retains the proposed target and reason and displays current facts, and saving is unavailable until explicit review followed by a separate deliberate save at the reviewed revision while the target is permitted. |
-| inventory8-C03 | task-progress-interface | SDD-I143-U8-R3 | Make the selected target unavailable and confirm refresh and cancel are offered and no replacement is selected without deliberate new choice; revoke authority and confirm the existing protected-view retirement behavior occurs. |
-| inventory8-C04 | task-progress-interface | SDD-I143-U8-R4 | Attempt direct writes with stale revision and with revoked or otherwise non-current command authority; each is rejected transactionally, while a write with current authority and exact revision is accepted. |
+|---|---|---|---|
+| 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
@@ -216,38 +217,42 @@ Document the Tasks journey for starting assigned work, explaining a block, and d
## 16. Acceptance scenarios
-These are prospective acceptance outcomes, not claims of implementation or execution.
+1. 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-C01)
-1. In Tasks, start an assigned task only when the current `transition:in_progress` hint is present. The state becomes `in_progress`, assignee identities remain unchanged, and current `tasks.complete` authority is required. (inventory6-C01)
-2. For available, assigned, or in-progress work, block only when the current `transition:blocked` hint is present. Preserve assignee identities and require `tasks.complete` authority for the blocked target. (inventory6-C02)
-3. Require meaningful multiline block text within the existing 1000 Unicode code-point maximum, validated with `validate_task_text(multiline=True, required=True)`. Preserve the exact accepted text as `state_reason` and show it as text to permitted readers while blocked. Reject blank required text, invalid Unicode, disallowed controls, and over-limit input; retain a correctable draft after validation or recoverable failure. (inventory7-C01)
-4. Unblock a task with current assignees to `assigned` only with `transition:assigned`; unblock one without assignees to `available` only with `transition:available`. Preserve assignee identities and enforce `tasks.complete` for the assigned target and `tasks.manage` for the available target. Start and unblock use the existing empty reason behavior; the historical block reason remains in its receipt and history. (inventory6-C03, inventory6-C04)
-5. For each action, capture the selected occurrence identity, target, reason, and revision. Refresh session, scope, task detail, and action hints through the existing controller path before admission. A stale hint alone never admits an action. (inventory8-C01)
-6. On changed revision and, separately, a competing post-admission conflict, retain the proposed target and reason and show current facts. Require explicit review and then a separate deliberate save at the reviewed revision while the target remains permitted. (inventory8-C02)
-7. If the target is unavailable, offer refresh or cancel and require a deliberate new choice without silently selecting a replacement. If authority is revoked, follow the existing protected-view retirement behavior. (inventory8-C03)
-8. Reject direct writes transactionally when command authority is revoked or otherwise not current, or the revision is not exact; accept a write with current authority and exact revision. (inventory8-C04)
-9. The increment retains the existing CI workflow’s configured self-hosted placement and full released action versions; its acceptance run exercises the existing task browser journeys and applicable container jobs. (inventory4-C01)
+2. 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-C02)
-The selected project’s current suite, installed Edge qualification, and complete supported-coverage evidence remain prospective acceptance evidence for this increment; this draft does not claim they have been run for it.
+3. 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-C03)
-## 17. Requirements traceability
+4. 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-C04)
+
+5. 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-C05)
-The host-maintained traceability inventory maps each requirement only to cases that exercise it, reciprocally with the case definitions. Start state, current transition hint, assignee preservation, and `tasks.complete` authority map to inventory6-C01. Blocking state, hint, assignee preservation, and authority map to inventory6-C02. Unblock target selection from the current assignee set and target-specific hint and authority map to inventory6-C03 and inventory6-C04. Blocking-text validation, exact saved reason, permitted display, and correctable draft map to inventory7-C01. Refreshed action admission and rejection of stale hints map to inventory8-C01. Changed-revision and competing-write review map to inventory8-C02. Unavailable target handling and revoked-authority retirement map to inventory8-C03. Transactional current-authority and exact-revision enforcement maps to inventory8-C04. CI workflow placement, action versions, and acceptance-job coverage map to inventory4-C01. Existing owning case IDs remain references, never new definitions. Structural counts and reciprocal mappings establish inventory consistency only, not semantic completeness or executed acceptance.
+6. 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-C06)
+
+7. 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-C07)
+
+8. 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-C08)
+
+9. 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. (task-progress-interface-C09)
+
+## 17. Requirements traceability
-Publication acceptance must make all three outcomes observable: the specification satisfies the required format; internal and cross-document consistency is checked; and reciprocal catalog ownership, paths, and evidence agree with the generated view. These are publication constraints, not additional product goals or test cases. The concrete invocation and prerequisites for the specification and catalog validation outcomes remain unverified in the selected source.
+Each requirement maps reciprocally to the supplied cases that exercise it.
+The nine case identities and their scenario definitions come from issue #143.
+Earlier owning case identities retain their definitions and existing evidence.
| Requirement | Cases |
|---|---|
-| SDD-I143-U4-R1 | inventory4-C01 |
-| SDD-I143-U6-R1 | inventory6-C01 |
-| SDD-I143-U6-R2 | inventory6-C02 |
-| SDD-I143-U6-R3 | inventory6-C03, inventory6-C04 |
-| SDD-I143-U6-R4 | inventory6-C01, inventory6-C02, inventory6-C03, inventory6-C04 |
-| SDD-I143-U7-R1 | inventory7-C01 |
-| SDD-I143-U8-R1 | inventory8-C01 |
-| SDD-I143-U8-R2 | inventory8-C02 |
-| SDD-I143-U8-R3 | inventory8-C03 |
-| SDD-I143-U8-R4 | inventory8-C04 |
+| task-progress-interface-R01 | task-progress-interface-C01, task-progress-interface-C02, task-progress-interface-C08, task-progress-interface-C09 |
+| task-progress-interface-R02 | task-progress-interface-C01, task-progress-interface-C02, task-progress-interface-C03, task-progress-interface-C05, task-progress-interface-C07, task-progress-interface-C09 |
+| task-progress-interface-R03 | task-progress-interface-C04, task-progress-interface-C07 |
+| task-progress-interface-R04 | task-progress-interface-C05, task-progress-interface-C08 |
+| task-progress-interface-R05 | task-progress-interface-C06, task-progress-interface-C07, task-progress-interface-C09 |
+| task-progress-interface-R06 | task-progress-interface-C08, task-progress-interface-C09 |
+
+Publication requires the specification format, internal and cross-document
+consistency, and reciprocal catalog ownership, paths and generated evidence.
+Executed product acceptance is recorded with its actual scope.
## 18. Implementation sequence
From cec2d43e79cea9f45f4586354d97c5a1ac847570 Mon Sep 17 00:00:00 2001
From: Efra Espada
Date: Thu, 19 Nov 2026 11:25:51 +0100
Subject: [PATCH 3/9] feat(tasks): confirm task progress and recover original
transitions
---
.github/workflows/ci_check.yml | 4 +-
backend/src/domus/application/task_queries.py | 1 +
backend/src/domus/entrypoints/task_http.py | 8 +-
docs/contracts/household-api.openapi.json | 2 +
.../native-household-api.openapi.json | 2 +
docs/evidence/task-progress-qualification.md | 59 ++++
frontend/src/adapters/task-values.ts | 7 +-
frontend/src/application/task-controller.ts | 13 +-
frontend/src/composition/entry-page.ts | 14 +-
frontend/src/domain/tasks.ts | 14 +
frontend/src/presentation/domus-tasks.ts | 193 ++++++++++-
frontend/src/presentation/task-messages.ts | 28 ++
frontend/tests/e2e/tasks.spec.ts | 183 ++++++++++
frontend/tests/page.test.ts | 12 +
frontend/tests/task-component.test.ts | 319 +++++++++++++++++-
frontend/tests/task-controller.test.ts | 73 ++++
frontend/tests/task-http.test.ts | 63 ++++
frontend/tests/task-journal.test.ts | 19 ++
frontend/tests/tasks.test.ts | 48 +++
tests/backend/test_task_execution_commands.py | 51 ++-
tests/backend/test_task_http.py | 90 +++++
tests/backend/test_task_queries.py | 1 +
tests/python/test_ci_contract.py | 4 +-
23 files changed, 1187 insertions(+), 21 deletions(-)
create mode 100644 docs/evidence/task-progress-qualification.md
diff --git a/.github/workflows/ci_check.yml b/.github/workflows/ci_check.yml
index a65b4da..92f39b1 100644
--- a/.github/workflows/ci_check.yml
+++ b/.github/workflows/ci_check.yml
@@ -401,11 +401,11 @@ jobs:
run: >-
lockf -k -t 600 /tmp/domus-ci-entry-browser.lock pnpm --filter @domus/frontend exec playwright test
-c playwright.entry.config.ts tests/e2e/administration.spec.ts tests/e2e/tasks.spec.ts tests/e2e/workspace-navigation.spec.ts
- - name: Require all sixty actual-image household journeys
+ - name: Require all sixty-four actual-image household journeys
run: >-
uv run python -c "import json; from pathlib import Path;
result=json.loads(Path('frontend/test-results/entry-results.json').read_text());
- assert result['stats']['expected']==60 and result['stats']['unexpected']==0
+ assert result['stats']['expected']==64 and result['stats']['unexpected']==0
and result['stats']['skipped']==0 and result['stats']['flaky']==0"
- name: Retain actual-image browser evidence
diff --git a/backend/src/domus/application/task_queries.py b/backend/src/domus/application/task_queries.py
index 371734c..60ef6b4 100644
--- a/backend/src/domus/application/task_queries.py
+++ b/backend/src/domus/application/task_queries.py
@@ -843,6 +843,7 @@ def original(self, action: str, key: str) -> OperationView:
"task.create",
"task.claim",
"task.assign",
+ "task.transition",
"task.complete",
"task.verify",
"task.reopen",
diff --git a/backend/src/domus/entrypoints/task_http.py b/backend/src/domus/entrypoints/task_http.py
index 8866629..7102a65 100644
--- a/backend/src/domus/entrypoints/task_http.py
+++ b/backend/src/domus/entrypoints/task_http.py
@@ -97,7 +97,13 @@
)
TaskWorkspaceAction = Literal[
- "task.create", "task.claim", "task.assign", "task.complete", "task.verify", "task.reopen"
+ "task.create",
+ "task.claim",
+ "task.assign",
+ "task.transition",
+ "task.complete",
+ "task.verify",
+ "task.reopen",
]
diff --git a/docs/contracts/household-api.openapi.json b/docs/contracts/household-api.openapi.json
index 54fd3c2..907fc92 100644
--- a/docs/contracts/household-api.openapi.json
+++ b/docs/contracts/household-api.openapi.json
@@ -9571,6 +9571,7 @@
"task.create",
"task.claim",
"task.assign",
+ "task.transition",
"task.complete",
"task.verify",
"task.reopen"
@@ -31830,6 +31831,7 @@
"task.create",
"task.claim",
"task.assign",
+ "task.transition",
"task.complete",
"task.verify",
"task.reopen"
diff --git a/docs/contracts/native-household-api.openapi.json b/docs/contracts/native-household-api.openapi.json
index c73bd1a..7ad5661 100644
--- a/docs/contracts/native-household-api.openapi.json
+++ b/docs/contracts/native-household-api.openapi.json
@@ -9533,6 +9533,7 @@
"task.create",
"task.claim",
"task.assign",
+ "task.transition",
"task.complete",
"task.verify",
"task.reopen"
@@ -31471,6 +31472,7 @@
"task.create",
"task.claim",
"task.assign",
+ "task.transition",
"task.complete",
"task.verify",
"task.reopen"
diff --git a/docs/evidence/task-progress-qualification.md b/docs/evidence/task-progress-qualification.md
new file mode 100644
index 0000000..5595eec
--- /dev/null
+++ b/docs/evidence/task-progress-qualification.md
@@ -0,0 +1,59 @@
+# Task progress interface qualification
+
+Issue #143 connects the existing task transition command to the Tasks workspace.
+The owning companion is [task progress interface](../../specs/task-progress-interface.md).
+The retained household task, execution, category and assignment owners keep their
+published case identities and behavior.
+
+Start confirms the assigned-to-in-progress transition. Block confirms a meaningful
+multiline reason. Unblock confirms Assigned when assignees remain and Available
+when the assignee set is empty. Current server hints determine discovery. The
+command transaction enforces current target-specific grants, household scope and
+the exact reviewed revision. Assignee identities remain unchanged.
+
+The editor uses released ha-ui buttons, cards and feedback from `0.1.0-next.2`.
+It preserves the existing multiline text validator and 1,000-code-point bound.
+A competing update retains the proposed target and reason. A separate review
+accepts current facts before a deliberate save. An unavailable target offers
+refresh and cancellation. Opening progress confirmation preserves other task
+form drafts and hides their competing actions until the confirmation closes.
+
+The existing workspace original-request allowlist now includes `task.transition`
+through recorded authorization. Both OpenAPI projections include the action.
+Original receipt decoding binds the task, revision, target and exact reason to
+the frozen journal request. Existing creation and assignment entries remain
+readable. Storage schema 34 and the persisted transition format are retained.
+
+| Published case | Executable evidence |
+| --- | --- |
+| task-progress-interface-C01 | The [compiled progress journeys](../../frontend/tests/e2e/tasks.spec.ts) start assigned work, block it and unblock it while checking revisions and assignees. The [component tests](../../frontend/tests/task-component.test.ts) require confirmation before each command. |
+| task-progress-interface-C02 | The compiled journeys block available work, return it to available and verify an empty assignee set. The retained [execution command tests](../../tests/backend/test_task_execution_commands.py) cover current target-specific grants. |
+| task-progress-interface-C03 | The [HTTP recovery regression](../../tests/backend/test_task_http.py) exercises both compositions and denies original disclosure after role revocation. The retained [query tests](../../tests/backend/test_task_queries.py) verify recorded authority, scope and transition target. |
+| task-progress-interface-C04 | The [domain tests](../../frontend/tests/tasks.test.ts), component tests and [normal page decoder tests](../../frontend/tests/page.test.ts) reject blank, invalid Unicode, controls and over-bound reasons. The compiled journey checks correction and exact saved multiline text. The retained backend validators enforce the same bound. |
+| task-progress-interface-C05 | Two browser tabs compete at one revision. The losing editor retains its reason. A still-permitted target requires explicit current review and a separate save. An unavailable target requires refresh or cancellation. The [controller tests](../../frontend/tests/task-controller.test.ts) include a conflict after preflight. |
+| task-progress-interface-C06 | The compiled journey commits a transition and drops its response. Reload recovers the same original operation. Exact replay preserves counts and changed key payload conflicts. [Transport tests](../../frontend/tests/task-http.test.ts) reject mismatched receipts. [Journal tests](../../frontend/tests/task-journal.test.ts) retain progress alongside older entries. |
+| task-progress-interface-C07 | Four execution command tests inject failure after an actual occurrence write, verify rollback of state and evidence, and retry the same original key successfully. Controller and component tests preserve correctable input across unavailable, denied and uncertain outcomes. |
+| task-progress-interface-C08 | Four compiled journeys cover Ingress and standalone with English desktop keyboard and Spanish 390 px native touch. Component tests assert reason, review, cancellation and recovery focus, public ha-ui controls and inert text. |
+| task-progress-interface-C09 | The compiled journey restarts the composed runtime, checks its saved reason and original operation, completes work, then restores an earlier checkpoint. Original replay returns the historical operation and leaves the restored current task and evidence counts unchanged. |
+
+The local frontend campaign passes 1,912 tests with all four coverage metrics at
+100% globally and per authored runtime file. The independent specification SDK
+accepts all nine supplied cases, reciprocal requirements and retained owners.
+The complete backend campaign passes 5,515 tests with 100% statement and branch
+coverage globally and per authored module, followed by an independent source
+audit. Four subsequently added late-write rollback cases and ten normal-HTTP
+Unicode-bound cases pass separately. Final CI collects their combined inventory.
+
+All four compiled progress journeys pass. They check readable card text and
+primary actions in both themes. An observed dark-theme primary-button ratio of
+1.72 failed the regression before the public on-accent token was supplied by the
+Tasks host. The same host tokens also reach the nested policy controls. The
+tests wait for the theme transition's final contrast before measuring it.
+
+The longer journey uses the existing Saved requests interface to dismiss a
+resolved creation request before reaching the fixed eight-record journal
+capacity. It retains the original transition receipt for restart and restoration.
+The complete source campaign passes all 119 compiled browser journeys without
+skips, unexpected results or flaky outcomes. The rebuilt catalog passes all
+45 journeys. Both CPU image campaigns and the immutable installed Edge candidate
+are being qualified before readiness.
diff --git a/frontend/src/adapters/task-values.ts b/frontend/src/adapters/task-values.ts
index 13d740c..93a944e 100644
--- a/frontend/src/adapters/task-values.ts
+++ b/frontend/src/adapters/task-values.ts
@@ -1,7 +1,7 @@
/** Project the task wire contract into immutable UI facts, preserving exact integers. */
import {nextRevision} from '../domain/administration';
import {civilDate} from '../domain/civil-date';
-import {categoryLabel, isCategoryCommand, taskCommand, taskIdentifier, taskQuantity, taskText, TASK_PRIORITIES, TASK_STATES} from '../domain/tasks';
+import {categoryLabel, isCategoryCommand, taskCommand, taskIdentifier, taskQuantity, taskText, TASK_PRIORITIES, TASK_STATES, TASK_TEXT_LIMITS} from '../domain/tasks';
import type {TaskCategoryCatalog, TaskCommand, TaskCycleSummary, TaskDetail, TaskPage, TaskReceipt, TaskSummary} from '../domain/tasks';
import type {TaskOriginal, TaskRequest} from '../application/task-ports';
import {boolean, check, choice, fields, identifier, invalid, responseInteger, responseRevision, text} from './json-values';
@@ -88,6 +88,7 @@ export function taskDetail(value: unknown, occurrenceId: string, householdId: st
const current = item.cycle === null ? null : cycle(item.cycle, occurrenceId, householdId);
check(base.currentCycleId === null || current?.cycleId === base.currentCycleId);
return Object.freeze({...base, description: literal(content.description, 4000, false, true), priority: choice(content.priority, TASK_PRIORITIES),
+ ...base.state === 'blocked' ? {stateReason: literal(work.state_reason, TASK_TEXT_LIMITS.reason, true, true)} : {},
allowedActions: Object.freeze(allowedActions), cycle: current, materials: Object.freeze(materials),
...item.completion_points === undefined ? {} : {completionPoints: choice(item.completion_points, ['automatic','manual','manager_required'] as const)},
materialRecording: choice(rules.material_recording, ['review_on_completion', 'separate_recording']),
@@ -163,6 +164,9 @@ export function taskReceipt(value: unknown, request: TaskRequest | TaskOriginal,
if (command.action !== 'task.create') check(command.occurrenceId === occurrenceId);
if (command.action === 'task.assign')
check(JSON.stringify([...assigneeIds].sort()) === JSON.stringify([...command.payload.assignee_ids].sort()));
+ if (command.action === 'task.transition')
+ check(state === command.payload.target
+ && literal(result.state_reason, TASK_TEXT_LIMITS.reason, state === 'blocked', true) === command.payload.reason);
const savedCycle = Object.hasOwn(result, 'cycle') ? cycle(result.cycle, occurrenceId) : null;
if (command.action === 'task.complete') {
check(state === 'completed' && savedCycle !== null && savedCycle.performedAt === command.payload.performed_at
@@ -175,6 +179,7 @@ export function taskReceipt(value: unknown, request: TaskRequest | TaskOriginal,
}
return Object.freeze({kind: 'receipt', stage, action: command.action, operationId, occurrenceId, revision, state, cycle: savedCycle, archivedBy,
...command.action === 'task.assign' ? {assigneeIds} : {},
+ ...command.action === 'task.transition' ? {stateReason: command.payload.reason} : {},
...originalBasePoints(result.point_value_minor, basePoints)});
}
/** Only validated decimal lexemes bypass JSON's string quoting; arbitrary text always uses JSON.stringify. */
diff --git a/frontend/src/application/task-controller.ts b/frontend/src/application/task-controller.ts
index 25a66f8..0ae94de 100644
--- a/frontend/src/application/task-controller.ts
+++ b/frontend/src/application/task-controller.ts
@@ -1,7 +1,7 @@
/** Task workflows coordinate current identity, durable original intents and server-owned actions. */
import {JournalError} from '../domain/journal';
import {isCategoryCommand, taskCommand, taskIdentifier} from '../domain/tasks';
-import type {TaskAccess, TaskCommand, TaskDetail, TaskMaterialUsage, TaskPage, TaskPriority, TaskScheduleDraft} from '../domain/tasks';
+import type {TaskAccess, TaskCommand, TaskDetail, TaskMaterialUsage, TaskPage, TaskPriority, TaskProgressTarget, TaskScheduleDraft} from '../domain/tasks';
import {EntryReadError} from './ports';
import type {Revision} from '../domain/administration';
import type {ReviewedAllocation} from '../domain/point-allocation';
@@ -131,6 +131,7 @@ export class TaskController {
const detail = this.state.detail!;
if (detail.occurrenceId !== command.occurrenceId) return false;
if (detail.revision !== command.payload.expected_revision) {this.update({notice: 'conflict'}); return false;}
+ if (command.action === 'task.transition') return detail.allowedActions.includes('transition:' + command.payload.target);
const action = command.action === 'task.verify' ? command.payload.decision === 'approved' ? 'approve' : 'reject' : command.action.slice(5);
return detail.allowedActions.includes(action);
}
@@ -164,7 +165,8 @@ export class TaskController {
}
if (this.clock.now() >= this.state.session!.expiresAt) throw new EntryReadError('authentication_required');
if (outcome.kind === 'receipt') await this.receiptFacts(command, outcome.occurrenceId, prior, generation);
- if (command.action === 'task.assign' && outcome.kind === 'rejected' && outcome.reason === 'conflict')
+ if ((command.action === 'task.assign' || command.action === 'task.transition')
+ && outcome.kind === 'rejected' && outcome.reason === 'conflict')
await this.facts(generation, command.occurrenceId);
});
}
@@ -205,6 +207,13 @@ export class TaskController {
if (work.occurrenceId !== occurrenceId) {this.update({notice: 'conflict'}); return Promise.resolve();}
return this.execute({action: 'task.assign', occurrenceId, payload: {expected_revision: revision, assignee_ids: assigneeIds}});
}
+ transition(occurrenceId: string, revision: Revision, target: TaskProgressTarget, reason: string): Promise {
+ const work = this.state.detail;
+ if (work === null) return Promise.resolve();
+ if (work.occurrenceId !== occurrenceId) {this.update({notice: 'conflict'}); return Promise.resolve();}
+ return this.execute({action: 'task.transition', occurrenceId,
+ payload: {expected_revision: revision, target, reason}});
+ }
complete(materialUsages: readonly TaskMaterialUsage[] | null, reviewed?: ReviewedAllocation): Promise {
const work = this.state.detail, member = this.state.access?.memberId;
if (work === null || member === undefined) return Promise.resolve();
diff --git a/frontend/src/composition/entry-page.ts b/frontend/src/composition/entry-page.ts
index 597dfcb..266bab8 100644
--- a/frontend/src/composition/entry-page.ts
+++ b/frontend/src/composition/entry-page.ts
@@ -65,7 +65,7 @@ import {language, message} from '../presentation/messages';
import type {DomusApp, EntryIntent} from '../presentation/domus-app';
import {revisionValue} from '../domain/administration';
import type {TaskIntent} from '../presentation/domus-tasks';
-import {taskAssignees, taskBasePointAmount, taskQuantity, taskScheduleDraft, TASK_PRIORITIES} from '../domain/tasks';
+import {taskAssignees, taskBasePointAmount, taskCommand, taskQuantity, taskScheduleDraft, TASK_PRIORITIES} from '../domain/tasks';
import type {TaskPriority} from '../domain/tasks';
import type {AdministrationIntent} from '../presentation/domus-administration';
import {administrationCommand} from '../domain/administration-commands';
@@ -134,12 +134,20 @@ function reviewedAllocation(value: unknown): ReviewedAllocation {
export function decodeTaskIntent(value: unknown): TaskIntent | null {
try {
- const item = fields(value, ['type'], ['title', 'description', 'priority', 'schedule', 'occurrenceId', 'materialUsages', 'decision', 'reason', 'key', 'categoryId', 'label', 'revision', 'reviewed', 'basePointsMinor', 'assigneeIds']);
+ const item = fields(value, ['type'], ['title', 'description', 'priority', 'schedule', 'occurrenceId', 'materialUsages', 'decision', 'reason', 'key', 'categoryId', 'label', 'revision', 'reviewed', 'basePointsMinor', 'assigneeIds', 'target']);
const type = item.type;
if (type === 'assign') {
fields(value, ['type', 'occurrenceId', 'revision', 'assigneeIds'], []);
return {type, occurrenceId: identifier(item.occurrenceId), revision: revisionValue(item.revision), assigneeIds: taskAssignees(item.assigneeIds)};
}
+ if (type === 'transition') {
+ fields(value, ['type', 'occurrenceId', 'revision', 'target', 'reason'], []);
+ const command = taskCommand({action: 'task.transition', occurrenceId: item.occurrenceId,
+ payload: {expected_revision: item.revision, target: item.target, reason: item.reason}});
+ check(command?.action === 'task.transition');
+ return {type, occurrenceId: command.occurrenceId, revision: command.payload.expected_revision,
+ target: command.payload.target, reason: command.payload.reason};
+ }
if (type === 'create') {
fields(value, ['type', 'title', 'description', 'priority'], ['schedule', 'categoryId', 'basePointsMinor']);
check(typeof item.title === 'string' && typeof item.description === 'string' && typeof item.priority === 'string'
@@ -711,6 +719,8 @@ export function mountEntry(page: EntryPage): PageMount {
case 'archiveCategory': await active.taskWork(controller => controller.archiveCategory(intent.categoryId, intent.revision)); break;
case 'claim': await active.taskWork(controller => controller.claim()); break;
case 'assign': await active.taskWork(controller => controller.assign(intent.occurrenceId, intent.revision, intent.assigneeIds)); break;
+ case 'transition': await active.taskWork(controller => controller.transition(
+ intent.occurrenceId, intent.revision, intent.target, intent.reason)); break;
case 'complete':
await active.taskWork(controller => controller.complete(intent.materialUsages, ...intent.reviewed === undefined ? [] : [intent.reviewed]));
break;
diff --git a/frontend/src/domain/tasks.ts b/frontend/src/domain/tasks.ts
index f2a1b5f..0a6e6e6 100644
--- a/frontend/src/domain/tasks.ts
+++ b/frontend/src/domain/tasks.ts
@@ -44,6 +44,8 @@ export function taskAssignees(value: unknown): readonly string[] {
}
export const TASK_STATES = ['draft', 'available', 'assigned', 'in_progress', 'blocked', 'completed', 'cancelled', 'skipped'] as const;
export type TaskState = typeof TASK_STATES[number];
+export const TASK_PROGRESS_TARGETS = ['in_progress', 'blocked', 'assigned', 'available'] as const;
+export type TaskProgressTarget = typeof TASK_PROGRESS_TARGETS[number];
export const TASK_PRIORITIES = ['low', 'normal', 'high', 'urgent'] as const;
export type TaskPriority = typeof TASK_PRIORITIES[number];
type ScheduledStart = Readonly<{kind: 'date' | 'time'; local: string}>;
@@ -77,6 +79,8 @@ export type TaskCommand = CategoryCommand |
category_id?: string; schedule?: TaskSchedule; overrides?: TaskCreationOverrides}>}>
| Readonly<{action: 'task.claim'; occurrenceId: string; payload: Readonly<{expected_revision: Revision}>}>
| Readonly<{action: 'task.assign'; occurrenceId: string; payload: Readonly<{expected_revision: Revision; assignee_ids: readonly string[]}>}>
+ | Readonly<{action: 'task.transition'; occurrenceId: string; payload: Readonly<{
+ expected_revision: Revision; target: TaskProgressTarget; reason: string}>}>
| Readonly<{action: 'task.complete'; occurrenceId: string; payload: Readonly<{expected_revision: Revision;
performer_ids: readonly string[]; performed_at: string; material_usages: readonly TaskMaterialUsage[] | null;
allocation_fingerprint?: string; manual_shares?: readonly ManualShare[]}>}>
@@ -171,6 +175,14 @@ export function taskCommand(value: unknown): TaskCommand | undefined {
return Object.freeze({action, occurrenceId, payload: Object.freeze({expected_revision: revisionValue(body.expected_revision),
assignee_ids: taskAssignees(body.assignee_ids)})});
}
+ if (action === 'task.transition') {
+ const body = fields(item.payload, ['expected_revision', 'target', 'reason']);
+ const target = choice(body.target, TASK_PROGRESS_TARGETS);
+ const reason = taskText(body.reason, TASK_TEXT_LIMITS.reason, target === 'blocked', true);
+ requireValue(target === 'blocked' || reason === '');
+ return Object.freeze({action, occurrenceId, payload: Object.freeze({
+ expected_revision: revisionValue(body.expected_revision), target, reason})});
+ }
if (action === 'task.claim') {
const body = fields(item.payload, ['expected_revision']);
return Object.freeze({action, occurrenceId, payload: Object.freeze({expected_revision: revisionValue(body.expected_revision)})});
@@ -215,6 +227,7 @@ export interface TaskCycleSummary {
}
export interface TaskDetail extends TaskSummary {
readonly description: string; readonly priority: TaskPriority; readonly allowedActions: readonly string[];
+ readonly stateReason?: string;
readonly completionPoints?: 'automatic' | 'manual' | 'manager_required';
readonly cycle: TaskCycleSummary | null; readonly materials: readonly TaskMaterial[];
readonly materialRecording: 'review_on_completion' | 'separate_recording';
@@ -236,4 +249,5 @@ export interface TaskReceipt {
readonly archivedBy: string | null;
readonly basePointsMinor?: number;
readonly assigneeIds?: readonly string[];
+ readonly stateReason?: string;
}
diff --git a/frontend/src/presentation/domus-tasks.ts b/frontend/src/presentation/domus-tasks.ts
index bc457aa..abda8db 100644
--- a/frontend/src/presentation/domus-tasks.ts
+++ b/frontend/src/presentation/domus-tasks.ts
@@ -7,12 +7,18 @@ import {textFieldState} from '@vypdev/ha-ui/field-contracts';
import {registerCheckbox} from '@vypdev/ha-ui/checkbox';
import type {CheckboxChangeEvent} from '@vypdev/ha-ui/checkbox';
import {checkboxChangeDetail, checkboxState} from '@vypdev/ha-ui/checkbox-contracts';
+import {registerButton} from '@vypdev/ha-ui/button';
+import {buttonState} from '@vypdev/ha-ui/button-contracts';
+import {registerCard} from '@vypdev/ha-ui/card';
+import {cardState} from '@vypdev/ha-ui/card-contracts';
+import {registerFeedback} from '@vypdev/ha-ui/feedback';
+import {feedbackState} from '@vypdev/ha-ui/feedback-contracts';
import type {AdministrationView} from '../application/administration-controller';
import type {TaskView} from '../application/task-controller';
import type {TaskRecord} from '../application/task-ports';
-import {categoryLabel, hasTaskText, taskAssignees, taskQuantity, taskScheduleDraft, TASK_PRIORITIES, TASK_TEXT_LIMITS} from '../domain/tasks';
+import {categoryLabel, hasTaskText, taskAssignees, taskQuantity, taskScheduleDraft, taskText, TASK_PRIORITIES, TASK_TEXT_LIMITS} from '../domain/tasks';
import type {Revision} from '../domain/administration';
-import type {TaskCategory, TaskDetail, TaskMaterialUsage, TaskPriority, TaskScheduleDraft} from '../domain/tasks';
+import type {TaskCategory, TaskDetail, TaskMaterialUsage, TaskPriority, TaskProgressTarget, TaskScheduleDraft} from '../domain/tasks';
import {language} from './messages';
import type {Language} from './messages';
import {taskDeadline, taskInstant, taskMessage} from './task-messages';
@@ -27,6 +33,7 @@ import './domus-allocation-settings';
export type TaskIntent = Readonly<{type: 'refresh' | 'more' | 'claim'}>
| Readonly<{type: 'select'; occurrenceId: string}>
| Readonly<{type: 'assign'; occurrenceId: string; revision: Revision; assigneeIds: readonly string[]}>
+ | Readonly<{type: 'transition'; occurrenceId: string; revision: Revision; target: TaskProgressTarget; reason: string}>
| Readonly<{type: 'create'; title: string; description: string; priority: TaskPriority;
categoryId?: string; schedule?: TaskScheduleDraft; basePointsMinor?: number}>
| Readonly<{type: 'createCategory'; label: string}>
@@ -39,9 +46,13 @@ export type TaskIntent = Readonly<{type: 'refresh' | 'more' | 'claim'}>
const EMPTY_SCHEDULE_FIELDS = Object.freeze({date: '', time: '', rule: '', interval: '30', visibility: 'at_completion'});
type ScheduleFields = {[Field in keyof typeof EMPTY_SCHEDULE_FIELDS]: string};
type AssignmentDraft = Readonly<{occurrenceId: string; revision: Revision; assigneeIds: readonly string[]}>;
+type ProgressDraft = Readonly<{occurrenceId: string; revision: Revision; target: TaskProgressTarget; reason: string}>;
function validCategoryLabel(value: string): boolean {
try {categoryLabel(value); return true;} catch {return false;}
}
+function validBlockingReason(value: string): boolean {
+ try {taskText(value, TASK_TEXT_LIMITS.reason, true, true); return true;} catch {return false;}
+}
function quantityInput(value: string, precision: number): string | null {
const trimmed = value.trim();
if (trimmed.length > 64 || !/^[0-9]+(?:[.,][0-9]+)?$/u.test(trimmed)) return null;
@@ -53,6 +64,7 @@ function quantityInput(value: string, precision: number): string | null {
/** Render only verified task facts; emitted intents never select an actor or grant a permission. */
export class DomusTasks extends LitElement {
static properties = {administration: {attribute: false}, assignmentDraft: {state: true}, assignmentError: {state: true},
+ progressDraft: {state: true}, progressError: {state: true},
allocation: {attribute: false}, participantNames: {attribute: false}, view: {attribute: false}, retired: {attribute: false}, language: {attribute: false}, titleDraft: {state: true}, descriptionDraft: {state: true},
categoryDraft: {state: true}, categoryName: {state: true}, categoryEdit: {state: true}, manageOpen: {state: true},
basePointsDraft: {state: true}, basePointsError: {state: true},
@@ -74,6 +86,12 @@ export class DomusTasks extends LitElement {
--vyp-ha-text:var(--text);--vyp-ha-font-family:inherit;--ha-checkbox-border-color:var(--muted);
--ha-checkbox-background-color-hover:var(--canvas);--ha-checkbox-checked-background-color:var(--accent);
--ha-checkbox-checked-background-color-hover:var(--accent);--wa-focus-ring:solid 2px var(--accent)}
+ :host {--vyp-ha-surface:var(--surface);--vyp-ha-surface-raised:var(--surface);
+ --vyp-ha-text:var(--text);--vyp-ha-text-secondary:var(--muted);--vyp-ha-border:var(--line);
+ --vyp-ha-primary:var(--accent);--vyp-ha-on-accent:var(--surface);--vyp-ha-focus-ring:3px solid var(--accent)}
+ vyp-ha-button {--vyp-ha-button-height:44px}
+ .progress {margin-block:24px}.progress h4 {margin-block:0 8px}.progress .field {margin-block:16px}
+ .progress vyp-ha-feedback {margin-block:12px}.task-work-actions[hidden] {display:none}
@media(min-width:800px) {.task-layout {grid-template-columns:minmax(0,1fr) minmax(0,1fr)}.task-layout.single {grid-template-columns:1fr}}`];
declare allocation: AllocationView | null;
declare administration: Pick | null;
@@ -106,13 +124,18 @@ export class DomusTasks extends LitElement {
private declare assignmentError: boolean;
private submittedAssignment: AssignmentDraft | null = null;
private assignmentFocus: string | null = null;
- private lastForm: 'create' | 'review' | 'category' | 'assignment' = 'create';
+ private declare progressDraft: ProgressDraft | null;
+ private declare progressError: boolean;
+ private submittedProgress: ProgressDraft | null = null;
+ private progressFocus: string | null = null;
+ private lastForm: 'create' | 'review' | 'category' | 'assignment' | 'progress' = 'create';
private focusDetail = false;
constructor() {super(); this.allocation = null; this.participantNames = []; this.view = null; this.retired = false; this.language = 'en'; this.titleDraft = ''; this.titleRequired = false; this.descriptionDraft = '';
this.priorityDraft = 'normal'; this.scheduleKind = 'manual'; this.scheduleError = false; this.scheduleInput = EMPTY_SCHEDULE_FIELDS;
this.createOpen = false; this.reasonDraft = ''; this.quantities = {}; this.quantityError = null;
this.basePointsDraft = ''; this.basePointsError = null;
this.administration = null; this.assignmentDraft = null; this.assignmentError = false;
+ this.progressDraft = null; this.progressError = false;
this.categoryDraft = ''; this.categoryName = ''; this.categoryEdit = null; this.manageOpen = false;}
private text(key: TaskMessageKey): string {return taskMessage(key, this.language);}
private get blocked(): boolean {return this.view?.busy !== false || this.view.readOnly || this.view.records === null
@@ -125,6 +148,7 @@ export class DomusTasks extends LitElement {
this.basePointsDraft, this.scheduleKind, this.scheduleInput]);
}
private reset(): void {
+ this.resetProgress();
this.assignmentDraft = null; this.submittedAssignment = null; this.assignmentFocus = null; this.assignmentError = false;
this.categoryDraft = ''; this.categoryName = ''; this.categoryEdit = null; this.submittedCategory = null; this.manageOpen = false;
this.createOpen = false; this.titleDraft = ''; this.titleRequired = false; this.descriptionDraft = ''; this.priorityDraft = 'normal'; this.reasonDraft = '';
@@ -140,14 +164,30 @@ export class DomusTasks extends LitElement {
|| next != null && this.draftScope !== null && next !== this.draftScope) this.reset();
if (next != null) this.draftScope = next;
const detail = this.view?.detail, key = detail ? JSON.stringify([next, detail.occurrenceId, detail.revision]) : null;
+ const outcome = this.view?.outcome;
if (detail && this.assignmentDraft && (detail.occurrenceId !== this.assignmentDraft.occurrenceId || !detail.allowedActions.includes('assign'))) {
this.assignmentDraft = null; this.submittedAssignment = null; this.assignmentFocus = null;
}
if (detail && this.assignmentDraft && key !== this.detailKey && this.assignmentNeedsReview(detail))
this.assignmentFocus = '#assignment-review';
+ if (detail && this.progressDraft && detail.occurrenceId !== this.progressDraft.occurrenceId) this.resetProgress();
+ if (detail && this.progressDraft) {
+ const newConflict = outcome?.kind === 'rejected' && outcome.reason === 'conflict'
+ && outcome !== changed.get('view')?.outcome;
+ if (this.progressNeedsReview(detail, this.progressDraft) && (key !== this.detailKey || newConflict))
+ this.progressFocus = this.progressTargets(detail).includes(this.progressDraft.target)
+ ? '#task-progress-review' : '#task-progress-editor';
+ else if (changed.get('view')?.detail === null)
+ this.progressFocus = this.progressDraft.target === 'blocked' ? '#task-progress-reason' : '#task-progress-save';
+ }
if (key !== null && key !== this.detailKey) {this.focusDetail = this.view?.phase === 'ready'; this.detailKey = key; this.reasonDraft = ''; this.quantityError = null;
this.quantities = Object.fromEntries(detail!.materials.map(item => [item.lineId, item.plannedQuantity]));}
- const outcome = this.view?.outcome;
+ if (outcome?.kind === 'receipt' && outcome.stage === 'committed' && outcome.action === 'task.transition'
+ && this.progressDraft !== null && this.progressDraft === this.submittedProgress
+ && outcome.occurrenceId === this.progressDraft.occurrenceId && outcome.state === this.progressDraft.target
+ && outcome.stateReason === this.progressDraft.reason
+ && BigInt(outcome.revision) === BigInt(this.progressDraft.revision) + 1n
+ && outcome !== changed.get('view')?.outcome) this.resetProgress('#task-progress-actions vyp-ha-button');
if (outcome?.kind === 'receipt' && outcome.stage === 'committed' && outcome.action === 'task.assign'
&& outcome.occurrenceId === this.assignmentDraft?.occurrenceId && this.assignmentDraft === this.submittedAssignment
&& outcome.assigneeIds !== undefined
@@ -171,14 +211,25 @@ export class DomusTasks extends LitElement {
protected updated(changed: PropertyValues): void {
this.lang = language(this.language, 'en');
if (this.focusDetail) {this.focusDetail = false; this.shadowRoot?.querySelector('#selected-task-title')?.focus();}
- if (changed.has('view') && this.view?.notice === 'invalid_input')
- this.shadowRoot?.querySelector(this.lastForm === 'create' ? '#task-title' : this.lastForm === 'category' ? '#task-category-label'
- : this.lastForm === 'assignment' ? '#assignment-editor' : '#task-reason')?.focus();
+ if (changed.has('view') && this.view?.notice === 'invalid_input') {
+ const field = {create: '#task-title', category: '#task-category-label', assignment: '#assignment-editor',
+ review: '#task-reason', progress: '#task-progress-editor'}[this.lastForm];
+ this.shadowRoot?.querySelector(field)?.focus();
+ }
if (this.assignmentFocus !== null) {
const target = this.renderRoot.querySelector(this.assignmentFocus)
?? this.renderRoot.querySelector('#assignment-editor');
if (target) {this.assignmentFocus = null; queueMicrotask(() => target.focus());}
}
+ if (this.progressFocus !== null && this.view?.phase === 'ready') {
+ const target = this.renderRoot.querySelector(this.progressFocus)
+ ?? this.renderRoot.querySelector('#task-progress-actions vyp-ha-button')
+ ?? this.renderRoot.querySelector('#selected-task-title');
+ if (target) {
+ this.progressFocus = null;
+ requestAnimationFrame(() => {if (target.isConnected) target.focus();});
+ }
+ }
if (changed.has('view') && this.view?.notice === 'category_unavailable')
this.renderRoot.querySelector('#task-category')?.focus();
const outcome = this.view?.outcome;
@@ -189,7 +240,7 @@ export class DomusTasks extends LitElement {
disconnectedCallback(): void {super.disconnectedCallback(); this.reset();}
private intent(detail: TaskIntent): void {
if (this.retired || this.view?.phase !== 'ready' || this.view.busy) return;
- if (['create', 'createCategory', 'renameCategory', 'archiveCategory', 'claim', 'assign', 'complete', 'verify', 'reopen'].includes(detail.type) && this.blocked) return;
+ if (['create', 'createCategory', 'renameCategory', 'archiveCategory', 'claim', 'assign', 'transition', 'complete', 'verify', 'reopen'].includes(detail.type) && this.blocked) return;
this.dispatchEvent(new CustomEvent('domus-task-intent', {detail: Object.freeze(detail), bubbles: true, composed: true}));
}
private scheduleDraft(form: HTMLFormElement): TaskScheduleDraft | undefined {
@@ -371,6 +422,120 @@ export class DomusTasks extends LitElement {
}
this.quantityError = null; this.intent({type: 'complete', materialUsages, ...reviewed === undefined ? {} : {reviewed}});
}
+ private resetProgress(focus: string | null = null): void {
+ this.progressDraft = null;
+ this.submittedProgress = null;
+ this.progressError = false;
+ this.progressFocus = focus;
+ }
+ private progressLabel(target: TaskProgressTarget): TaskMessageKey {
+ if (target === 'in_progress') return 'progressStart';
+ if (target === 'blocked') return 'progressBlock';
+ return 'progressUnblock';
+ }
+ private progressTargets(work: TaskDetail): readonly TaskProgressTarget[] {
+ const targets: TaskProgressTarget[] = [];
+ if (work.state === 'assigned') targets.push('in_progress');
+ if (['available', 'assigned', 'in_progress'].includes(work.state)) targets.push('blocked');
+ if (work.state === 'blocked') targets.push(work.assigneeIds.length ? 'assigned' : 'available');
+ return targets.filter(target => work.allowedActions.includes('transition:' + target));
+ }
+ private progressNeedsReview(work: TaskDetail, draft: ProgressDraft): boolean {
+ const outcome = this.view!.outcome;
+ return draft.occurrenceId !== work.occurrenceId || draft.revision !== work.revision
+ || this.submittedProgress !== null && outcome?.kind === 'rejected' && outcome.reason === 'conflict';
+ }
+ private openProgress(target: TaskProgressTarget): void {
+ const work = this.view?.detail;
+ if (!work || this.blocked || !this.progressTargets(work).includes(target)) return;
+ this.progressDraft = Object.freeze({occurrenceId: work.occurrenceId, revision: work.revision, target, reason: ''});
+ this.submittedProgress = null;
+ this.progressError = false;
+ this.progressFocus = target === 'blocked' ? '#task-progress-reason' : '#task-progress-save';
+ }
+ private changeProgressReason(event: InputEvent): void {
+ if (this.blocked || this.progressDraft === null) return;
+ this.progressDraft = Object.freeze({...this.progressDraft, reason: (event.target as HTMLTextAreaElement).value});
+ this.progressError = false;
+ }
+ private reviewProgress(): void {
+ const draft = this.progressDraft, work = this.view?.detail;
+ if (draft === null || !work || this.blocked || work.occurrenceId !== draft.occurrenceId
+ || !this.progressTargets(work).includes(draft.target)) return;
+ this.progressDraft = Object.freeze({...draft, revision: work.revision});
+ this.submittedProgress = null;
+ this.progressError = false;
+ this.progressFocus = draft.target === 'blocked' && !validBlockingReason(draft.reason)
+ ? '#task-progress-reason' : '#task-progress-save';
+ }
+ private saveProgress(event: SubmitEvent): void {
+ event.preventDefault();
+ const draft = this.progressDraft, work = this.view?.detail;
+ if (draft === null || !work || this.blocked) return;
+ if (this.progressNeedsReview(work, draft) || !this.progressTargets(work).includes(draft.target)) {
+ this.progressFocus = '#task-progress-editor';
+ this.requestUpdate();
+ return;
+ }
+ if (draft.target === 'blocked' && !validBlockingReason(draft.reason)) {
+ this.progressError = true;
+ this.progressFocus = '#task-progress-reason';
+ return;
+ }
+ this.submittedProgress = draft;
+ this.lastForm = 'progress';
+ this.intent({type: 'transition', occurrenceId: draft.occurrenceId, revision: draft.revision,
+ target: draft.target, reason: draft.reason});
+ }
+ private progress(work: TaskDetail) {
+ const draft = this.progressDraft, targets = this.progressTargets(work);
+ if (draft === null && targets.length === 0 && work.state !== 'blocked') return nothing;
+ const review = draft !== null && this.progressNeedsReview(work, draft);
+ const available = draft !== null && targets.includes(draft.target);
+ const invalid = draft?.target === 'blocked' && !validBlockingReason(draft.reason);
+ const showError = invalid && (this.progressError || draft.reason.length > 0);
+ return html`
+ ${work.state === 'blocked' ? html`