agent-contracts 0.19.2 → 0.19.4

package/README.md

@@ -229,6 +229,7 @@ A **Workflow** defines a phase-level execution sequence:
 Workflow steps support additional properties:
 
 * `group` — consecutive steps with the same group are rendered as `par` (parallel) blocks in sequence diagrams
+* `depends_on` — list of step task IDs that must complete before this step starts. When specified, the runtime can execute independent steps in parallel. When omitted, the step implicitly depends on all preceding steps (sequential execution)
 * `max_retries` (delegate steps) — maximum number of full task re-executions (new sessions) allowed per step. Defaults to `0` (no retries), or `1` when a `retry` block is present
 * `max_follow_ups` (delegate steps) — maximum number of lightweight same-session follow-up messages for output format corrections
 * `retry` (delegate steps) — defines a conditional retry loop with `condition`, `fix_task`, and optional `revalidate_task`. These are rendered as recovery instructions in the LLM prompt

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: agent-contracts CLI
-  version: 0.19.2
+  version: 0.19.4
   description: >-
     Declarative YAML DSL toolkit for defining, validating, and rendering
     multi-agent development workflows. Provides static validation,
@@ -625,44 +625,81 @@ commandSets:
             schema:
               type: string
 
+          - name: fail-on
+            description: >-
+              Minimum finding severity that causes exit 10
+              (info|warning|error|critical).
+            valueName: level
+            schema:
+              type: string
+              enum: [info, warning, error, critical]
+              default: critical
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              encoding: utf-8
+
+          - name: report-format
+            description: >-
+              Alias for --format. When both are specified, --report-format
+              takes precedence.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [text, json, markdown]
+              default: text
+
         exits:
           '0':
-            description: No critical findings detected.
+            description: Audit succeeded. No findings at or above --fail-on threshold.
             stdout:
               format: '{options.format}'
-              schemaNote: >-
-                Audit findings are always emitted on stdout as the primary
-                output. Format depends on --format option (text, json, or
-                markdown).
+              schema:
+                $ref: './dsl_base/components.yaml#/schemas/agent-audit-result'
 
           '1':
-            description: Critical findings detected.
+            description: Unexpected error (invalid input, config error, or internal failure).
             stderr:
               format: text
-              schemaNote: >-
-                Summary diagnostic on stderr. Structured findings are
-                emitted on stdout in the requested --format.
+
+          '10':
+            description: Findings at or above --fail-on severity threshold detected.
             stdout:
               format: '{options.format}'
+              schema:
+                $ref: './dsl_base/components.yaml#/schemas/agent-audit-result'
+            stderr:
+              format: text
               schemaNote: >-
-                Full findings output. Exit 1 indicates at least one
-                critical-severity finding exists; the findings themselves
-                are valid structured data, not error messages.
+                Summary diagnostic on stderr. Structured findings are
+                emitted on stdout in the requested format.
 
-          '2':
-            description: Invalid input or configuration error.
+          '11':
+            description: >-
+              Runtime dependency missing (agent-contracts-runtime not installed).
             stderr:
               format: text
 
-          '3':
-            description: LLM adapter error (API failure, runtime not installed).
+          '12':
+            description: LLM provider or adapter error (API failure, auth error).
             stderr:
               format: text
 
         x-agent:
           riskLevel: medium
           requiresConfirmation: false
-          idempotent: true
+          idempotent: false
+          idempotentNote: >-
+            Safe to repeat (no persistent side effects beyond network calls),
+            but LLM inference is non-deterministic — identical inputs may
+            produce different findings, severity assignments, and
+            recommendation text across runs.
           sideEffects:
             - network
           sideEffectNote: >-
@@ -671,7 +708,7 @@ commandSets:
             cost and sends DSL content to the LLM provider.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [3]
+          retryableExitCodes: [12]
           recommendedBeforeUse:
             - Ensure agent-contracts.config.yaml exists with render targets.
             - Run validate first to confirm DSL is valid.

package/dist/cli.js

@@ -48983,6 +48983,7 @@ var WorkflowDelegateStepSchema = z14.object({
   task: z14.string(),
   from_agent: z14.string(),
   group: z14.string().optional(),
+  depends_on: z14.array(z14.string()).optional(),
   max_retries: z14.number().int().min(0).optional(),
   max_follow_ups: z14.number().int().min(0).optional(),
   retry: RetrySchema.optional()
@@ -48991,7 +48992,8 @@ var WorkflowGateStepSchema = z14.object({
   type: z14.literal("gate"),
   description: z14.string().optional(),
   gate_kind: z14.string(),
-  group: z14.string().optional()
+  group: z14.string().optional(),
+  depends_on: z14.array(z14.string()).optional()
 }).passthrough();
 var WorkflowHandoffStepSchema = z14.object({
   type: z14.literal("handoff"),
@@ -49000,13 +49002,15 @@ var WorkflowHandoffStepSchema = z14.object({
   task: z14.string().optional(),
   from_agent: z14.string().optional(),
   group: z14.string().optional(),
+  depends_on: z14.array(z14.string()).optional(),
   retry: RetrySchema.optional()
 }).passthrough();
 var WorkflowValidationStepSchema = z14.object({
   type: z14.literal("validation"),
   description: z14.string().optional(),
   validation: z14.string(),
-  group: z14.string().optional()
+  group: z14.string().optional(),
+  depends_on: z14.array(z14.string()).optional()
 }).passthrough();
 var WorkflowDecisionStepSchema = z14.object({
   type: z14.literal("decision"),
@@ -49015,7 +49019,8 @@ var WorkflowDecisionStepSchema = z14.object({
   on: z14.string().optional(),
   routing_key: z14.string().optional(),
   branches: z14.record(z14.string(), z14.array(z14.string())),
-  group: z14.string().optional()
+  group: z14.string().optional(),
+  depends_on: z14.array(z14.string()).optional()
 }).passthrough();
 var WorkflowTeamTaskStepSchema = z14.object({
   type: z14.literal("team_task"),
@@ -49024,7 +49029,8 @@ var WorkflowTeamTaskStepSchema = z14.object({
   workflow: z14.string(),
   handoff: z14.string(),
   expects: z14.string(),
-  group: z14.string().optional()
+  group: z14.string().optional(),
+  depends_on: z14.array(z14.string()).optional()
 }).passthrough();
 var WorkflowStepSchema = z14.discriminatedUnion("type", [
   WorkflowDelegateStepSchema,
@@ -55892,6 +55898,7 @@ ${issues}
 );
 
 // src/cli/commands/audit.ts
+import { writeFileSync as writeFileSync2 } from "fs";
 import { Command as Command8 } from "commander";
 
 // src/auditor/context-builder.ts
@@ -56626,16 +56633,22 @@ function formatAuditResults(results, format2) {
   }
   return results.map((r3) => formatAuditResult(r3, format2)).join("\n\n");
 }
-function computeExitCode(results) {
+function computeExitCode(results, failOn) {
   for (const r3 of results) {
     if (r3.status === "error") {
-      if (r3.errorMessage?.includes("not installed") || r3.errorMessage?.includes("adapter")) return 3;
-      return 2;
+      if (r3.errorMessage?.includes("not installed")) return 11;
+      if (r3.errorMessage?.includes("adapter") || r3.errorMessage?.includes("API")) return 12;
+      return 1;
     }
   }
+  const severityRank = { info: 0, warning: 1, error: 2, critical: 3 };
+  const threshold = severityRank[failOn ?? "critical"] ?? 3;
   for (const r3 of results) {
-    if (r3.data?.critical_gaps && r3.data.critical_gaps.some((g2) => g2.severity === "critical")) {
-      return 1;
+    if (r3.data?.critical_gaps) {
+      for (const gap of r3.data.critical_gaps) {
+        const rank = severityRank[gap.severity ?? ""] ?? 0;
+        if (rank >= threshold) return 10;
+      }
     }
   }
   return 0;
@@ -56653,13 +56666,13 @@ function parseAuditConfig(config) {
     cache_dir: audit.cache_dir
   };
 }
-async function runAuditForDsl(dslPath, vars, configObj, auditType, opts) {
+async function runAuditForDsl(dslPath, vars, configObj, auditType, opts, failOn) {
   const resolved = await resolve4(dslPath);
   const data = vars ? substituteVars(resolved.data, vars) : resolved.data;
   const schemaResult = validateSchema(data);
   if (!schemaResult.success) {
     process.stderr.write("Schema validation failed. Run 'agent-contracts validate' first.\n");
-    return 2;
+    return { exitCode: 1, output: "" };
   }
   const auditConfig = parseAuditConfig(
     configObj.audit
@@ -56672,17 +56685,18 @@ async function runAuditForDsl(dslPath, vars, configObj, auditType, opts) {
       scope: opts.scope,
       dryRun: opts.dryRun
     });
+    let output2;
     if (opts.dryRun) {
-      for (const r3 of results) {
-        process.stdout.write(`
+      output2 = results.map(
+        (r3) => `
 --- Audit prompt: ${r3.auditType} ---
-`);
-        process.stdout.write(r3.prompt + "\n");
-      }
+${r3.prompt}
+`
+      ).join("");
     } else {
-      process.stdout.write(formatAuditResults(results, opts.format) + "\n");
+      output2 = formatAuditResults(results, opts.format) + "\n";
     }
-    return computeExitCode(results);
+    return { exitCode: computeExitCode(results, failOn), output: output2 };
   }
   const result = await runAudit(schemaResult.data, configObj, auditConfig, {
     auditType,
@@ -56690,67 +56704,78 @@ async function runAuditForDsl(dslPath, vars, configObj, auditType, opts) {
     scope: opts.scope,
     dryRun: opts.dryRun
   });
+  let output;
   if (opts.dryRun) {
-    process.stdout.write(result.prompt + "\n");
+    output = result.prompt + "\n";
   } else {
-    process.stdout.write(formatAuditResult(result, opts.format) + "\n");
+    output = formatAuditResult(result, opts.format) + "\n";
   }
-  return computeExitCode([result]);
+  return { exitCode: computeExitCode([result], failOn), output };
 }
-var auditCommand = new Command8("audit").description("Run LLM-based semantic audit on DSL definitions and generated outputs").argument("[type]", `Audit type: ${AUDIT_TYPES.join(", ")}`, "all").option("-c, --config <path>", "Path to agent-contracts.config.yaml").option("--team <id>", "Limit to one team (multi-team config only)").option("--format <format>", "Output format (text|json|markdown)", "text").option("--scope <entities>", "Limit audit scope (e.g. agents:architect,implementer)").option("--dry-run", "Output the audit prompt without calling LLM", false).option("--adapter <name>", "SDK adapter to use (default from config)").option("--model <name>", "LLM model override").action(
+var auditCommand = new Command8("audit").description("Run LLM-based semantic audit on DSL definitions and generated outputs").argument("[type]", `Audit type: ${AUDIT_TYPES.join(", ")}`, "all").option("-c, --config <path>", "Path to agent-contracts.config.yaml").option("--team <id>", "Limit to one team (multi-team config only)").option("--format <format>", "Output format (text|json|markdown)", "text").option("--scope <entities>", "Limit audit scope (e.g. agents:architect,implementer)").option("--dry-run", "Output the audit prompt without calling LLM", false).option("--adapter <name>", "SDK adapter to use (default from config)").option("--model <name>", "LLM model override").option("--fail-on <level>", "Minimum severity that causes exit 10 (info|warning|error|critical)", "critical").option("-o, --output <file>", "Write result to a file instead of stdout").option("--report-format <fmt>", "Alias for --format (for cli-contracts standard conformance)").action(
   async (type, opts) => {
     if (!AUDIT_TYPES.includes(type)) {
       process.stderr.write(
         `Unknown audit type: "${type}". Use one of: ${AUDIT_TYPES.join(", ")}
 `
       );
-      process.exit(2);
+      process.exit(1);
     }
-    const format2 = opts.format;
+    const format2 = opts.reportFormat ?? opts.format;
     try {
       const config = await loadConfig(opts.config);
       if (!config) {
         process.stderr.write(
           "Error: agent-contracts.config.yaml not found. Use --config to specify path.\n"
         );
-        process.exit(2);
+        process.exit(1);
       }
       if (isMultiTeamConfig(config)) {
         const teamEntries = getTeamEntries(config, opts.team);
         let maxExit = 0;
+        const allOutput = [];
         for (const [teamId, teamConfig] of teamEntries) {
           process.stderr.write(`
 --- Team: ${teamId} ---
 `);
-          const exitCode2 = await runAuditForDsl(
+          const result2 = await runAuditForDsl(
             teamConfig.dsl,
             teamConfig.vars,
             config,
             type,
-            { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model }
+            { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model },
+            opts.failOn
           );
-          if (exitCode2 > maxExit) maxExit = exitCode2;
+          process.stdout.write(result2.output);
+          allOutput.push(result2.output);
+          if (result2.exitCode > maxExit) maxExit = result2.exitCode;
         }
+        if (opts.output) writeFileSync2(opts.output, allOutput.join(""), "utf8");
         process.exit(maxExit);
       }
-      const exitCode = await runAuditForDsl(
+      const result = await runAuditForDsl(
         config.dsl,
         config.vars,
         config,
         type,
-        { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model }
+        { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model },
+        opts.failOn
       );
-      process.exit(exitCode);
+      process.stdout.write(result.output);
+      if (opts.output) writeFileSync2(opts.output, result.output, "utf8");
+      process.exit(result.exitCode);
     } catch (err) {
       if (err instanceof ConfigLoadError) {
         process.stderr.write(`Config error: ${err.message}
 `);
-        process.exit(2);
+        process.exit(1);
       }
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Error: ${msg}
 `);
-      process.exit(err instanceof Error && msg.includes("not installed") ? 3 : 2);
+      if (msg.includes("not installed")) process.exit(11);
+      if (msg.includes("adapter") || msg.includes("API")) process.exit(12);
+      process.exit(1);
     }
   }
 );