agent-contracts 0.19.4 → 0.19.5

package/dsl_base/artifacts.yaml

@@ -0,0 +1,73 @@
+dsl-source:
+  type: config
+  description: >-
+    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
+    - rendered
+  required_validations:
+    - dsl-schema-validation
+    - dsl-lint-validation
+
+dsl-generated-output:
+  type: doc
+  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
+  required_validations:
+    - dsl-completeness-audit
+
+dsl-score-report:
+  type: doc
+  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:
+    - dsl-score-report-validation
+
+dsl-audit-report:
+  type: doc
+  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:
+    - dsl-audit-report-validation
+  x-artifact-class: evidence

package/dsl_base/audit-test.config.yaml

@@ -0,0 +1,2 @@
+dsl: ./agent-contracts.yaml
+renders: []

package/dsl_base/components.yaml

@@ -0,0 +1,110 @@
+schemas:
+  agent-evidence:
+    type: object
+    description: Evidence supporting an agent finding.
+    required: [kind]
+    properties:
+      kind:
+        type: string
+        enum: [file, command, schema, diff, stdout, stderr, text]
+      target:
+        type: string
+        description: Target identifier (file path, command ID, schema name).
+      location:
+        type: string
+        description: Location within the target (line number, JSON pointer).
+      excerpt:
+        type: string
+        description: Relevant excerpt from the target.
+
+  agent-finding:
+    type: object
+    description: A single finding from an agent audit or analysis.
+    required: [severity, category, message]
+    properties:
+      id:
+        type: string
+        description: Unique finding identifier.
+      severity:
+        type: string
+        enum: [info, warning, error, critical]
+      category:
+        type: string
+        description: Finding category (e.g. missing-policy, inconsistent-risk).
+      target:
+        type: string
+        description: Target of the finding (command ID, schema path).
+      location:
+        type: string
+        description: Location within the target.
+      message:
+        type: string
+      recommendation:
+        type: string
+      confidence:
+        type: number
+        minimum: 0
+        maximum: 1
+        description: Confidence score (0-1) for LLM-generated findings.
+      evidence:
+        type: array
+        items:
+          $ref: "#/schemas/agent-evidence"
+      details:
+        type: object
+        additionalProperties: true
+
+  agent-recommended-action:
+    type: object
+    description: A recommended action from an agent audit.
+    required: [kind, title]
+    properties:
+      kind:
+        type: string
+        enum: [run_command, edit_file, review, confirm, block, ignore]
+      title:
+        type: string
+      command:
+        type: string
+        description: CLI command to run (for run_command kind).
+      target:
+        type: string
+        description: Target file or resource.
+      rationale:
+        type: string
+
+  agent-audit-result:
+    type: object
+    description: >-
+      Top-level result from an agent audit.
+      Canonical schema for agent interoperability across toolchains.
+    required: [summary, riskLevel, findings]
+    properties:
+      summary:
+        type: string
+      riskLevel:
+        type: string
+        enum: [low, medium, high, critical]
+      findings:
+        type: array
+        items:
+          $ref: "#/schemas/agent-finding"
+      recommendedActions:
+        type: array
+        items:
+          $ref: "#/schemas/agent-recommended-action"
+      metadata:
+        type: object
+        properties:
+          tool:
+            type: string
+          command:
+            type: string
+          version:
+            type: string
+          generatedAt:
+            type: string
+          adapter:
+            type: string
+          model:
+            type: string

package/dsl_base/guardrail-policies.yaml

@@ -0,0 +1,18 @@
+dsl-management-policy:
+  description: >-
+    Guardrail policy governing DSL management operations.
+    Groups all DSL-related guardrails and specifies resolution
+    behavior.
+  rules:
+    - guardrail: dsl-readonly-enforcement
+      severity: critical
+      action: block
+    - guardrail: dsl-validate-before-render
+      severity: mandatory
+      action: block
+    - guardrail: dsl-no-hallucinated-permissions
+      severity: critical
+      action: block
+      escalation:
+        target: dsl-designer
+        condition: Hallucinated permissions detected in generated prompts

package/dsl_base/guardrails.yaml

@@ -0,0 +1,46 @@
+dsl-readonly-enforcement:
+  description: >-
+    Prevent audit-purpose agents from modifying DSL source files.
+    dsl-auditor is mode=read-write (to produce dsl-audit-report) but
+    must not write to dsl-source. This guardrail enforces that boundary.
+  scope:
+    agents:
+      - dsl-auditor
+    artifacts:
+      - dsl-source
+  rationale: >-
+    dsl-auditor uses mode=read-write because it produces dsl-audit-report,
+    but its constraints prohibit modifying DSL definitions. This guardrail
+    blocks writes to dsl-source from audit-purpose agents.
+
+dsl-validate-before-render:
+  description: >-
+    Ensure DSL validation passes before rendering is attempted.
+    Prevents generation of prompts from invalid DSL definitions.
+  scope:
+    workflows:
+      - dsl-update
+    tasks:
+      - render-dsl-outputs
+    artifacts:
+      - dsl-generated-output
+  rationale: >-
+    render-dsl-outputs must not be invoked while validation_result
+    of update-dsl-definitions is not 'pass'.
+
+dsl-no-hallucinated-permissions:
+  description: >-
+    Rendered prompts must not grant permissions not declared in DSL.
+    Detected via audit-generated-prompts; any hallucinated-permission
+    finding of severity critical must be escalated.
+  scope:
+    artifacts:
+      - dsl-generated-output
+    tasks:
+      - audit-generated-prompts
+    tools:
+      - agent-contracts-cli
+  rationale: >-
+    audit-generated-prompts detects permissions or tool references
+    in generated prompts that have no corresponding declaration
+    in the agent's DSL definition.

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