agent-contracts 0.12.4 → 0.14.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.
 
 ---
 
@@ -1130,7 +1166,7 @@ guardrail_policies:
 
 ### Software bindings
 
-Bindings define software-specific check implementations:
+Bindings define software-specific check implementations, output generation, and rendering:
 
 ````yaml
 # bindings/cursor.yaml
@@ -1152,6 +1188,19 @@ outputs:
     mode: write
     executable: true
     template: ./templates/cursor-hook-wrapper.sh.hbs
+
+renders:
+  - context: agent
+    output: "{cursor_root}/agent-team/{agent.id}.md"
+    template: ./templates/agent-prompt.md.hbs
+    exclude:
+      - architect
+  - context: system
+    output: "{cursor_root}/rules/agent-team.mdc"
+    inline_template: |
+      {{#each agents}}
+      - {{@key}}: {{this.role_name}}
+      {{/each}}
 ````
 
 ### Binding inheritance
@@ -1208,6 +1257,7 @@ Merge behavior:
 | `software` | Project wins |
 | `guardrail_impl` | Map merge by guardrail ID (new IDs added; same ID deep-merged) |
 | `outputs` | Map merge by output ID (project overrides base) |
+| `renders` | Array concatenation (base renders + project renders) |
 | `reporting` | Deep merge (project fields override base) |
 | passthrough fields | Project wins |
 
@@ -1239,6 +1289,62 @@ paths:
   git_hooks_root: scripts/git-hooks
 ````
 
+### Binding template context
+
+Both `outputs` and `renders` templates have access to the full binding generation context:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `system` | `{ id, name }` | System metadata |
+| `guardrails` | `Record<string, Guardrail>` | All guardrail definitions |
+| `policy` | `GuardrailPolicy` | Active guardrail policy |
+| `binding` | `SoftwareBinding` | Current binding |
+| `all_bindings` | `Record<string, SoftwareBinding>` | All loaded bindings |
+| `vars` | `Record<string, string>` | Variables from `config.vars` |
+| `paths` | `Record<string, string>` | Path variables from `config.paths` |
+| `reporting` | `{ commands, fail_open, timeout_ms } \| null` | Reporting config |
+| `resolved_checks` | `ResolvedCheck[]` | Resolved guardrail checks |
+| `tasks` | `Record<string, Task>` | All DSL tasks |
+| `artifacts` | `Record<string, Artifact>` | All DSL artifacts |
+| `agents` | `Record<string, Agent>` | All DSL agents |
+| `handoff_types` | `Record<string, HandoffType>` | All DSL handoff types |
+| `workflow` | `Record<string, Workflow>` | All DSL workflows |
+
+DSL entities include passthrough fields (`x-*` extensions), so custom metadata defined in the DSL is accessible in templates (e.g., `{{agents.implementer.x-team}}`).
+
+### Binding renders
+
+Binding `renders` provide entity-iteration rendering with full DSL context — the same capability as config-level `renders`, but defined within binding YAML files.
+
+Each render target specifies a `context` type and an `output` path pattern:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `context` | yes | Entity type: `agent`, `task`, `artifact`, `tool`, `workflow`, `system`, etc. |
+| `output` | yes | Output path with `{entity.id}` and `{paths_var}` expansion |
+| `template` | one of | Path to external `.hbs` template file |
+| `inline_template` | one of | Inline Handlebars template string |
+| `include` | no | Only render these entity IDs |
+| `exclude` | no | Skip these entity IDs |
+| `skip_empty` | no | Delete target if rendered output is empty |
+| `executable` | no | Set file permissions to 0755 |
+
+For non-`system` contexts, one file is generated per entity (filtered by `include`/`exclude`). The output path supports two types of variable expansion:
+
+- `{agent.id}`, `{task.id}`, etc. — replaced with the current entity ID
+- `{cursor_root}`, `{observability_root}`, etc. — replaced from `config.paths`
+
+**When to use binding renders vs config renders vs binding outputs:**
+
+| Use case | Recommended |
+|----------|-------------|
+| Generate per-entity files (agent prompts, workflow docs) | Binding `renders` or config `renders` |
+| Generate guardrail/policy runtime artifacts | Binding `outputs` |
+| Generate files using DSL data + guardrail data | Binding `renders` (has both) |
+| Simple config without bindings | Config `renders` |
+
+Config `renders` remains supported and is not deprecated. Binding `renders` offers the advantage of co-locating templates with their binding definition and having access to the full binding context (`vars`, `paths`, `resolved_checks`, etc.) in addition to DSL entities.
+
 ### Generate command
 
 ````bash
@@ -1263,6 +1369,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.