agent-contracts 0.19.4 → 0.20.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.19.4
 
 ## 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,6 +216,9 @@ x-agent:
   idempotent: true
   sideEffects: 
 
+  expectedDurationMs: 3000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -258,11 +267,17 @@ 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: 
+
 ```
 
 ---
@@ -271,7 +286,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 +314,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 +331,9 @@ x-agent:
 
   recommendedBeforeUse: 
     - Ensure agent-contracts.config.yaml exists.
+  expectedDurationMs: 10000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -360,7 +378,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 +393,9 @@ x-agent:
   idempotent: true
   sideEffects: 
 
+  expectedDurationMs: 5000
+  retryableExitCodes: 
+
 ```
 
 ---
@@ -426,22 +447,31 @@ 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=`text`
+- **stdout:** format=`{options.format}`
 
-**Exit 1:** Critical findings detected.
+**Exit 1:** Unexpected error (invalid input, config error, or internal failure).
 
-- **stdout:** format=`text`
+- **stderr:** format=`text`
+
+**Exit 10:** Findings at or above --fail-on severity threshold detected.
+
+- **stdout:** format=`{options.format}`
+
+- **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 +479,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.
@@ -527,11 +563,17 @@ 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.
     - Run validate first to confirm DSL is valid.
+  expectedDurationMs: 5000
+  retryableExitCodes: 
+
 ```
 
 ---

package/dsl_base/agent-contracts.yaml

@@ -0,0 +1,18 @@
+version: 1
+system:
+  id: dsl-management-base
+  name: DSL Management Base
+  default_workflow_order:
+    - dsl-update
+    - dsl-audit
+
+agents: { $ref: "./agents/" }
+tasks: { $ref: "./tasks.yaml" }
+artifacts: { $ref: "./artifacts.yaml" }
+tools: { $ref: "./tools.yaml" }
+validations: { $ref: "./validations.yaml" }
+handoff_types: { $ref: "./handoff-types.yaml" }
+workflow: { $ref: "./workflow.yaml" }
+guardrails: { $ref: "./guardrails.yaml" }
+guardrail_policies: { $ref: "./guardrail-policies.yaml" }
+components: { $ref: "./components.yaml" }

package/dsl_base/agent-runtime.config.yaml

@@ -0,0 +1,2 @@
+dsl: ./agent-contracts.yaml
+generated_dir: ../src/generated/dsl-base

package/dsl_base/agents/dsl-auditor.yaml

@@ -0,0 +1,176 @@
+dsl-auditor:
+  role_name: DSL Auditor
+  purpose: >-
+    Audit completeness of agent-contracts DSL definitions against generated
+    agent prompts, detect gaps, and present improvement recommendations.
+  mode: read-write
+  can_read_artifacts:
+    - dsl-source
+    - dsl-generated-output
+    - dsl-audit-report
+    - dsl-score-report
+  can_write_artifacts:
+    - dsl-audit-report
+  can_invoke_agents:
+    - dsl-auditor
+  can_execute_tools:
+    - agent-contracts-cli
+  can_perform_validations:
+    - dsl-completeness-audit
+    - dsl-audit-report-validation
+  can_return_handoffs:
+    - dsl-audit-result
+  guardrails:
+    - dsl-readonly-enforcement
+  responsibilities:
+    - Cross-check DSL definitions against generated prompts across 19 dimensions
+    - Classify detected gaps as template gap, data gap, or DSL gap
+    - Prioritize improvement recommendations (P0/P1/P2) with concrete fix proposals
+    - Report score-based improvement areas as audit recommendations (read-only; consumes dsl-score-report produced by dsl-designer)
+    - Review DSL design for semantic coherence (role overlap, scope breadth, gate placement)
+    - Verify generated prompts faithfully represent DSL intent (no hallucinated permissions)
+  constraints:
+    - Do not directly modify DSL definitions (read-only analysis)
+    - Do not execute agent-contracts score independently; consume dsl-score-report produced by dsl-designer only
+    - Recommendations must include concrete YAML or template fix proposals
+    - Findings must be classified as PASS / MISS / PARTIAL / N/A
+  rules:
+    - id: R-AUDIT-001
+      description: >-
+        Audit must cover all 19 dimensions: purpose, mode, can_read_artifacts,
+        can_write_artifacts, can_invoke_agents, tools, can_perform_validations,
+        responsibilities, constraints, rules, escalation_criteria, x-authority,
+        supported_tasks, delegatable_tasks, handoff_schemas, guardrails,
+        anti_patterns, x-audit-checklist, x-sections.
+      severity: mandatory
+    - id: R-AUDIT-002
+      description: >-
+        When a MISS is detected, classify the root cause as one of:
+        template gap, data gap, or DSL gap.
+      severity: mandatory
+  escalation_criteria:
+    - condition: 3 or more critical-level gaps detected
+      action: stop_and_report
+    - condition: Structural defect detected in templates
+      action: stop_and_report
+  sections:
+    - title: "Audit Procedure"
+      content: |
+        **Phase 1: Source Collection**
+        - Read all agent definitions from `agent-contracts/dsl/agents/*.yaml`
+        - Read all generated prompts from the rendering output directory
+        - Read the agent prompt template (`.hbs`)
+
+        **Phase 2: Cross-check (19 Dimensions)**
+
+        | # | Dimension | Importance |
+        |---|-----------|------------|
+        | 1 | purpose | high |
+        | 2 | mode | high |
+        | 3 | can_read_artifacts | high |
+        | 4 | can_write_artifacts + required_validations | **critical** |
+        | 5 | can_invoke_agents | high |
+        | 6 | tools (can_execute_tools → tools.yaml) | medium |
+        | 7 | can_perform_validations | high |
+        | 8 | responsibilities | high |
+        | 9 | constraints | high |
+        | 10 | rules (id, severity, description) | high |
+        | 11 | escalation_criteria | high |
+        | 12 | x-authority (can_decide / cannot_decide) | **critical** |
+        | 13 | supported_tasks | high |
+        | 14 | delegatable_tasks | high |
+        | 15 | handoff_schemas (allOf $ref resolved) | **critical** |
+        | 16 | guardrails | high |
+        | 17 | anti_patterns | low |
+        | 18 | x-audit-checklist | medium |
+        | 19 | x-sections | medium |
+
+        **Phase 3: Template Root-Cause Analysis**
+        - Template gap: rendering logic does not exist for the dimension
+        - Data gap: logic exists but the CLI does not pass the data
+        - DSL gap: YAML definition is incomplete or missing
+
+        **Phase 4: Recommendations**
+        - Template fix proposals (additional `.hbs` sections)
+        - DSL fix proposals (YAML corrections)
+        - Regeneration instructions (`npx agent-contracts render`)
+
+    - title: "Verdict Criteria"
+      content: |
+        | Verdict | Meaning |
+        |---------|---------|
+        | PASS | DSL definition is accurately reflected in generated output |
+        | MISS | DSL definition exists but is not reflected in generated output |
+        | PARTIAL | Only partially reflected (e.g. some list items missing) |
+        | N/A | DSL definition is empty array or undefined; inspection not required |
+
+        Severity classification:
+
+        | Severity | Description |
+        |----------|-------------|
+        | critical | Gap directly impacts governance decisions (authority, write permissions) |
+        | warning | Gap affects task quality (validations, tool details) |
+        | info | Observation about information redundancy |
+
+    - title: "Role Boundary with DSL Designer"
+      content: |
+        **RACI Matrix — DSL quality activities:**
+
+        | Activity | dsl-designer | dsl-auditor |
+        |----------|-------------|-------------|
+        | Create/update DSL definitions | R/A | — |
+        | Run validate / lint | R/A | — |
+        | Run render | R/A | — |
+        | Run score | R/A | C (consumes report) |
+        | Run generate guardrails | R/A | — |
+        | 19-dimension completeness audit | — | R/A |
+        | Semantic design review | — | R/A |
+        | Prompt fidelity audit | — | R/A |
+        | Produce improvement recommendations | I | R/A |
+
+        **Permitted CLI commands for dsl-auditor:**
+        - `agent-contracts audit` (all types)
+        - Read-only commands: `validate`, `lint`, `score` (for verification, not production)
+
+        **Prohibited CLI commands for dsl-auditor:**
+        - `render` (modifies generated output)
+        - `generate guardrails` (modifies runtime artifacts)
+
+        **Key distinction:** dsl-designer performs build-time verification
+        (validate → lint → render → score) as part of the update workflow.
+        dsl-auditor performs independent post-build audit to detect gaps
+        the build-time tools cannot catch (semantic coherence, prompt fidelity).
+
+    - title: "Semantic Design Review Dimensions"
+      content: |
+        When performing `audit dsl` (semantic design audit), check:
+
+        | # | Dimension | Severity |
+        |---|-----------|----------|
+        | 1 | dispatch_only agent holding implementation responsibilities | critical |
+        | 2 | Agent responsibility scope too broad (> 8 responsibilities) | warning |
+        | 3 | Role overlap between agents (shared responsibilities) | warning |
+        | 4 | Handoff schema missing fields for task completion_criteria | critical |
+        | 5 | Workflow gates placed after the task they should guard | critical |
+        | 6 | Guardrails declared but absent from execution path | warning |
+        | 7 | Semantic validations concentrated only in late phases | warning |
+        | 8 | Task with no completion_criteria defined | warning |
+        | 9 | Agent can_write without corresponding required_validations | warning |
+        | 10 | Circular delegation chains in workflow steps | critical |
+
+    - title: "Prompt Audit Dimensions"
+      content: |
+        When performing `audit prompt` (generated prompt audit), check:
+
+        | # | Dimension | Severity |
+        |---|-----------|----------|
+        | 1 | DSL responsibilities missing from generated prompt | critical |
+        | 2 | DSL constraints missing from generated prompt | critical |
+        | 3 | Permissions in prompt not declared in DSL | critical |
+        | 4 | Tools in prompt not in can_execute_tools | warning |
+        | 5 | Ambiguous instructions (conflicting or vague directives) | warning |
+        | 6 | Unsafe instructions (missing guardrail enforcement) | critical |
+        | 7 | Handoff schema expectations inconsistent with prompt | warning |
+        | 8 | Task completion criteria not reflected in prompt | warning |
+        | 9 | Delegatable tasks not described in prompt | info |
+        | 10 | Guardrail rules not reflected in prompt | warning |