cli-contract.yaml

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

info:
  title: micro-contracts CLI
  version: 0.17.10
  description: >-
    Contract-first OpenAPI toolchain for TypeScript Web/API systems.
    Generates contract packages, server routes, and frontend clients
    from OpenAPI specifications with enforceable guardrails.
  license:
    name: MIT
  contact:
    name: foo-log-inc
    url: https://github.com/foo-log-inc/micro-contracts

artifact_slots:
  openapi-specs:
    direction: read
    description: OpenAPI specification files
  config:
    direction: read
    description: micro-contracts.config.yaml configuration
  generated-packages:
    direction: write
    description: Generated contract packages, server routes, and frontend clients
  guardrails-config:
    direction: read
    description: guardrails.yaml configuration
  manifest:
    direction: write
    description: Generated manifest (.generated-manifest.json)

command_sets:
  micro-contracts:
    summary: Contract-first OpenAPI toolchain for TypeScript.
    executable: micro-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:
      # ── generate ─────────────────────────────────────
      generate:
        summary: Generate code from OpenAPI specifications.
        description: >-
          Loads the multi-module config, applies overlays, runs Spectral
          linting (unless skipped), and generates contract packages, server
          routes, frontend clients, and documentation from OpenAPI specs.
          Supports input-hash caching to skip unnecessary regeneration.
        usage:
          - micro-contracts generate
          - micro-contracts generate -c my-config.yaml
          - micro-contracts generate -m core,billing
          - micro-contracts generate --contracts-only
          - micro-contracts generate --force

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

          - name: module
            aliases: [m]
            description: Module names, comma-separated. Generates all modules if omitted.
            value_name: names
            schema:
              type: string

          - name: contracts-only
            description: Generate contract packages only.
            schema:
              type: boolean
              default: false

          - name: server-only
            description: Generate server routes only.
            schema:
              type: boolean
              default: false

          - name: frontend-only
            description: Generate frontend clients only.
            schema:
              type: boolean
              default: false

          - name: docs-only
            description: Generate documentation only.
            schema:
              type: boolean
              default: false

          - name: skip-lint
            description: Skip Spectral linting before generation.
            schema:
              type: boolean
              default: false

          - name: manifest
            description: >-
              Generate manifest after generation. Enabled by default when
              guardrails.yaml has a generated section. Use --no-manifest to disable.
            schema:
              type: boolean
              default: true

          - name: manifest-dir
            description: Directory for manifest output.
            value_name: path
            schema:
              type: string
              default: packages/

          - name: force
            description: Bypass input hash cache and always regenerate.
            schema:
              type: boolean
              default: false

          - name: cache
            description: >-
              Enable input hash caching. Enabled by default.
              Use --no-cache to disable both reading and writing cache.
            schema:
              type: boolean
              default: true

        exits:
          '0':
            description: Generation succeeded.
            stdout:
              format: text
            files:
              - path: packages/contract/{module}/**/*.ts
                required: true
                media_type: text/x-typescript
                encoding: utf-8
                description: Generated contract packages.
              - path: packages/contract-published/{module}/**/*.ts
                required: false
                media_type: text/x-typescript
                encoding: utf-8
                description: Generated public contract packages.

          '1':
            description: Generation failed (config not found, spec invalid, or generation error).
            stderr:
              format: text

        x-agent:
          risk_level: medium
          requires_confirmation: false
          idempotent: true
          side_effects:
            - file_write
          recommended_before_use:
            - Ensure micro-contracts.config.yaml exists.
            - Verify OpenAPI specs are valid.

      # ── lint ─────────────────────────────────────────
      lint:
        summary: Lint OpenAPI specification.
        description: >-
          Validates an OpenAPI specification for x-micro-contracts extension
          violations and structural issues using Spectral rules.
        usage:
          - micro-contracts lint spec/core/openapi/core.yaml
          - micro-contracts lint spec/core/openapi/core.yaml --strict

        arguments:
          - name: input
            index: 0
            required: true
            description: Path to OpenAPI spec file.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: strict
            description: Treat warnings as errors.
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: Spec is valid. No lint errors found.
            stdout:
              format: text

          '1':
            description: Lint failed. Errors or warnings (in strict mode) found.
            stderr:
              format: text

        x-agent:
          risk_level: low
          requires_confirmation: false
          idempotent: true
          side_effects: []

      # ── init ─────────────────────────────────────────
      init:
        summary: Initialize a new module structure with starter templates.
        description: >-
          Creates the directory structure, starter Handlebars templates,
          shared schemas, Spectral rules, and optional config file for
          a new module. Can also process an existing OpenAPI spec to
          auto-add x-micro-contracts extensions.
        usage:
          - micro-contracts init core
          - micro-contracts init core --openapi path/to/spec.yaml
          - micro-contracts init myScreens --screens
          - micro-contracts init users --skip-templates

        arguments:
          - name: name
            index: 0
            required: true
            description: Module name (e.g., core, users, billing).
            schema:
              type: string

        options:
          - name: dir
            aliases: [d]
            description: Base directory for server/frontend files.
            value_name: path
            schema:
              type: string
              default: src

          - name: openapi
            aliases: [i]
            description: OpenAPI spec to process (auto-adds x-micro-contracts-service/method extensions).
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: output
            aliases: [o]
            description: Output path for processed OpenAPI. Defaults to spec/{name}/openapi/{name}.yaml.
            value_name: path
            schema:
              type: string

          - name: skip-templates
            description: Skip creating starter Handlebars templates.
            schema:
              type: boolean
              default: false

          - name: screens
            description: Initialize as screen spec module (generates screen templates and starter spec).
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: Module initialized successfully.
            stdout:
              format: text
            files:
              - path: spec/{name}/openapi/{name}.yaml
                required: false
                media_type: application/yaml
                encoding: utf-8
                description: OpenAPI spec (created when --openapi provided or --screens used).
              - path: spec/default/templates/*.hbs
                required: false
                media_type: text/x-handlebars-template
                encoding: utf-8
                description: Starter Handlebars templates.
              - path: micro-contracts.config.yaml
                required: false
                media_type: application/yaml
                encoding: utf-8
                description: Config file (created if not already present).

          '1':
            description: Initialization failed (OpenAPI file not found or write error).
            stderr:
              format: text

        x-agent:
          risk_level: medium
          requires_confirmation: false
          idempotent: true
          side_effects:
            - file_write
            - directory_create

      # ── check ────────────────────────────────────────
      check:
        summary: Run guardrail checks.
        description: >-
          Runs AI guardrail checks against generated code and config.
          Supports gating (1-5), selective check execution, auto-fix,
          and CI integration via changed-files input.
        usage:
          - micro-contracts check
          - micro-contracts check --gate 1,2
          - micro-contracts check --only drift,manifest
          - micro-contracts check --fix
          - micro-contracts check --list
          - micro-contracts check --list-gates

        options:
          - name: only
            description: Run only specific checks (comma-separated check names).
            value_name: checks
            schema:
              type: string

          - name: skip
            description: Skip specific checks (comma-separated check names).
            value_name: checks
            schema:
              type: string

          - name: gate
            description: Run checks for specific gates only (comma-separated, 1-5).
            value_name: gates
            schema:
              type: string

          - name: verbose
            aliases: [v]
            description: Enable verbose output.
            schema:
              type: boolean
              default: false

          - name: fix
            description: Auto-fix issues where possible.
            schema:
              type: boolean
              default: false

          - name: guardrails
            aliases: [g]
            description: Path to guardrails.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: generated-dir
            aliases: [d]
            description: Path to generated files directory.
            value_name: path
            schema:
              type: string
              default: packages/

          - name: changed-files
            description: Path to file containing list of changed files (for CI).
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: text/plain
              encoding: utf-8

          - name: list
            description: List available checks and exit.
            schema:
              type: boolean
              default: false

          - name: list-gates
            description: List available gates and exit.
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: All checks passed (or --list/--list-gates output).
            stdout:
              format: text

          '1':
            description: One or more checks failed.
            stdout:
              format: text
            stderr:
              required: false
              format: text

        x-agent:
          risk_level: low
          requires_confirmation: false
          idempotent: true
          side_effects: []
          recommended_before_use:
            - Run generate first so generated files exist.

      # ── pipeline ─────────────────────────────────────
      pipeline:
        summary: Run full guardrails pipeline.
        description: >-
          Executes the complete contract-first pipeline in order:
          Gate 1,2 (pre-generation checks) → Generate → Gate 3,4,5
          (post-generation checks). Supports --continue-on-error to
          run all steps regardless of failures.
        usage:
          - micro-contracts pipeline
          - micro-contracts pipeline --verbose
          - micro-contracts pipeline --continue-on-error
          - micro-contracts pipeline --contracts-only --skip-lint

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

          - name: verbose
            aliases: [v]
            description: Enable verbose output (show detailed logs).
            schema:
              type: boolean
              default: false

          - name: skip
            description: Skip specific checks (comma-separated).
            value_name: checks
            schema:
              type: string

          - name: continue-on-error
            description: Continue running even if a step fails.
            schema:
              type: boolean
              default: false

          - name: guardrails
            aliases: [g]
            description: Path to guardrails.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: generated-dir
            aliases: [d]
            description: Path to generated files directory.
            value_name: path
            schema:
              type: string
              default: packages/

          - name: manifest
            description: >-
              Generate manifest after generation. Enabled by default.
              Use --no-manifest to disable.
            schema:
              type: boolean
              default: true

          - name: skip-lint
            description: Skip Spectral linting before generation.
            schema:
              type: boolean
              default: false

          - name: contracts-only
            description: Generate contract packages only.
            schema:
              type: boolean
              default: false

          - name: server-only
            description: Generate server routes only.
            schema:
              type: boolean
              default: false

          - name: frontend-only
            description: Generate frontend clients only.
            schema:
              type: boolean
              default: false

          - name: docs-only
            description: Generate documentation only.
            schema:
              type: boolean
              default: false

          - name: force
            description: Bypass input hash cache and always regenerate.
            schema:
              type: boolean
              default: false

          - name: cache
            description: >-
              Enable input hash caching. Enabled by default.
              Use --no-cache to disable both reading and writing cache.
            schema:
              type: boolean
              default: true

        exits:
          '0':
            description: Pipeline completed successfully. All gates passed and generation succeeded.
            stdout:
              format: text

          '1':
            description: Pipeline failed. One or more steps had errors.
            stdout:
              format: text
            stderr:
              required: false
              format: text

        x-agent:
          risk_level: medium
          requires_confirmation: false
          idempotent: true
          side_effects:
            - file_write
          recommended_before_use:
            - Ensure micro-contracts.config.yaml and guardrails.yaml exist.
            - Verify OpenAPI specs are valid.

      # ── deps ─────────────────────────────────────────
      deps:
        summary: Analyze module dependencies.
        description: >-
          Reads x-micro-contracts-depend-on declarations from OpenAPI specs
          and config dependsOn fields. Can output dependency graphs (Mermaid),
          impact analysis, reverse lookups, and validation results.
        usage:
          - micro-contracts deps
          - micro-contracts deps --graph
          - micro-contracts deps --module billing
          - micro-contracts deps --impact core.User.getUsers
          - micro-contracts deps --who-depends-on core
          - micro-contracts deps --validate

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

          - name: module
            aliases: [m]
            description: Module to analyze.
            value_name: name
            schema:
              type: string

          - name: graph
            description: Output dependency graph in Mermaid format.
            schema:
              type: boolean
              default: false

          - name: impact
            description: Analyze impact of changing a specific API (e.g., core.User.getUsers).
            value_name: ref
            schema:
              type: string

          - name: who-depends-on
            description: Find modules that depend on a specific API.
            value_name: ref
            schema:
              type: string

          - name: validate
            description: Validate dependencies against OpenAPI declarations.
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: Dependency analysis completed successfully.
            stdout:
              format: text

          '1':
            description: Analysis failed or validation errors found.
            stderr:
              format: text

        x-agent:
          risk_level: low
          requires_confirmation: false
          idempotent: true
          side_effects: []

      # ── insights ─────────────────────────────────────
      insights:
        summary: Emit ExternalInsight JSON for agent-contracts-analyzer.
        description: >-
          Reads x-micro-contracts-depend-on from OpenAPI specs and outputs
          structured dependency edges and anchor mappings as JSON on stdout.
          Used by agent-contracts-analyzer CommandProvider integration.
        usage:
          - micro-contracts insights --format json
          - micro-contracts insights --format json --project-root .

        options:
          - name: format
            description: Output format (json only).
            value_name: format
            schema:
              type: string
              default: json

          - name: project-root
            description: Project root directory containing micro-contracts.config.yaml.
            value_name: path
            schema:
              type: string
              default: .

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

        exits:
          '0':
            description: ExternalInsight JSON written to stdout.
            stdout:
              format: json

          '1':
            description: Insights generation failed.
            stderr:
              format: text

        x-agent:
          risk_level: low
          requires_confirmation: false
          idempotent: true
          side_effects: []

      # ── guardrails-init ──────────────────────────────
      guardrails-init:
        path: [guardrails-init]
        summary: Create a guardrails.yaml configuration file.
        description: >-
          Generates a starter guardrails.yaml with default check
          configuration. Fails if the target file already exists.
        usage:
          - micro-contracts guardrails-init
          - micro-contracts guardrails-init -o custom-guardrails.yaml

        options:
          - name: output
            aliases: [o]
            description: Output path for guardrails.yaml.
            value_name: path
            schema:
              type: string
              default: guardrails.yaml

        exits:
          '0':
            description: guardrails.yaml created successfully.
            stdout:
              format: text
            files:
              - path: '{options.output}'
                required: true
                media_type: application/yaml
                encoding: utf-8

          '1':
            description: Failed to create (file already exists or write error).
            stderr:
              format: text

        x-agent:
          risk_level: low
          requires_confirmation: false
          idempotent: false
          side_effects:
            - file_write

      # ── manifest ─────────────────────────────────────
      manifest:
        summary: Generate or verify manifest for generated artifacts.
        description: >-
          Scans a directory of generated files and produces a
          .generated-manifest.json containing file hashes. In verify
          mode, checks that existing files match the manifest.
        usage:
          - micro-contracts manifest
          - micro-contracts manifest -d packages/
          - micro-contracts manifest --verify
          - micro-contracts manifest -o custom-manifest.json

        options:
          - name: dir
            aliases: [d]
            description: Directory to scan.
            value_name: path
            schema:
              type: string
              default: packages/

          - name: verify
            description: Verify existing manifest instead of generating.
            schema:
              type: boolean
              default: false

          - name: output
            aliases: [o]
            description: Output manifest path. Defaults to {dir}/.generated-manifest.json.
            value_name: path
            schema:
              type: string

        exits:
          '0':
            description: Manifest generated or verification passed.
            stdout:
              format: text
            files:
              - path: '{options.dir}/.generated-manifest.json'
                required: false
                media_type: application/json
                encoding: utf-8
                description: Generated manifest (not created in verify mode).

          '1':
            description: Directory not found, manifest generation failed, or verification failed.
            stderr:
              format: text

        x-agent:
          risk_level: low
          requires_confirmation: false
          idempotent: true
          side_effects:
            - file_write

      # ── audit-openapi ──────────────────────────────
      audit-openapi:
        path: [audit-openapi]
        summary: Run LLM-based OpenAPI design quality audit.
        description: >-
          Performs a semantic review of OpenAPI specification design quality
          using an LLM agent. Evaluates path design, module boundary alignment,
          schema bloat, CRUD vs use-case orientation, and cross-cutting
          concern coverage. Requires agent-contracts-runtime.
        usage:
          - micro-contracts audit-openapi
          - micro-contracts audit-openapi -m core
          - micro-contracts audit-openapi --adapter claude --report-format text
          - micro-contracts audit-openapi --show-prompt

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

          - name: module
            aliases: [m]
            description: Module name to audit (default is all modules).
            value_name: name
            schema:
              type: string

          - name: adapter
            aliases: [a]
            description: SDK adapter to use for LLM execution.
            value_name: name
            schema:
              type: string
              enum: [claude, openai, gemini, mock]

          - name: model
            description: LLM model override.
            value_name: name
            schema:
              type: string

          - name: fail-on
            description: Minimum severity that causes a non-zero exit.
            value_name: level
            schema:
              type: string
              enum: [warning, error, critical]
              default: error

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

          - name: report-format
            description: Output format for the audit report.
            value_name: fmt
            schema:
              type: string
              enum: [json, text, yaml]
              default: text

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

        exits:
          '0':
            description: Audit completed, no blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/OpenApiAuditResult'

          '1':
            description: Unexpected error.
            stderr:
              format: text

          '3':
            description: Input validation failed (config not found, spec invalid).
            stderr:
              format: text

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/OpenApiAuditResult'

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

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: text

        effects:
          reads: [openapi-specs, config]
          writes: []
          network:
            description: LLM API calls when adapter is not mock
            requires_secrets: []
            idempotent: true

        x-agent:
          dsl_task: audit-openapi-design
          expectedDurationMs: 120000
          retryableExitCodes: [12]

      # ── review-published ───────────────────────────
      review-published:
        path: [review-published]
        summary: Review published API surface for internal leakage.
        description: >-
          Analyzes the published (public-facing) API specification for
          internal type leakage, backward compatibility risks, and
          x-micro-contracts-non-exportable violations.
          Requires agent-contracts-runtime.
        usage:
          - micro-contracts review-published
          - micro-contracts review-published -m billing
          - micro-contracts review-published --adapter claude --report-format json

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

          - name: module
            aliases: [m]
            description: Module name to review (default is all modules).
            value_name: name
            schema:
              type: string

          - name: adapter
            aliases: [a]
            description: SDK adapter to use for LLM execution.
            value_name: name
            schema:
              type: string
              enum: [claude, openai, gemini, mock]

          - name: model
            description: LLM model override.
            value_name: name
            schema:
              type: string

          - name: fail-on
            description: Minimum severity that causes a non-zero exit.
            value_name: level
            schema:
              type: string
              enum: [warning, error, critical]
              default: error

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

          - name: report-format
            description: Output format for the review report.
            value_name: fmt
            schema:
              type: string
              enum: [json, text, yaml]
              default: text

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

        exits:
          '0':
            description: Review completed, no blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/PublishedReviewResult'

          '1':
            description: Unexpected error.
            stderr:
              format: text

          '3':
            description: Input validation failed.
            stderr:
              format: text

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/PublishedReviewResult'

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

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: text

        effects:
          reads: [openapi-specs, config, generated-packages]
          writes: []
          network:
            description: LLM API calls when adapter is not mock
            requires_secrets: []
            idempotent: true

        x-agent:
          dsl_task: audit-published-api
          expectedDurationMs: 120000
          retryableExitCodes: [12]

      # ── propose-overlays ───────────────────────────
      propose-overlays:
        path: [propose-overlays]
        summary: Propose cross-cutting overlay candidates.
        description: >-
          Analyzes the OpenAPI specification and proposes cross-cutting
          overlay candidates for authentication, tenancy, rate limiting,
          audit logging, and other patterns. Verifies proposals do not
          conflict with existing overlay definitions.
          Requires agent-contracts-runtime.
        usage:
          - micro-contracts propose-overlays
          - micro-contracts propose-overlays -m core
          - micro-contracts propose-overlays --adapter openai --report-format json

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

          - name: module
            aliases: [m]
            description: Module name to analyze (default is all modules).
            value_name: name
            schema:
              type: string

          - name: adapter
            aliases: [a]
            description: SDK adapter to use for LLM execution.
            value_name: name
            schema:
              type: string
              enum: [claude, openai, gemini, mock]

          - name: model
            description: LLM model override.
            value_name: name
            schema:
              type: string

          - name: fail-on
            description: Minimum severity that causes a non-zero exit.
            value_name: level
            schema:
              type: string
              enum: [warning, error, critical]
              default: error

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

          - name: report-format
            description: Output format for the proposal report.
            value_name: fmt
            schema:
              type: string
              enum: [json, text, yaml]
              default: json

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

        exits:
          '0':
            description: Proposal generated successfully.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/OverlayProposalResult'

          '1':
            description: Unexpected error.
            stderr:
              format: text

          '3':
            description: Input validation failed.
            stderr:
              format: text

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/OverlayProposalResult'

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

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: text

        effects:
          reads: [openapi-specs, config]
          writes: []
          network:
            description: LLM API calls when adapter is not mock
            requires_secrets: []
            idempotent: true

        x-agent:
          dsl_task: propose-overlay-candidates
          expectedDurationMs: 120000
          retryableExitCodes: [12]

      # ── audit-guardrails ───────────────────────────
      audit-guardrails:
        path: [audit-guardrails]
        summary: Audit guardrails configuration for drift and lint coverage.
        description: >-
          Checks that guardrails.yaml configuration covers all generated
          output directories for drift detection and that OpenAPI lint
          rules are properly configured. Note: file permission and
          editing checks have been moved to artifact-contracts.
          Requires agent-contracts-runtime.
        usage:
          - micro-contracts audit-guardrails
          - micro-contracts audit-guardrails --adapter mock --report-format json

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

          - name: guardrails
            aliases: [g]
            description: Path to guardrails.yaml.
            value_name: path
            schema:
              type: string
            file:
              mode: read
              exists: false
              media_type: application/yaml
              encoding: utf-8

          - name: adapter
            aliases: [a]
            description: SDK adapter to use for LLM execution.
            value_name: name
            schema:
              type: string
              enum: [claude, openai, gemini, mock]

          - name: model
            description: LLM model override.
            value_name: name
            schema:
              type: string

          - name: fail-on
            description: Minimum severity that causes a non-zero exit.
            value_name: level
            schema:
              type: string
              enum: [warning, error, critical]
              default: error

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

          - name: report-format
            description: Output format for the audit report.
            value_name: fmt
            schema:
              type: string
              enum: [json, text, yaml]
              default: text

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

        exits:
          '0':
            description: Audit completed, no blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/GuardrailsAuditResult'

          '1':
            description: Unexpected error.
            stderr:
              format: text

          '3':
            description: Input validation failed (guardrails.yaml not found).
            stderr:
              format: text

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: '#/components/schemas/GuardrailsAuditResult'

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

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: text

        effects:
          reads: [guardrails-config, config]
          writes: []
          network:
            description: LLM API calls when adapter is not mock
            requires_secrets: []
            idempotent: true

        x-agent:
          dsl_task: audit-guardrails-coverage
          expectedDurationMs: 120000
          retryableExitCodes: [12]

components:
  schemas:
    # ── AI Agent Interoperability Schemas ──────────────────
    AgentEvidence:
      $ref: 'components.yaml#/schemas/agent-evidence'
    AgentFinding:
      $ref: 'components.yaml#/schemas/agent-finding'
    AgentRecommendedAction:
      $ref: 'components.yaml#/schemas/agent-recommended-action'
    OpenApiAuditResult:
      $ref: 'components.yaml#/schemas/agent-audit-result'

    PublishedReviewResult:
      type: object
      description: >-
        Result from review-published command. Contains published endpoint
        enumeration and internal type leakage analysis.
      allOf:
        - $ref: 'components.yaml#/schemas/agent-audit-result'
        - type: object
          required: [publishedEndpoints, leakedInternalTypes]
          properties:
            publishedEndpoints:
              type: array
              items:
                type: object
                required: [operationId, path, method]
                properties:
                  operationId:
                    type: string
                  path:
                    type: string
                  method:
                    type: string
            leakedInternalTypes:
              type: array
              items:
                type: object
                required: [schemaName, referencedBy, reason]
                properties:
                  schemaName:
                    type: string
                  referencedBy:
                    type: string
                  reason:
                    type: string

    OverlayProposalResult:
      type: object
      description: >-
        Result from propose-overlays command. Contains overlay candidate
        proposals with endpoint, type, rationale, and suggested config.
      allOf:
        - $ref: 'components.yaml#/schemas/agent-audit-result'
        - type: object
          required: [overlayCandidates]
          properties:
            overlayCandidates:
              type: array
              items:
                type: object
                required: [endpoint, overlayType, rationale]
                properties:
                  endpoint:
                    type: string
                  overlayType:
                    type: string
                    enum: [auth, tenancy, rateLimit, auditLog, custom]
                  rationale:
                    type: string
                  suggestedConfig:
                    type: object
                    additionalProperties: true

    GuardrailsAuditResult:
      type: object
      description: >-
        Result from audit-guardrails command. Contains drift detection
        and lint rule coverage analysis.
      allOf:
        - $ref: 'components.yaml#/schemas/agent-audit-result'
        - type: object
          required: [coveredPaths, uncoveredPaths]
          properties:
            coveredPaths:
              type: array
              items:
                type: string
            uncoveredPaths:
              type: array
              items:
                type: string