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.
@@ -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 (pendingTroubleshooterRetries(job).length > 0)
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 { completionGateSatisfied, refreshTaskDependencies, transitionTaskEvent, tryTransitionTaskEvent } from './task-transitions.js';
7
- import { implementationComplete, implementationTasks } from './runtime-status.js';
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
- implementationComplete: implementationComplete(job),
51
+ reviewWorkSettled: reviewWorkSettled(job),
51
52
  headAvailable: Boolean(headSha),
52
- completionGateSatisfied: completionGateSatisfied(job),
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: reviewGateTasks.map(item => item.id), capabilities: ['review'],
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
+ }
@@ -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', 'check_objective', 'wait', 'recovered', 'created',
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
- objectiveUnsatisfied: boolGuard('objectiveUnsatisfied'),
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
- objectiveUnsatisfied: latestObjective !== 'satisfied',
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: 4,
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
- implementationComplete: boolGuard('implementationComplete'),
12
+ reviewWorkSettled: boolGuard('reviewWorkSettled'),
13
13
  headAvailable: boolGuard('headAvailable'),
14
- completionGateSatisfied: boolGuard('completionGateSatisfied'),
14
+ reviewPlanReady: boolGuard('reviewPlanReady'),
15
15
  noActiveReviewTask: boolGuard('noActiveReviewTask'),
16
16
  currentReviewCancelled: boolGuard('currentReviewCancelled'),
17
17
  noApprovedCurrentReview: boolGuard('noApprovedCurrentReview'),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.232",
3
+ "version": "2.0.233",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -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
- ## Targeted revision ownership
22
+ ## Findings and re-planning ownership
23
23
 
24
- For actionable findings, identify the original responsible durable Task ID. When the **execution-pinned Relay CLI supports** `task revise`, submit each owner's findings with a stable request ID, the exact active Reviewer execution identity, immutable head SHA and findings file; check the durable receipt. An ambiguous owner must be reported, not guessed. Do not edit artifacts, invoke Planner for every issue, or claim CLI submission completed a revision.
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
- checkObjective["state: check_objective"]
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
- unsatisfied["guard: objectiveUnsatisfied"]
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| checkObjective
87
+ materialized -->|true| checkReview
88
88
 
89
- checkObjective -->|on: planner.reconcile| unsatisfied
90
- unsatisfied -->|false| wait
91
- unsatisfied -->|true| createAction
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| continuation
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. The implementationComplete guard ignores only durably resolved cancel_supersede cancellations and failed Tasks with a valid superseded classification targeting succeeded work.
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
- implementationCompleteNone["guard: implementationComplete"]
18
+ workTerminalNone["guard: reviewWorkSettled"]
19
19
  headAvailableNone["guard: headAvailable"]
20
- completionGateNone["guard: completionGateSatisfied"]
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
- implementationCompleteStale["guard: implementationComplete"]
25
+ workTerminalStale["guard: reviewWorkSettled"]
26
26
  headAvailableStale["guard: headAvailable"]
27
- completionGateStale["guard: completionGateSatisfied"]
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| implementationCompleteNone
59
+ jobActiveNone -->|true| workTerminalNone
60
60
  jobActiveNone -->|false| none
61
- implementationCompleteNone -->|true| headAvailableNone
62
- implementationCompleteNone -->|false| none
63
- headAvailableNone -->|true| completionGateNone
61
+ workTerminalNone -->|true| headAvailableNone
62
+ workTerminalNone -->|false| none
63
+ headAvailableNone -->|true| reviewPlanReadyNone
64
64
  headAvailableNone -->|false| none
65
- completionGateNone -->|true| noActiveReviewNone
66
- completionGateNone -->|false| none
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| implementationCompleteStale
76
+ jobActiveStale -->|true| workTerminalStale
77
77
  jobActiveStale -->|false| stale
78
- implementationCompleteStale -->|true| headAvailableStale
79
- implementationCompleteStale -->|false| stale
80
- headAvailableStale -->|true| completionGateStale
78
+ workTerminalStale -->|true| headAvailableStale
79
+ workTerminalStale -->|false| stale
80
+ headAvailableStale -->|true| reviewPlanReadyStale
81
81
  headAvailableStale -->|false| stale
82
- completionGateStale -->|true| noActiveReviewStale
83
- completionGateStale -->|false| stale
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