Skip to content

Commit 88a2520

Browse files
simonvanlaaksimonvanlaak
committed
docs: define end-to-end task flow and rejection paths (#66)
1 parent aee08e0 commit 88a2520

1 file changed

Lines changed: 245 additions & 0 deletions

File tree

‎docs/features/planned/task_flow.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# Task Flows
2+
3+
## Overview
4+
This document is the canonical discussion surface for the full task lifecycle:
5+
- status transitions
6+
- execution and review loops
7+
- rejection handling and restart paths
8+
- follow-up task linkage
9+
10+
It reflects the current implementation and highlights places where behavior can be evolved.
11+
12+
## Lifecycle State Machine
13+
Current transitions (from `ALLOWED_TASK_TRANSITIONS`) are:
14+
- `pending -> in_progress | canceled`
15+
- `in_progress -> completed | blocked`
16+
- `blocked -> in_progress | canceled`
17+
- `completed -> approved | rejected`
18+
- `rejected -> pending | canceled`
19+
- `approved` is terminal
20+
- `canceled` is terminal
21+
22+
```mermaid
23+
stateDiagram-v2
24+
[*] --> pending
25+
pending --> in_progress
26+
pending --> canceled
27+
28+
in_progress --> completed
29+
in_progress --> blocked
30+
31+
blocked --> in_progress
32+
blocked --> canceled
33+
34+
completed --> approved
35+
completed --> rejected
36+
37+
rejected --> pending
38+
rejected --> canceled
39+
40+
approved --> [*]
41+
canceled --> [*]
42+
```
43+
44+
## End-To-End Runtime Flow
45+
```mermaid
46+
flowchart TB
47+
subgraph S1S["System1 Scope (Operations)"]
48+
A1["System1 sets task status to in_progress"]
49+
B["System1 executes"]
50+
C{"System1 result contract"}
51+
D["Task -> completed"]
52+
E["Task -> blocked"]
53+
end
54+
subgraph S3S["System3 Scope (Control)"]
55+
A01["System4 -> System3: InitiativeAssignMessage"]
56+
A02{"Tasks already exist for initiative?"}
57+
A03["System3 creates task records"]
58+
A04["New tasks start as pending"]
59+
A05["System3 picks next existing task"]
60+
A["System3 assigns task"]
61+
NX2{"Next task available?"}
62+
NX3["System3 assigns next task in initiative"]
63+
NX4["No remaining tasks in initiative"]
64+
IR1["System3 -> System4: InitiativeReviewMessage"]
65+
F["System3 task review"]
66+
G{"Task status review-eligible?"}
67+
H["Error: invalid review status for TaskReviewMessage"]
68+
H2["System3 resets task status to pending"]
69+
I{"Blocked or Completed path"}
70+
J0["System3 enters blocked-resolution loop"]
71+
J1{"Blocked-resolution action"}
72+
J3["System3 modifies task"]
73+
J4["System3 sets task status to pending and restarts execution"]
74+
M["Policy judgement cases"]
75+
N{"Outcome"}
76+
O["Task -> approved"]
77+
P1["System3 -> System5: PolicyVagueMessage"]
78+
P3["System5 -> System3: TaskReviewMessage"]
79+
P4["System3 reruns policy review"]
80+
Q["Task -> rejected"]
81+
R{"Rejection handling decision"}
82+
R0["System3 compiles rejection evidence"]
83+
R1["System3 -> System5: remediation request"]
84+
L["Task -> canceled"]
85+
NX1["System3 checks remaining tasks in initiative"]
86+
S1S
87+
end
88+
subgraph S4S["System4 Scope (Intelligence)"]
89+
A0["System4 selects/starts initiative"]
90+
J2["System3 -> System4: request_research_tool"]
91+
IR2["System4 reviews completed initiative and selects next initiative"]
92+
S3S
93+
end
94+
subgraph S5S["System5 Scope (Policy Supervision)"]
95+
S4S
96+
P2["System5 clarifies or updates policy"]
97+
H1["System3 -> System5: InternalErrorMessage"]
98+
R2{"System5 remediation outcome"}
99+
R21["System5 action: update System1 config/skills"]
100+
R22["System5 action: authorize new System1 profile"]
101+
R011["System5 -> User: escalation"]
102+
end
103+
subgraph US["User Scope (External)"]
104+
U1["User notified / manual intervention"]
105+
end
106+
J3 --> J4
107+
A0 --> A01
108+
A01 --> A02
109+
A02 -- no --> A03
110+
A03 --> A04
111+
A04 --> A
112+
A02 -- yes --> A05
113+
A05 --> A
114+
A --> A1
115+
A1 --> B
116+
B --> C
117+
C -- "status=done" --> D
118+
C -- "status=blocked" --> E
119+
D --> F
120+
E --> F
121+
F --> G
122+
G -- no --> H
123+
H --> H1 & H2
124+
H2 --> A
125+
G -- yes --> I
126+
I -- blocked --> J0
127+
J0 --> J1
128+
J1 -- request research --> J2
129+
J2 --> J3
130+
J1 -- System1 not equipped --> R1
131+
J1 -- modify and restart directly --> J3
132+
J4 --> A
133+
J1 -- cancel --> L
134+
I -- completed --> M
135+
M --> N
136+
N -- all satisfied --> O
137+
N -- any vague --> P1
138+
P1 --> P2
139+
P2 --> P3
140+
P3 --> P4
141+
P4 --> F
142+
N -- violated and no vague --> Q
143+
O --> NX1
144+
L --> NX1
145+
NX1 --> NX2
146+
NX2 -- yes --> NX3
147+
NX3 --> A05
148+
NX2 -- no --> NX4
149+
NX4 --> IR1
150+
IR1 --> IR2
151+
IR2 --> A01
152+
Q --> R
153+
R -- Existing System1 with better information/prompt --> J1
154+
R -- System1 change required --> R0
155+
R0 --> R1
156+
R1 --> R2
157+
R2 -- System1 config/skills updated --> R21
158+
R2 -- New System1 profile authorized --> R22
159+
R21 --> J4
160+
R22 --> J4
161+
R2 -- No viable remediation --> R011
162+
R011 --> U1
163+
U1 --> L
164+
```
165+
166+
## Vague Clarification Loop (System3 <-> System5)
167+
When review produces one or more `Vague` cases, the task stays `completed` while
168+
System3 and System5 resolve policy ambiguity and retrigger review.
169+
170+
```mermaid
171+
sequenceDiagram
172+
participant S3 as System3
173+
participant T as Task Record
174+
participant S5 as System5
175+
176+
S3->>T: Task is completed
177+
S3->>S5: PolicyVagueMessage(task_id, policy_id, reasoning)
178+
S5->>S5: Clarify/update ambiguous policy wording
179+
S5->>S3: TaskReviewMessage(task_id, assignee, content)
180+
S3->>S3: Re-run policy judgement
181+
S3->>T: Keep status completed until no Vague cases
182+
```
183+
184+
## Task Creation And Initial Assignment
185+
- Task creation starts from an initiative assignment to System3.
186+
- If no tasks exist for the initiative, System3 creates task records.
187+
- Newly created tasks start in `pending`.
188+
- System3 selects the next task and assigns it to System1.
189+
- On assignment handling, System1 moves the task to `in_progress` before execution.
190+
- After each task ends in `approved` or `canceled`, System3 checks for remaining
191+
tasks in the same initiative and assigns the next one.
192+
- If no tasks remain, System3 sends `InitiativeReviewMessage` to System4 for
193+
initiative review and next-initiative selection.
194+
195+
## Status Semantics
196+
- `pending`: backlog state for an already-defined task, ready to be assigned.
197+
- `in_progress`: task is actively being executed by System1.
198+
- `blocked`: System1 could not complete task with current context/capability.
199+
- `completed`: System1 returned done-result; waiting for/under review outcome.
200+
- `approved`: completed output satisfied policies; terminal success.
201+
- `rejected`: completed output failed policy review; requires rework or cancellation decision.
202+
- `canceled`: terminal stop state when work should not continue on this task.
203+
204+
## Review Contract
205+
- Review-eligible statuses are `completed` and `blocked`.
206+
- If a `TaskReviewMessage` is received for any other status, System3 should
207+
treat it as an internal error, route it to System5, reset task status to
208+
`pending`, and continue with assignment.
209+
- `completed` path:
210+
- all cases `Satisfied` -> `approved`
211+
- any case `Vague` -> remain `completed` and request clarification/review retry
212+
- no vague and at least one `Violated` -> `rejected`
213+
- `blocked` path:
214+
- System3 executes blocked-resolution flow (research/modify/restart)
215+
- if blocked-resolution determines System1 is not equipped, System3 sends
216+
a remediation request to System5 and continues via `System5 remediation outcome`
217+
- task can return to `in_progress` or end as `canceled`
218+
219+
## Rejected Task Flow
220+
After a task is `rejected`, handling should be:
221+
- choose one of two paths:
222+
- existing System1 can solve it with improved information/prompt
223+
- System1 change is required (capability/config/profile remediation via System5)
224+
225+
If replacement work is created, the flow should:
226+
- compile structured rejection evidence from case judgements and execution traces
227+
- request System5 remediation before replacement assignment
228+
- System5 may update current System1 config/skills
229+
- or authorize a better-equipped System1 profile
230+
- only System5 escalates to user when no viable remediation exists
231+
- move the original task to `canceled`
232+
- link replacement task IDs on the original via `follow_up_task_ids`
233+
- route into the task-creation path (`System3 creates task records`)
234+
235+
## Follow-Up Task Linking
236+
- Field: `tasks.follow_up_task_ids` (JSON list of integer task IDs)
237+
- Purpose: lineage between original task and replacement/follow-up tasks
238+
- Expected usage:
239+
- when a rejected task is replaced, append the new task ID(s) to the original
240+
- keep the original task as historical record (`rejected` or `canceled`)
241+
242+
## Discussion Topics
243+
Use this section to align desired behavior before further code changes:
244+
- Should System3 always create follow-up tasks on cancellation, or only for selected rejection scenarios?
245+
- Should initiative progression depend on all tasks being terminal (`approved|canceled`)?

0 commit comments

Comments
 (0)