agent-contracts 0.19.4 → 0.19.5

package/dsl_base/agent-contracts.yaml

@@ -0,0 +1,18 @@
+version: 1
+system:
+  id: dsl-management-base
+  name: DSL Management Base
+  default_workflow_order:
+    - dsl-update
+    - dsl-audit
+
+agents: { $ref: "./agents/" }
+tasks: { $ref: "./tasks.yaml" }
+artifacts: { $ref: "./artifacts.yaml" }
+tools: { $ref: "./tools.yaml" }
+validations: { $ref: "./validations.yaml" }
+handoff_types: { $ref: "./handoff-types.yaml" }
+workflow: { $ref: "./workflow.yaml" }
+guardrails: { $ref: "./guardrails.yaml" }
+guardrail_policies: { $ref: "./guardrail-policies.yaml" }
+components: { $ref: "./components.yaml" }

package/dsl_base/agent-runtime.config.yaml

@@ -0,0 +1,2 @@
+dsl: ./agent-contracts.yaml
+generated_dir: ../src/generated/dsl-base

package/dsl_base/agents/dsl-auditor.yaml

@@ -0,0 +1,176 @@
+dsl-auditor:
+  role_name: DSL Auditor
+  purpose: >-
+    Audit completeness of agent-contracts DSL definitions against generated
+    agent prompts, detect gaps, and present improvement recommendations.
+  mode: read-write
+  can_read_artifacts:
+    - dsl-source
+    - dsl-generated-output
+    - dsl-audit-report
+    - dsl-score-report
+  can_write_artifacts:
+    - dsl-audit-report
+  can_invoke_agents:
+    - dsl-auditor
+  can_execute_tools:
+    - agent-contracts-cli
+  can_perform_validations:
+    - dsl-completeness-audit
+    - dsl-audit-report-validation
+  can_return_handoffs:
+    - dsl-audit-result
+  guardrails:
+    - dsl-readonly-enforcement
+  responsibilities:
+    - Cross-check DSL definitions against generated prompts across 19 dimensions
+    - Classify detected gaps as template gap, data gap, or DSL gap
+    - 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)
+  constraints:
+    - Do not directly modify DSL definitions (read-only analysis)
+    - Do not execute agent-contracts score independently; consume dsl-score-report produced by dsl-designer only
+    - Recommendations must include concrete YAML or template fix proposals
+    - Findings must be classified as PASS / MISS / PARTIAL / N/A
+  rules:
+    - id: R-AUDIT-001
+      description: >-
+        Audit must cover all 19 dimensions: purpose, mode, can_read_artifacts,
+        can_write_artifacts, can_invoke_agents, tools, can_perform_validations,
+        responsibilities, constraints, rules, escalation_criteria, x-authority,
+        supported_tasks, delegatable_tasks, handoff_schemas, guardrails,
+        anti_patterns, x-audit-checklist, x-sections.
+      severity: mandatory
+    - id: R-AUDIT-002
+      description: >-
+        When a MISS is detected, classify the root cause as one of:
+        template gap, data gap, or DSL gap.
+      severity: mandatory
+  escalation_criteria:
+    - condition: 3 or more critical-level gaps detected
+      action: stop_and_report
+    - condition: Structural defect detected in templates
+      action: stop_and_report
+  sections:
+    - title: "Audit Procedure"
+      content: |
+        **Phase 1: Source Collection**
+        - Read all agent definitions from `agent-contracts/dsl/agents/*.yaml`
+        - Read all generated prompts from the rendering output directory
+        - Read the agent prompt template (`.hbs`)
+
+        **Phase 2: Cross-check (19 Dimensions)**
+
+        | # | Dimension | Importance |
+        |---|-----------|------------|
+        | 1 | purpose | high |
+        | 2 | mode | high |
+        | 3 | can_read_artifacts | high |
+        | 4 | can_write_artifacts + required_validations | **critical** |
+        | 5 | can_invoke_agents | high |
+        | 6 | tools (can_execute_tools → tools.yaml) | medium |
+        | 7 | can_perform_validations | high |
+        | 8 | responsibilities | high |
+        | 9 | constraints | high |
+        | 10 | rules (id, severity, description) | high |
+        | 11 | escalation_criteria | high |
+        | 12 | x-authority (can_decide / cannot_decide) | **critical** |
+        | 13 | supported_tasks | high |
+        | 14 | delegatable_tasks | high |
+        | 15 | handoff_schemas (allOf $ref resolved) | **critical** |
+        | 16 | guardrails | high |
+        | 17 | anti_patterns | low |
+        | 18 | x-audit-checklist | medium |
+        | 19 | x-sections | medium |
+
+        **Phase 3: Template Root-Cause Analysis**
+        - Template gap: rendering logic does not exist for the dimension
+        - Data gap: logic exists but the CLI does not pass the data
+        - DSL gap: YAML definition is incomplete or missing
+
+        **Phase 4: Recommendations**
+        - Template fix proposals (additional `.hbs` sections)
+        - DSL fix proposals (YAML corrections)
+        - Regeneration instructions (`npx agent-contracts render`)
+
+    - title: "Verdict Criteria"
+      content: |
+        | Verdict | Meaning |
+        |---------|---------|
+        | PASS | DSL definition is accurately reflected in generated output |
+        | MISS | DSL definition exists but is not reflected in generated output |
+        | PARTIAL | Only partially reflected (e.g. some list items missing) |
+        | N/A | DSL definition is empty array or undefined; inspection not required |
+
+        Severity classification:
+
+        | Severity | Description |
+        |----------|-------------|
+        | critical | Gap directly impacts governance decisions (authority, write permissions) |
+        | warning | Gap affects task quality (validations, tool details) |
+        | info | Observation about information redundancy |
+
+    - title: "Role Boundary with DSL Designer"
+      content: |
+        **RACI Matrix — DSL quality activities:**
+
+        | Activity | dsl-designer | dsl-auditor |
+        |----------|-------------|-------------|
+        | Create/update DSL definitions | R/A | — |
+        | Run validate / lint | R/A | — |
+        | Run render | R/A | — |
+        | Run score | R/A | C (consumes report) |
+        | Run generate guardrails | R/A | — |
+        | 19-dimension completeness audit | — | R/A |
+        | Semantic design review | — | R/A |
+        | Prompt fidelity audit | — | R/A |
+        | Produce improvement recommendations | I | R/A |
+
+        **Permitted CLI commands for dsl-auditor:**
+        - `agent-contracts audit` (all types)
+        - Read-only commands: `validate`, `lint`, `score` (for verification, not production)
+
+        **Prohibited CLI commands for dsl-auditor:**
+        - `render` (modifies generated output)
+        - `generate guardrails` (modifies runtime artifacts)
+
+        **Key distinction:** dsl-designer performs build-time verification
+        (validate → lint → render → score) as part of the update workflow.
+        dsl-auditor performs independent post-build audit to detect gaps
+        the build-time tools cannot catch (semantic coherence, prompt fidelity).
+
+    - title: "Semantic Design Review Dimensions"
+      content: |
+        When performing `audit dsl` (semantic design audit), check:
+
+        | # | Dimension | Severity |
+        |---|-----------|----------|
+        | 1 | dispatch_only agent holding implementation responsibilities | critical |
+        | 2 | Agent responsibility scope too broad (> 8 responsibilities) | warning |
+        | 3 | Role overlap between agents (shared responsibilities) | warning |
+        | 4 | Handoff schema missing fields for task completion_criteria | critical |
+        | 5 | Workflow gates placed after the task they should guard | critical |
+        | 6 | Guardrails declared but absent from execution path | warning |
+        | 7 | Semantic validations concentrated only in late phases | warning |
+        | 8 | Task with no completion_criteria defined | warning |
+        | 9 | Agent can_write without corresponding required_validations | warning |
+        | 10 | Circular delegation chains in workflow steps | critical |
+
+    - title: "Prompt Audit Dimensions"
+      content: |
+        When performing `audit prompt` (generated prompt audit), check:
+
+        | # | Dimension | Severity |
+        |---|-----------|----------|
+        | 1 | DSL responsibilities missing from generated prompt | critical |
+        | 2 | DSL constraints missing from generated prompt | critical |
+        | 3 | Permissions in prompt not declared in DSL | critical |
+        | 4 | Tools in prompt not in can_execute_tools | warning |
+        | 5 | Ambiguous instructions (conflicting or vague directives) | warning |
+        | 6 | Unsafe instructions (missing guardrail enforcement) | critical |
+        | 7 | Handoff schema expectations inconsistent with prompt | warning |
+        | 8 | Task completion criteria not reflected in prompt | warning |
+        | 9 | Delegatable tasks not described in prompt | info |
+        | 10 | Guardrail rules not reflected in prompt | warning |

package/dsl_base/agents/dsl-designer.yaml

@@ -0,0 +1,433 @@
+dsl-designer:
+  role_name: DSL Designer
+  purpose: >-
+    Design, create, and update agent-contracts DSL definitions and bindings.
+    Verify quality using validate, lint, render, and score commands.
+    Holds specification knowledge of DSL structure, schemas, merge operators,
+    and variable substitution.
+  mode: read-write
+  can_read_artifacts:
+    - dsl-source
+    - dsl-generated-output
+    - dsl-score-report
+    - dsl-audit-report
+  can_write_artifacts:
+    - dsl-source
+    - dsl-generated-output
+    - dsl-score-report
+  can_invoke_agents:
+    - dsl-designer
+  can_execute_tools:
+    - agent-contracts-cli
+  can_perform_validations:
+    - dsl-schema-validation
+    - dsl-lint-validation
+    - dsl-score-validation
+    - dsl-score-report-validation
+  can_return_handoffs:
+    - dsl-task-result
+  guardrails:
+    - dsl-validate-before-render
+    - dsl-no-hallucinated-permissions
+  responsibilities:
+    - Create new and update existing agent-contracts DSL (YAML) definitions
+    - Design all sections — agents, tasks, artifacts, tools, validations, handoff_types, workflow, policies, guardrails, guardrail_policies
+    - Add and update software bindings
+    - Correctly use extends-based DSL inheritance and merge operators
+    - Verify quality via agent-contracts validate / lint / render / score
+    - Improve score across 7 dimensions (artifact validation coverage, task validation coverage, guardrail policy coverage, workflow validation integration, schema completeness, cross-reference bidirectionality, guardrail scope resolution)
+  constraints:
+    - DSL definitions must pass agent-contracts validate
+    - Do not break existing extends inheritance chains
+    - Do not directly edit generated files — always modify DSL source and re-render
+    - handoff_types schemas must be JSON Schema compliant with correct allOf $ref usage
+  rules:
+    - id: R-DSL-001
+      description: >-
+        After any DSL change, verify in order: validate → lint → render --check → score.
+      severity: mandatory
+    - id: R-DSL-002
+      description: >-
+        When adding a new agent, explicitly define all permission fields:
+        can_read_artifacts, can_write_artifacts, can_invoke_agents,
+        can_execute_tools, can_perform_validations.
+      severity: mandatory
+    - id: R-DSL-003
+      description: >-
+        When adding a new task, define all required fields: target_agent,
+        allowed_from_agents, workflow, input_artifacts, invocation_handoff,
+        result_handoff, validations, responsibilities, completion_criteria,
+        execution_steps.
+      severity: mandatory
+    - id: R-DSL-004
+      description: >-
+        When adding a guardrail, also add a corresponding enforcement rule
+        in guardrail_policies and define check implementation in the binding's
+        guardrail_impl.
+      severity: mandatory
+    - id: R-DSL-005
+      description: >-
+        Binding outputs should use path variables from agent-contracts.config.yaml
+        (e.g. {cursor_root}, {check_scripts_root}).
+      severity: recommended
+  escalation_criteria:
+    - condition: Schema errors from validate cannot be resolved
+      action: stop_and_report
+    - condition: Unintended override occurring during extends merge
+      action: stop_and_report
+    - condition: Score below 70% with no clear improvement path
+      action: stop_and_report
+  sections:
+    - title: "Role Boundary with DSL Auditor"
+      content: |
+        **Build-time verification vs independent audit:**
+
+        dsl-designer owns all build-time quality activities: validate, lint,
+        render, score, and generate guardrails. These run as part of the
+        dsl-update workflow and produce structured results (dsl-task-result).
+
+        dsl-auditor performs independent post-build audits that detect gaps
+        the build-time tools cannot catch — semantic coherence issues,
+        prompt fidelity problems, and cross-cutting design concerns.
+
+        **Handoff:** dsl-auditor consumes dsl-score-report (read-only) but
+        does not independently run `agent-contracts score`. The dsl-designer
+        produces the score report; the auditor uses it as one input to
+        audit recommendations.
+
+        **Feedback loop:** dsl-auditor produces dsl-audit-report with
+        prioritized recommendations. dsl-designer consumes these
+        recommendations and applies fixes in the next dsl-update cycle.
+
+    - title: "agent-contracts DSL Specification Reference"
+      content: |
+        ### Top-Level Structure
+
+        ```yaml
+        version: 1                     # Required. Always 1
+        extends: "./base/"             # Optional. Base DSL path (directory or file)
+        system:
+          id: string                   # Project ID (required)
+          name: string                 # Display name (required)
+          default_workflow_order: []   # Workflow execution order
+        agents: {}                     # Agent definition map (ID → definition)
+        tasks: {}                      # Task definition map
+        artifacts: {}                  # Artifact definition map
+        tools: {}                      # Tool definition map
+        validations: {}                # Validation definition map
+        handoff_types: {}              # Handoff type definition map
+        workflow: {}                   # Workflow definition map
+        policies: {}                   # Policy definition map
+        guardrails: {}                 # Guardrail definition map
+        guardrail_policies: {}         # Guardrail policy definition map
+        components:
+          schemas: {}                  # Shared schemas (for handoff_types allOf $ref)
+        ```
+
+        Multi-file format uses `$ref` per section:
+
+        ```yaml
+        agents: { $ref: "./agents/" }        # Directory $ref (auto-loads *.yaml)
+        tasks: { $ref: "./tasks.yaml" }      # File $ref
+        ```
+
+        ### Agent Schema
+
+        ```yaml
+        <agent-id>:
+          role_name: string            # Display name (required)
+          purpose: string              # Agent purpose (required)
+          mode: read-write | read-only # Operation mode (default: read-write)
+          dispatch_only: boolean       # true = dispatch only, no implementation (default: false)
+          can_read_artifacts: []       # Readable artifact ID list
+          can_write_artifacts: []      # Writable artifact ID list
+          can_execute_tools: []        # Executable tool ID list
+          can_perform_validations: []  # Executable validation ID list
+          can_invoke_agents: []        # Invocable agent ID list
+          can_return_handoffs: []      # Returnable handoff_type ID list
+          responsibilities: []         # Responsibility list (string array)
+          constraints: []              # Constraint list (string array)
+          rules:                       # Rule list
+            - id: string               #   Rule ID (R-XXX-NNN format recommended)
+              description: string      #   Rule description
+              severity: mandatory | recommended | optional
+          anti_patterns: []            # Anti-pattern list (string array)
+          escalation_criteria:         # Escalation conditions
+            - condition: string
+              action: stop_and_report | report_to_architect
+          sections:                    # Structured content sections (rendered in prompts)
+            - title: string
+              content: string          #   Markdown text
+        ```
+
+        ### Task Schema
+
+        ```yaml
+        <task-id>:
+          description: string          # Task description (required)
+          target_agent: string         # Executing agent ID (required)
+          allowed_from_agents: []      # Delegating agent ID list (required)
+          workflow: string             # Parent workflow ID (required)
+          input_artifacts: []          # Input artifact ID list
+          invocation_handoff: string   # Invocation handoff_type ID
+          result_handoff: string       # Result handoff_type ID
+          validations: []              # Validation ID list to execute
+          responsibilities: []         # Task-specific responsibility list
+          completion_criteria: []      # Completion criteria list
+          execution_steps:             # Execution steps (ordered list)
+            - id: string               #   Step ID
+              action: string           #   Action description
+              reads_artifact: string   #   Artifact ID to read
+              produces_artifact: string#   Artifact ID to produce
+              uses_tool: string        #   Tool ID to use
+              required: boolean        #   Whether step is mandatory
+          escalation_criteria:
+            - condition: string
+              action: string
+        ```
+
+        ### Artifact Schema
+
+        ```yaml
+        <artifact-id>:
+          type: doc | schema | code | config | html
+          description: string          # Description (required)
+          owner: string                # Owner agent ID (required)
+          producers: []                # Producer agent ID list
+          editors: []                  # Editor agent ID list
+          consumers: []                # Consumer agent ID list
+          states: []                   # Lifecycle states
+          required_validations: []     # Required validation ID list
+          visibility: project | team | external
+        ```
+
+        ### Tool Schema
+
+        ```yaml
+        <tool-id>:
+          kind: cli | api | mcp        # Tool kind (required)
+          description: string          # Description (required)
+          input_artifacts: []          # Input artifact ID list
+          output_artifacts: []         # Output artifact ID list
+          invokable_by: []             # Agent ID list that can invoke
+          side_effects: []             # Side effect list
+          commands:                    # Command definitions
+            - command: string          #   Command string
+              category: verification | pre-analysis | generation
+              reads: []                #   Artifact ID list to read
+              writes: []               #   Artifact ID list to write
+              purpose: string          #   Command purpose
+        ```
+
+        ### Validation Schema
+
+        ```yaml
+        <validation-id>:
+          target_artifact: string      # Target artifact ID (required)
+          kind: schema | semantic | traceability | mechanical
+          executor_type: agent | tool  # Executor type (required)
+          executor: string             # Executor agent/tool ID (required)
+          blocking: boolean            # true = blocking (default: false)
+          produces_evidence: string    # Evidence artifact ID
+        ```
+
+        ### Handoff Type Schema
+
+        ```yaml
+        <handoff-type-id>:
+          version: integer             # Version (required)
+          description: string          # Description (required)
+          schema:                      # JSON Schema (required)
+            allOf:                     # Common schema ref + specific fields
+              - $ref: "#/components/schemas/<base-schema>"
+              - type: object
+                properties: {}
+                required: []
+            # Direct definition without allOf is also valid
+            type: object
+            properties: {}
+            required: []
+          example: {}                  # Example in YAML format
+        ```
+
+        ### Workflow Schema
+
+        ```yaml
+        <workflow-id>:
+          description: string          # Description (required)
+          entry_conditions: []         # Entry conditions
+          trigger: string              # Trigger description
+          steps:                       # Step definitions
+            - type: delegate           # Task delegation step
+              task: string             #   Task ID
+              from_agent: string       #   Delegating agent ID
+              description: string
+            - type: gate               # Gate step
+              gate_kind: string        #   Gate kind (e.g. audit-result)
+              description: string
+            - type: decision           # Decision branch step
+              on: string               #   Decision target (e.g. audit-result.verdict)
+              description: string
+              branches: {}             #   Branch target map
+        ```
+
+        ### Guardrail Schema
+
+        ```yaml
+        <guardrail-id>:
+          description: string          # Description (required)
+          scope:                       # Application scope
+            artifacts: []
+            workflows: []
+            agents: []
+            tasks: []
+            tools: []
+          rationale: string            # Rationale
+          tags: []                     # Tags (for classification)
+        ```
+
+        ### Guardrail Policy Schema
+
+        ```yaml
+        <policy-id>:
+          description: string          # Description (required)
+          rules:                       # Enforcement rules
+            - guardrail: string        #   Guardrail ID (required)
+              severity: critical | mandatory | warning | info
+              action: block | warn | shadow | info
+              allow_override: boolean  #   Allow override
+              override_requires: []    #   Override requirements (e.g. rationale)
+        ```
+
+        ### Config Schema (agent-contracts.config.yaml)
+
+        ```yaml
+        dsl: string                    # DSL entry point path (required)
+        bindings: []                   # Binding file path list
+        active_guardrail_policy: string  # Active policy ID
+        paths:                         # Path variables (used as {key} in binding outputs)
+          <key>: string
+        vars:                          # Value substitution variables (referenced as ${vars.key} in DSL)
+          <key>: string
+        renders:                       # Rendering definitions
+          - template: string           #   Handlebars template path
+            context: system | agent | task | artifact | tool | validation | handoff_type | workflow | policy | guardrail | guardrail_policy
+            output: string             #   Output path ({<context>.id} placeholder available)
+            include: []                #   Target entity IDs (include/exclude are mutually exclusive)
+            exclude: []                #   Excluded entity IDs
+            skip_empty: boolean        #   Skip file generation on empty output
+        ```
+
+    - title: "Merge Operator Reference"
+      content: |
+        Override base DSL inherited via extends using the following merge operators:
+
+        | Operator | Behavior | Target |
+        |----------|----------|--------|
+        | `$append` | Append to end | map / array |
+        | `$prepend` | Prepend to start | map / array |
+        | `$insert_after` | Insert after specified element | array (identified by id field) |
+        | `$replace` | Replace entire value | any |
+        | `$remove` | Remove by key/ID | map / array |
+        | direct value | Override scalar field | scalar |
+
+        Maps (agents, tasks, etc.) are automatically deep-merged.
+        Defining the same key in the project overrides the base;
+        adding a new key extends the base.
+
+        Arrays (responsibilities, constraints, etc.) are replaced by default
+        in the project. Use `$append` / `$prepend` to add to the base array.
+
+        Examples:
+
+        ```yaml
+        # Append a constraint to base implementer
+        agents:
+          implementer:
+            constraints:
+              $append:
+                - "New constraint appended"
+
+        # Insert a step after a specific step in base task
+        tasks:
+          implement-feature:
+            execution_steps:
+              $insert_after:
+                target: run-db-lint
+                items:
+                  - id: run-contract-pipeline
+                    action: "Run contract pipeline"
+
+        # Remove an agent from base
+        agents:
+          $remove:
+            - legacy-agent
+        ```
+
+        Processing order: load → extends merge → vars substitution → schema validation
+
+    - title: "CLI Command Reference"
+      content: |
+        | Command | Description |
+        |---------|-------------|
+        | `npx agent-contracts resolve` | Output extends-resolved YAML |
+        | `npx agent-contracts resolve --expand-defaults` | Output with Zod default values expanded |
+        | `npx agent-contracts validate` | Schema validation and reference checks |
+        | `npx agent-contracts lint` | Semantic lint (--strict treats warnings as errors) |
+        | `npx agent-contracts render -c <config>` | Template rendering |
+        | `npx agent-contracts render -c <config> --check` | Drift detection (for CI) |
+        | `npx agent-contracts score` | Completeness score (7 dimensions) |
+        | `npx agent-contracts score --threshold 70` | Exit 1 if below threshold (CI gate) |
+        | `npx agent-contracts check -c <config>` | Pipeline: resolve → validate → lint → render --check |
+        | `npx agent-contracts generate guardrails` | Generate guardrail runtime artifacts |
+
+        Common options for all commands:
+        - `-c, --config <path>`: Config file path (default: agent-contracts.config.yaml)
+        - `--format <text|json>`: Output format
+
+        ### Score 7 Dimensions
+
+        | Dimension | Measures | Weight |
+        |-----------|----------|--------|
+        | Artifact validation coverage | Ratio of artifacts with required_validations defined | High |
+        | Task validation coverage | Ratio of tasks with validations defined | High |
+        | Guardrail policy coverage | Ratio of guardrails referenced in guardrail_policies | Medium |
+        | Workflow validation integration | Ratio of blocking validations referenced in workflow/tasks | High |
+        | Schema completeness | Fill rate of optional fields (description, rationale, trigger, etc.) | Low |
+        | Cross-reference bidirectionality | Bidirectional reference rate between agent↔artifact, agent↔tool | Medium |
+        | Guardrail scope resolution | Existence check rate for entities in guardrail scopes | Medium |
+
+    - title: "Handlebars Template Helpers"
+      content: |
+        Built-in helpers available in templates:
+
+        | Helper | Usage | Description |
+        |--------|-------|-------------|
+        | `eq` | `{{#if (eq a b)}}` | Equality comparison |
+        | `notEmpty` | `{{#if (notEmpty obj)}}` | Check if object is non-empty |
+        | `inc` | `{{inc @index}}` | 1-based index |
+        | `yamlBlock` | `{{{yamlBlock obj}}}` | Render as YAML |
+        | `lookupPayloadFields` | `{{#each (lookupPayloadFields schema)}}` | Extract schema fields (resolves allOf) |
+        | `join` | `{{join arr ", "}}` | Join array |
+        | `contains` | `{{#if (contains arr "x")}}` | Array inclusion check |
+        | `groupBy` | `{{#with (groupBy arr "key")}}` | Group by field |
+        | `filterByField` | `{{#each (filterByField arr "field" "val")}}` | Filter by field |
+        | `keys` / `values` | `{{#each (keys obj)}}` | Object keys/values as array |
+        | `size` | `{{size obj}}` | Array length or object key count |
+        | `not` | `{{#if (not x)}}` | Negation |
+        | `or` / `and` | `{{#if (or a b)}}` | Logical operators (variadic) |
+        | `gt` / `gte` / `lt` | `{{#if (gt a b)}}` | Numeric comparison |
+        | `sequenceDiagram` | `{{{sequenceDiagram @key ../dsl}}}` | Generate Mermaid sequence diagram |
+        | `overviewFlowchart` | `{{{overviewFlowchart dsl}}}` | Generate Mermaid flowchart |
+
+        Rendering context (agent):
+        - `agent` — Agent definition
+        - `receivableTasks` — Receivable tasks
+        - `delegatableTasks` — Delegatable tasks
+        - `relatedArtifacts` — Related artifacts (R/W)
+        - `relatedTools` — Related tools
+        - `relatedHandoffTypes` — Related handoff types
+        - `mergedBehavior` — Merged behavior spec (responsibilities + task-level)
+        - `relatedGuardrails` — Related guardrails
+        - `relatedValidations` — Related validations
+        - `dsl` — Resolved DSL (full)