agent-contracts 0.16.0 → 0.16.2

package/README.md

@@ -1005,6 +1005,10 @@ VarsSubstitutionError: Undefined variable "repo_url" in value "Repository: ${var
 
 ## CLI
 
+For the full CLI reference with all commands, options, arguments, exit codes, and AI agent policies, see the [CLI Reference](docs/cli-reference.md).
+
+The CLI contract specification is defined in [`cli-contract.yaml`](cli-contract.yaml) using [CLI Contracts](https://github.com/foo-ogawa/cli-contracts).
+
 ### Installation
 
 ````bash

package/cli-contract.yaml

@@ -0,0 +1,610 @@
+# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json
+cliContracts: 0.1.0
+
+info:
+  title: agent-contracts CLI
+  version: 0.16.2
+  description: >-
+    Declarative YAML DSL toolkit for defining, validating, and rendering
+    multi-agent development workflows. Provides static validation,
+    semantic linting, prompt rendering, guardrail generation, and
+    completeness scoring for agent contract definitions.
+  license:
+    name: MIT
+  contact:
+    name: foo-ogawa
+    url: https://github.com/foo-ogawa/agent-contracts
+
+commandSets:
+  agent-contracts:
+    summary: Agent contracts tooling — validate, lint, render DSL files.
+    executable: agent-contracts
+
+    globalOptions:
+      - name: version
+        aliases: [V]
+        description: Print version and exit.
+        schema:
+          type: boolean
+
+      - name: help
+        aliases: [h]
+        description: Show help and exit.
+        schema:
+          type: boolean
+
+    commands:
+      # ── resolve ───────────────────────────────────────
+      resolve:
+        summary: Resolve DSL (load + merge extends) and output YAML.
+        description: >-
+          Loads the agent-contracts DSL file, merges all extends
+          inheritance chains, substitutes variables from config, and
+          outputs the fully resolved result as YAML or JSON.
+        usage:
+          - agent-contracts resolve
+          - agent-contracts resolve path/to/agent-contracts.yaml
+          - agent-contracts resolve --format json
+          - agent-contracts resolve --expand-defaults
+          - agent-contracts resolve -c agent-contracts.config.yaml
+
+        arguments:
+          - name: dir
+            index: 0
+            required: false
+            description: Path to agent-contracts.yaml.
+            schema:
+              type: string
+              default: agent-contracts.yaml
+            file:
+              mode: read
+              exists: true
+              mediaType: application/yaml
+              encoding: utf-8
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              mediaType: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            valueName: id
+            schema:
+              type: string
+
+          - name: format
+            description: Output format.
+            valueName: format
+            schema:
+              type: string
+              enum: [text, json]
+              default: text
+
+          - name: expand-defaults
+            description: >-
+              Expand all Zod default values in output. Fields like
+              required_validations, tags, and can_read_artifacts are
+              written explicitly instead of relying on schema defaults.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: Resolved DSL output successfully.
+            stdout:
+              format: text
+
+          '1':
+            description: Resolution failed (file not found, parse error, or config error).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── validate ──────────────────────────────────────
+      validate:
+        summary: Validate DSL against schema and check references.
+        description: >-
+          Validates the resolved DSL against the Zod schema, checks
+          inter-entity references (agent→task, task→artifact, etc.),
+          and validates handoff schemas. Reports diagnostics with
+          severity levels.
+        usage:
+          - agent-contracts validate
+          - agent-contracts validate path/to/agent-contracts.yaml
+          - agent-contracts validate --strict
+          - agent-contracts validate --format json
+          - agent-contracts validate --quiet
+
+        arguments:
+          - name: dir
+            index: 0
+            required: false
+            description: Path to agent-contracts.yaml.
+            schema:
+              type: string
+              default: agent-contracts.yaml
+            file:
+              mode: read
+              exists: true
+              mediaType: application/yaml
+              encoding: utf-8
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              mediaType: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            valueName: id
+            schema:
+              type: string
+
+          - name: format
+            description: Diagnostic output format.
+            valueName: format
+            schema:
+              type: string
+              enum: [text, json]
+              default: text
+
+          - name: quiet
+            description: Suppress output on success.
+            schema:
+              type: boolean
+              default: false
+
+          - name: strict
+            description: Treat warnings as errors.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: Validation passed. No errors found.
+            stdout:
+              format: text
+
+          '1':
+            description: Validation failed or unexpected error.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── lint ──────────────────────────────────────────
+      lint:
+        summary: Run semantic lint rules on resolved DSL.
+        description: >-
+          Runs TypeScript-based semantic lint rules and Spectral rules
+          on the resolved DSL. Checks for best-practice violations,
+          naming conventions, and structural issues beyond schema
+          conformance.
+        usage:
+          - agent-contracts lint
+          - agent-contracts lint path/to/agent-contracts.yaml
+          - agent-contracts lint --strict
+          - agent-contracts lint --format json
+
+        arguments:
+          - name: dir
+            index: 0
+            required: false
+            description: Path to agent-contracts.yaml.
+            schema:
+              type: string
+              default: agent-contracts.yaml
+            file:
+              mode: read
+              exists: true
+              mediaType: application/yaml
+              encoding: utf-8
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              mediaType: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            valueName: id
+            schema:
+              type: string
+
+          - name: format
+            description: Output format.
+            valueName: format
+            schema:
+              type: string
+              enum: [text, json]
+              default: text
+
+          - name: quiet
+            description: Suppress output on success.
+            schema:
+              type: boolean
+              default: false
+
+          - name: strict
+            description: Treat warnings as errors.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: Lint passed. No errors or warnings.
+            stdout:
+              format: text
+
+          '1':
+            description: Lint failed or unexpected error.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── render ────────────────────────────────────────
+      render:
+        summary: Render resolved DSL with Handlebars templates.
+        description: >-
+          Renders output files from the resolved DSL using Handlebars
+          templates configured in agent-contracts.config.yaml. Supports
+          drift detection via --check mode. Requires a config file.
+        usage:
+          - agent-contracts render -c agent-contracts.config.yaml
+          - agent-contracts render -c agent-contracts.config.yaml --check
+          - agent-contracts render --quiet
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              mediaType: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            valueName: id
+            schema:
+              type: string
+
+          - name: check
+            description: Check for drift without writing files.
+            schema:
+              type: boolean
+              default: false
+
+          - name: quiet
+            description: Suppress output on success.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: Render succeeded (or no drift detected in --check mode).
+            stdout:
+              format: text
+
+          '1':
+            description: >-
+              Render failed, config not found, schema validation failed,
+              or drift detected in --check mode.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: medium
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects:
+            - file_write
+          recommendedBeforeUse:
+            - Ensure agent-contracts.config.yaml exists with render targets.
+            - Run validate first to confirm DSL is valid.
+
+      # ── check ─────────────────────────────────────────
+      check:
+        summary: Run full pipeline — resolve, validate, lint, render --check.
+        description: >-
+          Executes the complete verification pipeline in order: resolve
+          DSL, validate schema and references, run lint rules, and check
+          for render drift. Also verifies cross-team interface imports
+          and team-interface.yaml drift when applicable.
+        usage:
+          - agent-contracts check -c agent-contracts.config.yaml
+          - agent-contracts check -c agent-contracts.config.yaml --strict
+          - agent-contracts check --format json --quiet
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              mediaType: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            valueName: id
+            schema:
+              type: string
+
+          - name: format
+            description: Diagnostic output format.
+            valueName: format
+            schema:
+              type: string
+              enum: [text, json]
+              default: text
+
+          - name: quiet
+            description: Suppress output on success.
+            schema:
+              type: boolean
+              default: false
+
+          - name: strict
+            description: Treat warnings as errors.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: All checks passed.
+            stdout:
+              format: text
+
+          '1':
+            description: >-
+              One or more checks failed — validation errors, lint errors,
+              render drift, or missing interface files.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+          recommendedBeforeUse:
+            - Ensure agent-contracts.config.yaml exists.
+
+      # ── score ─────────────────────────────────────────
+      score:
+        summary: Calculate DSL completeness score.
+        description: >-
+          Evaluates the resolved DSL across 7 dimensions including
+          artifact validation coverage, task validation coverage,
+          guardrail policy coverage, workflow validation integration,
+          schema completeness, cross-reference bidirectionality, and
+          guardrail scope resolution. Returns a score out of 100 with
+          optional CI gating via --threshold.
+        usage:
+          - agent-contracts score
+          - agent-contracts score --format json
+          - agent-contracts score --threshold 70
+          - agent-contracts score -c agent-contracts.config.yaml
+
+        arguments:
+          - name: dir
+            index: 0
+            required: false
+            description: Path to agent-contracts.yaml.
+            schema:
+              type: string
+              default: agent-contracts.yaml
+            file:
+              mode: read
+              exists: true
+              mediaType: application/yaml
+              encoding: utf-8
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              mediaType: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            valueName: id
+            schema:
+              type: string
+
+          - name: format
+            description: Output format.
+            valueName: format
+            schema:
+              type: string
+              enum: [text, json]
+              default: text
+
+          - name: threshold
+            description: Minimum score; exit 1 if below (for CI gates).
+            valueName: number
+            schema:
+              type: integer
+
+        exits:
+          '0':
+            description: Score calculated (and above threshold if specified).
+            stdout:
+              format: text
+
+          '1':
+            description: >-
+              Score below threshold, schema validation failed,
+              or unexpected error.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── generate ──────────────────────────────────────
+      generate:
+        summary: Generate guardrail or interface artifacts from DSL.
+        description: >-
+          Generates runtime artifacts from the DSL. When type is
+          "guardrails" (default), produces guardrail binding files from
+          DSL, policies, and software bindings. When type is "interface",
+          generates a team interface YAML/JSON file from the DSL's
+          team_interface section.
+        usage:
+          - agent-contracts generate -c agent-contracts.config.yaml
+          - agent-contracts generate guardrails -c agent-contracts.config.yaml
+          - agent-contracts generate guardrails --binding cursor-rules
+          - agent-contracts generate guardrails --dry-run
+          - agent-contracts generate interface -c agent-contracts.config.yaml
+          - agent-contracts generate interface --format json
+          - agent-contracts generate interface -o team-interface.yaml --dry-run
+
+        arguments:
+          - name: type
+            index: 0
+            required: false
+            description: Type of artifacts to generate.
+            schema:
+              type: string
+              enum: [guardrails, interface]
+              default: guardrails
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              mediaType: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            valueName: id
+            schema:
+              type: string
+
+          - name: binding
+            description: Filter to specific software binding(s). Guardrails type only.
+            valueName: name
+            repeatable: true
+            schema:
+              type: string
+
+          - name: output
+            aliases: [o]
+            description: Output path for generated team interface. Interface type only.
+            valueName: path
+            schema:
+              type: string
+
+          - name: format
+            description: Output format for team interface (yaml or json). Interface type only.
+            valueName: format
+            schema:
+              type: string
+              enum: [yaml, json]
+              default: yaml
+
+          - name: dry-run
+            description: Print what would be generated without writing files.
+            schema:
+              type: boolean
+              default: false
+
+          - name: quiet
+            description: Suppress output on success.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: Generation succeeded.
+            stdout:
+              format: text
+
+          '1':
+            description: >-
+              Generation failed — unknown type, schema validation failed,
+              config not found, or error-level diagnostics.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: medium
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects:
+            - file_write
+          recommendedBeforeUse:
+            - Ensure agent-contracts.config.yaml exists with binding definitions.
+            - Run validate first to confirm DSL is valid.

package/dist/cli.js

@@ -55209,7 +55209,9 @@ function buildPerAgentContext(dsl, agent) {
   const handoffKinds = /* @__PURE__ */ new Set([
     ...agent.can_return_handoffs,
     ...receivableTasks.map((t3) => t3.invocation_handoff),
-    ...receivableTasks.map((t3) => t3.result_handoff)
+    ...receivableTasks.map((t3) => t3.result_handoff),
+    ...delegatableTasks.map((t3) => t3.invocation_handoff),
+    ...delegatableTasks.map((t3) => t3.result_handoff)
   ]);
   const relatedHandoffTypes = {};
   for (const [kind, ht] of Object.entries(dsl.handoff_types)) {