# artifact-contracts CLI

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.

**Version:** 0.1.1

## Table of Contents

- [artifact-contracts](#artifact-contracts)
  - [validate](#artifact-contracts-validate)
  - [resolve](#artifact-contracts-resolve)
  - [list](#artifact-contracts-list)
  - [explain](#artifact-contracts-explain)
  - [audit](#artifact-contracts-audit)
  - [discover](#artifact-contracts-discover)
  - [agents](#artifact-contracts-agents)

---

## artifact-contracts

Artifact registry CLI — validate definitions, resolve artifacts, list registered entries, and explain file properties.

### Global Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--version` | -V | No |  | Output the version number |
| `--help` | -h | No |  | Display help for command |

### Environment Variables

| Variable | Description |
|---|---|
| `OPENAI_API_KEY` | OpenAI API key. Required when --adapter openai is selected. |
| `ANTHROPIC_API_KEY` | Anthropic API key. Required when --adapter claude is selected. |
| `GEMINI_API_KEY` | Google Gemini API key. Required when --adapter gemini is selected. |

### validate

Validate artifact-contracts definitions

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.

**Usage:**

```
artifact-contracts validate [--config] [--check-files]
```

#### Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
| `--check-files` |  | No |  | 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. |

#### Exit Codes

**Exit 0:** Validation passed with no errors

**Exit 1:** Schema or naming convention errors detected

**Exit 2:** Overlap detected — same path matches multiple artifacts

**Exit 3:** Config or input file not found / parse error

#### Extensions

```yaml
x-agent: 
  expected_duration_ms: 5000
  retryable_exit_codes: 

```

---

### resolve

Output fully-resolved artifact definitions

Expands config variables, applies authority-based defaults for manual_edit and change_control, and outputs the complete resolved DSL. Default format is yaml.

**Usage:**

```
artifact-contracts resolve [--config] [--format]
```

#### Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
| `--format` |  | No |  | Output format (default: yaml) |

#### Exit Codes

**Exit 0:** Successfully output resolved definitions

**Exit 1:** Error resolving definitions

**Exit 3:** Config or input file not found / parse error

#### Extensions

```yaml
x-agent: 
  expected_duration_ms: 2000
  retryable_exit_codes: 

```

---

### list

List registered artifacts

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.

**Usage:**

```
artifact-contracts list [--config] [--authority] [--path] [--format]
```

#### Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
| `--authority` |  | No |  | Filter by authority type |
| `--path` |  | No |  | Reverse-lookup — show artifact IDs matching this file path. For full governance details, use the explain command. |
| `--format` |  | No |  | Output format (default: text) |

#### Exit Codes

**Exit 0:** Successfully listed artifacts

**Exit 1:** Error reading definitions

**Exit 3:** Config or input file not found / parse error

#### Extensions

```yaml
x-agent: 
  expected_duration_ms: 2000
  retryable_exit_codes: 

```

---

### explain

Explain artifact properties for a file path

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.

**Usage:**

```
artifact-contracts explain <path> [--config] [--format]
```

#### Arguments

| Name | Required | Description |
|---|---|---|
| `path` | Yes | File path to explain |

#### Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
| `--format` |  | No |  | Output format (default: text) |

#### Exit Codes

**Exit 0:** Path resolved to an artifact

**Exit 2:** Overlap — path matches multiple artifacts

**Exit 3:** Config or input file not found / parse error

**Exit 4:** Path does not match any registered artifact

#### Extensions

```yaml
x-agent: 
  expected_duration_ms: 2000
  retryable_exit_codes: 

```

---

### audit

LLM-based semantic audit of artifact definitions

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.

**Usage:**

```
artifact-contracts audit [--config] [--adapter] [--model] [--show-prompt] [--dry-run] [--fail-on] [--output] [--report-format] [--log-file]
```

#### Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
| `--adapter` |  | No |  | LLM adapter to use |
| `--model` |  | No |  | Model name to pass to the adapter |
| `--show-prompt` |  | No |  | Output the constructed prompt without calling the LLM API |
| `--dry-run` | -n | No |  | Alias for --show-prompt (output prompt without LLM call) |
| `--fail-on` |  | No |  | Minimum severity that causes exit 10. Ordering: critical > error > warning > info. For example, --fail-on warning exits 10 on warning, error, or critical. |
| `--output` | -o | No |  | Write result to a file instead of stdout |
| `--report-format` |  | No |  | Output format for the report (default: text). LLM commands use --report-format; deterministic commands use --format. |
| `--log-file` | -l | No |  | Write agent progress log to this file path. |

#### Exit Codes

**Exit 0:** Audit completed — no findings above threshold

**Exit 1:** General / transient error

**Exit 3:** Config or input file not found / parse error

**Exit 10:** Findings detected above --fail-on threshold

**Exit 11:** agent-contracts-runtime is not installed

**Exit 12:** Adapter initialization error (missing API key, etc.)

#### Extensions

```yaml
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
```

---

### discover

LLM-based artifact discovery from project file structure

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.

**Usage:**

```
artifact-contracts discover [--adapter] [--model] [--show-prompt] [--dry-run] [--write] [--output] [--report-format] [--log-file]
```

#### Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--adapter` |  | No |  | LLM adapter to use |
| `--model` |  | No |  | Model name to pass to the adapter |
| `--show-prompt` |  | No |  | Output the constructed prompt without calling the LLM API |
| `--dry-run` | -n | No |  | Alias for --show-prompt (output prompt without LLM call) |
| `--write` | -w | No |  | Write the generated YAML directly to artifact-contracts.yaml |
| `--output` | -o | No |  | Write result to a specific file path instead of stdout |
| `--report-format` |  | No |  | Output format (default: yaml) |
| `--log-file` | -l | No |  | Write agent progress log to this file path. |

#### Exit Codes

**Exit 0:** Discovery completed successfully

**Exit 1:** General / transient error

**Exit 3:** File system read error

**Exit 11:** agent-contracts-runtime is not installed

**Exit 12:** Adapter initialization error (missing API key, etc.)

#### Extensions

```yaml
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
```

---

### agents

Output the full resolved agent DSL as structured data.

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.

**Usage:**

```
artifact-contracts agents [--format]
```

#### Options

| Option | Aliases | Required | Default | Description |
|---|---|---|---|---|
| `--format` | -F | No | `"yaml"` | Output format. |

#### Exit Codes

**Exit 0:** DSL output successfully.

- **stdout:** format=`text`

**Exit 1:** Failed to load embedded DSL.

- **stderr:** format=`text`

#### Extensions

```yaml
x-agent: 
  riskLevel: low
  requiresConfirmation: false
  idempotent: true
  sideEffects: 

```

---

---

## Schemas

### AgentFinding

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes |  |
| `severity` | `"critical" \| "error" \| "warning" \| "info"` | Yes |  |
| `category` | `string` | Yes |  |
| `title` | `string` | Yes |  |
| `description` | `string` | Yes |  |
| `location` | `string` | No |  |
| `target` | `string` | No |  |
| `recommendation` | `string` | No |  |
| `evidence` | `object[]` | No |  |
| `evidence[].kind` | `"schema" \| "code" \| "config" \| "runtime" \| "doc"` | Yes |  |
| `evidence[].target` | `string` | No |  |
| `evidence[].location` | `string` | No |  |
| `evidence[].excerpt` | `string` | No |  |
| `evidence[].reasoning` | `string` | No |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "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": {
        "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"
        ]
      }
    }
  },
  "required": [
    "id",
    "severity",
    "category",
    "title",
    "description"
  ]
}
```

</details>

### AgentAuditResult

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `summary` | `string` | Yes |  |
| `risk_level` | `"none" \| "low" \| "medium" \| "high" \| "critical"` | Yes |  |
| `findings` | `object[]` | Yes |  |
| `findings[].id` | `string` | Yes |  |
| `findings[].severity` | `"critical" \| "error" \| "warning" \| "info"` | Yes |  |
| `findings[].category` | `string` | Yes |  |
| `findings[].title` | `string` | Yes |  |
| `findings[].description` | `string` | Yes |  |
| `findings[].location` | `string` | No |  |
| `findings[].target` | `string` | No |  |
| `findings[].recommendation` | `string` | No |  |
| `findings[].evidence` | `object[]` | No |  |
| `findings[].evidence[].kind` | `"schema" \| "code" \| "config" \| "runtime" \| "doc"` | Yes |  |
| `findings[].evidence[].target` | `string` | No |  |
| `findings[].evidence[].location` | `string` | No |  |
| `findings[].evidence[].excerpt` | `string` | No |  |
| `findings[].evidence[].reasoning` | `string` | No |  |
| `recommended_actions` | `object[]` | Yes |  |
| `recommended_actions[].action` | `string` | Yes |  |
| `recommended_actions[].priority` | `"high" \| "medium" \| "low"` | Yes |  |
| `recommended_actions[].description` | `string` | No |  |
| `metadata` | `object` | No |  |
| `metadata.total_artifacts` | `integer` | No |  |
| `metadata.analyzed_artifacts` | `integer` | No |  |
| `metadata.analysis_scope` | `string` | No |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string"
    },
    "risk_level": {
      "type": "string",
      "enum": [
        "none",
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "findings": {
      "type": "array",
      "items": {
        "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": {
              "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"
              ]
            }
          }
        },
        "required": [
          "id",
          "severity",
          "category",
          "title",
          "description"
        ]
      }
    },
    "recommended_actions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "action",
          "priority"
        ]
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "total_artifacts": {
          "type": "integer"
        },
        "analyzed_artifacts": {
          "type": "integer"
        },
        "analysis_scope": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "summary",
    "risk_level",
    "findings",
    "recommended_actions"
  ]
}
```

</details>

### AgentEvidence

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `kind` | `"schema" \| "code" \| "config" \| "runtime" \| "doc"` | Yes |  |
| `target` | `string` | No |  |
| `location` | `string` | No |  |
| `excerpt` | `string` | No |  |
| `reasoning` | `string` | No |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "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"
  ]
}
```

</details>

### AgentRecommendedAction

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `action` | `string` | Yes |  |
| `priority` | `"high" \| "medium" \| "low"` | Yes |  |
| `description` | `string` | No |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string"
    },
    "priority": {
      "type": "string",
      "enum": [
        "high",
        "medium",
        "low"
      ]
    },
    "description": {
      "type": "string"
    }
  },
  "required": [
    "action",
    "priority"
  ]
}
```

</details>

### ResolvedDefinitions

Output of the resolve command

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `artifact_contracts` | `string` | Yes |  |
| `system` | `object` | Yes |  |
| `system.id` | `string` | Yes |  |
| `system.name` | `string` | No |  |
| `artifacts` | `Record<string, any>` | Yes | Map of artifact ID to resolved artifact definition |

<details>
<summary>JSON Schema</summary>

```json
{
  "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": {
        "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"
        ]
      }
    }
  },
  "required": [
    "artifact_contracts",
    "system",
    "artifacts"
  ]
}
```

</details>

### ArtifactExplanation

Output of the explain command (json/yaml format)

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes |  |
| `type` | `string` | Yes |  |
| `authority` | `string` | Yes |  |
| `manual_edit` | `string` | Yes |  |
| `change_control` | `string` | Yes |  |
| `visibility` | `string` | No |  |
| `description` | `string` | No |  |
| `path_patterns` | `string[]` | No |  |
| `exclude_patterns` | `string[]` | No |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "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"
  ]
}
```

</details>

### ArtifactDefinition

A single resolved artifact definition

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes |  |
| `authority` | `"canonical" \| "derived" \| "generated" \| "control"` | Yes |  |
| `manual_edit` | `"allowed" \| "discouraged" \| "forbidden"` | Yes |  |
| `change_control` | `"none" \| "approval-required" \| "regeneration-required"` | Yes |  |
| `visibility` | `"public" \| "internal" \| "private"` | Yes |  |
| `description` | `string` | No |  |
| `path_patterns` | `string[]` | Yes |  |
| `exclude_patterns` | `string[]` | No |  |
| `states` | `string[]` | No |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "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"
  ]
}
```

</details>

### ArtifactList

Output of the list command (json/yaml format)

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `artifacts` | `Record<string, any>` | No | Map of artifact ID to resolved artifact definition |

<details>
<summary>JSON Schema</summary>

```json
{
  "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": {
        "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"
        ]
      }
    }
  }
}
```

</details>

### DiscoverResult

Output of the discover command

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `mode` | `"init" \| "update"` | Yes |  |
| `artifact_contracts_yaml` | `string` | Yes | Generated YAML content |
| `decisions` | `object[]` | No |  |
| `decisions[].artifact_id` | `string` | Yes |  |
| `decisions[].reasoning` | `string` | Yes |  |
| `trace_decisions` | `object[]` | No |  |
| `trace_decisions[].link_id` | `string` | Yes |  |
| `trace_decisions[].reasoning` | `string` | Yes |  |
| `uncategorized_files` | `string[]` | No |  |
| `suggestions` | `string[]` | No |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "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"
  ]
}
```

</details>

### ValidationResult

Output of the validate command (json format, on error)

Type: `object`

| Property | Type | Required | Description |
|---|---|---|---|
| `valid` | `boolean` | Yes |  |
| `diagnostics` | `object[]` | Yes |  |
| `diagnostics[].path` | `string` | No |  |
| `diagnostics[].message` | `string` | Yes |  |
| `diagnostics[].severity` | `"error" \| "warning"` | Yes |  |
| `overlaps` | `object[]` | Yes |  |
| `overlaps[].path` | `string` | Yes |  |
| `overlaps[].matching_artifacts` | `string[]` | Yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "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"
  ]
}
```

</details>