agents-relay 2.0.232 → 2.0.233
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.
- package/dist/managed-worker-input.js +2 -0
- package/dist/planner.js +11 -5
- package/dist/pool.js +19 -2
- package/dist/reconciler-review.js +9 -6
- package/dist/review-replan.js +39 -0
- package/dist/task-transitions.js +2 -2
- package/dist/workflow/planner-orchestration-v2.js +7 -3
- package/dist/workflow/planner-trigger-v2.js +3 -2
- package/dist/workflow/review-v2.js +2 -2
- package/package.json +1 -1
- package/skills/agents-relay/SKILL.md +4 -0
- package/skills/agents-relay/agents/job-acceptance-reviewer.agent.md +2 -4
- package/skills/agents-relay/agents/planner.agent.md +6 -0
- package/skills/agents-relay/contracts/orchestrator-workflows.md +6 -0
- package/workflow/planner-orchestration.mmd +6 -6
- package/workflow/planner-trigger.mmd +8 -1
- package/workflow/review-lifecycle.mmd +31 -17
|
@@ -47,6 +47,8 @@ export async function managedWorkerInput(job, task, context, mode = 'production'
|
|
|
47
47
|
join(packageRoot, 'skills/agents-relay/contracts/task-recovery-flows.md'),
|
|
48
48
|
join(packageRoot, 'skills/agents-relay/contracts/blocker-job-recovery.md'),
|
|
49
49
|
] : []),
|
|
50
|
+
...(role === 'worker' && context.skills.find(skill => skill.name === 'ponytail')
|
|
51
|
+
? [context.skills.find(skill => skill.name === 'ponytail').path] : []),
|
|
50
52
|
...(role === 'worker' && !task.review && task.agentName !== 'review-chair'
|
|
51
53
|
? [join(packageRoot, 'skills/agents-relay/contracts/worker-self-review.md')] : []),
|
|
52
54
|
],
|
package/dist/planner.js
CHANGED
|
@@ -4,6 +4,7 @@ import { readFile } from 'node:fs/promises';
|
|
|
4
4
|
import { fileURLToPath } from 'node:url';
|
|
5
5
|
import { dirname, join, resolve as resolvePath } from 'node:path';
|
|
6
6
|
import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
|
|
7
|
+
import { reviewNeedsReplan } from './review-replan.js';
|
|
7
8
|
import { unresolvedTask } from './workflow/task-resolution.js';
|
|
8
9
|
import { BUNDLED_AGENTS_ROOT } from './execution-context.js';
|
|
9
10
|
import { agentSourceLayers, resolveAgentMarkdown } from './agent-content-resolver.js';
|
|
@@ -33,6 +34,7 @@ function plannerTrigger(job, manual = false) {
|
|
|
33
34
|
manualPlan: manual && !hasUnblock,
|
|
34
35
|
hasUnblock,
|
|
35
36
|
initialPlan: (job.plans?.length ?? 0) === 0 && !job.tasks.some(task => task.kind === 'planner'),
|
|
37
|
+
reviewRequired: reviewNeedsReplan(job),
|
|
36
38
|
});
|
|
37
39
|
if (!decision.accepted)
|
|
38
40
|
throw new Error('Planner trigger graph rejected plan.requested');
|
|
@@ -59,6 +61,9 @@ function plannerTrigger(job, manual = false) {
|
|
|
59
61
|
}
|
|
60
62
|
if (source === 'initial')
|
|
61
63
|
return { source: 'initial' };
|
|
64
|
+
if (source === 'review')
|
|
65
|
+
return { source: 'review', reviewTaskId: job.review?.taskId ?? undefined,
|
|
66
|
+
reason: 'Final Review requested changes', facts: ['Address persisted Final Review findings.'] };
|
|
62
67
|
return { source: 'continuation' };
|
|
63
68
|
}
|
|
64
69
|
export function plannerRoundNumber(task) {
|
|
@@ -427,6 +432,9 @@ export function plannerInput(context) {
|
|
|
427
432
|
previous_planner_task_id: context.previousPlannerTaskId,
|
|
428
433
|
plan_trigger: context.trigger,
|
|
429
434
|
legacy_change_cycle: context.job.changeCycle,
|
|
435
|
+
review_feedback: context.job.review && (context.trigger?.source === 'review' || context.job.review.outcome === 'changes_required')
|
|
436
|
+
? { task_id: context.job.review.taskId, head_sha: context.job.review.headSha,
|
|
437
|
+
findings: boundedText(JSON.stringify(context.job.review.evidence?.data ?? {}), 6000) } : undefined,
|
|
430
438
|
semantic_task_tree: semanticTaskTree(context.tasks),
|
|
431
439
|
plans: (context.job.plans ?? []).map(plan => ({
|
|
432
440
|
id: plan.id,
|
|
@@ -496,14 +504,12 @@ export async function buildPlannerExecutionPrompt(context, agentFile = DEFAULT_P
|
|
|
496
504
|
throw new Error('Planner execution is missing its durable Plan and execution identity');
|
|
497
505
|
const ctx = context.executionContext, selected = ctx ? await resolveAgentMarkdown('planner', BUNDLED_AGENTS_ROOT, ctx.project.path, ctx.project.sharedRoot, agentSourceLayers(ctx.project.path, ctx.project)) : undefined;
|
|
498
506
|
return buildRelayWorkPrompt({ agentName: 'planner', agentContent: selected?.content ?? await readFile(agentFile, 'utf8'), adapter,
|
|
499
|
-
contracts: [
|
|
500
|
-
join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/contracts/task-job-contract.md'),
|
|
507
|
+
contracts: [join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/contracts/task-job-contract.md'),
|
|
501
508
|
join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/contracts/blocker-job-recovery.md'),
|
|
502
|
-
|
|
509
|
+
...(ctx?.skills.find(skill => skill.name === 'ponytail')?.path ? [ctx.skills.find(skill => skill.name === 'ponytail').path] : [])],
|
|
503
510
|
contexts: ctx?.instructions.filter(item => item.path.endsWith('/AGENTS.md')) ?? [],
|
|
504
511
|
projectPath: ctx?.project.gitRoot ?? ctx?.project.path ?? process.cwd(), providerInstructions: ctx?.providerInstructions?.[adapter], skillPath: join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/SKILL.md'), jobId: context.job.id,
|
|
505
|
-
taskId: context.planExecution.planId, executionId: context.planExecution.executionId,
|
|
506
|
-
});
|
|
512
|
+
taskId: context.planExecution.planId, executionId: context.planExecution.executionId, });
|
|
507
513
|
}
|
|
508
514
|
export class AgentObjectivePlanner {
|
|
509
515
|
command;
|
package/dist/pool.js
CHANGED
|
@@ -5,7 +5,10 @@ import { errorMessage, observability, withObservabilityCorrelation } from './obs
|
|
|
5
5
|
import { jobHasActiveExecution } from './job-execution-slot.js';
|
|
6
6
|
import { pendingPlan } from './planner.js';
|
|
7
7
|
import { decidePlannerOrchestration, plannerOrchestrationFacts } from './workflow/planner-orchestration-v2.js';
|
|
8
|
-
import { pendingTroubleshooterRetries } from './troubleshooter.js';
|
|
8
|
+
import { pendingTroubleshooterTasks, pendingTroubleshooterReopens, pendingTroubleshooterRetries } from './troubleshooter.js';
|
|
9
|
+
import { reviewPlanReady, reviewWorkSettled } from './review-replan.js';
|
|
10
|
+
import { decideReviewLifecycle } from './workflow/review-v2.js';
|
|
11
|
+
import { isFinalReviewAgent } from './final-review-role.js';
|
|
9
12
|
const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
|
|
10
13
|
export function compareJobPriority(a, b) { return RANK[a.priority ?? 'P2'] - RANK[b.priority ?? 'P2'] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
|
|
11
14
|
export function runnableManagedJobs(items) { return items.filter(item => item.job.state === 'ACTIVE' || item.job.projectionRecovery?.status === 'repairing').map(item => item.job).sort(compareJobPriority); }
|
|
@@ -22,8 +25,22 @@ export function needsLifecycleReconciliation(job, now = Date.now()) {
|
|
|
22
25
|
const planning = decidePlannerOrchestration(plannerOrchestrationFacts(job, Boolean(pendingPlan(job))));
|
|
23
26
|
if (planning.accepted && planning.actions.length > 0)
|
|
24
27
|
return true;
|
|
25
|
-
if (
|
|
28
|
+
if (pendingTroubleshooterTasks(job).length || pendingTroubleshooterReopens(job).length || pendingTroubleshooterRetries(job).length)
|
|
26
29
|
return true;
|
|
30
|
+
// Use the canonical Review Graph for restart wake-ups; Reconciler must still verify the live head SHA.
|
|
31
|
+
if (job.state === 'ACTIVE' && job.headSha && job.reviewEnabled !== false) {
|
|
32
|
+
const reviewTasks = job.tasks.filter(task => isFinalReviewAgent(task.agentName) && task.reviewHeadSha === job.headSha);
|
|
33
|
+
const current = job.review?.taskId ? job.tasks.find(task => task.id === job.review?.taskId) : undefined;
|
|
34
|
+
const review = decideReviewLifecycle(job.review?.outcome, 'reconcile', {
|
|
35
|
+
reviewEnabled: true, jobActive: true, headAvailable: true,
|
|
36
|
+
reviewWorkSettled: reviewWorkSettled(job), reviewPlanReady: reviewPlanReady(job),
|
|
37
|
+
noActiveReviewTask: !reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)),
|
|
38
|
+
noApprovedCurrentReview: !reviewTasks.some(task => task.state === 'SUCCEEDED' && job.review?.headSha === job.headSha && job.review?.outcome === 'approved'),
|
|
39
|
+
currentReviewCancelled: current?.reviewHeadSha === job.headSha && current.state === 'CANCELLED',
|
|
40
|
+
});
|
|
41
|
+
if (review.accepted && review.actions.some(action => action.id === 'review.create'))
|
|
42
|
+
return true;
|
|
43
|
+
}
|
|
27
44
|
if (job.tasks.some(task => (task.state === 'QUEUED' && task.executionId === null)
|
|
28
45
|
|| (task.state === 'RUNNING' && task.adapter === 'orchestrator' && task.executionId === null)
|
|
29
46
|
|| (task.state === 'DRAFT' && task.dependencies.length > 0)))
|
|
@@ -3,8 +3,9 @@ import { isFinalReviewAgent, FINAL_REVIEW_AGENT, nextFinalReviewTaskId } from '.
|
|
|
3
3
|
import { normalizeReviewEvidence } from './review-evidence.js';
|
|
4
4
|
import { browserWorkerPool } from './browser-worker-runtime.js';
|
|
5
5
|
import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
|
|
6
|
-
import {
|
|
7
|
-
import {
|
|
6
|
+
import { refreshTaskDependencies, transitionTaskEvent, tryTransitionTaskEvent } from './task-transitions.js';
|
|
7
|
+
import { implementationTasks } from './runtime-status.js';
|
|
8
|
+
import { reviewPlanReady, reviewWorkSettled } from './review-replan.js';
|
|
8
9
|
import { eventFor } from './events.js';
|
|
9
10
|
import { workerCandidates } from './worker-routing.js';
|
|
10
11
|
import { routeExecution } from './execution-routing.js';
|
|
@@ -47,9 +48,9 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
|
|
|
47
48
|
return {
|
|
48
49
|
reviewEnabled: job.reviewEnabled !== false,
|
|
49
50
|
jobActive: job.state === 'ACTIVE' || job.projectionRecovery?.status === 'repairing',
|
|
50
|
-
|
|
51
|
+
reviewWorkSettled: reviewWorkSettled(job),
|
|
51
52
|
headAvailable: Boolean(headSha),
|
|
52
|
-
|
|
53
|
+
reviewPlanReady: reviewPlanReady(job),
|
|
53
54
|
noActiveReviewTask: !reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)),
|
|
54
55
|
currentReviewCancelled: currentReviewTask?.reviewHeadSha === headSha && currentReviewTask.state === 'CANCELLED',
|
|
55
56
|
noApprovedCurrentReview: !reviewTasks.some(task => task.state === 'SUCCEEDED' && job.review?.headSha === headSha && job.review.outcome === 'approved'),
|
|
@@ -120,11 +121,13 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
|
|
|
120
121
|
'Use the selected reviewer agent contract as the authoritative review protocol.',
|
|
121
122
|
'This is a PRE-MERGE artifact approval gate: inspect exact PR head, requirements, tests and genuine blocking defects.',
|
|
122
123
|
'Do not block approval because automatic merge, Job COMPLETED, or post-merge validation has not occurred yet.',
|
|
124
|
+
'All non-review Tasks have terminal outcomes. Examine FAILED and CANCELLED Tasks and their recovery evidence; never approve an unresolved required outcome.',
|
|
125
|
+
'The Final Review is the Job completion check. Persist concrete, owner-attributed findings with a changes-required verdict; Relay starts a new Planner round for revisions.',
|
|
123
126
|
'Do not treat historical failed attempts as current artifact defects; distinguish preserved baseline files from implementation.',
|
|
124
127
|
].join('\n\n');
|
|
125
128
|
const task = createTaskEntity(job, {
|
|
126
129
|
jobId: job.id, id, title: 'Review', kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: FINAL_REVIEW_AGENT,
|
|
127
|
-
parentTaskId: null, dependencies:
|
|
130
|
+
parentTaskId: null, dependencies: [], capabilities: ['review'],
|
|
128
131
|
workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter,
|
|
129
132
|
input,
|
|
130
133
|
output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.routing, continuation: null, continuationDeliveredAt: null,
|
|
@@ -489,7 +492,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
|
|
|
489
492
|
}
|
|
490
493
|
// Review approval records evidence only. The subsequent Graph reconcile
|
|
491
494
|
// drives durable local Git merge delivery and terminalization.
|
|
492
|
-
if (outcome === 'approved')
|
|
495
|
+
if (outcome === 'approved' || outcome === 'changes_required')
|
|
493
496
|
needsReconcile = true;
|
|
494
497
|
return { applied: true, reconcile: needsReconcile, reason: 'review.' + outcome, reconcileMode: needsReconcile ? 'detached' : undefined };
|
|
495
498
|
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { isFinalReviewAgent } from './final-review-role.js';
|
|
2
|
+
import { pendingTroubleshooterTasks, pendingTroubleshooterReopens, pendingTroubleshooterRetries } from './troubleshooter.js';
|
|
3
|
+
const terminal = new Set(['SUCCEEDED', 'FAILED', 'CANCELLED']);
|
|
4
|
+
/** A Final Reviewer reads all terminal outcomes, including failures, not just successes. */
|
|
5
|
+
export function reviewWorkSettled(job) {
|
|
6
|
+
const work = job.tasks.filter(task => task.kind !== 'planner' && !isFinalReviewAgent(task.agentName));
|
|
7
|
+
return work.some(task => task.agentName !== 'troubleshooter')
|
|
8
|
+
&& work.every(task => terminal.has(task.state) && !['active', 'waiting'].includes(task.resolution?.state ?? ''))
|
|
9
|
+
&& !pendingTroubleshooterTasks(job).length
|
|
10
|
+
&& !pendingTroubleshooterReopens(job).length
|
|
11
|
+
&& !pendingTroubleshooterRetries(job).length;
|
|
12
|
+
}
|
|
13
|
+
/** New reviews use Review -> Replan; older persisted targeted revisions remain recoverable. */
|
|
14
|
+
export function reviewNeedsReplan(job) {
|
|
15
|
+
const review = job.review;
|
|
16
|
+
if (!review?.taskId || review.revisionDisposition === 'targeted')
|
|
17
|
+
return false;
|
|
18
|
+
const changes = review.outcome === 'changes_required'
|
|
19
|
+
|| (review.outcome === 'stale' && (job.reviewRevisionRounds ?? []).some(round => round.reviewTaskId === review.taskId && round.status === 'changes_required'));
|
|
20
|
+
return changes && !(job.plans ?? []).some(plan => plan.trigger.source === 'review' && plan.trigger.reviewTaskId === review.taskId && plan.status !== 'FAILED');
|
|
21
|
+
}
|
|
22
|
+
/** An immutable re-review must wait for the finding-driven Plan and its work to settle. */
|
|
23
|
+
export function reviewPlanReady(job) {
|
|
24
|
+
if ((job.plans ?? []).some(plan => plan.status === 'PLANNING'))
|
|
25
|
+
return false;
|
|
26
|
+
const latest = (job.plans ?? []).at(-1);
|
|
27
|
+
const legacy = !latest && job.tasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED');
|
|
28
|
+
if (!legacy && (latest?.status !== 'SUCCEEDED' || !job.tasks.some(task => task.kind !== 'planner' && !isFinalReviewAgent(task.agentName))))
|
|
29
|
+
return false;
|
|
30
|
+
const review = job.review;
|
|
31
|
+
if (!review?.taskId || review.revisionDisposition === 'targeted')
|
|
32
|
+
return true;
|
|
33
|
+
const requiresRevision = review.outcome === 'changes_required'
|
|
34
|
+
|| (review.outcome === 'stale' && (job.reviewRevisionRounds ?? []).some(round => round.reviewTaskId === review.taskId && round.status === 'changes_required'));
|
|
35
|
+
if (!requiresRevision)
|
|
36
|
+
return true;
|
|
37
|
+
return (job.plans ?? []).some(plan => plan.status === 'SUCCEEDED'
|
|
38
|
+
&& plan.trigger.source === 'review' && plan.trigger.reviewTaskId === review.taskId);
|
|
39
|
+
}
|
package/dist/task-transitions.js
CHANGED
|
@@ -5,8 +5,8 @@ export { dependencyReady, detectCycles } from './workflow/task-reconcile.js';
|
|
|
5
5
|
import { observability } from './observability.js';
|
|
6
6
|
export function completionGateSatisfied(job) {
|
|
7
7
|
const latest = [...(job.plans ?? [])].sort((a, b) => a.round - b.round).at(-1);
|
|
8
|
-
const planSatisfied = latest?.status === 'SUCCEEDED' && latest.objectiveStatus === 'satisfied';
|
|
9
|
-
const legacySatisfied = (job.plans?.length ?? 0) === 0 && job.tasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && task.plannerResult?.objective_status === 'satisfied');
|
|
8
|
+
const planSatisfied = latest?.status === 'SUCCEEDED' && (job.reviewEnabled !== false || latest.objectiveStatus === 'satisfied');
|
|
9
|
+
const legacySatisfied = (job.plans?.length ?? 0) === 0 && job.tasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && (job.reviewEnabled !== false || task.plannerResult?.objective_status === 'satisfied'));
|
|
10
10
|
const implementation = implementationTasks(job);
|
|
11
11
|
return (planSatisfied || legacySatisfied) && implementation.length > 0 && implementation.every(task => task.state === 'SUCCEEDED');
|
|
12
12
|
}
|
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
import { readFileSync } from 'node:fs';
|
|
2
2
|
import { GraphRuntime } from './graph-v2.js';
|
|
3
3
|
import { dispatchWorkflowGraph, dispatchWorkflowGraphSync } from './dispatcher.js';
|
|
4
|
+
import { reviewNeedsReplan } from '../review-replan.js';
|
|
4
5
|
import { isEffectivelyBlocked, unblockNeedsNewPlan, unconsumedUnblockTrigger } from '../unblock.js';
|
|
5
6
|
const source = readFileSync(new URL('../../workflow/planner-orchestration.mmd', import.meta.url), 'utf8');
|
|
6
7
|
const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
|
|
7
8
|
export const plannerOrchestrationV2 = new GraphRuntime(source, {
|
|
8
9
|
states: new Set([
|
|
9
10
|
'idle', 'check_legacy_pending', 'check_recover', 'check_plan_failure', 'check_plan_recovery', 'check_plan_recovery_exists', 'check_seed', 'check_planner', 'check_resolution_ownership',
|
|
10
|
-
'check_blocked', 'check_work', 'check_materialized', '
|
|
11
|
+
'check_blocked', 'check_work', 'check_materialized', 'check_review', 'wait', 'recovered', 'created',
|
|
11
12
|
]),
|
|
12
13
|
guards: {
|
|
13
14
|
legacyPlanningPending: boolGuard('legacyPlanningPending'),
|
|
@@ -21,7 +22,7 @@ export const plannerOrchestrationV2 = new GraphRuntime(source, {
|
|
|
21
22
|
noBlockedWork: boolGuard('noBlockedWork'),
|
|
22
23
|
noActiveImplementation: boolGuard('noActiveImplementation'),
|
|
23
24
|
continuationMaterialized: boolGuard('continuationMaterialized'),
|
|
24
|
-
|
|
25
|
+
reviewNeedsReplan: boolGuard('reviewNeedsReplan'),
|
|
25
26
|
},
|
|
26
27
|
actions: {
|
|
27
28
|
'planner.createRecovery': { id: 'planner.createRecovery' },
|
|
@@ -65,6 +66,9 @@ export function plannerOrchestrationFacts(job, recoverablePendingPlan) {
|
|
|
65
66
|
noActiveImplementation: !scopedTasks.some(task => task.kind !== 'planner' && (['QUEUED', 'RUNNING', 'AWAITING_DECISION'].includes(task.state) || (task.state === 'DRAFT' && !task.unblock))),
|
|
66
67
|
resolutionOwnedByTroubleshooter: scopedTasks.some(task => task.kind !== 'planner' && task.resolution?.owner === 'troubleshooter' && ['active', 'waiting'].includes(task.resolution.state)),
|
|
67
68
|
continuationMaterialized: Boolean(unconsumedUnblockTrigger(job)) || !(latestObjective === 'in_progress' && latestId && !job.tasks.some(task => task.kind !== 'planner' && task.planningDecisionId === latestId)),
|
|
68
|
-
|
|
69
|
+
reviewNeedsReplan: reviewNeedsReplan(job) || Boolean(unconsumedUnblockTrigger(job))
|
|
70
|
+
|| (job.reviewEnabled === false && latestObjective !== 'satisfied')
|
|
71
|
+
|| (!scopedPlans.some(plan => plan.status === 'SUCCEEDED')
|
|
72
|
+
&& !scopedTasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED')),
|
|
69
73
|
};
|
|
70
74
|
}
|
|
@@ -4,11 +4,12 @@ import { dispatchWorkflowGraphSync } from './dispatcher.js';
|
|
|
4
4
|
const source = readFileSync(new URL('../../workflow/planner-trigger.mmd', import.meta.url), 'utf8');
|
|
5
5
|
const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
|
|
6
6
|
export const plannerTriggerV2 = new GraphRuntime(source, {
|
|
7
|
-
states: new Set(['idle', 'check_unblock', 'check_initial', 'manual', 'unblock', 'initial', 'continuation']),
|
|
7
|
+
states: new Set(['idle', 'check_unblock', 'check_initial', 'check_review', 'manual', 'unblock', 'initial', 'review', 'continuation']),
|
|
8
8
|
guards: {
|
|
9
9
|
manualPlan: boolGuard('manualPlan'),
|
|
10
10
|
hasUnblock: boolGuard('hasUnblock'),
|
|
11
11
|
initialPlan: boolGuard('initialPlan'),
|
|
12
|
+
reviewRequired: boolGuard('reviewRequired'),
|
|
12
13
|
},
|
|
13
14
|
actions: {},
|
|
14
15
|
events: { 'plan.requested': { id: 'plan.requested' } },
|
|
@@ -16,7 +17,7 @@ export const plannerTriggerV2 = new GraphRuntime(source, {
|
|
|
16
17
|
export function dispatchPlannerTrigger(facts) {
|
|
17
18
|
return dispatchWorkflowGraphSync(plannerTriggerV2, {
|
|
18
19
|
initialState: 'idle', input: { transport: 'event', id: 'plan.requested', payload: {} }, durableFacts: facts, graphName: 'planner-trigger',
|
|
19
|
-
isTransientState: state => state.startsWith('check_'), maxSteps:
|
|
20
|
+
isTransientState: state => state.startsWith('check_'), maxSteps: 5,
|
|
20
21
|
});
|
|
21
22
|
}
|
|
22
23
|
/** Compatibility/testing alias. Production callers use dispatchPlannerTrigger. */
|
|
@@ -9,9 +9,9 @@ export const reviewLifecycleV2 = new GraphRuntime(source, {
|
|
|
9
9
|
reviewEnabled: boolGuard('reviewEnabled'),
|
|
10
10
|
prOpen: boolGuard('prOpen'),
|
|
11
11
|
jobActive: boolGuard('jobActive'),
|
|
12
|
-
|
|
12
|
+
reviewWorkSettled: boolGuard('reviewWorkSettled'),
|
|
13
13
|
headAvailable: boolGuard('headAvailable'),
|
|
14
|
-
|
|
14
|
+
reviewPlanReady: boolGuard('reviewPlanReady'),
|
|
15
15
|
noActiveReviewTask: boolGuard('noActiveReviewTask'),
|
|
16
16
|
currentReviewCancelled: boolGuard('currentReviewCancelled'),
|
|
17
17
|
noApprovedCurrentReview: boolGuard('noApprovedCurrentReview'),
|
package/package.json
CHANGED
|
@@ -7,6 +7,10 @@ description: Use Agents Relay for durable multi-step or multi-agent work that ne
|
|
|
7
7
|
|
|
8
8
|
Agents Relay manages durable Jobs and Tasks. Use its CLI for Job/Task state and actions; do not read its private storage, GitHub projections, or internal service APIs. Prefer completing simple, non-delegated work directly without Relay.
|
|
9
9
|
|
|
10
|
+
## Job Execution Lifecycle (JEL)
|
|
11
|
+
|
|
12
|
+
Explain **JEL** to the user: **Create → Plan → Execute → Final Review → Merge → Completed**. After work/recovery Tasks terminate (SUCCEEDED/FAILED/CANCELLED), Final Review judges completion: PASS merges; CHANGES_REQUIRED persists findings, starts Planner N+1 for minimal fixes, then re-reviews. No automatic post-success Plan. Planner/Workers use discovered **ponytail** Skill (YAGNI, reuse, minimal Tasks); preserve mandatory safeguards.
|
|
13
|
+
|
|
10
14
|
## 1. Choose and start a Job
|
|
11
15
|
|
|
12
16
|
Use Relay when the objective requires independent Tasks, durable progress, retries, review, or cross-session handoffs. Capture the full user objective, decisions, constraints, acceptance checks, and delivery expectations in standalone Markdown before creating a Job. A fresh agent must be able to act without the originating conversation. Put a Mermaid diagram before its explanation only when it clarifies a real workflow.
|
|
@@ -19,11 +19,9 @@ Use `speckit-checklist` only as requirements-quality guidance; do not create
|
|
|
19
19
|
or edit checklists in this read-only Reviewer role. A Spec Kit analysis never
|
|
20
20
|
replaces independent implementation and acceptance-evidence review.
|
|
21
21
|
|
|
22
|
-
##
|
|
22
|
+
## Findings and re-planning ownership
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
**Bootstrap compatibility:** During a managed rollout that is itself introducing `task revise`, the execution-pinned CLI may not yet expose the command. Verify genuine command unavailability via its help/usage output. In that one case, **do not fail a completed review solely because the CLI does not exist**. Publish the canonical `task.completed` verdict `changes-required` with exact `head_sha`, complete actionable `data.findings` (including owner Task IDs where known), and `data.revision_submission: "cli-unavailable"`. Relay owns fallback remediation through its existing Review Graph. Never claim targeted requests were persisted. This fallback is NOT permission to ignore an available CLI's validation error, stale execution, authorization failure or missing evidence; those remain fail-closed.
|
|
24
|
+
Final Review is the sole whole-Job completion check. Examine all terminal Tasks, including FAILED and CANCELLED; these may be historically superseded by verified replacement work, but an unresolved required outcome is **CHANGES_REQUIRED**, never PASS. For each blocking finding, provide its concrete evidence, minimum remediation and responsible original Task ID when known. Put the **complete actionable findings in the `task.completed` verdict** (`data.findings`) at the immutable head SHA. Relay records this verdict in the Job and starts the next Planner round to assign the minimal fix Tasks. Do not call `task revise`, create Tasks, or initiate a separate Planner from this Reviewer; the JEL owns the handoff. Existing persisted targeted-revision requests remain supported by the runtime for backward compatibility.
|
|
27
25
|
|
|
28
26
|
## Review Decision
|
|
29
27
|
|
|
@@ -19,6 +19,12 @@ A CLI rejection (`PLAN_APPLY_VALIDATION_FAILED`) is distinct from a missing appl
|
|
|
19
19
|
|
|
20
20
|
Read current Plan, prior rounds, and Task history through the execution-bound Relay `plan context` CLI response. Do not infer Plan status from GitHub or PR comments. A Plan records its trigger/context (including unblock/change facts), assessment, and generated Task IDs; Plan records are not semantic parents for work Tasks.
|
|
21
21
|
|
|
22
|
+
## Ponytail — keep Plans and Tasks lean
|
|
23
|
+
|
|
24
|
+
Apply the installed `ponytail` Skill (`full`) when resolved in the execution context. Its ladder is mandatory: question if the extra Task is needed (YAGNI), reuse existing helpers/tests, keep scope minimal, and only split by truly independent Agent responsibility. Never add a Task solely to repeat successful checks or because some optional test could exist; do not defer mandatory security or correctness checks. The Final Reviewer—not a second completion Planner—decides whether the Job objective is satisfied.
|
|
25
|
+
|
|
26
|
+
For `plan_trigger.source = review`, consume the persisted Final Reviewer findings and propose **only minimal revision Tasks** that close them, keeping original Task history. Do not create a fresh Final Reviewer Task; Relay creates it when all Tasks are terminal. Never claim earlier failures succeeded or leave an unresolved required failure without a proper resolution.
|
|
27
|
+
|
|
22
28
|
## Planning contract
|
|
23
29
|
|
|
24
30
|
**Plan the whole objective before choosing Task boundaries.**
|
|
@@ -6,6 +6,12 @@ Before `job create`, the orchestrator converts the relevant discussion into a st
|
|
|
6
6
|
|
|
7
7
|
This contract defines orchestrator-owned exception workflows that sit above normal Agents Relay task/job execution.
|
|
8
8
|
|
|
9
|
+
## Review-driven JEL continuation
|
|
10
|
+
|
|
11
|
+
After the Initial Plan materializes its Tasks, Relay waits for **all non-review Tasks to be terminal**, including Troubleshooter recoveries. The Final Reviewer reads every Task result (including FAILED and CANCELLED), the original Job objective, the immutable head and test evidence. An outstanding required failure must be reported as a finding and cannot pass the merge gate. The Final Review is the **completion check**; do not schedule a second Planner merely to ask whether the objective is satisfied.
|
|
12
|
+
|
|
13
|
+
`review.approved` with valid durable evidence permits Relay-owned merge/delivery. `review.changes_required` persists the immutable Reviewer's findings in the Job and initiates a **new Planner round**, whose sole automatic objective is to address those findings with the minimum necessary revision Tasks. Once those Tasks terminate, repeat Final Review. No speculative verification Task or separate completion-check Planner is allowed. Preserve older targeted-revision histories for restart compatibility; new Review rounds should use the Review → Replan path. A real blocker/recovery may use its separate canonical trigger without pretending to be a Review finding.
|
|
14
|
+
|
|
9
15
|
## Normal managed Job start workflow
|
|
10
16
|
|
|
11
17
|
For a normal managed Job, the preferred bootstrap is one command:
|
|
@@ -16,7 +16,7 @@ checkResolution["state: check_resolution_ownership"]
|
|
|
16
16
|
checkBlocked["state: check_blocked"]
|
|
17
17
|
checkWork["state: check_work"]
|
|
18
18
|
checkMaterialized["state: check_materialized"]
|
|
19
|
-
|
|
19
|
+
checkReview["state: check_review"]
|
|
20
20
|
wait["state: wait"]
|
|
21
21
|
recovered["state: recovered"]
|
|
22
22
|
created["state: created"]
|
|
@@ -32,7 +32,7 @@ resolutionOwned["guard: resolutionOwnedByTroubleshooter"]
|
|
|
32
32
|
noBlocked["guard: noBlockedWork"]
|
|
33
33
|
noActiveWork["guard: noActiveImplementation"]
|
|
34
34
|
materialized["guard: continuationMaterialized"]
|
|
35
|
-
|
|
35
|
+
reviewRequired["guard: reviewNeedsReplan"]
|
|
36
36
|
|
|
37
37
|
recoverAction["action: planner.recoverPending"]
|
|
38
38
|
createRecovery["action: planner.createRecovery"]
|
|
@@ -84,9 +84,9 @@ noActiveWork -->|true| checkMaterialized
|
|
|
84
84
|
|
|
85
85
|
checkMaterialized -->|on: planner.reconcile| materialized
|
|
86
86
|
materialized -->|false| wait
|
|
87
|
-
materialized -->|true|
|
|
87
|
+
materialized -->|true| checkReview
|
|
88
88
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
89
|
+
checkReview -->|on: planner.reconcile| reviewRequired
|
|
90
|
+
reviewRequired -->|false| wait
|
|
91
|
+
reviewRequired -->|true| createAction
|
|
92
92
|
createAction --> created
|
|
@@ -7,14 +7,17 @@ flowchart LR
|
|
|
7
7
|
idle["state: idle"]
|
|
8
8
|
checkUnblock["state: check_unblock"]
|
|
9
9
|
checkInitial["state: check_initial"]
|
|
10
|
+
checkReview["state: check_review"]
|
|
10
11
|
manual["state: manual"]
|
|
11
12
|
unblock["state: unblock"]
|
|
12
13
|
initial["state: initial"]
|
|
13
14
|
continuation["state: continuation"]
|
|
15
|
+
review["state: review"]
|
|
14
16
|
|
|
15
17
|
manualGuard["guard: manualPlan"]
|
|
16
18
|
unblockGuard["guard: hasUnblock"]
|
|
17
19
|
initialGuard["guard: initialPlan"]
|
|
20
|
+
reviewGuard["guard: reviewRequired"]
|
|
18
21
|
|
|
19
22
|
idle -->|on: plan.requested| manualGuard
|
|
20
23
|
manualGuard -->|true| manual
|
|
@@ -26,4 +29,8 @@ unblockGuard -->|false| checkInitial
|
|
|
26
29
|
|
|
27
30
|
checkInitial -->|on: plan.requested| initialGuard
|
|
28
31
|
initialGuard -->|true| initial
|
|
29
|
-
initialGuard -->|false|
|
|
32
|
+
initialGuard -->|false| checkReview
|
|
33
|
+
|
|
34
|
+
checkReview -->|on: plan.requested| reviewGuard
|
|
35
|
+
reviewGuard -->|true| review
|
|
36
|
+
reviewGuard -->|false| continuation
|
|
@@ -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. Review is eligible after all non-review Tasks are terminal, regardless of outcome. Approval still requires verified implementation outcomes before merge.
|
|
4
4
|
---
|
|
5
5
|
flowchart LR
|
|
6
6
|
%% relay: initial none
|
|
@@ -15,16 +15,16 @@ stale["state: STALE"]
|
|
|
15
15
|
|
|
16
16
|
reviewEnabledNone["guard: reviewEnabled"]
|
|
17
17
|
jobActiveNone["guard: jobActive"]
|
|
18
|
-
|
|
18
|
+
workTerminalNone["guard: reviewWorkSettled"]
|
|
19
19
|
headAvailableNone["guard: headAvailable"]
|
|
20
|
-
|
|
20
|
+
reviewPlanReadyNone["guard: reviewPlanReady"]
|
|
21
21
|
noActiveReviewNone["guard: noActiveReviewTask"]
|
|
22
22
|
noApprovedReviewNone["guard: noApprovedCurrentReview"]
|
|
23
23
|
reviewEnabledStale["guard: reviewEnabled"]
|
|
24
24
|
jobActiveStale["guard: jobActive"]
|
|
25
|
-
|
|
25
|
+
workTerminalStale["guard: reviewWorkSettled"]
|
|
26
26
|
headAvailableStale["guard: headAvailable"]
|
|
27
|
-
|
|
27
|
+
reviewPlanReadyStale["guard: reviewPlanReady"]
|
|
28
28
|
noActiveReviewStale["guard: noActiveReviewTask"]
|
|
29
29
|
noApprovedReviewStale["guard: noApprovedCurrentReview"]
|
|
30
30
|
pendingRetry["guard: noActiveReviewTask"]
|
|
@@ -56,14 +56,14 @@ mergeStarted["action: review.requestMerge"]
|
|
|
56
56
|
none -->|on: reconcile| reviewEnabledNone
|
|
57
57
|
reviewEnabledNone -->|true| jobActiveNone
|
|
58
58
|
reviewEnabledNone -->|false| none
|
|
59
|
-
jobActiveNone -->|true|
|
|
59
|
+
jobActiveNone -->|true| workTerminalNone
|
|
60
60
|
jobActiveNone -->|false| none
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
headAvailableNone -->|true|
|
|
61
|
+
workTerminalNone -->|true| headAvailableNone
|
|
62
|
+
workTerminalNone -->|false| none
|
|
63
|
+
headAvailableNone -->|true| reviewPlanReadyNone
|
|
64
64
|
headAvailableNone -->|false| none
|
|
65
|
-
|
|
66
|
-
|
|
65
|
+
reviewPlanReadyNone -->|true| noActiveReviewNone
|
|
66
|
+
reviewPlanReadyNone -->|false| none
|
|
67
67
|
noActiveReviewNone -->|true| noApprovedReviewNone
|
|
68
68
|
noActiveReviewNone -->|false| none
|
|
69
69
|
noApprovedReviewNone -->|true| createNone
|
|
@@ -73,14 +73,14 @@ createNone --> pending
|
|
|
73
73
|
stale -->|on: reconcile| reviewEnabledStale
|
|
74
74
|
reviewEnabledStale -->|true| jobActiveStale
|
|
75
75
|
reviewEnabledStale -->|false| stale
|
|
76
|
-
jobActiveStale -->|true|
|
|
76
|
+
jobActiveStale -->|true| workTerminalStale
|
|
77
77
|
jobActiveStale -->|false| stale
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
headAvailableStale -->|true|
|
|
78
|
+
workTerminalStale -->|true| headAvailableStale
|
|
79
|
+
workTerminalStale -->|false| stale
|
|
80
|
+
headAvailableStale -->|true| reviewPlanReadyStale
|
|
81
81
|
headAvailableStale -->|false| stale
|
|
82
|
-
|
|
83
|
-
|
|
82
|
+
reviewPlanReadyStale -->|true| noActiveReviewStale
|
|
83
|
+
reviewPlanReadyStale -->|false| stale
|
|
84
84
|
noActiveReviewStale -->|true| noApprovedReviewStale
|
|
85
85
|
noActiveReviewStale -->|false| stale
|
|
86
86
|
noApprovedReviewStale -->|true| createStale
|
|
@@ -151,6 +151,20 @@ limitOwnerResolution --> changes
|
|
|
151
151
|
prepareRereview --> stale
|
|
152
152
|
changes -->|on: head.changed| cancelChanges
|
|
153
153
|
cancelChanges --> stale
|
|
154
|
+
%% Only a Review-finding-driven Plan with settled revision Tasks opens re-review.
|
|
155
|
+
reviewChangesReady["guard: reviewPlanReady"]
|
|
156
|
+
reviewChangesSettled["guard: reviewWorkSettled"]
|
|
157
|
+
reviewChangesInactive["guard: noActiveReviewTask"]
|
|
158
|
+
createChanges["action: review.create"]
|
|
159
|
+
changes -->|on: reconcile| reviewChangesReady
|
|
160
|
+
reviewChangesReady -->|true| reviewChangesSettled
|
|
161
|
+
reviewChangesReady -->|false| changes
|
|
162
|
+
reviewChangesSettled -->|true| reviewChangesInactive
|
|
163
|
+
reviewChangesSettled -->|false| changes
|
|
164
|
+
reviewChangesInactive -->|true| createChanges
|
|
165
|
+
reviewChangesInactive -->|false| changes
|
|
166
|
+
createChanges --> pending
|
|
167
|
+
|
|
154
168
|
blocked -->|on: review.retry| reviewUnblocked
|
|
155
169
|
reviewUnblocked -->|true| pending
|
|
156
170
|
reviewUnblocked -->|false| blocked
|