# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json
cli_contracts: 0.1.0

info:
  title: agent-contracts CLI
  version: 0.34.0
  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-log-inc
    url: https://github.com/foo-log-inc/agent-contracts

artifact_slots:
  dsl-definitions:
    description: Agent contracts DSL YAML files (agent-contracts.yaml and extends targets)
    direction: read
  config:
    description: agent-contracts.config.yaml configuration file
    direction: read
  generated-templates:
    description: Rendered output files from Handlebars templates
    direction: write
  generated-guardrails:
    description: Generated guardrail binding files (cursor-rules, AGENTS.md, etc.)
    direction: write
  generated-interface:
    description: Generated team interface YAML/JSON files
    direction: write
  audit-report:
    description: LLM audit result output files
    direction: write

command_sets:
  agent-contracts:
    summary: Agent contracts tooling — validate, lint, render DSL files.
    executable: agent-contracts

    global_options:
      - 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
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Output format.
            value_name: 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: '{options.format}'
              schema_note: >-
                Output format depends on --format option. Defaults to
                text (YAML representation); json produces a JSON object.

          '1':
            description: Resolution failed (file not found, parse error, or config error).
            stderr:
              format: text

      # ── 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
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Diagnostic output format.
            value_name: 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: '{options.format}'
              schema_note: >-
                Output format depends on --format option. Text shows
                human-readable diagnostics; json produces structured
                validation results.

          '1':
            description: Validation failed or unexpected error.
            stderr:
              format: text

      # ── 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
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Output format.
            value_name: 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: '{options.format}'
              schema_note: >-
                Output format depends on --format option. Text shows
                human-readable diagnostics; json produces structured
                lint results.

          '1':
            description: Lint failed or unexpected error.
            stderr:
              format: text

      # ── render (deprecated alias) ─────────────────────
      render:
        summary: (deprecated) Alias for 'generate templates'.
        deprecated:
          message: >-
            Use 'agent-contracts generate templates' instead.
          alternative: generate templates
        description: >-
          Deprecated alias for 'agent-contracts generate templates'.
          Renders output files from the resolved DSL using Handlebars
          templates and emits a deprecation warning. Supports --check
          for drift detection. 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

        effects:
          risk_level: medium
          writes:
            - generated-templates

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: check
            description: Check for template drift 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 (or no drift detected in --check mode).
            stdout:
              format: text

          '1':
            description: >-
              Generation failed, config not found, schema validation
              failed, or drift detected in --check mode.
            stderr:
              format: text

        x-agent:
          recommended_before_use:
            - 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:
          (1) resolve DSL, (2) validate schema and references,
          (3) run lint rules, (4) check render drift via render --check.
          Steps 1–4 always run. Additionally, when the DSL declares
          cross-team interfaces, (5) verifies interface import
          consistency and (6) checks team-interface.yaml drift.
          Steps 5–6 are skipped when no cross-team interfaces exist.
        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.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Diagnostic output format.
            value_name: 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: '{options.format}'
              schema_note: >-
                Output format depends on --format option. Text shows
                human-readable pipeline summary; json produces structured
                results per pipeline stage.

          '1':
            description: >-
              One or more checks failed — validation errors, lint errors,
              render drift, or missing interface files.
            stderr:
              format: text

        x-agent:
          recommended_before_use:
            - 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
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Output format.
            value_name: format
            schema:
              type: string
              enum: [text, json]
              default: text

          - name: threshold
            description: Minimum score; exit 1 if below (for CI gates).
            value_name: number
            schema:
              type: integer

        exits:
          '0':
            description: Score calculated (and above threshold if specified).
            stdout:
              format: '{options.format}'
              schema_note: >-
                Output format depends on --format option. Text shows
                human-readable score breakdown; json produces structured
                score object with per-dimension details.

          '1':
            description: >-
              Score below threshold, schema validation failed,
              or unexpected error.
            stderr:
              format: text

      # ── audit ───────────────────────────────────────────
      audit:
        summary: Run LLM-based semantic audit on DSL definitions and generated outputs.
        description: >-
          Performs LLM-based semantic analysis on DSL definitions and/or
          generated outputs. Four audit types are available: "render"
          checks whether generated files faithfully reflect the resolved
          DSL, "dsl" reviews DSL design for semantic coherence, "prompt"
          verifies that generated prompts accurately express DSL intent,
          and "extensions" detects declared x-* properties that are not
          consumed by render templates or runtime codegen. Uses
          agent-contracts-runtime (optional peer dependency) for LLM
          execution with handoff schema validation and follow-up recovery.
        usage:
          - agent-contracts audit render -c agent-contracts.config.yaml
          - agent-contracts audit dsl -c agent-contracts.config.yaml
          - agent-contracts audit prompt -c agent-contracts.config.yaml
          - agent-contracts audit extensions -c agent-contracts.config.yaml
          - agent-contracts audit all -c agent-contracts.config.yaml
          - agent-contracts audit dsl --show-prompt -c agent-contracts.config.yaml
          - agent-contracts audit render --format json -c agent-contracts.config.yaml
          - agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml

        effects:
          risk_level: medium
          reads:
            - dsl-definitions
            - config
          writes:
            - audit-report
          network:
            description: >-
              LLM API calls to configured adapter (e.g. OpenAI,
              Gemini, Cursor). Incurs token cost and sends DSL
              content to the LLM provider.
            idempotent: false
            idempotent_note: >-
              LLM inference is non-deterministic — identical inputs
              may produce different findings across runs.

        arguments:
          - name: type
            index: 0
            required: false
            description: >-
              Audit type to run: render (semantic diff of generated
              outputs vs DSL), dsl (design coherence review), prompt
              (generated prompt fidelity check), extensions (unconsumed
              x-* property detection), or all (run all four).
            schema:
              type: string
              enum: [render, dsl, prompt, extensions, all]
              default: all

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Output format.
            value_name: format
            schema:
              type: string
              enum: [text, json, markdown]
              default: text

          - name: scope
            description: >-
              Limit audit scope to specified entities
              (e.g. agents:architect,implementer).
            value_name: entities
            schema:
              type: string

          - name: show-prompt
            description: Output the constructed prompt without calling the LLM API.
            schema:
              type: boolean
              default: false

          - name: adapter
            description: >-
              SDK adapter to use for LLM calls
              (overrides config audit.adapter).
            value_name: name
            schema:
              type: string

          - name: model
            description: LLM model override (overrides config audit.model).
            value_name: name
            schema:
              type: string

          - name: log-file
            aliases: [l]
            description: Write agent progress log to this file path.
            schema:
              type: string

          - name: fail-on
            description: >-
              Minimum finding severity that causes exit 10
              (info|warning|error|critical).
            value_name: level
            schema:
              type: string
              enum: [info, warning, error, critical]
              default: critical

          - name: output
            aliases: [o]
            description: Write result to a file instead of stdout.
            value_name: file
            schema:
              type: string
            file:
              mode: write
              encoding: utf-8

          - name: report-format
            description: >-
              Alias for --format. When both are specified, --report-format
              takes precedence.
            value_name: fmt
            schema:
              type: string
              enum: [text, json, markdown]
              default: text

        exits:
          '0':
            description: Audit succeeded. No findings at or above --fail-on threshold.
            stdout:
              format: '{options.format}'
              schema:
                $ref: './dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error (invalid input, config error, or internal failure).
            stderr:
              format: text

          '10':
            description: Findings at or above --fail-on severity threshold detected.
            stdout:
              format: '{options.format}'
              schema:
                $ref: './dsl_base/components.yaml#/schemas/agent-audit-result'
            stderr:
              format: text
              schema_note: >-
                Summary diagnostic on stderr. Structured findings are
                emitted on stdout in the requested format.

          '11':
            description: >-
              Runtime dependency missing (agent-contracts-runtime not installed).
            stderr:
              format: text

          '12':
            description: LLM provider or adapter error (API failure, auth error).
            stderr:
              format: text

        x-agent:
          riskLevel: medium
          requiresConfirmation: false
          idempotent: false
          sideEffects:
            - network
          sideEffectNote: >-
            Network calls to LLM provider when adapter is not mock.
            Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]
          recommended_before_use:
            - Ensure agent-contracts.config.yaml exists with render targets.
            - Run validate first to confirm DSL is valid.
            - Install agent-contracts-runtime if not using --show-prompt.

      # ── generate ──────────────────────────────────────
      generate:
        summary: Generate artifacts from DSL — templates, guardrails, and/or interface.
        description: >-
          Unified generation command. When type is omitted, runs all
          generation targets (templates, guardrails, interface). When
          type is "templates", renders output files from the DSL using
          Handlebars templates. When type is "guardrails", 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
          - agent-contracts generate -c agent-contracts.config.yaml
          - agent-contracts generate templates
          - agent-contracts generate templates --check
          - 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

        effects:
          risk_level: low
          writes:
            - generated-templates
            - generated-guardrails
            - generated-interface

        arguments:
          - name: type
            index: 0
            required: false
            description: >-
              Type of artifacts to generate. Omit to run all targets.
            schema:
              type: string
              enum: [templates, guardrails, interface]

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: check
            description: >-
              Check for template drift without writing files.
              Only applies to the templates target.
            schema:
              type: boolean
              default: false

          - name: binding
            description: Filter to specific software binding(s). Guardrails type only.
            value_name: name
            repeatable: true
            schema:
              type: string

          - name: output
            aliases: [o]
            description: Output path for generated team interface. Interface type only.
            value_name: path
            schema:
              type: string
            file:
              mode: write
              media_type: application/yaml
              encoding: utf-8

          - name: format
            description: Output format for team interface (yaml or json). Interface type only.
            value_name: 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 (or no drift detected in --check mode).
            stdout:
              format: text

          '1':
            description: >-
              Generation failed — unknown type, schema validation failed,
              config not found, drift detected, or error-level diagnostics.
            stderr:
              format: text

        x-agent:
          recommended_before_use:
            - Ensure agent-contracts.config.yaml exists with render targets and/or binding definitions.
            - Run validate first to confirm DSL is valid.

      # ── navigation-index ──────────────────────────────
      navigation-index:
        summary: Build artifact-centric navigation index from resolved DSL.
        description: >-
          Compiles a structured navigation index that maps each artifact
          to its operations (producer, validator, consumer tools), agent
          permissions (owner, editor, reader), inter-artifact relations,
          and recommended action routes. The index is a queryable model
          for runtime planners, guardrails, and governance tools.
        usage:
          - agent-contracts navigation-index
          - agent-contracts navigation-index --format json
          - agent-contracts navigation-index --artifact api-contracts
          - agent-contracts navigation-index -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
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Output format.
            value_name: format
            schema:
              type: string
              enum: [json, yaml]
              default: json

          - name: artifact
            description: Filter output to a single artifact by ID.
            value_name: id
            schema:
              type: string

          - name: quiet
            description: Suppress informational output.
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: Navigation index built successfully.
            stdout:
              format: '{options.format}'
              schema_note: >-
                Output format depends on --format option. JSON produces a
                ProjectNavigationIndex object; yaml produces its YAML
                representation.

          '1':
            description: Build failed — schema validation error, config error, or resolution failure.
            stderr:
              format: text

      # ── artifact-coverage ────────────────────────────────
      artifact-coverage:
        summary: Measure file coverage by artifact path_patterns definitions.
        description: >-
          Cross-references git ls-files output against compiled artifact
          path_patterns / exclude_patterns to measure what percentage of
          a project's tracked files are covered by artifact definitions.
          Reports uncovered files, overlapping files, and per-artifact
          match counts. Supports CI gating via --min-coverage.
        usage:
          - agent-contracts artifact-coverage
          - agent-contracts artifact-coverage -c agent-contracts.config.yaml
          - agent-contracts artifact-coverage --format json
          - agent-contracts artifact-coverage --min-coverage 80

        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
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: config
            aliases: [c]
            description: Path to agent-contracts.config.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: team
            description: Limit to one team (multi-team config only).
            value_name: id
            schema:
              type: string

          - name: format
            description: Output format.
            value_name: format
            schema:
              type: string
              enum: [text, json]
              default: text

          - name: min-coverage
            description: Minimum coverage percentage; exit 1 if below (for CI gates).
            value_name: number
            schema:
              type: number

        exits:
          '0':
            description: Coverage report generated (and above threshold if --min-coverage specified).
            stdout:
              format: '{options.format}'
              schema_note: >-
                Output format depends on --format option. Text shows
                human-readable coverage report; json produces structured
                ArtifactCoverageReport object.

          '1':
            description: >-
              Coverage below threshold, schema validation failed,
              or unexpected error.
            stderr:
              format: text