agent-contracts 0.19.4 → 0.20.0

package/dsl_base/handoff-types.yaml

@@ -0,0 +1,182 @@
+dsl-task-request:
+  version: 1
+  description: Request to execute a DSL management task
+  schema:
+    type: object
+    properties:
+      task_id:
+        type: string
+        description: Identifier of the task to execute
+      scope:
+        type: string
+        description: Scope of changes (agents, tasks, artifacts, workflow, bindings, etc.)
+      context:
+        type: string
+        description: Background and purpose of the change
+    required:
+      - task_id
+
+dsl-task-result:
+  version: 3
+  description: Result of a DSL management task execution
+  schema:
+    type: object
+    properties:
+      changed_files:
+        type: array
+        items:
+          type: string
+        description: List of changed file paths
+      validation_result:
+        type: string
+        enum:
+          - pass
+          - fail
+        description: Result of agent-contracts validate
+      lint_result:
+        type: string
+        enum:
+          - pass
+          - fail
+          - skipped
+        description: Result of agent-contracts lint (separate from validate)
+      generate_result:
+        type: string
+        enum:
+          - pass
+          - fail
+          - skipped
+        description: >-
+          Result of agent-contracts generate guardrails (binding task).
+          Used by post-binding gate to block render on failure.
+      render_result:
+        type: string
+        enum:
+          - pass
+          - fail
+          - skipped
+        description: >-
+          Result of agent-contracts render execution.
+          Distinct from drift_detected — captures whether render itself succeeded.
+      drift_detected:
+        type: boolean
+        description: >-
+          True if render --check detected drift between DSL source
+          and generated outputs
+      cross_reference_check:
+        type: string
+        enum:
+          - pass
+          - fail
+          - skipped
+        description: >-
+          Result of cross-reference integrity verification for newly
+          added entities (update-dsl-definitions completion criterion).
+      score:
+        type: number
+        description: Score command result (0-100)
+      score_dimensions:
+        type: object
+        description: Per-dimension score breakdown
+      notes:
+        type: string
+        description: Additional notes or improvement suggestions
+    required:
+      - validation_result
+
+audit-result:
+  version: 1
+  description: >-
+    Generic audit result for tool/agent execution.
+    Uses canonical agent-audit-result schema from components.schemas.
+  schema:
+    $ref: "#/components/schemas/agent-audit-result"
+
+dsl-audit-result:
+  version: 3
+  description: Result of DSL audit (completeness, semantic design, or prompt fidelity)
+  schema:
+    type: object
+    properties:
+      audit_type:
+        type: string
+        enum:
+          - completeness
+          - semantic
+          - prompt
+        description: Which audit task produced this result
+      total_dimensions:
+        type: integer
+        description: Number of dimensions inspected
+      pass_count:
+        type: integer
+        description: Number of PASS dimensions
+      miss_count:
+        type: integer
+        description: Number of MISS dimensions
+      partial_count:
+        type: integer
+        description: Number of PARTIAL dimensions
+      agents_reviewed:
+        type: integer
+        description: Number of agents reviewed (semantic and prompt audits)
+      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
+        description: >-
+          True when all declared guardrails have been verified to exist
+          in execution paths (semantic audit completion criterion).
+      critical_gaps:
+        type: array
+        items:
+          type: object
+          properties:
+            dimension:
+              type: string
+            agent:
+              type: string
+            gap_type:
+              type: string
+              enum:
+                - template_gap
+                - data_gap
+                - dsl_gap
+            severity:
+              type: string
+              enum:
+                - critical
+                - warning
+                - info
+        description: List of detected gaps
+      recommendations:
+        type: array
+        items:
+          type: object
+          properties:
+            priority:
+              type: string
+              enum:
+                - P0
+                - P1
+                - P2
+            description:
+              type: string
+            fix_type:
+              type: string
+              enum:
+                - template_fix
+                - dsl_fix
+                - regeneration
+        description: Prioritized improvement recommendation list
+    required:
+      - audit_type
+      - total_dimensions
+      - pass_count
+      - miss_count

package/dsl_base/tasks.yaml

@@ -0,0 +1,269 @@
+# === DSL Update Tasks ===
+
+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
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-task-result
+  validations:
+    - dsl-schema-validation
+    - dsl-lint-validation
+  responsibilities:
+    - Create and update DSL YAML files
+    - Define agents, tasks, artifacts, tools, validations, handoff_types, workflow, guardrails
+    - Configure system section
+  completion_criteria:
+    - agent-contracts validate succeeds
+    - agent-contracts lint reports no errors
+    - Cross-references for newly added entities are correct
+  execution_steps:
+    - id: read-current-dsl
+      action: Read current DSL definitions and understand the structure
+      reads_artifact: dsl-source
+      required: true
+    - id: update-dsl
+      action: Create or update DSL definitions
+      produces_artifact: dsl-source
+    - id: validate
+      action: Run agent-contracts validate
+      uses_tool: agent-contracts-cli
+      required: true
+    - id: lint
+      action: Run agent-contracts lint
+      uses_tool: agent-contracts-cli
+  escalation_criteria:
+    - condition: Schema errors from validate cannot be resolved
+      action: stop_and_report
+
+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
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-task-result
+  validations:
+    - dsl-schema-validation
+  responsibilities:
+    - Add and update guardrail_impl check definitions
+    - Configure outputs section templates and inline templates
+    - Set up binding extends inheritance
+  completion_criteria:
+    - Binding YAML conforms to the correct schema
+    - guardrail_impl hook_event / matcher values are valid
+    - agent-contracts generate guardrails succeeds
+  execution_steps:
+    - id: read-guardrails
+      action: Review target guardrail definitions and policies
+      reads_artifact: dsl-source
+      required: true
+    - id: update-binding
+      action: Create or update binding YAML
+      produces_artifact: dsl-source
+    - id: generate
+      action: Run agent-contracts generate guardrails to verify
+      uses_tool: agent-contracts-cli
+      required: true
+  escalation_criteria:
+    - condition: Binding guardrail_impl is inconsistent with DSL guardrails
+      action: stop_and_report
+
+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
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-task-result
+  validations:
+    - dsl-schema-validation
+  responsibilities:
+    - Generate prompts and documents via agent-contracts render
+    - Detect and resolve drift using render --check
+  completion_criteria:
+    - render succeeds
+    - render --check reports no drift
+  execution_steps:
+    - id: render
+      action: Run agent-contracts render
+      uses_tool: agent-contracts-cli
+      produces_artifact: dsl-generated-output
+      required: true
+    - id: check-drift
+      action: Run agent-contracts render --check to verify no drift
+      uses_tool: agent-contracts-cli
+  escalation_criteria:
+    - condition: Unresolved template errors during render
+      action: stop_and_report
+
+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
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-task-result
+  validations:
+    - dsl-score-validation
+    - dsl-score-report-validation
+  responsibilities:
+    - Review score across 7 dimensions and identify weaknesses
+    - List entities that need improvement
+  completion_criteria:
+    - Score results have been reviewed
+    - Improvement areas have been identified
+  execution_steps:
+    - id: run-score
+      action: Run agent-contracts score
+      uses_tool: agent-contracts-cli
+      required: true
+    - id: analyze
+      action: Analyze score weaknesses and formulate improvement plan
+      produces_artifact: dsl-score-report
+  escalation_criteria:
+    - condition: Score is significantly below threshold with no clear improvement path
+      action: stop_and_report
+
+# === DSL Audit Tasks ===
+
+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
+    - dsl-generated-output
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-audit-result
+  validations:
+    - dsl-completeness-audit
+    - dsl-audit-report-validation
+  responsibilities:
+    - Cross-check across 19 dimensions per audit procedure
+    - Classify gaps as template gap, data gap, or DSL gap
+    - Present improvement recommendations
+  completion_criteria:
+    - All dimensions inspected for all agents
+    - Detected gaps are classified
+    - Improvement recommendations are presented with priority
+  execution_steps:
+    - id: collect-sources
+      action: Collect DSL definitions, generated prompts, and templates
+      reads_artifact: dsl-source
+      required: true
+    - id: collect-outputs
+      action: Collect generated prompts
+      reads_artifact: dsl-generated-output
+      required: true
+    - id: run-audit
+      action: Execute 19-dimension cross-check
+    - id: analyze-gaps
+      action: Analyze root causes of detected gaps
+    - id: produce-report
+      action: Produce audit report and improvement recommendations
+      produces_artifact: dsl-audit-report
+  escalation_criteria:
+    - condition: 3 or more critical-level gaps detected
+      action: stop_and_report
+
+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
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-audit-result
+  validations:
+    - dsl-completeness-audit
+    - dsl-audit-report-validation
+  responsibilities:
+    - Check dispatch_only agents for implementation responsibilities
+    - Detect agents with overly broad scope
+    - Identify role overlap between agents
+    - Verify handoff schemas carry sufficient fields for task completion_criteria
+    - Check workflow gates are placed effectively
+    - Detect guardrails declared but absent from execution path
+    - Check semantic validations are distributed across phases
+  completion_criteria:
+    - All agents reviewed for scope and overlap
+    - Workflow gate placement analyzed
+    - Guardrail enforcement path verified
+    - Findings classified with severity and category
+  execution_steps:
+    - id: load-dsl
+      action: Load resolved DSL definitions
+      reads_artifact: dsl-source
+      required: true
+    - id: analyze-agents
+      action: Review agent responsibilities, permissions, and role boundaries
+    - id: analyze-workflows
+      action: Analyze workflow structure, gate placement, and validation coverage
+    - id: analyze-guardrails
+      action: Verify guardrail enforcement paths
+    - id: produce-report
+      action: Produce semantic design audit report
+      produces_artifact: dsl-audit-report
+  escalation_criteria:
+    - condition: 3 or more critical-level design issues detected
+      action: stop_and_report
+
+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
+    - dsl-generated-output
+  invocation_handoff: dsl-task-request
+  result_handoff: dsl-audit-result
+  validations:
+    - dsl-completeness-audit
+    - dsl-audit-report-validation
+  responsibilities:
+    - Compare generated prompt content against DSL agent definitions
+    - Detect missing requirements from DSL
+    - Detect hallucinated permissions not in DSL
+    - Identify ambiguous or unsafe instructions
+    - Verify consistency between prompt and handoff schema expectations
+  completion_criteria:
+    - All generated prompts compared against DSL definitions
+    - Missing, hallucinated, and ambiguous instructions identified
+    - Findings classified with severity and category
+  execution_steps:
+    - id: collect-sources
+      action: Collect DSL agent definitions and related entities
+      reads_artifact: dsl-source
+      required: true
+    - id: collect-prompts
+      action: Collect generated prompt files
+      reads_artifact: dsl-generated-output
+      required: true
+    - id: compare
+      action: Compare each prompt against its DSL definition
+    - id: produce-report
+      action: Produce prompt audit report
+      produces_artifact: dsl-audit-report
+  escalation_criteria:
+    - condition: Hallucinated permissions detected in generated prompts
+      action: stop_and_report

package/dsl_base/tools.yaml

@@ -0,0 +1,50 @@
+agent-contracts-cli:
+  kind: cli
+  description: >-
+    agent-contracts CLI — execute resolve, validate, lint, render, score,
+    check, and generate commands for the DSL.
+  input_artifacts:
+    - dsl-source
+  output_artifacts:
+    - dsl-generated-output
+    - dsl-score-report
+  invokable_by:
+    - dsl-designer
+    - dsl-auditor
+  side_effects: []
+  commands:
+    - command: "npx agent-contracts validate"
+      category: verification
+      reads: [dsl-source]
+      writes: []
+      purpose: DSL schema validation and reference checks
+    - command: "npx agent-contracts lint"
+      category: verification
+      reads: [dsl-source]
+      writes: []
+      purpose: Semantic lint
+    - command: "npx agent-contracts render -c agent-contracts.config.yaml"
+      category: generation
+      reads: [dsl-source]
+      writes: [dsl-generated-output]
+      purpose: Template rendering (prompt and document generation)
+    - command: "npx agent-contracts render -c agent-contracts.config.yaml --check"
+      category: verification
+      reads: [dsl-source, dsl-generated-output]
+      writes: []
+      purpose: Drift detection (source vs generated output)
+    - command: "npx agent-contracts score"
+      category: verification
+      reads: [dsl-source]
+      writes: [dsl-score-report]
+      purpose: DSL completeness score calculation (7 dimensions)
+    - command: "npx agent-contracts check -c agent-contracts.config.yaml"
+      category: verification
+      reads: [dsl-source]
+      writes: []
+      purpose: Pipeline — resolve → validate → lint → render --check
+    - command: "npx agent-contracts generate guardrails"
+      category: generation
+      reads: [dsl-source]
+      writes: [dsl-generated-output]
+      purpose: Generate guardrail runtime artifacts

package/dsl_base/validations.yaml

@@ -0,0 +1,66 @@
+dsl-schema-validation:
+  target_artifact: dsl-source
+  kind: schema
+  executor_type: tool
+  executor: agent-contracts-cli
+  blocking: true
+  x-description: >-
+    DSL schema validation via agent-contracts validate command.
+    Performs type checks on all entities, verifies required fields,
+    and checks cross-reference integrity.
+
+dsl-lint-validation:
+  target_artifact: dsl-source
+  kind: semantic
+  executor_type: tool
+  executor: agent-contracts-cli
+  blocking: false
+  x-description: >-
+    Semantic validation via agent-contracts lint command.
+    Checks naming conventions, unused entities, circular references,
+    and other design quality aspects.
+
+dsl-score-validation:
+  target_artifact: dsl-source
+  kind: semantic
+  executor_type: tool
+  executor: agent-contracts-cli
+  blocking: false
+  x-description: >-
+    Completeness evaluation via agent-contracts score command.
+    Scores across 7 dimensions: artifact validation coverage,
+    task validation coverage, guardrail policy coverage,
+    workflow validation integration, schema completeness,
+    cross-reference bidirectionality, guardrail scope resolution.
+
+dsl-completeness-audit:
+  target_artifact: dsl-generated-output
+  kind: semantic
+  executor_type: agent
+  executor: dsl-auditor
+  blocking: false
+  produces_evidence: dsl-audit-report
+  x-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.
+
+dsl-score-report-validation:
+  target_artifact: dsl-score-report
+  kind: semantic
+  executor_type: tool
+  executor: agent-contracts-cli
+  blocking: false
+  x-description: >-
+    Validates that dsl-score-report has been produced and contains
+    a valid score across all 7 dimensions.
+
+dsl-audit-report-validation:
+  target_artifact: dsl-audit-report
+  kind: semantic
+  executor_type: agent
+  executor: dsl-auditor
+  blocking: false
+  x-description: >-
+    Validates that dsl-audit-report contains findings classified
+    as PASS/MISS/PARTIAL for all inspected dimensions.

package/dsl_base/workflow.yaml

@@ -0,0 +1,91 @@
+dsl-update:
+  description: >-
+    DSL Update — create and update agent-contracts DSL definitions and
+    bindings, verify quality via validate / lint / render / score.
+    Executed by DSL Designer.
+  entry_conditions:
+    - A DSL definition change request exists
+  trigger: >-
+    Execute when new DSL definitions need to be created, existing definitions
+    need updating, or bindings need to be added or modified.
+  steps:
+    - type: delegate
+      task: update-dsl-definitions
+      from_agent: dsl-designer
+      description: >-
+        DSL Designer creates or updates DSL definitions and verifies
+        via validate / lint.
+    - type: gate
+      gate_kind: dsl-task-result
+      description: >-
+        Block if validation_result or lint_result did not pass in
+        update-dsl-definitions.
+    - type: delegate
+      task: update-dsl-binding
+      from_agent: dsl-designer
+      description: >-
+        DSL Designer adds or updates bindings and verifies via generate.
+    - type: gate
+      gate_kind: dsl-task-result
+      description: >-
+        Block if generate_result is not 'pass' in update-dsl-binding.
+        Prevents render-dsl-outputs from executing against invalid bindings.
+    - type: delegate
+      task: render-dsl-outputs
+      from_agent: dsl-designer
+      description: >-
+        DSL Designer renders prompts and documents and checks for drift.
+    - type: gate
+      gate_kind: dsl-task-result
+      description: >-
+        Block if render_result is not 'pass' or drift_detected is true
+        in render-dsl-outputs result.
+    - type: delegate
+      task: check-dsl-score
+      from_agent: dsl-designer
+      description: >-
+        DSL Designer checks completeness score and identifies improvement areas.
+
+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).
+  entry_conditions:
+    - DSL definition rendering is complete
+  trigger: >-
+    Execute when DSL completeness audit is needed. Typically run as a
+    quality check after DSL updates.
+  steps:
+    - type: delegate
+      task: audit-dsl-completeness
+      from_agent: dsl-auditor
+      description: >-
+        DSL Auditor executes 19-dimension cross-check and produces
+        audit report with improvement recommendations.
+    - type: gate
+      gate_kind: dsl-audit-result
+      description: >-
+        Block if audit-dsl-completeness detected 3 or more
+        critical-level gaps (triggers stop_and_report escalation).
+    - type: delegate
+      task: audit-semantic-design
+      from_agent: dsl-auditor
+      description: >-
+        DSL Auditor reviews DSL design for semantic coherence —
+        role overlap, scope breadth, gate placement, guardrail
+        enforcement paths.
+    - type: delegate
+      task: audit-generated-prompts
+      from_agent: dsl-auditor
+      description: >-
+        DSL Auditor compares generated prompts against DSL intent —
+        detects missing requirements, hallucinated permissions,
+        ambiguous instructions.
+    - type: gate
+      gate_kind: dsl-audit-result
+      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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-contracts",
-  "version": "0.19.4",
+  "version": "0.20.0",
   "description": "Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "dsl_base",
     "cli-contract.yaml",
     "docs/cli-reference.md",
     "README.md",
@@ -76,7 +77,7 @@
     "@openai/agents": "^0.11.1",
     "@types/node": "^25.6.0",
     "agent-contracts-runtime": "^0.12.0",
-    "cli-contracts": "^0.5.1",
+    "cli-contracts": "^0.5.2",
     "eslint": "^10.2.0",
     "globals": "^17.5.0",
     "prettier": "^3.8.2",