agent-contracts 0.21.0 → 0.22.0

package/README.md

@@ -1011,7 +1011,7 @@ VarsSubstitutionError: Undefined variable "repo_url" in value "Repository: ${var
 
 For the full CLI reference with all commands, options, arguments, exit codes, and AI agent policies, see the [CLI Reference](docs/cli-reference.md).
 
-The CLI contract specification is defined in [`cli-contract.yaml`](cli-contract.yaml) using [CLI Contracts](https://github.com/foo-ogawa/cli-contracts).
+The CLI contract specification is defined in [`cli-contract.yaml`](cli-contract.yaml) using [CLI Contracts](https://github.com/foo-ogawa/cli-contracts). Commands that have side effects declare structured `effects` metadata, and the `--introspect` global option outputs the derived policy as JSON without executing the command.
 
 ### Installation
 
@@ -1042,6 +1042,40 @@ If `-c` / `--config` is specified, the DSL path from the config file is used.
 
 All commands also accept `--team <id>` to limit execution to a single team when using a [multi-team configuration](#multi-team-configuration).
 
+#### `--introspect` (global)
+
+Any command can be invoked with `--introspect` to output the derived policy as JSON **without executing** the command. This is useful for AI agents to inspect what side effects a command would have before deciding whether to run it.
+
+````bash
+agent-contracts generate --introspect
+agent-contracts audit --introspect
+agent-contracts validate --introspect
+````
+
+The output follows the [CLI Contracts](https://github.com/foo-ogawa/cli-contracts) `IntrospectionResult` shape:
+
+````json
+{
+  "command": "generate",
+  "activeOptions": ["format"],
+  "policy": {
+    "riskLevel": "low",
+    "requiresConfirmation": false,
+    "idempotent": true,
+    "sideEffects": ["file_write"],
+    "reads": [],
+    "writes": [
+      {
+        "kind": "semantic",
+        "target": "configured render, guardrail, and interface output paths",
+        "idempotent": true,
+        "source": "command:generate"
+      }
+    ]
+  }
+}
+````
+
 #### `resolve` options
 
 | Option | Description |

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: agent-contracts CLI
-  version: 0.21.0
+  version: 0.22.0
   description: >-
     Declarative YAML DSL toolkit for defining, validating, and rendering
     multi-agent development workflows. Provides static validation,
@@ -112,14 +112,6 @@ commandSets:
             stderr:
               format: text
 
-        x-agent:
-          riskLevel: low
-          requiresConfirmation: false
-          idempotent: true
-          sideEffects: []
-          expectedDurationMs: 3000
-          retryableExitCodes: []
-
       # ── validate ──────────────────────────────────────
       validate:
         summary: Validate DSL against schema and check references.
@@ -203,14 +195,6 @@ commandSets:
             stderr:
               format: text
 
-        x-agent:
-          riskLevel: low
-          requiresConfirmation: false
-          idempotent: true
-          sideEffects: []
-          expectedDurationMs: 3000
-          retryableExitCodes: []
-
       # ── lint ──────────────────────────────────────────
       lint:
         summary: Run semantic lint rules on resolved DSL.
@@ -293,14 +277,6 @@ commandSets:
             stderr:
               format: text
 
-        x-agent:
-          riskLevel: low
-          requiresConfirmation: false
-          idempotent: true
-          sideEffects: []
-          expectedDurationMs: 3000
-          retryableExitCodes: []
-
       # ── render (deprecated alias) ─────────────────────
       render:
         summary: (deprecated) Alias for 'generate templates'.
@@ -318,6 +294,17 @@ commandSets:
           - agent-contracts render -c agent-contracts.config.yaml --check
           - agent-contracts render --quiet
 
+        effects:
+          riskLevel: medium
+          writes:
+            - target: "configured render output paths"
+              description: "rendered template files from DSL input"
+              overwrite: true
+              idempotent: true
+              idempotentNote: >-
+                Output is deterministic from DSL input and templates.
+                Repeated runs produce identical files.
+
         options:
           - name: config
             aliases: [c]
@@ -363,24 +350,9 @@ commandSets:
               format: text
 
         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: []
 
       # ── check ─────────────────────────────────────────
       check:
@@ -455,14 +427,8 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: low
-          requiresConfirmation: false
-          idempotent: true
-          sideEffects: []
           recommendedBeforeUse:
             - Ensure agent-contracts.config.yaml exists.
-          expectedDurationMs: 10000
-          retryableExitCodes: []
 
       # ── score ─────────────────────────────────────────
       score:
@@ -544,14 +510,6 @@ commandSets:
             stderr:
               format: text
 
-        x-agent:
-          riskLevel: low
-          requiresConfirmation: false
-          idempotent: true
-          sideEffects: []
-          expectedDurationMs: 5000
-          retryableExitCodes: []
-
       # ── audit ───────────────────────────────────────────
       audit:
         summary: Run LLM-based semantic audit on DSL definitions and generated outputs.
@@ -573,6 +531,18 @@ commandSets:
           - agent-contracts audit render --format json -c agent-contracts.config.yaml
           - agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
 
+        effects:
+          riskLevel: medium
+          network:
+            description: >-
+              LLM API calls to configured adapter (e.g. OpenAI,
+              Gemini, Cursor). Incurs token cost and sends DSL
+              content to the LLM provider.
+            idempotent: false
+            idempotentNote: >-
+              LLM inference is non-deterministic — identical inputs
+              may produce different findings across runs.
+
         arguments:
           - name: type
             index: 0
@@ -708,22 +678,6 @@ commandSets:
               format: text
 
         x-agent:
-          riskLevel: medium
-          requiresConfirmation: false
-          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.
@@ -753,6 +707,20 @@ commandSets:
           - agent-contracts generate interface --format json
           - agent-contracts generate interface -o team-interface.yaml --dry-run
 
+        effects:
+          riskLevel: low
+          writes:
+            - target: "configured render, guardrail, and interface output paths"
+              description: >-
+                template files, guardrail binding files, and/or team
+                interface files generated from DSL input
+              overwrite: true
+              idempotent: true
+              idempotentNote: >-
+                Output is deterministic from DSL input, templates,
+                policies, and bindings. Repeated runs produce
+                identical files.
+
         arguments:
           - name: type
             index: 0
@@ -842,25 +810,6 @@ commandSets:
               format: text
 
         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 render targets and/or binding definitions.
             - Run validate first to confirm DSL is valid.
-          expectedDurationMs: 5000
-          retryableExitCodes: []