agent-contracts 0.7.1 → 0.9.0

package/dist/cli.js

@@ -59175,18 +59175,27 @@ var TaskSchema = z7.object({
   completion_criteria: z7.array(z7.string()).optional(),
   rules: z7.array(RuleSchema).optional(),
   anti_patterns: z7.array(z7.string()).optional(),
-  escalation_criteria: z7.array(EscalationCriterionSchema).optional()
+  escalation_criteria: z7.array(EscalationCriterionSchema).optional(),
+  validations: z7.array(z7.string()).default([])
 }).passthrough();
 
 // src/schema/tool.ts
 import { z as z8 } from "zod";
+var CommandSchema = z8.object({
+  command: z8.string(),
+  category: z8.string(),
+  reads: z8.array(z8.string()).default([]),
+  writes: z8.array(z8.string()).default([]),
+  purpose: z8.string().optional()
+});
 var ToolSchema = z8.object({
   kind: z8.string(),
   description: z8.string().optional(),
   input_artifacts: z8.array(z8.string()).default([]),
   output_artifacts: z8.array(z8.string()).default([]),
   invokable_by: z8.array(z8.string()),
-  side_effects: z8.array(z8.string()).default([])
+  side_effects: z8.array(z8.string()).default([]),
+  commands: z8.array(CommandSchema).default([])
 }).passthrough();
 
 // src/schema/validation.ts
@@ -59202,25 +59211,56 @@ var ValidationSchema = z9.object({
 
 // src/schema/workflow.ts
 import { z as z10 } from "zod";
+var RetrySchema = z10.object({
+  condition: z10.string(),
+  fix_task: z10.string(),
+  revalidate_task: z10.string().optional()
+});
+var ExternalParticipantSchema = z10.object({
+  id: z10.string(),
+  kind: z10.enum(["actor", "participant"]),
+  label: z10.string(),
+  description: z10.string().optional()
+});
+var WorkflowDelegateStepSchema = z10.object({
+  type: z10.literal("delegate"),
+  description: z10.string().optional(),
+  task: z10.string(),
+  from_agent: z10.string(),
+  group: z10.string().optional(),
+  retry: RetrySchema.optional()
+}).passthrough();
+var WorkflowGateStepSchema = z10.object({
+  type: z10.literal("gate"),
+  description: z10.string().optional(),
+  gate_kind: z10.string(),
+  group: z10.string().optional()
+}).passthrough();
 var WorkflowHandoffStepSchema = z10.object({
   type: z10.literal("handoff"),
   description: z10.string().optional(),
   handoff_kind: z10.string(),
   task: z10.string().optional(),
-  from_agent: z10.string().optional()
+  from_agent: z10.string().optional(),
+  group: z10.string().optional(),
+  retry: RetrySchema.optional()
 }).passthrough();
 var WorkflowValidationStepSchema = z10.object({
   type: z10.literal("validation"),
   description: z10.string().optional(),
-  validation: z10.string()
+  validation: z10.string(),
+  group: z10.string().optional()
 }).passthrough();
 var WorkflowDecisionStepSchema = z10.object({
   type: z10.literal("decision"),
   description: z10.string().optional(),
   on: z10.string(),
-  branches: z10.record(z10.string(), z10.array(z10.string()))
+  branches: z10.record(z10.string(), z10.array(z10.string())),
+  group: z10.string().optional()
 }).passthrough();
 var WorkflowStepSchema = z10.discriminatedUnion("type", [
+  WorkflowDelegateStepSchema,
+  WorkflowGateStepSchema,
   WorkflowHandoffStepSchema,
   WorkflowValidationStepSchema,
   WorkflowDecisionStepSchema
@@ -59229,7 +59269,8 @@ var WorkflowSchema = z10.object({
   description: z10.string().optional(),
   entry_conditions: z10.array(z10.string()).default([]),
   trigger: z10.string().optional(),
-  steps: z10.array(WorkflowStepSchema)
+  steps: z10.array(WorkflowStepSchema),
+  external_participants: z10.array(ExternalParticipantSchema).default([])
 }).passthrough();
 
 // src/schema/dsl.ts
@@ -59445,12 +59486,20 @@ function checkReferences(dsl) {
     for (const ref of task.input_artifacts) {
       checkExists(ref, artifactIds, "artifacts", `tasks.${id}.input_artifacts`);
     }
+    for (const ref of task.validations) {
+      checkExists(ref, validationIds, "validations", `tasks.${id}.validations`);
+    }
   }
   for (const [wfId, wf] of Object.entries(dsl.workflow)) {
     checkExists(wfId, workflowIds, "system.default_workflow_order", `workflow.${wfId}`);
     for (let j2 = 0; j2 < wf.steps.length; j2++) {
       const step = wf.steps[j2];
-      if (step.type === "handoff") {
+      if (step.type === "delegate") {
+        checkExists(step.task, taskIds, "tasks", `workflow.${wfId}.steps[${j2}].task`);
+        checkExists(step.from_agent, agentIds, "agents", `workflow.${wfId}.steps[${j2}].from_agent`);
+      } else if (step.type === "gate") {
+        checkExists(step.gate_kind, handoffKinds, "handoff_types", `workflow.${wfId}.steps[${j2}].gate_kind`);
+      } else if (step.type === "handoff") {
         if (step.task) {
           checkExists(step.task, taskIds, "tasks", `workflow.${wfId}.steps[${j2}].task`);
         }
@@ -59622,21 +59671,26 @@ var validationCoverageRule = {
         });
       }
     }
-    const validationsReferencedInWorkflow = /* @__PURE__ */ new Set();
+    const referencedValidations = /* @__PURE__ */ new Set();
     for (const wf of Object.values(dsl.workflow)) {
       for (const step of wf.steps) {
         if (step.type === "validation") {
-          validationsReferencedInWorkflow.add(step.validation);
+          referencedValidations.add(step.validation);
         }
       }
     }
+    for (const task of Object.values(dsl.tasks)) {
+      for (const valId of task.validations) {
+        referencedValidations.add(valId);
+      }
+    }
     for (const [valId, val] of Object.entries(dsl.validations)) {
-      if (val.blocking && !validationsReferencedInWorkflow.has(valId)) {
+      if (val.blocking && !referencedValidations.has(valId)) {
         diagnostics.push({
           ruleId: "validation-coverage",
           severity: "warning",
           path: `validations.${valId}`,
-          message: `Blocking validation "${valId}" is not referenced in any workflow step`
+          message: `Blocking validation "${valId}" is not referenced in any workflow step or task`
         });
       }
     }
@@ -59846,12 +59900,100 @@ var mergeIntegrityRule = {
   }
 };
 
+// src/linter/rules/artifact-ownership.ts
+var artifactOwnershipRule = {
+  id: "artifact-ownership",
+  description: "Ensure execution_step produces/reads operations are consistent with artifact producers/editors/consumers",
+  run(dsl) {
+    const diagnostics = [];
+    for (const [taskId, task] of Object.entries(dsl.tasks)) {
+      if (!task.execution_steps) continue;
+      const agentId = task.target_agent;
+      for (const step of task.execution_steps) {
+        if (step.produces_artifact) {
+          const artifact = dsl.artifacts[step.produces_artifact];
+          if (artifact) {
+            const canWrite = artifact.producers.includes(agentId) || artifact.editors.includes(agentId);
+            if (!canWrite) {
+              diagnostics.push({
+                ruleId: "artifact-ownership",
+                severity: "warning",
+                path: `tasks.${taskId}.execution_steps`,
+                message: `Agent "${agentId}" produces artifact "${step.produces_artifact}" but is not listed in its producers or editors`
+              });
+            }
+          }
+        }
+        if (step.reads_artifact) {
+          const artifact = dsl.artifacts[step.reads_artifact];
+          if (artifact) {
+            const canRead = artifact.consumers.includes(agentId) || artifact.producers.includes(agentId) || artifact.editors.includes(agentId);
+            if (!canRead) {
+              diagnostics.push({
+                ruleId: "artifact-ownership",
+                severity: "warning",
+                path: `tasks.${taskId}.execution_steps`,
+                message: `Agent "${agentId}" reads artifact "${step.reads_artifact}" but is not listed in its producers, editors, or consumers`
+              });
+            }
+          }
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// src/linter/rules/tool-commands.ts
+var toolCommandsRule = {
+  id: "tool-commands",
+  description: "Validate tool commands: reads/writes reference existing artifacts; writes align with output_artifacts",
+  run(dsl) {
+    const diagnostics = [];
+    for (const [toolId, tool] of Object.entries(dsl.tools)) {
+      for (const cmd of tool.commands) {
+        for (const ref of cmd.reads) {
+          if (!dsl.artifacts[ref]) {
+            diagnostics.push({
+              ruleId: "tool-commands",
+              severity: "error",
+              path: `tools.${toolId}.commands`,
+              message: `Command "${cmd.command}" reads artifact "${ref}" which does not exist`
+            });
+          }
+        }
+        for (const ref of cmd.writes) {
+          if (!dsl.artifacts[ref]) {
+            diagnostics.push({
+              ruleId: "tool-commands",
+              severity: "error",
+              path: `tools.${toolId}.commands`,
+              message: `Command "${cmd.command}" writes artifact "${ref}" which does not exist`
+            });
+          }
+          if (dsl.artifacts[ref] && !tool.output_artifacts.includes(ref)) {
+            diagnostics.push({
+              ruleId: "tool-commands",
+              severity: "warning",
+              path: `tools.${toolId}.commands`,
+              message: `Command "${cmd.command}" writes artifact "${ref}" but tool's output_artifacts does not include it`
+            });
+          }
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
 // src/linter/linter.ts
 var builtinRules = [
   validationCoverageRule,
   toolExecutionRule,
   taskAgentBindingRule,
-  mergeIntegrityRule
+  mergeIntegrityRule,
+  artifactOwnershipRule,
+  toolCommandsRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -60024,6 +60166,28 @@ var workflow_handoff_kind_exists_default = (0, import_spectral_core6.createRules
     for (let i3 = 0; i3 < steps.length; i3++) {
       const step = steps[i3];
       const stepPath = [...context.path, "steps", i3];
+      if (step.type === "delegate") {
+        if (step.task && !taskKeys.has(step.task)) {
+          results.push({
+            message: `task "${step.task}" does not exist in tasks`,
+            path: [...stepPath, "task"]
+          });
+        }
+        if (step.from_agent && !agentKeys.has(step.from_agent)) {
+          results.push({
+            message: `from_agent "${step.from_agent}" does not exist in agents`,
+            path: [...stepPath, "from_agent"]
+          });
+        }
+      }
+      if (step.type === "gate") {
+        if (step.gate_kind && !handoffKeys.has(step.gate_kind)) {
+          results.push({
+            message: `gate_kind "${step.gate_kind}" does not exist in handoff_types`,
+            path: [...stepPath, "gate_kind"]
+          });
+        }
+      }
       if (step.type === "handoff") {
         if (step.handoff_kind && !handoffKeys.has(step.handoff_kind)) {
           results.push({
@@ -60237,6 +60401,17 @@ var ruleset = {
         functionOptions: { referenceTo: "artifacts" }
       }
     },
+    "task-validations-ref": {
+      description: "Task validations must reference existing validations",
+      message: "{{error}}",
+      severity: "error",
+      given: "$.tasks.*",
+      then: {
+        field: "validations",
+        function: ref_exists_default,
+        functionOptions: { referenceTo: "validations" }
+      }
+    },
     "validation-target-artifact-ref": {
       description: "Validation target_artifact must reference an existing artifact",
       message: "{{error}}",
@@ -60280,7 +60455,7 @@ var ruleset = {
     },
     // ========== 15.2.5 Handoff integrity ==========
     "workflow-step-refs": {
-      description: "Workflow step references (handoff_kind, task, from_agent, validation) must exist",
+      description: "Workflow step references (task, from_agent, gate_kind, handoff_kind, validation) must exist",
       message: "{{error}}",
       severity: "error",
       given: "$.workflow.*",
@@ -60582,7 +60757,23 @@ function buildHandoffTypeContext(dsl, handoffTypeId) {
 function buildWorkflowContext(dsl, workflowId) {
   const wfDef = dsl.workflow[workflowId];
   const workflow = { ...wfDef, id: workflowId };
-  const relatedTasks = Object.entries(dsl.tasks).filter(([, t3]) => t3.workflow === workflowId).map(([id, t3]) => ({ ...t3, id }));
+  const stepReferencedTaskIds = /* @__PURE__ */ new Set();
+  for (const step of wfDef.steps) {
+    if (step.type === "delegate") {
+      stepReferencedTaskIds.add(step.task);
+      if (step.retry) {
+        stepReferencedTaskIds.add(step.retry.fix_task);
+        if (step.retry.revalidate_task) stepReferencedTaskIds.add(step.retry.revalidate_task);
+      }
+    } else if (step.type === "handoff" && step.task) {
+      stepReferencedTaskIds.add(step.task);
+      if (step.retry) {
+        stepReferencedTaskIds.add(step.retry.fix_task);
+        if (step.retry.revalidate_task) stepReferencedTaskIds.add(step.retry.revalidate_task);
+      }
+    }
+  }
+  const relatedTasks = Object.entries(dsl.tasks).filter(([id, t3]) => t3.workflow === workflowId || stepReferencedTaskIds.has(id)).map(([id, t3]) => ({ ...t3, id }));
   const agentIds = /* @__PURE__ */ new Set();
   for (const task of relatedTasks) {
     agentIds.add(task.target_agent);
@@ -60591,7 +60782,9 @@ function buildWorkflowContext(dsl, workflowId) {
     }
   }
   for (const step of wfDef.steps) {
-    if (step.type === "handoff" && step.from_agent) {
+    if (step.type === "delegate") {
+      agentIds.add(step.from_agent);
+    } else if (step.type === "handoff" && step.from_agent) {
       agentIds.add(step.from_agent);
     }
     if (step.type === "validation") {
@@ -60648,6 +60841,11 @@ function buildWorkflowContext(dsl, workflowId) {
       validationIds.add(step.validation);
     }
   }
+  for (const task of relatedTasks) {
+    for (const valId of task.validations ?? []) {
+      validationIds.add(valId);
+    }
+  }
   const relatedValidations = {};
   for (const id of validationIds) {
     if (dsl.validations[id]) relatedValidations[id] = dsl.validations[id];
@@ -60813,40 +61011,64 @@ function agentAlias(id, agent) {
 }
 function collectReferencedIds(workflow, dsl, relatedTasks) {
   const agents = /* @__PURE__ */ new Set();
+  const auditAgents = /* @__PURE__ */ new Set();
   const tools = /* @__PURE__ */ new Set();
   const artifacts = /* @__PURE__ */ new Set();
   const taskMap = /* @__PURE__ */ new Map();
   for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
+  function collectTaskIds(task) {
+    addAgent(task.target_agent);
+    for (const es of task.execution_steps ?? []) {
+      collectExecutionStepIds(es, tools, artifacts);
+    }
+  }
+  function collectRetryIds(retry) {
+    const fixTask = taskMap.get(retry.fix_task);
+    if (fixTask) collectTaskIds(fixTask);
+    if (retry.revalidate_task) {
+      const revalTask = taskMap.get(retry.revalidate_task);
+      if (revalTask) addAgent(revalTask.target_agent);
+    }
+  }
   for (const step of workflow.steps) {
-    if (step.type === "handoff") {
-      if (step.from_agent) agents.add(step.from_agent);
+    if (step.type === "delegate") {
+      addAgent(step.from_agent);
+      const task = taskMap.get(step.task);
+      if (task) collectTaskIds(task);
+      if (step.retry) collectRetryIds(step.retry);
+    } else if (step.type === "gate") {
+    } else if (step.type === "handoff") {
+      if (step.from_agent) addAgent(step.from_agent);
       if (step.task) {
         const task = taskMap.get(step.task);
-        if (task) {
-          agents.add(task.target_agent);
-          for (const es of task.execution_steps ?? []) {
-            collectExecutionStepIds(es, tools, artifacts);
-          }
-        }
+        if (task) collectTaskIds(task);
       }
+      if (step.retry) collectRetryIds(step.retry);
     } else if (step.type === "validation") {
       const val = dsl.validations[step.validation];
       if (val) {
-        if (val.executor_type === "agent") agents.add(val.executor);
+        if (val.executor_type === "agent") addAgent(val.executor);
         else tools.add(val.executor);
         artifacts.add(val.target_artifact);
       }
-    } else if (step.type === "decision") {
     }
   }
-  return { agents, tools, artifacts };
+  function addAgent(agentId) {
+    const agent = dsl.agents[agentId];
+    if (agent?.mode === "read-only") {
+      auditAgents.add(agentId);
+    } else {
+      agents.add(agentId);
+    }
+  }
+  return { agents, auditAgents, tools, artifacts };
 }
 function collectExecutionStepIds(es, tools, artifacts) {
   if (es.uses_tool) tools.add(es.uses_tool);
   if (es.produces_artifact) artifacts.add(es.produces_artifact);
   if (es.reads_artifact) artifacts.add(es.reads_artifact);
 }
-function buildParticipants(ids, dsl) {
+function buildParticipants(ids, externals, dsl) {
   const participants = [];
   const usedAliases = /* @__PURE__ */ new Set();
   function uniqueAlias(preferred) {
@@ -60859,12 +61081,22 @@ function buildParticipants(ids, dsl) {
     usedAliases.add(alias);
     return alias;
   }
+  for (const ep of externals) {
+    const alias = uniqueAlias(sanitizeAlias(ep.id));
+    participants.push({ id: ep.id, alias, label: ep.label, group: "external" });
+  }
   for (const id of ids.agents) {
     const agent = dsl.agents[id];
     if (!agent) continue;
     const alias = uniqueAlias(agentAlias(id, agent));
     participants.push({ id, alias, label: agent.role_name, group: "agents" });
   }
+  for (const id of ids.auditAgents) {
+    const agent = dsl.agents[id];
+    if (!agent) continue;
+    const alias = uniqueAlias(agentAlias(id, agent));
+    participants.push({ id, alias, label: agent.role_name, group: "audit" });
+  }
   for (const id of ids.tools) {
     const tool = dsl.tools[id];
     if (!tool) continue;
@@ -60883,15 +61115,33 @@ function participantAlias(participants, id) {
   const p2 = participants.find((pp) => pp.id === id);
   return p2 ? p2.alias : sanitizeAlias(id);
 }
-function emitParticipants(participants, lines, indent) {
+function emitParticipants(participants, externals, lines, indent) {
   const groups = {
+    external: [],
     agents: [],
+    audit: [],
     toolchain: [],
     artifacts: []
   };
   for (const p2 of participants) groups[p2.group].push(p2);
+  const externalMap = /* @__PURE__ */ new Map();
+  for (const ep of externals) externalMap.set(ep.id, ep);
+  if (groups.external.length > 0) {
+    lines.push(`${indent}box rgb(255,245,230) External`);
+    for (const p2 of groups.external) {
+      const ep = externalMap.get(p2.id);
+      const keyword = ep?.kind === "actor" ? "actor" : "participant";
+      if (p2.alias === p2.label) {
+        lines.push(`${indent}${keyword} ${p2.alias}`);
+      } else {
+        lines.push(`${indent}${keyword} ${p2.alias} as ${p2.label}`);
+      }
+    }
+    lines.push(`${indent}end`);
+  }
   const groupConfig = [
     { key: "agents", label: "Agents", color: "rgb(200,220,255)" },
+    { key: "audit", label: "Audit", color: "rgb(255,220,220)" },
     { key: "toolchain", label: "Toolchain", color: "rgb(220,255,220)" },
     { key: "artifacts", label: "Artifacts", color: "rgb(255,230,210)" }
   ];
@@ -60967,7 +61217,7 @@ function emitValidationStep(step, participants, dsl, lastFromAgent, lines, inden
 function emitDecisionStep(step, participants, lastFromAgent, lines, indent) {
   const branches = Object.entries(step.branches);
   if (branches.length === 0) return;
-  const agentAlias2 = lastFromAgent ? participantAlias(participants, lastFromAgent) : null;
+  const agentAl = lastFromAgent ? participantAlias(participants, lastFromAgent) : null;
   for (let i3 = 0; i3 < branches.length; i3++) {
     const [key, values] = branches[i3];
     if (i3 === 0) {
@@ -60975,21 +61225,95 @@ function emitDecisionStep(step, participants, lastFromAgent, lines, indent) {
     } else {
       lines.push(`${indent}else ${key}`);
     }
-    if (agentAlias2) {
-      lines.push(`${indent}    Note over ${agentAlias2}: ${values.join(", ")}`);
-    } else {
-      lines.push(`${indent}    Note right of ${participantAlias(participants, [.../* @__PURE__ */ new Set()].join(""))}: ${values.join(", ")}`);
+    if (agentAl) {
+      lines.push(`${indent}    Note over ${agentAl}: ${values.join(", ")}`);
     }
   }
   lines.push(`${indent}end`);
 }
+function emitDelegateStep(step, participants, dsl, relatedTasks, lines, indent) {
+  const taskMap = /* @__PURE__ */ new Map();
+  for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
+  const task = taskMap.get(step.task);
+  if (!task) return;
+  const fromAlias = participantAlias(participants, step.from_agent);
+  const targetAlias = participantAlias(participants, task.target_agent);
+  lines.push(`${indent}${fromAlias}->>${targetAlias}: delegate ${step.task}`);
+  for (const es of task.execution_steps ?? []) {
+    emitExecutionStep(es, targetAlias, participants, lines, indent);
+  }
+  lines.push(`${indent}${targetAlias}-->>${fromAlias}: ${task.result_handoff}`);
+}
+function emitGateStep(step, participants, lastFromAgent, lines, indent) {
+  if (lastFromAgent) {
+    const agentAl = participantAlias(participants, lastFromAgent);
+    lines.push(`${indent}${agentAl}->>${agentAl}: ${step.gate_kind}`);
+  }
+}
+function emitRetryBlock(fromAgent, retry, participants, relatedTasks, lines, indent) {
+  const taskMap = /* @__PURE__ */ new Map();
+  for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
+  lines.push(`${indent}opt ${retry.condition}`);
+  const innerIndent = indent + "    ";
+  const fixTask = taskMap.get(retry.fix_task);
+  if (fixTask) {
+    const fromAlias = fromAgent ? participantAlias(participants, fromAgent) : null;
+    const targetAlias = participantAlias(participants, fixTask.target_agent);
+    if (fromAlias) {
+      lines.push(`${innerIndent}${fromAlias}->>${targetAlias}: fix ${retry.fix_task}`);
+    }
+    for (const es of fixTask.execution_steps ?? []) {
+      emitExecutionStep(es, targetAlias, participants, lines, innerIndent);
+    }
+    if (fromAlias) {
+      lines.push(`${innerIndent}${targetAlias}-->>${fromAlias}: ${fixTask.result_handoff}`);
+    }
+  }
+  if (retry.revalidate_task) {
+    const revalTask = taskMap.get(retry.revalidate_task);
+    if (revalTask) {
+      const fromAlias = fromAgent ? participantAlias(participants, fromAgent) : null;
+      const revalAlias = participantAlias(participants, revalTask.target_agent);
+      if (fromAlias) {
+        lines.push(`${innerIndent}${fromAlias}->>${revalAlias}: revalidate ${retry.revalidate_task}`);
+        lines.push(`${innerIndent}${revalAlias}-->>${fromAlias}: ${revalTask.result_handoff}`);
+      }
+    }
+  }
+  lines.push(`${indent}end`);
+}
+function groupSteps(steps) {
+  const result = [];
+  let currentGroup = null;
+  for (let i3 = 0; i3 < steps.length; i3++) {
+    const step = steps[i3];
+    const group = "group" in step ? step.group : void 0;
+    if (group) {
+      if (currentGroup && currentGroup.group === group) {
+        currentGroup.steps.push({ step, index: i3 });
+      } else {
+        if (currentGroup) result.push(currentGroup);
+        currentGroup = { group, steps: [{ step, index: i3 }] };
+      }
+    } else {
+      if (currentGroup) {
+        result.push(currentGroup);
+        currentGroup = null;
+      }
+      result.push({ group: null, steps: [{ step, index: i3 }] });
+    }
+  }
+  if (currentGroup) result.push(currentGroup);
+  return result;
+}
 function generateSequenceDiagram(workflow, relatedTasks, dsl) {
   const ids = collectReferencedIds(workflow, dsl, relatedTasks);
-  const participants = buildParticipants(ids, dsl);
+  const externals = workflow.external_participants ?? [];
+  const participants = buildParticipants(ids, externals, dsl);
   const lines = [];
   const indent = "    ";
   lines.push("sequenceDiagram");
-  emitParticipants(participants, lines, indent);
+  emitParticipants(participants, externals, lines, indent);
   lines.push("");
   lines.push(`${indent}rect ${hashToColor(workflow.id, 0.15, 0.95)}`);
   const firstP = participants[0];
@@ -60998,22 +61322,188 @@ function generateSequenceDiagram(workflow, relatedTasks, dsl) {
     const noteLabel = workflow.description ? `${workflow.id} \u2014 ${workflow.description}` : workflow.id;
     lines.push(`${indent}Note over ${firstP.alias},${lastP.alias}: ${noteLabel}`);
   }
+  if (workflow.trigger && externals.some((ep) => ep.kind === "actor")) {
+    const actor = externals.find((ep) => ep.kind === "actor");
+    const actorAlias = participantAlias(participants, actor.id);
+    const firstAgent = participants.find((p2) => p2.group === "agents" || p2.group === "audit");
+    if (firstAgent) {
+      lines.push(`${indent}${actorAlias}->>${firstAgent.alias}: ${workflow.trigger}`);
+    }
+  }
   let lastFromAgent;
-  for (const step of workflow.steps) {
-    lines.push("");
-    if (step.type === "handoff") {
-      if (step.from_agent) lastFromAgent = step.from_agent;
-      emitHandoffStep(step, participants, dsl, relatedTasks, lines, indent);
-    } else if (step.type === "validation") {
-      emitValidationStep(step, participants, dsl, lastFromAgent, lines, indent);
-    } else if (step.type === "decision") {
-      emitDecisionStep(step, participants, lastFromAgent, lines, indent);
+  const grouped = groupSteps(workflow.steps);
+  for (const g2 of grouped) {
+    if (g2.group && g2.steps.length > 1) {
+      lines.push("");
+      lines.push(`${indent}par ${g2.group}`);
+      const parIndent = indent + "    ";
+      for (let i3 = 0; i3 < g2.steps.length; i3++) {
+        const { step } = g2.steps[i3];
+        if (i3 > 0) lines.push(`${indent}and`);
+        emitStep(step, participants, dsl, relatedTasks, lines, parIndent, lastFromAgent, (a3) => {
+          lastFromAgent = a3;
+        });
+      }
+      lines.push(`${indent}end`);
+    } else {
+      for (const { step } of g2.steps) {
+        lines.push("");
+        emitStep(step, participants, dsl, relatedTasks, lines, indent, lastFromAgent, (a3) => {
+          lastFromAgent = a3;
+        });
+      }
     }
   }
   lines.push("");
   lines.push(`${indent}end`);
   return lines.join("\n");
 }
+function emitStep(step, participants, dsl, relatedTasks, lines, indent, lastFromAgent, setLastFromAgent) {
+  if (step.type === "delegate") {
+    setLastFromAgent(step.from_agent);
+    emitDelegateStep(step, participants, dsl, relatedTasks, lines, indent);
+    if (step.retry) {
+      emitRetryBlock(step.from_agent, step.retry, participants, relatedTasks, lines, indent);
+    }
+  } else if (step.type === "gate") {
+    emitGateStep(step, participants, lastFromAgent, lines, indent);
+  } else if (step.type === "handoff") {
+    if (step.from_agent) setLastFromAgent(step.from_agent);
+    emitHandoffStep(step, participants, dsl, relatedTasks, lines, indent);
+    if (step.retry) {
+      emitRetryBlock(step.from_agent, step.retry, participants, relatedTasks, lines, indent);
+    }
+  } else if (step.type === "validation") {
+    emitValidationStep(step, participants, dsl, lastFromAgent, lines, indent);
+  } else if (step.type === "decision") {
+    emitDecisionStep(step, participants, lastFromAgent, lines, indent);
+  }
+}
+
+// src/renderer/overview-flowchart.ts
+function collectPhaseOps(dsl, wfId) {
+  const ctx = buildWorkflowContext(dsl, wfId);
+  const wf = dsl.workflow[wfId];
+  const agentOps = /* @__PURE__ */ new Map();
+  const artifactOps = /* @__PURE__ */ new Map();
+  const toolOps = /* @__PURE__ */ new Map();
+  function addOp(map, id, op) {
+    if (!map.has(id)) map.set(id, /* @__PURE__ */ new Set());
+    map.get(id).add(op);
+  }
+  const taskMap = new Map(ctx.relatedTasks.map((t3) => [t3.id, t3]));
+  function collectTaskOps(task) {
+    addOp(agentOps, task.target_agent, "execute");
+    for (const es of task.execution_steps ?? []) {
+      if (es.reads_artifact) addOp(artifactOps, es.reads_artifact, "R");
+      if (es.produces_artifact) addOp(artifactOps, es.produces_artifact, "W");
+      if (es.uses_tool) {
+        const tool = dsl.tools[es.uses_tool];
+        if (tool) {
+          const cats = tool.commands.map((c2) => c2.category).filter((v2, i3, a3) => a3.indexOf(v2) === i3);
+          for (const cat of cats) addOp(toolOps, es.uses_tool, cat);
+          if (cats.length === 0) addOp(toolOps, es.uses_tool, "\u2713");
+        } else {
+          addOp(toolOps, es.uses_tool, "\u2713");
+        }
+      }
+    }
+  }
+  for (const step of wf.steps) {
+    if (step.type === "delegate") {
+      addOp(agentOps, step.from_agent, "delegate");
+      const task = taskMap.get(step.task);
+      if (task) collectTaskOps(task);
+    } else if (step.type === "gate") {
+    } else if (step.type === "handoff") {
+      if (step.from_agent) addOp(agentOps, step.from_agent, "delegate");
+      if (step.task) {
+        const task = taskMap.get(step.task);
+        if (task) collectTaskOps(task);
+      }
+    } else if (step.type === "validation") {
+      const val = dsl.validations[step.validation];
+      if (val) {
+        if (val.executor_type === "agent") {
+          addOp(agentOps, val.executor, "validate");
+        } else {
+          addOp(toolOps, val.executor, "verification");
+        }
+        addOp(artifactOps, val.target_artifact, "V");
+      }
+    }
+  }
+  return { agentOps, artifactOps, toolOps };
+}
+function formatOps(ops) {
+  if (!ops || ops.size === 0) return "\u2014";
+  return [...ops].join(", ");
+}
+function buildTable(header, rows) {
+  const lines = [];
+  lines.push("| " + header.join(" | ") + " |");
+  lines.push("|" + header.map(() => "---").join("|") + "|");
+  for (const row of rows) {
+    lines.push("| " + row.join(" | ") + " |");
+  }
+  return lines.join("\n");
+}
+function generateOverviewFlowchart(dsl) {
+  const workflowOrder = dsl.system.default_workflow_order ?? Object.keys(dsl.workflow);
+  const phases = workflowOrder.filter((id) => dsl.workflow[id]);
+  const phaseData = /* @__PURE__ */ new Map();
+  for (const wfId of phases) {
+    phaseData.set(wfId, collectPhaseOps(dsl, wfId));
+  }
+  const allAgentIds = /* @__PURE__ */ new Set();
+  const allArtifactIds = /* @__PURE__ */ new Set();
+  const allToolIds = /* @__PURE__ */ new Set();
+  for (const ops of phaseData.values()) {
+    for (const id of ops.agentOps.keys()) allAgentIds.add(id);
+    for (const id of ops.artifactOps.keys()) allArtifactIds.add(id);
+    for (const id of ops.toolOps.keys()) allToolIds.add(id);
+  }
+  const sections = [];
+  if (allAgentIds.size > 0) {
+    const header = ["Agent", ...phases];
+    const rows = [];
+    for (const agentId of allAgentIds) {
+      const agent = dsl.agents[agentId];
+      const label = agent ? agent.role_name : agentId;
+      const row = [label];
+      for (const wfId of phases) {
+        row.push(formatOps(phaseData.get(wfId).agentOps.get(agentId)));
+      }
+      rows.push(row);
+    }
+    sections.push("#### Agent \xD7 Phase\n\n" + buildTable(header, rows));
+  }
+  if (allArtifactIds.size > 0) {
+    const header = ["Artifact", ...phases];
+    const rows = [];
+    for (const artId of allArtifactIds) {
+      const row = [artId];
+      for (const wfId of phases) {
+        row.push(formatOps(phaseData.get(wfId).artifactOps.get(artId)));
+      }
+      rows.push(row);
+    }
+    sections.push("#### Artifact \xD7 Phase\n\n" + buildTable(header, rows));
+  }
+  if (allToolIds.size > 0) {
+    const header = ["Tool", ...phases];
+    const rows = [];
+    for (const toolId of allToolIds) {
+      const row = [toolId];
+      for (const wfId of phases) {
+        row.push(formatOps(phaseData.get(wfId).toolOps.get(toolId)));
+      }
+      rows.push(row);
+    }
+    sections.push("#### Tool \xD7 Phase\n\n" + buildTable(header, rows));
+  }
+  return sections.join("\n\n");
+}
 
 // src/renderer/renderer.ts
 Handlebars.registerHelper("eq", (a3, b3) => a3 === b3);
@@ -61178,14 +61668,39 @@ Handlebars.registerHelper("size", (obj) => {
 });
 Handlebars.registerHelper(
   "sequenceDiagram",
-  function() {
+  function(...args) {
+    const opts = args[args.length - 1];
+    const positionalArgs = args.slice(0, -1);
+    if (typeof positionalArgs[0] === "string" && positionalArgs[1]) {
+      const workflowId = positionalArgs[0];
+      const dsl2 = positionalArgs[1];
+      if (!dsl2.workflow[workflowId]) return "";
+      const ctx = buildWorkflowContext(dsl2, workflowId);
+      return generateSequenceDiagram(
+        ctx.workflow,
+        ctx.relatedTasks,
+        dsl2
+      );
+    }
     const workflow = this["workflow"];
     const relatedTasks = this["relatedTasks"];
-    const dsl = this["dsl"];
+    const dsl = opts?.hash?.["dsl"] ?? this["dsl"];
     if (!workflow || !dsl) return "";
     return generateSequenceDiagram(workflow, relatedTasks ?? [], dsl);
   }
 );
+Handlebars.registerHelper(
+  "overviewFlowchart",
+  function(...args) {
+    const positionalArgs = args.slice(0, -1);
+    if (positionalArgs[0] && typeof positionalArgs[0] === "object") {
+      return generateOverviewFlowchart(positionalArgs[0]);
+    }
+    const dsl = this["dsl"];
+    if (!dsl) return "";
+    return generateOverviewFlowchart(dsl);
+  }
+);
 function getDslSection(dsl, context) {
   const sectionMap = {
     agent: dsl.agents,