agent-contracts 0.11.7 → 0.12.0

package/README.md

@@ -229,6 +229,31 @@ Workflow steps support additional properties:
 * `retry` (delegate steps) — defines a conditional retry loop with `condition`, `fix_task`, and optional `revalidate_task`
 * `routing_key` (decision steps) — the field that determines branch selection. The legacy field `on` is still accepted but deprecated due to YAML 1.1 reserved word collision
 
+### Validation
+
+A **Validation** defines a verification step for an artifact:
+
+* `target_artifact` — the artifact being verified
+* `kind` — the type of verification (see below)
+* `executor_type` — `tool` (automated) or `agent` (agent-driven)
+* `executor` — the tool or agent that runs the validation
+* `blocking` — whether the validation must pass before proceeding
+* `produces_evidence` — optional artifact produced as evidence
+
+#### Validation kinds
+
+| Kind | Purpose | Example |
+|------|---------|---------|
+| `schema` | Structural schema check | JSON Schema validation, OpenAPI lint, SQL syntax |
+| `mechanical` | Automated tool check | CLI linters, diff checks, coverage reports |
+| `semantic` | Meaning-level review | Agent-based review of spec intent, plan coherence |
+| `approval` | Human/agent sign-off gate | Architect approval before implementation |
+| `provenance` | Source derivation verification | Confirm generated artifact derives from its canonical source (e.g., manifest from API contracts) |
+| `traceability` | Cross-artifact link completeness | Verify every spec requirement reaches contracts, tests, and code |
+| `fidelity` | Semantic faithfulness to source | Confirm tests actually verify spec intent, not just structural compliance |
+
+`schema` and `mechanical` are best suited for automated checks via tools. `semantic`, `fidelity`, and `approval` are typically agent-driven. `provenance` and `traceability` can be either tool or agent-based depending on the verification complexity.
+
 ### Guardrail
 
 A **Guardrail** declares a cross-cutting constraint:
@@ -973,7 +998,7 @@ Each `context` type provides a different rendering scope:
 
 | Context | Scope | Output | Key variables |
 |---------|-------|--------|---------------|
-| `system` | Single file | `output` as-is | `system`, `dsl` |
+| `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` |
@@ -1002,6 +1027,18 @@ Each `context` type provides a different rendering scope:
 * `producerAgents` / `consumerAgents` / `editorAgents` — resolved agent records
 * `createdInWorkflows` — workflow phases where this artifact is written
 
+**`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`
+* `bindings` — array of loaded `SoftwareBinding` objects
+
+These fields are only populated when the config specifies `bindings` and `active_guardrail_policy`. Existing templates that do not reference these fields are unaffected.
+
+**Matrix helpers** are available in `context: system` templates:
+
+* `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`
@@ -1268,6 +1305,7 @@ Checks:
 * prerequisite readability
 * 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)
 * 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

@@ -50676,7 +50676,7 @@ var ToolSchema = z9.object({
 import { z as z10 } from "zod";
 var ValidationSchema = z10.object({
   target_artifact: z10.string(),
-  kind: z10.enum(["schema", "mechanical", "semantic", "approval"]),
+  kind: z10.enum(["schema", "mechanical", "semantic", "approval", "provenance", "traceability", "fidelity"]),
   executor_type: z10.enum(["tool", "agent"]),
   executor: z10.string(),
   blocking: z10.boolean(),
@@ -52800,6 +52800,68 @@ var taskOutputValidationCompletenessRule = {
   }
 };
 
+// src/linter/rules/semantic-validation-phase-coverage.ts
+var SEMANTIC_KINDS = /* @__PURE__ */ new Set(["semantic", "fidelity"]);
+var semanticValidationPhaseCoverageRule = {
+  id: "semantic-validation-phase-coverage",
+  description: "Semantic and fidelity validations should appear in early workflow phases, not only in late phases.",
+  run(dsl) {
+    const diagnostics = [];
+    const semanticValIds = /* @__PURE__ */ new Set();
+    for (const [valId, val] of Object.entries(dsl.validations)) {
+      if (SEMANTIC_KINDS.has(val.kind)) {
+        semanticValIds.add(valId);
+      }
+    }
+    if (semanticValIds.size === 0) {
+      return diagnostics;
+    }
+    const phaseOrder = dsl.system.default_workflow_order;
+    if (phaseOrder.length < 2) {
+      return diagnostics;
+    }
+    const phaseValidations = /* @__PURE__ */ new Map();
+    for (const phase of phaseOrder) {
+      phaseValidations.set(phase, /* @__PURE__ */ new Set());
+    }
+    for (const [phase, wf] of Object.entries(dsl.workflow)) {
+      if (!phaseValidations.has(phase)) continue;
+      for (const step of wf.steps) {
+        if (step.type === "validation" && semanticValIds.has(step.validation)) {
+          phaseValidations.get(phase).add(step.validation);
+        }
+      }
+    }
+    for (const task of Object.values(dsl.tasks)) {
+      const phase = task.workflow;
+      if (!phaseValidations.has(phase)) continue;
+      for (const valId of task.validations) {
+        if (semanticValIds.has(valId)) {
+          phaseValidations.get(phase).add(valId);
+        }
+      }
+    }
+    const earlyBoundary = Math.ceil(phaseOrder.length / 2);
+    const earlyPhases = phaseOrder.slice(0, earlyBoundary);
+    const latePhases = phaseOrder.slice(earlyBoundary);
+    const earlyHasAny = earlyPhases.some(
+      (p2) => (phaseValidations.get(p2)?.size ?? 0) > 0
+    );
+    const lateWithSemantic = latePhases.filter(
+      (p2) => (phaseValidations.get(p2)?.size ?? 0) > 0
+    );
+    if (!earlyHasAny && lateWithSemantic.length > 0) {
+      diagnostics.push({
+        ruleId: "semantic-validation-phase-coverage",
+        severity: "warning",
+        path: "validations",
+        message: `Semantic validations are only referenced in workflow phases [${lateWithSemantic.join(", ")}]. Consider adding semantic review to earlier phases [${earlyPhases.join(", ")}] to catch issues before implementation.`
+      });
+    }
+    return diagnostics;
+  }
+};
+
 // src/linter/linter.ts
 var builtinRules = [
   validationCoverageRule,
@@ -52811,7 +52873,8 @@ var builtinRules = [
   guardrailPolicyCoverageRule,
   yamlReservedKeySafetyRule,
   artifactRequiredValidationWiringRule,
-  taskOutputValidationCompletenessRule
+  taskOutputValidationCompletenessRule,
+  semanticValidationPhaseCoverageRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -53511,8 +53574,52 @@ import { dirname as dirname5 } from "path";
 import Handlebars from "handlebars";
 
 // src/renderer/context.ts
-function buildSystemContext(dsl) {
-  return { system: dsl.system, dsl };
+function buildSystemContext(dsl, options) {
+  const ctx = { system: dsl.system, dsl };
+  if (options?.loadedBindings && options.loadedBindings.length > 0) {
+    ctx.bindings = options.loadedBindings.map((lb) => lb.binding);
+    const policyName = options.activeGuardrailPolicy;
+    const policy = policyName ? dsl.guardrail_policies[policyName] : void 0;
+    if (policy) {
+      ctx.guardrailEnforcement = buildGuardrailEnforcement(dsl, policy, options.loadedBindings);
+    }
+  }
+  return ctx;
+}
+function buildGuardrailEnforcement(dsl, policy, loadedBindings) {
+  const entries = [];
+  const bindingTriggers = /* @__PURE__ */ new Map();
+  for (const lb of loadedBindings) {
+    const impl = lb.binding.guardrail_impl ?? {};
+    for (const [guardrailId, gi] of Object.entries(impl)) {
+      for (const check of gi.checks) {
+        if (check.matcher) {
+          bindingTriggers.set(guardrailId, check.matcher.type);
+        }
+      }
+    }
+  }
+  for (const rule of policy.rules) {
+    const guardrail = dsl.guardrails[rule.guardrail];
+    if (!guardrail) continue;
+    const scope = guardrail.scope ?? {};
+    entries.push({
+      guardrail_id: rule.guardrail,
+      description: guardrail.description,
+      severity: rule.severity,
+      action: rule.action,
+      scoped_agents: scope.agents ?? [],
+      scoped_tasks: scope.tasks ?? [],
+      scoped_workflows: scope.workflows ?? [],
+      scoped_tools: scope.tools ?? [],
+      scoped_artifacts: scope.artifacts ?? [],
+      allow_override: rule.allow_override,
+      override_requires: rule.override_requires ?? [],
+      trigger: bindingTriggers.get(rule.guardrail) ?? null,
+      escalation: rule.escalation ? { target: rule.escalation.target, condition: rule.escalation.condition } : null
+    });
+  }
+  return entries;
 }
 function buildTaskContext(dsl, taskId) {
   const taskDef = dsl.tasks[taskId];
@@ -54567,6 +54674,50 @@ Handlebars.registerHelper(
     return generateOverviewFlowchart(dsl);
   }
 );
+Handlebars.registerHelper(
+  "guardrailCoverageMatrix",
+  function() {
+    const enforcement = this["guardrailEnforcement"];
+    if (!enforcement || enforcement.length === 0) return "";
+    const header = "| Guardrail | Severity | Action | Agents | Tasks | Workflows | Tools | Artifacts | Trigger | Override | Escalation |";
+    const divider = "|-----------|----------|--------|--------|-------|-----------|-------|-----------|---------|----------|------------|";
+    const rows = enforcement.map((e3) => {
+      const agents = e3["scoped_agents"]?.join(", ") || "\u2014";
+      const tasks = e3["scoped_tasks"]?.join(", ") || "\u2014";
+      const workflows = e3["scoped_workflows"]?.join(", ") || "\u2014";
+      const tools = e3["scoped_tools"]?.join(", ") || "\u2014";
+      const artifacts = e3["scoped_artifacts"]?.join(", ") || "\u2014";
+      const trigger = e3["trigger"] || "\u2014";
+      const override = e3["allow_override"] ? "yes" : "no";
+      const esc = e3["escalation"];
+      const escalation = esc ? esc["target"] : "\u2014";
+      return `| ${e3["guardrail_id"]} | ${e3["severity"]} | ${e3["action"]} | ${agents} | ${tasks} | ${workflows} | ${tools} | ${artifacts} | ${trigger} | ${override} | ${escalation} |`;
+    });
+    return [header, divider, ...rows].join("\n");
+  }
+);
+Handlebars.registerHelper(
+  "taskGuardrailMatrix",
+  function() {
+    const dsl = this["dsl"];
+    const enforcement = this["guardrailEnforcement"];
+    if (!dsl || !enforcement || enforcement.length === 0) return "";
+    const taskIds = Object.keys(dsl.tasks);
+    if (taskIds.length === 0) return "";
+    const guardrailIds = enforcement.map((e3) => e3["guardrail_id"]);
+    const header = `| Task | ${guardrailIds.join(" | ")} |`;
+    const divider = `|------|${guardrailIds.map(() => "------").join("|")}|`;
+    const rows = taskIds.map((taskId) => {
+      const cells = enforcement.map((e3) => {
+        const scopedTasks = e3["scoped_tasks"];
+        if (scopedTasks.length > 0 && !scopedTasks.includes(taskId)) return "n/a";
+        return e3["action"];
+      });
+      return `| ${taskId} | ${cells.join(" | ")} |`;
+    });
+    return [header, divider, ...rows].join("\n");
+  }
+);
 function getDslSection(dsl, context) {
   const sectionMap = {
     agent: dsl.agents,
@@ -54631,13 +54782,13 @@ async function removeIfExists(filePath) {
   } catch {
   }
 }
-async function renderFromConfig(dsl, renderTargets) {
+async function renderFromConfig(dsl, renderTargets, options) {
   const outputFiles = [];
   for (const target of renderTargets) {
     const templateContent = await loadTemplate(target.template);
     const compiled = Handlebars.compile(templateContent, { noEscape: false });
     if (target.context === "system") {
-      const ctx = buildSystemContext(dsl);
+      const ctx = buildSystemContext(dsl, options);
       const output = compiled(ctx);
       if (target.skip_empty && isEffectivelyEmpty(output)) {
         await removeIfExists(target.output);
@@ -54686,13 +54837,13 @@ function checkExpectedVsExisting(expected, outputPath, skipEmpty, diffs) {
     diffs.push(outputPath);
   });
 }
-async function checkDriftFromConfig(dsl, renderTargets) {
+async function checkDriftFromConfig(dsl, renderTargets, options) {
   const diffs = [];
   for (const target of renderTargets) {
     const templateContent = await loadTemplate(target.template);
     const compiled = Handlebars.compile(templateContent, { noEscape: false });
     if (target.context === "system") {
-      const ctx = buildSystemContext(dsl);
+      const ctx = buildSystemContext(dsl, options);
       const expected = compiled(ctx);
       await checkExpectedVsExisting(expected, target.output, target.skip_empty, diffs);
     } else {
@@ -54730,10 +54881,19 @@ var renderCommand = new Command4("render").description("Render resolved DSL with
         );
         process.exit(1);
       }
+      let renderOptions;
+      if (config.bindings.length > 0) {
+        const loadedBindings = await loadBindings(config.bindings);
+        renderOptions = {
+          loadedBindings,
+          activeGuardrailPolicy: config.activeGuardrailPolicy
+        };
+      }
       if (opts.check) {
         const drift = await checkDriftFromConfig(
           schemaResult.data,
-          config.renders
+          config.renders,
+          renderOptions
         );
         if (drift.hasDrift) {
           process.stderr.write("Drift detected in the following files:\n");
@@ -54749,7 +54909,8 @@ var renderCommand = new Command4("render").description("Render resolved DSL with
       } else {
         const files = await renderFromConfig(
           schemaResult.data,
-          config.renders
+          config.renders,
+          renderOptions
         );
         if (!opts.quiet) {
           process.stdout.write(`Rendered ${files.length} file(s):