agent-contracts 0.19.5 → 0.21.0

package/docs/cli-reference.md

@@ -2,7 +2,7 @@
 
 Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows. Provides static validation, semantic linting, prompt rendering, guardrail generation, and completeness scoring for agent contract definitions.
 
-**Version:** 0.19.1
+**Version:** 0.21.0
 
 ## Table of Contents
 
@@ -72,7 +72,7 @@ agent-contracts resolve -c agent-contracts.config.yaml
 
 **Exit 0:** Resolved DSL output successfully.
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Resolution failed (file not found, parse error, or config error).
 
@@ -87,6 +87,9 @@ x-agent:
   idempotent: true
   sideEffects: 
 
+  expectedDurationMs: 3000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -135,7 +138,7 @@ agent-contracts validate --quiet
 
 **Exit 0:** Validation passed. No errors found.
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Validation failed or unexpected error.
 
@@ -150,6 +153,9 @@ x-agent:
   idempotent: true
   sideEffects: 
 
+  expectedDurationMs: 3000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -195,7 +201,7 @@ agent-contracts lint --format json
 
 **Exit 0:** Lint passed. No errors or warnings.
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Lint failed or unexpected error.
 
@@ -210,15 +216,21 @@ x-agent:
   idempotent: true
   sideEffects: 
 
+  expectedDurationMs: 3000
+  retryableExitCodes: 
+
 ```
 
 ---
 
 ### render
 
-Render resolved DSL with Handlebars templates.
+(deprecated) Alias for 'generate templates'.
+
+Deprecated alias for 'agent-contracts generate templates'. Renders output files from the resolved DSL using Handlebars templates and emits a deprecation warning. Supports --check for drift detection. Requires a config file.
 
-Renders output files from the resolved DSL using Handlebars templates configured in agent-contracts.config.yaml. Supports drift detection via --check mode. Requires a config file.
+> **Deprecated**: Use 'agent-contracts generate templates' instead.
+> Use `generate templates` instead.
 
 **Usage:**
 
@@ -238,16 +250,16 @@ agent-contracts render --quiet
 |---|---|---|---|---|
 | `--config` | -c | No |  | Path to agent-contracts.config.yaml. |
 | `--team` |  | No |  | Limit to one team (multi-team config only). |
-| `--check` |  | No | `false` | Check for drift without writing files. |
+| `--check` |  | No | `false` | Check for template drift without writing files. |
 | `--quiet` |  | No | `false` | Suppress output on success. |
 
 #### Exit Codes
 
-**Exit 0:** Render succeeded (or no drift detected in --check mode).
+**Exit 0:** Generation succeeded (or no drift detected in --check mode).
 
 - **stdout:** format=`text`
 
-**Exit 1:** Render failed, config not found, schema validation failed, or drift detected in --check mode.
+**Exit 1:** Generation failed, config not found, schema validation failed, or drift detected in --check mode.
 
 - **stderr:** format=`text`
 
@@ -258,11 +270,17 @@ x-agent:
   riskLevel: medium
   requiresConfirmation: false
   idempotent: true
+  idempotentNote: Output is deterministic from DSL input and templates. Repeated runs produce identical files. This is a deprecated alias; prefer 'generate templates'.
   sideEffects: 
     - file_write
+  sideEffectNote: Writes rendered files to configured output paths. No file writes occur when --check is specified.
+  safeDryRunOption: check
   recommendedBeforeUse: 
     - Ensure agent-contracts.config.yaml exists with render targets.
     - Run validate first to confirm DSL is valid.
+  expectedDurationMs: 5000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -271,7 +289,7 @@ x-agent:
 
 Run full pipeline — resolve, validate, lint, render --check.
 
-Executes the complete verification pipeline in order: resolve DSL, validate schema and references, run lint rules, and check for render drift. Also verifies cross-team interface imports and team-interface.yaml drift when applicable.
+Executes the complete verification pipeline in order: (1) resolve DSL, (2) validate schema and references, (3) run lint rules, (4) check render drift via render --check. Steps 1–4 always run. Additionally, when the DSL declares cross-team interfaces, (5) verifies interface import consistency and (6) checks team-interface.yaml drift. Steps 5–6 are skipped when no cross-team interfaces exist.
 
 **Usage:**
 
@@ -299,7 +317,7 @@ agent-contracts check --format json --quiet
 
 **Exit 0:** All checks passed.
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** One or more checks failed — validation errors, lint errors, render drift, or missing interface files.
 
@@ -316,6 +334,9 @@ x-agent:
 
   recommendedBeforeUse: 
     - Ensure agent-contracts.config.yaml exists.
+  expectedDurationMs: 10000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -360,7 +381,7 @@ agent-contracts score -c agent-contracts.config.yaml
 
 **Exit 0:** Score calculated (and above threshold if specified).
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Score below threshold, schema validation failed, or unexpected error.
 
@@ -375,6 +396,9 @@ x-agent:
   idempotent: true
   sideEffects: 
 
+  expectedDurationMs: 5000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -426,22 +450,463 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
 | `--dry-run` |  | No | `false` | Output the audit prompt without calling LLM. |
 | `--adapter` |  | No |  | SDK adapter to use for LLM calls (overrides config audit.adapter). |
 | `--model` |  | No |  | LLM model override (overrides config audit.model). |
+| `--fail-on` |  | No | `"critical"` | Minimum finding severity that causes exit 10 (info|warning|error|critical). |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"text"` | Alias for --format. When both are specified, --report-format takes precedence. |
 
 #### Exit Codes
 
-**Exit 0:** No critical findings detected.
+**Exit 0:** Audit succeeded. No findings at or above --fail-on threshold.
+
+- **stdout:** format=`{options.format}`
+
+  | Property | Type | Required | Description |
+  |---|---|---|---|
+  | `summary` | `string` | Yes |  |
+  | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes |  |
+  | `findings` | `object[]` | Yes |  |
+  | `findings[].id` | `string` | No | Unique finding identifier. |
+  | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes |  |
+  | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
+  | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
+  | `findings[].location` | `string` | No | Location within the target. |
+  | `findings[].message` | `string` | Yes |  |
+  | `findings[].recommendation` | `string` | No |  |
+  | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
+  | `findings[].evidence` | `object[]` | No |  |
+  | `findings[].evidence[].kind` | `enum(7 values)` | Yes |  |
+  | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
+  | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
+  | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
+  | `findings[].details` | `Record<string, any>` | No |  |
+  | `recommendedActions` | `object[]` | No |  |
+  | `recommendedActions[].kind` | `enum(6 values)` | Yes |  |
+  | `recommendedActions[].title` | `string` | Yes |  |
+  | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
+  | `recommendedActions[].target` | `string` | No | Target file or resource. |
+  | `recommendedActions[].rationale` | `string` | No |  |
+  | `metadata` | `object` | No |  |
+  | `metadata.tool` | `string` | No |  |
+  | `metadata.command` | `string` | No |  |
+  | `metadata.version` | `string` | No |  |
+  | `metadata.generatedAt` | `string` | No |  |
+  | `metadata.adapter` | `string` | No |  |
+  | `metadata.model` | `string` | No |  |
+
+  <details>
+  <summary>JSON Schema</summary>
+
+  ```json
+  {
+    "type": "object",
+    "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
+    "required": [
+      "summary",
+      "riskLevel",
+      "findings"
+    ],
+    "properties": {
+      "summary": {
+        "type": "string"
+      },
+      "riskLevel": {
+        "type": "string",
+        "enum": [
+          "low",
+          "medium",
+          "high",
+          "critical"
+        ]
+      },
+      "findings": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "description": "A single finding from an agent audit or analysis.",
+          "required": [
+            "severity",
+            "category",
+            "message"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "Unique finding identifier."
+            },
+            "severity": {
+              "type": "string",
+              "enum": [
+                "info",
+                "warning",
+                "error",
+                "critical"
+              ]
+            },
+            "category": {
+              "type": "string",
+              "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
+            },
+            "target": {
+              "type": "string",
+              "description": "Target of the finding (command ID, schema path)."
+            },
+            "location": {
+              "type": "string",
+              "description": "Location within the target."
+            },
+            "message": {
+              "type": "string"
+            },
+            "recommendation": {
+              "type": "string"
+            },
+            "confidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Confidence score (0-1) for LLM-generated findings."
+            },
+            "evidence": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "description": "Evidence supporting an agent finding.",
+                "required": [
+                  "kind"
+                ],
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "file",
+                      "command",
+                      "schema",
+                      "diff",
+                      "stdout",
+                      "stderr",
+                      "text"
+                    ]
+                  },
+                  "target": {
+                    "type": "string",
+                    "description": "Target identifier (file path, command ID, schema name)."
+                  },
+                  "location": {
+                    "type": "string",
+                    "description": "Location within the target (line number, JSON pointer)."
+                  },
+                  "excerpt": {
+                    "type": "string",
+                    "description": "Relevant excerpt from the target."
+                  }
+                }
+              }
+            },
+            "details": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      },
+      "recommendedActions": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "description": "A recommended action from an agent audit.",
+          "required": [
+            "kind",
+            "title"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "run_command",
+                "edit_file",
+                "review",
+                "confirm",
+                "block",
+                "ignore"
+              ]
+            },
+            "title": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "CLI command to run (for run_command kind)."
+            },
+            "target": {
+              "type": "string",
+              "description": "Target file or resource."
+            },
+            "rationale": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "metadata": {
+        "type": "object",
+        "properties": {
+          "tool": {
+            "type": "string"
+          },
+          "command": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "generatedAt": {
+            "type": "string"
+          },
+          "adapter": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  </details>
+
+**Exit 1:** Unexpected error (invalid input, config error, or internal failure).
 
-- **stdout:** format=`text`
+- **stderr:** format=`text`
 
-**Exit 1:** Critical findings detected.
+**Exit 10:** Findings at or above --fail-on severity threshold detected.
+
+- **stdout:** format=`{options.format}`
+
+  | Property | Type | Required | Description |
+  |---|---|---|---|
+  | `summary` | `string` | Yes |  |
+  | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes |  |
+  | `findings` | `object[]` | Yes |  |
+  | `findings[].id` | `string` | No | Unique finding identifier. |
+  | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes |  |
+  | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
+  | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
+  | `findings[].location` | `string` | No | Location within the target. |
+  | `findings[].message` | `string` | Yes |  |
+  | `findings[].recommendation` | `string` | No |  |
+  | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
+  | `findings[].evidence` | `object[]` | No |  |
+  | `findings[].evidence[].kind` | `enum(7 values)` | Yes |  |
+  | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
+  | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
+  | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
+  | `findings[].details` | `Record<string, any>` | No |  |
+  | `recommendedActions` | `object[]` | No |  |
+  | `recommendedActions[].kind` | `enum(6 values)` | Yes |  |
+  | `recommendedActions[].title` | `string` | Yes |  |
+  | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
+  | `recommendedActions[].target` | `string` | No | Target file or resource. |
+  | `recommendedActions[].rationale` | `string` | No |  |
+  | `metadata` | `object` | No |  |
+  | `metadata.tool` | `string` | No |  |
+  | `metadata.command` | `string` | No |  |
+  | `metadata.version` | `string` | No |  |
+  | `metadata.generatedAt` | `string` | No |  |
+  | `metadata.adapter` | `string` | No |  |
+  | `metadata.model` | `string` | No |  |
+
+  <details>
+  <summary>JSON Schema</summary>
+
+  ```json
+  {
+    "type": "object",
+    "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
+    "required": [
+      "summary",
+      "riskLevel",
+      "findings"
+    ],
+    "properties": {
+      "summary": {
+        "type": "string"
+      },
+      "riskLevel": {
+        "type": "string",
+        "enum": [
+          "low",
+          "medium",
+          "high",
+          "critical"
+        ]
+      },
+      "findings": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "description": "A single finding from an agent audit or analysis.",
+          "required": [
+            "severity",
+            "category",
+            "message"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "Unique finding identifier."
+            },
+            "severity": {
+              "type": "string",
+              "enum": [
+                "info",
+                "warning",
+                "error",
+                "critical"
+              ]
+            },
+            "category": {
+              "type": "string",
+              "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
+            },
+            "target": {
+              "type": "string",
+              "description": "Target of the finding (command ID, schema path)."
+            },
+            "location": {
+              "type": "string",
+              "description": "Location within the target."
+            },
+            "message": {
+              "type": "string"
+            },
+            "recommendation": {
+              "type": "string"
+            },
+            "confidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Confidence score (0-1) for LLM-generated findings."
+            },
+            "evidence": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "description": "Evidence supporting an agent finding.",
+                "required": [
+                  "kind"
+                ],
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "file",
+                      "command",
+                      "schema",
+                      "diff",
+                      "stdout",
+                      "stderr",
+                      "text"
+                    ]
+                  },
+                  "target": {
+                    "type": "string",
+                    "description": "Target identifier (file path, command ID, schema name)."
+                  },
+                  "location": {
+                    "type": "string",
+                    "description": "Location within the target (line number, JSON pointer)."
+                  },
+                  "excerpt": {
+                    "type": "string",
+                    "description": "Relevant excerpt from the target."
+                  }
+                }
+              }
+            },
+            "details": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      },
+      "recommendedActions": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "description": "A recommended action from an agent audit.",
+          "required": [
+            "kind",
+            "title"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "run_command",
+                "edit_file",
+                "review",
+                "confirm",
+                "block",
+                "ignore"
+              ]
+            },
+            "title": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "CLI command to run (for run_command kind)."
+            },
+            "target": {
+              "type": "string",
+              "description": "Target file or resource."
+            },
+            "rationale": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "metadata": {
+        "type": "object",
+        "properties": {
+          "tool": {
+            "type": "string"
+          },
+          "command": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "generatedAt": {
+            "type": "string"
+          },
+          "adapter": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  </details>
 
-- **stdout:** format=`text`
+- **stderr:** format=`text`
 
-**Exit 2:** Invalid input or configuration error.
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime not installed).
 
 - **stderr:** format=`text`
 
-**Exit 3:** LLM adapter error (API failure, runtime not installed).
+**Exit 12:** LLM provider or adapter error (API failure, auth error).
 
 - **stderr:** format=`text`
 
@@ -449,11 +914,17 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
 
 ```yaml
 x-agent: 
-  riskLevel: low
+  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: Makes LLM API calls to the configured adapter (e.g. OpenAI, Gemini, Cursor) unless --dry-run is specified. Incurs token cost and sends DSL content to the LLM provider.
+  safeDryRunOption: dry-run
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
   recommendedBeforeUse: 
     - Ensure agent-contracts.config.yaml exists with render targets.
     - Run validate first to confirm DSL is valid.
@@ -464,16 +935,25 @@ x-agent:
 
 ### generate
 
-Generate guardrail or interface artifacts from DSL.
+Generate artifacts from DSL — templates, guardrails, and/or interface.
 
-Generates runtime artifacts from the DSL. When type is "guardrails" (default), produces guardrail binding files from DSL, policies, and software bindings. When type is "interface", generates a team interface YAML/JSON file from the DSL's team_interface section.
+Unified generation command. When type is omitted, runs all generation targets (templates, guardrails, interface). When type is "templates", renders output files from the DSL using Handlebars templates. When type is "guardrails", produces guardrail binding files from DSL, policies, and software bindings. When type is "interface", generates a team interface YAML/JSON file from the DSL's team_interface section.
 
 **Usage:**
 
+```
+agent-contracts generate
+```
 ```
 agent-contracts generate -c agent-contracts.config.yaml
 ```
 ```
+agent-contracts generate templates
+```
+```
+agent-contracts generate templates --check
+```
+```
 agent-contracts generate guardrails -c agent-contracts.config.yaml
 ```
 ```
@@ -496,7 +976,7 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 
 | Name | Required | Description |
 |---|---|---|
-| `type` | No | Type of artifacts to generate. |
+| `type` | No | Type of artifacts to generate. Omit to run all targets. |
 
 #### Options
 
@@ -504,6 +984,7 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 |---|---|---|---|---|
 | `--config` | -c | No |  | Path to agent-contracts.config.yaml. |
 | `--team` |  | No |  | Limit to one team (multi-team config only). |
+| `--check` |  | No | `false` | Check for template drift without writing files. Only applies to the templates target. |
 | `--binding` |  | No |  | Filter to specific software binding(s). Guardrails type only. |
 | `--output` | -o | No |  | Output path for generated team interface. Interface type only. |
 | `--format` |  | No | `"yaml"` | Output format for team interface (yaml or json). Interface type only. |
@@ -512,11 +993,11 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 
 #### Exit Codes
 
-**Exit 0:** Generation succeeded.
+**Exit 0:** Generation succeeded (or no drift detected in --check mode).
 
 - **stdout:** format=`text`
 
-**Exit 1:** Generation failed — unknown type, schema validation failed, config not found, or error-level diagnostics.
+**Exit 1:** Generation failed — unknown type, schema validation failed, config not found, drift detected, or error-level diagnostics.
 
 - **stderr:** format=`text`
 
@@ -527,11 +1008,17 @@ x-agent:
   riskLevel: medium
   requiresConfirmation: false
   idempotent: true
+  idempotentNote: Output is deterministic from DSL input, templates, policies, and bindings. Repeated runs produce identical files. Confirmation is not required because the command is idempotent and --dry-run / --check provide side-effect-free preview modes.
   sideEffects: 
     - file_write
+  sideEffectNote: Writes rendered template files, guardrail binding files, and/or team interface files to configured output paths. No file writes occur when --dry-run or --check is specified (--check applies to templates only).
+  safeDryRunOption: dry-run
   recommendedBeforeUse: 
-    - Ensure agent-contracts.config.yaml exists with binding definitions.
+    - Ensure agent-contracts.config.yaml exists with render targets and/or binding definitions.
     - Run validate first to confirm DSL is valid.
+  expectedDurationMs: 5000
+  retryableExitCodes: 
+
 ```
 
 ---