agent-contracts 0.11.4 → 0.11.5

package/README.md

@@ -221,12 +221,13 @@ A **Workflow** defines a phase-level execution sequence:
 * `entry_conditions`
 * `trigger`
 * `external_participants` — actors/participants outside the agent system (e.g., User, external advisory)
-* ordered steps (handoff, validation, decision)
+* ordered steps (delegate, gate, validation, decision)
 
 Workflow steps support additional properties:
 
 * `group` — consecutive steps with the same group are rendered as `par` (parallel) blocks in sequence diagrams
-* `retry` (handoff steps only) — defines a conditional retry loop with `condition`, `fix_task`, and optional `revalidate_task`
+* `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
 
 ### Guardrail
 
@@ -305,6 +306,9 @@ Design regressions become testable.
 * **Software bindings** (DI) for tool-specific guardrail implementation (Cursor, Git, GitHub)
 * **Guardrail generation** from DSL + policy + bindings via `generate guardrails`
 * **Flexible file splitting** via `$ref` (replacement), `$refs` (import + deep-merge), and JSON Pointer `$ref` (in-document)
+* **YAML safety linting** for reserved word collision detection across YAML 1.1/1.2
+* **`x-extensions` declarations** for documenting project-specific custom extension fields
+* **`resolve --expand-defaults`** to materialize all Zod schema defaults in output
 * **JSON Schema for editor support and external tooling**
 * **CI-friendly workflow checks**
 
@@ -342,6 +346,16 @@ guardrails: {}
 guardrail_policies: {}
 components:
   schemas: {}
+
+# Optional: declare project-specific x-* extensions
+x-extensions:
+  x-flags:
+    type: array
+    items: string
+    description: "CLI flags for tool commands"
+  x-check-script:
+    type: string
+    description: "Path to hook check script"
 ````
 
 This makes definitions easy to merge, extend, and reference by stable identifiers.
@@ -572,6 +586,23 @@ tasks:
 `x-` prefixed custom properties work at any nesting level — including inside
 `execution_steps`, `rules`, `workflow.steps`, and other nested objects.
 
+### `x-extensions` declarations
+
+Projects can optionally declare their custom `x-*` extension fields in the DSL using `x-extensions`. This makes extensions discoverable and self-documenting:
+
+````yaml
+x-extensions:
+  x-flags:
+    type: array
+    items: string
+    description: "CLI flags for tool commands"
+  x-check-script:
+    type: string
+    description: "Path to hook check script"
+````
+
+Each key must start with `x-` (validated at schema level). The `type`, `items`, and `description` fields describe the expected shape. This declaration is informational today; future versions may validate `x-*` field values against their declared schemas.
+
 ---
 
 ## Example: Artifact definition
@@ -602,21 +633,20 @@ workflow:
       - User story or feature request received
     trigger: "User invokes /speckit.specify or asks to create a feature spec."
     steps:
-      - type: handoff
-        handoff_kind: delegation
+      - type: delegate
         task: specify-feature
         from_agent: main-architect
       - type: validation
-        validation_id: spec-semantic-review
+        validation: spec-semantic-review
       - type: decision
-        agent: main-architect
-        options:
-          - label: approve
-            next_workflow: plan
-          - label: revise
-            retry_from_step: 0
+        routing_key: evidence-gate-verdict.verdict
+        branches:
+          PASS: [plan]
+          REVISE: [specify-feature]
 ````
 
+Decision steps use `routing_key` to specify the field that determines branching. The legacy `on` field is still accepted but deprecated — see [YAML safety](#yaml-safety) below.
+
 ---
 
 ## Example: Handoff type definition
@@ -819,10 +849,19 @@ npx agent-contracts
 The `[path]` argument defaults to `agent-contracts.yaml` in the current directory.
 If `-c` / `--config` is specified, the DSL path from the config file is used.
 
+#### `resolve` options
+
+| Option | Description |
+|--------|-------------|
+| `--format <text\|json>` | Output format (default: `text`) |
+| `--expand-defaults` | Expand all Zod default values in output. Fields like `required_validations: []`, `tags: []`, and `can_read_artifacts: []` are written explicitly instead of being silently applied by schema defaults. |
+| `-c, --config <path>` | Path to `agent-contracts.config.yaml` |
+
 ### Common usage
 
 ````bash
 agent-contracts resolve
+agent-contracts resolve --expand-defaults --format json
 agent-contracts validate
 agent-contracts lint --strict
 agent-contracts render -c agent-contracts.config.yaml
@@ -1153,6 +1192,34 @@ Checks:
 
 Custom properties with `x-` prefix are allowed on any object in the DSL — top-level entities (agents, tasks, artifacts, …), nested objects (rules, execution steps, workflow steps, …), and the root DSL itself.
 
+### YAML safety
+
+The DSL is expressed in YAML, which introduces risks from YAML 1.1's implicit type coercion. The `yaml-reserved-key-safety` lint rule warns when reserved words appear in positions that may be misinterpreted by non-1.2 parsers.
+
+The most notable case is the `on` field in decision steps. In YAML 1.1, bare `on` as a mapping key is interpreted as boolean `true`. While `agent-contracts` uses a YAML 1.2 parser internally, DSL consumers (CI tools, editors, other parsers) may use YAML 1.1 parsers.
+
+To address this:
+
+* Decision steps now support `routing_key` as the preferred field name (replacing `on`)
+* The legacy `on` field is still accepted for backward compatibility but triggers a lint warning
+* Branch keys like `yes`, `no`, `true`, `false` also trigger warnings
+
+````yaml
+# Preferred — safe across all YAML versions
+- type: decision
+  routing_key: evidence-gate-verdict.verdict
+  branches:
+    PASS: [release]
+    FAIL: [fix-violations]
+
+# Deprecated — works but triggers yaml-reserved-key-safety warning
+- type: decision
+  on: evidence-gate-verdict.verdict
+  branches:
+    PASS: [release]
+    FAIL: [fix-violations]
+````
+
 ### Reference integrity
 
 Checks:
@@ -1174,6 +1241,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`
+* 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

@@ -50728,7 +50728,9 @@ var WorkflowValidationStepSchema = z11.object({
 var WorkflowDecisionStepSchema = z11.object({
   type: z11.literal("decision"),
   description: z11.string().optional(),
-  on: z11.string(),
+  /** @deprecated Use `routing_key` instead. `on` is kept for backward compatibility. */
+  on: z11.string().optional(),
+  routing_key: z11.string().optional(),
   branches: z11.record(z11.string(), z11.array(z11.string())),
   group: z11.string().optional()
 }).passthrough();
@@ -50751,6 +50753,11 @@ var WorkflowSchema = z11.object({
 var ComponentsSchema = z12.object({
   schemas: z12.record(z12.string(), z12.record(z12.string(), z12.any())).default({})
 }).passthrough();
+var XExtensionDeclSchema = z12.object({
+  type: z12.string(),
+  items: z12.string().optional(),
+  description: z12.string().optional()
+});
 var DslSchema = z12.object({
   version: z12.literal(1),
   extends: z12.string().optional(),
@@ -50765,7 +50772,8 @@ var DslSchema = z12.object({
   policies: z12.record(z12.string(), PolicySchema).default({}),
   guardrails: z12.record(z12.string(), GuardrailSchema).default({}),
   guardrail_policies: z12.record(z12.string(), GuardrailPolicySchema).default({}),
-  components: ComponentsSchema.default({ schemas: {} })
+  components: ComponentsSchema.default({ schemas: {} }),
+  "x-extensions": z12.record(z12.string(), XExtensionDeclSchema).optional()
 }).passthrough();
 
 // src/schema/json-schema-utils.ts
@@ -51620,6 +51628,13 @@ function substituteVars(data, vars) {
   return walk(data, vars);
 }
 
+// src/resolver/expand-defaults.ts
+function expandDefaults(data) {
+  const result = DslSchema.safeParse(data);
+  if (!result.success) return data;
+  return JSON.parse(JSON.stringify(result.data));
+}
+
 // src/config/binding-merger.ts
 function isRecord3(v2) {
   return typeof v2 === "object" && v2 !== null && !Array.isArray(v2);
@@ -51760,12 +51775,15 @@ ${issues}`,
 // src/cli/commands/resolve.ts
 import { stringify } from "yaml";
 var DIR_DEFAULT = "agent-contracts.yaml";
-var resolveCommand = new Command("resolve").description("Resolve DSL (load + merge extends) and output YAML").argument("[dir]", "Path to agent-contracts.yaml", DIR_DEFAULT).option("-c, --config <path>", "Path to agent-contracts.config.yaml").option("--format <format>", "Output format (text|json)", "text").action(async (dir, opts) => {
+var resolveCommand = new Command("resolve").description("Resolve DSL (load + merge extends) and output YAML").argument("[dir]", "Path to agent-contracts.yaml", DIR_DEFAULT).option("-c, --config <path>", "Path to agent-contracts.config.yaml").option("--format <format>", "Output format (text|json)", "text").option("--expand-defaults", "Expand all Zod default values in output", false).action(async (dir, opts) => {
   try {
     const config = await loadConfig(opts.config);
     const dslPath = resolveDslPath(dir, DIR_DEFAULT, config);
     const result = await resolve4(dslPath);
-    const data = config?.vars ? substituteVars(result.data, config.vars) : result.data;
+    let data = config?.vars ? substituteVars(result.data, config.vars) : result.data;
+    if (opts.expandDefaults) {
+      data = expandDefaults(data);
+    }
     if (opts.format === "json") {
       process.stdout.write(JSON.stringify(data, null, 2) + "\n");
     } else {
@@ -51844,6 +51862,47 @@ function checkCustomPropsRecursive(data, schema, path) {
   }
   return [];
 }
+function checkXExtensionsKeys(data) {
+  const extensions = data["x-extensions"];
+  if (typeof extensions !== "object" || extensions === null) return [];
+  const diagnostics = [];
+  for (const key of Object.keys(extensions)) {
+    if (!key.startsWith("x-")) {
+      diagnostics.push({
+        path: `x-extensions.${key}`,
+        message: `Extension key "${key}" must start with "x-" prefix.`,
+        code: "x-extension-key-prefix"
+      });
+    }
+  }
+  return diagnostics;
+}
+function checkDecisionStepRoutingKey(data) {
+  const workflow = data["workflow"];
+  if (typeof workflow !== "object" || workflow === null) return [];
+  const diagnostics = [];
+  for (const [wfKey, wf] of Object.entries(
+    workflow
+  )) {
+    if (typeof wf !== "object" || wf === null) continue;
+    const steps = wf["steps"];
+    if (!Array.isArray(steps)) continue;
+    for (let i3 = 0; i3 < steps.length; i3++) {
+      const step = steps[i3];
+      if (typeof step !== "object" || step === null) continue;
+      const s2 = step;
+      if (s2["type"] !== "decision") continue;
+      if (s2["routing_key"] === void 0 && s2["on"] === void 0) {
+        diagnostics.push({
+          path: `workflow.${wfKey}.steps[${i3}]`,
+          message: 'Decision step requires "routing_key" (or deprecated "on"). Prefer "routing_key".',
+          code: "decision-missing-routing-key"
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
 function validateSchema(data) {
   const result = DslSchema.safeParse(data);
   if (!result.success) {
@@ -51858,6 +51917,14 @@ function validateSchema(data) {
   if (customPropDiagnostics.length > 0) {
     return { success: false, diagnostics: customPropDiagnostics };
   }
+  const decisionDiagnostics = checkDecisionStepRoutingKey(data);
+  if (decisionDiagnostics.length > 0) {
+    return { success: false, diagnostics: decisionDiagnostics };
+  }
+  const xExtDiagnostics = checkXExtensionsKeys(data);
+  if (xExtDiagnostics.length > 0) {
+    return { success: false, diagnostics: xExtDiagnostics };
+  }
   return { success: true, data: result.data, diagnostics: [] };
 }
 
@@ -52583,6 +52650,51 @@ var guardrailPolicyCoverageRule = {
   }
 };
 
+// src/linter/rules/yaml-reserved-key-safety.ts
+var YAML_11_RESERVED_KEYS = /* @__PURE__ */ new Set([
+  "on",
+  "off",
+  "yes",
+  "no",
+  "true",
+  "false",
+  "y",
+  "n"
+]);
+var yamlReservedKeySafetyRule = {
+  id: "yaml-reserved-key-safety",
+  description: "Warns when YAML 1.1 reserved words are used as field values in positions where they may be misinterpreted by non-1.2 parsers",
+  run(dsl) {
+    const diagnostics = [];
+    for (const [wfKey, wf] of Object.entries(dsl.workflow)) {
+      for (let i3 = 0; i3 < wf.steps.length; i3++) {
+        const step = wf.steps[i3];
+        if (step.type !== "decision") continue;
+        if (step.on !== void 0 && step.routing_key === void 0) {
+          diagnostics.push({
+            ruleId: "yaml-reserved-key-safety",
+            severity: "warning",
+            path: `workflow.${wfKey}.steps[${i3}].on`,
+            message: 'Field name "on" is a YAML 1.1 reserved word and may be interpreted as boolean true by some parsers. Use "routing_key" instead.'
+          });
+        }
+        const branchKeys = Object.keys(step.branches);
+        for (const key of branchKeys) {
+          if (YAML_11_RESERVED_KEYS.has(key.toLowerCase())) {
+            diagnostics.push({
+              ruleId: "yaml-reserved-key-safety",
+              severity: "warning",
+              path: `workflow.${wfKey}.steps[${i3}].branches.${key}`,
+              message: `Branch key "${key}" is a YAML 1.1 reserved word and may be interpreted as a boolean by some parsers. Consider quoting or renaming.`
+            });
+          }
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
 // src/linter/linter.ts
 var builtinRules = [
   validationCoverageRule,
@@ -52591,7 +52703,8 @@ var builtinRules = [
   mergeIntegrityRule,
   artifactOwnershipRule,
   toolCommandsRule,
-  guardrailPolicyCoverageRule
+  guardrailPolicyCoverageRule,
+  yamlReservedKeySafetyRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];