{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tessl.io/skill-insights/staleness.schema.json",
  "title": "Skill Insights — Staleness + Git Provenance Output",
  "description": "Per-skill git-derived signals produced by analyze-skill-staleness. Combines age tracking, broken-reference detection from discovery warnings, registry-update availability for owning tiles, and authorship/provenance (1.1+).",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema_version", "metadata", "per_skill", "estate_summary", "warnings"],
  "properties": {
    "schema_version": { "type": "string", "const": "1.1" },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "required": ["scanned_at", "tool_version", "skill_count", "thresholds"],
      "properties": {
        "scan_id": { "type": ["string", "null"] },
        "scanned_at": { "type": "string", "format": "date-time" },
        "tool_version": { "type": "string" },
        "skill_count": { "type": "integer", "minimum": 0 },
        "thresholds": {
          "type": "object",
          "additionalProperties": false,
          "required": ["fresh_days", "warm_days", "stale_days", "ancient_days"],
          "properties": {
            "fresh_days": { "type": "integer", "minimum": 0 },
            "warm_days": { "type": "integer", "minimum": 0 },
            "stale_days": { "type": "integer", "minimum": 0 },
            "ancient_days": { "type": "integer", "minimum": 0 }
          }
        }
      }
    },
    "per_skill": {
      "type": "array",
      "items": { "$ref": "#/$defs/PerSkillStaleness" }
    },
    "estate_summary": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "median_days_since_modified",
        "skills_with_broken_refs",
        "skills_with_unknown_age",
        "buckets",
        "top_offenders"
      ],
      "properties": {
        "median_days_since_modified": { "type": ["integer", "null"], "minimum": 0 },
        "skills_with_broken_refs": { "type": "integer", "minimum": 0 },
        "skills_with_unknown_age": { "type": "integer", "minimum": 0 },
        "buckets": {
          "type": "object",
          "additionalProperties": false,
          "required": ["fresh", "warm", "stale", "ancient", "unknown"],
          "properties": {
            "fresh": { "type": "integer", "minimum": 0 },
            "warm": { "type": "integer", "minimum": 0 },
            "stale": { "type": "integer", "minimum": 0 },
            "ancient": { "type": "integer", "minimum": 0 },
            "unknown": { "type": "integer", "minimum": 0 }
          }
        },
        "top_offenders": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["skill_id", "staleness_score", "reason"],
            "properties": {
              "skill_id": { "type": "string" },
              "staleness_score": { "type": "integer", "minimum": 0, "maximum": 100 },
              "reason": { "type": "string" }
            }
          }
        }
      }
    },
    "warnings": { "type": "array", "items": { "type": "string" } }
  },
  "$defs": {
    "Tier": {
      "type": ["string", "null"],
      "enum": ["published_tile", "authored_tile", "github_tile", "claude_plugin", "non_tile", null]
    },
    "PerSkillStaleness": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "skill_id", "primary_path", "tracked_path", "repo",
        "tile_id", "tile_name", "tier", "is_declared",
        "tile_update_available",
        "tile_current_version", "tile_latest_version", "tile_last_scored_at",
        "last_modified", "days_since_modified",
        "first_seen", "days_since_first_seen", "commit_count",
        "git_provenance",
        "broken_references",
        "staleness_score", "staleness_bucket", "factors"
      ],
      "properties": {
        "skill_id": { "type": "string" },
        "primary_path": { "type": "string" },
        "tracked_path": { "type": ["string", "null"] },
        "repo": { "type": "string" },
        "tile_id": { "type": ["string", "null"] },
        "tile_name": { "type": ["string", "null"] },
        "tier": { "$ref": "#/$defs/Tier" },
        "is_declared": { "type": "boolean" },
        "tile_update_available": { "type": "boolean" },
        "tile_current_version": { "type": ["string", "null"] },
        "tile_latest_version": { "type": ["string", "null"] },
        "tile_last_scored_at": { "type": ["string", "null"] },
        "last_modified": { "type": ["string", "null"] },
        "days_since_modified": { "type": ["integer", "null"], "minimum": 0 },
        "first_seen": { "type": ["string", "null"] },
        "days_since_first_seen": { "type": ["integer", "null"], "minimum": 0 },
        "commit_count": { "type": "integer", "minimum": 0 },
        "git_provenance": { "$ref": "#/$defs/GitProvenance" },
        "broken_references": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["target", "kind", "source"],
            "properties": {
              "target": { "type": "string" },
              "kind": { "type": "string", "enum": ["code", "doc", "config", "other"] },
              "source": { "type": "string" }
            }
          }
        },
        "staleness_score": { "type": "integer", "minimum": 0, "maximum": 100 },
        "staleness_bucket": {
          "type": "string",
          "enum": ["fresh", "warm", "stale", "ancient", "unknown"]
        },
        "factors": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "older_than_180_days",
              "older_than_365_days",
              "older_than_repo_median",
              "broken_references",
              "no_git_history",
              "never_modified",
              "registry_update_available"
            ]
          },
          "uniqueItems": true
        }
      }
    },
    "GitProvenance": {
      "description": "Authorship and contributor data derived from `git log` for the tracked path. `null` when no git history was available (e.g. non-git repo, or path never tracked).",
      "anyOf": [
        { "type": "null" },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["created_by", "last_modified_by", "contributors", "recent_commits"],
          "properties": {
            "created_by": {
              "$ref": "#/$defs/Author",
              "description": "Author of the first commit touching this path."
            },
            "last_modified_by": {
              "$ref": "#/$defs/Author",
              "description": "Author of the most recent commit touching this path."
            },
            "contributors": {
              "type": "array",
              "description": "Top N distinct (name, email) pairs by commit count, descending. Capped at 10.",
              "items": { "$ref": "#/$defs/Contributor" }
            },
            "recent_commits": {
              "type": "array",
              "description": "Most recent commits touching this path, newest first. Capped at 5.",
              "items": { "$ref": "#/$defs/RecentCommit" }
            }
          }
        }
      ]
    },
    "Author": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "email"],
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      }
    },
    "Contributor": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "email", "commits"],
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" },
        "commits": { "type": "integer", "minimum": 1 }
      }
    },
    "RecentCommit": {
      "type": "object",
      "additionalProperties": false,
      "required": ["sha", "date", "author", "subject"],
      "properties": {
        "sha": { "type": "string", "description": "Short SHA (first 12 chars)." },
        "date": { "type": "string", "description": "ISO-8601 author date." },
        "author": { "type": "string", "description": "Author name (free-form, may contain spaces or punctuation)." },
        "subject": { "type": "string", "description": "Commit subject line (first line of commit message)." }
      }
    }
  }
}