{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/boshu2/agentops/docs/contracts/finding-artifact.schema.json",
  "title": "Finding Artifact",
  "description": "Canonical schema for promoted prevention findings stored under .agents/findings/ as markdown with YAML frontmatter.",
  "type": "object",
  "required": [
    "id",
    "type",
    "date",
    "source_skill",
    "source_artifact",
    "title",
    "summary",
    "pattern",
    "detection_question",
    "checklist_item",
    "severity",
    "detectability",
    "status",
    "compiler_targets",
    "scope_tags",
    "dedup_key",
    "applicable_when",
    "applicable_languages"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "type": {
      "type": "string",
      "const": "finding"
    },
    "version": {
      "type": "integer",
      "const": 1
    },
    "date": {
      "type": "string",
      "format": "date"
    },
    "source_skill": {
      "type": "string",
      "minLength": 1
    },
    "source_artifact": {
      "type": "string",
      "minLength": 1
    },
    "source_bead": {
      "type": "string",
      "minLength": 1
    },
    "source_phase": {
      "type": "string",
      "enum": ["research", "plan", "implement", "validate"]
    },
    "title": {
      "type": "string",
      "minLength": 1
    },
    "summary": {
      "type": "string",
      "minLength": 1
    },
    "pattern": {
      "type": "string",
      "minLength": 1
    },
    "detection_question": {
      "type": "string",
      "minLength": 1
    },
    "checklist_item": {
      "type": "string",
      "minLength": 1
    },
    "severity": {
      "type": "string",
      "minLength": 1
    },
    "detectability": {
      "type": "string",
      "enum": ["advisory", "mechanical"]
    },
    "status": {
      "type": "string",
      "enum": ["draft", "active", "retired", "superseded"]
    },
    "compiler_targets": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": ["plan", "pre-mortem", "constraint"]
      }
    },
    "scope_tags": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "dedup_key": {
      "type": "string",
      "minLength": 1
    },
    "applicable_when": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "enum": [
          "plan-shape",
          "classifier",
          "enum-parser",
          "struct-change",
          "pattern-matcher",
          "validation-gap",
          "test-gap",
          "docs-drift"
        ]
      }
    },
    "applicable_languages": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "tier": {
      "type": "string",
      "enum": ["local", "seed", "pulled"]
    },
    "confidence": {
      "type": "string",
      "minLength": 1
    },
    "ttl_days": {
      "type": "integer",
      "minimum": 0
    },
    "hit_count": {
      "type": "integer",
      "minimum": 0
    },
    "last_cited": {
      "type": ["string", "null"],
      "format": "date-time"
    },
    "supersedes": {
      "type": "string",
      "minLength": 1
    },
    "superseded_by": {
      "type": "string",
      "minLength": 1
    },
    "retired_by": {
      "type": "string",
      "minLength": 1
    },
    "utility": {
      "type": "number"
    },
    "compiler": {
      "type": "object",
      "properties": {
        "review_file": {
          "type": "string",
          "minLength": 1
        },
        "applies_to": {
          "type": "object",
          "properties": {
            "scope": {
              "type": "string",
              "enum": ["files", "repo"]
            },
            "issue_types": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "path_globs": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "path_prefixes": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "languages": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "extensions": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          "additionalProperties": false
        },
        "detector": {
          "type": "object",
          "required": ["kind"],
          "properties": {
            "kind": {
              "type": "string",
              "enum": ["content_pattern", "paired_files", "restricted_command"]
            },
            "mode": {
              "type": "string",
              "enum": ["must_contain", "must_not_contain"]
            },
            "pattern": {
              "type": "string",
              "minLength": 1
            },
            "file_pattern": {
              "type": "string",
              "minLength": 1
            },
            "exclude": {
              "type": "string",
              "minLength": 1
            },
            "companion": {
              "type": "string",
              "minLength": 1
            },
            "message": {
              "type": "string",
              "minLength": 1
            },
            "command": {
              "type": "string",
              "minLength": 1
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "detectability": {
            "const": "mechanical"
          }
        },
        "required": ["detectability"]
      },
      "then": {
        "required": ["compiler"],
        "properties": {
          "compiler_targets": {
            "contains": {
              "const": "constraint"
            }
          },
          "compiler": {
            "required": ["detector"]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "status": {
            "const": "superseded"
          }
        },
        "required": ["status"]
      },
      "then": {
        "required": ["superseded_by"]
      }
    }
  ],
  "additionalProperties": false
}