agent-contracts 0.25.0 → 0.30.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.22.3
+**Version:** 0.30.0
 
 ## Table of Contents
 
@@ -15,6 +15,7 @@ Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent
   - [score](#agent-contracts-score)
   - [audit](#agent-contracts-audit)
   - [generate](#agent-contracts-generate)
+  - [navigation-index](#agent-contracts-navigation-index)
 
 ---
 
@@ -225,7 +226,7 @@ agent-contracts render --quiet
 
 ```yaml
 x-agent: 
-  recommendedBeforeUse: 
+  recommended_before_use: 
     - Ensure agent-contracts.config.yaml exists with render targets.
     - Run validate first to confirm DSL is valid.
 ```
@@ -274,7 +275,7 @@ agent-contracts check --format json --quiet
 
 ```yaml
 x-agent: 
-  recommendedBeforeUse: 
+  recommended_before_use: 
     - Ensure agent-contracts.config.yaml exists.
 ```
 
@@ -391,7 +392,7 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
   | Property | Type | Required | Description |
   |---|---|---|---|
   | `summary` | `string` | Yes |  |
-  | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes |  |
+  | `risk_level` | `"low" \| "medium" \| "high" \| "critical"` | Yes |  |
   | `findings` | `object[]` | Yes |  |
   | `findings[].id` | `string` | No | Unique finding identifier. |
   | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes |  |
@@ -407,17 +408,17 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
   | `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 |  |
+  | `recommended_actions` | `object[]` | No |  |
+  | `recommended_actions[].kind` | `enum(6 values)` | Yes |  |
+  | `recommended_actions[].title` | `string` | Yes |  |
+  | `recommended_actions[].command` | `string` | No | CLI command to run (for run_command kind). |
+  | `recommended_actions[].target` | `string` | No | Target file or resource. |
+  | `recommended_actions[].rationale` | `string` | No |  |
   | `metadata` | `object` | No |  |
   | `metadata.tool` | `string` | No |  |
   | `metadata.command` | `string` | No |  |
   | `metadata.version` | `string` | No |  |
-  | `metadata.generatedAt` | `string` | No |  |
+  | `metadata.generated_at` | `string` | No |  |
   | `metadata.adapter` | `string` | No |  |
   | `metadata.model` | `string` | No |  |
 
@@ -430,14 +431,14 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
     "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
     "required": [
       "summary",
-      "riskLevel",
+      "risk_level",
       "findings"
     ],
     "properties": {
       "summary": {
         "type": "string"
       },
-      "riskLevel": {
+      "risk_level": {
         "type": "string",
         "enum": [
           "low",
@@ -537,7 +538,7 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
           }
         }
       },
-      "recommendedActions": {
+      "recommended_actions": {
         "type": "array",
         "items": {
           "type": "object",
@@ -587,7 +588,7 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
           "version": {
             "type": "string"
           },
-          "generatedAt": {
+          "generated_at": {
             "type": "string"
           },
           "adapter": {
@@ -615,7 +616,7 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
   | Property | Type | Required | Description |
   |---|---|---|---|
   | `summary` | `string` | Yes |  |
-  | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes |  |
+  | `risk_level` | `"low" \| "medium" \| "high" \| "critical"` | Yes |  |
   | `findings` | `object[]` | Yes |  |
   | `findings[].id` | `string` | No | Unique finding identifier. |
   | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes |  |
@@ -631,17 +632,17 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
   | `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 |  |
+  | `recommended_actions` | `object[]` | No |  |
+  | `recommended_actions[].kind` | `enum(6 values)` | Yes |  |
+  | `recommended_actions[].title` | `string` | Yes |  |
+  | `recommended_actions[].command` | `string` | No | CLI command to run (for run_command kind). |
+  | `recommended_actions[].target` | `string` | No | Target file or resource. |
+  | `recommended_actions[].rationale` | `string` | No |  |
   | `metadata` | `object` | No |  |
   | `metadata.tool` | `string` | No |  |
   | `metadata.command` | `string` | No |  |
   | `metadata.version` | `string` | No |  |
-  | `metadata.generatedAt` | `string` | No |  |
+  | `metadata.generated_at` | `string` | No |  |
   | `metadata.adapter` | `string` | No |  |
   | `metadata.model` | `string` | No |  |
 
@@ -654,14 +655,14 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
     "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
     "required": [
       "summary",
-      "riskLevel",
+      "risk_level",
       "findings"
     ],
     "properties": {
       "summary": {
         "type": "string"
       },
-      "riskLevel": {
+      "risk_level": {
         "type": "string",
         "enum": [
           "low",
@@ -761,7 +762,7 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
           }
         }
       },
-      "recommendedActions": {
+      "recommended_actions": {
         "type": "array",
         "items": {
           "type": "object",
@@ -811,7 +812,7 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
           "version": {
             "type": "string"
           },
-          "generatedAt": {
+          "generated_at": {
             "type": "string"
           },
           "adapter": {
@@ -842,9 +843,9 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
 
 ```yaml
 x-agent: 
-  retryableExitCodes: 
+  retryable_exit_codes: 
     - 12
-  recommendedBeforeUse: 
+  recommended_before_use: 
     - Ensure agent-contracts.config.yaml exists with render targets.
     - Run validate first to confirm DSL is valid.
     - Install agent-contracts-runtime if not using --dry-run.
@@ -924,9 +925,58 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 
 ```yaml
 x-agent: 
-  recommendedBeforeUse: 
+  recommended_before_use: 
     - Ensure agent-contracts.config.yaml exists with render targets and/or binding definitions.
     - Run validate first to confirm DSL is valid.
 ```
 
 ---
+
+### navigation-index
+
+Build artifact-centric navigation index from resolved DSL.
+
+Compiles a structured navigation index that maps each artifact to its operations (producer, validator, consumer tools), agent permissions (owner, editor, reader), inter-artifact relations, and recommended action routes. The index is a queryable model for runtime planners, guardrails, and governance tools.
+
+**Usage:**
+
+```
+agent-contracts navigation-index
+```
+```
+agent-contracts navigation-index --format json
+```
+```
+agent-contracts navigation-index --artifact api-contracts
+```
+```
+agent-contracts navigation-index -c agent-contracts.config.yaml
+```
+
+#### Arguments
+
+| Name | Required | Description |
+|---|---|---|
+| `dir` | No | Path to agent-contracts.yaml. |
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to agent-contracts.config.yaml. |
+| `--team` |  | No |  | Limit to one team (multi-team config only). |
+| `--format` |  | No | `"json"` | Output format. |
+| `--artifact` |  | No |  | Filter output to a single artifact by ID. |
+| `--quiet` |  | No | `false` | Suppress informational output. |
+
+#### Exit Codes
+
+**Exit 0:** Navigation index built successfully.
+
+- **stdout:** format=`{options.format}`
+
+**Exit 1:** Build failed — schema validation error, config error, or resolution failure.
+
+- **stderr:** format=`text`
+
+---

package/dsl_base/agents/dsl-auditor.yaml

@@ -4,13 +4,6 @@ dsl-auditor:
     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_execute_tools:
     - agent-contracts-cli
   can_perform_validations:
@@ -36,8 +29,9 @@ dsl-auditor:
   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,
+        Audit must cover all 19 dimensions: purpose, mode,
+        can_read_artifacts (deprecated), can_write_artifacts (deprecated),
+        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.
@@ -75,8 +69,8 @@ dsl-auditor:
         |---|-----------|------------|
         | 1 | purpose | high |
         | 2 | mode | high |
-        | 3 | can_read_artifacts | high |
-        | 4 | can_write_artifacts + required_validations | **critical** |
+        | 3 | can_read_artifacts (deprecated) | high |
+        | 4 | can_write_artifacts + required_validations (deprecated: can_write_artifacts) | **critical** |
         | 5 | can_invoke_agents | high |
         | 6 | tools (can_execute_tools → tools.yaml) | medium |
         | 7 | can_perform_validations | high |

package/dsl_base/agents/dsl-designer.yaml

@@ -6,15 +6,6 @@ dsl-designer:
     Holds specification knowledge of DSL structure, schemas, merge operators,
     and variable substitution.
   mode: read-write
-  can_read_artifacts:
-    - dsl-source
-    - dsl-generated-output
-    - dsl-score-report
-    - dsl-audit-report
-  can_write_artifacts:
-    - dsl-source
-    - dsl-generated-output
-    - dsl-score-report
   can_execute_tools:
     - agent-contracts-cli
   can_perform_validations:
@@ -47,8 +38,7 @@ dsl-designer:
     - id: R-DSL-002
       description: >-
         When adding a new agent, explicitly define all permission fields:
-        can_read_artifacts, can_write_artifacts, can_invoke_agents,
-        can_execute_tools, can_perform_validations.
+        can_invoke_agents, can_execute_tools, can_perform_validations.
       severity: mandatory
     - id: R-DSL-003
       description: >-
@@ -137,8 +127,8 @@ dsl-designer:
           purpose: string              # Agent purpose (required)
           mode: read-write | read-only # Operation mode (default: read-write)
           dispatch_only: boolean       # true = dispatch only, no implementation (default: false)
-          can_read_artifacts: []       # Readable artifact ID list
-          can_write_artifacts: []      # Writable artifact ID list
+          can_read_artifacts: []       # (deprecated) Readable artifact ID list
+          can_write_artifacts: []      # (deprecated) Writable artifact ID list
           can_execute_tools: []        # Executable tool ID list
           can_perform_validations: []  # Executable validation ID list
           can_invoke_agents: []        # Invocable agent ID list
@@ -190,10 +180,10 @@ dsl-designer:
         <artifact-id>:
           type: doc | schema | code | config | html
           description: string          # Description (required)
-          owner: string                # Owner agent ID (required)
-          producers: []                # Producer agent ID list
-          editors: []                  # Editor agent ID list
-          consumers: []                # Consumer agent ID list
+          owner: string                # (deprecated) Owner agent ID
+          producers: []                # (deprecated) Producer agent ID list
+          editors: []                  # (deprecated) Editor agent ID list
+          consumers: []                # (deprecated) Consumer agent ID list
           states: []                   # Lifecycle states
           required_validations: []     # Required validation ID list
           visibility: project | team | external

package/dsl_base/artifacts.yaml

@@ -4,13 +4,6 @@ dsl-source:
     agent-contracts DSL source files — YAML definitions for agents, tasks,
     artifacts, tools, validations, handoff_types, workflow, policies,
     guardrails, guardrail_policies, and bindings.
-  owner: dsl-designer
-  producers:
-    - dsl-designer
-  editors:
-    - dsl-designer
-  consumers:
-    - dsl-auditor
   states:
     - draft
     - validated
@@ -24,13 +17,6 @@ dsl-generated-output:
   description: >-
     Files generated from DSL via render — agent prompts, overview documents,
     workflow commands, guardrail configurations, etc.
-  owner: dsl-designer
-  producers:
-    - dsl-designer
-  editors:
-    - dsl-designer
-  consumers:
-    - dsl-auditor
   states:
     - generated
     - verified
@@ -42,13 +28,6 @@ dsl-score-report:
   description: >-
     Output of agent-contracts score command — completeness evaluation
     across 7 dimensions.
-  owner: dsl-designer
-  producers:
-    - dsl-designer
-  editors:
-    - dsl-designer
-  consumers:
-    - dsl-auditor
   states:
     - generated
   required_validations:
@@ -59,13 +38,6 @@ dsl-audit-report:
   description: >-
     DSL completeness audit report — PASS/MISS matrix across 19 dimensions,
     gap analysis, and improvement recommendations.
-  owner: dsl-auditor
-  producers:
-    - dsl-auditor
-  editors:
-    - dsl-auditor
-  consumers:
-    - dsl-designer
   states:
     - submitted
   required_validations:

package/dsl_base/components.yaml

@@ -78,18 +78,18 @@ schemas:
     description: >-
       Top-level result from an agent audit.
       Canonical schema for agent interoperability across toolchains.
-    required: [summary, riskLevel, findings]
+    required: [summary, risk_level, findings]
     properties:
       summary:
         type: string
-      riskLevel:
+      risk_level:
         type: string
         enum: [low, medium, high, critical]
       findings:
         type: array
         items:
           $ref: "#/schemas/agent-finding"
-      recommendedActions:
+      recommended_actions:
         type: array
         items:
           $ref: "#/schemas/agent-recommended-action"
@@ -102,7 +102,7 @@ schemas:
             type: string
           version:
             type: string
-          generatedAt:
+          generated_at:
             type: string
           adapter:
             type: string

package/dsl_base/tasks.yaml

@@ -48,6 +48,7 @@ update-dsl-binding:
   result_handoff: dsl-task-result
   validations:
     - dsl-schema-validation
+    - dsl-lint-validation
   responsibilities:
     - Add and update guardrail_impl check definitions
     - Configure outputs section templates and inline templates
@@ -82,6 +83,7 @@ render-dsl-outputs:
   result_handoff: dsl-task-result
   validations:
     - dsl-schema-validation
+    - dsl-completeness-audit
   responsibilities:
     - Generate prompts and documents via agent-contracts render
     - Detect and resolve drift using render --check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-contracts",
-  "version": "0.25.0",
+  "version": "0.30.0",
   "description": "Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -64,7 +64,7 @@
     "@stoplight/spectral-functions": "^1.9.0",
     "@stoplight/spectral-rulesets": "^1.22.1",
     "ajv": "^8.18.0",
-    "cli-contracts": "^0.7.2",
+    "cli-contracts": "^0.30.0",
     "commander": "^14.0.3",
     "handlebars": "^4.7.9",
     "yaml": "^2.8.3",