{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/rossedman/guardrails/main/internal/config/schema.json",
  "title": "Guardrails configuration",
  "description": "Configuration for .guardrails.yaml and ~/.config/guardrails/config.yaml.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "version": {
      "const": 1,
      "description": "Config schema version."
    },
    "mode": {
      "type": "string",
      "description": "enforce blocks on failure; warn reports only.",
      "enum": [
        "enforce",
        "warn"
      ]
    },
    "preset": {
      "enum": [
        "strict",
        "standard",
        "adopt"
      ],
      "description": "Starting bar: strict (90% coverage, 90% of changed lines), standard (80%/80%) or adopt (coverage may not drop, 80% of changed lines). Keys set in the file override it."
    },
    "go": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable the Go module. Defaults to true when the module's files exist."
        },
        "coverage": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "total": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "description": "Minimum total statement coverage of touched packages."
            },
            "per_package_floor": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "description": "Minimum coverage for any single touched package."
            },
            "ratchet": {
              "type": "boolean",
              "description": "Never allow a package to drop below its SessionStart baseline."
            },
            "exclude": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Glob patterns excluded from coverage."
            }
          }
        },
        "patch_coverage": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Minimum coverage of lines changed this session."
        },
        "lint": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "config": {
              "type": "string",
              "description": "golangci-lint config path; falls back to the bundled config."
            },
            "on_edit": {
              "type": "string",
              "description": "Lint depth on each edit.",
              "enum": [
                "fast",
                "full",
                "off"
              ]
            }
          }
        },
        "race": {
          "type": "boolean",
          "description": "Run tests with -race."
        },
        "vuln": {
          "type": "boolean",
          "description": "Run govulncheck at Stop."
        },
        "mutation": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "tool": {
              "type": "string",
              "description": "builtin (Go)."
            },
            "min_score": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "description": "Minimum mutation score on changed code."
            },
            "budget_seconds": {
              "type": "integer",
              "minimum": 1,
              "description": "Time slice for the mutation run."
            }
          },
          "description": "Mutation testing of changed functions, run by `guardrails harden`."
        },
        "bench": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "require_on_hot_paths": {
              "type": "boolean",
              "description": "Ask for benchmarks on hot-path code."
            },
            "regression_pct": {
              "type": "number",
              "minimum": 0
            },
            "count": {
              "type": "integer",
              "minimum": 1
            },
            "packages": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Performance-critical packages (module-relative, ... allowed)."
            }
          },
          "description": "Benchmark guidance."
        },
        "fuzz": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "require_on_parsers": {
              "type": "boolean",
              "description": "Ask for fuzz targets on parsers."
            },
            "fuzztime": {
              "type": "string",
              "description": "Fuzz duration per target, e.g. 10s."
            },
            "budget_seconds": {
              "type": "integer",
              "minimum": 1,
              "description": "Total time budget for fuzzing."
            }
          },
          "description": "Fuzzing, run by `guardrails harden`."
        }
      },
      "description": "Go module."
    },
    "python": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable the Python module. Defaults to true when the module's files exist."
        },
        "coverage": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "total": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "description": "Minimum total coverage."
            },
            "ratchet": {
              "type": "boolean",
              "description": "Never allow a package to drop below its SessionStart baseline."
            }
          }
        },
        "patch_coverage": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Minimum coverage of changed lines."
        },
        "typecheck": {
          "type": "string",
          "description": "Type checker.",
          "enum": [
            "mypy",
            "pyright",
            "off"
          ]
        },
        "strict": {
          "type": "boolean",
          "description": "Strict type checking."
        },
        "mutation": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "tool": {
              "type": "string",
              "description": "Mutation testing tool."
            },
            "min_score": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "description": "Minimum mutation score on changed code."
            },
            "budget_seconds": {
              "type": "integer",
              "minimum": 1,
              "description": "Time slice for the mutation run."
            }
          },
          "description": "Mutation testing (planned)."
        }
      },
      "description": "Python module."
    },
    "shell": {
      "type": "object",
      "additionalProperties": false,
      "description": "Shell module.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable the shell module. Defaults to true when shell scripts exist."
        },
        "severity": {
          "type": "string",
          "enum": [
            "style",
            "info",
            "warning",
            "error"
          ],
          "description": "Minimum shellcheck severity reported."
        }
      }
    },
    "yaml": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable the YAML module. Defaults to true when the module's files exist."
        },
        "kubeconform": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "kubernetes_version": {
              "type": "string",
              "description": "Kubernetes version for schema validation."
            },
            "enabled": {
              "type": "boolean",
              "description": "Validate Kubernetes manifests with kubeconform."
            }
          }
        },
        "actionlint": {
          "type": "boolean",
          "description": "Check GitHub Actions workflows with actionlint."
        }
      },
      "description": "YAML module."
    },
    "terraform": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable the Terraform module. Defaults to true when the module's files exist."
        },
        "binary": {
          "type": "string",
          "description": "Terraform binary.",
          "enum": [
            "terraform",
            "tofu"
          ]
        },
        "scan": {
          "type": "string",
          "enum": [
            "trivy",
            "off"
          ],
          "description": "Config scanner."
        },
        "tflint": {
          "type": "boolean",
          "description": "Run tflint on edit and at the gate."
        },
        "require_version_constraints": {
          "type": "boolean",
          "description": "Every provider must have a version constraint."
        }
      },
      "description": "Terraform module."
    },
    "docker": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable the Docker module. Defaults to true when the module's files exist."
        },
        "require_digest_pins": {
          "type": "boolean",
          "description": "Base images must be pinned by digest."
        },
        "require_non_root": {
          "type": "boolean",
          "description": "Final stage must set a non-root USER."
        },
        "build_check": {
          "type": "boolean",
          "description": "Run `docker build --check` when a Docker daemon is available."
        }
      },
      "description": "Docker module."
    },
    "tools": {
      "type": "object",
      "additionalProperties": false,
      "description": "How external tools are found and installed.",
      "properties": {
        "install": {
          "type": "string",
          "enum": [
            "auto",
            "never"
          ],
          "description": "auto downloads pinned, checksum-verified tools on demand; never uses only what is installed."
        },
        "prefer": {
          "type": "string",
          "enum": [
            "path",
            "managed"
          ],
          "description": "path uses installed tools first; managed always uses the pinned versions."
        }
      }
    },
    "guards": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "allow_suppression_tag": {
          "type": "string",
          "description": "Tag a human writes to allow a suppression comment.",
          "minLength": 1
        },
        "kubectl_safe_contexts": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "kubectl contexts where writes are allowed without asking."
        },
        "protected_branches": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Branches Claude may not push to."
        }
      },
      "description": "PreToolUse policy guards."
    },
    "deps": {
      "type": "object",
      "additionalProperties": false,
      "description": "Dependency check: packages Claude installs or adds to a manifest are looked up on deps.dev and OSV before the change runs.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Run the dependency check (default true)."
        },
        "min_age_days": {
          "type": "integer",
          "minimum": 0,
          "description": "Ask before adding a package first published fewer days ago; 0 disables."
        },
        "min_version_age_days": {
          "type": "integer",
          "minimum": 0,
          "description": "Ask before adding a version published fewer days ago; 0 disables."
        },
        "vulnerabilities": {
          "enum": [
            "ask",
            "deny",
            "allow"
          ],
          "description": "What to do with a version that has known advisories."
        },
        "unreachable": {
          "enum": [
            "ask",
            "allow"
          ],
          "description": "What to do when the registries can't be reached in time."
        },
        "licenses": {
          "type": "object",
          "additionalProperties": false,
          "description": "SPDX license identifiers. An empty allow list allows any license not denied.",
          "properties": {
            "allow": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Licenses dependencies may have."
            },
            "deny": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Licenses that are denied."
            }
          }
        },
        "allow": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Packages that skip the check, as globs such as @acme/* or github.com/acme/*."
        }
      }
    },
    "lessons": {
      "type": "object",
      "additionalProperties": false,
      "description": "Capture your corrections of Claude as candidate rules for /guardrails:learn.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Capture corrections (default true)."
        },
        "nudge": {
          "type": "boolean",
          "description": "Tell Claude when a correction was recorded."
        }
      }
    },
    "gate": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "max_consecutive_blocks": {
          "type": "integer",
          "minimum": 1,
          "description": "Stop blocks before handing off to the human."
        },
        "timeout_seconds": {
          "type": "integer",
          "minimum": 1,
          "description": "Stop gate time budget."
        }
      },
      "description": "Stop gate."
    }
  }
}