agent-contracts 0.20.0 → 0.22.0

package/README.md

@@ -151,11 +151,11 @@ artifacts:
     states: [draft, reviewed, approved]
 ````
 
-Validate and render:
+Validate and generate:
 
 ````bash
 agent-contracts validate
-agent-contracts render -c agent-contracts.config.yaml
+agent-contracts generate -c agent-contracts.config.yaml
 ````
 
 
@@ -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
 
@@ -1028,18 +1028,54 @@ npx agent-contracts
 | `agent-contracts resolve [path]`  | Resolve `extends` inheritance and output resolved YAML |
 | `agent-contracts validate [path]` | Validate schema and references                         |
 | `agent-contracts lint [path]`     | Run semantic lint                                      |
-| `agent-contracts render`          | Render outputs from config                             |
-| `agent-contracts score [path]`    | Calculate DSL completeness score                       |
+| `agent-contracts generate`        | Generate all artifacts (templates + guardrails + interface) |
+| `agent-contracts generate templates` | Render template outputs from config                |
 | `agent-contracts generate guardrails` | Generate guardrail artifacts from bindings       |
-| `agent-contracts generate interface` | Generate team interface YAML from DSL |
+| `agent-contracts generate interface` | Generate team interface YAML from DSL            |
+| `agent-contracts score [path]`    | Calculate DSL completeness score                       |
 | `agent-contracts audit <type>`    | Run LLM-based semantic audit (render/dsl/prompt/all)   |
 | `agent-contracts check`           | Run resolve → validate → lint → render --check         |
+| `agent-contracts render`          | _(deprecated)_ Alias for `generate templates`          |
 
 The `[path]` argument defaults to `agent-contracts.yaml` in the current directory.
 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 |
@@ -1100,8 +1136,9 @@ agent-contracts lint --strict
 agent-contracts score
 agent-contracts score -c agent-contracts.config.yaml --threshold 70
 agent-contracts score --format json
-agent-contracts render -c agent-contracts.config.yaml
-agent-contracts render -c agent-contracts.config.yaml --check
+agent-contracts generate -c agent-contracts.config.yaml
+agent-contracts generate templates -c agent-contracts.config.yaml
+agent-contracts generate templates -c agent-contracts.config.yaml --check
 agent-contracts check -c agent-contracts.config.yaml --strict
 agent-contracts generate interface -c agent-contracts.config.yaml
 agent-contracts generate interface -c agent-contracts.config.yaml --dry-run
@@ -1239,7 +1276,7 @@ renders:
 
 Tools with `x-script` get a generated script file; tools without it produce no file at all.
 
-`skip_empty` also works with `render --check` (drift detection): when the expected output is empty, the check expects the file to **not exist** and reports drift if it does.
+`skip_empty` also works with `generate templates --check` (drift detection): when the expected output is empty, the check expects the file to **not exist** and reports drift if it does.
 
 ### Available context types
 
@@ -1724,7 +1761,7 @@ A practical model is:
 
 1. define the workflow in YAML
 2. validate and lint it in CI
-3. render prompts and derived docs
+3. generate prompts and derived docs
 4. execute the workflow in your runtime of choice
 
 That separation keeps runtime concerns and architecture concerns from being mixed together.

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: agent-contracts CLI
-  version: 0.20.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,26 +277,34 @@ commandSets:
             stderr:
               format: text
 
-        x-agent:
-          riskLevel: low
-          requiresConfirmation: false
-          idempotent: true
-          sideEffects: []
-          expectedDurationMs: 3000
-          retryableExitCodes: []
-
-      # ── render ────────────────────────────────────────
+      # ── render (deprecated alias) ─────────────────────
       render:
-        summary: Render resolved DSL with Handlebars templates.
+        summary: (deprecated) Alias for 'generate templates'.
+        deprecated:
+          message: >-
+            Use 'agent-contracts generate templates' instead.
+          alternative: generate templates
         description: >-
+          Deprecated alias for 'agent-contracts generate templates'.
           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.
+          templates and emits a deprecation warning. Supports --check
+          for drift detection. Requires a config file.
         usage:
           - agent-contracts render -c agent-contracts.config.yaml
           - 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]
@@ -333,7 +325,7 @@ commandSets:
               type: string
 
           - name: check
-            description: Check for drift without writing files.
+            description: Check for template drift without writing files.
             schema:
               type: boolean
               default: false
@@ -346,37 +338,21 @@ commandSets:
 
         exits:
           '0':
-            description: Render succeeded (or no drift detected in --check mode).
+            description: Generation succeeded (or no drift detected in --check mode).
             stdout:
               format: text
 
           '1':
             description: >-
-              Render failed, config not found, schema validation failed,
-              or drift detected in --check mode.
+              Generation failed, config not found, schema validation
+              failed, or drift detected in --check mode.
             stderr:
               format: text
 
         x-agent:
-          riskLevel: medium
-          requiresConfirmation: false
-          idempotent: true
-          idempotentNote: >-
-            Output is deterministic from DSL input and templates.
-            Repeated runs produce identical files. Confirmation is not
-            required because the command is idempotent and --check
-            provides a side-effect-free preview mode.
-          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:
@@ -451,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:
@@ -540,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.
@@ -569,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
@@ -704,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.
@@ -728,15 +686,20 @@ commandSets:
 
       # ── generate ──────────────────────────────────────
       generate:
-        summary: Generate guardrail or interface artifacts from DSL.
+        summary: Generate artifacts from DSL — templates, guardrails, and/or interface.
         description: >-
-          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
           - agent-contracts generate guardrails --binding cursor-rules
           - agent-contracts generate guardrails --dry-run
@@ -744,15 +707,29 @@ 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
             required: false
-            description: Type of artifacts to generate.
+            description: >-
+              Type of artifacts to generate. Omit to run all targets.
             schema:
               type: string
-              enum: [guardrails, interface]
-              default: guardrails
+              enum: [templates, guardrails, interface]
 
         options:
           - name: config
@@ -773,6 +750,14 @@ commandSets:
             schema:
               type: string
 
+          - name: check
+            description: >-
+              Check for template drift without writing files.
+              Only applies to the templates target.
+            schema:
+              type: boolean
+              default: false
+
           - name: binding
             description: Filter to specific software binding(s). Guardrails type only.
             valueName: name
@@ -813,36 +798,18 @@ commandSets:
 
         exits:
           '0':
-            description: Generation succeeded.
+            description: Generation succeeded (or no drift detected in --check mode).
             stdout:
               format: text
 
           '1':
             description: >-
               Generation failed — unknown type, schema validation failed,
-              config not found, or error-level diagnostics.
+              config not found, drift detected, or error-level diagnostics.
             stderr:
               format: text
 
         x-agent:
-          riskLevel: medium
-          requiresConfirmation: false
-          idempotent: true
-          idempotentNote: >-
-            Output is deterministic from DSL input, policies, and
-            bindings. Repeated runs produce identical files.
-            Confirmation is not required because the command is
-            idempotent and --dry-run provides a side-effect-free
-            preview mode.
-          sideEffects:
-            - file_write
-          sideEffectNote: >-
-            Writes guardrail binding files or team interface files to
-            configured output paths. No file writes occur when
-            --dry-run is specified.
-          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: []