@chllming/wave-orchestration 0.8.3 → 0.8.5

package/scripts/wave-orchestrator/{launcher-retry.mjs → retry-engine.mjs}

@@ -8,7 +8,7 @@ import {
   readClarificationBarrier,
   readWaveAssignmentBarrier,
   readWaveDependencyBarrier,
-} from "./launcher-gates.mjs";
+} from "./gate-engine.mjs";
 import {
   isOpenCoordinationStatus,
   openClarificationLinkedRequests,
@@ -20,6 +20,7 @@ import {
 } from "./shared.mjs";
 import {
   readAgentExecutionSummary,
+  validateDesignSummary,
   validateImplementationSummary,
 } from "./agent-state.mjs";
 import {
@@ -32,7 +33,11 @@ import {
 } from "./proof-registry.mjs";
 import { hashAgentPromptFingerprint } from "./context7.mjs";
 import {
+  isDocsOnlyDesignAgent,
+  isDesignAgent,
+  isImplementationOwningDesignAgent,
   isSecurityReviewAgent,
+  resolveWaveRoleBindings,
 } from "./role-helpers.mjs";
 import {
   commandForExecutor,
@@ -121,6 +126,7 @@ export function persistedRelaunchPlanMatchesCurrentState(
   }
   const componentGate = readWaveComponentGate(waveDefinition, agentRuns, {
     laneProfile: lanePaths?.laneProfile,
+    mode: "live",
   });
   if (componentGate?.statusCode !== "shared-component-sibling-pending") {
     return true;
@@ -271,7 +277,10 @@ export function reconcileFailuresAgainstSharedComponentState(wave, agentRuns, fa
     return failures;
   }
   const summariesByAgentId = Object.fromEntries(
-    (agentRuns || []).map((runInfo) => [runInfo.agent.agentId, readRunExecutionSummary(runInfo, wave)]),
+    (agentRuns || []).map((runInfo) => [
+      runInfo.agent.agentId,
+      readRunExecutionSummary(runInfo, wave, { mode: "live" }),
+    ]),
   );
   const failureAgentIds = new Set(failures.map((failure) => failure.agentId).filter(Boolean));
   const consumedSatisfiedAgentIds = new Set();
@@ -310,6 +319,28 @@ export function hasReusableSuccessStatus(agent, statusPath, options = {}) {
   if (!basicReuseOk) {
     return false;
   }
+  if (isDocsOnlyDesignAgent(agent) || isImplementationOwningDesignAgent(agent)) {
+    const summary = readAgentExecutionSummary(statusPath, {
+      agent,
+      statusPath,
+      statusRecord,
+      logPath: options.logPath || null,
+      reportPath: options.reportPath || null,
+    });
+    if (!summary) {
+      return false;
+    }
+    const effectiveSummary = options.proofRegistry
+      ? augmentSummaryWithProofRegistry(agent, summary, options.proofRegistry)
+      : summary;
+    if (isDocsOnlyDesignAgent(agent)) {
+      return validateDesignSummary(agent, effectiveSummary).ok;
+    }
+    return (
+      validateDesignSummary(agent, effectiveSummary).ok &&
+      validateImplementationSummary(agent, effectiveSummary).ok
+    );
+  }
   const proofCentric =
     agentRequiresProofCentricValidation(agent) || waveRequiresProofCentricValidation(options.wave);
   if (!proofCentric) {
@@ -337,13 +368,43 @@ export function hasReusableSuccessStatus(agent, statusPath, options = {}) {
   return true;
 }
 
-function isClosureAgentId(agent, lanePaths) {
-  return [
-    lanePaths.contEvalAgentId || "E0",
-    lanePaths.integrationAgentId || "A8",
-    lanePaths.documentationAgentId || "A9",
-    lanePaths.contQaAgentId || "A0",
-  ].includes(agent?.agentId) || isSecurityReviewAgent(agent);
+function hasReusableDesignPassStatus(agent, statusPath, options = {}) {
+  if (!isDesignAgent(agent)) {
+    return hasReusableSuccessStatus(agent, statusPath, options);
+  }
+  const statusRecord = readStatusRecordIfPresent(statusPath);
+  const basicReuseOk = Boolean(
+    statusRecord && statusRecord.code === 0 && statusRecord.promptHash === hashAgentPromptFingerprint(agent),
+  );
+  if (!basicReuseOk) {
+    return false;
+  }
+  const summary = readAgentExecutionSummary(statusPath, {
+    agent: {
+      ...agent,
+      exitContract: null,
+      components: [],
+      componentTargets: {},
+      deliverables: [],
+      proofArtifacts: [],
+    },
+    statusPath,
+    statusRecord,
+    logPath: options.logPath || null,
+    reportPath: options.reportPath || null,
+  });
+  if (!summary) {
+    return false;
+  }
+  return validateDesignSummary(agent, summary).ok;
+}
+
+function isClosureAgentId(agent, lanePaths, waveDefinition = null) {
+  return (
+    resolveWaveRoleBindings(waveDefinition, lanePaths, waveDefinition?.agents).closureAgentIds.includes(
+      agent?.agentId,
+    ) || isSecurityReviewAgent(agent)
+  );
 }
 
 export function selectReusablePreCompletedAgentIds(
@@ -357,7 +418,7 @@ export function selectReusablePreCompletedAgentIds(
       .filter(
         (run) =>
           !retryOverrideClearedAgentIds.has(run.agent.agentId) &&
-          !isClosureAgentId(run.agent, lanePaths) &&
+          !isClosureAgentId(run.agent, lanePaths, wave) &&
           hasReusableSuccessStatus(run.agent, run.statusPath, {
             wave,
             derivedState,
@@ -369,10 +430,27 @@ export function selectReusablePreCompletedAgentIds(
   );
 }
 
-export function selectInitialWaveRuns(agentRuns, lanePaths) {
+export function selectInitialWaveRuns(agentRuns, lanePaths, waveDefinition = null) {
   const implementationRuns = (agentRuns || []).filter(
-    (run) => !isClosureAgentId(run?.agent, lanePaths),
+    (run) => !isClosureAgentId(run?.agent, lanePaths, waveDefinition),
+  );
+  const pendingDesignRuns = implementationRuns.filter(
+    (run) =>
+      isDesignAgent(run.agent) &&
+      !hasReusableDesignPassStatus(run.agent, run.statusPath, {
+        wave: waveDefinition,
+        logPath: run.logPath,
+      }),
   );
+  if (pendingDesignRuns.length > 0) {
+    return pendingDesignRuns;
+  }
+  const implementationFanoutRuns = implementationRuns.filter(
+    (run) => !isDocsOnlyDesignAgent(run.agent),
+  );
+  if (implementationFanoutRuns.length > 0) {
+    return implementationFanoutRuns;
+  }
   return implementationRuns.length > 0 ? implementationRuns : agentRuns;
 }
 
@@ -560,7 +638,38 @@ function retryBarrierFromOutcomes(outcomes, failures) {
   };
 }
 
-export function resolveRelaunchRuns(agentRuns, failures, derivedState, lanePaths, waveDefinition = null) {
+function runsFromAgentIds(agentRuns, agentIds) {
+  const runsByAgentId = new Map((agentRuns || []).map((run) => [run.agent.agentId, run]));
+  return Array.from(new Set((agentIds || []).filter(Boolean)))
+    .map((agentId) => runsByAgentId.get(agentId))
+    .filter(Boolean);
+}
+
+function resolveRunsForResumePhase(agentRuns, lanePaths, resumePhase, waveDefinition = null) {
+  const roleBindings = resolveWaveRoleBindings(waveDefinition, lanePaths, waveDefinition?.agents);
+  if (resumePhase === "design") {
+    return (agentRuns || []).filter((run) => isDesignAgent(run.agent));
+  }
+  if (resumePhase === "integrating") {
+    return runsFromAgentIds(agentRuns, [roleBindings.integrationAgentId]);
+  }
+  if (resumePhase === "security-review") {
+    return (agentRuns || []).filter((run) => isSecurityReviewAgent(run.agent));
+  }
+  if (resumePhase === "docs-closure") {
+    return runsFromAgentIds(agentRuns, [roleBindings.documentationAgentId]);
+  }
+  if (resumePhase === "cont-qa-closure") {
+    return runsFromAgentIds(agentRuns, [roleBindings.contQaAgentId]);
+  }
+  if (resumePhase === "cont-eval") {
+    return runsFromAgentIds(agentRuns, [roleBindings.contEvalAgentId]);
+  }
+  return [];
+}
+
+function resolveRelaunchRunsLegacy(agentRuns, failures, derivedState, lanePaths, waveDefinition = null) {
+  const roleBindings = resolveWaveRoleBindings(waveDefinition, lanePaths, waveDefinition?.agents);
   const runsByAgentId = new Map(agentRuns.map((run) => [run.agent.agentId, run]));
   const pendingFeedback = (derivedState?.coordinationState?.humanFeedback || []).filter((record) =>
     isOpenCoordinationStatus(record.status),
@@ -693,7 +802,13 @@ export function resolveRelaunchRuns(agentRuns, failures, derivedState, lanePaths
   }
   if (derivedState?.ledger?.phase === "docs-closure") {
     return {
-      runs: [runsByAgentId.get(lanePaths.documentationAgentId)].filter(Boolean),
+      runs: [runsByAgentId.get(roleBindings.documentationAgentId)].filter(Boolean),
+      barrier: null,
+    };
+  }
+  if (derivedState?.ledger?.phase === "design") {
+    return {
+      runs: agentRuns.filter((run) => isDesignAgent(run.agent)),
       barrier: null,
     };
   }
@@ -705,19 +820,19 @@ export function resolveRelaunchRuns(agentRuns, failures, derivedState, lanePaths
   }
   if (derivedState?.ledger?.phase === "cont-eval") {
     return {
-      runs: [runsByAgentId.get(lanePaths.contEvalAgentId)].filter(Boolean),
+      runs: [runsByAgentId.get(roleBindings.contEvalAgentId)].filter(Boolean),
       barrier: null,
     };
   }
   if (derivedState?.ledger?.phase === "cont-qa-closure") {
     return {
-      runs: [runsByAgentId.get(lanePaths.contQaAgentId)].filter(Boolean),
+      runs: [runsByAgentId.get(roleBindings.contQaAgentId)].filter(Boolean),
       barrier: null,
     };
   }
   if (derivedState?.ledger?.phase === "integrating") {
     return {
-      runs: [runsByAgentId.get(lanePaths.integrationAgentId)].filter(Boolean),
+      runs: [runsByAgentId.get(roleBindings.integrationAgentId)].filter(Boolean),
       barrier: null,
     };
   }
@@ -742,6 +857,216 @@ export function resolveRelaunchRuns(agentRuns, failures, derivedState, lanePaths
   };
 }
 
+function resolveRelaunchRunsFromWaveState(
+  agentRuns,
+  failures,
+  derivedState,
+  lanePaths,
+  waveDefinition,
+  waveState,
+) {
+  const roleBindings = resolveWaveRoleBindings(waveDefinition, lanePaths, waveDefinition?.agents);
+  const pendingFeedback = (waveState?.coordinationState?.humanFeedback || []).filter((record) =>
+    isOpenCoordinationStatus(record.status),
+  );
+  const pendingHumanEscalations = (waveState?.coordinationState?.humanEscalations || []).filter(
+    (record) => isOpenCoordinationStatus(record.status),
+  );
+  if (pendingFeedback.length > 0 || pendingHumanEscalations.length > 0) {
+    return { runs: [], barrier: null };
+  }
+
+  const nextAttemptNumber = Number(derivedState?.ledger?.attempt || 0) + 1;
+  const fallbackResolution = applyRetryFallbacks(
+    agentRuns,
+    failures,
+    lanePaths,
+    nextAttemptNumber,
+    waveDefinition,
+  );
+  const retryBarrier = retryBarrierFromOutcomes(fallbackResolution.outcomes, failures);
+  if (retryBarrier) {
+    return { runs: [], barrier: retryBarrier };
+  }
+
+  const clarificationTargets = new Set();
+  for (const record of openClarificationLinkedRequests(waveState?.coordinationState)) {
+    for (const target of record.targets || []) {
+      if (String(target).startsWith("agent:")) {
+        clarificationTargets.add(String(target).slice("agent:".length));
+      } else {
+        clarificationTargets.add(target);
+      }
+    }
+  }
+  if (clarificationTargets.size > 0) {
+    return {
+      runs: runsFromAgentIds(agentRuns, Array.from(clarificationTargets)),
+      barrier: null,
+    };
+  }
+
+  const blockingAssignments = (waveState?.capabilityAssignments || []).filter(
+    (assignment) => assignment.blocking,
+  );
+  if (blockingAssignments.length > 0) {
+    const unresolvedAssignments = blockingAssignments.filter((assignment) => !assignment.assignedAgentId);
+    if (unresolvedAssignments.length > 0) {
+      return {
+        runs: [],
+        barrier: {
+          statusCode: "helper-assignment-unresolved",
+          detail: `No matching assignee exists for helper requests (${unresolvedAssignments.map((assignment) => assignment.requestId).join(", ")}).`,
+          failures: unresolvedAssignments.map((assignment) => ({
+            agentId: null,
+            statusCode: "helper-assignment-unresolved",
+            logPath: null,
+            detail: assignment.assignmentDetail || assignment.summary || assignment.requestId,
+          })),
+        },
+      };
+    }
+    return {
+      runs: runsFromAgentIds(
+        agentRuns,
+        blockingAssignments.map((assignment) => assignment.assignedAgentId),
+      ),
+      barrier: null,
+    };
+  }
+
+  const unresolvedInboundAssignments =
+    waveState?.dependencySnapshot?.unresolvedInboundAssignments || [];
+  if (unresolvedInboundAssignments.length > 0) {
+    return {
+      runs: [],
+      barrier: {
+        statusCode: "dependency-assignment-unresolved",
+        detail: `Required inbound dependencies are not assigned (${unresolvedInboundAssignments.map((record) => record.id).join(", ")}).`,
+        failures: unresolvedInboundAssignments.map((record) => ({
+          agentId: null,
+          statusCode: "dependency-assignment-unresolved",
+          logPath: null,
+          detail: record.assignmentDetail || record.summary || record.id,
+        })),
+      },
+    };
+  }
+
+  const inboundDependencyAgentIds = new Set(
+    (waveState?.dependencySnapshot?.openInbound || [])
+      .map((record) => record.assignedAgentId)
+      .filter(Boolean),
+  );
+  if (inboundDependencyAgentIds.size > 0) {
+    return {
+      runs: runsFromAgentIds(agentRuns, Array.from(inboundDependencyAgentIds)),
+      barrier: null,
+    };
+  }
+
+  const blockerAgentIds = new Set();
+  for (const record of waveState?.coordinationState?.blockers || []) {
+    if (!isOpenCoordinationStatus(record.status)) {
+      continue;
+    }
+    blockerAgentIds.add(record.agentId);
+    for (const target of record.targets || []) {
+      if (String(target).startsWith("agent:")) {
+        blockerAgentIds.add(String(target).slice("agent:".length));
+      }
+    }
+  }
+  if (blockerAgentIds.size > 0) {
+    return {
+      runs: runsFromAgentIds(agentRuns, Array.from(blockerAgentIds)),
+      barrier: null,
+    };
+  }
+
+  const sharedComponentWaitingAgentIds = new Set(
+    (failures || [])
+      .filter((failure) => failure.statusCode === "shared-component-sibling-pending")
+      .flatMap((failure) => failure.waitingOnAgentIds || [])
+      .filter(Boolean),
+  );
+  if (sharedComponentWaitingAgentIds.size > 0) {
+    return {
+      runs: runsFromAgentIds(agentRuns, Array.from(sharedComponentWaitingAgentIds)),
+      barrier: null,
+    };
+  }
+
+  const resumePlan = buildResumePlan(waveState, {
+    waveDefinition,
+    lanePaths,
+  });
+  if (!resumePlan.canResume || resumePlan.reason === "human-request") {
+    return { runs: [], barrier: null };
+  }
+
+  const phaseRuns = resolveRunsForResumePhase(
+    agentRuns,
+    lanePaths,
+    resumePlan.resumeFromPhase,
+    waveDefinition,
+  );
+  if (phaseRuns.length > 0 && resumePlan.resumeFromPhase !== "implementation") {
+    return {
+      runs: phaseRuns,
+      barrier: null,
+    };
+  }
+
+  const retryTargetAgentIds = normalizeRetryTargets(waveState?.retryTargetSet).map(
+    (target) => target.agentId,
+  );
+  const implementationAgentIds =
+    resumePlan.invalidatedAgentIds.length > 0
+      ? resumePlan.invalidatedAgentIds
+      : retryTargetAgentIds;
+  if (implementationAgentIds.length > 0) {
+    return {
+      runs: runsFromAgentIds(agentRuns, implementationAgentIds),
+      barrier: null,
+    };
+  }
+
+  const failedAgentIds = new Set(failures.map((failure) => failure.agentId));
+  return {
+    runs: agentRuns.filter((run) => failedAgentIds.has(run.agent.agentId)),
+    barrier: null,
+  };
+}
+
+export function resolveRelaunchRuns(
+  agentRuns,
+  failures,
+  derivedState,
+  lanePaths,
+  waveDefinition = null,
+  options = {},
+) {
+  const waveState = options?.waveState || null;
+  if (!waveState) {
+    return resolveRelaunchRunsLegacy(
+      agentRuns,
+      failures,
+      derivedState,
+      lanePaths,
+      waveDefinition,
+    );
+  }
+  return resolveRelaunchRunsFromWaveState(
+    agentRuns,
+    failures,
+    derivedState,
+    lanePaths,
+    waveDefinition,
+    waveState,
+  );
+}
+
 export function preflightWavesForExecutorAvailability(waves, lanePaths) {
   for (const wave of waves) {
     const mixValidation = validateWaveRuntimeMixAssignments(wave, {
@@ -776,12 +1101,21 @@ export function preflightWavesForExecutorAvailability(waves, lanePaths) {
 
 function phaseFromGate(gateName) {
   switch (gateName) {
+    case "designGate":
+      return "design";
     case "implementationGate":
     case "componentGate":
-    case "contEvalGate":
+    case "helperAssignmentBarrier":
+    case "dependencyBarrier":
+    case "clarificationBarrier":
       return "implementation";
+    case "contEvalGate":
+      return "cont-eval";
+    case "securityGate":
+      return "security-review";
     case "integrationBarrier":
       return "integrating";
+    case "componentMatrixGate":
     case "documentationGate":
       return "docs-closure";
     case "contQaGate":

package/scripts/wave-orchestrator/role-helpers.mjs

@@ -1,5 +1,9 @@
 import {
+  DEFAULT_CONT_QA_AGENT_ID,
   DEFAULT_CONT_EVAL_AGENT_ID,
+  DEFAULT_DESIGN_ROLE_PROMPT_PATH,
+  DEFAULT_DOCUMENTATION_AGENT_ID,
+  DEFAULT_INTEGRATION_AGENT_ID,
   DEFAULT_SECURITY_ROLE_PROMPT_PATH,
 } from "./config.mjs";
 
@@ -34,6 +38,29 @@ export function isSecurityReportPath(relPath) {
   return /(?:^|\/).*security.*\.(?:md|txt)$/i.test(cleanPath(relPath));
 }
 
+export function isDesignRolePromptPath(
+  relPath,
+  designRolePromptPath = DEFAULT_DESIGN_ROLE_PROMPT_PATH,
+) {
+  const normalized = cleanPath(relPath);
+  const configured = cleanPath(designRolePromptPath);
+  return (
+    normalized === configured ||
+    normalized === DEFAULT_DESIGN_ROLE_PROMPT_PATH ||
+    normalized.endsWith("/wave-design-role.md")
+  );
+}
+
+export function isDesignReportPath(relPath) {
+  return /(?:^|\/).*(?:design|handoff|decision-lineage).*\.(?:md|txt)$/i.test(cleanPath(relPath));
+}
+
+function normalizedOwnedPaths(agent) {
+  return Array.isArray(agent?.ownedPaths)
+    ? agent.ownedPaths.map(cleanPath).filter(Boolean)
+    : [];
+}
+
 export function isContEvalImplementationOwningAgent(
   agent,
   { contEvalAgentId = DEFAULT_CONT_EVAL_AGENT_ID } = {},
@@ -78,7 +105,103 @@ export function isSecurityReviewAgent(
   return capabilities.includes("security-review");
 }
 
+export function isDesignAgent(
+  agent,
+  { designRolePromptPath = DEFAULT_DESIGN_ROLE_PROMPT_PATH } = {},
+) {
+  if (!agent || typeof agent !== "object") {
+    return false;
+  }
+  const rolePromptPaths = Array.isArray(agent.rolePromptPaths) ? agent.rolePromptPaths : [];
+  if (
+    rolePromptPaths.some((rolePromptPath) =>
+      isDesignRolePromptPath(rolePromptPath, designRolePromptPath),
+    )
+  ) {
+    return true;
+  }
+  const capabilities = Array.isArray(agent.capabilities)
+    ? agent.capabilities.map((entry) => String(entry || "").trim().toLowerCase())
+    : [];
+  return capabilities.includes("design");
+}
+
+export function isImplementationOwningDesignAgent(
+  agent,
+  { designRolePromptPath = DEFAULT_DESIGN_ROLE_PROMPT_PATH } = {},
+) {
+  if (!isDesignAgent(agent, { designRolePromptPath })) {
+    return false;
+  }
+  const ownedPaths = normalizedOwnedPaths(agent);
+  if (ownedPaths.length === 0) {
+    return false;
+  }
+  return ownedPaths.some((ownedPath) => !isDesignReportPath(ownedPath));
+}
+
+export function isDocsOnlyDesignAgent(
+  agent,
+  { designRolePromptPath = DEFAULT_DESIGN_ROLE_PROMPT_PATH } = {},
+) {
+  return isDesignAgent(agent, { designRolePromptPath }) &&
+    !isImplementationOwningDesignAgent(agent, { designRolePromptPath });
+}
+
 export function resolveSecurityReviewReportPath(agent) {
-  const ownedPaths = Array.isArray(agent?.ownedPaths) ? agent.ownedPaths.map(cleanPath).filter(Boolean) : [];
+  const ownedPaths = normalizedOwnedPaths(agent);
   return ownedPaths.find((ownedPath) => isSecurityReportPath(ownedPath)) || null;
 }
+
+export function resolveDesignReportPath(agent) {
+  const ownedPaths = normalizedOwnedPaths(agent);
+  return ownedPaths.find((ownedPath) => isDesignReportPath(ownedPath)) || null;
+}
+
+export function resolveWaveRoleBindings(wave = {}, lanePaths = {}, agents = wave?.agents || []) {
+  const contQaAgentId =
+    wave?.contQaAgentId || lanePaths?.contQaAgentId || DEFAULT_CONT_QA_AGENT_ID;
+  const contEvalAgentId =
+    wave?.contEvalAgentId || lanePaths?.contEvalAgentId || DEFAULT_CONT_EVAL_AGENT_ID;
+  const integrationAgentId =
+    wave?.integrationAgentId || lanePaths?.integrationAgentId || DEFAULT_INTEGRATION_AGENT_ID;
+  const documentationAgentId =
+    wave?.documentationAgentId ||
+    lanePaths?.documentationAgentId ||
+    DEFAULT_DOCUMENTATION_AGENT_ID;
+  const securityReviewerAgentIds = Array.from(
+    new Set(
+      (Array.isArray(agents) ? agents : [])
+        .filter((agent) =>
+          isSecurityReviewAgent(agent, {
+            securityRolePromptPath: lanePaths?.securityRolePromptPath,
+          }),
+        )
+        .map((agent) => agent.agentId)
+        .filter(Boolean),
+    ),
+  ).sort();
+  const closureAgentIds = Array.from(
+    new Set(
+      [
+        contEvalAgentId,
+        integrationAgentId,
+        documentationAgentId,
+        contQaAgentId,
+        ...securityReviewerAgentIds,
+      ].filter(Boolean),
+    ),
+  ).sort();
+  return {
+    contQaAgentId,
+    contEvalAgentId,
+    integrationAgentId,
+    documentationAgentId,
+    securityReviewerAgentIds,
+    closureAgentIds,
+  };
+}
+
+export function isClosureRoleAgentId(agentId, roleBindings) {
+  return (roleBindings?.closureAgentIds || []).includes(agentId);
+}