octopus-workflow/core/schemas/runs-meta.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://eightarms.net/octopus-workflow/schemas/runs-meta.schema.json",
  "title": "Tier 1 Run Metadata",
  "description": "Schema for runs/{slug}/meta.json — run metadata for a Tier 1 local structured run. Authoritative layout: templates/runs-layout.md. Boundary rule: rules/two-tier-artifacts.md. State transitions active -> archived at close (archive-at-close).",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "slug",
    "state",
    "created_at",
    "updated_at",
    "ticket",
    "parent_epic",
    "closed_at",
    "close_commit_sha"
  ],
  "allOf": [
    {
      "if": { "properties": { "state": { "const": "archived" } }, "required": ["state"] },
      "then": {
        "properties": {
          "closed_at": { "type": "string", "format": "date-time" },
          "close_commit_sha": { "type": "string", "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$" }
        },
        "required": ["closed_at", "close_commit_sha"]
      }
    }
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Optional JSON Schema $self reference for editor validation."
    },
    "schema_version": {
      "type": "integer",
      "const": 1,
      "description": "Layout schema version. Bumped on breaking changes to this shape."
    },
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]*$",
      "description": "Run slug. Matches the workflow branch tail and the Gitea wiki namespace."
    },
    "ticket": {
      "oneOf": [
        { "type": "null" },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["owner", "repo", "number"],
          "properties": {
            "owner": { "type": "string", "minLength": 1 },
            "repo": { "type": "string", "minLength": 1 },
            "number": { "type": "integer", "minimum": 1 }
          }
        }
      ],
      "description": "Source issue reference, or null for an ad-hoc run (no ticket)."
    },
    "branch": {
      "type": "string",
      "description": "Workflow branch, e.g. workflow/enhancement/1968-two-tier-artifacts. Omitted for ad-hoc runs without a branch (both runs-bundle profiles tolerate omission)."
    },
    "worktree": {
      "type": ["string", "null"],
      "description": "Absolute path of the worktree hosting this run, or null for ad-hoc runs without a worktree (aligned with runs-bundle.schema.json metaStrict)."
    },
    "parent_epic": {
      "oneOf": [
        { "type": "null" },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["number"],
          "properties": {
            "number": { "type": "integer", "minimum": 1 }
          }
        }
      ],
      "description": "Parent Epic issue number, or null if the run is not under an Epic."
    },
    "state": {
      "type": "string",
      "enum": ["active", "archived"],
      "description": "active: run in progress (workspace gitignored). archived: closed; bundle committed under runs/archive/{slug}.json."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp — run creation."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp — last metadata mutation."
    },
    "closed_at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "RFC 3339 timestamp set at archive-at-close, or null while active."
    },
    "close_commit_sha": {
      "type": ["string", "null"],
      "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$",
      "description": "git SHA of the commit that landed archive/{slug}.json; null while active. Must be non-null when state=archived (enforced by the if/then invariant)."
    }
  }
}