plan.model

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "PlanCounts": {
      "description": "A milestone's issues counted: the two denominators, then one entry per declared status.",
      "properties": {
        "by_status": {
          "additionalProperties": {
            "format": "uint32",
            "minimum": 0,
            "type": "integer"
          },
          "description": "One entry per declared issue status, keyed by the vocabulary.",
          "type": "object"
        },
        "required": {
          "description": "The denominator the milestone's own status derivation uses: total less cancelled, so\nno surface prints \"n of total\" for a milestone the engine calls DONE.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "total": {
          "description": "Every issue naming this milestone.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "total",
        "required",
        "by_status"
      ],
      "type": "object"
    },
    "PlanEdge": {
      "description": "One dependency edge, `from` before `to`.",
      "properties": {
        "from": {
          "description": "The record that must be real first.",
          "type": "string"
        },
        "to": {
          "description": "The record that waits for it.",
          "type": "string"
        }
      },
      "required": [
        "from",
        "to"
      ],
      "type": "object"
    },
    "PlanFinding": {
      "description": "One validation finding, in the shape `project.finding-carries-reproduce` asks for.",
      "properties": {
        "code": {
          "description": "The stable code a reader greps for (`unknown_dependency`, `scope_conflict`, …).",
          "type": "string"
        },
        "level": {
          "description": "`FAIL` or `WARN`. A failure means the model is invalid.",
          "type": "string"
        },
        "message": {
          "description": "What is wrong, in one line.",
          "type": "string"
        },
        "subject": {
          "description": "The record the finding is about, or `graph` when it is about the whole graph.",
          "type": "string"
        }
      },
      "required": [
        "level",
        "code",
        "subject",
        "message"
      ],
      "type": "object"
    },
    "PlanIssue": {
      "description": "One issue, as its record declares it and as the graph derives it.",
      "properties": {
        "blocked_by": {
          "description": "The dependencies that are not DONE, plus `milestone:<id>` when the milestone gate\nholds the whole outcome back.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "completed_at": {
          "description": "When completion was recorded.",
          "type": "string"
        },
        "dependents": {
          "description": "The issues that depend on this one.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "depends_on": {
          "description": "Every issue it declares a dependency on, as declared — including one that does not\nexist, which is a finding rather than a silent omission.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "evidence_have": {
          "description": "Evidence entries attached.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "evidence_need": {
          "description": "Evidence tokens the record requires before it may be DONE.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "id": {
          "description": "The identity, which is also the file name.",
          "type": "string"
        },
        "milestone": {
          "description": "The milestone it belongs to.",
          "type": "string"
        },
        "objective": {
          "description": "One line: what the issue is for.",
          "type": "string"
        },
        "parallel_safe": {
          "description": "Whether it may run beside another issue of its wave.",
          "type": "boolean"
        },
        "priority": {
          "description": "`p0` … `p3`.",
          "type": "string"
        },
        "profile": {
          "description": "The execution profile the issue is worked under.",
          "type": "string"
        },
        "scope": {
          "description": "The paths it touches; two issues of one wave that share a path are serialised.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "serves": {
          "description": "The intent criteria it exists to make true, each `<intent>#<criterion>`, as declared.\nEmpty for maintenance work under a milestone no intent names; whether a named\ncriterion exists is the intent coverage's question, not the plan's.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "slug": {
          "description": "The slug, when the record carries one.",
          "type": "string"
        },
        "started_at": {
          "description": "When execution began, when it did.",
          "type": "string"
        },
        "status": {
          "description": "The derived status. Never stored: an issue records what happened to it and the\nstatus follows from that and from the state of its dependencies.",
          "type": "string"
        },
        "title": {
          "description": "One line naming the outcome.",
          "type": "string"
        },
        "verified_at": {
          "description": "When implementation was declared complete.",
          "type": "string"
        },
        "wave": {
          "description": "The execution wave: one past the longest path to it through the dependency graph.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "id",
        "milestone",
        "status",
        "wave",
        "priority",
        "profile",
        "parallel_safe",
        "title",
        "slug",
        "depends_on",
        "blocked_by",
        "dependents",
        "scope",
        "serves",
        "objective",
        "evidence_have",
        "evidence_need",
        "started_at",
        "verified_at",
        "completed_at"
      ],
      "type": "object"
    },
    "PlanMilestone": {
      "description": "One milestone, as its record declares it and as the two graphs derive it.",
      "properties": {
        "blocked_by": {
          "description": "Those of them that are not DONE. Non-empty means the gate holds every issue of this\nmilestone back, whatever the issue graph says.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "claims": {
          "description": "The claims of the repository this outcome makes true.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "counts": {
          "$ref": "#/$defs/PlanCounts",
          "description": "Its issues, counted by derived status."
        },
        "dependents": {
          "description": "The milestones that require it.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "depends_on": {
          "description": "The milestones it requires.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "id": {
          "description": "The identity, which is also the file name; a stable slug, never a version.",
          "type": "string"
        },
        "issues": {
          "description": "Its issues, in id order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "last_accepted": {
          "description": "The last accepted issue of a DONE milestone: its DONE issue with the latest\n`completed_at`, the greater id on a tie. Empty for a milestone that is not DONE, or\nthat is DONE with no issue (its evidence finished it). Which release carried it is\n`released_in`'s to answer.",
          "type": "string"
        },
        "order": {
          "description": "Tie-break inside one rank; the roadmap is ordered by rank first.",
          "format": "int64",
          "type": "integer"
        },
        "outcome": {
          "description": "One line: what is true once the milestone is real.",
          "type": "string"
        },
        "priority": {
          "description": "`p0` … `p3`.",
          "type": "string"
        },
        "rank": {
          "description": "Its layer in the milestone graph: what orders the roadmap.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "released_in": {
          "description": "The release that carried the milestone — the first release record whose commit\ncontains the merge of its last accepted issue (or, with no issue, the commit that\nrecorded its latest evidence), else `unreleased` — when the reader\nasked for it\n(`released_in`); the roadmap always does. Never a typed field (ADR 0166).",
          "type": [
            "string",
            "null"
          ]
        },
        "slug": {
          "description": "The slug, when the record carries one.",
          "type": "string"
        },
        "status": {
          "description": "The derived status.",
          "type": "string"
        },
        "title": {
          "description": "One line naming the outcome.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "status",
        "order",
        "priority",
        "title",
        "slug",
        "rank",
        "depends_on",
        "blocked_by",
        "dependents",
        "claims",
        "counts",
        "issues",
        "outcome"
      ],
      "type": "object"
    },
    "PlanProject": {
      "description": "The plan's header: what this repository is, plus the one field nobody authors.",
      "properties": {
        "active_milestone": {
          "description": "The milestone a worker is executing now: the lowest-ranked unblocked milestone that\nis ACTIVE, else the lowest-ranked unblocked one not finished. Derived on every read,\nstored nowhere, and never authored — the plan cannot nominate a milestone whose\nprerequisites are not real.",
          "type": "string"
        },
        "default_branch": {
          "description": "The branch the plan is executed on.",
          "type": "string"
        },
        "name": {
          "description": "The project's name, from `project.yaml`.",
          "type": "string"
        },
        "repository": {
          "description": "The repository it belongs to, `owner/name`.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "repository",
        "default_branch",
        "active_milestone"
      ],
      "type": "object"
    },
    "PlanVocabulary": {
      "description": "The status vocabularies, so a reader never has to know which statuses exist.",
      "properties": {
        "issue": {
          "description": "The issue statuses, in derivation order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "milestone": {
          "description": "The milestone statuses, in derivation order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "issue",
        "milestone"
      ],
      "type": "object"
    },
    "PlanWave": {
      "description": "One execution wave: the issues the graph allows to run at the same time.",
      "properties": {
        "issues": {
          "description": "The issues in it, in id order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "wave": {
          "description": "The layer, from zero.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "wave",
        "issues"
      ],
      "type": "object"
    }
  },
  "description": "The whole derived plan: what every plan capability answers out of.",
  "properties": {
    "edges": {
      "description": "The issue dependency graph, sorted.",
      "items": {
        "$ref": "#/$defs/PlanEdge"
      },
      "type": "array"
    },
    "findings": {
      "description": "Every finding, in derivation order.",
      "items": {
        "$ref": "#/$defs/PlanFinding"
      },
      "type": "array"
    },
    "issues": {
      "description": "Every issue, in id order.",
      "items": {
        "$ref": "#/$defs/PlanIssue"
      },
      "type": "array"
    },
    "milestone_edges": {
      "description": "The milestone dependency graph, sorted.",
      "items": {
        "$ref": "#/$defs/PlanEdge"
      },
      "type": "array"
    },
    "milestones": {
      "description": "Every milestone, in id order.",
      "items": {
        "$ref": "#/$defs/PlanMilestone"
      },
      "type": "array"
    },
    "project": {
      "$ref": "#/$defs/PlanProject",
      "description": "The plan's header, with the active milestone derived."
    },
    "statuses": {
      "$ref": "#/$defs/PlanVocabulary",
      "description": "The declared status vocabularies."
    },
    "waves": {
      "description": "The execution waves, lowest first.",
      "items": {
        "$ref": "#/$defs/PlanWave"
      },
      "type": "array"
    }
  },
  "required": [
    "project",
    "statuses",
    "milestones",
    "issues",
    "waves",
    "edges",
    "milestone_edges",
    "findings"
  ],
  "title": "Plan",
  "type": "object"
}