agent-contracts 0.22.3 → 0.22.4

package/dist/cli.js

@@ -49436,7 +49436,7 @@ function createProgram(handlers2, version) {
     }
     await handlers2.score(dir, opts, globalOpts);
   });
-  program2.command("audit").description("Run LLM-based semantic audit on DSL definitions and generated outputs.").argument("[type]", "Audit type to run: render (semantic diff of generated outputs vs DSL), dsl (design coherence review), prompt (generated prompt fidelity check), or all (run all three).").option("-c, --config <path>", "Path to agent-contracts.config.yaml.").option("--team <id>", "Limit to one team (multi-team config only).").option("--format <format>", "Output format.", "text").option("--scope <entities>", "Limit audit scope to specified entities (e.g. agents:architect,implementer).").option("--dry-run", "Output the audit prompt without calling LLM.", false).option("--adapter <name>", "SDK adapter to use for LLM calls (overrides config audit.adapter).").option("--model <name>", "LLM model override (overrides config audit.model).").option("--fail-on <level>", "Minimum finding severity that causes exit 10 (info|warning|error|critical).", "critical").option("-o, --output <file>", "Write result to a file instead of stdout.").option("--report-format <fmt>", "Alias for --format. When both are specified, --report-format takes precedence.", "text").action(async (type, opts, cmd) => {
+  program2.command("audit").description("Run LLM-based semantic audit on DSL definitions and generated outputs.").argument("[type]", "Audit type to run: render (semantic diff of generated outputs vs DSL), dsl (design coherence review), prompt (generated prompt fidelity check), extensions (unconsumed x-* property detection), or all (run all four).").option("-c, --config <path>", "Path to agent-contracts.config.yaml.").option("--team <id>", "Limit to one team (multi-team config only).").option("--format <format>", "Output format.", "text").option("--scope <entities>", "Limit audit scope to specified entities (e.g. agents:architect,implementer).").option("--dry-run", "Output the audit prompt without calling LLM.", false).option("--adapter <name>", "SDK adapter to use for LLM calls (overrides config audit.adapter).").option("--model <name>", "LLM model override (overrides config audit.model).").option("--fail-on <level>", "Minimum finding severity that causes exit 10 (info|warning|error|critical).", "critical").option("-o, --output <file>", "Write result to a file instead of stdout.").option("--report-format <fmt>", "Alias for --format. When both are specified, --report-format takes precedence.", "text").action(async (type, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     if (globalOpts.introspect) {
       const policy = deriveCommandPolicy("audit", opts);
@@ -49533,6 +49533,7 @@ var ArtifactSchema = z2.object({
   states: z2.array(z2.string()),
   required_validations: z2.array(z2.string()).default([]),
   visibility: z2.string().optional(),
+  classification: z2.string().optional(),
   guardrails: z2.array(z2.string()).optional()
 }).passthrough();
 
@@ -49737,7 +49738,7 @@ var ExecutionStepSchema = z9.object({
 var TaskSchema = z9.object({
   description: z9.string(),
   target_agent: z9.string(),
-  allowed_from_agents: z9.array(z9.string()),
+  allowed_from_agents: z9.array(z9.string()).default([]),
   workflow: z9.string(),
   input_artifacts: z9.array(z9.string()),
   invocation_handoff: z9.string(),
@@ -49810,7 +49811,8 @@ var ValidationSchema = z13.object({
   executor_type: z13.enum(["tool", "agent"]),
   executor: z13.string(),
   blocking: z13.boolean(),
-  produces_evidence: z13.string().optional()
+  produces_evidence: z13.string().optional(),
+  description: z13.string().optional()
 }).passthrough();
 
 // src/schema/workflow.ts
@@ -50194,7 +50196,8 @@ ${issues}`,
       bindings: [],
       activeGuardrailPolicy: void 0,
       paths: void 0,
-      teams: resolveTeamConfigs(config.teams, configDir)
+      teams: resolveTeamConfigs(config.teams, configDir),
+      audit: config.audit ?? void 0
     };
   }
   return {
@@ -50204,7 +50207,8 @@ ${issues}`,
     configDir,
     bindings: (config.bindings ?? []).map((b3) => resolve(configDir, b3)),
     activeGuardrailPolicy: config.active_guardrail_policy,
-    paths: config.paths
+    paths: config.paths,
+    audit: config.audit ?? void 0
   };
 }
 function resolveDslPath(dirArg, dirArgDefault, config) {
@@ -50248,7 +50252,7 @@ function deepClone(value) {
   }
   return result;
 }
-function resolveJsonPointer(root, pointer) {
+function tryResolveJsonPointer(root, pointer) {
   const path = pointer.slice(2);
   const segments = path.split("/").map(
     (s2) => s2.replace(/~1/g, "/").replace(/~0/g, "~")
@@ -50262,12 +50266,19 @@ function resolveJsonPointer(root, pointer) {
     }
     current = current[segment];
     if (current === void 0) {
-      throw new DslLoadError(
-        `Cannot resolve JSON Pointer "${pointer}": path segment "${segment}" not found`
-      );
+      return { found: false };
     }
   }
-  return current;
+  return { found: true, value: current };
+}
+function resolveJsonPointer(root, pointer) {
+  const result = tryResolveJsonPointer(root, pointer);
+  if (!result.found) {
+    throw new DslLoadError(
+      `Cannot resolve JSON Pointer "${pointer}": target not found`
+    );
+  }
+  return result.value;
 }
 function hasRefs(value) {
   if (!("$refs" in value)) return false;
@@ -50311,7 +50322,7 @@ function deepMergeRefs(a3, b3, sourcePath) {
   }
   return result;
 }
-async function loadRefsSource(refPath, baseDir, resolving, rootDoc) {
+async function loadRefsSource(refPath, baseDir, resolving) {
   const target = resolve2(baseDir, refPath);
   const s2 = await fsStat(target).catch(() => null);
   if (s2?.isDirectory()) {
@@ -50319,7 +50330,7 @@ async function loadRefsSource(refPath, baseDir, resolving, rootDoc) {
       throw new DslLoadError(`Circular $refs detected: ${target}`, target);
     }
     resolving.add(target);
-    const result = await loadDirectoryAsMap(target, resolving, rootDoc);
+    const result = await loadDirectoryAsMap(target, resolving);
     resolving.delete(target);
     return result;
   }
@@ -50337,16 +50348,16 @@ async function loadRefsSource(refPath, baseDir, resolving, rootDoc) {
       target
     );
   }
-  const resolved = await resolveRefsDeep(
+  const resolved = await assembleRefs(
     content,
     dirname2(target),
     resolving,
-    rootDoc
+    content
   );
   resolving.delete(target);
   return resolved;
 }
-async function loadDirectoryAsMap(dirPath, resolving, rootDoc) {
+async function loadDirectoryAsMap(dirPath, resolving) {
   let entries;
   try {
     entries = await readdir(dirPath);
@@ -50373,17 +50384,17 @@ async function loadDirectoryAsMap(dirPath, resolving, rootDoc) {
         filePath
       );
     }
-    const resolved = await resolveRefsDeep(
+    const resolved = await assembleRefs(
       content,
       dirPath,
       resolving,
-      rootDoc
+      content
     );
     merged = deepMergeRefs(merged, resolved, filePath);
   }
   return merged;
 }
-async function processRefs(obj, baseDir, resolving, rootDoc) {
+async function processRefs(obj, baseDir, resolving) {
   const refPaths = obj["$refs"];
   const inline = {};
   for (const [key, value] of Object.entries(obj)) {
@@ -50393,17 +50404,17 @@ async function processRefs(obj, baseDir, resolving, rootDoc) {
   }
   let merged = {};
   for (const refPath of refPaths) {
-    const loaded = await loadRefsSource(refPath, baseDir, resolving, rootDoc);
+    const loaded = await loadRefsSource(refPath, baseDir, resolving);
     merged = deepMergeRefs(merged, loaded, refPath);
   }
   merged = deepMergeRefs(merged, inline, "(inline)");
   return merged;
 }
-async function resolveRefsDeep(data, baseDir, resolving, rootDoc) {
+async function assembleRefs(data, baseDir, resolving, fileRoot) {
   if (typeof data !== "object" || data === null) return data;
   if (Array.isArray(data)) {
     return Promise.all(
-      data.map((item) => resolveRefsDeep(item, baseDir, resolving, rootDoc))
+      data.map((item) => assembleRefs(item, baseDir, resolving, fileRoot))
     );
   }
   if (isRef(data)) {
@@ -50412,13 +50423,16 @@ async function resolveRefsDeep(data, baseDir, resolving, rootDoc) {
       if (resolving.has(refValue)) {
         throw new DslLoadError(`Circular $ref detected: ${refValue}`);
       }
+      const result2 = tryResolveJsonPointer(fileRoot, refValue);
+      if (!result2.found) {
+        return data;
+      }
       resolving.add(refValue);
-      const target = resolveJsonPointer(rootDoc, refValue);
-      const resolved = await resolveRefsDeep(
-        deepClone(target),
+      const resolved = await assembleRefs(
+        deepClone(result2.value),
         baseDir,
         resolving,
-        rootDoc
+        fileRoot
       );
       resolving.delete(refValue);
       return resolved;
@@ -50442,7 +50456,7 @@ async function resolveRefsDeep(data, baseDir, resolving, rootDoc) {
         );
       }
       resolving.add(refTarget);
-      const result2 = await loadDirectoryAsMap(refTarget, resolving, rootDoc);
+      const result2 = await loadDirectoryAsMap(refTarget, resolving);
       resolving.delete(refTarget);
       return result2;
     }
@@ -50457,12 +50471,12 @@ async function resolveRefsDeep(data, baseDir, resolving, rootDoc) {
     }
     resolving.add(refTarget);
     const content = await readYaml(refTarget);
-    const fileRoot = fragment ? content : rootDoc;
-    let fileData = await resolveRefsDeep(
+    const newFileRoot = isRecord(content) ? content : fileRoot;
+    let fileData = await assembleRefs(
       content,
       dirname2(refTarget),
       resolving,
-      fileRoot
+      newFileRoot
     );
     resolving.delete(refTarget);
     if (fragment && fragment.startsWith("#/")) {
@@ -50478,11 +50492,31 @@ async function resolveRefsDeep(data, baseDir, resolving, rootDoc) {
   }
   let obj = data;
   if (hasRefs(obj)) {
-    obj = await processRefs(obj, baseDir, resolving, rootDoc);
+    obj = await processRefs(obj, baseDir, resolving);
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = await assembleRefs(value, baseDir, resolving, fileRoot);
+  }
+  return result;
+}
+function linkDocPointers(data, rootDoc) {
+  if (typeof data !== "object" || data === null) return data;
+  if (Array.isArray(data)) {
+    return data.map((item) => linkDocPointers(item, rootDoc));
   }
+  if (isRef(data)) {
+    const refValue = data.$ref;
+    if (refValue.startsWith("#/")) {
+      const target = resolveJsonPointer(rootDoc, refValue);
+      return linkDocPointers(deepClone(target), rootDoc);
+    }
+    return data;
+  }
+  const obj = data;
   const result = {};
   for (const [key, value] of Object.entries(obj)) {
-    result[key] = await resolveRefsDeep(value, baseDir, resolving, rootDoc);
+    result[key] = linkDocPointers(value, rootDoc);
   }
   return result;
 }
@@ -50513,13 +50547,16 @@ async function loadDsl(entryPath) {
   const data = raw;
   checkVersion(data, absPath);
   const baseDir = dirname2(absPath);
-  const resolving = /* @__PURE__ */ new Set([absPath]);
-  const resolved = await resolveRefsDeep(
+  const assembled = await assembleRefs(
     data,
     baseDir,
-    resolving,
+    /* @__PURE__ */ new Set([absPath]),
     data
   );
+  const resolved = linkDocPointers(
+    assembled,
+    assembled
+  );
   return { data: resolved, filePath: absPath };
 }
 
@@ -52316,6 +52353,7 @@ var taskAgentBindingRule = {
     }
     for (const [taskId, task] of Object.entries(dsl.tasks)) {
       for (const fromAgentId of task.allowed_from_agents) {
+        if (fromAgentId === task.target_agent) continue;
         const fromAgent = dsl.agents[fromAgentId];
         if (fromAgent && !fromAgent.can_invoke_agents.includes(task.target_agent)) {
           diagnostics.push({
@@ -52890,6 +52928,176 @@ var validationExecutorNoContextRule = {
   }
 };
 
+// src/linter/rules/extension-consumption.ts
+function isRecord5(v2) {
+  return typeof v2 === "object" && v2 !== null && !Array.isArray(v2);
+}
+function collectXUsages(dsl) {
+  const usages = /* @__PURE__ */ new Map();
+  function record(key, path, nodeType) {
+    let list = usages.get(key);
+    if (!list) {
+      list = [];
+      usages.set(key, list);
+    }
+    list.push({ path, nodeType });
+  }
+  function walkObj(obj, path, nodeType) {
+    for (const key of Object.keys(obj)) {
+      if (key.startsWith("x-") && key !== "x-extensions" && key !== "x-extensions-strict") {
+        record(key, path ? `${path}.${key}` : key, nodeType);
+      }
+    }
+  }
+  walkObj(dsl, "", "root");
+  if (isRecord5(dsl.system)) {
+    walkObj(dsl.system, "system", "system");
+  }
+  for (const [id, agent] of Object.entries(dsl.agents)) {
+    const agentObj = agent;
+    walkObj(agentObj, `agents.${id}`, "agent");
+    if (Array.isArray(agentObj["rules"])) {
+      for (let i3 = 0; i3 < agentObj["rules"].length; i3++) {
+        const r3 = agentObj["rules"][i3];
+        if (isRecord5(r3)) walkObj(r3, `agents.${id}.rules[${i3}]`, "rule");
+      }
+    }
+    if (Array.isArray(agentObj["escalation_criteria"])) {
+      for (let i3 = 0; i3 < agentObj["escalation_criteria"].length; i3++) {
+        const e3 = agentObj["escalation_criteria"][i3];
+        if (isRecord5(e3)) walkObj(e3, `agents.${id}.escalation_criteria[${i3}]`, "escalation_criterion");
+      }
+    }
+    if (Array.isArray(agentObj["prerequisites"])) {
+      for (let i3 = 0; i3 < agentObj["prerequisites"].length; i3++) {
+        const p2 = agentObj["prerequisites"][i3];
+        if (isRecord5(p2)) walkObj(p2, `agents.${id}.prerequisites[${i3}]`, "prerequisite");
+      }
+    }
+  }
+  for (const [id, task] of Object.entries(dsl.tasks)) {
+    const taskObj = task;
+    walkObj(taskObj, `tasks.${id}`, "task");
+    if (Array.isArray(taskObj["execution_steps"])) {
+      for (let i3 = 0; i3 < taskObj["execution_steps"].length; i3++) {
+        const s2 = taskObj["execution_steps"][i3];
+        if (isRecord5(s2)) walkObj(s2, `tasks.${id}.execution_steps[${i3}]`, "execution_step");
+      }
+    }
+  }
+  for (const [id, art] of Object.entries(dsl.artifacts)) {
+    walkObj(art, `artifacts.${id}`, "artifact");
+  }
+  for (const [id, tool] of Object.entries(dsl.tools)) {
+    const toolObj = tool;
+    walkObj(toolObj, `tools.${id}`, "tool");
+    if (Array.isArray(toolObj["commands"])) {
+      for (let i3 = 0; i3 < toolObj["commands"].length; i3++) {
+        const c2 = toolObj["commands"][i3];
+        if (isRecord5(c2)) walkObj(c2, `tools.${id}.commands[${i3}]`, "tool_command");
+      }
+    }
+  }
+  for (const [id, val] of Object.entries(dsl.validations)) {
+    walkObj(val, `validations.${id}`, "validation");
+  }
+  for (const [id, ht] of Object.entries(dsl.handoff_types)) {
+    walkObj(ht, `handoff_types.${id}`, "handoff_type");
+  }
+  for (const [id, wf] of Object.entries(dsl.workflow)) {
+    const wfObj = wf;
+    walkObj(wfObj, `workflow.${id}`, "workflow");
+    if (Array.isArray(wfObj["steps"])) {
+      for (let i3 = 0; i3 < wfObj["steps"].length; i3++) {
+        const s2 = wfObj["steps"][i3];
+        if (isRecord5(s2)) walkObj(s2, `workflow.${id}.steps[${i3}]`, "workflow_step");
+      }
+    }
+  }
+  for (const [id, pol] of Object.entries(dsl.policies)) {
+    walkObj(pol, `policies.${id}`, "policy");
+  }
+  for (const [id, gr] of Object.entries(dsl.guardrails)) {
+    walkObj(gr, `guardrails.${id}`, "guardrail");
+  }
+  for (const [id, gp] of Object.entries(dsl.guardrail_policies)) {
+    walkObj(gp, `guardrail_policies.${id}`, "guardrail_policy");
+  }
+  return usages;
+}
+var extensionDeclaredButUnusedRule = {
+  id: "extension-declared-unused",
+  description: "Declared extension in `extensions` is never used on any entity",
+  run(dsl) {
+    const diagnostics = [];
+    const declaredKeys = Object.keys(dsl.extensions);
+    if (declaredKeys.length === 0) return diagnostics;
+    const usages = collectXUsages(dsl);
+    for (const key of declaredKeys) {
+      if (!usages.has(key)) {
+        diagnostics.push({
+          ruleId: "extension-declared-unused",
+          severity: "warning",
+          path: `extensions.${key}`,
+          message: `Extension "${key}" is declared but never used on any entity`
+        });
+      }
+    }
+    return diagnostics;
+  }
+};
+var extensionScopeMismatchRule = {
+  id: "extension-scope-mismatch",
+  description: "Extension used on a node type outside its declared scope",
+  run(dsl) {
+    const diagnostics = [];
+    const extensions = dsl.extensions;
+    if (Object.keys(extensions).length === 0) return diagnostics;
+    const usages = collectXUsages(dsl);
+    for (const [key, decl] of Object.entries(extensions)) {
+      const scope = decl.scope;
+      if (!scope || scope.length === 0) continue;
+      const scopeSet = new Set(scope);
+      const keyUsages = usages.get(key);
+      if (!keyUsages) continue;
+      for (const usage of keyUsages) {
+        if (!scopeSet.has(usage.nodeType)) {
+          diagnostics.push({
+            ruleId: "extension-scope-mismatch",
+            severity: "warning",
+            path: usage.path,
+            message: `Extension "${key}" is used on ${usage.nodeType} but declared scope is [${scope.join(", ")}]`
+          });
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+var extensionUndeclaredUsageRule = {
+  id: "extension-undeclared-usage",
+  description: "Entity uses x-* property that is not declared in extensions (when extensions section exists)",
+  run(dsl) {
+    const diagnostics = [];
+    const extensions = dsl.extensions;
+    if (Object.keys(extensions).length === 0) return diagnostics;
+    const declaredKeys = new Set(Object.keys(extensions));
+    const usages = collectXUsages(dsl);
+    for (const [key, keyUsages] of usages) {
+      if (declaredKeys.has(key)) continue;
+      for (const usage of keyUsages) {
+        diagnostics.push({
+          ruleId: "extension-undeclared-usage",
+          severity: "info",
+          path: usage.path,
+          message: `Extension "${key}" is used but not declared in extensions \u2014 consider adding a declaration`
+        });
+      }
+    }
+    return diagnostics;
+  }
+};
+
 // src/linter/linter.ts
 var builtinRules = [
   validationCoverageRule,
@@ -52906,7 +53114,10 @@ var builtinRules = [
   entityGuardrailUndefinedRule,
   entityNoGuardrailsRule,
   guardrailOrphanedRule,
-  validationExecutorNoContextRule
+  validationExecutorNoContextRule,
+  extensionDeclaredButUnusedRule,
+  extensionScopeMismatchRule,
+  extensionUndeclaredUsageRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -55839,6 +56050,121 @@ function formatDslOverview(dsl) {
     `- Validations: ${Object.keys(dsl.validations).join(", ")}`
   ].join("\n");
 }
+function isRecord6(v2) {
+  return typeof v2 === "object" && v2 !== null && !Array.isArray(v2);
+}
+function collectAllXUsages(dsl) {
+  const entries = [];
+  function walk2(obj, path, nodeType) {
+    for (const key of Object.keys(obj)) {
+      if (key.startsWith("x-") && key !== "x-extensions" && key !== "x-extensions-strict") {
+        entries.push({ path: path ? `${path}.${key}` : key, nodeType, key });
+      }
+    }
+  }
+  walk2(dsl, "", "root");
+  if (isRecord6(dsl.system)) walk2(dsl.system, "system", "system");
+  for (const [id, a3] of Object.entries(dsl.agents))
+    walk2(a3, `agents.${id}`, "agent");
+  for (const [id, t3] of Object.entries(dsl.tasks))
+    walk2(t3, `tasks.${id}`, "task");
+  for (const [id, a3] of Object.entries(dsl.artifacts))
+    walk2(a3, `artifacts.${id}`, "artifact");
+  for (const [id, t3] of Object.entries(dsl.tools))
+    walk2(t3, `tools.${id}`, "tool");
+  for (const [id, v2] of Object.entries(dsl.validations))
+    walk2(v2, `validations.${id}`, "validation");
+  for (const [id, h2] of Object.entries(dsl.handoff_types))
+    walk2(h2, `handoff_types.${id}`, "handoff_type");
+  for (const [id, w2] of Object.entries(dsl.workflow))
+    walk2(w2, `workflow.${id}`, "workflow");
+  for (const [id, p2] of Object.entries(dsl.policies))
+    walk2(p2, `policies.${id}`, "policy");
+  for (const [id, g2] of Object.entries(dsl.guardrails))
+    walk2(g2, `guardrails.${id}`, "guardrail");
+  for (const [id, gp] of Object.entries(dsl.guardrail_policies))
+    walk2(gp, `guardrail_policies.${id}`, "guardrail_policy");
+  return entries;
+}
+function extractTemplateXReferences(config) {
+  const refs = [];
+  try {
+    const { readFileSync: readFileSync3 } = __require("fs");
+    for (const target of config.renders) {
+      try {
+        const content = readFileSync3(target.template, "utf8");
+        const matches = content.matchAll(/\{\{[^}]*?(x-[\w-]+)[^}]*?\}\}/g);
+        for (const m2 of matches) refs.push(m2[1]);
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return [...new Set(refs)];
+}
+function buildExtensionsContext(dsl, config) {
+  const parts = [];
+  parts.push("## Extension Declarations");
+  const declaredKeys = Object.keys(dsl.extensions);
+  if (declaredKeys.length === 0) {
+    parts.push("(No extensions declared in `extensions` section)");
+  } else {
+    parts.push("```yaml\n" + yaml.stringify({ extensions: dsl.extensions }) + "```");
+  }
+  parts.push("## x-* Usage Map");
+  const usages = collectAllXUsages(dsl);
+  if (usages.length === 0) {
+    parts.push("(No x-* properties found on any entity)");
+  } else {
+    const byKey = /* @__PURE__ */ new Map();
+    for (const u2 of usages) {
+      let list = byKey.get(u2.key);
+      if (!list) {
+        list = [];
+        byKey.set(u2.key, list);
+      }
+      list.push(u2);
+    }
+    const lines = ["| Extension | Node Type | Path |", "|-----------|-----------|------|"];
+    for (const [key, entries] of byKey) {
+      for (const e3 of entries) {
+        lines.push(`| ${key} | ${e3.nodeType} | ${e3.path} |`);
+      }
+    }
+    parts.push(lines.join("\n"));
+  }
+  parts.push("## Template x-* References");
+  const templateRefs = extractTemplateXReferences(config);
+  if (templateRefs.length === 0) {
+    parts.push("(No x-* references found in render templates, or no templates configured)");
+  } else {
+    parts.push(templateRefs.map((r3) => `- ${r3}`).join("\n"));
+  }
+  parts.push("## Runtime Codegen Fixed Fields");
+  parts.push(
+    "The agent-contracts-runtime codegen templates emit only these fixed fields (x-* properties are not included in generated TypeScript contracts):\n- **AgentContract**: id, role_name, purpose, mode, dispatch_only, can_read_artifacts, can_write_artifacts, can_execute_tools, can_invoke_agents, can_return_handoffs, responsibilities, constraints, rules, escalation_criteria\n- **TaskContract**: id, description, target_agent, allowed_from_agents, workflow, invocation_handoff, result_handoff, input_artifacts, responsibilities, completion_criteria, optional\n- **WorkflowContract**: id, description, trigger, entry_conditions, steps"
+  );
+  const declaredSet = new Set(declaredKeys);
+  const usedKeys = new Set(usages.map((u2) => u2.key));
+  const templateRefSet = new Set(templateRefs);
+  parts.push("## Gap Summary");
+  const gaps = [];
+  for (const key of declaredKeys) {
+    if (!usedKeys.has(key)) gaps.push(`- **${key}**: declared but never populated on any entity`);
+  }
+  for (const key of usedKeys) {
+    if (declaredKeys.length > 0 && !declaredSet.has(key))
+      gaps.push(`- **${key}**: used on entities but not declared in extensions`);
+    if (!templateRefSet.has(key))
+      gaps.push(`- **${key}**: populated on entities but not referenced in any render template`);
+  }
+  if (gaps.length === 0) {
+    parts.push("(No obvious gaps detected by static analysis)");
+  } else {
+    parts.push(gaps.join("\n"));
+  }
+  return parts.join("\n\n");
+}
 async function buildAuditContext(auditType, dsl, config) {
   const sections = [];
   sections.push(formatDslOverview(dsl));
@@ -55859,6 +56185,9 @@ ${entry.content}`);
       sections.push("(No rendered agent prompt files found. Run `agent-contracts render` first.)");
     }
   }
+  if (auditType === "extensions") {
+    sections.push(buildExtensionsContext(dsl, config));
+  }
   if (auditType === "dsl") {
     sections.push("## Agent Definitions");
     for (const [agentId, agentDef] of Object.entries(dsl.agents)) {
@@ -55925,7 +56254,8 @@ var dslAuditor = {
     "Prioritize improvement recommendations (P0/P1/P2) with concrete fix proposals",
     "Report score-based improvement areas as audit recommendations (read-only; consumes dsl-score-report produced by dsl-designer)",
     "Review DSL design for semantic coherence (role overlap, scope breadth, gate placement)",
-    "Verify generated prompts faithfully represent DSL intent (no hallucinated permissions)"
+    "Verify generated prompts faithfully represent DSL intent (no hallucinated permissions)",
+    "Audit x-* extension consumption across render templates and runtime codegen paths"
   ],
   constraints: [
     "Do not directly modify DSL definitions (read-only analysis)",
@@ -56186,12 +56516,14 @@ var auditSemanticDesign = {
     "Verify handoff schemas carry sufficient fields for task completion_criteria",
     "Check workflow gates are placed effectively",
     "Detect guardrails declared but absent from execution path",
-    "Check semantic validations are distributed across phases"
+    "Check semantic validations are distributed across phases",
+    "Detect custom x- properties that replicate standard DSL control-flow features (gate, decision, entry_conditions)"
   ],
   completion_criteria: [
     "All agents reviewed for scope and overlap",
     "Workflow gate placement analyzed",
     "Guardrail enforcement path verified",
+    "Custom x- property misuse flagged",
     "Findings classified with severity and category"
   ],
   optional: false
@@ -56224,6 +56556,35 @@ var auditGeneratedPrompts = {
   ],
   optional: false
 };
+var auditExtensionConsumption = {
+  id: "audit-extension-consumption",
+  description: "Audit declared x-* extensions for consumption gaps across render and runtime paths",
+  target_agent: "dsl-auditor",
+  allowed_from_agents: [
+    "dsl-auditor"
+  ],
+  workflow: "dsl-audit",
+  invocation_handoff: "dsl-task-request",
+  result_handoff: "dsl-audit-result",
+  input_artifacts: [
+    "dsl-source",
+    "dsl-generated-output"
+  ],
+  responsibilities: [
+    "Cross-check extensions declarations against entity x-* usage",
+    "Identify x-* properties populated in DSL but not consumed by any render template",
+    "Detect semantic overlap between x-* extensions and standard DSL features",
+    "Report runtime codegen reachability for each extension",
+    "Distinguish intentional metadata-only extensions from consumption gaps"
+  ],
+  completion_criteria: [
+    "All declared extensions checked for template and runtime consumption",
+    "Unused extensions flagged with suggested action (remove, migrate to standard, or add template support)",
+    "Runtime-unreachable extensions documented with explanation",
+    "Findings classified with severity and category"
+  ],
+  optional: false
+};
 var taskRegistry = {
   "update-dsl-definitions": updateDslDefinitions,
   "update-dsl-binding": updateDslBinding,
@@ -56231,7 +56592,8 @@ var taskRegistry = {
   "check-dsl-score": checkDslScore,
   "audit-dsl-completeness": auditDslCompleteness,
   "audit-semantic-design": auditSemanticDesign,
-  "audit-generated-prompts": auditGeneratedPrompts
+  "audit-generated-prompts": auditGeneratedPrompts,
+  "audit-extension-consumption": auditExtensionConsumption
 };
 
 // src/generated/dsl-base/handoffs.ts
@@ -56253,8 +56615,44 @@ var DslTaskResultSchema = z20.object({
   score_dimensions: z20.record(z20.string(), z20.unknown()).optional(),
   notes: z20.string().optional()
 });
+var AuditResultSchema = z20.object({
+  summary: z20.string(),
+  riskLevel: z20.enum(["low", "medium", "high", "critical"]),
+  findings: z20.array(z20.object({
+    id: z20.string().optional(),
+    severity: z20.enum(["info", "warning", "error", "critical"]),
+    category: z20.string(),
+    target: z20.string().optional(),
+    location: z20.string().optional(),
+    message: z20.string(),
+    recommendation: z20.string().optional(),
+    confidence: z20.number().optional(),
+    evidence: z20.array(z20.object({
+      kind: z20.enum(["file", "command", "schema", "diff", "stdout", "stderr", "text"]),
+      target: z20.string().optional(),
+      location: z20.string().optional(),
+      excerpt: z20.string().optional()
+    })).optional(),
+    details: z20.record(z20.string(), z20.unknown()).optional()
+  })),
+  recommendedActions: z20.array(z20.object({
+    kind: z20.enum(["run_command", "edit_file", "review", "confirm", "block", "ignore"]),
+    title: z20.string(),
+    command: z20.string().optional(),
+    target: z20.string().optional(),
+    rationale: z20.string().optional()
+  })).optional(),
+  metadata: z20.object({
+    tool: z20.string().optional(),
+    command: z20.string().optional(),
+    version: z20.string().optional(),
+    generatedAt: z20.string().optional(),
+    adapter: z20.string().optional(),
+    model: z20.string().optional()
+  }).optional()
+});
 var DslAuditResultSchema = z20.object({
-  audit_type: z20.enum(["completeness", "semantic", "prompt"]),
+  audit_type: z20.enum(["completeness", "semantic", "prompt", "extensions"]),
   total_dimensions: z20.number(),
   pass_count: z20.number(),
   miss_count: z20.number(),
@@ -56278,6 +56676,7 @@ var DslAuditResultSchema = z20.object({
 var handoffSchemas = {
   "dsl-task-request": DslTaskRequestSchema,
   "dsl-task-result": DslTaskResultSchema,
+  "audit-result": AuditResultSchema,
   "dsl-audit-result": DslAuditResultSchema
 };
 
@@ -56330,7 +56729,8 @@ async function createAdapter(runtimePkg, name, config) {
 var AUDIT_TYPE_TO_TASK = {
   render: "audit-dsl-completeness",
   dsl: "audit-semantic-design",
-  prompt: "audit-generated-prompts"
+  prompt: "audit-generated-prompts",
+  extensions: "audit-extension-consumption"
 };
 async function runAudit(dsl, config, auditConfig, options) {
   const taskId = AUDIT_TYPE_TO_TASK[options.auditType];
@@ -56384,7 +56784,7 @@ async function runAudit(dsl, config, auditConfig, options) {
   };
 }
 async function runAllAudits(dsl, config, auditConfig, options) {
-  const types = ["render", "dsl", "prompt"];
+  const types = ["render", "dsl", "prompt", "extensions"];
   const results = [];
   for (const auditType of types) {
     results.push(await runAudit(dsl, config, auditConfig, { ...options, auditType }));
@@ -57092,7 +57492,7 @@ ${issues}
     process.exit(1);
   }
 };
-var AUDIT_TYPES = ["render", "dsl", "prompt", "all"];
+var AUDIT_TYPES = ["render", "dsl", "prompt", "extensions", "all"];
 function parseAuditConfig(configObj) {
   if (!configObj) return {};
   const audit = configObj;