agents-relay 2.0.208 → 2.0.210

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/dist/adapters.js +2 -1
  2. package/dist/agent-shortcut.js +113 -41
  3. package/dist/browser-worker-runtime.js +7 -2
  4. package/dist/chatgpt-platform-fallback.js +30 -0
  5. package/dist/cli-help.js +10 -4
  6. package/dist/cli-prompt.js +2 -1
  7. package/dist/cli-revision.js +49 -0
  8. package/dist/cli-shortcut-local.js +49 -0
  9. package/dist/cli-shortcut.js +81 -19
  10. package/dist/cli-worker-task.js +15 -0
  11. package/dist/cli.js +19 -5
  12. package/dist/dashboard-html.js +2 -2
  13. package/dist/dependency-revision-execution.js +152 -0
  14. package/dist/dependency-validity.js +17 -0
  15. package/dist/final-review-role.js +17 -0
  16. package/dist/force-restate-validation.js +6 -3
  17. package/dist/job-execution-slot.js +4 -1
  18. package/dist/job-pr-number-migration.js +2 -1
  19. package/dist/managed-worker-input.js +2 -1
  20. package/dist/model-routing.js +8 -0
  21. package/dist/planner-agent-roles.js +18 -0
  22. package/dist/planner-runtime.js +7 -1
  23. package/dist/planner-task-ids.js +1 -0
  24. package/dist/planner.js +11 -6
  25. package/dist/reconciler-review.js +110 -109
  26. package/dist/reconciler-runtime.js +56 -58
  27. package/dist/reconciler.js +33 -13
  28. package/dist/relay-job-snapshot-reads.js +5 -2
  29. package/dist/relay-store.js +2 -0
  30. package/dist/relay-workflow-operations.js +1 -1
  31. package/dist/relayd-control.js +31 -0
  32. package/dist/review-evidence.js +44 -0
  33. package/dist/review-generation-fence.js +2 -1
  34. package/dist/review-revision-execution.js +86 -0
  35. package/dist/review-revision-merge.js +15 -0
  36. package/dist/review-revision-model.js +191 -0
  37. package/dist/review-revision-policy.js +49 -0
  38. package/dist/review-revision-settlement.js +54 -0
  39. package/dist/review-revision-stale.js +57 -0
  40. package/dist/reviewer-thread.js +41 -1
  41. package/dist/runtime-status.js +24 -8
  42. package/dist/shortcut-node-worker.js +128 -0
  43. package/dist/shortcut-stage-contract.js +50 -0
  44. package/dist/shortcut-worker-runner.js +73 -0
  45. package/dist/single-job-task-control.js +1 -1
  46. package/dist/task-actions.js +4 -13
  47. package/dist/task-context.js +3 -2
  48. package/dist/task-inactivity-watchdog.js +7 -0
  49. package/dist/terminal-event-recovery.js +13 -0
  50. package/dist/worker-failure-recovery.js +90 -0
  51. package/dist/workflow/contracts.js +4 -0
  52. package/dist/workflow/definitions-v2.js +2 -0
  53. package/dist/workflow/dependency-revision-v2.js +16 -0
  54. package/dist/workflow/entity-creation.js +2 -0
  55. package/dist/workflow/review-v2.js +6 -2
  56. package/dist/workflow/revision-v2.js +32 -0
  57. package/dist/workflow/runtime.js +30 -0
  58. package/dist/workflow/task-reconcile.js +3 -0
  59. package/dist/workflow/task-resolution.js +1 -4
  60. package/package.json +4 -3
  61. package/skills/agents-relay/agents/job-acceptance-reviewer.agent.md +41 -0
  62. package/skills/agents-relay/agents/planner.agent.md +18 -5
  63. package/skills/agents-relay/agents/reviewer.agent.md +2 -0
  64. package/skills/agents-relay/contracts/event-contract.md +7 -0
  65. package/skills/agents-relay/contracts/orchestrator-workflows.md +6 -0
  66. package/skills/agents-relay/contracts/task-job-contract.md +10 -0
  67. package/workflow/dependency-revision.mmd +30 -0
  68. package/workflow/force-restate-validation.mmd +1 -1
  69. package/workflow/review-lifecycle.mmd +41 -10
  70. package/workflow/revision-lifecycle.mmd +68 -0
  71. package/workflow/task-lifecycle.mmd +13 -12
  72. package/workflow/task-resolution.mmd +1 -6
@@ -27,15 +27,18 @@ For every non-satisfied objective:
27
27
 
28
28
  1. Reconstruct the end-to-end execution flow from the current durable state to objective completion.
29
29
  2. Express that flow as a compact Mermaid graph in `assessment`.
30
- 3. Mark the points in that graph that deserve durable Task boundaries.
30
+ 3. Mark only the distinct Agent responsibilities and genuine independent approval/recovery boundaries in that graph.
31
31
  4. Create only the next useful executable Task batch from those boundaries.
32
32
 
33
33
  ### Objective decomposition and convergence
34
34
 
35
- - **Never bundle independently testable acceptance layers into one giant Task.** Break objectives into separately verifiable deliverables (for example, contract tests, real-provider compliance, L1 Graph branches, L2 role evidence, and L3 production-ingress and recovery evidence). Give each Task concrete acceptance checks and an observable output.
36
- - Split a large Task when its remaining work spans distinct implementation areas, independently testable failure paths, or more than one meaningful review/recovery cycle. Put shared prerequisites in earlier Tasks and express true dependencies explicitly; independent work may run in parallel.
35
+ - **Agent-responsibility-first:** for each Plan round create at most ONE new durable Task per effective Agent role. Group design, implementation, test layers, verification and self-review into that Agent's Task internal checklist. Missing or blank `agentName` is the same `implementation` role; it does not evade deduplication.
36
+ - Split Tasks only for genuinely distinct Agent ownership (such as an independent specialist, real human approval boundary, or recovery); technical subsystems and independently testable layers are not independently owned Agents by themselves. A later Plan round may reuse an Agent role for a real revision/recovery.
37
+ - The Relay Final Review gate auto-creates `job-acceptance-reviewer`. Do not emit it as a Planner Task. The independent Final Review validates the entire Job objective, immutable head and Design Principles; worker self-review remains inside implementation work.
38
+ - Recovery/revision work belongs beneath its original artifact Task tree; a future Plan round may assign the same implementation role again when justified by new evidence.
39
+ - Group implementation, deterministic tests, and self-review under the responsible Agent Task when they share one owner; do not require a live-service test before that service can be published.
37
40
  - For a failed Task with repeated deterministic acceptance gaps, do not reissue the identical broad assignment. Identify the *missing acceptance cases*, create focused same-Job repair Tasks with valid `same_job_dependency` resolutions, and specify how their evidence unblocks the original Task. Preserve the original failed Task and failure history.
38
- - For event-driven workflows, separate basic ingress/persistence checks from L3 full-path lifecycle and recovery scenarios. Require negative-path, multi-failure recovery and no-false-completion evidence before claiming full objective coverage.
41
+ - For event-driven workflows, require deterministic ingress/persistence, negative-path, restart and no-false-completion evidence before publishing. Do not elevate tests that require the newly published live runtime/provider/device to release-blocking Tasks merely because they are independently observable.
39
42
  - In `assessment`, show the entire remaining objective as a dependency graph, clearly distinguishing already proven work, the executable batch, subsequent verification, and Relay-owned review/merge. Never report overall `satisfied` merely because one batch has passed.
40
43
 
41
44
 
@@ -52,6 +55,16 @@ If an intermediate result does not need that independent lifecycle, keep it insi
52
55
 
53
56
  Keep sibling Tasks at a comparable abstraction level. Do not mix a whole product milestone with tiny implementation steps as peers.
54
57
 
58
+ ### Publish-first live acceptance
59
+
60
+ Classify each acceptance check **before planning Tasks**: pre-publish (verifiable in source/build/isolated runtime), live-only (requires newly published service, real account/provider/device or live traffic), or mandatory pre-release gate (security, data integrity, legal compliance or explicit approval).
61
+
62
+ - Complete pre-publish checks and independent immutable-head Final Review before Relay merge/delivery. **Never defer mandatory pre-release gates.** Do not create merge/deploy Tasks or infer delivery from model output.
63
+ - **Do not create a blocking pre-publish Task**, human escalation or repeated Planner round for live-only verification unavailable before publication. Record `NOT_RUN` or `PENDING_POST_PUBLISH` (never PASS), including residual risk; this does not constitute failed implementation.
64
+ - In the durable Plan `assessment`, provide a **post-publish acceptance handoff**: scenario, target release/version, evidence gap, risk, owner (`orchestrator` or `user`), prerequisites, and receipt-triggered follow-up. After actual publication, the orchestrator can run supported live tests or set up an authorized scheduled watcher/separate Job; otherwise request manual verification. **Never claim a watcher/reminder exists until it is actually created.**
65
+ - When only authorized live-only checks remain, pre-publish evidence and mandatory gates are complete, return `objective_status: "satisfied"` with `next_tasks: []` to reach Relay Final Review; preserve the handoff and `NOT_RUN` status. The code Job may complete, but live acceptance remains pending in the separate post-publish process.
66
+ - Preserve historical failed/deferred Tasks. Resolve them via supported cancellation/supersession and durable evidence/authorization, never silent deletion, invented success, or repeated E2E work. Diagnose version-mismatched Plan admission as a runtime issue instead of creating another live-only Task. After publication, defects require separate recovery/rollback work, not reopening a completed Job.
67
+
55
68
  ### Architecture Lens
56
69
 
57
70
  When the resolved project context exposes a canonical design-principles
@@ -118,7 +131,7 @@ If evidence is absent or execution outcome is unknown, disposition that historic
118
131
 
119
132
  - Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.
120
133
  - When a Task depends on mutable repository or product state, distinguish a frozen evidence target from the current execution head. A SHA may freeze that Task's own review/source evidence, but do not copy an upstream SHA into a dependent release, deploy, publication, or other follow-on Task unless the objective explicitly requires that same frozen target. After dependencies complete, downstream Tasks must resolve and verify the current durable Job/PR head before acting.
121
- - When fresh UI, browser, store, runtime, or visual evidence is material to the Task outcome, say so explicitly in the Task input and require evidence from the real current state. Existing screenshots, prepared assets, or prior observations are not substitutes for fresh evidence unless the objective explicitly allows reuse.
134
+ - When fresh UI, browser, store, runtime, or visual evidence is material to a **pre-publish** Task, require current authentic evidence. If it is possible only after deployment, use the post-publish acceptance handoff above; existing screenshots or prior observations never substitute for live evidence.
122
135
  - When a Job needs multi-perspective review, use the visible `review-chair` agent or an Agent Graph to select specialist roles dynamically. Keep specialist Tasks as independent siblings against the same immutable target/version, and leave worker/model/provider routing to Relay.
123
136
  - A Task describes what an agent must accomplish; never emit a shell command as a worker Task.
124
137
  - Use dependencies only for Task IDs inside the current Job, and only when execution order actually matters. Never encode cross-Job or cross-repository dependencies in `dependencies`.
@@ -13,6 +13,8 @@ Review exactly the immutable target/version specified by the Review Task. Do not
13
13
 
14
14
  Reconstruct all material acceptance requirements from the durable Job objective and Task, then evaluate each with direct evidence. Check correctness, completeness, provenance, quality, regressions, explicit approvals and externally observable outcomes where applicable. Missing evidence is not PASS. If validation cannot complete, report task.failed. Keep review independent of implementation work.
15
15
 
16
+ For **publish-first live acceptance**, distinguish checks verifiable before release from checks that genuinely require the newly published runtime, real device, or external provider. A properly classified and handed-off live-only check is **NOT_RUN**, never PASS, but must not by itself cause a `task.failed` or `changes-required` verdict before publication. Verify that required pre-release quality/security/compliance/approval gates passed, that the future live test has a named owner and executable post-publish follow-up, and that remaining risks are disclosed. Missing mandatory pre-release evidence or a fabricated post-publish handoff remains blocking. Do not approve an unreviewed source/head or perform deployment yourself.
17
+
16
18
  For spec-oriented delivery, select read-only `speckit-analyze` to check
17
19
  `spec.md`, `plan.md`, and `tasks.md` consistency when those artifacts exist.
18
20
  Use `speckit-checklist` only as requirements-quality guidance; do not create
@@ -35,6 +35,13 @@ Every Implementation, Reviewer, and Troubleshooter execution publishes `task.sta
35
35
 
36
36
  A Reviewer must **not** publish unstructured `task.completed`: missing verdict or immutable head is invalid. Relay validates the Reviewer verdict; read the accepted review outcome through the matching Relay CLI.
37
37
 
38
+ ### Targeted review findings and original Task revisions
39
+
40
+ The automatically created `job-acceptance-reviewer` (historical `reviewer` records remain valid) owns the integrated Job acceptance gate, not the Implementation Agent's self-review. For blocking findings with an unambiguous original succeeded Task owner, its *active execution* calls `agents-relay task revise --repo ... --id ... --task-id ORIGINAL --review-task-id REVIEW --execution-id REVIEW_EXEC --head-sha REVIEW_SHA --request-id STABLE_ID --findings-file PATH`. A findings file is a JSON array of identified `{id, summary, evidence?}` items. Relay rejects stale execution/head, unsupported owner or conflicting request ID, and transactionally appends `review.feedback` comments and one targeted child per owner/Review round. The CLI receipt is evidence of request persistence, **not** repair or completion. The Reviewer then publishes its single correlated `task.completed` verdict `changes-required` with matching `findings` and immutable `head_sha`; the Review Graph authorizes scheduling only when all blocking findings have durable owners. No direct `task.blocked`/`task.unblocked` event is emitted by the agent.
41
+
42
+ A fix child reports its **own** correlated completion after verified repair. Downstream `dependencyValidity` policy is `order-only` by default, or explicitly `revalidate`/`rerun` per declared input. All changed upstream generations must settle before a fan-in consumer can verify or rerun. Relay derives successful revision lineage from durable Task results, then creates another fresh immutable-head Job Acceptance Review. A partially submitted message, unverified terminal, historical result or stale source SHA does not count as a fix or approval.
43
+
44
+
38
45
  ## Troubleshooter human escalation
39
46
 
40
47
  Only a real user action merits escalation. Troubleshooter invokes the Relay escalation operation, specifying the required action, resolution condition, and diagnostic context. Relay durably records the human action and blocks **the Troubleshooter Task**, leaving the original failed Task `FAILED`. This is a Relay state transition, not a third agent terminal event.
@@ -54,4 +54,10 @@ For a managed Job, Relay owns Job completion. A satisfied Plan, successful imple
54
54
 
55
55
  Post-merge publication and deployment activity is separate from Job lifecycle. Events or evidence such as `package.published`, published version metadata, service restart, and deployment verification may be attached after the Job is already `COMPLETED`; they must not hold the Job open, reopen it, or redefine completion. If post-merge deployment needs remediation, record that as separate deployment/recovery work rather than mutating the completed implementation Job lifecycle.
56
56
 
57
+ ## Live acceptance after publication
58
+
59
+ Use **publish-first live acceptance** when verification genuinely requires a running published build, real provider/account, device, or runtime. The Planner completes available build/isolated tests and mandatory pre-merge gates, then hands off unrun live-only scenarios as explicit `NOT_RUN` / `PENDING_POST_PUBLISH` evidence, not successful tests. Do not let a live-only check become a pre-merge Task or repeated Plan round just because its environment is unavailable. Independent Final Review and normal Relay merge/delivery remain mandatory.
60
+
61
+ After a **verified** publication/deployment receipt, the orchestrator uses the handoff to run supported live checks and monitor health if capable and authorized. A persistent watcher requires a real scheduled automation/monitoring mechanism; never promise background execution without creating one. If the scenario requires a user action or unsupported device/account, provide a concrete manual-acceptance checklist and request/reminder rather than holding the completed code Job open. Record exact version, test owner, evidence and final status separately; failures trigger a new post-release fix/rollback workflow. Security, legal, data-loss and explicit pre-release approval requirements are **not** deferrable under this policy.
62
+
57
63
  If a PR closes without merge, check the Job state through Relay CLI; do not infer a successful completion.
@@ -22,12 +22,20 @@ Use `job create` with standalone objective Markdown, or `job adopt` for an exist
22
22
  Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.
23
23
  Task producers choose semantic task properties such as objective, dependencies, worker requirements, priority, and `storySize`. They do not normally choose an adapter, provider/model, or raw timeout milliseconds.
24
24
 
25
+ Before Task decomposition, distinguish tests achievable before publishing from live-only acceptance requiring the newly deployed runtime. The latter must be handed off for post-publish orchestrator or manual verification with an explicit `NOT_RUN`/`PENDING_POST_PUBLISH` status; do not create release-blocking Tasks for an unavailable future environment. Do not defer mandatory pre-publish security, compliance, or human approval gates. The authoritative policy and follow-up contract are in `agents/planner.agent.md` and `contracts/orchestrator-workflows.md`.
26
+
25
27
  `Task.timeoutMs` is the inactivity window. Only an accepted `task.started` or newer `task.progress` event for the exact current execution resets it; duplicate, stale, and out-of-order progress does not.
26
28
 
29
+ ### Planner role-first Task granularity
30
+
31
+ New Plan rounds assign at most one newly authored Task per effective Agent role. Group design, coding, Graph changes, CLI, testing, self-review, and internal phases in the same implementation worker Task instead of decomposing by technical subsystem. A missing/blank `agentName` is normalized to `implementation` for duplicate checks. PLAN_APPLY_VALIDATION_FAILED rejects duplicate effective roles atomically, with corrective detail. Distinct Agents may own truly independent work, and a later Plan round can reuse the same role for genuine revision/recovery. The automatic SHA-bound Final Review gate creates `job-acceptance-reviewer` itself; Planner does not emit that agent as an ordinary Task. Legacy review agents and historical Plans are read compatibly.
32
+
27
33
  ### Planning graph and semantic Task tree
28
34
 
29
35
  The planning graph expresses execution flow. The Task tree expresses semantic ownership. `dependencies` answer which durable outcomes must succeed before a Task can run; `parentTaskId` answers which durable artifact or milestone owns the Task. These are independent relationships.
30
36
 
37
+ Each dependency edge may also declare `dependencyValidity`: `order-only` (the default), `revalidate` (check downstream evidence against the latest successful upstream result), or `rerun` (produce downstream verification again). Set this policy explicitly when later upstream revisions can change the validity of downstream evidence. It is execution evidence policy; it does not change Task ownership or normal DAG ordering.
38
+
31
39
  A later Planner round must inspect the existing semantic tree and attach review, revision, re-review, validation rerun, release correction, or recovery work to the existing artifact subtree. Independent milestones remain roots. `plan-N` records are provenance/history and must never be semantic parents. Existing terminal Tasks remain immutable historical evidence and may continue to own later work.
32
40
 
33
41
  ### Task input vs result
@@ -66,6 +74,8 @@ This is a worker result-content contract, not a requirement for dedicated `rootC
66
74
 
67
75
  Keep these concepts distinct: observation is not root cause; hypothesis is not root cause; requested approach is not implemented solution; implementation is not validation.
68
76
 
77
+ Reviewers apply the same publish-first evidence boundary: they must not call a post-publish live-only test PASS, but may approve pre-publish implementation when all mandatory pre-release gates pass and deferred scenarios have an explicit owner, evidence gap, risk and actionable handoff. Missing mandatory pre-publish evidence still blocks approval. No reviewer may authorize an unverified merge or treat an unevaluated provider receipt as success.
78
+
69
79
  ### Worker self-review before success
70
80
 
71
81
  Every artifact-changing implementation worker follows the shared [worker self-review loop](worker-self-review.md), regardless of its selected agent name or runtime adapter. Complete the implement → self-review → fix → re-review cycle until the latest full review has no actionable findings. Include review rounds, fixes, validation evidence, and the clean-review result in the durable Task result. The worker's self-review never substitutes for an independent final Reviewer, human approval, or Relay's Graph-owned lifecycle gates.
@@ -0,0 +1,30 @@
1
+ ---
2
+ title: Dependency Revision
3
+ description: Authorizes a semantic downstream verification or rerun based on explicit edge policy and a settled dependency evidence vector.
4
+ ---
5
+ flowchart LR
6
+ %% relay: initial none
7
+ none["state: NONE"]
8
+ proposed["state: PROPOSED"]
9
+ verified["state: VERIFIED"]
10
+ stale["state: STALE"]
11
+ markStale["action: dependencyRevision.markStale"]
12
+ upstreamChanged["guard: upstreamEvidenceChanged"]
13
+ explicitPolicy["guard: explicitValidityPolicy"]
14
+ allSettled["guard: allInputsSettled"]
15
+ notDuplicated["guard: notAlreadyRecorded"]
16
+ rerunRequired["guard: rerunRequired"]
17
+ createRerun["action: dependencyRevision.createRerun"]
18
+ createRevalidation["action: dependencyRevision.createRevalidation"]
19
+ none -->|on: dependency.reconcile| upstreamChanged
20
+ upstreamChanged -->|true| explicitPolicy
21
+ explicitPolicy -->|true| allSettled
22
+ allSettled -->|true| notDuplicated
23
+ notDuplicated -->|true| rerunRequired
24
+ rerunRequired -->|true| createRerun
25
+ rerunRequired -->|false| createRevalidation
26
+ createRerun --> proposed
27
+ createRevalidation --> proposed
28
+ proposed -->|on: dependency.verified| verified
29
+ proposed -->|on: dependency.stale| markStale
30
+ markStale --> stale
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: Plan Apply Convergence Validation
3
- description: Validates hypothetical Plan application and, for Force Restate, historical consistency before the atomic commit action.
3
+ description: Validates Plan objective completion and, for Force Restate, historical consistency before the atomic commit action. Explicitly resolved cancel_supersede Tasks and failed Tasks classified superseded by a succeeded target are historical evidence, not unfinished implementation.
4
4
  ---
5
5
  flowchart LR
6
6
  %% relay: initial idle
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: Review Lifecycle
3
- description: Manages review creation, immutable verdicts, changes-required, and re-review.
3
+ description: Manages review creation, immutable verdicts, changes-required, and re-review. The implementationComplete guard ignores only durably resolved cancel_supersede cancellations and failed Tasks with a valid superseded classification targeting succeeded work.
4
4
  ---
5
5
  flowchart LR
6
6
  %% relay: initial none
@@ -41,9 +41,15 @@ cancelApproved["action: review.cancelStale"]
41
41
  cancelChanges["action: review.cancelStale"]
42
42
  cancelBlocked["action: review.cancelStale"]
43
43
  reviewUnblocked["guard: reviewUnblocked"]
44
- fixPending["action: review.createFix"]
45
- fixStarted["action: review.createFix"]
46
- fixChanges["action: review.createFix"]
44
+ targetedPending["guard: targetedRevisionRequestsReady"]
45
+ targetedStarted["guard: targetedRevisionRequestsReady"]
46
+ targetedChanges["guard: targetedRevisionRequestsReady"]
47
+ recordTargetedPending["action: review.awaitTargetedRevisions"]
48
+ recordTargetedStarted["action: review.awaitTargetedRevisions"]
49
+ recordTargetedChanges["action: review.awaitTargetedRevisions"]
50
+ ownerPending["action: review.requireOwnerResolution"]
51
+ ownerStarted["action: review.requireOwnerResolution"]
52
+ ownerChanges["action: review.requireOwnerResolution"]
47
53
  mergePending["action: review.requestMerge"]
48
54
  mergeStarted["action: review.requestMerge"]
49
55
 
@@ -96,8 +102,11 @@ pending -->|on: review.approved| autoMergePending
96
102
  autoMergePending -->|true| mergePending
97
103
  mergePending --> approved
98
104
  autoMergePending -->|false| approved
99
- pending -->|on: review.changes_required| fixPending
100
- fixPending --> changes
105
+ pending -->|on: review.changes_required| targetedPending
106
+ targetedPending -->|true| recordTargetedPending
107
+ targetedPending -->|false| ownerPending
108
+ recordTargetedPending --> changes
109
+ ownerPending --> changes
101
110
 
102
111
  %% A failed Reviewer execution may recover with a new Execution ID while
103
112
  %% the Review lifecycle remains STARTED. This is a legal re-start event;
@@ -107,10 +116,16 @@ started -->|on: review.approved| autoMergeStarted
107
116
  autoMergeStarted -->|true| mergeStarted
108
117
  mergeStarted --> approved
109
118
  autoMergeStarted -->|false| approved
110
- started -->|on: review.changes_required| fixStarted
111
- fixStarted --> changes
112
- changes -->|on: review.changes_required| fixChanges
113
- fixChanges --> changes
119
+ started -->|on: review.changes_required| targetedStarted
120
+ targetedStarted -->|true| recordTargetedStarted
121
+ targetedStarted -->|false| ownerStarted
122
+ recordTargetedStarted --> changes
123
+ ownerStarted --> changes
124
+ changes -->|on: review.changes_required| targetedChanges
125
+ targetedChanges -->|true| recordTargetedChanges
126
+ targetedChanges -->|false| ownerChanges
127
+ recordTargetedChanges --> changes
128
+ ownerChanges --> changes
114
129
 
115
130
  pending -->|on: head.changed| cancelPending
116
131
  cancelPending --> stale
@@ -118,6 +133,22 @@ started -->|on: head.changed| cancelStarted
118
133
  cancelStarted --> stale
119
134
  approved -->|on: head.changed| cancelApproved
120
135
  cancelApproved --> stale
136
+ changes -->|on: revision.settled| targetedVerified
137
+ %% Only the Review Graph selects re-review; settlement is proven by correlated
138
+ %% child terminal evidence and explicit revision request provenance.
139
+ targetedVerified["guard: targetedRevisionsVerified"]
140
+ reviewRoundAllowed["guard: reviewRoundWithinLimit"]
141
+ reviewNoProgressAllowed["guard: reviewNoProgressWithinLimit"]
142
+ prepareRereview["action: review.prepareRereview"]
143
+ limitOwnerResolution["action: review.requireOwnerResolution"]
144
+ targetedVerified -->|true| reviewRoundAllowed
145
+ reviewRoundAllowed -->|true| reviewNoProgressAllowed
146
+ reviewNoProgressAllowed -->|true| prepareRereview
147
+ reviewNoProgressAllowed -->|false| limitOwnerResolution
148
+ %% Exhausted re-review rounds require explicit owner/Planner recovery.
149
+ reviewRoundAllowed -->|false| limitOwnerResolution
150
+ limitOwnerResolution --> changes
151
+ prepareRereview --> stale
121
152
  changes -->|on: head.changed| cancelChanges
122
153
  cancelChanges --> stale
123
154
  blocked -->|on: review.retry| reviewUnblocked
@@ -0,0 +1,68 @@
1
+ ---
2
+ title: Revision Lifecycle
3
+ description: Authorizes immutable-head targeted feedback and child revision lifecycle; Task graph continues to own worker execution.
4
+ ---
5
+ flowchart LR
6
+ %% relay: initial none
7
+ none["state: NONE"]
8
+ requested["state: REQUESTED"]
9
+ queued["state: QUEUED"]
10
+ running["state: RUNNING"]
11
+ verified["state: VERIFIED"]
12
+ failed["state: FAILED"]
13
+ stale["state: STALE"]
14
+ reviewerAuthorized["guard: reviewerAuthorized"]
15
+ sameHead["guard: reviewHeadCurrent"]
16
+ ownerEligible["guard: originalTaskSucceeded"]
17
+ recordRequest["action: revision.recordRequest"]
18
+ recordQueue["action: revision.queueTask"]
19
+ recordVerified["action: revision.recordVerified"]
20
+ recordFailed["action: revision.recordFailed"]
21
+ retryQueued["guard: taskRetryQueued"]
22
+ retryQueue["action: revision.queueTask"]
23
+ markStaleRequested["action: revision.markStale"]
24
+ markStaleQueued["action: revision.markStale"]
25
+ markStaleRunning["action: revision.markStale"]
26
+ markStaleFailed["action: revision.markStale"]
27
+ verdictReady["guard: changesRequiredRecorded"]
28
+ none -->|on: revision.submit| reviewerAuthorized
29
+ reviewerAuthorized -->|true| sameHead
30
+ reviewerAuthorized -->|false| none
31
+ sameHead -->|true| ownerEligible
32
+ sameHead -->|false| none
33
+ ownerEligible -->|true| recordRequest
34
+ ownerEligible -->|false| none
35
+ recordRequest --> requested
36
+ %% Duplicate submissions are idempotent only when the durable request payload
37
+ %% matches. The reducer rejects a conflicting payload for the same request ID.
38
+ requested -->|on: revision.submit| requested
39
+ requested -->|on: revision.queue| verdictReady
40
+ verdictReady -->|true| recordQueue
41
+ verdictReady -->|false| requested
42
+ recordQueue --> queued
43
+ queued -->|on: revision.started| running
44
+ running -->|on: revision.verified| recordVerified
45
+ recordVerified --> verified
46
+ running -->|on: revision.failed| recordFailed
47
+ recordFailed --> failed
48
+ %% A failed/uncertain revision can resume only after Relay has authoritatively
49
+ %% requeued the SAME child through its recovery Graph.
50
+ failed -->|on: revision.retry| retryQueued
51
+ running -->|on: revision.retry| retryQueued
52
+ retryQueued -->|true| retryQueue
53
+ retryQueue --> queued
54
+ requested -->|on: review.head_changed| markStaleRequested
55
+ markStaleRequested --> stale
56
+ queued -->|on: review.head_changed| markStaleQueued
57
+ markStaleQueued --> stale
58
+ running -->|on: review.head_changed| markStaleRunning
59
+ markStaleRunning --> stale
60
+ failed -->|on: review.head_changed| markStaleFailed
61
+ markStaleFailed --> stale
62
+
63
+ %% A restarted reviewer execution is a new immutable review generation even
64
+ %% when the reviewed SHA is unchanged; old pending feedback cannot hold the gate.
65
+ requested -->|on: review.execution_changed| markStaleRequested
66
+ queued -->|on: review.execution_changed| markStaleQueued
67
+ running -->|on: review.execution_changed| markStaleRunning
68
+ failed -->|on: review.execution_changed| markStaleFailed
@@ -24,9 +24,8 @@ depUnsat["guard: dependenciesUnsatisfied"]
24
24
  runnable["guard: runnable"]
25
25
  dispatchable["guard: dispatchable"]
26
26
  shortcutExecution["guard: shortcutExecution"]
27
- shortcutFallback["guard: shortcutFallback"]
28
27
  shortcutHasGraph["guard: shortcutHasGraph"]
29
- shortcutEffectsSafe["guard: shortcutEffectsSafe"]
28
+ shortcutDirectInvocation["guard: shortcutDirectInvocation"]
30
29
  recoverStart["guard: recoverableExecution"]
31
30
  recoverComplete["guard: recoverableExecution"]
32
31
  recoverBlocked["guard: recoverableExecution"]
@@ -37,11 +36,12 @@ recoveryReopenClearError["action: mutation.clearError"]
37
36
  recoveryReopenClearReason["action: mutation.clearFailureReason"]
38
37
  recoveryReopenClearLease["action: mutation.clearLease"]
39
38
  recoveryReopenClearExecution["action: mutation.clearExecution"]
40
- shortcutWorkerFallback["action: mutation.markShortcutWorkerFallback"]
41
39
  shortcutRecoveryRequired["action: mutation.markShortcutRecoveryRequired"]
42
40
 
43
41
  plannerRetryAvailable["guard: retryAvailable"]
44
42
  platformFallbackSafe["guard: platformFallbackSafe"]
43
+ noStartFallbackAllowed["guard: noStartFallbackAllowed"]
44
+ prepareNoStartFallback["action: mutation.prepareNoStartFallback"]
45
45
  preparePlatformFallback["action: mutation.preparePlatformFallback"]
46
46
  plannerUnavailableMark["action: mutation.markPlannerUnavailable"]
47
47
  orphanFailMark["action: mutation.markUnknownOutcome"]
@@ -113,12 +113,12 @@ runnable -->|true| reconcileQueuedClearError
113
113
  reconcileQueuedClearError --> reconcileQueuedClearReason
114
114
  reconcileQueuedClearReason --> queued
115
115
  queued -->|on: dispatch| shortcutExecution
116
- shortcutExecution -->|true| shortcutFallback
116
+ shortcutExecution -->|true| shortcutHasGraph
117
117
  shortcutExecution -->|false| dispatchable
118
- shortcutFallback -->|true| dispatchable
119
- shortcutFallback -->|false| shortcutHasGraph
120
- shortcutHasGraph -->|true| shortcutLaunch
121
- shortcutHasGraph -->|false| dispatchable
118
+ shortcutHasGraph -->|true| shortcutDirectInvocation
119
+ shortcutDirectInvocation -->|true| shortcutLaunch
120
+ shortcutDirectInvocation -->|false| queued
121
+ shortcutHasGraph -->|false| queued
122
122
  dispatchable -->|true| dispatchLaunch
123
123
  dispatchLaunch --> queued
124
124
  shortcutLaunch --> queued
@@ -146,6 +146,10 @@ queued -->|on: effect.launchShortcut.failed| failed
146
146
  queued -->|on: watchdog.failed| failed
147
147
  queued -->|on: worker.delivery_failed| failed
148
148
  queued -->|on: worker.start_ack_failed| failed
149
+ queued -->|on: worker.no_start_failed| noStartFallbackAllowed
150
+ noStartFallbackAllowed -->|true| prepareNoStartFallback
151
+ prepareNoStartFallback --> queued
152
+ noStartFallbackAllowed -->|false| failed
149
153
  queued -->|on: worker.platform_failure| platformFallbackSafe
150
154
  platformFallbackSafe -->|true| preparePlatformFallback
151
155
  preparePlatformFallback --> queued
@@ -193,10 +197,7 @@ running -->|on: task.completed| completeClearError
193
197
  completeClearError --> completeClearReason
194
198
  completeClearReason --> succeeded
195
199
  running -->|on: task.failed| failed
196
- running -->|on: shortcut.failed| shortcutEffectsSafe
197
- shortcutEffectsSafe -->|true| shortcutWorkerFallback
198
- shortcutWorkerFallback --> failed
199
- shortcutEffectsSafe -->|false| shortcutRecoveryRequired
200
+ running -->|on: shortcut.failed| shortcutRecoveryRequired
200
201
  shortcutRecoveryRequired --> failed
201
202
  running -->|on: worker.platform_failure| runningPlatformFailureQuarantine
202
203
  runningPlatformFailureQuarantine["action: mutation.quarantinePlatformFailure"]
@@ -9,7 +9,6 @@ checkOwner["state: check_owner"]
9
9
  checkPath["state: check_path"]
10
10
  checkFreshExecution["state: check_fresh_execution"]
11
11
  activeRecovery["action: resolution.activateRecovery"]
12
- shortcutWorkerFallback["action: resolution.activateShortcutWorkerFallback"]
13
12
  sameJob["action: resolution.attachSameJobDependency"]
14
13
  blockerJob["action: resolution.registerBlockerDependency"]
15
14
  escalate["action: resolution.createEscalationGate"]
@@ -19,7 +18,6 @@ rejected["state: rejected"]
19
18
  recoveryOwner["guard: recoveryOwnerAvailable"]
20
19
  plannerOwner["guard: plannerOwnerAvailable"]
21
20
  exact["guard: exactOriginalRetry"]
22
- shortcutInterrupted["guard: shortcutInterrupted"]
23
21
  same["guard: sameJobDependency"]
24
22
  fresh["guard: freshRecoveryExecution"]
25
23
  blocker["guard: blockerJobDependency"]
@@ -42,9 +40,7 @@ checkPath -->|on: resolution.propose| fresh
42
40
  fresh -->|true| checkFreshExecution
43
41
  fresh -->|false| rejected
44
42
  checkFreshExecution -->|on: resolution.propose| exact
45
- exact -->|true| shortcutInterrupted
46
- shortcutInterrupted -->|true| shortcutWorkerFallback
47
- shortcutInterrupted -->|false| activeRecovery
43
+ exact -->|true| activeRecovery
48
44
  exact -->|false| same
49
45
  same -->|true| sameJob
50
46
  same -->|false| blocker
@@ -55,7 +51,6 @@ gate -->|false| obsoleteGuard
55
51
  obsoleteGuard -->|true| obsolete
56
52
  obsoleteGuard -->|false| rejected
57
53
  activeRecovery -->|to: resolved| resolved
58
- shortcutWorkerFallback -->|to: resolved| resolved
59
54
  sameJob -->|to: resolved| resolved
60
55
  blockerJob -->|to: resolved| resolved
61
56
  escalate -->|to: resolved| resolved