agent-contracts 0.12.2 → 0.12.4

package/README.md

@@ -999,10 +999,10 @@ Each `context` type provides a different rendering scope:
 | Context | Scope | Output | Key variables |
 |---------|-------|--------|---------------|
 | `system` | Single file | `output` as-is | `system`, `dsl`, `guardrailEnforcement`\*, `bindings`\* |
-| `agent` | Per agent | `{agent.id}` in output path | `agent`, `receivableTasks`, `delegatableTasks`, `relatedArtifacts`, `relatedTools`, `relatedHandoffTypes`, `mergedBehavior`, `dsl` |
-| `task` | Per task | `{task.id}` in output path | `task`, `targetAgent`, `dsl` |
-| `artifact` | Per artifact | `{artifact.id}` in output path | `artifact`, `relatedTools`, `relatedValidations`, `producerAgents`, `consumerAgents`, `editorAgents`, `createdInWorkflows`, `dsl` |
-| `tool` | Per tool | `{tool.id}` in output path | `tool`, `invokableAgents`, `inputArtifactDetails`, `outputArtifactDetails`, `dsl` |
+| `agent` | Per agent | `{agent.id}` in output path | `agent`, `receivableTasks`, `delegatableTasks`, `relatedArtifacts`, `relatedTools`, `relatedHandoffTypes`, `mergedBehavior`, `relatedGuardrails`, `relatedValidations`, `dsl` |
+| `task` | Per task | `{task.id}` in output path | `task`, `targetAgent`, `relatedGuardrails`, `relatedValidations`, `dsl` |
+| `artifact` | Per artifact | `{artifact.id}` in output path | `artifact`, `relatedTools`, `relatedValidations`, `relatedGuardrails`, `producerAgents`, `consumerAgents`, `editorAgents`, `createdInWorkflows`, `dsl` |
+| `tool` | Per tool | `{tool.id}` in output path | `tool`, `invokableAgents`, `inputArtifactDetails`, `outputArtifactDetails`, `relatedGuardrails`, `relatedValidations`, `dsl` |
 | `validation` | Per validation | `{validation.id}` in output path | `validation`, `dsl` |
 | `handoff_type` | Per handoff type | `{handoff_type.id}` in output path | `handoff_type`, `relatedTasks`, `dsl` |
 | `workflow` | Per workflow phase | `{workflow.id}` in output path | `workflow`, `relatedAgents`, `relatedTasks`, `relatedTools`, `relatedArtifacts`, `relatedValidations`, `dsl` |
@@ -1027,6 +1027,23 @@ Each `context` type provides a different rendering scope:
 * `producerAgents` / `consumerAgents` / `editorAgents` — resolved agent records
 * `createdInWorkflows` — workflow phases where this artifact is written
 
+**`agent` context** provides merged behavioral specs and cross-references:
+
+* `relatedGuardrails` — guardrails bound via `agent.guardrails[]` or guardrail `scope.agents[]`, merged and deduplicated
+* `relatedValidations` — validations from `agent.can_perform_validations`, resolved into full entries (kind, target_artifact, executor_type, blocking)
+
+**`task` context** provides execution details:
+
+* `relatedGuardrails` — guardrails bound via `task.guardrails[]` or guardrail `scope.tasks[]`
+* `relatedValidations` — validations from `task.validations[]`, resolved into full entries
+
+**`tool` context** provides invocation and artifact details:
+
+* `relatedGuardrails` — guardrails bound via `tool.guardrails[]` or guardrail `scope.tools[]`
+* `relatedValidations` — validations where `executor_type` is `"tool"` and `executor` matches this tool ID
+* `invokableAgents` — agents listed in `invokable_by`
+* `inputArtifactDetails` / `outputArtifactDetails` — resolved artifact records
+
 **`system` context** includes binding-aware guardrail enforcement data when `bindings` and `active_guardrail_policy` are configured:
 
 * `guardrailEnforcement` — array of enforcement entries, each with `guardrail_id`, `description`, `severity`, `action`, scoped entities (`scoped_agents`, `scoped_tasks`, `scoped_workflows`, `scoped_tools`, `scoped_artifacts`), `allow_override`, `override_requires`, `trigger` (from binding matcher type), and `escalation`
@@ -1039,11 +1056,6 @@ These fields are only populated when the config specifies `bindings` and `active
 * `guardrailCoverageMatrix` — generates a Guardrail Coverage Matrix table (guardrail × severity × action × scoped entities × trigger × override × escalation)
 * `taskGuardrailMatrix` — generates a Task × Guardrail cross-reference table showing which action applies to each task
 
-**`tool` context** resolves agent and artifact references:
-
-* `invokableAgents` — agents listed in `invokable_by`
-* `inputArtifactDetails` / `outputArtifactDetails` — resolved artifact records
-
 ### Handlebars helpers
 
 Templates can use these built-in helpers:
@@ -1306,6 +1318,7 @@ Checks:
 * artifact ownership — `produces_artifact`/`reads_artifact` in execution steps vs. artifact producers/editors/consumers
 * tool commands — `commands[].reads`/`commands[].writes` reference valid artifacts and align with `output_artifacts`
 * semantic validation phase coverage — warns when `semantic` or `fidelity` validations only appear in late workflow phases (e.g., audit) but not earlier phases (e.g., specify, plan)
+* validation executor context wiring — warns when a validation's executor (agent or tool) exists in the DSL but the validation is not surfaced in the executor's prompt context
 * YAML safety — warns when YAML 1.1 reserved words (`on`, `yes`, `no`, `true`, `false`, etc.) are used in positions where they may be misinterpreted by non-1.2 parsers
 * naming/style issues through Spectral rules
 

package/dist/cli.js

@@ -50479,7 +50479,8 @@ var AgentSchema = z.object({
   rules: z.array(RuleSchema).optional(),
   anti_patterns: z.array(z.string()).optional(),
   escalation_criteria: z.array(EscalationCriterionSchema).optional(),
-  prerequisites: z.array(PrerequisiteSchema).optional()
+  prerequisites: z.array(PrerequisiteSchema).optional(),
+  guardrails: z.array(z.string()).optional()
 }).passthrough();
 
 // src/schema/artifact.ts
@@ -50493,7 +50494,8 @@ var ArtifactSchema = z2.object({
   consumers: z2.array(z2.string()),
   states: z2.array(z2.string()),
   required_validations: z2.array(z2.string()).default([]),
-  visibility: z2.string().optional()
+  visibility: z2.string().optional(),
+  guardrails: z2.array(z2.string()).optional()
 }).passthrough();
 
 // src/schema/binding.ts
@@ -50657,7 +50659,8 @@ var TaskSchema = z8.object({
   rules: z8.array(RuleSchema).optional(),
   anti_patterns: z8.array(z8.string()).optional(),
   escalation_criteria: z8.array(EscalationCriterionSchema).optional(),
-  validations: z8.array(z8.string()).default([])
+  validations: z8.array(z8.string()).default([]),
+  guardrails: z8.array(z8.string()).optional()
 }).passthrough();
 
 // src/schema/tool.ts
@@ -50676,7 +50679,8 @@ var ToolSchema = z9.object({
   output_artifacts: z9.array(z9.string()).default([]),
   invokable_by: z9.array(z9.string()),
   side_effects: z9.array(z9.string()).default([]),
-  commands: z9.array(CommandSchema).default([])
+  commands: z9.array(CommandSchema).default([]),
+  guardrails: z9.array(z9.string()).optional()
 }).passthrough();
 
 // src/schema/validation.ts
@@ -52139,6 +52143,34 @@ function checkReferences(dsl) {
       }
     }
   }
+  for (const [id, agent] of Object.entries(dsl.agents)) {
+    if (agent.guardrails) {
+      for (const ref of agent.guardrails) {
+        checkExists(ref, guardrailIds, "guardrails", `agents.${id}.guardrails`, "entity-guardrail-ref-not-found");
+      }
+    }
+  }
+  for (const [id, task] of Object.entries(dsl.tasks)) {
+    if (task.guardrails) {
+      for (const ref of task.guardrails) {
+        checkExists(ref, guardrailIds, "guardrails", `tasks.${id}.guardrails`, "entity-guardrail-ref-not-found");
+      }
+    }
+  }
+  for (const [id, tool] of Object.entries(dsl.tools)) {
+    if (tool.guardrails) {
+      for (const ref of tool.guardrails) {
+        checkExists(ref, guardrailIds, "guardrails", `tools.${id}.guardrails`, "entity-guardrail-ref-not-found");
+      }
+    }
+  }
+  for (const [id, art] of Object.entries(dsl.artifacts)) {
+    if (art.guardrails) {
+      for (const ref of art.guardrails) {
+        checkExists(ref, guardrailIds, "guardrails", `artifacts.${id}.guardrails`, "entity-guardrail-ref-not-found");
+      }
+    }
+  }
   for (const [id, guardrail] of Object.entries(dsl.guardrails)) {
     if (guardrail.scope.agents) {
       for (const ref of guardrail.scope.agents) {
@@ -52869,6 +52901,148 @@ var semanticValidationPhaseCoverageRule = {
   }
 };
 
+// src/linter/rules/entity-guardrail-binding.ts
+var entityGuardrailUndefinedRule = {
+  id: "entity-guardrail-undefined",
+  description: "Entity references a guardrail ID not defined in guardrails",
+  run(dsl) {
+    const diagnostics = [];
+    const guardrailIds = new Set(Object.keys(dsl.guardrails));
+    const sections = [
+      { name: "agents", entities: dsl.agents },
+      { name: "tasks", entities: dsl.tasks },
+      { name: "tools", entities: dsl.tools },
+      { name: "artifacts", entities: dsl.artifacts }
+    ];
+    for (const { name, entities } of sections) {
+      for (const [entityId, entity] of Object.entries(entities)) {
+        for (const ref of entity.guardrails ?? []) {
+          if (!guardrailIds.has(ref)) {
+            diagnostics.push({
+              ruleId: "entity-guardrail-undefined",
+              severity: "error",
+              path: `${name}.${entityId}.guardrails`,
+              message: `${name.slice(0, -1)} "${entityId}" references guardrail "${ref}" which is not defined in guardrails`
+            });
+          }
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+var entityNoGuardrailsRule = {
+  id: "entity-no-guardrails",
+  description: "Entity has no effective guardrails (neither entity-side nor scope-side)",
+  run(dsl) {
+    const diagnostics = [];
+    const scopeBindings = {
+      agents: /* @__PURE__ */ new Set(),
+      tasks: /* @__PURE__ */ new Set(),
+      tools: /* @__PURE__ */ new Set(),
+      artifacts: /* @__PURE__ */ new Set()
+    };
+    for (const guardrail of Object.values(dsl.guardrails)) {
+      for (const key of Object.keys(scopeBindings)) {
+        const ids = guardrail.scope[key];
+        if (ids) {
+          for (const id of ids) scopeBindings[key].add(id);
+        }
+      }
+    }
+    const sections = [
+      { name: "agents", entities: dsl.agents },
+      { name: "tasks", entities: dsl.tasks },
+      { name: "tools", entities: dsl.tools },
+      { name: "artifacts", entities: dsl.artifacts }
+    ];
+    for (const { name, entities } of sections) {
+      for (const [entityId, entity] of Object.entries(entities)) {
+        const hasEntitySide = (entity.guardrails ?? []).length > 0;
+        const hasScopeSide = scopeBindings[name].has(entityId);
+        if (!hasEntitySide && !hasScopeSide) {
+          diagnostics.push({
+            ruleId: "entity-no-guardrails",
+            severity: "info",
+            path: `${name}.${entityId}`,
+            message: `${name.slice(0, -1)} "${entityId}" has no effective guardrails`
+          });
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+var guardrailOrphanedRule = {
+  id: "guardrail-orphaned",
+  description: "Guardrail is not referenced by any entity and not bound to any entity via scope",
+  run(dsl) {
+    const diagnostics = [];
+    const referencedByEntities = /* @__PURE__ */ new Set();
+    const sections = [
+      dsl.agents,
+      dsl.tasks,
+      dsl.tools,
+      dsl.artifacts
+    ];
+    for (const entities of sections) {
+      for (const entity of Object.values(entities)) {
+        for (const ref of entity.guardrails ?? []) {
+          referencedByEntities.add(ref);
+        }
+      }
+    }
+    for (const [guardrailId, guardrail] of Object.entries(dsl.guardrails)) {
+      const hasEntityRef = referencedByEntities.has(guardrailId);
+      const scope = guardrail.scope;
+      const hasScopeBinding = (scope.agents?.length ?? 0) > 0 || (scope.tasks?.length ?? 0) > 0 || (scope.tools?.length ?? 0) > 0 || (scope.artifacts?.length ?? 0) > 0 || (scope.workflows?.length ?? 0) > 0;
+      if (!hasEntityRef && !hasScopeBinding) {
+        diagnostics.push({
+          ruleId: "guardrail-orphaned",
+          severity: "warning",
+          path: `guardrails.${guardrailId}`,
+          message: `Guardrail "${guardrailId}" is not referenced by any entity and has no scope bindings`
+        });
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// src/linter/rules/validation-executor-no-context.ts
+var validationExecutorNoContextRule = {
+  id: "validation-executor-no-context",
+  description: "Validation executor is not wired so the validation appears in the executor's rendered context",
+  run(dsl) {
+    const diagnostics = [];
+    for (const [validationId, val] of Object.entries(dsl.validations)) {
+      if (val.executor_type === "agent") {
+        const agent = dsl.agents[val.executor];
+        if (!agent) continue;
+        const allowed = new Set(agent.can_perform_validations ?? []);
+        if (!allowed.has(validationId)) {
+          diagnostics.push({
+            ruleId: "validation-executor-no-context",
+            severity: "warning",
+            path: `agents.${val.executor}.can_perform_validations`,
+            message: `Validation "${validationId}" is executed by agent "${val.executor}" but is not listed in can_perform_validations, so it will be missing from that agent's prompt context`
+          });
+        }
+      } else if (val.executor_type === "tool") {
+        if (!dsl.tools[val.executor]) {
+          diagnostics.push({
+            ruleId: "validation-executor-no-context",
+            severity: "warning",
+            path: `validations.${validationId}.executor`,
+            message: `Validation "${validationId}" references tool executor "${val.executor}" which is not defined in tools`
+          });
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
 // src/linter/linter.ts
 var builtinRules = [
   validationCoverageRule,
@@ -52881,7 +53055,11 @@ var builtinRules = [
   yamlReservedKeySafetyRule,
   artifactRequiredValidationWiringRule,
   taskOutputValidationCompletenessRule,
-  semanticValidationPhaseCoverageRule
+  semanticValidationPhaseCoverageRule,
+  entityGuardrailUndefinedRule,
+  entityNoGuardrailsRule,
+  guardrailOrphanedRule,
+  validationExecutorNoContextRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -53628,12 +53806,96 @@ function buildGuardrailEnforcement(dsl, policy, loadedBindings) {
   }
   return entries;
 }
+function resolveEffectiveGuardrails(dsl, entityType, entityId) {
+  const entityDef = dsl[entityType][entityId];
+  const entitySide = new Set(entityDef?.guardrails ?? []);
+  const scopeSide = /* @__PURE__ */ new Set();
+  for (const [guardrailId, guardrail] of Object.entries(dsl.guardrails)) {
+    const scopeIds = guardrail.scope[entityType];
+    if (scopeIds?.includes(entityId)) {
+      scopeSide.add(guardrailId);
+    }
+  }
+  const allIds = /* @__PURE__ */ new Set([...entitySide, ...scopeSide]);
+  const activePolicyRules = /* @__PURE__ */ new Map();
+  for (const policy of Object.values(dsl.guardrail_policies)) {
+    for (const rule of policy.rules) {
+      if (!activePolicyRules.has(rule.guardrail)) {
+        activePolicyRules.set(rule.guardrail, {
+          severity: rule.severity,
+          action: rule.action
+        });
+      }
+    }
+  }
+  const entries = [];
+  for (const id of allIds) {
+    const guardrail = dsl.guardrails[id];
+    if (!guardrail) continue;
+    const fromEntity = entitySide.has(id);
+    const fromScope = scopeSide.has(id);
+    const source = fromEntity && fromScope ? "both" : fromEntity ? "entity" : "scope";
+    const policyInfo = activePolicyRules.get(id);
+    entries.push({
+      guardrail_id: id,
+      description: guardrail.description,
+      rationale: guardrail.rationale,
+      tags: guardrail.tags,
+      source,
+      severity: policyInfo?.severity,
+      action: policyInfo?.action
+    });
+  }
+  return entries;
+}
+function validationToEntityEntry(validationId, validation) {
+  return {
+    validation_id: validationId,
+    kind: validation.kind,
+    target_artifact: validation.target_artifact,
+    executor_type: validation.executor_type,
+    blocking: validation.blocking,
+    produces_evidence: validation.produces_evidence
+  };
+}
+function resolveEntityValidations(dsl, entityType, entityId) {
+  if (entityType === "agents") {
+    const agent = dsl.agents[entityId];
+    if (!agent) return [];
+    const entries2 = [];
+    for (const vid of agent.can_perform_validations ?? []) {
+      const v2 = dsl.validations[vid];
+      if (v2) entries2.push(validationToEntityEntry(vid, v2));
+    }
+    return entries2;
+  }
+  if (entityType === "tasks") {
+    const task = dsl.tasks[entityId];
+    if (!task) return [];
+    const entries2 = [];
+    for (const vid of task.validations ?? []) {
+      const v2 = dsl.validations[vid];
+      if (v2) entries2.push(validationToEntityEntry(vid, v2));
+    }
+    return entries2;
+  }
+  const entries = [];
+  for (const [vid, v2] of Object.entries(dsl.validations)) {
+    if (v2.executor_type === "tool" && v2.executor === entityId) {
+      entries.push(validationToEntityEntry(vid, v2));
+    }
+  }
+  entries.sort((a3, b3) => a3.validation_id.localeCompare(b3.validation_id));
+  return entries;
+}
 function buildTaskContext(dsl, taskId) {
   const taskDef = dsl.tasks[taskId];
   const task = { ...taskDef, id: taskId };
   const agentDef = dsl.agents[taskDef.target_agent];
   const targetAgent = agentDef ? { ...agentDef, id: taskDef.target_agent } : null;
-  return { task, targetAgent, dsl };
+  const relatedGuardrails = resolveEffectiveGuardrails(dsl, "tasks", taskId);
+  const relatedValidations = resolveEntityValidations(dsl, "tasks", taskId);
+  return { task, targetAgent, relatedGuardrails, relatedValidations, dsl };
 }
 function buildArtifactContext(dsl, artifactId) {
   const artifactDef = dsl.artifacts[artifactId];
@@ -53676,6 +53938,7 @@ function buildArtifactContext(dsl, artifactId) {
       }
     }
   }
+  const relatedGuardrails = resolveEffectiveGuardrails(dsl, "artifacts", artifactId);
   return {
     artifact,
     relatedTools,
@@ -53684,6 +53947,7 @@ function buildArtifactContext(dsl, artifactId) {
     consumerAgents,
     editorAgents,
     createdInWorkflows,
+    relatedGuardrails,
     dsl
   };
 }
@@ -53701,11 +53965,15 @@ function buildToolContext(dsl, toolId) {
     }
     return result;
   };
+  const relatedGuardrails = resolveEffectiveGuardrails(dsl, "tools", toolId);
+  const relatedValidations = resolveEntityValidations(dsl, "tools", toolId);
   return {
     tool,
     invokableAgents,
     inputArtifactDetails: pickArtifacts(toolDef.input_artifacts),
     outputArtifactDetails: pickArtifacts(toolDef.output_artifacts),
+    relatedGuardrails,
+    relatedValidations,
     dsl
   };
 }
@@ -53937,6 +54205,8 @@ function buildPerAgentContext(dsl, agent) {
   }
   const rawReceivableTasks = receivableTasks.map(({ id: _id, ...rest }) => rest);
   const mergedBehavior = mergeBehavioralSpec(agent, rawReceivableTasks);
+  const relatedGuardrails = resolveEffectiveGuardrails(dsl, "agents", agentId);
+  const relatedValidations = resolveEntityValidations(dsl, "agents", agentId);
   return {
     agent,
     tasks: receivableTasks,
@@ -53946,6 +54216,8 @@ function buildPerAgentContext(dsl, agent) {
     relatedTools,
     relatedHandoffTypes,
     mergedBehavior,
+    relatedGuardrails,
+    relatedValidations,
     dsl
   };
 }
@@ -55676,6 +55948,52 @@ function crossReferenceBidirectionality(dsl) {
     recommendations: issues.length > 0 ? [`${issues.length} unreciprocated cross-references: ${issues.slice(0, 5).join(", ")}${issues.length > 5 ? `, ... (${issues.length - 5} more)` : ""}`] : []
   };
 }
+function entityGuardrailCoverage(dsl) {
+  const entitySections = [
+    { name: "agents", entities: dsl.agents },
+    { name: "tasks", entities: dsl.tasks },
+    { name: "tools", entities: dsl.tools },
+    { name: "artifacts", entities: dsl.artifacts }
+  ];
+  const scopeBindings = {
+    agents: /* @__PURE__ */ new Set(),
+    tasks: /* @__PURE__ */ new Set(),
+    tools: /* @__PURE__ */ new Set(),
+    artifacts: /* @__PURE__ */ new Set()
+  };
+  for (const guardrail of Object.values(dsl.guardrails)) {
+    for (const key of Object.keys(scopeBindings)) {
+      const ids = guardrail.scope[key];
+      if (ids) {
+        for (const id of ids) scopeBindings[key].add(id);
+      }
+    }
+  }
+  let total = 0;
+  let covered = 0;
+  const missing = [];
+  for (const { name, entities } of entitySections) {
+    for (const [entityId, entity] of Object.entries(entities)) {
+      total++;
+      const hasEntitySide = (entity.guardrails ?? []).length > 0;
+      const hasScopeSide = scopeBindings[name].has(entityId);
+      if (hasEntitySide || hasScopeSide) {
+        covered++;
+      } else {
+        missing.push(`${name}.${entityId}`);
+      }
+    }
+  }
+  return {
+    id: "entity-guardrail-coverage",
+    label: "Entity guardrail coverage",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 1,
+    recommendations: missing.length > 0 ? [`${missing.length} entities without guardrails: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? `, ... (${missing.length - 5} more)` : ""}`] : []
+  };
+}
 function guardrailScopeResolution(dsl) {
   let totalRefs = 0;
   let resolvedRefs = 0;
@@ -55721,7 +56039,8 @@ function score(dsl) {
     workflowValidationIntegration(dsl),
     schemaCompleteness(dsl),
     crossReferenceBidirectionality(dsl),
-    guardrailScopeResolution(dsl)
+    guardrailScopeResolution(dsl),
+    entityGuardrailCoverage(dsl)
   ];
   const totalWeight = dimensions.reduce((s2, d2) => s2 + d2.weight, 0);
   const weightedSum = dimensions.reduce(