agent-contracts 0.11.7 → 0.11.8

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:
@@ -1268,6 +1293,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 = [];