agent-contracts 0.22.3 → 0.22.4

package/dsl_base/agents/dsl-auditor.yaml

@@ -11,8 +11,6 @@ dsl-auditor:
     - dsl-score-report
   can_write_artifacts:
     - dsl-audit-report
-  can_invoke_agents:
-    - dsl-auditor
   can_execute_tools:
     - agent-contracts-cli
   can_perform_validations:
@@ -29,6 +27,7 @@ dsl-auditor:
     - 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)
+    - Audit x-* extension consumption across render templates and runtime codegen paths
   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
@@ -48,6 +47,15 @@ dsl-auditor:
         When a MISS is detected, classify the root cause as one of:
         template gap, data gap, or DSL gap.
       severity: mandatory
+  anti_patterns:
+    - >-
+      Directly editing DSL source files or generated outputs —
+      dsl-auditor is read-only; produce fix proposals in
+      dsl-audit-report instead and let dsl-designer apply them.
+    - >-
+      Running render or generate commands — these produce
+      side-effect file writes that belong to dsl-designer's scope;
+      use read-only commands (validate, lint, score, audit) only.
   escalation_criteria:
     - condition: 3 or more critical-level gaps detected
       action: stop_and_report
@@ -175,3 +183,24 @@ dsl-auditor:
         | 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 |
+
+    - title: "Extension Consumption Audit Dimensions"
+      content: |
+        When performing `audit extensions` (extension consumption audit), check:
+
+        | # | Dimension | Severity |
+        |---|-----------|----------|
+        | 1 | Declared extension never populated on any entity | warning |
+        | 2 | Populated x-* not declared in extensions (when declarations exist) | info |
+        | 3 | Populated x-* not referenced in any render template | warning |
+        | 4 | Declared scope vs actual usage node type mismatch | warning |
+        | 5 | x-* with required: true but no render template consumption path | critical |
+        | 6 | x-* replicates standard DSL feature (semantic overlap) | warning |
+        | 7 | x-* unreachable in runtime codegen (not in AgentContract/TaskContract/WorkflowContract fixed fields) | info |
+        | 8 | Template references x-* key that is never populated in DSL | warning |
+
+        For each finding, recommend one of:
+        - **Remove**: Extension is dead weight — remove from declarations and entities
+        - **Migrate**: Extension duplicates a standard DSL feature — migrate to the standard field
+        - **Add template**: Extension carries useful data — add template support to consume it
+        - **Document**: Extension is metadata-only (not intended for render/runtime) — add description clarifying intent

package/dsl_base/agents/dsl-designer.yaml

@@ -15,8 +15,6 @@ dsl-designer:
     - dsl-source
     - dsl-generated-output
     - dsl-score-report
-  can_invoke_agents:
-    - dsl-designer
   can_execute_tools:
     - agent-contracts-cli
   can_perform_validations:

package/dsl_base/artifacts.yaml

@@ -70,4 +70,4 @@ dsl-audit-report:
     - submitted
   required_validations:
     - dsl-audit-report-validation
-  x-artifact-class: evidence
+  classification: evidence

package/dsl_base/handoff-types.yaml

@@ -93,8 +93,8 @@ audit-result:
     $ref: "#/components/schemas/agent-audit-result"
 
 dsl-audit-result:
-  version: 3
-  description: Result of DSL audit (completeness, semantic design, or prompt fidelity)
+  version: 4
+  description: Result of DSL audit (completeness, semantic design, prompt fidelity, or extensions)
   schema:
     type: object
     properties:
@@ -104,6 +104,7 @@ dsl-audit-result:
           - completeness
           - semantic
           - prompt
+          - extensions
         description: Which audit task produced this result
       total_dimensions:
         type: integer
@@ -123,16 +124,36 @@ dsl-audit-result:
       prompts_reviewed:
         type: integer
         description: Number of generated prompts compared (prompt audit)
-      gate_analysis_complete:
-        type: boolean
-        description: >-
-          True when workflow gate placement analysis has been performed
-          (semantic audit completion criterion).
-      guardrail_enforcement_verified:
-        type: boolean
+      completion_criteria_coverage:
+        type: object
+        properties:
+          all_dimensions_inspected:
+            type: boolean
+            description: All required dimensions were inspected for all agents
+          gaps_classified:
+            type: boolean
+            description: Every detected gap has a root-cause classification
+          gate_analysis_complete:
+            type: boolean
+            description: Workflow gate placement analysis has been performed
+          guardrail_enforcement_verified:
+            type: boolean
+            description: All declared guardrails verified to exist in execution paths
+          scope_overlap_analyzed:
+            type: boolean
+            description: All agents reviewed for responsibility scope and role overlap
+          x_property_misuse_checked:
+            type: boolean
+            description: Custom x-* properties checked for standard DSL overlap
+          hallucinated_permissions_checked:
+            type: boolean
+            description: Generated prompts verified for permissions not declared in DSL
+          extension_consumption_checked:
+            type: boolean
+            description: All declared extensions checked for template/runtime consumption
         description: >-
-          True when all declared guardrails have been verified to exist
-          in execution paths (semantic audit completion criterion).
+          Per-criterion completion status. Each field maps to a
+          completion_criteria entry in the corresponding audit task.
       critical_gaps:
         type: array
         items:
@@ -180,3 +201,4 @@ dsl-audit-result:
       - total_dimensions
       - pass_count
       - miss_count
+      - completion_criteria_coverage

package/dsl_base/tasks.yaml

@@ -3,8 +3,6 @@
 update-dsl-definitions:
   description: Create new or update existing agent-contracts DSL definitions
   target_agent: dsl-designer
-  allowed_from_agents:
-    - dsl-designer
   workflow: dsl-update
   input_artifacts:
     - dsl-source
@@ -43,8 +41,6 @@ update-dsl-definitions:
 update-dsl-binding:
   description: Create new or update existing software bindings
   target_agent: dsl-designer
-  allowed_from_agents:
-    - dsl-designer
   workflow: dsl-update
   input_artifacts:
     - dsl-source
@@ -79,8 +75,6 @@ update-dsl-binding:
 render-dsl-outputs:
   description: Render prompts and documents from DSL and check for drift
   target_agent: dsl-designer
-  allowed_from_agents:
-    - dsl-designer
   workflow: dsl-update
   input_artifacts:
     - dsl-source
@@ -110,8 +104,6 @@ render-dsl-outputs:
 check-dsl-score:
   description: Check DSL completeness score and identify improvement areas
   target_agent: dsl-designer
-  allowed_from_agents:
-    - dsl-designer
   workflow: dsl-update
   input_artifacts:
     - dsl-source
@@ -143,8 +135,6 @@ check-dsl-score:
 audit-dsl-completeness:
   description: Audit completeness of DSL definitions against generated prompts
   target_agent: dsl-auditor
-  allowed_from_agents:
-    - dsl-auditor
   workflow: dsl-audit
   input_artifacts:
     - dsl-source
@@ -185,8 +175,6 @@ audit-dsl-completeness:
 audit-semantic-design:
   description: Audit DSL design for semantic coherence
   target_agent: dsl-auditor
-  allowed_from_agents:
-    - dsl-auditor
   workflow: dsl-audit
   input_artifacts:
     - dsl-source
@@ -231,8 +219,6 @@ audit-semantic-design:
 audit-generated-prompts:
   description: Audit generated prompts against DSL intent
   target_agent: dsl-auditor
-  allowed_from_agents:
-    - dsl-auditor
   workflow: dsl-audit
   input_artifacts:
     - dsl-source
@@ -269,3 +255,46 @@ audit-generated-prompts:
   escalation_criteria:
     - condition: Hallucinated permissions detected in generated prompts
       action: stop_and_report
+
+audit-extension-consumption:
+  description: Audit declared x-* extensions for consumption gaps across render and runtime paths
+  target_agent: dsl-auditor
+  workflow: dsl-audit
+  input_artifacts:
+    - dsl-source
+    - dsl-generated-output
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-audit-result
+  validations:
+    - dsl-completeness-audit
+    - dsl-audit-report-validation
+  responsibilities:
+    - Cross-check extensions declarations against entity x-* usage
+    - Identify x-* properties populated in DSL but not consumed by any render template
+    - Detect semantic overlap between x-* extensions and standard DSL features
+    - Report runtime codegen reachability for each extension
+    - Distinguish intentional metadata-only extensions from consumption gaps
+  completion_criteria:
+    - All declared extensions checked for template and runtime consumption
+    - Unused extensions flagged with suggested action (remove, migrate to standard, or add template support)
+    - Runtime-unreachable extensions documented with explanation
+    - Findings classified with severity and category
+  execution_steps:
+    - id: collect-declarations
+      action: Collect extensions declarations and x-* usage map
+      reads_artifact: dsl-source
+      required: true
+    - id: collect-templates
+      action: Collect render template x-* references
+      reads_artifact: dsl-generated-output
+      required: true
+    - id: analyze-consumption
+      action: Cross-check declarations vs usage vs template references vs runtime fields
+    - id: analyze-semantics
+      action: Detect semantic overlap with standard DSL features
+    - id: produce-report
+      action: Produce extension consumption audit report
+      produces_artifact: dsl-audit-report
+  escalation_criteria:
+    - condition: Required extension with no consumption path detected
+      action: stop_and_report

package/dsl_base/validations.yaml

@@ -4,7 +4,7 @@ dsl-schema-validation:
   executor_type: tool
   executor: agent-contracts-cli
   blocking: true
-  x-description: >-
+  description: >-
     DSL schema validation via agent-contracts validate command.
     Performs type checks on all entities, verifies required fields,
     and checks cross-reference integrity.
@@ -15,7 +15,7 @@ dsl-lint-validation:
   executor_type: tool
   executor: agent-contracts-cli
   blocking: false
-  x-description: >-
+  description: >-
     Semantic validation via agent-contracts lint command.
     Checks naming conventions, unused entities, circular references,
     and other design quality aspects.
@@ -26,7 +26,7 @@ dsl-score-validation:
   executor_type: tool
   executor: agent-contracts-cli
   blocking: false
-  x-description: >-
+  description: >-
     Completeness evaluation via agent-contracts score command.
     Scores across 7 dimensions: artifact validation coverage,
     task validation coverage, guardrail policy coverage,
@@ -40,7 +40,7 @@ dsl-completeness-audit:
   executor: dsl-auditor
   blocking: false
   produces_evidence: dsl-audit-report
-  x-description: >-
+  description: >-
     19-dimension cross-check audit of DSL definitions against generated
     prompts. Verifies that all items defined in the DSL are correctly
     reflected in generated output.
@@ -51,7 +51,7 @@ dsl-score-report-validation:
   executor_type: tool
   executor: agent-contracts-cli
   blocking: false
-  x-description: >-
+  description: >-
     Validates that dsl-score-report has been produced and contains
     a valid score across all 7 dimensions.
 
@@ -61,6 +61,6 @@ dsl-audit-report-validation:
   executor_type: agent
   executor: dsl-auditor
   blocking: false
-  x-description: >-
+  description: >-
     Validates that dsl-audit-report contains findings classified
     as PASS/MISS/PARTIAL for all inspected dimensions.

package/dsl_base/workflow.yaml

@@ -19,7 +19,8 @@ dsl-update:
       gate_kind: dsl-task-result
       description: >-
         Block if validation_result or lint_result did not pass in
-        update-dsl-definitions.
+        update-dsl-definitions.  Enforces dsl-validate-before-render
+        guardrail — prevents render from executing against invalid DSL.
     - type: delegate
       task: update-dsl-binding
       from_agent: dsl-designer
@@ -50,8 +51,9 @@ dsl-audit:
   description: >-
     DSL Audit — audit completeness of DSL definitions against generated
     prompts, detect gaps, and present improvement recommendations.
-    Executed by DSL Auditor. Supports three audit types: render (semantic
-    diff), dsl (design coherence), and prompt (prompt fidelity).
+    Executed by DSL Auditor. Supports four audit types: render (semantic
+    diff), dsl (design coherence), prompt (prompt fidelity), and
+    extensions (x-* consumption gap detection).
   entry_conditions:
     - DSL definition rendering is complete
   trigger: >-
@@ -77,6 +79,12 @@ dsl-audit:
         DSL Auditor reviews DSL design for semantic coherence —
         role overlap, scope breadth, gate placement, guardrail
         enforcement paths.
+    - type: gate
+      gate_kind: dsl-audit-result
+      depends_on: [audit-semantic-design]
+      description: >-
+        Semantic-design gate — block if critical design issues
+        detected (gate placement defects, handoff schema gaps).
     - type: delegate
       task: audit-generated-prompts
       from_agent: dsl-auditor
@@ -86,9 +94,23 @@ dsl-audit:
         detects missing requirements, hallucinated permissions,
         ambiguous instructions.
     - type: gate
-      gate_kind: dsl-audit-terminal
-      depends_on: [audit-semantic-design, audit-generated-prompts]
+      gate_kind: dsl-audit-result
+      depends_on: [audit-generated-prompts]
+      description: >-
+        Hallucinated-permissions gate — block immediately if
+        audit-generated-prompts detected permissions not declared
+        in DSL (enforces dsl-no-hallucinated-permissions guardrail).
+    - type: delegate
+      task: audit-extension-consumption
+      from_agent: dsl-auditor
+      depends_on: ["gate:dsl-audit-result"]
+      description: >-
+        DSL Auditor checks x-* extension properties for consumption
+        gaps — declared but unused, populated but not rendered,
+        semantic overlap with standard DSL features.
+    - type: gate
+      gate_kind: dsl-audit-result
+      depends_on: [audit-semantic-design, audit-generated-prompts, audit-extension-consumption]
       description: >-
-        Terminal gate — block if audit-generated-prompts detected
-        hallucinated permissions (enforces dsl-no-hallucinated-permissions
-        guardrail at workflow level via stop_and_report escalation).
+        Terminal gate — aggregates all audit results and blocks if
+        any critical-level findings remain unresolved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-contracts",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "description": "Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows",
   "type": "module",
   "main": "dist/index.js",