cli_contracts: 0.1.0

info:
  title: CLI Contracts CLI
  version: 0.6.0
  description: >-
    Contract definition for the cli-contracts command line tool itself.
    This is a self-referential contract: cli-contracts defines its own interface
    using the CLI Contracts specification.
  license:
    name: MIT
  contact:
    name: foo-log-inc
    url: https://github.com/foo-log-inc/cli-contracts

artifact_slots:
  contract-definitions:
    description: CLI contract YAML files (cli-contract.yaml and external $ref targets)
    direction: read
  config:
    description: cli-contracts.config.yaml configuration file
    direction: read
  generated-code:
    description: Generated TypeScript/Rust/custom code from generators
    direction: write
  generated-docs:
    description: Generated Markdown CLI reference documentation
    direction: write
  cli-source:
    description: CLI source code, README, or help output for suggest command
    direction: read
  audit-report:
    description: LLM audit/analysis result output files
    direction: write

command_sets:
  cli-contracts:
    summary: Contract-first specification and toolchain for CLI interfaces.
    x-stdin: >-
      No command reads from stdin. All inputs are provided via file options
      or positional arguments. Pipeline composition is not supported.

    env:
      GEMINI_API_KEY:
        description: API key for the Gemini adapter (required when --adapter=gemini).
        required: false
        sensitive: true
        requiredWhen: '{options.adapter} == "gemini"'
      OPENAI_API_KEY:
        description: API key for the OpenAI adapter (required when --adapter=openai).
        required: false
        sensitive: true
        requiredWhen: '{options.adapter} == "openai"'
      ANTHROPIC_API_KEY:
        description: API key for the Claude adapter (required when --adapter=claude).
        required: false
        sensitive: true
        requiredWhen: '{options.adapter} == "claude"'

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

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

      - name: format
        aliases: [F]
        description: >-
          Output format for structured results (core commands only).
          Overrides the per-exit declared format at runtime; exit format
          declarations represent the default when this option is not
          explicitly set. Does NOT apply to LLM-powered commands which
          use --report-format instead. Precedence: core commands use
          --format; LLM commands use --report-format; --format is ignored
          by LLM commands.
        value_name: format
        schema:
          type: string
          enum: [yaml, json]
          default: yaml
        x-stability: immutable-default

      - name: quiet
        aliases: [q]
        description: >-
          Suppress informational/verbose output only. Does NOT suppress
          the primary structured stdout (schema guarantees remain valid).
          Only affects supplementary human-readable messages.
        schema:
          type: boolean
          default: false

      - 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:
      # ── init ────────────────────────────────────────────
      init:
        summary: Initialize a contract file or project layout.
        description: >-
          Generates a starter cli-contract.yaml (and optionally
          cli-contracts.config.yaml) in the current directory.
        usage:
          - cli-contracts init
          - cli-contracts init --name foo
          - cli-contracts init --name foo --multi-command-set

        effects:
          risk_level: low
          writes:
            - contract-definitions

        options:
          - name: name
            aliases: [n]
            description: Executable name for the initial command set.
            value_name: name
            schema:
              type: string

          - name: multi-command-set
            aliases: [m]
            description: Scaffold multiple command sets.
            schema:
              type: boolean
              default: false

          - name: output
            aliases: [o]
            description: Output directory.
            value_name: dir
            schema:
              type: string
              default: "."

          - name: with-config
            description: Also generate cli-contracts.config.yaml.
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: Project initialized successfully.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/InitResult'
            files:
              - path: '{stdout.contractFile}'
                required: true
                media_type: application/yaml
                encoding: utf-8
              - path: '{stdout.configFile}'
                required: false
                media_type: application/yaml
                encoding: utf-8

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '4':
            description: Target file already exists.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'


      # ── validate ────────────────────────────────────────
      validate:
        summary: Validate contract files.
        description: >-
          Validates contract syntax, JSON Schema conformance, $ref resolution,
          duplicate command IDs, option aliases, exit codes,
          stream definitions, file schema references,
          and config generator settings.
        usage:
          - cli-contracts validate
          - cli-contracts validate --file cli-contract.yaml
          - cli-contracts validate --strict

        options:
          - name: file
            aliases: [f]
            description: Contract file(s) to validate. Defaults to config input.files.
            value_name: file
            repeatable: true
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

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

          - name: resolve-refs
            description: Resolve and validate external $ref targets.
            schema:
              type: boolean
              default: true

        exits:
          '0':
            description: All contracts are valid.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ValidateResult'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '9':
            description: Validation completed but found errors in the contract.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ValidateResult'
            stderr:
              required: false
              format: json
              schema:
                $ref: '#/components/schemas/Error'


      # ── resolve ────────────────────────────────────────
      resolve:
        summary: Resolve extends chain and dump merged contract.
        description: >-
          Loads a contract with optional extends field, resolves the base
          chain (including merge operators $append and $replace), and outputs
          the fully merged contract document.
        usage:
          - cli-contracts resolve
          - cli-contracts resolve --file overlay.yaml
          - cli-contracts resolve --file overlay.yaml --format json

        options:
          - name: file
            aliases: [f]
            description: Contract file to resolve. Defaults to config input.files.
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: format
            description: Output format for the resolved contract.
            schema:
              type: string
              enum: [yaml, json]
              default: yaml

        exits:
          '0':
            description: Contract resolved successfully.
            stdout:
              format: '{options.format}'
              schema:
                type: object
                description: Fully resolved CLI Contracts document (extends field stripped).

          '1':
            description: Unexpected error (circular extends, merge error, etc.).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'


      # ── generate ────────────────────────────────────────
      generate:
        summary: Run code generators.
        description: >-
          Runs one or more generators defined in cli-contracts.config.yaml.
          If no generator name is given, all enabled generators are run.
        usage:
          - cli-contracts generate
          - cli-contracts generate typescript
          - cli-contracts generate rust
          - cli-contracts generate markdown
          - cli-contracts generate custom-go

        effects:
          risk_level: low
          writes:
            - generated-code
            - generated-docs

        x-agent:
          recommended_before_use:
            - "Run with --dry-run first to preview generated files"

        arguments:
          - name: generators
            index: 0
            required: false
            description: Generator name(s) to run. If omitted, all enabled generators run.
            variadic: true
            schema:
              type: string

        options:
          - name: file
            aliases: [f]
            description: Contract file(s) to use as input.
            value_name: file
            repeatable: true
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: output
            aliases: [o]
            description: Override output directory.
            value_name: dir
            schema:
              type: string

          - name: dry-run
            aliases: [n]
            description: Show what would be generated without writing files.
            schema:
              type: boolean
              default: false

          - name: clean
            description: Remove output directory before generating.
            schema:
              type: boolean
              default: false
            effects:
              risk_level: high
              writes:
                - target: "output directory"
                  description: "removes and recreates output directory before generating"
                  destructive: true

        exits:
          '0':
            description: Generation succeeded.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/GenerateResult'
            files:
              - path: '{stdout.generators[*].files[*]}'
                required: false
                description: Generated output files as listed in GenerateResult.

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments or unknown generator name.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation failed (generation aborted).
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ValidateResult'

          '5':
            description: Generation partially failed.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/GenerateResult'
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'


      # ── docs ────────────────────────────────────────────
      docs:
        summary: Generate Markdown documentation.
        description: >-
          Generates Markdown CLI reference documentation from the contract.
          A simplified interface for the markdown generator; does not support
          --clean or generator selection. Use "cli-contracts generate markdown"
          for full control.
        usage:
          - cli-contracts docs
          - cli-contracts docs --output docs/cli.md
          - cli-contracts docs --dry-run

        effects:
          risk_level: low
          writes:
            - generated-docs

        options:
          - name: file
            aliases: [f]
            description: Contract file(s) to use as input.
            value_name: file
            repeatable: true
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: output
            aliases: [o]
            description: Output file path.
            value_name: file
            schema:
              type: string
            file:
              mode: write
              media_type: text/markdown
              encoding: utf-8

          - name: dry-run
            aliases: [n]
            description: Show what would be generated without writing files.
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: Documentation generated successfully.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/GenerateResult'
            files:
              - path: '{stdout.generators[*].files[*]}'
                required: false
                media_type: text/markdown
                encoding: utf-8
                description: Generated markdown documentation files.

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation failed (generation aborted).
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ValidateResult'


      # ── test ────────────────────────────────────────────
      test:
        summary: Run contract tests.
        description: >-
          Executes contract test cases against a real CLI implementation.
          Uses execution profiles from cli-contracts.config.yaml to invoke commands.
        usage:
          - cli-contracts test
          - cli-contracts test --profile local
          - cli-contracts test --case users.import.success

        effects:
          risk_level: medium
          requires_confirmation: true
          writes:
            - target: "varies (determined by target CLI under test)"
              description: >-
                executes target CLI processes; transitive side effects
                depend on the target CLI and test cases being executed,
                may include filesystem, network, or database operations
              idempotent: false

        options:
          - name: profile
            aliases: [p]
            description: Execution profile to use.
            value_name: name
            schema:
              type: string

          - name: case
            description: Run a specific test case by ID.
            value_name: id
            repeatable: true
            schema:
              type: string

          - name: cases-dir
            description: Directory containing test case YAML files.
            value_name: dir
            schema:
              type: string

          - name: timeout
            aliases: [t]
            description: Timeout per test case in milliseconds.
            value_name: ms
            schema:
              type: integer
              default: 30000

          - name: bail
            description: Stop on first failure.
            schema:
              type: boolean
              default: false

        exits:
          '0':
            description: All tests passed.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/TestResult'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments or missing profile.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation failed (tests aborted).
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ValidateResult'

          '6':
            description: >-
              One or more tests failed. Uses a single failure exit code
              (no partial-success distinction) by design.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/TestResult'


      # ── diff ────────────────────────────────────────────
      diff:
        summary: Compare contract versions and detect breaking changes.
        description: >-
          Compares two contract files (or git revisions) and reports
          additions, removals, modifications, and breaking changes.
          At least one input pair must be provided: either positional
          arguments (old new) or --base/--head options.
        usage:
          - cli-contracts diff old.yaml new.yaml
          - cli-contracts diff --base main --head HEAD --contract-path cli-contract.yaml

        arguments:
          - name: old
            index: 0
            required: false
            description: >-
              Path to the old (base) contract file.
              Can be omitted when using --base/--head.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: new
            index: 1
            required: false
            description: >-
              Path to the new (head) contract file.
              Can be omitted when using --base/--head.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: base
            description: Git ref for the base version (e.g. main, v1.0.0).
            value_name: ref
            schema:
              type: string

          - name: head
            description: Git ref for the head version (e.g. HEAD, feature-branch).
            value_name: ref
            schema:
              type: string

          - name: contract-path
            aliases: [p]
            description: Contract file path within the repository (used with --base/--head).
            value_name: path
            schema:
              type: string
              default: cli-contract.yaml

          - name: breaking-only
            description: Only report breaking changes.
            schema:
              type: boolean
              default: false

          - name: text
            description: >-
              Output human-readable text summary instead of structured data.
              When active, stdout is plain text and does not conform to the
              DiffResult schema. Agents should avoid this option for parsing.
            schema:
              type: boolean
              default: false
            x-agent:
              disablesStructuredOutput: true

        exits:
          '0':
            description: No breaking changes detected (may include non-breaking changes).
            stdout:
              format: '{options.text ? "text" : globalOptions.format}'
              schema:
                $ref: '#/components/schemas/DiffResult'
              schemaNote: Schema applies only when --text is not set.

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '7':
            description: Breaking changes detected.
            stdout:
              format: '{options.text ? "text" : globalOptions.format}'
              schema:
                $ref: '#/components/schemas/DiffResult'
              schemaNote: Schema applies only when --text is not set.

      # ── propose-agent-policy ─────────────────────────────
      propose-agent-policy:
        summary: Detect missing or inconsistent x-agent policies via LLM.
        description: >-
          Analyzes CLI contract commands and proposes x-agent execution
          policies (riskLevel, requiresConfirmation, sideEffects, etc.)
          for commands that lack them. Uses agent-contracts-runtime as
          an optional peer dependency for LLM integration. Overlaps with
          "audit --checks agent-policy"; prefer audit for comprehensive
          review, this command for focused policy generation.
        usage:
          - cli-contracts propose-agent-policy cli-contract.yaml
          - cli-contracts propose-agent-policy --file cli-contract.yaml --adapter mock --show-prompt
          - cli-contracts propose-agent-policy --file cli-contract.yaml --adapter gemini --format json

        arguments:
          - name: contract
            index: 0
            required: false
            description: >-
              Contract file to analyze. Mutually exclusive with --file;
              positional argument takes precedence if both are provided.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

        constraints:
          mutuallyExclusive: [[contract, file]]

        options:
          - name: file
            aliases: [f]
            description: Contract file to analyze (alternative to positional argument).
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

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

          - name: model
            description: Model name to pass to the adapter.
            value_name: name
            schema:
              type: string

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

          - 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: json

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

        effects:
          reads:
            - contract-definitions
          writes:
            - audit-report
          network:
            description: "LLM API calls to configured provider"
            requires_secrets: [GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY]
            idempotent: true

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: [network]
          sideEffectNote: >-
            Makes network calls to the configured LLM provider when adapter is
            not mock. Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]

        exits:
          '0':
            description: Completed without blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid input or configuration.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation/parse failed.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '11':
            description: Runtime dependency missing (agent-contracts-runtime).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── audit ──────────────────────────────────────────
      audit:
        summary: Semantic audit of CLI contract design quality.
        description: >-
          Performs a comprehensive audit of CLI contract design quality
          including responsibility boundaries, exit code consistency,
          output schema coverage, and AI-agent safety metadata.
          Uses agent-contracts-runtime as an optional peer dependency.
        usage:
          - cli-contracts audit cli-contract.yaml
          - cli-contracts audit --file cli-contract.yaml --checks agent-policy
          - cli-contracts audit --file cli-contract.yaml --adapter claude --show-prompt

        arguments:
          - name: contract
            index: 0
            required: false
            description: >-
              Contract file to audit. Mutually exclusive with --file;
              positional argument takes precedence if both are provided.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

        constraints:
          mutuallyExclusive: [[contract, file]]

        options:
          - name: file
            aliases: [f]
            description: Contract file to audit (alternative to positional argument).
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: checks
            description: Audit dimension(s) to run.
            value_name: check
            repeatable: true
            schema:
              type: string
              enum: [agent-policy, responsibility, exit-code, output-schema, breaking-risk]

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

          - name: model
            description: Model name to pass to the adapter.
            value_name: name
            schema:
              type: string

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

          - 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: json

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

        effects:
          reads:
            - contract-definitions
          writes:
            - audit-report
          network:
            description: "LLM API calls to configured provider"
            requires_secrets: [GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY]
            idempotent: true

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: [network]
          sideEffectNote: >-
            Makes network calls to the configured LLM provider when adapter is
            not mock. Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]

        exits:
          '0':
            description: Completed without blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid input or configuration.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation/parse failed.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '11':
            description: Runtime dependency missing (agent-contracts-runtime).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── extract ─────────────────────────────────────────
      extract:
        summary: Extract a subset of the contract for specific commands.
        description: >-
          Extracts one or more commands from a contract file, resolving all
          $ref references inline. Useful for feeding a focused contract subset
          to AI agents or external tooling.
        usage:
          - cli-contracts extract init validate
          - cli-contracts extract --file cli-contract.yaml init
          - cli-contracts extract --all

        arguments:
          - name: commands
            index: 0
            required: false
            description: >-
              Command ID(s) to extract.
              Use dot notation for nested commands (e.g. users.import).
              If omitted, --all must be specified.
            variadic: true
            schema:
              type: string

        options:
          - name: file
            aliases: [f]
            description: Contract file to extract from. Defaults to config input.files.
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: all
            aliases: [a]
            description: Extract all commands.
            schema:
              type: boolean
              default: false

          - name: include-meta
            description: Include extraction metadata (source, timestamp, etc.).
            schema:
              type: boolean
              default: true

        exits:
          '0':
            description: Extraction succeeded.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ExtractResult'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid arguments (no commands specified and --all not set).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation failed.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ValidateResult'

          '8':
            description: One or more requested commands not found.
            stdout:
              format: yaml
              schema:
                $ref: '#/components/schemas/ExtractResult'
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── propose-tests ────────────────────────────────────
      propose-tests:
        summary: Propose contract test cases via LLM analysis.
        description: >-
          Analyzes CLI contract definitions and proposes test cases
          covering normal, error, edge, and safety scenarios.
          Generates test case YAML drafts or an AgentAuditResult
          with coverage-oriented findings.
        usage:
          - cli-contracts propose-tests cli-contract.yaml
          - cli-contracts propose-tests --file cli-contract.yaml --adapter gemini
          - cli-contracts propose-tests --file cli-contract.yaml --show-prompt

        arguments:
          - name: contract
            index: 0
            required: false
            description: >-
              Contract file to analyze. Mutually exclusive with --file;
              positional argument takes precedence if both are provided.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

        constraints:
          mutuallyExclusive: [[contract, file]]

        options:
          - name: file
            aliases: [f]
            description: Contract file to analyze (alternative to positional argument).
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

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

          - name: model
            description: Model name to pass to the adapter.
            value_name: name
            schema:
              type: string

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

          - 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: json

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

        effects:
          reads:
            - contract-definitions
          writes:
            - audit-report
          network:
            description: "LLM API calls to configured provider"
            requires_secrets: [GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY]
            idempotent: true

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: [network]
          sideEffectNote: >-
            Makes network calls to the configured LLM provider when adapter is
            not mock. Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]

        exits:
          '0':
            description: Completed without blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid input or configuration.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation/parse failed.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '11':
            description: Runtime dependency missing (agent-contracts-runtime).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── explain-diff ─────────────────────────────────────
      explain-diff:
        summary: Explain contract diff in human- and agent-readable form.
        description: >-
          Takes a diff result (from cli-contracts diff) and generates
          human-friendly explanations including breaking change impact,
          migration notes, semver suggestions, and release note drafts.
          At least one input pair must be provided: either positional
          arguments (old new) or --base/--head options.
        usage:
          - cli-contracts explain-diff old.yaml new.yaml
          - cli-contracts explain-diff --base main --head HEAD --adapter gemini
          - cli-contracts explain-diff old.yaml new.yaml --show-prompt

        arguments:
          - name: old
            index: 0
            required: false
            description: Path to the old (base) contract file.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

          - name: new
            index: 1
            required: false
            description: Path to the new (head) contract file.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

        options:
          - name: base
            description: Git ref for the base version.
            value_name: ref
            schema:
              type: string

          - name: head
            description: Git ref for the head version.
            value_name: ref
            schema:
              type: string

          - name: contract-path
            aliases: [p]
            description: Contract file path within the repository (used with --base/--head).
            value_name: path
            schema:
              type: string
              default: cli-contract.yaml

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

          - name: model
            description: Model name to pass to the adapter.
            value_name: name
            schema:
              type: string

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

          - 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: json

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

        effects:
          reads:
            - contract-definitions
          writes:
            - audit-report
          network:
            description: "LLM API calls to configured provider"
            requires_secrets: [GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY]
            idempotent: true

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: [network]
          sideEffectNote: >-
            Makes network calls to the configured LLM provider when adapter is
            not mock. Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]

        exits:
          '0':
            description: Completed without blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid input or configuration.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation/parse failed.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '10':
            description: Completed with blocking findings.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '11':
            description: Runtime dependency missing (agent-contracts-runtime).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── check-reference ───────────────────────────────────
      check-reference:
        summary: Check LLM command conformance against the reference specification.
        description: >-
          Verifies whether LLM-powered commands in a target cli-contract.yaml
          conform to the cli-contracts reference specification. Checks standard
          option sets, exit codes, x-agent metadata, output schema conformance
          to the agent-contracts canonical audit result schema (via $ref or
          compatible inline definition), and agent-evidence base properties.
          Performs deterministic pre-analysis and uses LLM for semantic
          evaluation of overall conformance quality.
        usage:
          - cli-contracts check-reference path/to/cli-contract.yaml
          - cli-contracts check-reference --file path/to/cli-contract.yaml --adapter openai
          - cli-contracts check-reference --file path/to/cli-contract.yaml --show-prompt

        arguments:
          - name: contract
            index: 0
            required: false
            description: >-
              Contract file to check. Mutually exclusive with --file;
              positional argument takes precedence if both are provided.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

        constraints:
          mutuallyExclusive: [[contract, file]]

        options:
          - name: file
            aliases: [f]
            description: Contract file to check (alternative to positional argument).
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml
              encoding: utf-8

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

          - name: model
            description: Model name to pass to the adapter.
            value_name: name
            schema:
              type: string

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

          - 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: scope
            description: >-
              What to check. "contract" checks the contract definition against the
              reference spec (default). "implementation" checks that source code
              conforms to the contract. "all" checks both.
            value_name: scope
            schema:
              type: string
              enum: [contract, implementation, all]
              default: contract

          - name: report-format
            description: Output format for the conformance 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

        effects:
          reads:
            - contract-definitions
            - cli-source
          writes:
            - audit-report
          network:
            description: "LLM API calls to configured provider"
            requires_secrets: [GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY]
            idempotent: true

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: [network]
          sideEffectNote: >-
            Makes network calls to the configured LLM provider when adapter is
            not mock. Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]

        exits:
          '0':
            description: All LLM commands conform to the reference specification.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid input or configuration.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation/parse failed.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '10':
            description: Conformance issues found above --fail-on threshold.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '11':
            description: Runtime dependency missing (agent-contracts-runtime).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── suggest ──────────────────────────────────────────
      suggest:
        summary: Generate a contract draft from existing CLI sources.
        description: >-
          Generates a cli-contract.yaml draft from existing CLI sources
          such as README, --help output, or source code. Results require
          human review before adoption. At least one --from-* option must
          be provided.
        usage:
          - cli-contracts suggest --from-readme README.md
          - cli-contracts suggest --from-help help.txt
          - cli-contracts suggest --from-source src/cli.ts
          - cli-contracts suggest --from-readme README.md --adapter gemini

        constraints:
          requiredOneOf: [from-readme, from-help, from-source]

        options:
          - name: from-readme
            description: Path to a README file to extract CLI information from.
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              encoding: utf-8

          - name: from-help
            description: Path to a file containing --help output.
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              encoding: utf-8

          - name: from-source
            description: Path to CLI source code file.
            value_name: file
            schema:
              type: string
            file:
              mode: read
              exists: true
              encoding: utf-8

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

          - name: model
            description: Model name to pass to the adapter.
            value_name: name
            schema:
              type: string

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

          - 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 suggestion 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

        effects:
          reads:
            - contract-definitions
            - cli-source
          writes:
            - audit-report
          network:
            description: "LLM API calls to configured provider"
            requires_secrets: [GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY]
            idempotent: true

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: [network]
          sideEffectNote: >-
            Makes network calls to the configured LLM provider when adapter is
            not mock. Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]

        exits:
          '0':
            description: Suggestion generated successfully.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid input or no source specified.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '3':
            description: Contract validation/parse failed.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '10':
            description: Suggestion generated with blocking issues.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '11':
            description: Runtime dependency missing (agent-contracts-runtime).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── bundle ──────────────────────────────────────────────
      bundle:
        summary: Generate esbuild bundle config for a cli-contracts project via LLM.
        description: >-
          Analyzes a cli-contracts project structure (entry point, dependencies,
          dynamic imports, version handling) and generates a tailored
          esbuild.bundle.mjs build script. The LLM identifies patterns that
          require custom esbuild plugins (obfuscated agent-contracts-runtime
          imports, build-time version inlining, policy-runtime embedding) and
          produces a ready-to-use single-file bundle configuration.
          Results require human review before adoption.
        usage:
          - cli-contracts bundle
          - cli-contracts bundle --project-dir ./my-cli --show-prompt
          - cli-contracts bundle --adapter claude --output esbuild.bundle.mjs

        options:
          - name: project-dir
            aliases: [d]
            description: >-
              Project directory to analyze. Must contain package.json and
              cli-contract.yaml. Defaults to the current working directory.
            value_name: dir
            schema:
              type: string
              default: "."

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

          - name: model
            description: Model name to pass to the adapter.
            value_name: name
            schema:
              type: string

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

          - 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 bundle analysis 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

        effects:
          reads:
            - cli-source
            - config
            - contract-definitions
          writes:
            - audit-report
          network:
            description: "LLM API calls to configured provider"
            requires_secrets: [GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY]
            idempotent: true

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: [network]
          sideEffectNote: >-
            Makes network calls to the configured LLM provider when adapter is
            not mock. Filesystem write only when --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]

        exits:
          '0':
            description: Bundle configuration generated successfully.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '1':
            description: Unexpected error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '2':
            description: Invalid project directory or missing entry point.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '10':
            description: Bundle config generated with blocking issues.
            stdout:
              format: '{options.report-format}'
              schema:
                $ref: 'node_modules/agent-contracts/dsl_base/components.yaml#/schemas/agent-audit-result'

          '11':
            description: Runtime dependency missing (agent-contracts-runtime).
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

          '12':
            description: LLM provider or adapter error.
            stderr:
              format: json
              schema:
                $ref: '#/components/schemas/Error'

      # ── agents ─────────────────────────────────────────────
      agents:
        summary: Output the full resolved agent DSL as structured data.
        description: >-
          Outputs the complete resolved agent-contracts DSL (agents, tasks,
          workflows, handoff_types) embedded in this CLI binary.
          Useful for debugging, external tooling integration, and DSL
          inspection.
        options:
          - name: format
            aliases: [F]
            description: Output format.
            schema:
              type: string
              enum: [yaml, json]
              default: yaml

        exits:
          '0':
            description: DSL output successfully.
            stdout:
              format: text
          '1':
            description: Failed to load embedded DSL.
            stderr:
              format: text

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: []

components:
  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true

    InitResult:
      type: object
      required: [contractFile]
      properties:
        contractFile:
          type: string
          description: Path to the generated cli-contract.yaml.
        configFile:
          type: string
          description: Path to the generated cli-contracts.config.yaml (if --with-config).

    ValidateResult:
      type: object
      required: [valid, errorCount, warningCount, errors, warnings]
      properties:
        valid:
          type: boolean
        errorCount:
          type: integer
          minimum: 0
        warningCount:
          type: integer
          minimum: 0
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Diagnostic'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Diagnostic'

    Diagnostic:
      type: object
      required: [path, message, rule]
      properties:
        path:
          type: string
          description: JSON pointer to the problematic location (e.g. /commandSets/foo/commands/init).
        message:
          type: string
        rule:
          type: string
          description: Validation rule ID (e.g. duplicate-command-id, invalid-exit-code).
        severity:
          type: string
          enum: [error, warning]

    GenerateResult:
      type: object
      required: [generators]
      properties:
        generators:
          type: array
          items:
            $ref: '#/components/schemas/GeneratorOutput'

    GeneratorOutput:
      type: object
      required: [name, status, files]
      properties:
        name:
          type: string
          description: Generator name (e.g. typescript, rust, markdown).
        status:
          type: string
          enum: [success, skipped, failed]
        files:
          type: array
          items:
            type: string
          description: List of generated file paths.
        error:
          type: string
          description: Error message if status is failed.

    TestResult:
      type: object
      required: [total, passed, failed, skipped, cases]
      properties:
        total:
          type: integer
          minimum: 0
        passed:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
        skipped:
          type: integer
          minimum: 0
        durationMs:
          type: integer
          minimum: 0
        cases:
          type: array
          items:
            $ref: '#/components/schemas/TestCaseResult'

    TestCaseResult:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
          description: Test case ID.
        status:
          type: string
          enum: [passed, failed, skipped]
        durationMs:
          type: integer
          minimum: 0
        violations:
          type: array
          items:
            $ref: '#/components/schemas/ContractViolation'

    ContractViolation:
      type: object
      required: [type, message]
      properties:
        type:
          type: string
          enum:
            - exit_code_mismatch
            - stdout_schema_mismatch
            - stderr_schema_mismatch
            - stdout_format_mismatch
            - stderr_format_mismatch
            - file_missing
            - file_schema_mismatch
        message:
          type: string
        expected:
          description: Expected value or schema excerpt.
        actual:
          description: Actual value received.

    ExtractResult:
      type: object
      required: [cli_contracts, info, command_sets]
      description: >-
        A self-contained contract subset with all $ref resolved inline.
        When --include-meta is true, a _meta property is included.
      properties:
        _meta:
          $ref: '#/components/schemas/ExtractMeta'
        cli_contracts:
          type: string
          description: Spec version from the source contract.
        info:
          type: object
          description: Info block from the source contract.
        command_sets:
          type: object
          description: Subset of command sets containing only the requested commands.
        components:
          type: object
          description: Only the schemas referenced by extracted commands.

    ExtractMeta:
      type: object
      required: [source, type, extractedAt, commands]
      properties:
        source:
          type: string
          description: Path to the source contract file.
        type:
          type: string
          const: cli-contracts/extract
        extractedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of extraction.
        specVersion:
          type: string
          description: CLI Contracts spec version from the source.
        commands:
          type: array
          items:
            type: string
          description: List of command IDs that were extracted.

    DiffResult:
      type: object
      required: [hasBreakingChanges, changes]
      properties:
        hasBreakingChanges:
          type: boolean
        breakingCount:
          type: integer
          minimum: 0
        nonBreakingCount:
          type: integer
          minimum: 0
        changes:
          type: array
          items:
            $ref: '#/components/schemas/DiffChange'

    DiffChange:
      type: object
      required: [type, path, breaking, description]
      properties:
        type:
          type: string
          enum: [added, removed, changed]
        path:
          type: string
          description: JSON pointer to the changed location.
        breaking:
          type: boolean
        description:
          type: string