@chllming/wave-orchestration 0.8.4 → 0.8.6

package/scripts/wave-orchestrator/ledger.mjs

@@ -6,6 +6,7 @@ import {
 } from "./config.mjs";
 import {
   validateContEvalSummary,
+  validateDesignSummary,
   validateDocumentationClosureSummary,
   validateContQaSummary,
   validateImplementationSummary,
@@ -13,6 +14,8 @@ import {
 } from "./agent-state.mjs";
 import {
   isContEvalImplementationOwningAgent,
+  isDesignAgent,
+  isImplementationOwningDesignAgent,
   isSecurityReviewAgent,
 } from "./role-helpers.mjs";
 import { openClarificationLinkedRequests } from "./coordination-store.mjs";
@@ -54,6 +57,7 @@ export function buildSeedWaveLedger({
 }) {
   const tasks = [];
   for (const agent of wave.agents) {
+    const hybridDesignAgent = isImplementationOwningDesignAgent(agent);
     const kind =
       agent.agentId === contQaAgentId
         ? "cont-qa"
@@ -63,35 +67,46 @@ export function buildSeedWaveLedger({
           ? "integration"
         : agent.agentId === documentationAgentId
             ? "documentation"
+            : isDesignAgent(agent)
+              ? "design"
             : isSecurityReviewAgent(agent)
               ? "security"
-            : "implementation";
-    tasks.push({
-      id: taskId(kind, agent.agentId),
-      title: `${agent.agentId}: ${agent.title}`,
-      owner: agent.agentId,
-      kind,
-      dependsOn: [],
-      state: "planned",
-      proofState: "pending",
-      docState: "pending",
-      infraState: "n/a",
-      priority:
-        kind === "implementation" ? "normal" : kind === "integration" ? "high" : "high",
-      artifactRefs: agent.ownedPaths || [],
-      runtime: agent.executorResolved
-        ? {
-            executorId: agent.executorResolved.id,
-            role: agent.executorResolved.role,
-            profile: agent.executorResolved.profile,
-            selectedBy: agent.executorResolved.selectedBy,
-            retryPolicy: agent.executorResolved.retryPolicy || null,
-            allowFallbackOnRetry: agent.executorResolved.allowFallbackOnRetry !== false,
-            fallbacks: agent.executorResolved.fallbacks || [],
-            fallbackUsed: agent.executorResolved.fallbackUsed === true,
-          }
-        : null,
-    });
+              : "implementation";
+    const runtime = agent.executorResolved
+      ? {
+          executorId: agent.executorResolved.id,
+          role: agent.executorResolved.role,
+          profile: agent.executorResolved.profile,
+          selectedBy: agent.executorResolved.selectedBy,
+          retryPolicy: agent.executorResolved.retryPolicy || null,
+          allowFallbackOnRetry: agent.executorResolved.allowFallbackOnRetry !== false,
+          fallbacks: agent.executorResolved.fallbacks || [],
+          fallbackUsed: agent.executorResolved.fallbackUsed === true,
+        }
+      : null;
+    const pushTask = (taskKind) => {
+      tasks.push({
+        id: taskId(taskKind, agent.agentId),
+        title: `${agent.agentId}: ${agent.title}`,
+        owner: agent.agentId,
+        kind: taskKind,
+        dependsOn: [],
+        state: "planned",
+        proofState: "pending",
+        docState: "pending",
+        infraState: "n/a",
+        priority:
+          taskKind === "implementation" ? "normal" : taskKind === "integration" ? "high" : "high",
+        artifactRefs: agent.ownedPaths || [],
+        runtime,
+      });
+    };
+    if (hybridDesignAgent && kind === "design") {
+      pushTask("design");
+      pushTask("implementation");
+      continue;
+    }
+    pushTask(kind);
   }
   for (const promotion of wave.componentPromotions || []) {
     tasks.push({
@@ -163,6 +178,11 @@ function derivePhase({
     return blockingHelperTasks.some((task) => task.state === "blocked") ? "blocked" : "running";
   }
   const implementationTasks = tasks.filter((task) => task.kind === "implementation");
+  const designTasks = tasks.filter((task) => task.kind === "design");
+  const allDesignDone = designTasks.every((task) => task.state === "done");
+  if (!allDesignDone && designTasks.length > 0) {
+    return "design";
+  }
   const allImplementationDone = implementationTasks.every((task) => task.state === "done");
   if (!allImplementationDone) {
     return "running";
@@ -221,6 +241,15 @@ export function deriveWaveLedger({
         docState: summary?.docDelta?.state || "pending",
       };
     }
+    if (task.kind === "design" && agent) {
+      const validation = validateDesignSummary(agent, summary);
+      return {
+        ...task,
+        state: taskStateFromValidation(validation),
+        proofState: validation.ok ? "met" : "gap",
+        docState: validation.ok ? "met" : "gap",
+      };
+    }
     if (task.kind === "documentation" && agent) {
       const validation = validateDocumentationClosureSummary(agent, summary);
       return {

package/scripts/wave-orchestrator/local-executor.mjs

@@ -173,6 +173,11 @@ function formatWaveEvalLine(evalMarker, detail) {
   return `[wave-eval] state=satisfied targets=${targetIds.length} benchmarks=${benchmarkIds.length} regressions=0${targetIdSegment}${benchmarkIdSegment} detail=${detail}`;
 }
 
+function isDesignAgentPrompt(rawPrompt) {
+  const text = String(rawPrompt || "");
+  return /\[wave-design\]/i.test(text) || /\bwave design\b/i.test(text);
+}
+
 export function resolveRepoOwnedDeliverablePath(relPath) {
   if (!relPath || path.isAbsolute(relPath)) {
     throw new Error(`Unsafe deliverable path: ${String(relPath || "")}`);
@@ -277,6 +282,8 @@ export function runLocalExecutorCli(argv) {
   const contQaAgent = agentId === contQaAgentId;
   const contEvalAgent = agentId === contEvalAgentId;
   const integrationAgent = agentId === integrationAgentId;
+  const designAgent = isDesignAgentPrompt(rawPrompt);
+  const implementationMarkersRequired = /\[wave-proof\]/i.test(rawPrompt);
   const ownedComponents = extractOwnedComponents(rawPrompt);
   const assignedPrompt = extractAssignedPrompt(rawPrompt);
   const ownedPaths = extractFileOwnershipPaths(assignedPrompt);
@@ -304,6 +311,21 @@ export function runLocalExecutorCli(argv) {
       console.log(
         "[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=local-executor-no-deliverables",
       );
+    } else if (designAgent) {
+      console.log(
+        "[wave-design] state=ready-for-implementation decisions=1 assumptions=1 open_questions=0 detail=local-executor-no-deliverables",
+      );
+      if (implementationMarkersRequired) {
+        console.log(
+          "[wave-proof] completion=contract durability=none proof=unit state=met detail=local-executor-no-deliverables",
+        );
+        console.log("[wave-doc-delta] state=none detail=local-executor-no-deliverables");
+        for (const component of ownedComponents) {
+          console.log(
+            `[wave-component] component=${component.componentId} level=${component.level || "repo-landed"} state=met detail=local-executor-no-deliverables`,
+          );
+        }
+      }
     } else if (agentId === documentationAgentId) {
       console.log("[wave-doc-closure] state=no-change detail=local-executor-no-deliverables");
     } else if (agentId) {
@@ -348,6 +370,21 @@ export function runLocalExecutorCli(argv) {
     console.log(
       "[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=local-executor-smoke",
     );
+  } else if (designAgent) {
+    console.log(
+      "[wave-design] state=ready-for-implementation decisions=2 assumptions=1 open_questions=0 detail=local-executor-smoke",
+    );
+    if (implementationMarkersRequired) {
+      console.log(
+        "[wave-proof] completion=contract durability=none proof=unit state=met detail=local-executor-smoke",
+      );
+      console.log("[wave-doc-delta] state=owned detail=local-executor-smoke");
+      for (const component of ownedComponents) {
+        console.log(
+          `[wave-component] component=${component.componentId} level=${component.level || "repo-landed"} state=met detail=local-executor-smoke`,
+        );
+      }
+    }
   } else if (agentId === documentationAgentId) {
     console.log("[wave-doc-closure] state=no-change detail=local-executor-smoke");
   } else if (agentId) {

package/scripts/wave-orchestrator/planner.mjs

@@ -317,6 +317,9 @@ function defaultTargetLevel(template) {
 }
 
 function defaultExecutorProfile(roleKind) {
+  if (roleKind === "design") {
+    return "design-pass";
+  }
   if (roleKind === "infra" || roleKind === "deploy" || roleKind === "research") {
     return "ops-triage";
   }
@@ -327,7 +330,7 @@ function defaultExecutorProfile(roleKind) {
 }
 
 function defaultExitContract(roleKind) {
-  if (roleKind === "security") {
+  if (roleKind === "security" || roleKind === "design") {
     return null;
   }
   if (roleKind === "infra" || roleKind === "deploy") {
@@ -355,6 +358,9 @@ function defaultExitContract(roleKind) {
 }
 
 function buildDefaultValidationCommand(template, roleKind) {
+  if (roleKind === "design") {
+    return "Manual review of the design packet against the wave scope, constraints, and downstream ownership.";
+  }
   if (roleKind === "security") {
     return "Manual review of the changed security-sensitive surfaces plus required proofs.";
   }
@@ -368,6 +374,9 @@ function buildDefaultValidationCommand(template, roleKind) {
 }
 
 function buildDefaultOutputSummary(template, roleKind) {
+  if (roleKind === "design") {
+    return "Summarize the design packet, key decisions, assumptions, open questions, and exact implementation handoff.";
+  }
   if (roleKind === "security") {
     return "Summarize the threat model, findings, required approvals, requested fixes, and final security disposition.";
   }
@@ -381,6 +390,9 @@ function buildDefaultOutputSummary(template, roleKind) {
 }
 
 function buildDefaultPrimaryGoal(template, roleKind, title) {
+  if (roleKind === "design") {
+    return `Produce an implementation-ready design packet for the ${title.toLowerCase()} slice before coding starts.`;
+  }
   if (roleKind === "security") {
     return `Review the ${title.toLowerCase()} slice for security risks and route exact fixes before integration.`;
   }
@@ -1067,6 +1079,9 @@ function buildWorkerAgentSpec({
   if (roleKind === "research" && !capabilities.includes("research")) {
     capabilities.push("research");
   }
+  if (roleKind === "design" && !capabilities.includes("design")) {
+    capabilities.push("design");
+  }
   return {
     agentId,
     title,
@@ -1075,6 +1090,8 @@ function buildWorkerAgentSpec({
         ? values.rolePromptPaths
         : roleKind === "security"
           ? [lanePaths.securityRolePromptPath]
+          : roleKind === "design"
+            ? [lanePaths.designRolePromptPath]
           : [],
     skills: values.skills || [],
     executor: {
@@ -1934,6 +1951,7 @@ function normalizePlannerContext7Bundle(bundle, bundleIndex) {
 function normalizePlannerWorkerAgent(rawAgent, context) {
   const agentId = cleanText(rawAgent?.agentId) || `A${context.index + 1}`;
   const roleKind = [
+    "design",
     "implementation",
     "qa",
     "infra",
@@ -3067,12 +3085,12 @@ async function collectWorkerAgents({
     const title = cleanText(await prompt.ask(`Worker ${agentId} title`, defaults.title));
     const roleKind = await prompt.askChoice(
       `Worker ${agentId} role kind`,
-      ["implementation", "qa", "infra", "deploy", "research", "security"],
+      ["design", "implementation", "qa", "infra", "deploy", "research", "security"],
       defaultRoleKind,
     );
     const executorProfile = await prompt.askChoice(
       `Worker ${agentId} executor profile`,
-      ["implement-fast", "deep-review", "eval-tuning", "docs-pass", "ops-triage", "security-review"],
+      ["implement-fast", "design-pass", "deep-review", "eval-tuning", "docs-pass", "ops-triage", "security-review"],
       defaultExecutorProfile(roleKind),
     );
     const ownedPaths = normalizeRepoPathList(
@@ -3081,6 +3099,8 @@ async function collectWorkerAgents({
           `Worker ${agentId} owned paths (comma or | separated)`,
           roleKind === "security"
             ? `.tmp/${lane}-wave-launcher/security/wave-${waveNumber}-review.md`
+            : roleKind === "design"
+              ? `docs/plans/waves/design/wave-${waveNumber}-${agentId}.md`
             : template === "infra"
             ? "scripts/,docs/plans/"
             : template === "release"
@@ -3093,7 +3113,7 @@ async function collectWorkerAgents({
     const components = normalizeListText(
       await prompt.ask(
         `Worker ${agentId} component ids (comma or | separated)`,
-        roleKind === "security"
+        roleKind === "security" || roleKind === "design"
           ? ""
           : componentPromotions.map((promotion) => promotion.componentId).join(", "),
       ),

package/scripts/wave-orchestrator/result-envelope.mjs

@@ -7,6 +7,7 @@ import {
 } from "./shared.mjs";
 
 export const ENVELOPE_VALID_ROLES = [
+  "design",
   "implementation",
   "integration",
   "documentation",
@@ -24,6 +25,9 @@ function inferEnvelopeRole(agent, summary) {
   if (summary?.integration) {
     return "integration";
   }
+  if (summary?.design) {
+    return "design";
+  }
   if (summary?.docClosure) {
     return "documentation";
   }
@@ -205,7 +209,11 @@ export function buildAgentResultEnvelope(agent, summary, options = {}) {
     facts,
   };
 
-  if (role === "implementation") {
+  if (
+    role === "implementation" ||
+    safeSummary.docDelta ||
+    Array.isArray(safeSummary.components)
+  ) {
     const docDelta = safeSummary.docDelta || {};
     const components = Array.isArray(safeSummary.components)
       ? safeSummary.components.map((component) => ({
@@ -225,6 +233,17 @@ export function buildAgentResultEnvelope(agent, summary, options = {}) {
     };
   }
 
+  if (role === "design") {
+    const design = safeSummary.design || {};
+    envelope.design = {
+      state: design.state || null,
+      decisions: design.decisions || 0,
+      assumptions: design.assumptions || 0,
+      openQuestions: design.openQuestions || 0,
+      detail: design.detail || null,
+    };
+  }
+
   if (role === "integration") {
     const integration = safeSummary.integration || {};
     envelope.integration = {
@@ -392,6 +411,16 @@ export function projectLegacySummaryFromEnvelope(envelope, options = {}) {
       : [];
   }
 
+  if (envelope.design) {
+    summary.design = {
+      state: envelope.design.state || null,
+      decisions: envelope.design.decisions || 0,
+      assumptions: envelope.design.assumptions || 0,
+      openQuestions: envelope.design.openQuestions || 0,
+      detail: envelope.design.detail || null,
+    };
+  }
+
   if (envelope.documentation?.docClosure) {
     summary.docClosure = {
       state: envelope.documentation.docClosure.state || "no-change",
@@ -466,6 +495,8 @@ export function projectLegacySummaryFromEnvelope(envelope, options = {}) {
 
 function requiredRoleSection(role) {
   switch (role) {
+    case "design":
+      return "design";
     case "implementation":
       return "implementation";
     case "integration":

package/scripts/wave-orchestrator/retry-control.mjs

@@ -10,7 +10,11 @@ import {
   readWaveControlPlaneState,
   syncWaveControlPlaneProjections,
 } from "./control-plane.mjs";
-import { isSecurityReviewAgent } from "./role-helpers.mjs";
+import {
+  isDesignAgent,
+  isDocsOnlyDesignAgent,
+  isSecurityReviewAgent,
+} from "./role-helpers.mjs";
 import { ensureDirectory, parseNonNegativeInt } from "./shared.mjs";
 
 function uniqueAgentIds(values) {
@@ -188,7 +192,18 @@ export function resolveRetryOverrideAgentIds(waveDefinition, lanePaths, override
   );
   if (resumePhase === "implementation") {
     return agents
-      .filter((agent) => agent?.agentId && !closureAgentIds.has(agent.agentId) && !isSecurityReviewAgent(agent))
+      .filter(
+        (agent) =>
+          agent?.agentId &&
+          !closureAgentIds.has(agent.agentId) &&
+          !isSecurityReviewAgent(agent) &&
+          !isDocsOnlyDesignAgent(agent),
+      )
+      .map((agent) => agent.agentId);
+  }
+  if (resumePhase === "design") {
+    return agents
+      .filter((agent) => isDesignAgent(agent))
       .map((agent) => agent.agentId);
   }
   if (resumePhase === "integrating") {

package/scripts/wave-orchestrator/retry-engine.mjs

@@ -20,6 +20,7 @@ import {
 } from "./shared.mjs";
 import {
   readAgentExecutionSummary,
+  validateDesignSummary,
   validateImplementationSummary,
 } from "./agent-state.mjs";
 import {
@@ -32,6 +33,9 @@ import {
 } from "./proof-registry.mjs";
 import { hashAgentPromptFingerprint } from "./context7.mjs";
 import {
+  isDocsOnlyDesignAgent,
+  isDesignAgent,
+  isImplementationOwningDesignAgent,
   isSecurityReviewAgent,
   resolveWaveRoleBindings,
 } from "./role-helpers.mjs";
@@ -315,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) {
@@ -342,6 +368,37 @@ export function hasReusableSuccessStatus(agent, statusPath, options = {}) {
   return true;
 }
 
+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(
@@ -377,6 +434,23 @@ export function selectInitialWaveRuns(agentRuns, lanePaths, waveDefinition = nul
   const implementationRuns = (agentRuns || []).filter(
     (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;
 }
 
@@ -573,6 +647,9 @@ function runsFromAgentIds(agentRuns, agentIds) {
 
 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]);
   }
@@ -729,6 +806,12 @@ function resolveRelaunchRunsLegacy(agentRuns, failures, derivedState, lanePaths,
       barrier: null,
     };
   }
+  if (derivedState?.ledger?.phase === "design") {
+    return {
+      runs: agentRuns.filter((run) => isDesignAgent(run.agent)),
+      barrier: null,
+    };
+  }
   if (derivedState?.ledger?.phase === "security-review") {
     return {
       runs: agentRuns.filter((run) => isSecurityReviewAgent(run.agent)),
@@ -1018,6 +1101,8 @@ export function preflightWavesForExecutorAvailability(waves, lanePaths) {
 
 function phaseFromGate(gateName) {
   switch (gateName) {
+    case "designGate":
+      return "design";
     case "implementationGate":
     case "componentGate":
     case "helperAssignmentBarrier":

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

@@ -1,6 +1,7 @@
 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,
@@ -37,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 } = {},
@@ -81,11 +105,59 @@ 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;