agent-contracts 0.10.0 → 0.11.1

package/README.md

@@ -228,6 +228,23 @@ 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`
 
+### Guardrail
+
+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:
@@ -283,6 +300,10 @@ Design regressions become testable.
 * **Config-driven prompt rendering**
 * **Variable substitution** via `${vars.xxx}` in DSL values
 * **Inheritance with merge operators via `extends`**
+* **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**
@@ -317,6 +338,8 @@ validations: {}
 handoff_types: {}
 workflow: {}
 policies: {}
+guardrails: {}
+guardrail_policies: {}
 components:
   schemas: {}
 ````
@@ -790,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.
@@ -856,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
 
@@ -906,6 +932,172 @@ 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
+````
+
+### Binding inheritance
+
+Binding files support `extends` for inheriting and extending a base binding, using the same mechanism as DSL-level `extends`.
+
+A base binding defines shared guardrail implementations and outputs:
+
+````yaml
+# skeleton/bindings/cursor.yaml (base)
+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:
+  policy-bundle:
+    target: "{cursor_root}/guardrails/policy.json"
+    mode: write
+    inline_template: "{{json resolved_checks}}"
+````
+
+A project binding extends the base and adds project-specific guardrail implementations:
+
+````yaml
+# project/bindings/cursor.yaml
+extends: ../../skeleton/bindings/cursor.yaml
+software: cursor
+version: 1
+
+guardrail_impl:
+  lint-on-save:
+    checks:
+      - hook_event: afterFileEdit
+        matcher:
+          type: file_glob
+          pattern: "**/*.{ts,tsx}"
+        message: "TS file edited — lint results attached."
+````
+
+The result is a single merged binding with all guardrail implementations from both base and project.
+
+Merge behavior:
+
+| Field | 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) |
+| `reporting` | Deep merge (project fields override base) |
+| passthrough fields | Project wins |
+
+All merge operators (`$append`, `$prepend`, `$insert_after`, `$replace`, `$remove`) work within binding `extends`, the same as DSL `extends`.
+
+Chained inheritance (grandparent → parent → child) and both local path (`./`, `../`) and npm package references are supported. Circular extends are detected and rejected.
+
+When using binding `extends`, the config only needs to list the child binding:
+
+````yaml
+# agent-contracts.config.yaml
+bindings:
+  - ./bindings/cursor.yaml    # extends base internally
+  - ./bindings/git.yaml
+````
+
+### 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.