done.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/renezander030/skillgate/master/schema/done.schema.json",
  "title": "skillgate definition-of-done",
  "description": "Schema for .skillgate/done.yaml — deterministic finish-line gates.",
  "type": "object",
  "required": ["gates"],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1,
      "description": "Spec format version. Omit for the current format."
    },
    "name": {
      "type": "string",
      "description": "A label for this definition of done."
    },
    "finishLine": {
      "type": "array",
      "description": "Commands that count as crossing the finish line. Patterns are matched structurally against shell command segments.",
      "items": { "type": "string", "minLength": 1 }
    },
    "gatedTools": {
      "type": "array",
      "description": "Agent tool names (globs, e.g. mcp__course__publish_*) that also cross the finish line. Shell tools are judged by finishLine.",
      "items": { "type": "string", "minLength": 1 }
    },
    "timeout": {
      "type": "integer",
      "minimum": 1,
      "description": "Maximum wall-clock budget in milliseconds for the complete gate run. Default 300000."
    },
    "gates": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/definitions/gate" }
    }
  },
  "definitions": {
    "when": {
      "type": "object",
      "additionalProperties": false,
      "minProperties": 1,
      "description": "Conditions under which the gate applies (all must hold). An undecidable condition runs the gate.",
      "properties": {
        "command": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Finish-line command prefixes this gate is required for." },
        "tool": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Gated tool-name globs this gate is required for." },
        "changed": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Run only if a file matching one of these globs changed versus the base ref." },
        "branch": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Run only on a branch matching one of these globs." }
      }
    },
    "base": {
      "properties": {
        "id": { "type": "string" },
        "description": { "type": "string" }
      },
      "required": ["id"]
    },
    "gate": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "trufflehog" },
            "trufflehog": { "type": "string", "minLength": 1 },
            "namesFile": { "type": "string", "minLength": 1 },
            "timeout": { "type": "integer", "minimum": 1 },
            "maxBytes": { "type": "integer", "minimum": 1 }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "file"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "review" },
            "file": { "type": "string", "minLength": 1 }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "file"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "file-exists" },
            "file": {
              "oneOf": [
                { "type": "string" },
                { "type": "array", "items": { "type": "string" } }
              ],
              "description": "Path or paths that must all exist."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "file", "pattern"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "file-contains" },
            "file": { "type": "string" },
            "pattern": { "type": "string", "description": "JavaScript regular expression source." },
            "flags": { "type": "string", "description": "Regex flags, e.g. \"i\"." },
            "maxBytes": { "type": "integer", "minimum": 1, "description": "Largest file (bytes) the gate reads; larger files fail it. Default 10485760 (10 MiB)." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "glob", "pattern"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "absent" },
            "glob": { "type": "string", "description": "Files to scan." },
            "pattern": { "type": "string", "description": "Regex that must NOT appear." },
            "flags": { "type": "string" },
            "ignore": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Extra globs to exclude (fixtures, examples, the spec itself)."
            },
            "maxBytes": { "type": "integer", "minimum": 1, "description": "Largest file (bytes) the gate reads; larger files fail it. Default 10485760 (10 MiB)." },
            "allowEmpty": { "type": "boolean", "description": "Allow the glob to match no files. Default false: a glob matching nothing fails as a no-op." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "run"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "command" },
            "run": { "type": "string", "description": "Shell command; must exit 0." },
            "timeout": { "type": "integer", "minimum": 1, "description": "Timeout in milliseconds. Default 30000." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "trivy" },
            "target": { "type": "string", "description": "Path to scan. Default \".\"." },
            "trivy": { "type": "string", "description": "Trivy binary to execute. Default \"trivy\"." },
            "scanners": {
              "type": "array",
              "items": { "enum": ["vuln", "secret"] },
              "description": "Trivy scanners to run. Default [\"vuln\", \"secret\"]."
            },
            "severity": {
              "type": "array",
              "items": { "enum": ["UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL"] },
              "description": "Vulnerability severities that block. Default [\"CRITICAL\"]."
            },
            "summary": {
              "type": "boolean",
              "description": "After a passing vulnerability scan, report the counts below the blocking severities. Default true."
            },
            "sbom": {
              "type": "boolean",
              "description": "Also require Trivy to generate a CycloneDX SBOM. Default true."
            },
            "ignoreUnfixed": {
              "type": "boolean",
              "description": "Pass --ignore-unfixed to the vulnerability scan. Default false."
            },
            "timeout": { "type": "integer", "minimum": 1, "description": "Timeout in milliseconds per Trivy invocation. Default 30000." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "file"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "evidence" },
            "file": { "type": "string", "description": "A file that must exist and be non-empty." },
            "newerThan": { "type": "string", "description": "Glob of files the evidence must be newer than: written after the last change to any of them." },
            "ignore": { "type": "array", "items": { "type": "string" }, "description": "Globs excluded from newerThan." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "instruction-sync" },
            "threshold": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Similarity required to count as in sync (default 0.95)."
            },
            "require": {
              "type": "array",
              "minItems": 1,
              "items": { "enum": ["agents-md", "claude-code", "cursor", "github-copilot", "gemini-cli", "cline", "windsurf", "jetbrains-junie"] },
              "description": "Tools that must have their own instruction file, in sync or linked to the canonical one."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "instruction-refs" },
            "ignore": { "type": "array", "items": { "type": "string" }, "description": "Globs of referenced paths to skip." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "path"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "not-empty" },
            "path": { "type": "string", "description": "Directory path that must contain at least `min` entries." },
            "min": {
              "type": "integer",
              "minimum": 1,
              "description": "Minimum number of entries. Default 1."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "glob", "pattern"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "no-new" },
            "glob": { "type": "string", "description": "Files to scan." },
            "pattern": { "type": "string", "description": "Regex whose match count must not increase versus the base ref." },
            "flags": { "type": "string" },
            "ignore": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Extra globs to exclude."
            },
            "maxBytes": { "type": "integer", "minimum": 1, "description": "Largest file (bytes) the gate reads; larger files fail it. Default 10485760 (10 MiB)." },
            "allowEmpty": { "type": "boolean", "description": "Allow the glob to match no files. Default false: a glob matching nothing fails as a no-op." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "glob"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "no-deleted" },
            "glob": { "type": "string", "description": "Files that existed at the base ref and must still exist." },
            "ignore": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Extra globs to exclude from the must-still-exist set."
            },
            "allowEmpty": { "type": "boolean", "description": "Allow the glob to match no files. Default false: a glob matching nothing fails as a no-op." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "glob", "pattern"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "no-fewer" },
            "glob": { "type": "string", "description": "Files to scan." },
            "pattern": { "type": "string", "description": "Regex whose match count must not decrease versus the base ref (test cases, assertions)." },
            "flags": { "type": "string" },
            "ignore": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Extra globs to exclude."
            },
            "maxBytes": { "type": "integer", "minimum": 1, "description": "Largest file (bytes) the gate reads; larger files fail it. Default 10485760 (10 MiB)." },
            "allowEmpty": { "type": "boolean", "description": "Allow the glob to match no files. Default false: a glob matching nothing fails as a no-op." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "deps-locked" },
            "manifest": {
              "oneOf": [
                { "type": "string" },
                { "type": "array", "items": { "type": "string" }, "minItems": 1 }
              ],
              "description": "package.json or pyproject.toml path(s). Default: every supported manifest at the workspace root."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "phases"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "phase" },
            "phases": {
              "type": "array",
              "minItems": 1,
              "description": "Phases in order. Being in a phase requires the gates listed by it and by every earlier phase to pass now.",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["id"],
                "properties": {
                  "id": { "type": "string" },
                  "requires": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Ids of other (non-phase) gates in this spec." }
                }
              }
            },
            "current": { "type": "string", "description": "Plain-text file naming the active phase. Default .skillgate/phase; missing = the first phase." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "glob"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "unchanged" },
            "glob": { "type": "string", "description": "Files that exist at the base ref and must stay byte-identical." },
            "ignore": { "type": "array", "items": { "type": "string" }, "description": "Extra globs that may change." },
            "allowEmpty": { "type": "boolean", "description": "Allow the glob to match no files. Default false." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "glob"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "deps-declared" },
            "glob": { "type": "string", "description": "JavaScript/TypeScript source files to scan." },
            "ignore": { "type": "array", "items": { "type": "string" }, "description": "Extra globs to exclude." },
            "allow": { "type": "array", "items": { "type": "string" }, "description": "Package names (globs) treated as declared: path aliases, virtual modules." },
            "maxBytes": { "type": "integer", "minimum": 1, "description": "Largest file (bytes) the gate reads. Default 10485760 (10 MiB)." },
            "allowEmpty": { "type": "boolean", "description": "Allow the glob to match no files. Default false." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "signed-commits" },
            "trust": { "enum": ["signed", "verified"], "description": "signed (default): any signature git did not reject. verified: a good signature git can check." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type", "pattern"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "commit-messages" },
            "pattern": { "type": "string", "description": "Regular expression every non-merge commit subject since the base must match." },
            "flags": { "type": "string", "description": "Regular expression flags, e.g. i." }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "type"],
          "properties": {
            "id": { "type": "string" },
            "description": { "type": "string" },
            "when": { "$ref": "#/definitions/when" },
            "level": { "enum": ["block", "warn"], "description": "warn reports a failure without failing the run or blocking. Default block." },
            "type": { "const": "pushed" },
            "ref": { "type": "string", "description": "Remote ref that must contain HEAD, e.g. origin/main. Default: the branch's upstream." }
          }
        }
      ]
    }
  }
}