document-haness/skills/technical-doc-flow/schemas/run.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "run.schema.json",
  "title": "00_run.json",
  "type": "object",
  "required": ["schema_version", "run_id", "created_at", "updated_at", "mode", "document_kind", "kind_reason", "route_requested", "route_hint", "route_reason", "route_metrics", "status", "error", "contract_sha256", "rules_version", "rules_sha256", "omissions", "inputs", "history"],
  "properties": {
    "schema_version": {"const": "1.0"},
    "run_id": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3,4}$"},
    "created_at": {"type": "string", "format": "date-time"},
    "updated_at": {"type": "string", "format": "date-time"},
    "mode": {"enum": ["write", "revise", "review"]},
    "document_kind": {"enum": ["explanation", "decision", "how-to", "reference"]},
    "kind_reason": {"type": "string", "minLength": 1},
    "audience": {"type": ["string", "null"]},
    "route_requested": {"enum": ["auto", "light", "standard", "deep"]},
    "route_hint": {"enum": ["light", "standard", "deep"]},
    "route_reason": {"type": "string", "minLength": 1, "pattern": "\\S"},
    "route_metrics": {
      "type": "object",
      "required": ["total_chars", "source_count", "total_headings"],
      "properties": {
        "total_chars": {"type": "integer", "minimum": 0},
        "source_count": {"type": "integer", "minimum": 0},
        "total_headings": {"type": "integer", "minimum": 0}
      },
      "additionalProperties": false
    },
    "status": {"enum": ["initialized", "evidence_ready", "planned", "drafted", "reviewed", "finalized", "verified", "hold_for_review", "failed", "incomplete"]},
    "error": {
      "oneOf": [
        {"$ref": "#/$defs/terminalError"},
        {"type": "null"}
      ]
    },
    "contract_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
    "rules_version": {"type": "string", "minLength": 1},
    "rules_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
    "omissions": {"type": "array", "items": {"$ref": "#/$defs/omission"}},
    "inputs": {
      "type": "object",
      "required": ["brief", "draft", "source_count", "brief_sha256", "draft_sha256", "sources_manifest_sha256", "input_sha256"],
      "properties": {
        "brief": {"$ref": "#/$defs/fileInventory"},
        "draft": {"oneOf": [{"$ref": "#/$defs/fileInventory"}, {"type": "null"}]},
        "source_count": {"type": "integer", "minimum": 0},
        "brief_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
        "draft_sha256": {"type": ["string", "null"], "pattern": "^[0-9a-f]{64}$"},
        "sources_manifest_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
        "input_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
      }
    },
    "history": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["at", "from", "to", "reason", "error"],
        "properties": {
          "at": {"type": "string", "format": "date-time"},
          "from": {"type": ["string", "null"]},
          "to": {"type": "string"},
          "reason": {"type": "string"},
          "error": {
            "oneOf": [
              {"$ref": "#/$defs/terminalError"},
              {"type": "null"}
            ]
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "to": {"enum": ["hold_for_review", "failed", "incomplete"]}
              },
              "required": ["to"]
            },
            "then": {"properties": {"error": {"$ref": "#/$defs/terminalError"}}},
            "else": {"properties": {"error": {"type": "null"}}}
          }
        ]
      }
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "status": {"enum": ["hold_for_review", "failed", "incomplete"]}
        },
        "required": ["status"]
      },
      "then": {"properties": {"error": {"$ref": "#/$defs/terminalError"}}},
      "else": {"properties": {"error": {"type": "null"}}}
    }
  ],
  "additionalProperties": false,
  "$defs": {
    "terminalError": {
      "type": "object",
      "required": ["stage", "code", "message", "affected_artifact", "retryable", "safe_next_action"],
      "properties": {
        "stage": {"type": "string", "minLength": 1, "pattern": "\\S"},
        "code": {"type": "string", "minLength": 1, "pattern": "\\S"},
        "message": {"type": "string", "minLength": 1, "pattern": "\\S"},
        "affected_artifact": {
          "oneOf": [
            {"type": "string", "minLength": 1, "pattern": "\\S"},
            {"type": "null"}
          ]
        },
        "retryable": {"type": "boolean"},
        "safe_next_action": {"type": "string", "minLength": 1, "pattern": "\\S"}
      },
      "additionalProperties": false
    },
    "omission": {
      "type": "object",
      "required": ["artifact", "reason"],
      "properties": {
        "artifact": {
          "enum": [
            "00_run.json",
            "01_input.md",
            "01_sources.json",
            "02_reader_contract.json",
            "03_evidence_map.json",
            "04_logic_map.json",
            "05_term_ledger.json",
            "07_draft.md",
            "08_logic_review.json",
            "08_reader_review.json",
            "08_lint.json",
            "final.md",
            "09_final_report.json"
          ]
        },
        "reason": {"type": "string", "minLength": 1, "pattern": "\\S"}
      },
      "additionalProperties": false
    },
    "fileInventory": {
      "type": "object",
      "required": ["id", "role", "path", "resolved_path", "size_bytes", "sha256"],
      "properties": {
        "id": {"type": "string", "minLength": 1},
        "role": {"type": "string"},
        "path": {"type": "string"},
        "resolved_path": {"type": "string"},
        "size_bytes": {"type": "integer", "minimum": 0},
        "sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
      }
    }
  }
}