@yeaft/webchat-agent 1.0.185 → 1.0.186

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.185",
+  "version": "1.0.186",
   "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/work-center/assignment.js

@@ -71,12 +71,19 @@ export function selectWorkItemVp({ policy: rawPolicy, stageType, vps, priorRuns
     return { vp: fixed, reason: `fixed:${fixed.id}`, policy };
   }
 
-  const pool = policy.mode === 'pool'
+  const pool = ['pool', 'planned'].includes(policy.mode)
     ? policy.candidateVpIds.map(id => byId.get(id)).filter(Boolean)
     : all;
   if (pool.length === 0) throw policyError('No configured Work Center VP candidates are available');
   const eligible = pool.filter(vp => !excluded.has(vp.id));
   if (eligible.length === 0) throw policyError('No Work Center VP satisfies the stage separation policy');
+  if (policy.mode === 'planned') {
+    return {
+      vp: eligible[0],
+      reason: `planned:${eligible[0].id}:${policy.assignmentReason || stageType}`,
+      policy,
+    };
+  }
 
   const ranked = eligible
     .map(vp => ({ vp, score: capabilityScore(vp, policy.capability || stageType) }))

package/yeaft/work-center/bridge.js

@@ -116,6 +116,7 @@ async function createDefaultService() {
     yeaftDir,
     runner,
     runtimeInfoProvider: getSettingsRuntime,
+    listAvailableVpIds: () => defaultRegistry.listVps().map(vp => vp.id),
     watcherOptions: {
       concurrencyProvider: () => readWorkCenterSettings(yeaftDir).maxConcurrentActions,
     },

package/yeaft/work-center/controller.js

@@ -8,6 +8,7 @@ import {
 } from './workflow.js';
 import { renderSessionContextSnapshot } from './session-context.js';
 import { normalizeEvidence } from './evidence.js';
+import { applyAdditivePlanProposal } from './plan-mutation.js';
 
 function normalizeCriteria(value) {
   if (!Array.isArray(value)) return null;
@@ -92,6 +93,10 @@ function normalizeTerminalResult(result, action) {
     acceptanceChecks: Array.isArray(result.acceptanceChecks) ? result.acceptanceChecks : [],
     checkpoint: result.checkpoint && typeof result.checkpoint === 'object'
       ? result.checkpoint : null,
+    planProposal: result.planProposal && typeof result.planProposal === 'object'
+      && !Array.isArray(result.planProposal) ? result.planProposal : null,
+    replanRequest: result.replanRequest && typeof result.replanRequest === 'object'
+      && !Array.isArray(result.replanRequest) ? result.replanRequest : null,
   };
   if (normalized.outcome === 'waiting' && !normalized.waitingReason) {
     throw new Error('waiting outcome requires waitingReason');
@@ -101,6 +106,16 @@ function normalizeTerminalResult(result, action) {
     normalized.error = 'Only triage may submit a WorkItem contractPatch';
     normalized.contractPatch = null;
   }
+  if (normalized.outcome !== 'completed') {
+    normalized.planProposal = null;
+    normalized.replanRequest = null;
+  }
+  if (normalized.planProposal && normalized.replanRequest) {
+    normalized.outcome = 'failed';
+    normalized.error = 'An Action cannot expand and replan the WorkItem in the same completion';
+    normalized.planProposal = null;
+    normalized.replanRequest = null;
+  }
   if (action.type === 'review' && normalized.outcome === 'completed' && !normalized.reviewDecision) {
     normalized.outcome = 'failed';
     normalized.error = 'Completed review requires approved or changes_requested';
@@ -121,8 +136,11 @@ function contextEntry(action, result, run) {
 }
 
 export class WorkflowController {
-  constructor(store) {
+  constructor(store, options = {}) {
     this.store = store;
+    this.listAvailableVpIds = typeof options.listAvailableVpIds === 'function'
+      ? options.listAvailableVpIds
+      : null;
   }
 
   create(input) {
@@ -331,12 +349,45 @@ export class WorkflowController {
           }
         : current;
       try {
-        validatedGeneratedWorkflow = applyGeneratedPlan(effective, result.plan);
+        const reservedStageIds = activeAction.stageId?.startsWith('replan-')
+          ? this.store.getWorkItemDetail(activeWorkItem.id).actions.map(action => action.stageId)
+          : [];
+        validatedGeneratedWorkflow = applyGeneratedPlan(effective, result.plan, {
+          availableVpIds: this.listAvailableVpIds?.(),
+          reservedStageIds,
+        });
+      } catch (error) {
+        result.outcome = 'failed';
+        result.error = error?.message || String(error);
+      }
+    }
+    let validatedPlanProposal = null;
+    if (result.outcome === 'completed' && result.planProposal) {
+      try {
+        validatedPlanProposal = applyAdditivePlanProposal({
+          workItem: activeWorkItem,
+          actions: this.store.getWorkItemDetail(activeWorkItem.id).actions,
+          proposal: result.planProposal,
+          availableVpIds: this.listAvailableVpIds?.(),
+        });
       } catch (error) {
         result.outcome = 'failed';
         result.error = error?.message || String(error);
       }
     }
+    if (result.outcome === 'completed' && result.replanRequest) {
+      const basePlanRevision = Number(result.replanRequest.basePlanRevision);
+      const proposalId = typeof result.replanRequest.proposalId === 'string'
+        ? result.replanRequest.proposalId.trim().slice(0, 128) : '';
+      const reason = typeof result.replanRequest.reason === 'string'
+        ? result.replanRequest.reason.trim().slice(0, 4_000) : '';
+      if (!proposalId || !reason || basePlanRevision !== activeWorkItem.planRevision) {
+        result.outcome = 'failed';
+        result.error = 'Work Center replan request is missing fields or has a stale basePlanRevision';
+      } else {
+        result.replanRequest = { proposalId, reason, basePlanRevision };
+      }
+    }
     const detail = this.store.finalizeRun(
       runId,
       ownerBootId,
@@ -394,11 +445,40 @@ export class WorkflowController {
           && workItem.workflowSnapshot?.planningMode === 'ai'
           ? validatedGeneratedWorkflow
           : null;
+        const planProposal = workItem.planRevision === activeWorkItem.planRevision
+          ? validatedPlanProposal
+          : null;
+        if (validatedPlanProposal && !planProposal) {
+          throw new Error('Work Center plan revision changed before finalization');
+        }
         const plannedWorkItem = generatedWorkflow
           ? { ...effectiveWorkItem, workflowSnapshot: generatedWorkflow }
-          : effectiveWorkItem;
+          : planProposal
+            ? { ...effectiveWorkItem, workflowSnapshot: planProposal.workflowSnapshot }
+            : effectiveWorkItem;
         const context = [...(action.context || []), contextEntry(action, result, activeRun)];
         if (plannedWorkItem.workflowSnapshot?.executionMode === 'graph') {
+          if (result.replanRequest) {
+            const replanStage = {
+              ...plannedWorkItem.workflowSnapshot.stages[0],
+              id: `replan-${workItem.planRevision + 1}`,
+              name: 'Replan',
+              type: 'triage',
+              objective: 'Replan the unfinished WorkItem graph without changing completed history.',
+              approach: `Inspect completed evidence and this replan reason: ${result.replanRequest.reason}`,
+              expectedOutcome: 'A validated replacement plan for all unfinished work.',
+              dependsOnStageIds: [],
+            };
+            return {
+              actionStatus: 'completed', workItemStatus: 'ready', graphAdvance: true,
+              replanBarrier: {
+                ...result.replanRequest,
+                action: actionForStage(replanStage, plannedWorkItem, context),
+              },
+              eventType: 'workflow.replan_requested',
+              eventData: { reason: result.replanRequest.reason },
+            };
+          }
           if (action.type === 'review' && result.reviewDecision === 'changes_requested') {
             const targetStage = plannedWorkItem.workflowSnapshot.stages
               .find(stage => stage.id === action.changesRequestedStageId);
@@ -413,15 +493,19 @@ export class WorkflowController {
           }
           const nextActions = generatedWorkflow
             ? generatedWorkflow.stages.slice(1).map(stage => actionForStage(stage, plannedWorkItem, context))
-            : [];
+            : (planProposal?.nextActions || []);
+          const workflowSnapshot = generatedWorkflow || planProposal?.workflowSnapshot || null;
           return {
             actionStatus: 'completed',
             workItemStatus: nextActions.length > 0 ? 'ready' : 'running',
             contractPatch,
-            workflowSnapshot: generatedWorkflow,
+            workflowSnapshot,
+            expectedPlanRevision: generatedWorkflow ? workItem.planRevision : planProposal?.basePlanRevision,
+            proposalId: generatedWorkflow ? `initial:${runId}` : planProposal?.proposalId,
+            dependencyPatches: planProposal?.dependencyPatches || [],
             nextActions,
             graphAdvance: true,
-            eventType: 'action.completed',
+            eventType: planProposal ? 'workflow.plan_expanded' : 'action.completed',
             eventData: { nextActionCount: nextActions.length, reviewDecision: result.reviewDecision },
           };
         }
@@ -433,6 +517,8 @@ export class WorkflowController {
             workItemStatus: 'done',
             contractPatch,
             workflowSnapshot: generatedWorkflow,
+            expectedPlanRevision: generatedWorkflow ? workItem.planRevision : undefined,
+            proposalId: generatedWorkflow ? `initial:${runId}` : undefined,
             eventType: 'work_item.completed',
             eventData: { summary: result.summary },
           };
@@ -443,6 +529,8 @@ export class WorkflowController {
           workItemStatus: 'ready',
           contractPatch,
           workflowSnapshot: generatedWorkflow,
+          expectedPlanRevision: generatedWorkflow ? workItem.planRevision : undefined,
+          proposalId: generatedWorkflow ? `initial:${runId}` : undefined,
           nextAction: actionForStage(nextStep, plannedWorkItem, context),
           eventType: 'action.completed',
           eventData: {

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

@@ -0,0 +1,185 @@
+import {
+  actionForStage,
+  applyGeneratedPlan,
+  canonicalActionId,
+  canonicalExplicitActionId,
+  canonicalExplicitActionIds,
+} from './workflow.js';
+
+function cleanProposalId(value) {
+  const id = typeof value === 'string' ? value.trim().slice(0, 128) : '';
+  if (!id) throw new Error('Work Center plan proposal requires proposalId');
+  return id;
+}
+
+function planActionFromStage(stage) {
+  return {
+    id: stage.id,
+    name: stage.name,
+    type: stage.type,
+    objective: stage.objective,
+    approach: stage.approach,
+    expectedOutcome: stage.expectedOutcome,
+    capability: stage.assignmentPolicy?.capability,
+    candidateVpIds: stage.assignmentPolicy?.mode === 'planned'
+      ? stage.assignmentPolicy.candidateVpIds
+      : undefined,
+    assignmentReason: stage.assignmentPolicy?.assignmentReason,
+    separateFromActionTypes: stage.assignmentPolicy?.separateFromStageTypes,
+    dependsOnActionIds: stage.dependsOnStageIds || [],
+    workspaceMode: stage.workspaceMode,
+    changesRequestedActionId: stage.changesRequestedStageId,
+    maxAttempts: stage.maxAttempts,
+  };
+}
+
+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]));
+  const outgoing = new Map(actions.map(action => [action.id, []]));
+  for (const action of actions) {
+    const orderingDependencies = new Set([
+      ...(action.dependsOnActionIds || []),
+      ...(action.changesRequestedActionId ? [action.changesRequestedActionId] : []),
+    ]);
+    for (const dependencyId of orderingDependencies) {
+      if (!byId.has(dependencyId) || dependencyId === action.id) {
+        throw new Error(`Work Center additive Action "${action.id}" has an invalid dependency "${dependencyId}"`);
+      }
+      incoming.set(action.id, incoming.get(action.id) + 1);
+      outgoing.get(dependencyId).push(action.id);
+    }
+  }
+  const ready = actions.filter(action => incoming.get(action.id) === 0)
+    .sort((left, right) => byId.get(left.id).index - byId.get(right.id).index);
+  const ordered = [];
+  while (ready.length > 0) {
+    const action = ready.shift();
+    ordered.push(action);
+    for (const dependentId of outgoing.get(action.id)) {
+      const count = incoming.get(dependentId) - 1;
+      incoming.set(dependentId, count);
+      if (count === 0) {
+        ready.push(byId.get(dependentId).action);
+        ready.sort((left, right) => byId.get(left.id).index - byId.get(right.id).index);
+      }
+    }
+  }
+  if (ordered.length !== actions.length) {
+    throw new Error('Work Center additive plan contains a dependency cycle');
+  }
+  return ordered;
+}
+
+function validateDependencyPatches(actions, patches, addedIds) {
+  const active = new Map(actions
+    .filter(action => !['superseded', 'cancelled'].includes(action.status))
+    .map(action => [action.stageId, action]));
+  const normalized = [];
+  const patchedActionIds = new Set();
+  for (const raw of Array.isArray(patches) ? patches : []) {
+    const actionId = typeof raw?.actionId === 'string' ? raw.actionId.trim() : '';
+    const action = actions.find(candidate => candidate.id === actionId);
+    if (!action || action.status !== 'ready' || action.attempt !== 0) {
+      throw new Error(`Work Center dependency patch target must be an unattempted ready Action: ${actionId || '(missing)'}`);
+    }
+    if (patchedActionIds.has(action.id)) {
+      throw new Error(`Work Center dependency patch target is duplicated: ${action.id}`);
+    }
+    patchedActionIds.add(action.id);
+    const addDependsOnActionIds = canonicalExplicitActionIds(
+      raw.addDependsOnActionIds,
+      'dependency patch',
+    );
+    if (addDependsOnActionIds.length === 0) throw new Error('Work Center dependency patch must add at least one dependency');
+    for (const dependencyId of addDependsOnActionIds) {
+      if (!active.has(dependencyId) && !addedIds.has(dependencyId)) {
+        throw new Error(`Work Center dependency patch references missing Action: ${dependencyId}`);
+      }
+      if (dependencyId === action.stageId) throw new Error('Work Center Action cannot depend on itself');
+    }
+    normalized.push({ action, addDependsOnActionIds });
+  }
+  return normalized;
+}
+
+export function applyAdditivePlanProposal({ workItem, actions, proposal, availableVpIds = null }) {
+  if (workItem.workflowSnapshot?.executionMode !== 'graph') {
+    throw new Error('Work Center additive planning requires graph execution');
+  }
+  if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal)) {
+    throw new Error('Work Center plan proposal must be an object');
+  }
+  const proposalId = cleanProposalId(proposal.proposalId);
+  const basePlanRevision = Number(proposal.basePlanRevision);
+  if (!Number.isInteger(basePlanRevision) || basePlanRevision !== workItem.planRevision) {
+    throw new Error('Work Center plan proposal has a stale basePlanRevision');
+  }
+  if (!Array.isArray(proposal.actions) || proposal.actions.length < 1 || proposal.actions.length > 8) {
+    throw new Error('Work Center additive plan requires between 1 and 8 new Actions');
+  }
+  const activeStages = workItem.workflowSnapshot.stages || [];
+  const existingIds = new Set(activeStages.map(stage => stage.id));
+  const addedIds = new Set();
+  const canonicalActions = proposal.actions.map(raw => {
+    const id = canonicalActionId(raw?.id);
+    if (!id || existingIds.has(id) || addedIds.has(id)) {
+      throw new Error(`Work Center additive Action id is missing or already exists: ${id || '(missing)'}`);
+    }
+    addedIds.add(id);
+    const hasReturnTarget = Object.hasOwn(raw, 'changesRequestedActionId');
+    return {
+      ...raw,
+      id,
+      dependsOnActionIds: canonicalExplicitActionIds(
+        raw.dependsOnActionIds,
+        `Action "${id}" dependencies`,
+      ),
+      changesRequestedActionId: hasReturnTarget
+        ? canonicalExplicitActionId(
+          raw.changesRequestedActionId,
+          `Action "${id}" review target`,
+        )
+        : undefined,
+    };
+  });
+  const dependencyPatches = validateDependencyPatches(actions, proposal.dependencyPatches, addedIds);
+  const synthetic = {
+    ...workItem,
+    workflowSnapshot: {
+      ...workItem.workflowSnapshot,
+      actionTemplates: [],
+      workItemType: workItem.workflowSnapshot.workItemType,
+      stages: [workItem.workflowSnapshot.stages[0]],
+    },
+  };
+  const patchByStageId = new Map(dependencyPatches.map(patch => [patch.action.stageId, patch]));
+  const mergedActions = [
+    ...activeStages.slice(1).map(stage => {
+      const action = planActionFromStage(stage);
+      const patch = patchByStageId.get(stage.id);
+      if (!patch) return action;
+      return {
+        ...action,
+        dependsOnActionIds: [...new Set([
+          ...(action.dependsOnActionIds || []),
+          ...patch.addDependsOnActionIds,
+        ])],
+      };
+    }),
+    ...canonicalActions,
+  ];
+  const rawPlan = {
+    workItemType: workItem.workflowSnapshot.workItemType,
+    actions: stableTopologicalActions(mergedActions),
+  };
+  const workflowSnapshot = applyGeneratedPlan(synthetic, rawPlan, { availableVpIds });
+  const addedStages = workflowSnapshot.stages.filter(stage => addedIds.has(stage.id));
+  return {
+    proposalId,
+    basePlanRevision,
+    workflowSnapshot,
+    nextActions: addedStages.map(stage => actionForStage(stage, { ...workItem, workflowSnapshot }, [])),
+    dependencyPatches,
+  };
+}

package/yeaft/work-center/runner.js

@@ -1,5 +1,6 @@
 import { Engine } from '../engine.js';
 import { ToolRegistry } from '../tools/registry.js';
+import { defineTool } from '../tools/types.js';
 import { allTools } from '../tools/index.js';
 import { parsePatch } from '../tools/apply-patch.js';
 import { defaultRegistry } from '../vp/registry.js';
@@ -30,6 +31,7 @@ import { loadMCPConfig } from '../config.js';
 import { MCPManager } from '../mcp.js';
 import { buildMcpFlattenedTools } from '../tools/mcp-tools.js';
 import { recallWorkspaceSessionContext } from './workspace-context.js';
+import { BUILT_IN_ACTION_TYPES } from './workflow.js';
 
 const WORK_ITEM_TOOL_NAMES = Object.freeze([
   'FileRead',
@@ -280,7 +282,126 @@ function wrapWorkItemTool(tool, canonicalDir, canonicalAttachmentFiles, isRunAct
   };
 }
 
-export function createWorkItemToolRegistry({ workDir, attachmentFiles = [], isRunActive, mcpTools = [] }) {
+export function planningVpCatalog(vps) {
+  return vps.map(vp => ({
+    id: vp.id,
+    name: vp.name || vp.id,
+    nameZh: vp.nameZh || '',
+    role: vp.role || '',
+    roleZh: vp.roleZh || '',
+    area: vp.area || '',
+    traits: Array.isArray(vp.traits) ? vp.traits.slice(0, 20) : [],
+  }));
+}
+
+export function createSubmitWorkItemPlanTool({ vps, collector, isRunActive }) {
+  const vpCatalog = planningVpCatalog(vps);
+  const vpIds = vpCatalog.map(vp => vp.id);
+  const actionTypes = BUILT_IN_ACTION_TYPES.filter(type => type !== 'triage');
+  const catalogDescription = `Action types: ${actionTypes.join(', ')}. Available VPs: ${vpCatalog.map(vp => `${vp.id} (${vp.role || vp.area || 'VP'}; ${vp.traits.join(', ') || 'no traits'})`).join('; ')}.`;
+  return defineTool({
+    name: 'SubmitWorkItemPlan',
+    description: `Submit the complete initial WorkItem contract and executable Action DAG. This tool records a Run-local proposal only; Work Center validates and persists it in the current Run finalization transaction. ${catalogDescription}`,
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['summary', 'evidence', 'acceptanceChecks', 'workItemType', 'actions'],
+      properties: {
+        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 } } } },
+        contractPatch: { type: 'object', additionalProperties: false, properties: { goal: { type: 'string', minLength: 1, maxLength: 8_000 }, acceptanceCriteria: { type: 'array', items: { type: 'string', minLength: 1, maxLength: 2_000 } } } },
+        workItemType: { type: 'string', minLength: 1, maxLength: 64 },
+        actions: { type: 'array', minItems: 1, maxItems: 8, items: { type: 'object', additionalProperties: false, required: ['id', 'name', 'type', 'objective', 'approach', 'expectedOutcome', 'candidateVpIds', 'assignmentReason', 'dependsOnActionIds', 'workspaceMode'], properties: {
+          id: { type: 'string', minLength: 1, maxLength: 64 }, name: { type: 'string', minLength: 1, maxLength: 120 },
+          type: { type: 'string', enum: actionTypes }, capability: { type: 'string', maxLength: 64 },
+          objective: { type: 'string', minLength: 1, maxLength: 2_000 }, approach: { type: 'string', minLength: 1, maxLength: 2_000 }, expectedOutcome: { type: 'string', minLength: 1, maxLength: 2_000 },
+          candidateVpIds: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string', enum: vpIds } }, assignmentReason: { type: 'string', minLength: 1, maxLength: 1_000 },
+          dependsOnActionIds: { type: 'array', uniqueItems: true, items: { type: 'string' } }, workspaceMode: { type: 'string', enum: ['read', 'isolated-write', 'integrate', 'shared'] },
+          separateFromActionTypes: { type: 'array', uniqueItems: true, items: { type: 'string' } }, changesRequestedActionId: { type: 'string' }, maxAttempts: { type: 'integer', minimum: 1, maximum: 5 },
+        } } },
+      },
+    },
+    async execute(input, ctx = {}) {
+      if (!isRunActive()) throw new Error('Work Center Run is no longer active');
+      if (collector.value) throw new Error('WorkItem plan was already submitted for this Run');
+      collector.value = structuredClone(input);
+      ctx.requestEndTurn?.({ kind: 'work_item_plan_submitted' });
+      return JSON.stringify({ submitted: true, actionCount: input.actions.length });
+    },
+    isConcurrencySafe: () => false,
+    isReadOnly: () => false,
+  });
+}
+
+function terminalPlanningFields() {
+  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 } } } },
+  };
+}
+
+function plannedActionSchema(vpIds, { requireCandidates = true } = {}) {
+  const required = ['id', 'name', 'type', 'objective', 'approach', 'expectedOutcome', 'dependsOnActionIds', 'workspaceMode'];
+  if (requireCandidates) required.push('candidateVpIds', 'assignmentReason');
+  return { type: 'object', additionalProperties: false, required, properties: {
+    id: { type: 'string', minLength: 1, maxLength: 64 }, name: { type: 'string', minLength: 1, maxLength: 120 },
+    type: { type: 'string', enum: BUILT_IN_ACTION_TYPES.filter(type => type !== 'triage') }, capability: { type: 'string', maxLength: 64 },
+    objective: { type: 'string', minLength: 1, maxLength: 2_000 }, approach: { type: 'string', minLength: 1, maxLength: 2_000 }, expectedOutcome: { type: 'string', minLength: 1, maxLength: 2_000 },
+    candidateVpIds: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string', enum: vpIds } }, assignmentReason: { type: 'string', minLength: 1, maxLength: 1_000 },
+    dependsOnActionIds: { type: 'array', uniqueItems: true, items: { type: 'string' } }, workspaceMode: { type: 'string', enum: ['read', 'isolated-write', 'integrate', 'shared'] },
+    separateFromActionTypes: { type: 'array', uniqueItems: true, items: { type: 'string' } }, changesRequestedActionId: { type: 'string' }, maxAttempts: { type: 'integer', minimum: 1, maximum: 5 },
+  } };
+}
+
+export function createProposeWorkItemActionsTool({ vps, workItem, actions, collector, isRunActive }) {
+  const vpCatalog = planningVpCatalog(vps);
+  const vpIds = vpCatalog.map(vp => vp.id);
+  const existing = actions.filter(action => !['superseded', 'cancelled'].includes(action.status));
+  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. Existing Actions: ${existing.map(action => `${action.id}/${action.stageId} (${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.`,
+    parameters: { type: 'object', additionalProperties: false,
+      required: ['summary', 'evidence', 'acceptanceChecks', 'proposalId', 'basePlanRevision', 'actions'],
+      properties: {
+        ...terminalPlanningFields(), 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' } } } } },
+      } },
+    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: 'expand', input: structuredClone(input) };
+      ctx.requestEndTurn?.({ kind: 'work_item_actions_proposed', proposalId: input.proposalId });
+      return JSON.stringify({ submitted: true, proposalId: input.proposalId, actionCount: input.actions.length });
+    },
+  });
+}
+
+export function createRequestWorkItemReplanTool({ workItem, collector, isRunActive }) {
+  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'],
+      properties: {
+        ...terminalPlanningFields(), 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) };
+      ctx.requestEndTurn?.({ kind: 'work_item_replan_requested', proposalId: input.proposalId });
+      return JSON.stringify({ submitted: true, proposalId: input.proposalId });
+    },
+  });
+}
+
+export function createWorkItemToolRegistry({ workDir, attachmentFiles = [], isRunActive, mcpTools = [], runTools = [] }) {
   const canonicalDir = canonicalWorkDir(path.resolve(workDir));
   const canonicalAttachmentFiles = attachmentFiles.map(file => ({
     ...file,
@@ -296,6 +417,9 @@ export function createWorkItemToolRegistry({ workDir, attachmentFiles = [], isRu
     if (!tool?.name?.startsWith('mcp__')) continue;
     registry.register(wrapWorkItemTool(tool, canonicalDir, canonicalAttachmentFiles, isRunActive));
   }
+  for (const tool of runTools) {
+    registry.register(wrapWorkItemTool(tool, canonicalDir, canonicalAttachmentFiles, isRunActive));
+  }
   return registry;
 }
 
@@ -347,12 +471,17 @@ function completionContract(action, workItem) {
   const planField = action.type === 'triage' && workItem?.workflowSnapshot?.planningMode === 'ai'
     ? ',\n  "plan": { "workItemType": "specific-lowercase-slug", "actions": [{ "id": "stable-id", "name": "User-facing name", "type": "extensible-lowercase-slug (built-ins include research|design|diagnose|implement|migrate|test|review|document|operate|deliver|integrate|write|custom)", "capability": "specific executor capability", "objective": "task-specific concrete work this Action must do", "approach": "task-specific repository-aware method the executor must follow", "expectedOutcome": "task-specific verifiable result this Action must produce", "dependsOnActionIds": ["earlier Action id; [] means concurrent root"], "workspaceMode": "read|isolated-write|integrate|shared", "separateFromActionTypes": ["optional prior Action type"], "changesRequestedActionId": "for review: optional earlier editable Action id; omit to use nearest", "maxAttempts": 2 }] }'
     : '';
+  const toolSubmission = action.type === 'triage' && workItem?.workflowSnapshot?.planningMode === 'ai'
+    ? '\nSubmit the initial plan with SubmitWorkItemPlan. The legacy terminal JSON plan below exists only for compatibility; do not use it when the tool is available.'
+    : workItem?.workflowSnapshot?.executionMode === 'graph'
+      ? '\nIf execution discovered strictly additive work, use ProposeWorkItemActions. If the contract or existing unfinished topology must change, use RequestWorkItemReplan. Both tools submit the completed Action and end the turn; do not emit terminal JSON after calling one.'
+      : '';
   const acceptanceChecks = (workItem?.acceptanceCriteria || []).map(criterion => ({
     criterion,
     status: 'passed|deferred|not_applicable',
     evidence: 'specific evidence reference',
   }));
-  return `\n\nYou are executing one Work Center Action. Before the terminal JSON, write a concise user-facing response describing what you did and the result. Do not include raw tool output or secrets. End your response with exactly one JSON object, preferably in a json code fence:\n{
+  return `${toolSubmission}\n\nYou are executing one Work Center Action. Before the terminal JSON, write a concise user-facing response describing what you did and the result. Do not include raw tool output or secrets. End your response with exactly one JSON object, preferably in a json code fence:\n{
   "outcome": "completed|waiting|retryable|failed",
   "summary": "short result",
   "evidence": ["test, PR, file, or other verifiable evidence"],
@@ -693,16 +822,34 @@ export class WorkItemRunner {
       && this.store.isActiveRun(run.id, ownerBootId, run.leaseEpoch);
     const workspaceRuntime = await this.#workspaceRuntime(workspaceDir, workDir, isRunActive);
     const mcpToolNames = workspaceRuntime.mcpTools.map(tool => tool.name);
+    const planCollector = { value: null };
+    const mutationCollector = { value: null };
+    const planToolEnabled = executionAction.type === 'triage'
+      && workItem?.workflowSnapshot?.planningMode === 'ai';
+    const runTools = [];
+    if (planToolEnabled) runTools.push(createSubmitWorkItemPlanTool({
+      vps: this.registry.listVps(), collector: planCollector, isRunActive,
+    }));
+    if (!planToolEnabled && workItem?.workflowSnapshot?.executionMode === 'graph') {
+      runTools.push(createProposeWorkItemActionsTool({
+        vps: this.registry.listVps(), workItem,
+        actions: this.store.getWorkItemDetail(workItem.id).actions,
+        collector: mutationCollector, isRunActive,
+      }));
+      runTools.push(createRequestWorkItemReplanTool({ workItem, collector: mutationCollector, isRunActive }));
+    }
+    const runToolNames = runTools.map(tool => tool.name);
     const toolPolicySnapshot = workItemToolPolicySnapshot(
       workDir,
       attachmentContext.files.map(file => file.ref),
-      mcpToolNames,
+      [...mcpToolNames, ...runToolNames],
     );
     const toolRegistry = createWorkItemToolRegistry({
       workDir,
       attachmentFiles: attachmentContext.files,
       isRunActive,
       mcpTools: workspaceRuntime.mcpTools,
+      runTools,
     });
     const config = {
       ...runtime.config,
@@ -844,7 +991,36 @@ export class WorkItemRunner {
     }
     const response = publicWorkItemResponse(text);
     reportProgress(true);
-    const parsedResult = parseStructuredResult(text, executionAction.type);
+    const submittedPlan = planCollector.value;
+    const submittedExpansion = mutationCollector.value?.kind === 'expand'
+      ? mutationCollector.value.input : null;
+    const submittedReplan = mutationCollector.value?.kind === 'replan'
+      ? mutationCollector.value.input : null;
+    const parsedResult = submittedPlan ? {
+      outcome: 'completed',
+      summary: submittedPlan.summary,
+      evidence: submittedPlan.evidence,
+      contractPatch: submittedPlan.contractPatch || null,
+      plan: { workItemType: submittedPlan.workItemType, actions: submittedPlan.actions },
+      acceptanceChecks: submittedPlan.acceptanceChecks,
+    } : submittedExpansion ? {
+      outcome: 'completed', summary: submittedExpansion.summary,
+      evidence: submittedExpansion.evidence, acceptanceChecks: submittedExpansion.acceptanceChecks,
+      planProposal: {
+        proposalId: submittedExpansion.proposalId,
+        basePlanRevision: submittedExpansion.basePlanRevision,
+        actions: submittedExpansion.actions,
+        dependencyPatches: submittedExpansion.dependencyPatches || [],
+      },
+    } : submittedReplan ? {
+      outcome: 'completed', summary: submittedReplan.summary,
+      evidence: submittedReplan.evidence, acceptanceChecks: submittedReplan.acceptanceChecks,
+      replanRequest: {
+        proposalId: submittedReplan.proposalId,
+        basePlanRevision: submittedReplan.basePlanRevision,
+        reason: submittedReplan.reason,
+      },
+    } : parseStructuredResult(text, executionAction.type);
     if (parsedResult.outcome === 'completed' && action.workspace?.isolated) {
       const workspace = commitActionWorktree(action.workspace, action);
       this.store.setActionWorkspace(action.id, workspace);

package/yeaft/work-center/service.js

@@ -64,7 +64,9 @@ export class WorkCenterService {
     this.ownerBootId = options.ownerBootId || randomUUID();
     this.attachmentRoot = options.attachmentRoot || join(yeaftDir, 'work-center', 'attachments');
     this.store = options.store || new WorkItemStore(join(yeaftDir, 'work-center', 'work-center.db'));
-    this.controller = options.controller || new WorkflowController(this.store);
+    this.controller = options.controller || new WorkflowController(this.store, {
+      listAvailableVpIds: options.listAvailableVpIds,
+    });
     this.onEvent = typeof options.onEvent === 'function' ? options.onEvent : () => {};
     this.watcher = new WorkItemWatcher({
       store: this.store,

package/yeaft/work-center/store.js

@@ -5,7 +5,7 @@ import { randomUUID } from 'node:crypto';
 import { normalizeEvidence } from './evidence.js';
 import { normalizeActionCheckpoint } from './action-checkpoint.js';
 
-const SCHEMA_VERSION = 11;
+const SCHEMA_VERSION = 12;
 const OPEN_ACTION_STATUSES = "'ready','running','waiting'";
 const MAX_REUSABLE_CONTEXT_ITEMS = 12;
 const MAX_RUN_RESPONSE_CHARS = 65_536;
@@ -34,6 +34,7 @@ function mapWorkItem(row) {
   return {
     id: row.id,
     revision: row.revision,
+    planRevision: Math.max(0, Number(row.plan_revision) || 0),
     title: row.title,
     goal: row.goal,
     acceptanceCriteria: parseJson(row.acceptance_criteria, []),
@@ -181,6 +182,7 @@ export class WorkItemStore {
       CREATE TABLE IF NOT EXISTS work_items (
         id TEXT PRIMARY KEY,
         revision INTEGER NOT NULL DEFAULT 1,
+        plan_revision INTEGER NOT NULL DEFAULT 0,
         title TEXT NOT NULL,
         goal TEXT NOT NULL,
         acceptance_criteria TEXT NOT NULL,
@@ -266,6 +268,19 @@ export class WorkItemStore {
         data TEXT NOT NULL,
         created_at INTEGER NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS plan_audits (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        work_item_id TEXT NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
+        proposal_id TEXT NOT NULL,
+        base_plan_revision INTEGER NOT NULL,
+        plan_revision INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        action_id TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        data TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        UNIQUE(work_item_id, proposal_id)
+      );
       CREATE INDEX IF NOT EXISTS idx_work_items_status_updated ON work_items(status, updated_at DESC);
       CREATE INDEX IF NOT EXISTS idx_actions_ready ON actions(status, updated_at, sequence);
       CREATE INDEX IF NOT EXISTS idx_runs_active ON runs(status, expires_at);
@@ -362,6 +377,9 @@ export class WorkItemStore {
     if (!hasColumn(this.db, 'actions', 'workspace')) {
       this.db.exec('ALTER TABLE actions ADD COLUMN workspace TEXT');
     }
+    if (!hasColumn(this.db, 'work_items', 'plan_revision')) {
+      this.db.exec('ALTER TABLE work_items ADD COLUMN plan_revision INTEGER NOT NULL DEFAULT 0');
+    }
     this.db.prepare(`INSERT INTO schema_meta(key, value) VALUES('schema_version', ?)
       ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(String(SCHEMA_VERSION));
   }
@@ -1322,17 +1340,76 @@ export class WorkItemStore {
         nextWorkItem = this.getWorkItem(workItem.id);
       }
       if (transition.workflowSnapshot) {
-        this.db.prepare(`UPDATE work_items SET workflow_template = ?, workflow_snapshot = ?, updated_at = ?
-          WHERE id = ?`).run(
+        const expectedPlanRevision = Number.isInteger(transition.expectedPlanRevision)
+          ? transition.expectedPlanRevision
+          : workItem.planRevision;
+        const changedPlan = this.db.prepare(`UPDATE work_items SET workflow_template = ?, workflow_snapshot = ?,
+          plan_revision = plan_revision + 1, updated_at = ? WHERE id = ? AND plan_revision = ?`).run(
           transition.workflowSnapshot.id,
           stringify(transition.workflowSnapshot),
           now,
           workItem.id,
+          expectedPlanRevision,
         );
+        if (Number(changedPlan.changes) !== 1) {
+          throw new Error('Work Center plan revision changed before finalization');
+        }
         nextWorkItem = this.getWorkItem(workItem.id);
       }
 
+      for (const patch of Array.isArray(transition.dependencyPatches) ? transition.dependencyPatches : []) {
+        const actionPatch = patch.action;
+        const dependencies = [...new Set([
+          ...(actionPatch.dependsOnStageIds || []),
+          ...(patch.addDependsOnActionIds || []),
+        ])];
+        const changed = this.db.prepare(`UPDATE actions SET depends_on_stage_ids = ?, updated_at = ?
+          WHERE id = ? AND work_item_id = ? AND status = 'ready' AND attempt = 0 AND current_run_id IS NULL`).run(
+          stringify(dependencies), now, actionPatch.id, workItem.id,
+        );
+        if (Number(changed.changes) !== 1) {
+          throw new Error('Work Center dependency patch lost its unattempted Action fence');
+        }
+      }
+
       let nextAction = null;
+      if (transition.replanBarrier) {
+        const barrier = transition.replanBarrier;
+        if (barrier.basePlanRevision !== workItem.planRevision) {
+          throw new Error('Work Center replan request has a stale basePlanRevision');
+        }
+        const activeActions = this.db.prepare(`SELECT * FROM actions WHERE work_item_id = ?
+          AND status NOT IN ('superseded', 'cancelled') ORDER BY sequence`).all(workItem.id).map(mapAction);
+        this.#assertNoIntegrationReservation(activeActions, now);
+        const unfinished = activeActions.filter(candidate => candidate.id !== action.id && candidate.status !== 'completed');
+        for (const candidate of unfinished) {
+          if (candidate.status === 'running' && candidate.currentRunId) {
+            this.db.prepare(`UPDATE runs SET status = 'superseded', ended_at = ?, error = ?
+              WHERE id = ? AND status = 'running'`).run(now, 'Superseded by Work Center replan barrier', candidate.currentRunId);
+          }
+          this.db.prepare(`UPDATE actions SET status = 'superseded', current_run_id = NULL,
+            lease_epoch = lease_epoch + 1, updated_at = ? WHERE id = ? AND status != 'completed'`).run(now, candidate.id);
+        }
+        const replanWorkflow = {
+          ...nextWorkItem.workflowSnapshot,
+          stages: [
+            ...(nextWorkItem.workflowSnapshot?.stages || []).filter(stage => activeActions
+              .some(candidate => candidate.stageId === stage.id && candidate.status === 'completed')),
+            { ...(nextWorkItem.workflowSnapshot?.stages?.[0] || {}), id: barrier.action.stageId, type: 'triage', name: 'Replan' },
+          ],
+        };
+        const changedPlan = this.db.prepare(`UPDATE work_items SET workflow_snapshot = ?, plan_revision = plan_revision + 1,
+          updated_at = ? WHERE id = ? AND plan_revision = ?`).run(
+          stringify(replanWorkflow), now, workItem.id, barrier.basePlanRevision,
+        );
+        if (Number(changedPlan.changes) !== 1) throw new Error('Work Center replan barrier lost its plan revision fence');
+        nextWorkItem = this.getWorkItem(workItem.id);
+        nextAction = this.#insertAction(workItem.id, {
+          ...barrier.action,
+          contractRevision: nextWorkItem.revision,
+          status: 'ready',
+        }, this.#nextSequence(workItem.id), now);
+      }
       if (transition.graphResetStageId) {
         nextAction = this.#resetGraphFromStage(
           workItem.id,
@@ -1382,8 +1459,33 @@ export class WorkItemStore {
       if (Number(changedWorkItem.changes) !== 1) {
         throw new Error('Work Center terminal transition lost the current WorkItem fence');
       }
+      if (transition.workflowSnapshot || transition.replanBarrier) {
+        const proposalId = transition.proposalId || transition.replanBarrier?.proposalId;
+        if (!proposalId) throw new Error('Work Center plan mutation requires proposalId');
+        try {
+          this.db.prepare(`INSERT INTO plan_audits
+            (work_item_id, proposal_id, base_plan_revision, plan_revision, kind, action_id, run_id, data, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+            workItem.id, proposalId, workItem.planRevision, nextWorkItem.planRevision,
+            transition.replanBarrier ? 'replan' : (workItem.planRevision === 0 ? 'initial' : 'expand'),
+            action.id, runId, stringify(transition.eventData || {}), now,
+          );
+        } catch (error) {
+          if (String(error?.message || '').includes('UNIQUE constraint failed')) {
+            throw new Error(`Work Center plan proposal was already applied: ${proposalId}`);
+          }
+          throw error;
+        }
+      }
       this.onTransitionStep?.('before_event');
-      this.appendEvent(workItem.id, transition.eventType, transition.eventData || {}, {
+      this.appendEvent(workItem.id, transition.eventType, {
+        ...(transition.eventData || {}),
+        ...((transition.workflowSnapshot || transition.replanBarrier) ? {
+          proposalId: transition.proposalId || transition.replanBarrier?.proposalId || null,
+          previousPlanRevision: workItem.planRevision,
+          planRevision: nextWorkItem.planRevision,
+        } : {}),
+      }, {
         actionId: action.id,
         runId,
       });

package/yeaft/work-center/workflow.js

@@ -17,7 +17,7 @@ export const BUILT_IN_ACTION_TYPES = Object.freeze([
   'custom',
 ]);
 const STAGE_TYPES = new Set(BUILT_IN_ACTION_TYPES);
-const ASSIGNMENT_MODES = new Set(['auto', 'pool', 'fixed']);
+const ASSIGNMENT_MODES = new Set(['auto', 'pool', 'fixed', 'planned']);
 const MODEL_MODES = new Set(['inherit', 'primary', 'fast', 'specific']);
 const MODEL_EFFORTS = new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
 const WORKSPACE_MODES = new Set(['shared', 'read', 'isolated-write', 'integrate']);
@@ -108,11 +108,29 @@ export const RUN_OUTCOMES = Object.freeze([
   'failed',
 ]);
 
-function cleanId(value, fallback) {
+export function canonicalActionId(value, fallback = '') {
   const normalized = String(value || '').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
   return normalized || fallback;
 }
 
+export function canonicalExplicitActionId(value, field) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`Work Center ${field} contains an empty Action reference`);
+  }
+  const id = canonicalActionId(value);
+  if (!id) {
+    throw new Error(`Work Center ${field} contains an invalid Action reference: ${value}`);
+  }
+  return id;
+}
+
+export function canonicalExplicitActionIds(value, field) {
+  if (!Array.isArray(value)) {
+    throw new Error(`Work Center ${field} must be an array of Action references`);
+  }
+  return [...new Set(value.map(item => canonicalExplicitActionId(item, field)))];
+}
+
 function uniqueStrings(value) {
   if (!Array.isArray(value)) return [];
   return [...new Set(value.map(item => String(item || '').trim()).filter(Boolean))];
@@ -126,12 +144,17 @@ export function normalizeAssignmentPolicy(value, stageType = 'custom') {
     : null;
   const candidateVpIds = uniqueStrings(source.candidateVpIds);
   if (mode === 'fixed' && !fixedVpId) throw new Error('Fixed Work Center assignment requires fixedVpId');
-  if (mode === 'pool' && candidateVpIds.length === 0) throw new Error('Work Center VP pool cannot be empty');
+  if (['pool', 'planned'].includes(mode) && candidateVpIds.length === 0) {
+    throw new Error('Work Center VP candidate list cannot be empty');
+  }
   return {
     mode,
-    capability: cleanId(source.capability, stageType),
+    capability: canonicalActionId(source.capability, stageType),
     candidateVpIds,
     fixedVpId,
+    assignmentReason: typeof source.assignmentReason === 'string'
+      ? source.assignmentReason.trim().slice(0, 1_000)
+      : '',
     separateFromStageTypes: uniqueStrings(source.separateFromStageTypes),
   };
 }
@@ -173,14 +196,14 @@ function normalizeGlobalInstructions(value) {
 }
 
 function generatedActionType(value) {
-  return cleanId(value, 'custom').slice(0, 64);
+  return canonicalActionId(value, 'custom').slice(0, 64);
 }
 
 export function normalizeWorkflowDefinition(value, index = 0) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new Error('Work Center workflow must be an object');
   }
-  const id = cleanId(value.id, `workflow-${index + 1}`);
+  const id = canonicalActionId(value.id, `workflow-${index + 1}`);
   const name = String(value.name || id).trim() || id;
   if (!Array.isArray(value.stages) || value.stages.length === 0) {
     throw new Error(`Work Center workflow "${id}" requires at least one stage`);
@@ -193,7 +216,7 @@ export function normalizeWorkflowDefinition(value, index = 0) {
     const type = planningMode === 'ai'
       ? generatedActionType(source.type)
       : (STAGE_TYPES.has(source.type) ? source.type : 'custom');
-    const stageId = cleanId(source.id, `${type}-${stageIndex + 1}`);
+    const stageId = canonicalActionId(source.id, `${type}-${stageIndex + 1}`);
     if (seen.has(stageId)) throw new Error(`Duplicate Work Center stage id: ${stageId}`);
     seen.add(stageId);
     const stage = {
@@ -211,7 +234,7 @@ export function normalizeWorkflowDefinition(value, index = 0) {
       maxAttempts: Math.min(Math.max(Number(source.maxAttempts) || 2, 1), 5),
     };
     if (type === 'review') {
-      stage.changesRequestedStageId = cleanId(source.changesRequestedStageId, 'implement');
+      stage.changesRequestedStageId = canonicalActionId(source.changesRequestedStageId, 'implement');
     }
     return stage;
   });
@@ -233,7 +256,7 @@ export function normalizeWorkflowDefinition(value, index = 0) {
     planningMode,
     executionMode,
     workItemType: typeof value.workItemType === 'string' && value.workItemType.trim()
-      ? cleanId(value.workItemType, 'general')
+      ? canonicalActionId(value.workItemType, 'general')
       : null,
     globalInstructions: normalizeGlobalInstructions(value.globalInstructions),
     modelPolicy: normalizeModelPolicy(value.modelPolicy),
@@ -324,7 +347,7 @@ export function resolvePlanningWorkflowSnapshot(settings, requestedWorkItemType
   const requestedType = typeof requestedWorkItemType === 'string'
     && requestedWorkItemType.trim()
     && requestedWorkItemType.trim().toLowerCase() !== 'auto'
-    ? cleanId(requestedWorkItemType, '').slice(0, 64)
+    ? canonicalActionId(requestedWorkItemType, '').slice(0, 64)
     : '';
   const actionTemplates = normalized.workflows.map(workflow => normalizeWorkflowDefinition({
     ...workflow,
@@ -394,8 +417,9 @@ export function resolveWorkflowSnapshot(settings, workflowId, stageOverrides = {
   });
 }
 
-export function applyGeneratedPlan(workItem, rawPlan) {
+export function applyGeneratedPlan(workItem, rawPlan, options = {}) {
   const source = workflowFrom(workItem);
+  const forceGraph = options.forceGraph !== false;
   if (source.planningMode !== 'ai') return source;
   if (!rawPlan || typeof rawPlan !== 'object' || Array.isArray(rawPlan)) {
     throw new Error('AI-planned triage requires a structured plan');
@@ -403,17 +427,23 @@ export function applyGeneratedPlan(workItem, rawPlan) {
   if (typeof rawPlan.workItemType !== 'string' || !rawPlan.workItemType.trim()) {
     throw new Error('AI-planned triage requires a specific workItemType');
   }
-  const workItemType = cleanId(rawPlan.workItemType, '').slice(0, 64);
+  const workItemType = canonicalActionId(rawPlan.workItemType, '').slice(0, 64);
   if (!workItemType) throw new Error('AI-planned triage requires a valid workItemType');
   if (source.workItemType && workItemType !== source.workItemType) {
     throw new Error(`AI-planned triage must keep the selected workItemType "${source.workItemType}"`);
   }
+  const reservedStageIds = new Set((options.reservedStageIds || [])
+    .map(id => String(id || '').trim()).filter(Boolean));
   const reusableTemplate = source.actionTemplates.find(template => template.workItemType === workItemType);
   if (reusableTemplate) {
     const templateActions = reusableTemplate.stages.filter(stage => stage.type !== 'triage');
     if (templateActions.length === 0) {
       throw new Error(`Reusable Action template "${workItemType}" has no executable Actions`);
     }
+    const reusedStageId = templateActions.find(stage => reservedStageIds.has(stage.id))?.id;
+    if (reusedStageId) {
+      throw new Error(`AI-planned Action id reuses historical stage identity: ${reusedStageId}`);
+    }
     return normalizeWorkflowDefinition({
       ...source,
       workItemType,
@@ -424,14 +454,20 @@ export function applyGeneratedPlan(workItem, rawPlan) {
   if (!Array.isArray(rawPlan.actions) || rawPlan.actions.length < 1 || rawPlan.actions.length > 8) {
     throw new Error('AI-planned triage requires between 1 and 8 Actions when no reusable template exists');
   }
+  const availableVpIds = Array.isArray(options.availableVpIds)
+    ? new Set(options.availableVpIds.map(id => String(id || '').trim()).filter(Boolean))
+    : null;
   const seen = new Set(['triage']);
   let previousGeneratedId = null;
   const generated = rawPlan.actions.map((rawAction, index) => {
     const input = rawAction && typeof rawAction === 'object' && !Array.isArray(rawAction) ? rawAction : {};
     const type = generatedActionType(input.type);
     if (type === 'triage') throw new Error('AI-planned Actions cannot add another triage Action');
-    const id = cleanId(input.id, `${type}-${index + 1}`);
+    const id = canonicalActionId(input.id, `${type}-${index + 1}`);
     if (seen.has(id)) throw new Error(`Duplicate AI-planned Action id: ${id}`);
+    if (reservedStageIds.has(id)) {
+      throw new Error(`AI-planned Action id reuses historical stage identity: ${id}`);
+    }
     seen.add(id);
     const objective = typeof input.objective === 'string' ? input.objective.trim().slice(0, 2_000) : '';
     if (!objective) throw new Error(`AI-planned Action "${id}" requires a task-specific objective`);
@@ -451,6 +487,17 @@ export function applyGeneratedPlan(workItem, rawPlan) {
     const actionInstruction = Object.hasOwn(source.actionInstructions, type)
       ? source.actionInstructions[type]
       : source.actionInstructions.custom;
+    const candidateVpIds = uniqueStrings(input.candidateVpIds);
+    if (candidateVpIds.length > 0 && availableVpIds) {
+      const unavailable = candidateVpIds.find(vpId => !availableVpIds.has(vpId));
+      if (unavailable) throw new Error(`AI-planned Action "${id}" references unavailable VP "${unavailable}"`);
+    }
+    const assignmentReason = typeof input.assignmentReason === 'string'
+      ? input.assignmentReason.trim().slice(0, 1_000)
+      : '';
+    if (candidateVpIds.length > 0 && !assignmentReason) {
+      throw new Error(`AI-planned Action "${id}" requires an assignmentReason`);
+    }
     const stage = {
       id,
       name: String(input.name || id).trim().slice(0, 120) || id,
@@ -459,25 +506,37 @@ export function applyGeneratedPlan(workItem, rawPlan) {
       approach,
       expectedOutcome,
       instruction: actionInstruction,
-      assignmentPolicy: {
+      assignmentPolicy: candidateVpIds.length > 0 ? {
+        mode: 'planned',
+        capability: canonicalActionId(input.capability, type),
+        candidateVpIds,
+        fixedVpId: null,
+        assignmentReason,
+        separateFromStageTypes: uniqueStrings(input.separateFromActionTypes),
+      } : {
         mode: 'auto',
-        capability: cleanId(input.capability, type),
+        capability: canonicalActionId(input.capability, type),
         candidateVpIds: [],
         fixedVpId: null,
+        assignmentReason: '',
         separateFromStageTypes: uniqueStrings(input.separateFromActionTypes),
       },
       modelPolicy: source.actionModelPolicies[type] || source.actionModelPolicies.custom,
       dependsOnStageIds: Object.hasOwn(input, 'dependsOnActionIds')
-        ? uniqueStrings(input.dependsOnActionIds)
+        ? canonicalExplicitActionIds(
+          input.dependsOnActionIds,
+          `Action "${id}" dependencies`,
+        )
         : (previousGeneratedId ? [previousGeneratedId] : []),
       workspaceMode: WORKSPACE_MODES.has(input.workspaceMode) ? input.workspaceMode : 'shared',
       maxAttempts: Math.min(Math.max(Number(input.maxAttempts) || 2, 1), 5),
     };
     previousGeneratedId = id;
-    if (type === 'review' && Object.prototype.hasOwnProperty.call(input, 'changesRequestedActionId')) {
-      stage.changesRequestedStageId = typeof input.changesRequestedActionId === 'string'
-        ? cleanId(input.changesRequestedActionId, '')
-        : '';
+    if (type === 'review' && Object.hasOwn(input, 'changesRequestedActionId')) {
+      stage.changesRequestedStageId = canonicalExplicitActionId(
+        input.changesRequestedActionId,
+        `Action "${id}" review target`,
+      );
     }
     return stage;
   });
@@ -497,6 +556,14 @@ export function applyGeneratedPlan(workItem, rawPlan) {
     if (!stage.changesRequestedStageId) {
       throw new Error(`AI-planned review Action "${stage.id}" requires an earlier editable Action`);
     }
+    const returnTarget = candidates.find(candidate => candidate.id === stage.changesRequestedStageId);
+    stage.assignmentPolicy = {
+      ...stage.assignmentPolicy,
+      separateFromStageTypes: uniqueStrings([
+        ...(stage.assignmentPolicy.separateFromStageTypes || []),
+        returnTarget.type,
+      ]),
+    };
   }
   const hasIsolatedWrites = generated.some(stage => stage.workspaceMode === 'isolated-write');
   const integrationStages = generated.filter(stage => stage.workspaceMode === 'integrate');
@@ -530,7 +597,7 @@ export function applyGeneratedPlan(workItem, rawPlan) {
   }
   return normalizeWorkflowDefinition({
     ...source,
-    executionMode: 'graph',
+    executionMode: forceGraph ? 'graph' : source.executionMode,
     workItemType,
     stages: [source.stages[0], ...generated],
   });