142 lines
6.0 KiB
Markdown
142 lines
6.0 KiB
Markdown
---
|
|
id: "01-move-decision-api"
|
|
title: "Read-only move decisions and API"
|
|
status: completed
|
|
wave: 1
|
|
depends_on: []
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-TASKS-WORKFLOW-MOVE-PREVIEW-001
|
|
- REQ-TASKS-WORKFLOW-MOVE-PREVIEW-002
|
|
acceptance_criteria:
|
|
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.1
|
|
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.2
|
|
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.3
|
|
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.4
|
|
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.5
|
|
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.6
|
|
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.7
|
|
system_design:
|
|
- ../../specs/tasks/system-design/workflow-move-preview.md
|
|
---
|
|
|
|
# Task 01: Read-only move decisions and API
|
|
|
|
## Summary
|
|
|
|
Provide a task-specific preview of recipient and expected configuration without
|
|
executing routing or ACP operations. Reuse decisions in execution paths so the
|
|
endpoint and actual moves remain consistent.
|
|
|
|
## In scope
|
|
|
|
Shared recipient decision extraction, effective configuration and conditional
|
|
rule projection, normalized one-shot reset/dispatch effects, DTO, authorized
|
|
HTTP endpoint, dependency wiring, and focused backend regression fixtures.
|
|
|
|
## Out of scope
|
|
|
|
Rendered UI, schema migrations, changed lifecycle policy, provider probes,
|
|
and caching or reserving preview selections.
|
|
|
|
## Acceptance
|
|
|
|
1. Real fixture moves match their previews for same/other/new session cases,
|
|
explicit targets, overrides, and conditional settings; terminal exclusion holds.
|
|
2. Repeated previews leave session/task metadata, bindings, messages, and runtime
|
|
invocation counters unchanged. Authorization and safe DTO filtering hold.
|
|
3. Unknown/skipped/planned configuration is explicit; existing atomic route,
|
|
retry, deferred-move, and best-effort provider semantics remain intact.
|
|
|
|
## Verification
|
|
|
|
Run from repository root. Add named test files before running these commands;
|
|
use TDD to demonstrate the missing preview behavior first.
|
|
|
|
```bash
|
|
(cd apps/backend && go test ./internal/orchestrator ./internal/task/handlers ./internal/task/service ./internal/workflow/...)
|
|
(cd apps/backend && go test -race ./internal/orchestrator ./internal/task/handlers -run 'Preview|WorkflowStepSession|WorkflowSessionConfig|WorkflowSessionTarget|SameProfile')
|
|
python3 scripts/list-docs.py validate
|
|
python3 scripts/lint-spec-files.py --all
|
|
git diff --check
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/backend/internal/orchestrator/workflow_move_preview.go`,
|
|
`workflow_move_preview_settings.go`, and `_test.go` (new).
|
|
- `apps/backend/internal/orchestrator/event_handlers_workflow.go`.
|
|
- `apps/backend/internal/orchestrator/workflow_session_target.go`.
|
|
- `apps/backend/internal/orchestrator/workflow_session_config.go`.
|
|
- `apps/backend/internal/task/handlers/workflow_move_preview_http.go` and `_test.go` (new).
|
|
- `apps/backend/internal/task/handlers/task_handlers.go`, `task_http_handlers.go`.
|
|
- `apps/backend/internal/task/dto/` and existing backendapp dependency wiring.
|
|
|
|
## Dependencies
|
|
|
|
None. Read both paired specifications and current lifecycle/conditional-settings
|
|
contracts. Existing same-profile policy and session-target tests are exemplars.
|
|
|
|
## Risks
|
|
|
|
A helper named resolve can mutate state. Review every reachable call; extract
|
|
pure inputs/outputs and keep warning publication in execution only.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
[Design](../../specs/tasks/system-design/workflow-move-preview.md), especially
|
|
Resolution, API, and Freshness and failures. [Plan test matrix](plan.md#tests).
|
|
|
|
## Results
|
|
|
|
Implemented the read-only workflow move decision layer and the authorized
|
|
`POST /api/v1/tasks/:id/move-preview` endpoint. Recipient selection shares the
|
|
pure reusable-session selector with execution, preserves explicit targets and
|
|
terminal-session exclusion, projects runtime configuration and conditional
|
|
rules without writes, and reports unknown or deferred outcomes explicitly.
|
|
|
|
Verification passed:
|
|
|
|
- `cd apps/backend && go test ./internal/orchestrator ./internal/task/handlers ./internal/task/service ./internal/workflow/...`
|
|
- `cd apps/backend && go test -race ./internal/orchestrator ./internal/task/handlers -run 'Preview|WorkflowStepSession|WorkflowSessionConfig|WorkflowSessionTarget|SameProfile'`
|
|
- `python3 scripts/list-docs.py validate`
|
|
- `python3 scripts/lint-spec-files.py --all`
|
|
- `git diff --check`
|
|
|
|
## Review remediation results
|
|
|
|
The preview now shares `workflowmove.ShouldAutoStartAgent` with the actual
|
|
no-session launch handler. A destination without `auto_start_agent`, or a
|
|
`skip_step_prompt` move without instructions, returns `no_session` with no
|
|
recipient. A permitted sessionless launch still resolves the task-level agent
|
|
profile when the destination has no step profile. Provider option labels are
|
|
bounded display labels, while Kandev-owned setting fields keep stable keys for
|
|
localization. The endpoint authorizes the task before repository access, keeps
|
|
current-session routing when only the task profile fallback exists, predicts
|
|
profile switches from an existing source session, and projects applicable
|
|
configure-session rules for a fresh launch. Busy reusable targets report
|
|
deferred dispatch, while fresh context and passthrough mode changes report
|
|
skipped applicability.
|
|
|
|
Regression coverage compares both idle launch gates with the actual move path,
|
|
checks task-profile fallback for an allowed launch, and verifies the setting
|
|
label DTO shape, task authorization ordering, typed configuration notices, and
|
|
busy-target dispatch.
|
|
|
|
Remediation verification passed on 2026-09-15:
|
|
|
|
- `cd apps/backend && go test ./internal/workflow/move ./internal/orchestrator`
|
|
- `cd apps/backend && make lint`
|
|
|
|
Final post-remediation verification also passed for the targeted backend race
|
|
suite and the managed backend build:
|
|
|
|
- `cd apps/backend && go test -race ./internal/orchestrator ./internal/task/handlers -run 'Preview|WorkflowStepSession|WorkflowSessionConfig|WorkflowSessionTarget|SameProfile'`
|
|
- `cd apps/backend && go test -race ./internal/orchestrator -count=1`
|
|
- `cd apps/backend && go test ./internal/orchestrator -run '^TestCompletedTaskFollowUpAdmissionIsConversationalOnly$' -count=100 -failfast`
|
|
- `cd apps/backend && make build`
|