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

info:
  title: artifact-contracts CLI
  version: 0.1.1
  description: >-
    Declarative artifact registry — define file properties, resolve
    paths to artifact IDs, and detect definition overlaps.
    stdout is reserved for primary output (JSON/YAML/text result);
    all diagnostics and progress messages go to stderr.
  license:
    name: MIT
  contact:
    name: foo-log-inc
    url: https://github.com/foo-log-inc/artifact-contracts

artifact_slots:
  artifact-definitions:
    description: artifact-contracts.yaml definitions and config files
    direction: read
  repository-files:
    description: Repository files scanned for path pattern matching and overlap detection
    direction: read
  audit-report:
    description: LLM audit result output files
    direction: write

command_sets:
  artifact-contracts:
    summary: >-
      Artifact registry CLI — validate definitions, resolve artifacts,
      list registered entries, and explain file properties.
    executable: artifact-contracts

    global_options:
      - name: version
        aliases: [V]
        description: Output the version number
        schema:
          type: boolean
      - name: help
        aliases: [h]
        description: Display help for command
        schema:
          type: boolean

    commands:
      validate:
        summary: Validate artifact-contracts definitions
        description: >-
          Validates artifact-contracts.yaml against the schema, checks
          artifact ID naming conventions, ensures path_patterns are
          non-empty, and optionally detects overlapping definitions
          against real repository files.
        options:
          - name: config
            description: Path to artifact-contracts.config.yaml
            value_name: path
          - name: check-files
            description: >-
              Scan repository files to detect path_patterns overlaps
              that static glob analysis cannot fully determine.
              When enabled, reads all files from git ls-files or glob.
            schema:
              type: boolean
        effects:
          risk_level: low
          reads:
            - artifact-definitions
            - repository-files
          execution_mode: normal
        x-agent:
          expected_duration_ms: 5000
          retryable_exit_codes: []
        stdout:
          schema:
            $ref: "#/components/schemas/ValidationResult"
          description: >-
            Validation diagnostics. On exit 0 stdout is empty (diagnostics
            go to stderr). On exit 1/2 with --format json, structured
            diagnostics are written to stdout.
        exits:
          "0":
            description: Validation passed with no errors
          "1":
            description: Schema or naming convention errors detected
          "2":
            description: Overlap detected — same path matches multiple artifacts
          "3":
            description: Config or input file not found / parse error

      resolve:
        summary: Output fully-resolved artifact definitions
        description: >-
          Expands config variables, applies authority-based defaults
          for manual_edit and change_control, and outputs the complete
          resolved DSL. Default format is yaml.
        options:
          - name: config
            description: Path to artifact-contracts.config.yaml
            value_name: path
          - name: format
            description: "Output format (default: yaml)"
            schema:
              type: string
              enum: [yaml, json]
        effects:
          risk_level: low
          reads:
            - artifact-definitions
          execution_mode: normal
        x-agent:
          expected_duration_ms: 2000
          retryable_exit_codes: []
        stdout:
          schema:
            $ref: "#/components/schemas/ResolvedDefinitions"
          description: >-
            Fully resolved artifact definitions with authority-based
            defaults applied. Format varies by --format (yaml default, json).
        exits:
          "0":
            description: Successfully output resolved definitions
          "1":
            description: Error resolving definitions
          "3":
            description: Config or input file not found / parse error

      list:
        summary: List registered artifacts
        description: >-
          Displays all registered artifacts with optional filtering
          by authority. Use --path for simple ID lookup; use explain
          for full governance metadata. Default format is text.
        options:
          - name: config
            description: Path to artifact-contracts.config.yaml
            value_name: path
          - name: authority
            description: Filter by authority type
            schema:
              type: string
              enum: [canonical, derived, generated, control]
          - name: path
            description: >-
              Reverse-lookup — show artifact IDs matching this file
              path. For full governance details, use the explain command.
            value_name: file
          - name: format
            description: "Output format (default: text)"
            schema:
              type: string
              enum: [text, json, yaml]
        effects:
          risk_level: low
          reads:
            - artifact-definitions
          execution_mode: normal
        x-agent:
          expected_duration_ms: 2000
          retryable_exit_codes: []
        stdout:
          schema:
            $ref: "#/components/schemas/ArtifactList"
          description: >-
            List of matching artifacts. Schema applies to --format json
            and --format yaml. Text format is human-readable only.
        exits:
          "0":
            description: Successfully listed artifacts
          "1":
            description: Error reading definitions
          "3":
            description: Config or input file not found / parse error

      explain:
        summary: Explain artifact properties for a file path
        description: >-
          Given a file path, resolves the matching artifact and displays
          its full governance properties — artifact ID, authority,
          manual_edit policy, change_control, and other metadata.
          Useful for humans and LLM agents to understand file
          governance. Default format is text.
        arguments:
          - name: path
            description: File path to explain
            required: true
        options:
          - name: config
            description: Path to artifact-contracts.config.yaml
            value_name: path
          - name: format
            description: "Output format (default: text)"
            schema:
              type: string
              enum: [text, json, yaml]
        effects:
          risk_level: low
          reads:
            - artifact-definitions
          execution_mode: normal
        x-agent:
          expected_duration_ms: 2000
          retryable_exit_codes: []
        stdout:
          schema:
            $ref: "#/components/schemas/ArtifactExplanation"
          description: >-
            Artifact governance metadata for the resolved path.
            Schema applies to --format json and --format yaml.
            Text format is human-readable only.
        exits:
          "0":
            description: Path resolved to an artifact
          "2":
            description: Overlap — path matches multiple artifacts
          "3":
            description: Config or input file not found / parse error
          "4":
            description: Path does not match any registered artifact

      audit:
        summary: LLM-based semantic audit of artifact definitions
        description: >-
          Performs semantic analysis of artifact definitions using LLM
          to identify quality issues that static validation cannot
          detect — naming inconsistencies, missing coverage for common
          file types, authority mismatches, and structural improvements.
        options:
          - name: config
            description: Path to artifact-contracts.config.yaml
            value_name: path
          - name: adapter
            description: LLM adapter to use
            schema:
              type: string
              enum: [mock, openai, claude, gemini]
          - name: model
            description: Model name to pass to the adapter
          - name: show-prompt
            description: Output the constructed prompt without calling the LLM API
            schema:
              type: boolean
          - name: dry-run
            aliases: [n]
            description: Alias for --show-prompt (output prompt without LLM call)
            schema:
              type: boolean
          - name: fail-on
            description: >-
              Minimum severity that causes exit 10. Ordering:
              critical > error > warning > info. For example,
              --fail-on warning exits 10 on warning, error, or critical.
            schema:
              type: string
              enum: [info, warning, error, critical]
          - name: output
            aliases: [o]
            description: Write result to a file instead of stdout
            value_name: file
          - name: report-format
            description: >-
              Output format for the report (default: text).
              LLM commands use --report-format; deterministic
              commands use --format.
            schema:
              type: string
              enum: [text, json, yaml]
          - name: log-file
            aliases: [l]
            description: Write agent progress log to this file path.
            schema:
              type: string
        effects:
          risk_level: medium
          reads:
            - artifact-definitions
          writes:
            - audit-report
          network:
            description: LLM API calls to configured provider
            idempotent: false
          execution_mode: normal
        stdout:
          schema:
            $ref: "#/components/schemas/AgentAuditResult"
          description: >-
            Structured audit result conforming to the AgentAuditResult
            schema. Format varies by --report-format (json, yaml, text).
        x-agent:
          dslTask: audit-artifact-definitions
          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]
          recommendedBeforeUse:
            - "Run with --show-prompt first to preview the prompt"
        exits:
          "0":
            description: Audit completed — no findings above threshold
          "1":
            description: General / transient error
          "3":
            description: Config or input file not found / parse error
          "10":
            description: Findings detected above --fail-on threshold
          "11":
            description: agent-contracts-runtime is not installed
          "12":
            description: Adapter initialization error (missing API key, etc.)

      discover:
        summary: LLM-based artifact discovery from project file structure
        description: >-
          Analyzes the project file structure using LLM to generate or update
          artifact-contracts.yaml definitions. In init mode (no existing file),
          creates a new registry from scratch. In update mode (existing file),
          proposes additional artifact definitions and trace link rules for
          uncovered files.
        options:
          - name: adapter
            description: LLM adapter to use
            schema:
              type: string
              enum: [mock, openai, claude, gemini]
          - name: model
            description: Model name to pass to the adapter
          - name: show-prompt
            description: Output the constructed prompt without calling the LLM API
            schema:
              type: boolean
          - name: dry-run
            aliases: [n]
            description: Alias for --show-prompt (output prompt without LLM call)
            schema:
              type: boolean
          - name: write
            aliases: [w]
            description: Write the generated YAML directly to artifact-contracts.yaml
            schema:
              type: boolean
          - name: output
            aliases: [o]
            description: Write result to a specific file path instead of stdout
            value_name: file
          - name: report-format
            description: "Output format (default: yaml)"
            schema:
              type: string
              enum: [yaml, json]
          - name: log-file
            aliases: [l]
            description: Write agent progress log to this file path.
            schema:
              type: string
        effects:
          risk_level: medium
          reads:
            - artifact-definitions
            - repository-files
          writes:
            - artifact-definitions
          network:
            description: LLM API calls to configured provider
            idempotent: false
          execution_mode: normal
        stdout:
          schema:
            $ref: "#/components/schemas/DiscoverResult"
          description: >-
            Generated artifact-contracts.yaml content or structured discovery result.
        x-agent:
          dslTask: discover-artifact-definitions
          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 --write or --output is specified.
          safeDryRunOption: show-prompt
          expectedDurationMs: 120000
          retryableExitCodes: [1, 12]
          recommendedBeforeUse:
            - "Run with --show-prompt first to preview the prompt"
        exits:
          "0":
            description: Discovery completed successfully
          "1":
            description: General / transient error
          "3":
            description: File system read error
          "11":
            description: agent-contracts-runtime is not installed
          "12":
            description: Adapter initialization error (missing API key, etc.)

      # ── 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: []

    env:
      OPENAI_API_KEY:
        description: >-
          OpenAI API key. Required when --adapter openai is selected.
        required: false
      ANTHROPIC_API_KEY:
        description: >-
          Anthropic API key. Required when --adapter claude is selected.
        required: false
      GEMINI_API_KEY:
        description: >-
          Google Gemini API key. Required when --adapter gemini is selected.
        required: false

components:
  schemas:
    AgentFinding:
      type: object
      properties:
        id:
          type: string
        severity:
          type: string
          enum: [critical, error, warning, info]
        category:
          type: string
        title:
          type: string
        description:
          type: string
        location:
          type: string
        target:
          type: string
        recommendation:
          type: string
        evidence:
          type: array
          items:
            $ref: "#/components/schemas/AgentEvidence"
      required: [id, severity, category, title, description]

    AgentAuditResult:
      type: object
      properties:
        summary:
          type: string
        risk_level:
          type: string
          enum: [none, low, medium, high, critical]
        findings:
          type: array
          items:
            $ref: "#/components/schemas/AgentFinding"
        recommended_actions:
          type: array
          items:
            $ref: "#/components/schemas/AgentRecommendedAction"
        metadata:
          type: object
          properties:
            total_artifacts:
              type: integer
            analyzed_artifacts:
              type: integer
            analysis_scope:
              type: string
      required: [summary, risk_level, findings, recommended_actions]

    AgentEvidence:
      type: object
      properties:
        kind:
          type: string
          enum: [schema, code, config, runtime, doc]
        target:
          type: string
        location:
          type: string
        excerpt:
          type: string
        reasoning:
          type: string
      required: [kind]

    AgentRecommendedAction:
      type: object
      properties:
        action:
          type: string
        priority:
          type: string
          enum: [high, medium, low]
        description:
          type: string
      required: [action, priority]

    ResolvedDefinitions:
      type: object
      description: Output of the resolve command
      properties:
        artifact_contracts:
          type: string
        system:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
          required: [id]
        artifacts:
          type: object
          description: Map of artifact ID to resolved artifact definition
          additionalProperties:
            $ref: "#/components/schemas/ArtifactDefinition"
      required: [artifact_contracts, system, artifacts]

    ArtifactExplanation:
      type: object
      description: Output of the explain command (json/yaml format)
      properties:
        id:
          type: string
        type:
          type: string
        authority:
          type: string
        manual_edit:
          type: string
        change_control:
          type: string
        visibility:
          type: string
        description:
          type: string
        path_patterns:
          type: array
          items:
            type: string
        exclude_patterns:
          type: array
          items:
            type: string
      required: [id, type, authority, manual_edit, change_control]

    ArtifactDefinition:
      type: object
      description: A single resolved artifact definition
      properties:
        type:
          type: string
        authority:
          type: string
          enum: [canonical, derived, generated, control]
        manual_edit:
          type: string
          enum: [allowed, discouraged, forbidden]
        change_control:
          type: string
          enum: [none, approval-required, regeneration-required]
        visibility:
          type: string
          enum: [public, internal, private]
        description:
          type: string
        path_patterns:
          type: array
          items:
            type: string
        exclude_patterns:
          type: array
          items:
            type: string
        states:
          type: array
          items:
            type: string
      required: [type, authority, manual_edit, change_control, visibility, path_patterns]

    ArtifactList:
      type: object
      description: Output of the list command (json/yaml format)
      properties:
        artifacts:
          type: object
          description: Map of artifact ID to resolved artifact definition
          additionalProperties:
            $ref: "#/components/schemas/ArtifactDefinition"

    DiscoverResult:
      type: object
      description: Output of the discover command
      properties:
        mode:
          type: string
          enum: [init, update]
        artifact_contracts_yaml:
          type: string
          description: Generated YAML content
        decisions:
          type: array
          items:
            type: object
            properties:
              artifact_id:
                type: string
              reasoning:
                type: string
            required: [artifact_id, reasoning]
        trace_decisions:
          type: array
          items:
            type: object
            properties:
              link_id:
                type: string
              reasoning:
                type: string
            required: [link_id, reasoning]
        uncategorized_files:
          type: array
          items:
            type: string
        suggestions:
          type: array
          items:
            type: string
      required: [mode, artifact_contracts_yaml]

    ValidationResult:
      type: object
      description: Output of the validate command (json format, on error)
      properties:
        valid:
          type: boolean
        diagnostics:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
              severity:
                type: string
                enum: [error, warning]
            required: [message, severity]
        overlaps:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              matching_artifacts:
                type: array
                items:
                  type: string
            required: [path, matching_artifacts]
      required: [valid, diagnostics, overlaps]