agent-contracts 0.12.3 → 0.13.0

package/README.md

@@ -332,7 +332,7 @@ Design regressions become testable.
 * **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
+* **`extensions` declarations** with scope, schema validation, and strict enforcement for custom `x-*` fields
 * **`resolve --expand-defaults`** to materialize all Zod schema defaults in output
 * **DSL completeness scoring** with 7 dimensions, text/JSON output, and `--threshold` CI gate
 * **JSON Schema for editor support and external tooling**
@@ -373,15 +373,20 @@ guardrail_policies: {}
 components:
   schemas: {}
 
-# Optional: declare project-specific x-* extensions
-x-extensions:
+extensions:
   x-flags:
     type: array
     items: string
     description: "CLI flags for tool commands"
-  x-check-script:
+  x-path-hint:
     type: string
-    description: "Path to hook check script"
+    description: "Filesystem path hint"
+    scope: [artifact]
+    schema:
+      type: string
+      minLength: 1
+    required: true
+extensions_strict: false
 ````
 
 This makes definitions easy to merge, extend, and reference by stable identifiers.
@@ -612,22 +617,53 @@ tasks:
 `x-` prefixed custom properties work at any nesting level — including inside
 `execution_steps`, `rules`, `workflow.steps`, and other nested objects.
 
-### `x-extensions` declarations
+### Extension declarations
 
-Projects can optionally declare their custom `x-*` extension fields in the DSL using `x-extensions`. This makes extensions discoverable and self-documenting:
+Projects can declare their custom `x-*` extension fields in the DSL using `extensions`. This makes extensions discoverable, self-documenting, and — optionally — machine-validated:
 
 ````yaml
-x-extensions:
+extensions:
   x-flags:
     type: array
     items: string
     description: "CLI flags for tool commands"
-  x-check-script:
+  x-path-hint:
     type: string
-    description: "Path to hook check script"
+    description: "Filesystem path hint"
+    scope: [artifact]
+    schema:
+      type: string
+      minLength: 1
+    required: true
+
+extensions_strict: true  # undeclared x-* properties become errors
 ````
 
-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.
+Each key must start with `x-` (validated at schema level). The declaration supports:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | `string` | *(required)* | Informational type descriptor |
+| `items` | `string` | — | Item type (for array-typed extensions) |
+| `description` | `string` | — | Human-readable description |
+| `scope` | `string[]` | all node types | Restricts which DSL node types this extension may appear on |
+| `schema` | `object` | — | JSON Schema to validate the extension value |
+| `required` | `boolean` | `false` | Whether the extension must be present on every in-scope entity |
+
+**Scope values**: `root`, `system`, `agent`, `task`, `execution_step`, `artifact`, `tool`, `tool_command`, `validation`, `handoff_type`, `workflow`, `workflow_step`, `policy`, `guardrail`, `guardrail_policy`, `rule`, `escalation_criterion`, `prerequisite`
+
+**`extensions_strict`**: When `true`, any `x-*` property not declared in `extensions` is an error. When `false` (default), undeclared extensions produce a warning.
+
+**Diagnostics**:
+
+| Code | Severity | Trigger |
+|------|----------|---------|
+| `extension-scope-mismatch` | error | Extension used on a node type outside its declared `scope` |
+| `extension-schema-violation` | error | Extension value fails the declared JSON Schema |
+| `extension-required-missing` | error | Required extension missing on an in-scope entity |
+| `undeclared-extension` | warning/error | Extension not declared in `extensions` (error when `extensions_strict: true`) |
+
+> **Backward compatibility:** `x-extensions` and `x-extensions-strict` are still accepted as deprecated aliases. They produce a `deprecated-property` warning and are normalized to `extensions` / `extensions_strict` during validation.
 
 ---
 
@@ -999,10 +1035,10 @@ Each `context` type provides a different rendering scope:
 | Context | Scope | Output | Key variables |
 |---------|-------|--------|---------------|
 | `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` |
-| `tool` | Per tool | `{tool.id}` in output path | `tool`, `invokableAgents`, `inputArtifactDetails`, `outputArtifactDetails`, `dsl` |
+| `agent` | Per agent | `{agent.id}` in output path | `agent`, `receivableTasks`, `delegatableTasks`, `relatedArtifacts`, `relatedTools`, `relatedHandoffTypes`, `mergedBehavior`, `relatedGuardrails`, `relatedValidations`, `dsl` |
+| `task` | Per task | `{task.id}` in output path | `task`, `targetAgent`, `relatedGuardrails`, `relatedValidations`, `dsl` |
+| `artifact` | Per artifact | `{artifact.id}` in output path | `artifact`, `relatedTools`, `relatedValidations`, `relatedGuardrails`, `producerAgents`, `consumerAgents`, `editorAgents`, `createdInWorkflows`, `dsl` |
+| `tool` | Per tool | `{tool.id}` in output path | `tool`, `invokableAgents`, `inputArtifactDetails`, `outputArtifactDetails`, `relatedGuardrails`, `relatedValidations`, `dsl` |
 | `validation` | Per validation | `{validation.id}` in output path | `validation`, `dsl` |
 | `handoff_type` | Per handoff type | `{handoff_type.id}` in output path | `handoff_type`, `relatedTasks`, `dsl` |
 | `workflow` | Per workflow phase | `{workflow.id}` in output path | `workflow`, `relatedAgents`, `relatedTasks`, `relatedTools`, `relatedArtifacts`, `relatedValidations`, `dsl` |
@@ -1027,6 +1063,23 @@ Each `context` type provides a different rendering scope:
 * `producerAgents` / `consumerAgents` / `editorAgents` — resolved agent records
 * `createdInWorkflows` — workflow phases where this artifact is written
 
+**`agent` context** provides merged behavioral specs and cross-references:
+
+* `relatedGuardrails` — guardrails bound via `agent.guardrails[]` or guardrail `scope.agents[]`, merged and deduplicated
+* `relatedValidations` — validations from `agent.can_perform_validations`, resolved into full entries (kind, target_artifact, executor_type, blocking)
+
+**`task` context** provides execution details:
+
+* `relatedGuardrails` — guardrails bound via `task.guardrails[]` or guardrail `scope.tasks[]`
+* `relatedValidations` — validations from `task.validations[]`, resolved into full entries
+
+**`tool` context** provides invocation and artifact details:
+
+* `relatedGuardrails` — guardrails bound via `tool.guardrails[]` or guardrail `scope.tools[]`
+* `relatedValidations` — validations where `executor_type` is `"tool"` and `executor` matches this tool ID
+* `invokableAgents` — agents listed in `invokable_by`
+* `inputArtifactDetails` / `outputArtifactDetails` — resolved artifact records
+
 **`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`
@@ -1039,11 +1092,6 @@ These fields are only populated when the config specifies `bindings` and `active
 * `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`
-* `inputArtifactDetails` / `outputArtifactDetails` — resolved artifact records
-
 ### Handlebars helpers
 
 Templates can use these built-in helpers:
@@ -1251,6 +1299,8 @@ Checks:
 * handoff schema shape (meta-validated as valid JSON Schema via ajv)
 * `allOf` composition in handoff schemas
 * invalid custom properties without `x-` prefix (checked at all nesting levels)
+* `extensions` declaration validation — scope, schema, required, and undeclared checks
+* `extensions_strict` enforcement — reject undeclared `x-*` properties when enabled
 
 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.
 
@@ -1306,6 +1356,7 @@ Checks:
 * 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)
+* validation executor context wiring — warns when a validation's executor (agent or tool) exists in the DSL but the validation is not surfaced in the executor's prompt context
 * 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