agent-contracts 0.11.3 → 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

@@ -159,11 +159,11 @@ function __metadata(metadataKey, metadataValue) {
 }
 function __awaiter(thisArg, _arguments, P2, generator) {
   function adopt(value) {
-    return value instanceof P2 ? value : new P2(function(resolve7) {
-      resolve7(value);
+    return value instanceof P2 ? value : new P2(function(resolve8) {
+      resolve8(value);
     });
   }
-  return new (P2 || (P2 = Promise))(function(resolve7, reject) {
+  return new (P2 || (P2 = Promise))(function(resolve8, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -179,7 +179,7 @@ function __awaiter(thisArg, _arguments, P2, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve7(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve8(result.value) : adopt(result.value).then(fulfilled, rejected);
     }
     step((generator = generator.apply(thisArg, _arguments || [])).next());
   });
@@ -370,14 +370,14 @@ function __asyncValues(o3) {
   }, i3);
   function verb(n3) {
     i3[n3] = o3[n3] && function(v2) {
-      return new Promise(function(resolve7, reject) {
-        v2 = o3[n3](v2), settle(resolve7, reject, v2.done, v2.value);
+      return new Promise(function(resolve8, reject) {
+        v2 = o3[n3](v2), settle(resolve8, reject, v2.done, v2.value);
       });
     };
   }
-  function settle(resolve7, reject, d2, v2) {
+  function settle(resolve8, reject, d2, v2) {
     Promise.resolve(v2).then(function(v3) {
-      resolve7({ value: v3, done: d2 });
+      resolve8({ value: v3, done: d2 });
     }, reject);
   }
 }
@@ -13033,11 +13033,11 @@ function __metadata2(metadataKey, metadataValue) {
 }
 function __awaiter2(thisArg, _arguments, P2, generator) {
   function adopt(value) {
-    return value instanceof P2 ? value : new P2(function(resolve7) {
-      resolve7(value);
+    return value instanceof P2 ? value : new P2(function(resolve8) {
+      resolve8(value);
     });
   }
-  return new (P2 || (P2 = Promise))(function(resolve7, reject) {
+  return new (P2 || (P2 = Promise))(function(resolve8, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -13053,7 +13053,7 @@ function __awaiter2(thisArg, _arguments, P2, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve7(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve8(result.value) : adopt(result.value).then(fulfilled, rejected);
     }
     step((generator = generator.apply(thisArg, _arguments || [])).next());
   });
@@ -13231,14 +13231,14 @@ function __asyncValues2(o3) {
   }, i3);
   function verb(n3) {
     i3[n3] = o3[n3] && function(v2) {
-      return new Promise(function(resolve7, reject) {
-        v2 = o3[n3](v2), settle(resolve7, reject, v2.done, v2.value);
+      return new Promise(function(resolve8, reject) {
+        v2 = o3[n3](v2), settle(resolve8, reject, v2.done, v2.value);
       });
     };
   }
-  function settle(resolve7, reject, d2, v2) {
+  function settle(resolve8, reject, d2, v2) {
     Promise.resolve(v2).then(function(v3) {
-      resolve7({ value: v3, done: d2 });
+      resolve8({ value: v3, done: d2 });
     }, reject);
   }
 }
@@ -15152,7 +15152,7 @@ function consumeBody() {
   let accum = [];
   let accumBytes = 0;
   let abort = false;
-  return new Body.Promise(function(resolve7, reject) {
+  return new Body.Promise(function(resolve8, reject) {
     let resTimeout;
     if (_this4.timeout) {
       resTimeout = setTimeout(function() {
@@ -15186,7 +15186,7 @@ function consumeBody() {
       }
       clearTimeout(resTimeout);
       try {
-        resolve7(Buffer.concat(accum, accumBytes));
+        resolve8(Buffer.concat(accum, accumBytes));
       } catch (err) {
         reject(new FetchError(`Could not create Buffer from response body for ${_this4.url}: ${err.message}`, "system", err));
       }
@@ -15449,7 +15449,7 @@ function fetch(url, opts) {
     throw new Error("native promise missing, set fetch.Promise to your favorite alternative");
   }
   Body.Promise = fetch.Promise;
-  return new fetch.Promise(function(resolve7, reject) {
+  return new fetch.Promise(function(resolve8, reject) {
     const request = new Request(url, opts);
     const options = getNodeRequestOptions(request);
     const send = (options.protocol === "https:" ? https : http).request;
@@ -15582,7 +15582,7 @@ function fetch(url, opts) {
               requestOpts.body = void 0;
               requestOpts.headers.delete("content-length");
             }
-            resolve7(fetch(new Request(locationURL, requestOpts)));
+            resolve8(fetch(new Request(locationURL, requestOpts)));
             finalize();
             return;
         }
@@ -15603,7 +15603,7 @@ function fetch(url, opts) {
       const codings = headers.get("Content-Encoding");
       if (!request.compress || request.method === "HEAD" || codings === null || res.statusCode === 204 || res.statusCode === 304) {
         response = new Response(body, response_options);
-        resolve7(response);
+        resolve8(response);
         return;
       }
       const zlibOptions = {
@@ -15613,7 +15613,7 @@ function fetch(url, opts) {
       if (codings == "gzip" || codings == "x-gzip") {
         body = body.pipe(zlib.createGunzip(zlibOptions));
         response = new Response(body, response_options);
-        resolve7(response);
+        resolve8(response);
         return;
       }
       if (codings == "deflate" || codings == "x-deflate") {
@@ -15625,12 +15625,12 @@ function fetch(url, opts) {
             body = body.pipe(zlib.createInflateRaw());
           }
           response = new Response(body, response_options);
-          resolve7(response);
+          resolve8(response);
         });
         raw.on("end", function() {
           if (!response) {
             response = new Response(body, response_options);
-            resolve7(response);
+            resolve8(response);
           }
         });
         return;
@@ -15638,11 +15638,11 @@ function fetch(url, opts) {
       if (codings == "br" && typeof zlib.createBrotliDecompress === "function") {
         body = body.pipe(zlib.createBrotliDecompress());
         response = new Response(body, response_options);
-        resolve7(response);
+        resolve8(response);
         return;
       }
       response = new Response(body, response_options);
-      resolve7(response);
+      resolve8(response);
     });
     writeToStream(req, request);
   });
@@ -16355,13 +16355,13 @@ var require_file = __commonJS({
     Object.defineProperty(exports, "__esModule", { value: true });
     var fs_1 = __require("fs");
     function resolveFile(ref) {
-      return new Promise((resolve7, reject) => {
+      return new Promise((resolve8, reject) => {
         const path = ref.href();
         fs_1.readFile(path, "utf8", (err, data) => {
           if (err) {
             reject(err);
           } else {
-            resolve7(data);
+            resolve8(data);
           }
         });
       });
@@ -23964,12 +23964,12 @@ var require_reader = __commonJS({
         }
       } else {
         try {
-          return await new Promise((resolve7, reject) => {
+          return await new Promise((resolve8, reject) => {
             fs.readFile(name, opts.encoding, (err, data) => {
               if (err !== null) {
                 reject(err);
               } else {
-                resolve7(data);
+                resolve8(data);
               }
             });
           });
@@ -40854,14 +40854,14 @@ var require_AsyncFromSyncIteratorContinuation = __commonJS({
       if (!$Promise) {
         throw new $SyntaxError("This environment does not support Promises.");
       }
-      return new $Promise(function(resolve7) {
+      return new $Promise(function(resolve8) {
         var done = IteratorComplete(result);
         var value = IteratorValue(result);
         var valueWrapper = PromiseResolve($Promise, value);
         var onFulfilled = function(value2) {
           return CreateIteratorResultObject(value2, done);
         };
-        resolve7($then(valueWrapper, onFulfilled));
+        resolve8($then(valueWrapper, onFulfilled));
       });
     };
   }
@@ -41409,7 +41409,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
         var O2 = this;
         SLOT.assert(O2, "[[SyncIteratorRecord]]");
         var argsLength = arguments.length;
-        return new $Promise(function(resolve7) {
+        return new $Promise(function(resolve8) {
           var syncIteratorRecord = SLOT.get(O2, "[[SyncIteratorRecord]]");
           var result;
           if (argsLength > 0) {
@@ -41417,7 +41417,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
           } else {
             result = IteratorNext(syncIteratorRecord);
           }
-          resolve7(AsyncFromSyncIteratorContinuation(result));
+          resolve8(AsyncFromSyncIteratorContinuation(result));
         });
       },
       "return": function() {
@@ -41428,12 +41428,12 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
         SLOT.assert(O2, "[[SyncIteratorRecord]]");
         var valueIsPresent = arguments.length > 0;
         var value = valueIsPresent ? arguments[0] : void 0;
-        return new $Promise(function(resolve7, reject) {
+        return new $Promise(function(resolve8, reject) {
           var syncIterator = SLOT.get(O2, "[[SyncIteratorRecord]]")["[[Iterator]]"];
           var iteratorReturn = GetMethod(syncIterator, "return");
           if (typeof iteratorReturn === "undefined") {
             var iterResult = CreateIteratorResultObject(value, true);
-            Call(resolve7, void 0, [iterResult]);
+            Call(resolve8, void 0, [iterResult]);
             return;
           }
           var result;
@@ -41446,7 +41446,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
             Call(reject, void 0, [new $TypeError("Iterator `return` method returned a non-object value.")]);
             return;
           }
-          resolve7(AsyncFromSyncIteratorContinuation(result));
+          resolve8(AsyncFromSyncIteratorContinuation(result));
         });
       },
       "throw": function() {
@@ -41457,7 +41457,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
         SLOT.assert(O2, "[[SyncIteratorRecord]]");
         var valueIsPresent = arguments.length > 0;
         var value = valueIsPresent ? arguments[0] : void 0;
-        return new $Promise(function(resolve7, reject) {
+        return new $Promise(function(resolve8, reject) {
           var syncIterator = SLOT.get(O2, "[[SyncIteratorRecord]]")["[[Iterator]]"];
           var throwMethod = GetMethod(syncIterator, "throw");
           if (typeof throwMethod === "undefined") {
@@ -41474,7 +41474,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
             Call(reject, void 0, [new $TypeError("Iterator `throw` method returned a non-object value.")]);
             return;
           }
-          resolve7(AsyncFromSyncIteratorContinuation(
+          resolve8(AsyncFromSyncIteratorContinuation(
             result
             /* , promiseCapability */
           ));
@@ -50425,6 +50425,9 @@ var require_dist13 = __commonJS({
 });
 
 // src/cli/cli.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { resolve as resolve7, dirname as dirname7 } from "path";
 import { Command as Command7 } from "commander";
 
 // src/cli/commands/resolve.ts
@@ -50725,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();
@@ -50748,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(),
@@ -50762,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
@@ -51617,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);
@@ -51757,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 {
@@ -51841,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) {
@@ -51855,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: [] };
 }
 
@@ -52580,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,
@@ -52588,7 +52703,8 @@ var builtinRules = [
   mergeIntegrityRule,
   artifactOwnershipRule,
   toolCommandsRule,
-  guardrailPolicyCoverageRule
+  guardrailPolicyCoverageRule,
+  yamlReservedKeySafetyRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -54961,8 +55077,10 @@ var generateGuardrailsCommand = new Command6("generate").description("Generate g
 );
 
 // src/cli/cli.ts
+var __dirname = dirname7(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(resolve7(__dirname, "../package.json"), "utf8"));
 var program = new Command7();
-program.name("agent-contracts").description("Agent contracts tooling \u2014 validate, lint, render DSL files").version("0.0.2");
+program.name("agent-contracts").description("Agent contracts tooling \u2014 validate, lint, render DSL files").version(pkg.version);
 program.addCommand(resolveCommand);
 program.addCommand(validateCommand);
 program.addCommand(lintCommand);