@yeaft/webchat-agent 1.0.360 → 1.0.362

package/local-runtime/version.json

@@ -1 +1 @@
-{"version":"1.0.360"}
+{"version":"1.0.362"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.360",
+  "version": "1.0.362",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/engine.js

@@ -2158,8 +2158,12 @@ export class Engine {
     const executionOrigin = inboundEnvelope?.msg?.meta?.injectedBy === 'route_forward'
       ? 'route_forward'
       : null;
-    const queryTurnId = randomUUID();
-    this.#currentQueryTurnId = vpTurnId || queryTurnId;
+    // The bridge-provided VP turn id is also persisted on assistant messages and
+    // is therefore the identity the UI sends back when opening turn debug. Keep
+    // the engine event/trace id identical; a second random id makes the trace
+    // impossible to retrieve from a rendered assistant turn.
+    const queryTurnId = vpTurnId || randomUUID();
+    this.#currentQueryTurnId = queryTurnId;
     // Bind the live query scope before tools can register async work. The
     // constructor's Session id is only guaranteed for bridge-owned engines;
     // standalone/CLI callers pass it per query.

package/yeaft/web-bridge.js

@@ -1035,18 +1035,19 @@ async function waitForRoutePromises(msgId) {
 }
 
 /**
- * Drop the cached coordinator + router for a group AND abort/clear any
- * in-flight VP turns belonging to it. Call this from every CRUD handler
- * that mutates the group's roster, meta, or lifecycle state on disk —
- * the cached coord holds a closed `sessionHandle`, so without invalidation
- * later route_forward / ingest calls would read zombie meta (stale
- * roster, pre-rename announcement, kicked members still routable).
+ * Drop the cached coordinator + router for a Session. Metadata changes must
+ * not abort in-flight work: a rename, announcement sync, or default-VP update
+ * can race any provider request, and the running coordinator already owns a
+ * consistent snapshot for that turn. Future turns rebuild from disk.
+ *
+ * Destructive lifecycle operations opt into runtime teardown.
  *
  * Idempotent — safe to call when no entry exists.
  */
-function invalidateGroupContext(sessionId) {
+function invalidateGroupContext(sessionId, { abortRuntime = false } = {}) {
   if (!sessionId) return;
   sessionContexts.delete(sessionId);
+  if (!abortRuntime) return;
   const prefix = `${sessionId}::`;
   for (const [k, ctrl] of vpAborts) {
     if (!k.startsWith(prefix)) continue;
@@ -1066,7 +1067,7 @@ function invalidateGroupContext(sessionId) {
     if (k.startsWith(prefix)) vpThreads.delete(k);
   }
   // Reap per-(group,vp) TodoWrite snapshots for this group so a
-  // deleted/renamed group doesn't pin a stale checklist forever.
+  // deleted/archived group doesn't pin a stale checklist forever.
   for (const k of vpCurrentTodos.keys()) {
     if (k.startsWith(prefix)) vpCurrentTodos.delete(k);
   }
@@ -3438,7 +3439,7 @@ export function handleYeaftArchiveSession(msg) {
     const yeaftDir = ctx.CONFIG?.yeaftDir;
     const result = archiveSession(yeaftDir, sessionId);
     projectContextBySession.delete(sessionId);
-    invalidateGroupContext(sessionId);
+    invalidateGroupContext(sessionId, { abortRuntime: true });
     sendSessionCrudResult({
       op: 'archive',
       requestId,
@@ -3478,7 +3479,7 @@ export function handleYeaftDeleteSession(msg) {
     // turns for the deleted group. Engines for the deleted group are
     // also dropped — unlike rename/announcement updates, the group is
     // gone for good and there's nothing to preserve.
-    invalidateGroupContext(sessionId);
+    invalidateGroupContext(sessionId, { abortRuntime: true });
     const prefix = `${sessionId}::`;
     for (const k of Array.from(vpEngines.keys())) {
       if (k.startsWith(prefix)) {

package/yeaft/work-center/controller.js

@@ -380,6 +380,10 @@ export class WorkflowController {
           actions: this.store.getWorkItemDetail(activeWorkItem.id).actions,
           proposal: result.planProposal,
           availableVpIds: this.listAvailableVpIds?.(),
+          reviewAction: activeAction.type === 'review'
+            && result.reviewDecision === 'changes_requested'
+            ? activeAction
+            : null,
         });
       } catch (error) {
         result.outcome = 'failed';
@@ -546,7 +550,7 @@ export class WorkflowController {
               eventData: { reason: result.replanRequest.reason },
             };
           }
-          if (action.type === 'review' && result.reviewDecision === 'changes_requested') {
+          if (action.type === 'review' && result.reviewDecision === 'changes_requested' && !planProposal) {
             const targetStage = plannedWorkItem.workflowSnapshot.stages
               .find(stage => stage.id === action.changesRequestedStageId);
             if (!targetStage) throw new Error('Work Center review return target is missing');

package/yeaft/work-center/coordinator.js

@@ -12,6 +12,7 @@ import { normalizeContractPatch } from './completion-contract.js';
 import { applyCoordinatorReplan } from './plan-mutation.js';
 import { buildWorkItemAttachmentContext } from './attachments.js';
 import { sanitizeDiagnosticText } from './debug-projection.js';
+import { generatedActionGraphRules } from './workflow.js';
 
 const COORDINATOR_MAX_REPLY_CHARS = 8_000;
 const COORDINATOR_MAX_INSTRUCTION_CHARS = 8_000;
@@ -181,8 +182,8 @@ Decision rules:
 - answer: use for explanation or status questions. Do not include contractPatch, guidance, or actions.
 - guide_actions: use only when the contract and graph stay valid. guidance must contain one or more {"stageId":"existing unfinished stage id","instruction":"specific next instruction"}. Do not include contractPatch or actions.
 - replan: use when the WorkItem contract or unfinished topology changes. contractPatch may be null or contain title, goal, and/or acceptanceCriteria. actions must be the COMPLETE desired unfinished Action graph after this decision; omit completed Actions. Each Action requires id, name, type, objective, approach, expectedOutcome, capability, candidateVpIds, assignmentReason, dependsOnActionIds, workspaceMode, and may include separateFromActionTypes, changesRequestedActionId, maxAttempts. Dependencies may reference immutable completed stage ids or earlier Actions in this actions array.
+- Replan graph contract: ${generatedActionGraphRules()}
 - request_human: use only during automatic failure recovery, and only when no safe retry, guidance, or replan can be decided without human information. Set question to the exact information or decision required. Do not include contractPatch, guidance, or actions.
-- Every replan must keep exactly one final acceptance gate: normally one deliver Action, or one terminal review when no delivery operation is required. It must be the unique graph sink and transitively depend on all other Actions.
 - Action references are stage ids, never internal database Action ids.
 - Stage ids in the snapshot may be bounded aliases. Echo them exactly; the runtime resolves them to durable identities.
 - Never return destructive cancellation. Tell the user to use the explicit cancel control instead.`;
@@ -313,8 +314,8 @@ function permanentRecoveryDecision(error, language) {
 function coordinatorDecisionError(error, language) {
   const diagnostic = sanitizeDiagnosticText(error?.message || String(error || ''), 2_000);
   const wrapped = new Error(coordinatorLanguage(language) === 'zh'
-    ? 'Work Center Coordinator 未能生成有效回复。你的消息已经保留，请重试。'
-    : 'Work Center Coordinator could not produce a valid response. Your message was preserved; try again.');
+    ? 'Work Center Coordinator 生成的操作方案未通过校验。你的消息已经保留；重试会重新生成方案。'
+    : 'The Work Center Coordinator proposal did not pass validation. Your message was preserved; retry to generate a new proposal.');
   wrapped.coordinatorClassified = true;
   wrapped.coordinatorRetryable = false;
   wrapped.coordinatorPhase = 'decision';
@@ -411,9 +412,12 @@ export function normalizeCoordinatorResponse(value, detail, options = {}) {
     };
   }
   const contractPatch = normalizeContractPatch(source.contractPatch);
-  if (!Array.isArray(source.actions) || source.actions.length < 1 || source.actions.length > 8) {
+  if (!Array.isArray(source.actions)) {
     throw new Error('Work Center Coordinator replan requires the complete unfinished Action graph');
   }
+  if (source.actions.length < 1 || source.actions.length > 8) {
+    throw new Error('Work Center Coordinator replan requires between 1 and 8 unfinished Actions');
+  }
   return {
     reply,
     decision: {

package/yeaft/work-center/plan-mutation.js

@@ -42,6 +42,46 @@ function planActionFromStage(stage) {
   };
 }
 
+function dependencyAncestors(stageId, stagesById) {
+  const ancestors = new Set();
+  const visit = id => {
+    if (ancestors.has(id)) return;
+    ancestors.add(id);
+    for (const dependencyId of stagesById.get(id)?.dependsOnStageIds || []) visit(dependencyId);
+  };
+  for (const dependencyId of stagesById.get(stageId)?.dependsOnStageIds || []) visit(dependencyId);
+  return ancestors;
+}
+
+function validateReviewRemediationGate(workflowSnapshot, reviewAction, addedIds) {
+  if (reviewAction?.type !== 'review') return;
+  const stages = (workflowSnapshot.stages || []).filter(stage => stage.type !== 'triage');
+  const byId = new Map(stages.map(stage => [stage.id, stage]));
+  const freshReviews = stages.filter(stage => (
+    stage.type === 'review'
+    && addedIds.has(stage.id)
+    && addedIds.has(stage.changesRequestedStageId)
+    && dependencyAncestors(stage.id, byId).has(reviewAction.stageId)
+  ));
+  const gate = stages.find(stage => stage.type === 'deliver')
+    || stages.find(stage => stage.type === 'review'
+      && !stages.some(candidate => (candidate.dependsOnStageIds || []).includes(stage.id)));
+  const gateAncestors = gate ? dependencyAncestors(gate.id, byId) : new Set();
+  const gatedReviews = freshReviews.filter(review => (
+    gate?.id === review.id || gateAncestors.has(review.id)
+  ));
+  const addedWork = stages.filter(stage => (
+    addedIds.has(stage.id) && stage.type !== 'review' && stage.type !== 'deliver'
+  ));
+  const uncovered = addedWork.filter(stage => (
+    !gatedReviews.some(review => dependencyAncestors(review.id, byId).has(stage.id))
+  ));
+  if (addedWork.length === 0 || gatedReviews.length === 0 || uncovered.length > 0) {
+    const suffix = uncovered.length > 0 ? `; uncovered Actions: ${uncovered.map(stage => stage.id).join(', ')}` : '';
+    throw new Error(`Work Center changes_requested additive plan requires remediation and a fresh review covering every added Action before delivery${suffix}`);
+  }
+}
+
 function stableTopologicalActions(actions) {
   const byId = new Map(actions.map((action, index) => [action.id, { action, index }]));
   const incoming = new Map(actions.map(action => [action.id, 0]));
@@ -112,7 +152,9 @@ function validateDependencyPatches(actions, patches, addedIds) {
   return normalized;
 }
 
-export function applyAdditivePlanProposal({ workItem, actions, proposal, availableVpIds = null }) {
+export function applyAdditivePlanProposal({
+  workItem, actions, proposal, availableVpIds = null, reviewAction = null,
+}) {
   if (workItem.workflowSnapshot?.executionMode !== 'graph') {
     throw new Error('Work Center additive planning requires graph execution');
   }
@@ -144,12 +186,14 @@ export function applyAdditivePlanProposal({ workItem, actions, proposal, availab
         raw.dependsOnActionIds,
         `Action "${id}" dependencies`,
       ),
-      changesRequestedActionId: hasReturnTarget
-        ? canonicalExplicitActionId(
-          raw.changesRequestedActionId,
-          `Action "${id}" review target`,
-        )
-        : undefined,
+      ...(hasReturnTarget
+        ? {
+            changesRequestedActionId: canonicalExplicitActionId(
+              raw.changesRequestedActionId,
+              `Action "${id}" review target`,
+            ),
+          }
+        : {}),
     };
   });
   const dependencyPatches = validateDependencyPatches(actions, proposal.dependencyPatches, addedIds);
@@ -192,6 +236,7 @@ export function applyAdditivePlanProposal({ workItem, actions, proposal, availab
     availableVpIds,
     maxActions: MAX_WORK_ITEM_ACTIONS,
   });
+  validateReviewRemediationGate(workflowSnapshot, reviewAction, addedIds);
   const addedStages = workflowSnapshot.stages.filter(stage => addedIds.has(stage.id));
   return {
     proposalId,
@@ -253,9 +298,14 @@ export function applyCoordinatorReplan({ workItem, actions, proposal, availableV
       ...raw,
       id,
       dependsOnActionIds,
-      changesRequestedActionId: Object.hasOwn(raw, 'changesRequestedActionId')
-        ? canonicalExplicitActionId(raw.changesRequestedActionId, `Coordinator Action "${id}" review target`)
-        : undefined,
+      ...(Object.hasOwn(raw, 'changesRequestedActionId')
+        ? {
+            changesRequestedActionId: canonicalExplicitActionId(
+              raw.changesRequestedActionId,
+              `Coordinator Action "${id}" review target`,
+            ),
+          }
+        : {}),
     };
   });
 
@@ -363,9 +413,14 @@ export function applyReplanMutation({ workItem, action, actions, proposal, avail
       ...raw,
       id,
       dependsOnActionIds: canonicalExplicitActionIds(raw.dependsOnActionIds, `Action "${id}" dependencies`),
-      changesRequestedActionId: Object.hasOwn(raw, 'changesRequestedActionId')
-        ? canonicalExplicitActionId(raw.changesRequestedActionId, `Action "${id}" review target`)
-        : undefined,
+      ...(Object.hasOwn(raw, 'changesRequestedActionId')
+        ? {
+            changesRequestedActionId: canonicalExplicitActionId(
+              raw.changesRequestedActionId,
+              `Action "${id}" review target`,
+            ),
+          }
+        : {}),
     };
   };
   const retainedInputs = retained.map(entry => canonicalFuture(entry.input, entry.action.stageId));

package/yeaft/work-center/runner.js

@@ -413,14 +413,32 @@ export function createSubmitWorkItemPlanTool({
   });
 }
 
-function terminalPlanningFields() {
+function terminalPlanningFields(options = {}) {
   return {
     summary: { type: 'string', minLength: 1, maxLength: 2_000 },
     evidence: { type: 'array', minItems: 1, maxItems: 20, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
     acceptanceChecks: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['criterion', 'status', 'evidence'], properties: { criterion: { type: 'string' }, status: { type: 'string', enum: ['passed', 'deferred', 'not_applicable'] }, evidence: { type: 'string', minLength: 1, maxLength: 1_000 } } } },
+    ...(options.review === true ? {
+      reviewDecision: { type: 'string', const: 'changes_requested' },
+    } : {}),
   };
 }
 
+function reviewPlanningRequirements(action) {
+  return action?.type === 'review' ? ['reviewDecision'] : [];
+}
+
+function assertReviewPlanningDecision(input, action) {
+  if (action?.type !== 'review') return;
+  if (input?.reviewDecision !== 'changes_requested') {
+    throw new Error('Review planning controls require reviewDecision "changes_requested"');
+  }
+}
+
+function reviewPlanningResult(input, action) {
+  return action?.type === 'review' ? { reviewDecision: input.reviewDecision } : {};
+}
+
 function plannedActionSchema(vpIds, { requireCandidates = true } = {}) {
   const required = ['id', 'name', 'type', 'objective', 'approach', 'expectedOutcome', 'dependsOnActionIds', 'workspaceMode'];
   if (requireCandidates) required.push('candidateVpIds', 'assignmentReason');
@@ -445,11 +463,15 @@ export function createProposeWorkItemActionsTool({
     : '';
   return defineTool({
     name: 'ProposeWorkItemActions',
-    description: `Propose an additive change to the current WorkItem DAG. It is applied only if this Action completes and its Run lease plus basePlanRevision remain valid. Use stable stageId values in dependsOnActionIds, changesRequestedActionId, and dependencyPatches[].addDependsOnActionIds. The only internal id field is dependencyPatches[].actionId, which must use the displayed internalActionId of an eligible ready attempt=0 target.${currentIdentity} Existing Actions: ${existing.map(action => `stageId=${action.stageId} (internalActionId=${action.id}, ${action.status}, attempt ${action.attempt})`).join('; ')}. Available VPs: ${vpCatalog.map(vp => `${vp.id} (${vp.role || vp.area || 'VP'})`).join('; ')}. Only add new Actions and optionally add dependencies to attempt=0 ready Actions. This tool validates the complete additive DAG immediately; if validation fails, correct the proposal in the same turn.`,
+    description: `Propose an additive change to the current WorkItem DAG. It is applied only if this Action completes and its Run lease plus basePlanRevision remain valid. Use stable stageId values in dependsOnActionIds, changesRequestedActionId, and dependencyPatches[].addDependsOnActionIds. The only internal id field is dependencyPatches[].actionId, which must use the displayed internalActionId of an eligible ready attempt=0 target.${currentIdentity} Existing Actions: ${existing.map(action => `stageId=${action.stageId} (internalActionId=${action.id}, ${action.status}, attempt ${action.attempt})`).join('; ')}. Available VPs: ${vpCatalog.map(vp => `${vp.id} (${vp.role || vp.area || 'VP'})`).join('; ')}. Only add new Actions and optionally add dependencies to attempt=0 ready Actions. A Review submitting changes_requested must add remediation followed by a fresh Review and make delivery depend on that fresh approval gate; otherwise request a replan. This tool validates the complete additive DAG immediately; if validation fails, correct the proposal in the same turn.`,
     parameters: { type: 'object', additionalProperties: false,
-      required: ['summary', 'evidence', 'acceptanceChecks', 'proposalId', 'basePlanRevision', 'actions'],
+      required: [
+        'summary', 'evidence', 'acceptanceChecks', 'proposalId', 'basePlanRevision', 'actions',
+        ...reviewPlanningRequirements(currentAction),
+      ],
       properties: {
-        ...terminalPlanningFields(), proposalId: { type: 'string', minLength: 1, maxLength: 128 },
+        ...terminalPlanningFields({ review: currentAction?.type === 'review' }),
+        proposalId: { type: 'string', minLength: 1, maxLength: 128 },
         basePlanRevision: { type: 'integer', const: workItem.planRevision },
         actions: { type: 'array', minItems: 1, maxItems: 8, items: plannedActionSchema(vpIds) },
         dependencyPatches: { type: 'array', maxItems: 8, items: { type: 'object', additionalProperties: false, required: ['actionId', 'addDependsOnActionIds'], properties: { actionId: { type: 'string', enum: existing.filter(action => action.status === 'ready' && action.attempt === 0).map(action => action.id) }, addDependsOnActionIds: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string' } } } } },
@@ -457,14 +479,22 @@ export function createProposeWorkItemActionsTool({
     async execute(input, ctx = {}) {
       if (!isRunActive()) throw new Error('Work Center Run is no longer active');
       if (collector.value) throw new Error('A WorkItem plan mutation was already submitted for this Run');
+      assertReviewPlanningDecision(input, currentAction);
       applyAdditivePlanProposal({
         workItem,
         actions,
         proposal: input,
         availableVpIds: vpIds,
+        reviewAction: currentAction,
       });
       if (!isRunActive()) throw new Error('Work Center Run is no longer active');
-      collector.value = { kind: 'expand', input: structuredClone(input) };
+      collector.value = {
+        kind: 'expand',
+        input: {
+          ...structuredClone(input),
+          ...reviewPlanningResult(input, currentAction),
+        },
+      };
       ctx.requestEndTurn?.({ kind: 'work_item_actions_proposed', proposalId: input.proposalId });
       return JSON.stringify({ submitted: true, proposalId: input.proposalId, actionCount: input.actions.length });
     },
@@ -472,21 +502,34 @@ export function createProposeWorkItemActionsTool({
   });
 }
 
-export function createRequestWorkItemReplanTool({ workItem, collector, isRunActive }) {
+export function createRequestWorkItemReplanTool({
+  workItem, collector, isRunActive, currentAction = null,
+}) {
   return defineTool({
     name: 'RequestWorkItemReplan',
     description: 'Request an explicit replan barrier when additive Actions are insufficient because the contract or existing future topology must change. The current Action must still complete. Work Center will preserve completed history, fence sibling Runs, supersede only unfinished Actions, and insert a new triage/replan Action. Active integration finalization prevents the barrier.',
     parameters: { type: 'object', additionalProperties: false,
-      required: ['summary', 'evidence', 'acceptanceChecks', 'proposalId', 'basePlanRevision', 'reason'],
+      required: [
+        'summary', 'evidence', 'acceptanceChecks', 'proposalId', 'basePlanRevision', 'reason',
+        ...reviewPlanningRequirements(currentAction),
+      ],
       properties: {
-        ...terminalPlanningFields(), proposalId: { type: 'string', minLength: 1, maxLength: 128 },
+        ...terminalPlanningFields({ review: currentAction?.type === 'review' }),
+        proposalId: { type: 'string', minLength: 1, maxLength: 128 },
         basePlanRevision: { type: 'integer', const: workItem.planRevision },
         reason: { type: 'string', minLength: 1, maxLength: 4_000 },
       } },
     async execute(input, ctx = {}) {
       if (!isRunActive()) throw new Error('Work Center Run is no longer active');
       if (collector.value) throw new Error('A WorkItem plan mutation was already submitted for this Run');
-      collector.value = { kind: 'replan', input: structuredClone(input) };
+      assertReviewPlanningDecision(input, currentAction);
+      collector.value = {
+        kind: 'replan',
+        input: {
+          ...structuredClone(input),
+          ...reviewPlanningResult(input, currentAction),
+        },
+      };
       ctx.requestEndTurn?.({ kind: 'work_item_replan_requested', proposalId: input.proposalId });
       return JSON.stringify({ submitted: true, proposalId: input.proposalId });
     },
@@ -1082,7 +1125,12 @@ export class WorkItemRunner {
         actions: this.store.getWorkItemDetail(workItem.id).actions,
         collector: mutationCollector, isRunActive, currentAction: executionAction,
       }));
-      runTools.push(createRequestWorkItemReplanTool({ workItem, collector: mutationCollector, isRunActive }));
+      runTools.push(createRequestWorkItemReplanTool({
+        workItem,
+        collector: mutationCollector,
+        isRunActive,
+        currentAction: executionAction,
+      }));
     }
     const runToolNames = runTools.map(tool => tool.name);
     const toolPolicySnapshot = workItemToolPolicySnapshot(
@@ -1389,6 +1437,7 @@ export class WorkItemRunner {
     } : submittedExpansion ? {
       outcome: 'completed', summary: submittedExpansion.summary,
       evidence: submittedExpansion.evidence, acceptanceChecks: submittedExpansion.acceptanceChecks,
+      ...reviewPlanningResult(submittedExpansion, executionAction),
       planProposal: {
         proposalId: submittedExpansion.proposalId,
         basePlanRevision: submittedExpansion.basePlanRevision,
@@ -1398,6 +1447,7 @@ export class WorkItemRunner {
     } : submittedReplan ? {
       outcome: 'completed', summary: submittedReplan.summary,
       evidence: submittedReplan.evidence, acceptanceChecks: submittedReplan.acceptanceChecks,
+      ...reviewPlanningResult(submittedReplan, executionAction),
       replanRequest: {
         proposalId: submittedReplan.proposalId,
         basePlanRevision: submittedReplan.basePlanRevision,

package/yeaft/work-center/workflow.js

@@ -362,6 +362,23 @@ export function listWorkItemTypeTemplates(settings) {
   }));
 }
 
+export const MAX_INITIAL_PLAN_ACTIONS = 8;
+export const MAX_WORK_ITEM_ACTIONS = 64;
+
+export function generatedActionGraphRules(options = {}) {
+  const maxActions = Math.min(
+    Math.max(Number(options.maxActions) || MAX_INITIAL_PLAN_ACTIONS, 1),
+    MAX_WORK_ITEM_ACTIONS,
+  );
+  const concurrency = Number.isInteger(Number(options.maxConcurrentActions))
+    ? Math.min(Math.max(Number(options.maxConcurrentActions), 1), 12)
+    : null;
+  const concurrencyRule = concurrency
+    ? ` The scheduler can run up to ${concurrency} Actions concurrently.`
+    : '';
+  return `Always submit the smallest reliable graph of 1 to ${maxActions} task-specific Actions; never omit Actions or copy template brief text. Every graph must end in exactly one final acceptance gate: normally one deliver Action, or one terminal review when no delivery operation is required. The final gate must be the unique graph sink and every other Action must be its transitive dependency, so final acceptance cannot run before required evidence.${concurrencyRule} Before submitting, compare each pair of Actions and add a dependency only when one consumes a concrete result or side effect of the other; ordering by narrative, phase name, or list position is not a dependency. Split independent analysis, verification, and repository changes into sibling Actions so the scheduler can use concurrency. Use workspaceMode read only for Actions guaranteed not to mutate files, Git state, services, or external systems; use isolated-write for independent Git changes, integrate for an integrate Action that combines isolated-write dependencies, and shared for serial side effects. An Action with type integrate must use workspaceMode integrate, and type integrate is only valid when combining isolated-write Actions. If any Action uses isolated-write, add exactly one Action with type integrate and workspaceMode integrate; it must depend directly on every isolated-write Action, and all later Actions must consume those writes through the integration Action. Non-Git or dirty workspaces are serialized automatically; do not fake parallelism by marking a mutating Action as read. Every review Action must depend directly or transitively on the editable non-review, non-deliver Action it reviews, so the scheduler cannot claim the Review before that result exists. Set changesRequestedActionId to a non-empty dependency ancestor Action id, or omit the property to use the nearest eligible dependency ancestor; never send null or an empty string. Every generated Action must state objective, approach, expectedOutcome, capability, dependencies, and workspaceMode. The objective, approach, and expectedOutcome must be specific to this WorkItem and that Action: describe the concrete work, the repository-aware execution method, and the verifiable result that will guide the executor. Generic Action-type boilerplate is invalid. Add only Actions required by this task. Do not copy a generic workflow.`;
+}
+
 export function resolvePlanningWorkflowSnapshot(settings, requestedWorkItemType = null) {
   const normalized = normalizeWorkCenterSettings(settings);
   const requestedType = typeof requestedWorkItemType === 'string'
@@ -379,7 +396,9 @@ export function resolvePlanningWorkflowSnapshot(settings, requestedWorkItemType
   const typeInstruction = requestedType
     ? `The user explicitly selected workItemType "${requestedType}". Keep that exact type.`
     : 'Infer one specific workItemType from the contract.';
-  const triageInstruction = `${normalized.actionInstructions.triage}\n\n${typeInstruction}\nReference workflow catalog:\n${catalog || '(none)'}\nUse the catalog only to understand established task categories and sequencing patterns. Always submit the smallest reliable graph of 1 to 8 task-specific Actions; never omit Actions or copy template brief text. Every graph must end in exactly one final acceptance gate: normally one deliver Action, or one terminal review when no delivery operation is required. The final gate must be the unique graph sink and every other Action must be its transitive dependency, so final acceptance cannot run before required evidence. The scheduler can run up to ${normalized.maxConcurrentActions} Actions concurrently. Before submitting, compare each pair of Actions and add a dependency only when one consumes a concrete result or side effect of the other; ordering by narrative, phase name, or list position is not a dependency. Split independent analysis, verification, and repository changes into sibling Actions so the scheduler can use that concurrency. Use workspaceMode read only for Actions guaranteed not to mutate files, Git state, services, or external systems; use isolated-write for independent Git changes, integrate for an integrate Action that combines isolated-write dependencies, and shared for serial side effects. If any Action uses isolated-write, add exactly one Action with type integrate and workspaceMode integrate; it must depend directly on every isolated-write Action, and all later Actions must depend on the integration result rather than an isolated-write Action. Non-Git or dirty workspaces are serialized automatically; do not fake parallelism by marking a mutating Action as read. Every generated Action must state objective, approach, expectedOutcome, capability, dependencies, and workspaceMode. The objective, approach, and expectedOutcome must be specific to this WorkItem and that Action: describe the concrete work, the repository-aware execution method, and the verifiable result that will guide the executor. Generic Action-type boilerplate is invalid. Add only Actions required by this task. Do not copy a generic workflow.`;
+  const triageInstruction = `${normalized.actionInstructions.triage}\n\n${typeInstruction}\nReference workflow catalog:\n${catalog || '(none)'}\nUse the catalog only to understand established task categories and sequencing patterns. ${generatedActionGraphRules({
+    maxConcurrentActions: normalized.maxConcurrentActions,
+  })}`;
   return normalizeWorkflowDefinition({
     id: 'ai-planned',
     name: 'AI planned',
@@ -466,9 +485,6 @@ export function validateGeneratedCompletionGate(stages) {
   }
 }
 
-export const MAX_INITIAL_PLAN_ACTIONS = 8;
-export const MAX_WORK_ITEM_ACTIONS = 64;
-
 export function applyGeneratedPlan(workItem, rawPlan, options = {}) {
   const source = workflowFrom(workItem);
   const forceGraph = options.forceGraph !== false;
@@ -582,23 +598,42 @@ export function applyGeneratedPlan(workItem, rawPlan, options = {}) {
     }
     return stage;
   });
+  const generatedById = new Map(generated.map(stage => [stage.id, stage]));
+  const dependencyAncestors = stage => {
+    const ancestors = new Set();
+    const visit = stageId => {
+      if (ancestors.has(stageId)) return;
+      ancestors.add(stageId);
+      for (const dependencyId of generatedById.get(stageId)?.dependsOnStageIds || []) visit(dependencyId);
+    };
+    for (const dependencyId of stage.dependsOnStageIds) visit(dependencyId);
+    return ancestors;
+  };
   for (const [index, stage] of generated.entries()) {
     if (stage.type !== 'review') continue;
+    const ancestors = dependencyAncestors(stage);
     const candidates = generated.slice(0, index)
-      .filter(candidate => candidate.type !== 'review' && candidate.type !== 'deliver');
+      .filter(candidate => (
+        candidate.type !== 'review'
+        && candidate.type !== 'deliver'
+        && ancestors.has(candidate.id)
+      ));
     if (Object.prototype.hasOwnProperty.call(stage, 'changesRequestedStageId')) {
-      const requested = candidates.find(candidate => candidate.id === stage.changesRequestedStageId);
-      if (!requested) {
+      const requested = generatedById.get(stage.changesRequestedStageId);
+      if (!requested || requested.type === 'review' || requested.type === 'deliver') {
         throw new Error(`AI-planned review Action "${stage.id}" points to an invalid return Action`);
       }
+      if (!ancestors.has(requested.id)) {
+        throw new Error(`AI-planned review Action "${stage.id}" review target "${requested.id}" must be a dependency ancestor`);
+      }
       stage.changesRequestedStageId = requested.id;
     } else {
       stage.changesRequestedStageId = candidates.at(-1)?.id || '';
     }
     if (!stage.changesRequestedStageId) {
-      throw new Error(`AI-planned review Action "${stage.id}" requires an earlier editable Action`);
+      throw new Error(`AI-planned review Action "${stage.id}" requires an editable dependency ancestor`);
     }
-    const returnTarget = candidates.find(candidate => candidate.id === stage.changesRequestedStageId);
+    const returnTarget = generatedById.get(stage.changesRequestedStageId);
     stage.assignmentPolicy = {
       ...stage.assignmentPolicy,
       separateFromStageTypes: uniqueStrings([