@chllming/wave-orchestration 0.8.3 → 0.8.5

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

@@ -5,8 +5,17 @@ import {
   setWaveDashboardAgent,
   updateWaveDashboardMessageBoard,
 } from "./dashboard-state.mjs";
+import {
+  materializeAgentExecutionSummaryForRun as materializeAgentExecutionSummaryForRunDefault,
+  readWaveComponentMatrixGate as readWaveComponentMatrixGateDefault,
+  readWaveContEvalGate as readWaveContEvalGateDefault,
+  readWaveContQaGate as readWaveContQaGateDefault,
+  readWaveDocumentationGate as readWaveDocumentationGateDefault,
+  readWaveIntegrationBarrier as readWaveIntegrationBarrierDefault,
+  readWaveSecurityGate as readWaveSecurityGateDefault,
+} from "./gate-engine.mjs";
 import { REPO_ROOT, toIsoTimestamp } from "./shared.mjs";
-import { isSecurityReviewAgent } from "./role-helpers.mjs";
+import { isSecurityReviewAgent, resolveWaveRoleBindings } from "./role-helpers.mjs";
 import { summarizeResolvedSkills } from "./skills.mjs";
 
 function failureResultFromGate(gate, fallbackLogPath) {
@@ -71,76 +80,41 @@ export async function runClosureSweepPhase({
   materializeAgentExecutionSummaryForRunFn,
   monitorWaveHumanFeedbackFn,
 }) {
-  const contQaAgentId = wave.contQaAgentId || "A0";
-  const contEvalAgentId = wave.contEvalAgentId || lanePaths.contEvalAgentId || "E0";
-  const integrationAgentId = wave.integrationAgentId || lanePaths.integrationAgentId || "A8";
-  const documentationAgentId = wave.documentationAgentId || "A9";
-  const stagedRuns = [
-    {
-      agentId: contEvalAgentId,
-      label: "cont-EVAL gate",
-      runs: closureRuns.filter((run) => run.agent.agentId === contEvalAgentId),
-      validate: () =>
-        readWaveContEvalGateFn(wave, closureRuns, {
-          contEvalAgentId,
-          mode: "live",
-          evalTargets: wave.evalTargets,
-          benchmarkCatalogPath: lanePaths.laneProfile?.paths?.benchmarkCatalogPath,
-        }),
-      actionRequested:
-        `Lane ${lanePaths.lane} owners should resolve cont-EVAL tuning gaps before integration closure.`,
-    },
-    {
-      agentId: "security",
-      label: "Security review",
-      runs: closureRuns.filter((run) => isSecurityReviewAgent(run.agent)),
-      validate: () => readWaveSecurityGateFn(wave, closureRuns),
-      actionRequested:
-        `Lane ${lanePaths.lane} owners should resolve blocked security findings or missing approvals before integration closure.`,
-    },
-    {
-      agentId: integrationAgentId,
-      label: "Integration gate",
-      runs: closureRuns.filter((run) => run.agent.agentId === integrationAgentId),
-      validate: () =>
-        readWaveIntegrationBarrierFn(
-          wave,
-          closureRuns,
-          refreshDerivedState?.(dashboardState?.attempt || 0),
-          {
-            integrationAgentId,
-            requireIntegrationStewardFromWave: lanePaths.requireIntegrationStewardFromWave,
-          },
-        ),
-      actionRequested:
-        `Lane ${lanePaths.lane} owners should resolve integration contradictions or blockers before documentation and cont-QA closure.`,
-    },
-    {
-      agentId: documentationAgentId,
-      label: "Documentation closure",
-      runs: closureRuns.filter((run) => run.agent.agentId === documentationAgentId),
-      validate: () => {
-        const documentationGate = readWaveDocumentationGateFn(wave, closureRuns);
-        if (!documentationGate.ok) {
-          return documentationGate;
-        }
-        return readWaveComponentMatrixGateFn(wave, closureRuns, {
-          laneProfile: lanePaths.laneProfile,
-          documentationAgentId,
-        });
-      },
-      actionRequested:
-        `Lane ${lanePaths.lane} owners should resolve the shared-plan or component-matrix closure state before cont-QA progression.`,
-    },
-    {
-      agentId: contQaAgentId,
-      label: "cont-QA gate",
-      runs: closureRuns.filter((run) => run.agent.agentId === contQaAgentId),
-      validate: () => readWaveContQaGateFn(wave, closureRuns, { contQaAgentId, mode: "live" }),
-      actionRequested:
-        `Lane ${lanePaths.lane} owners should resolve the cont-QA gate before wave progression.`,
-    },
-  ];
+  const materializeSummary =
+    typeof materializeAgentExecutionSummaryForRunFn === "function"
+      ? materializeAgentExecutionSummaryForRunFn
+      : materializeAgentExecutionSummaryForRunDefault;
+  const monitorHumanFeedback =
+    typeof monitorWaveHumanFeedbackFn === "function"
+      ? monitorWaveHumanFeedbackFn
+      : () => false;
+  const readContEvalGate =
+    typeof readWaveContEvalGateFn === "function"
+      ? readWaveContEvalGateFn
+      : readWaveContEvalGateDefault;
+  const readSecurityGate =
+    typeof readWaveSecurityGateFn === "function"
+      ? readWaveSecurityGateFn
+      : readWaveSecurityGateDefault;
+  const readIntegrationBarrier =
+    typeof readWaveIntegrationBarrierFn === "function"
+      ? readWaveIntegrationBarrierFn
+      : readWaveIntegrationBarrierDefault;
+  const readDocumentationGate =
+    typeof readWaveDocumentationGateFn === "function"
+      ? readWaveDocumentationGateFn
+      : readWaveDocumentationGateDefault;
+  const readComponentMatrixGate =
+    typeof readWaveComponentMatrixGateFn === "function"
+      ? readWaveComponentMatrixGateFn
+      : readWaveComponentMatrixGateDefault;
+  const readContQaGate =
+    typeof readWaveContQaGateFn === "function"
+      ? readWaveContQaGateFn
+      : readWaveContQaGateDefault;
+  const stagedRuns = planClosureStages({ lanePaths, wave, closureRuns });
+  const { contQaAgentId, contEvalAgentId, integrationAgentId, documentationAgentId } =
+    resolveWaveRoleBindings(wave, lanePaths);
   for (const stage of stagedRuns) {
     if (stage.runs.length === 0) {
       continue;
@@ -177,6 +151,11 @@ export async function runClosureSweepPhase({
         agentRateLimitBaseDelaySeconds: options.agentRateLimitBaseDelaySeconds,
         agentRateLimitMaxDelaySeconds: options.agentRateLimitMaxDelaySeconds,
         context7Enabled: options.context7Enabled,
+        attempt: dashboardState?.attempt || 1,
+        controlPlane: {
+          waveNumber: wave.wave,
+          attempt: dashboardState?.attempt || 1,
+        },
       });
       runInfo.lastLaunchAttempt = dashboardState?.attempt || null;
       runInfo.lastPromptHash = launchResult?.promptHash || null;
@@ -201,7 +180,7 @@ export async function runClosureSweepPhase({
           refreshWaveDashboardAgentStates(dashboardState, [runInfo], pendingAgentIds, (event) =>
             recordCombinedEvent(event),
           );
-          const feedbackChanged = monitorWaveHumanFeedbackFn({
+          const feedbackChanged = monitorHumanFeedback({
             lanePaths,
             waveNumber: wave.wave,
             agentRuns: [runInfo],
@@ -217,14 +196,37 @@ export async function runClosureSweepPhase({
           updateWaveDashboardMessageBoard(dashboardState, runInfo.messageBoardPath);
           flushDashboards();
         },
+        {
+          controlPlane: {
+            waveNumber: wave.wave,
+            attempt: dashboardState?.attempt || 1,
+          },
+        },
       );
-      materializeAgentExecutionSummaryForRunFn(wave, runInfo);
+      materializeSummary(wave, runInfo);
       refreshDerivedState?.(dashboardState?.attempt || 0);
       if (result.failures.length > 0) {
         return result;
       }
     }
-    const gate = stage.validate();
+    const gate = evaluateClosureStage({
+      stage,
+      wave,
+      closureRuns,
+      lanePaths,
+      dashboardState,
+      refreshDerivedState,
+      readWaveContEvalGateFn: readContEvalGate,
+      readWaveSecurityGateFn: readSecurityGate,
+      readWaveIntegrationBarrierFn: readIntegrationBarrier,
+      readWaveDocumentationGateFn: readDocumentationGate,
+      readWaveComponentMatrixGateFn: readComponentMatrixGate,
+      readWaveContQaGateFn: readContQaGate,
+      contEvalAgentId,
+      integrationAgentId,
+      documentationAgentId,
+      contQaAgentId,
+    });
     if (!gate.ok) {
       recordClosureGateFailure({
         wave,
@@ -244,6 +246,120 @@ export async function runClosureSweepPhase({
   return { failures: [], timedOut: false };
 }
 
+export function planClosureStages({ lanePaths, wave, closureRuns }) {
+  const { contQaAgentId, contEvalAgentId, integrationAgentId, documentationAgentId } =
+    resolveWaveRoleBindings(wave, lanePaths);
+  return [
+    {
+      key: "cont-eval",
+      agentId: contEvalAgentId,
+      label: "cont-EVAL gate",
+      runs: closureRuns.filter((run) => run.agent.agentId === contEvalAgentId),
+      actionRequested:
+        `Lane ${lanePaths.lane} owners should resolve cont-EVAL tuning gaps before integration closure.`,
+    },
+    {
+      key: "security-review",
+      agentId: "security",
+      label: "Security review",
+      runs: closureRuns.filter((run) => isSecurityReviewAgent(run.agent)),
+      actionRequested:
+        `Lane ${lanePaths.lane} owners should resolve blocked security findings or missing approvals before integration closure.`,
+    },
+    {
+      key: "integration",
+      agentId: integrationAgentId,
+      label: "Integration gate",
+      runs: closureRuns.filter((run) => run.agent.agentId === integrationAgentId),
+      actionRequested:
+        `Lane ${lanePaths.lane} owners should resolve integration contradictions or blockers before documentation and cont-QA closure.`,
+    },
+    {
+      key: "documentation",
+      agentId: documentationAgentId,
+      label: "Documentation closure",
+      runs: closureRuns.filter((run) => run.agent.agentId === documentationAgentId),
+      actionRequested:
+        `Lane ${lanePaths.lane} owners should resolve the shared-plan or component-matrix closure state before cont-QA progression.`,
+    },
+    {
+      key: "cont-qa",
+      agentId: contQaAgentId,
+      label: "cont-QA gate",
+      runs: closureRuns.filter((run) => run.agent.agentId === contQaAgentId),
+      actionRequested:
+        `Lane ${lanePaths.lane} owners should resolve the cont-QA gate before wave progression.`,
+    },
+  ];
+}
+
+function evaluateClosureStage({
+  stage,
+  wave,
+  closureRuns,
+  lanePaths,
+  dashboardState,
+  refreshDerivedState,
+  readWaveContEvalGateFn,
+  readWaveSecurityGateFn,
+  readWaveIntegrationBarrierFn,
+  readWaveDocumentationGateFn,
+  readWaveComponentMatrixGateFn,
+  readWaveContQaGateFn,
+  contEvalAgentId,
+  integrationAgentId,
+  documentationAgentId,
+  contQaAgentId,
+}) {
+  switch (stage.key) {
+    case "cont-eval":
+      return readWaveContEvalGateFn(wave, closureRuns, {
+        contEvalAgentId,
+        mode: "live",
+        evalTargets: wave.evalTargets,
+        benchmarkCatalogPath: lanePaths.laneProfile?.paths?.benchmarkCatalogPath,
+      });
+    case "security-review":
+      return readWaveSecurityGateFn(wave, closureRuns, { mode: "live" });
+    case "integration":
+      return readWaveIntegrationBarrierFn(
+        wave,
+        closureRuns,
+        refreshDerivedState?.(dashboardState?.attempt || 0),
+        {
+          integrationAgentId,
+          mode: "live",
+          requireIntegrationStewardFromWave: lanePaths.requireIntegrationStewardFromWave,
+        },
+      );
+    case "documentation": {
+      const documentationGate = readWaveDocumentationGateFn(wave, closureRuns, {
+        mode: "live",
+      });
+      if (!documentationGate.ok) {
+        return documentationGate;
+      }
+      return readWaveComponentMatrixGateFn(wave, closureRuns, {
+        laneProfile: lanePaths.laneProfile,
+        documentationAgentId,
+      });
+    }
+    case "cont-qa":
+      return readWaveContQaGateFn(wave, closureRuns, {
+        contQaAgentId,
+        mode: "live",
+      });
+    default:
+      return {
+        ok: true,
+        agentId: null,
+        statusCode: "pass",
+        detail: "No closure stage configured.",
+        logPath: null,
+      };
+  }
+}
+
 const NON_BLOCKING_INFRA_SIGNAL_STATES = new Set([
   "conformant",
   "setup-required",

package/scripts/wave-orchestrator/config.mjs

@@ -28,6 +28,7 @@ export const DEFAULT_INTEGRATION_ROLE_PROMPT_PATH = "docs/agents/wave-integratio
 export const DEFAULT_DOCUMENTATION_ROLE_PROMPT_PATH =
   "docs/agents/wave-documentation-role.md";
 export const DEFAULT_SECURITY_ROLE_PROMPT_PATH = "docs/agents/wave-security-role.md";
+export const DEFAULT_DESIGN_ROLE_PROMPT_PATH = "docs/agents/wave-design-role.md";
 export const DEFAULT_TERMINALS_PATH = ".vscode/terminals.json";
 export const DEFAULT_DOCS_DIR = "docs";
 export const DEFAULT_STATE_ROOT = ".tmp";
@@ -348,6 +349,10 @@ function normalizeRoles(rawRoles = {}) {
       rawRoles.securityRolePromptPath || DEFAULT_SECURITY_ROLE_PROMPT_PATH,
       "roles.securityRolePromptPath",
     ),
+    designRolePromptPath: normalizeRepoRelativePath(
+      rawRoles.designRolePromptPath || DEFAULT_DESIGN_ROLE_PROMPT_PATH,
+      "roles.designRolePromptPath",
+    ),
   };
 }
 

package/scripts/wave-orchestrator/coordination.mjs

@@ -17,6 +17,8 @@ import {
 import { resolveEvalTargetsAgainstCatalog } from "./evals.mjs";
 import {
   isContEvalImplementationOwningAgent,
+  isDesignAgent,
+  isImplementationOwningDesignAgent,
   isSecurityReviewAgent,
 } from "./role-helpers.mjs";
 
@@ -199,6 +201,8 @@ export function buildExecutionPrompt({
   evalTargets = null,
   benchmarkCatalogPath = null,
   sharedPlanDocs = null,
+  designPacketPaths = null,
+  designExecutionMode = null,
   contQaAgentId = "A0",
   contEvalAgentId = "E0",
   integrationAgentId = "A8",
@@ -222,6 +226,10 @@ export function buildExecutionPrompt({
   const contEvalImplementationOwning = isContEvalImplementationOwningAgent(agent, {
     contEvalAgentId,
   });
+  const hybridDesignAgent = isImplementationOwningDesignAgent(agent);
+  const designAgent = isDesignAgent(agent);
+  const designImplementationPass = designAgent && hybridDesignAgent && designExecutionMode === "implementation-pass";
+  const designPacketPass = designAgent && !designImplementationPass;
   const resolvedEvalTargets = (() => {
     try {
       return resolveEvalTargetsAgainstCatalog(evalTargets, { benchmarkCatalogPath }).targets;
@@ -269,6 +277,22 @@ export function buildExecutionPrompt({
         "- Use `clear` only when no unresolved findings or approvals remain. Use `blocked` only when the wave must stop before integration.",
       ]
     : [];
+  const designRequirements = designAgent
+    ? [
+        designImplementationPass
+          ? "- You are in the hybrid design steward's implementation follow-through pass. Keep the design packet current, implement only your explicit owned paths, and finish with both `[wave-design]` and the normal implementation proof markers."
+          : "- You are the wave's design steward. Stay packet-first and docs/spec-owned unless the wave explicitly assigns more.",
+        "- Leave one design packet with these sections in order: `Problem`, `Constraints`, `Decisions`, `Assumptions`, `Open Questions`, `Interface Impacts`, `Validation Plan`, `Implementation Handoff`.",
+        "- Emit one final structured design marker: `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> decisions=<n> assumptions=<n> open_questions=<n> detail=<short-note>`.",
+        "- Use `ready-for-implementation` only when downstream implementation owners can start without unresolved design ambiguity.",
+        "- Use `needs-clarification` when the wave should stop for a specific question or decision before coding starts.",
+        ...(hybridDesignAgent && !designImplementationPass
+          ? [
+              "- This wave also assigns you explicit implementation-owned files, but this first pass is still design-only. Do not claim implementation proof yet; the code-owning pass starts only after the design packet is ready.",
+            ]
+          : []),
+      ]
+    : [];
   const coordinationCommand = [
     "pnpm exec wave coord post",
     `--lane ${lane}`,
@@ -280,6 +304,7 @@ export function buildExecutionPrompt({
   ].join(" ");
   const implementationRequirements =
     ![contQaAgentId, documentationAgentId].includes(agent.agentId) &&
+    (!designAgent || designImplementationPass) &&
     !isSecurityReviewAgent(agent) &&
     (agent.agentId !== contEvalAgentId || contEvalImplementationOwning)
       ? [
@@ -294,7 +319,8 @@ export function buildExecutionPrompt({
           `- Route unresolved architecture, integration, durability, ops, or docs issues through \`${coordinationCommand}\`. Do not append \`[wave-gap]\` lines after the final implementation markers.`,
         ]
       : [];
-  const exitContractLines = agent.exitContract
+  const exitContractLines =
+    implementationRequirements.length > 0 && agent.exitContract
     ? [
         "Exit contract for this run:",
         `- completion: ${agent.exitContract.completion}`,
@@ -385,6 +411,7 @@ export function buildExecutionPrompt({
       : [];
   const ownedComponentLines =
     ![contQaAgentId, documentationAgentId].includes(agent.agentId) &&
+    (!designAgent || designImplementationPass) &&
     (agent.agentId !== contEvalAgentId || contEvalImplementationOwning) &&
     Array.isArray(agent.components) &&
     agent.components.length > 0
@@ -398,6 +425,7 @@ export function buildExecutionPrompt({
         ]
       : [];
   const deliverableLines =
+    (!designAgent || designImplementationPass) &&
     Array.isArray(agent.deliverables) && agent.deliverables.length > 0
       ? [
           "Deliverables required for this agent:",
@@ -405,7 +433,18 @@ export function buildExecutionPrompt({
           "",
         ]
       : [];
+  const designPacketLines =
+    !designAgent &&
+    Array.isArray(designPacketPaths) &&
+    designPacketPaths.length > 0
+      ? [
+          "Same-wave design packets to read before coding:",
+          ...designPacketPaths.map((designPacketPath) => `- ${designPacketPath}`),
+          "",
+        ]
+      : [];
   const proofArtifactLines =
+    implementationRequirements.length > 0 &&
     Array.isArray(agent.proofArtifacts) && agent.proofArtifacts.length > 0
       ? [
           "Proof artifacts required for this agent:",
@@ -473,6 +512,7 @@ export function buildExecutionPrompt({
     ...contEvalRequirements,
     ...docStewardRequirements,
     ...securityRequirements,
+    ...designRequirements,
     ...implementationRequirements,
     `- Update docs impacted by your implementation. If your work changes status, sequencing, ownership, or explicit proof expectations, update the relevant docs. If shared plan docs need changes outside your owned files, post the exact doc paths and exact delta needed for ${sharedPlanDocList} as a coordination record instead of leaving documentation drift for later cleanup.`,
     "- If the wave defines a documentation steward or other explicit owner for shared plan docs, coordinate those updates through that owner, notify them as soon as the delta is known, and stay engaged until they confirm `closed` or `no-change`. Do not treat the ownership boundary as the definition of done.",
@@ -503,6 +543,7 @@ export function buildExecutionPrompt({
     ...evalTargetLines,
     ...ownedComponentLines,
     ...deliverableLines,
+    ...designPacketLines,
     ...proofArtifactLines,
     ...skillLines,
     ...context7PromptLines,