agent-contracts 0.9.0 → 0.11.0

package/README.md

@@ -228,10 +228,39 @@ 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`
 
-### Handoff
+### Guardrail
 
-A **Handoff** is a runtime delegation instance.
-The YAML defines the allowed handoff types and constraints; concrete handoffs are created at runtime.
+A **Guardrail** declares a cross-cutting constraint:
+
+* description — what is protected
+* scope — which DSL entities it applies to (agents, tasks, tools, artifacts, workflows)
+* rationale — why the constraint exists
+* tags — classification for filtering
+* exemptions — glob patterns or entity IDs exempt from the guardrail
+
+### Guardrail Policy
+
+A **Guardrail Policy** defines enforcement strategy for guardrails:
+
+* rules — array of enforcement rules mapping guardrails to actions
+* Each rule specifies: severity (`critical`/`mandatory`/`warning`/`info`), action (`block`/`warn`/`shadow`/`info`), override permissions
+
+### Handoff Type
+
+A **Handoff Type** defines the schema for inter-agent messages:
+
+* `schema` — a JSON Schema object describing the full message structure
+* `description`
+* `example`
+* `version`
+
+Schemas can use `allOf` with `$ref: "#/components/schemas/..."` to compose shared fields (e.g., common envelope) with type-specific properties.
+
+### Components
+
+**Components** provide reusable definitions, following the OpenAPI pattern:
+
+* `components.schemas` — named JSON Schema fragments that can be referenced from anywhere via `$ref: "#/components/schemas/<name>"`
 
 ---
 
@@ -265,12 +294,17 @@ Design regressions become testable.
 * **Static schema validation**
 * **Reference integrity checks**
 * **Semantic linting**
-* **Structured handoff definitions**
+* **Structured handoff definitions** with formal JSON Schema and `allOf` composition
+* **Reusable schema components** via `components.schemas` and JSON Pointer `$ref`
 * **Artifact ownership and lifecycle modeling**
 * **Config-driven prompt rendering**
 * **Variable substitution** via `${vars.xxx}` in DSL values
 * **Inheritance with merge operators via `extends`**
-* **Flexible file splitting** via `$ref` (replacement) and `$refs` (import + deep-merge)
+* **Guardrail definitions** for cross-cutting process constraints
+* **Guardrail policies** with configurable enforcement (block/warn/shadow/info)
+* **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)
 * **JSON Schema for editor support and external tooling**
 * **CI-friendly workflow checks**
 
@@ -304,6 +338,10 @@ validations: {}
 handoff_types: {}
 workflow: {}
 policies: {}
+guardrails: {}
+guardrail_policies: {}
+components:
+  schemas: {}
 ````
 
 This makes definitions easy to merge, extend, and reference by stable identifiers.
@@ -421,8 +459,44 @@ Overlapping map keys are deep-merged recursively. Conflicting leaf values (scala
 | Directive | Type   | Behavior                                                 |
 | --------- | ------ | -------------------------------------------------------- |
 | `$ref`    | string | Replace the object at that position with file contents   |
+| `$ref` (`#/...`) | string | Replace with the value at the given JSON Pointer path within the document |
 | `$refs`   | array  | Import files and deep-merge into the containing map      |
 
+### JSON Pointer `$ref`
+
+`$ref` also supports **in-document references** using JSON Pointer syntax (RFC 6901).
+When the value starts with `#/`, it resolves against the root document instead of the file system.
+
+````yaml
+components:
+  schemas:
+    handoff-common:
+      type: object
+      required: [from_agent, to_agent]
+      properties:
+        from_agent: { type: string }
+        to_agent: { type: string }
+
+handoff_types:
+  task-delegation:
+    version: 1
+    schema:
+      allOf:
+        - $ref: "#/components/schemas/handoff-common"
+        - type: object
+          required: [payload]
+          properties:
+            payload:
+              type: object
+              required: [objective]
+              properties:
+                objective: { type: string }
+````
+
+This is particularly useful for sharing common schema fragments across multiple `handoff_types` entries via `components.schemas`.
+
+JSON Pointer references are resolved in the same processing phase as file `$ref` — before Zod validation. They can be used anywhere in the document, not just within `handoff_types`.
+
 ---
 
 ## Example: Agent definition
@@ -545,6 +619,80 @@ workflow:
 
 ---
 
+## Example: Handoff type definition
+
+Handoff types define the schema for inter-agent messages using JSON Schema.
+
+````yaml
+handoff_types:
+  task-delegation:
+    version: 1
+    description: "Delegate a task to a sub-agent"
+    schema:
+      type: object
+      required: [task, objective]
+      properties:
+        task: { type: string }
+        objective: { type: string }
+        constraints:
+          type: array
+          items: { type: string }
+````
+
+### Using `components.schemas` with `allOf`
+
+Common fields (e.g., `from_agent`, `to_agent`, `run_id`) can be shared across handoff types by placing them in `components.schemas` and composing via `allOf`:
+
+````yaml
+components:
+  schemas:
+    handoff-common:
+      type: object
+      required: [from_agent, to_agent]
+      properties:
+        from_agent: { type: string }
+        to_agent: { type: string }
+        run_id: { type: string }
+
+handoff_types:
+  task-delegation:
+    version: 1
+    description: "Delegate a task"
+    schema:
+      allOf:
+        - $ref: "#/components/schemas/handoff-common"
+        - type: object
+          required: [payload]
+          properties:
+            payload:
+              type: object
+              required: [objective]
+              properties:
+                objective: { type: string }
+
+  implementation-result:
+    version: 1
+    description: "Return implementation results"
+    schema:
+      allOf:
+        - $ref: "#/components/schemas/handoff-common"
+        - type: object
+          required: [payload]
+          properties:
+            payload:
+              type: object
+              required: [result]
+              properties:
+                result: { type: string }
+                evidence:
+                  type: array
+                  items: { type: string }
+````
+
+The `$ref: "#/..."` references are resolved during loading, before validation. The resulting merged schema is then meta-validated as valid JSON Schema.
+
+---
+
 ## Inheritance and merge operators
 
 `agent-contracts` supports shared base definitions with project-level overrides through `extends`.
@@ -665,6 +813,7 @@ npx agent-contracts
 | `agent-contracts validate [path]` | Validate schema and references                         |
 | `agent-contracts lint [path]`     | Run semantic lint                                      |
 | `agent-contracts render`          | Render outputs from config                             |
+| `agent-contracts generate guardrails` | Generate guardrail artifacts from bindings       |
 | `agent-contracts check`           | Run resolve → validate → lint → render --check         |
 
 The `[path]` argument defaults to `agent-contracts.yaml` in the current directory.
@@ -731,6 +880,8 @@ Each `context` type provides a different rendering scope:
 | `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` |
 | `policy` | Per policy | `{policy.id}` in output path | `policy`, `dsl` |
+| `guardrail` | Per guardrail | `{guardrail.id}` in output path | `guardrail`, `dsl` |
+| `guardrail_policy` | Per guardrail policy | `{guardrail_policy.id}` in output path | `guardrail_policy`, `dsl` |
 
 #### Enriched context details
 
@@ -764,7 +915,7 @@ Templates can use these built-in helpers:
 | `notEmpty` | `{{#if (notEmpty obj)}}` | True when object has at least one key |
 | `inc` | `{{inc @index}}` | Increment number by 1 (for 1-based indexing) |
 | `yamlBlock` | `{{{yamlBlock obj}}}` | Render value as YAML-formatted text |
-| `lookupPayloadFields` | `{{#each (lookupPayloadFields payload)}}` | Extract payload field info (name, type, required, enum) |
+| `lookupPayloadFields` | `{{#each (lookupPayloadFields schema)}}` | Extract schema field info (name, type, required, enum); resolves `allOf` internally |
 | `join` | `{{join arr ", "}}` | Join array elements with separator |
 | `contains` | `{{#if (contains arr "x")}}` | True when array includes value |
 | `groupBy` | `{{#with (groupBy arr "key")}}` | Group array elements by field value |
@@ -781,6 +932,102 @@ Templates can use these built-in helpers:
 
 ---
 
+## Guardrail DI system
+
+`agent-contracts` includes a dependency injection system for guardrails that separates **what to protect** from **how to enforce** and **where to output**.
+
+### Architecture
+
+```text
+agent-contracts.yaml (DSL)        agent-contracts.config.yaml
+├─ guardrails:   (what + why)     ├─ bindings: [cursor.yaml, git.yaml, ...]
+├─ guardrail_policies: (how)      ├─ active_guardrail_policy: default
+└─ agents, tasks, ...             ├─ paths: {cursor_root: .cursor, ...}
+                                  └─ vars, renders (existing)
+```
+
+### Guardrail definition
+
+Guardrails declare constraints in the DSL without any implementation details:
+
+````yaml
+guardrails:
+  no-force-push:
+    description: "Force push to protected branches is forbidden"
+    scope:
+      tools: [git]
+    rationale: "Force push destroys commit history"
+    tags: [branch-protection, safety]
+````
+
+### Guardrail policy
+
+Policies define enforcement strategies:
+
+````yaml
+guardrail_policies:
+  default-enforcement:
+    rules:
+      - guardrail: no-force-push
+        severity: critical
+        action: block
+      - guardrail: english-only-code
+        severity: warning
+        action: warn
+        allow_override: true
+````
+
+### Software bindings
+
+Bindings define software-specific check implementations:
+
+````yaml
+# bindings/cursor.yaml
+software: cursor
+version: 1
+
+guardrail_impl:
+  no-force-push:
+    checks:
+      - hook_event: beforeShellExecution
+        matcher:
+          type: command_regex
+          pattern: "git\\s+push\\s+.*--force"
+        message: "Force push is forbidden"
+
+outputs:
+  hook-script:
+    target: "{cursor_root}/hooks/evaluate-hook.sh"
+    mode: write
+    executable: true
+    template: ./templates/cursor-hook-wrapper.sh.hbs
+````
+
+### Config
+
+````yaml
+# agent-contracts.config.yaml
+bindings:
+  - ./bindings/cursor.yaml
+  - ./bindings/git.yaml
+
+active_guardrail_policy: default-enforcement
+
+paths:
+  cursor_root: .cursor
+  git_hooks_root: scripts/git-hooks
+````
+
+### Generate command
+
+````bash
+agent-contracts generate guardrails -c agent-contracts.config.yaml
+agent-contracts generate guardrails -c agent-contracts.config.yaml --binding cursor
+agent-contracts generate guardrails -c agent-contracts.config.yaml --dry-run
+````
+
+---
+
 ## Validation model
 
 `agent-contracts` validates your system in multiple layers.
@@ -792,7 +1039,8 @@ Checks:
 * required fields
 * types
 * enums
-* handoff payload shape
+* 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)
 
 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.
@@ -803,7 +1051,7 @@ Checks:
 
 * cross-entity references
 * owner / producer / editor / consumer validity
-* handoff and payload consistency
+* handoff schema consistency (`required` vs. `properties` alignment)
 * permission alignment between agents and artifacts
 
 ### Semantic lint
@@ -839,16 +1087,16 @@ That separation keeps runtime concerns and architecture concerns from being mixe
 
 ## Tech stack
 
-| Category     | Choice                             |
-| ------------ | ---------------------------------- |
-| Language     | TypeScript (ESM, strict mode)      |
-| Schema       | Zod                                |
-| YAML parsing | yaml                               |
-| Lint         | TypeScript custom rules + Spectral |
-| Templates    | Handlebars                         |
-| CLI          | commander                          |
-| Testing      | Vitest                             |
-| Build        | tsup                               |
+| Category       | Choice                             |
+| -------------- | ---------------------------------- |
+| Language       | TypeScript (ESM, strict mode)      |
+| Schema         | Zod + ajv (JSON Schema meta-validation) |
+| YAML parsing   | yaml                               |
+| Lint           | TypeScript custom rules + Spectral |
+| Templates      | Handlebars                         |
+| CLI            | commander                          |
+| Testing        | Vitest                             |
+| Build          | tsup                               |
 
 ---