devtask.milestone

{
  "additionalProperties": false,
  "description": "Which milestone to read as a dependency graph.",
  "properties": {
    "milestone": {
      "description": "The milestone id, as the canonical model spells it. An id the model does not declare\nis answered with an empty graph and every field `unknown`, not refused.",
      "type": "string"
    }
  },
  "required": [
    "milestone"
  ],
  "title": "DevMilestoneInput",
  "type": "object"
}

{
  "$defs": {
    "AttestedCount": {
      "description": "A count with its provenance. Separate from `AttestedText` because a wave, a commit\ntally and an evidence count are numbers a caller does arithmetic on, and a number\nrendered as a string is a number every client has to parse back.",
      "properties": {
        "provenance": {
          "$ref": "#/$defs/FieldProvenance",
          "description": "Where it came from."
        },
        "reason": {
          "description": "Why the provenance is what it is, when that is worth a sentence.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "The one place a reader goes to check it.",
          "type": "string"
        },
        "value": {
          "description": "The number, absent exactly when the provenance is `unknown`.",
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "provenance",
        "source"
      ],
      "type": "object"
    },
    "AttestedList": {
      "description": "A list with its provenance. The distinction a bare `Vec` cannot make is the one that\nmatters here: `depends_on: []` in the record is an authored empty list, and a record with\nno `depends_on` key is unknown. Both are empty; only one is a statement.",
      "properties": {
        "provenance": {
          "$ref": "#/$defs/FieldProvenance",
          "description": "Where they came from."
        },
        "reason": {
          "description": "Why the provenance is what it is, when that is worth a sentence.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "The one place a reader goes to check them.",
          "type": "string"
        },
        "values": {
          "description": "The items, in the order the record or the derivation produced them. Empty for an\nauthored empty list and for an unknown field alike; `provenance` tells them apart.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "values",
        "provenance",
        "source"
      ],
      "type": "object"
    },
    "AttestedText": {
      "description": "One scalar with its provenance: the unit every field of a development task is made of.\n\nThe invariant the constructors enforce, and `AttestedText::is_consistent` states, is\nthat a value is present exactly when the provenance is not `FieldProvenance::Unknown`.\nWithout it the shape can express \"unknown, and here is the value\", which is the defect\nthis whole module exists to prevent.",
      "properties": {
        "provenance": {
          "$ref": "#/$defs/FieldProvenance",
          "description": "Where it came from."
        },
        "reason": {
          "description": "Why the provenance is what it is, when that is worth a sentence: always for\n`unknown` and for `inferred`, and omitted otherwise.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "The one place a reader goes to check it: a repository-relative path with the key it\nwas read from, a capability id, or a command. Never a machine path.",
          "type": "string"
        },
        "value": {
          "description": "The value, absent exactly when the provenance is `unknown`.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "provenance",
        "source"
      ],
      "type": "object"
    },
    "CriticalBlocker": {
      "description": "One unfinished issue that holds back downstream work, and how much.",
      "properties": {
        "blocks": {
          "description": "The unfinished issues that wait on it, directly or through another, in canonical\norder.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "issue": {
          "description": "The issue.",
          "type": "string"
        },
        "readiness": {
          "$ref": "#/$defs/TaskReadiness",
          "description": "Where it stands, which is what says whether unblocking it is work or a decision."
        },
        "weight": {
          "description": "How many that is. The number the list is ordered by.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "issue",
        "readiness",
        "blocks",
        "weight"
      ],
      "type": "object"
    },
    "DevTaskDiagnostic": {
      "description": "One thing wrong with this task's records, in the shape `project.finding-carries-reproduce`\nasks for.",
      "properties": {
        "code": {
          "description": "The stable code a reader greps for.",
          "type": "string"
        },
        "level": {
          "description": "`FAIL` or `WARN`, as the plan's own finding levels.",
          "type": "string"
        },
        "message": {
          "description": "What is wrong, in one line.",
          "type": "string"
        },
        "reproduce": {
          "description": "The one command that shows it again.",
          "type": "string"
        }
      },
      "required": [
        "level",
        "code",
        "message",
        "reproduce"
      ],
      "type": "object"
    },
    "FieldProvenance": {
      "description": "Where a value came from, and therefore how much weight a reader may put on it.\n\nThe four words are not degrees of confidence, they are four different relations to the\nrepository, and the distinction that matters most is the first from the last two: a\nperson wrote it, or a machine worked it out.\n\n```\nuse majordomus_cli::devtask::{AttestedText, FieldProvenance};\n\n// a value the record itself carried\nlet title = AttestedText::explicit(\"Ship it\", \".ai/repo/project/issues/I0001.yaml#title\");\nassert_eq!(title.provenance, FieldProvenance::Explicit);\n\n// a key the record does not have is unknown, and unknown carries no value\nlet missing = AttestedText::unknown(\n    \".ai/repo/project/issues/I0001.yaml#objective\",\n    \"the record declares no `objective`\",\n);\nassert_eq!(missing.provenance, FieldProvenance::Unknown);\nassert!(missing.value.is_none());\n```",
      "oneOf": [
        {
          "const": "explicit",
          "description": "A person authored it, in the canonical record, under this key. The strongest thing\nthat can be said about a value, and the only one that survives a rewrite of every\nderivation in this repository.",
          "type": "string"
        },
        {
          "const": "derived",
          "description": "A machine worked it out from records or from git, by a rule that cannot be wrong\nabout a repository it can read: an issue's dependents are the issues that name it.\nRe-derived on every call and stored nowhere.",
          "type": "string"
        },
        {
          "const": "inferred",
          "description": "A machine worked it out by a rule that *can* be wrong, because the relation it reads\nwas never declared: a session belongs to an issue because its branch name contains\nthe issue's id. Useful, and never to be mistaken for a declaration.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Not available. Either the record does not carry the key, or the fact lives outside\nwhat this process may read — a live GitHub state, for one — and the field says which\nin its `reason`. An unknown field never carries a value.",
          "type": "string"
        }
      ]
    },
    "MilestoneCounts": {
      "description": "One milestone's issues counted by readiness, plus the two denominators.",
      "properties": {
        "by_readiness": {
          "additionalProperties": {
            "format": "uint32",
            "minimum": 0,
            "type": "integer"
          },
          "description": "One entry per readiness state that has at least one issue, keyed by its word.",
          "type": "object"
        },
        "required": {
          "description": "Total less cancelled: the denominator a progress figure uses.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "total": {
          "description": "Every issue naming this milestone.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "total",
        "required",
        "by_readiness"
      ],
      "type": "object"
    },
    "MilestoneEdge": {
      "description": "One dependency edge of the milestone's graph, `from` before `to`.",
      "properties": {
        "external": {
          "description": "True when one end is outside this milestone. Such an edge is why a milestone can be\nentirely blocked with nothing wrong inside it, so it is marked rather than dropped.",
          "type": "boolean"
        },
        "from": {
          "description": "The issue that must be real first.",
          "type": "string"
        },
        "to": {
          "description": "The issue that waits for it.",
          "type": "string"
        }
      },
      "required": [
        "from",
        "to",
        "external"
      ],
      "type": "object"
    },
    "MilestoneNode": {
      "description": "One issue of a milestone, as a node of its graph.",
      "properties": {
        "blocked_by": {
          "description": "What is not `DONE` yet, plus the milestone gate when it applies.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "canonical_status": {
          "description": "The canonical status it refines.",
          "type": "string"
        },
        "dependents": {
          "description": "The issues that wait on it directly.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "issue": {
          "description": "The issue id.",
          "type": "string"
        },
        "parallel_safe": {
          "description": "Whether it may run beside another issue of its wave.",
          "type": "boolean"
        },
        "priority": {
          "description": "`p0` … `p3`.",
          "type": "string"
        },
        "readiness": {
          "$ref": "#/$defs/TaskReadiness",
          "description": "Where it stands as work."
        },
        "scope": {
          "description": "The paths it touches.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "title": {
          "description": "One line naming the outcome.",
          "type": "string"
        },
        "transitive_dependents": {
          "description": "How many issues wait on it directly or through another.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "wave": {
          "description": "The execution wave, absent when a cycle prevents it from having one.",
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "issue",
        "title",
        "readiness",
        "canonical_status",
        "priority",
        "parallel_safe",
        "blocked_by",
        "dependents",
        "transitive_dependents",
        "scope"
      ],
      "type": "object"
    },
    "ParallelSet": {
      "description": "One subset of the startable work that may genuinely run at the same time.",
      "properties": {
        "issues": {
          "description": "The issues, in canonical order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "serialised": {
          "description": "Why the set is not larger: the candidates of the same wave that had to be serialised\nagainst something already in it.",
          "items": {
            "$ref": "#/$defs/ScopeConflict"
          },
          "type": "array"
        },
        "wave": {
          "description": "The wave every issue in it belongs to.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "wave",
        "issues",
        "serialised"
      ],
      "type": "object"
    },
    "ScopeConflict": {
      "description": "Two issues of one wave that cannot run together, and the path that stops them.",
      "properties": {
        "excluded": {
          "description": "The issue that could not join it.",
          "type": "string"
        },
        "held": {
          "description": "The issue already in the set.",
          "type": "string"
        },
        "path": {
          "description": "The scope path they share, as one of them declares it.",
          "type": "string"
        }
      },
      "required": [
        "held",
        "excluded",
        "path"
      ],
      "type": "object"
    },
    "TaskReadiness": {
      "description": "Where a development task stands, as work.\n\n```\nuse majordomus_cli::devtask::TaskReadiness;\n\n// every state names the canonical status it refines, and refines only one\nassert_eq!(TaskReadiness::Ready.canonical(), \"READY\");\nassert_eq!(TaskReadiness::Waiting.canonical(), \"BLOCKED\");\nassert_eq!(TaskReadiness::Blocked.canonical(), \"BLOCKED\");\nassert_eq!(TaskReadiness::Review.canonical(), \"VERIFY\");\nassert_eq!(TaskReadiness::CompletionBlocked.canonical(), \"VERIFY\");\n\n// and one state is the absence of a record rather than a status of one\nassert!(TaskReadiness::Undeclared.canonical().is_empty());\n```",
      "oneOf": [
        {
          "const": "ready",
          "description": "Nothing holds it back and nobody has started it. Canonical `READY`.",
          "type": "string"
        },
        {
          "const": "blocked",
          "description": "At least one issue it depends on is not `DONE`. Canonical `BLOCKED`.",
          "type": "string"
        },
        {
          "const": "waiting",
          "description": "Every issue dependency is satisfied; the milestone gate holds it. Canonical\n`BLOCKED`, and a distinct situation because it is resolved in another milestone.",
          "type": "string"
        },
        {
          "const": "in_progress",
          "description": "Execution began: the record carries `started_at`. Canonical `ACTIVE`.",
          "type": "string"
        },
        {
          "const": "review",
          "description": "Implementation is declared finished and completion has not been recorded: the record\ncarries `verified_at`. Canonical `VERIFY`.",
          "type": "string"
        },
        {
          "const": "completion_blocked",
          "description": "Completion *was* recorded and the evidence the record itself requires is not all\nthere, so the plan refuses to call it `DONE`. Canonical `VERIFY`, and the case the\n`evidence_missing` finding is about.",
          "type": "string"
        },
        {
          "const": "complete",
          "description": "Finished on its own terms: not cancelled, completion recorded, every required\nevidence token present. Canonical `DONE`.",
          "type": "string"
        },
        {
          "const": "cancelled",
          "description": "Withdrawn. Canonical `CANCELLED`.",
          "type": "string"
        },
        {
          "const": "undeclared",
          "description": "The canonical model does not declare this id. Not a status: the absence of a record.",
          "type": "string"
        }
      ]
    }
  },
  "description": "One milestone as an executable dependency graph.",
  "properties": {
    "active": {
      "description": "The issues somebody has started.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "blocked": {
      "description": "The issues waiting on a peer.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "blocked_by": {
      "$ref": "#/$defs/AttestedList",
      "description": "Those of them that are not `DONE`. Non-empty means every issue here is held back\nwhatever its own dependencies say."
    },
    "cancelled": {
      "description": "The issues withdrawn.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "complete": {
      "description": "The issues finished on their own terms.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "completion_blocked": {
      "description": "The issues declared complete whose evidence does not back that up.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "counts": {
      "$ref": "#/$defs/MilestoneCounts",
      "description": "The issues counted by readiness."
    },
    "critical_blockers": {
      "description": "What to unblock first, most downstream work first.",
      "items": {
        "$ref": "#/$defs/CriticalBlocker"
      },
      "type": "array"
    },
    "cycles": {
      "description": "Every dependency cycle with an issue of this milestone in it, each as its strongly\nconnected component in canonical order.",
      "items": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "type": "array"
    },
    "declared": {
      "description": "Whether the canonical model declares it. False is answered, not refused.",
      "type": "boolean"
    },
    "dependents": {
      "$ref": "#/$defs/AttestedList",
      "description": "The milestones that require it."
    },
    "depends_on": {
      "$ref": "#/$defs/AttestedList",
      "description": "The milestones it requires, as authored."
    },
    "diagnostics": {
      "description": "Everything wrong with the records of this milestone or of its issues.",
      "items": {
        "$ref": "#/$defs/DevTaskDiagnostic"
      },
      "type": "array"
    },
    "edges": {
      "description": "Every dependency edge with at least one end in this milestone, sorted.",
      "items": {
        "$ref": "#/$defs/MilestoneEdge"
      },
      "type": "array"
    },
    "milestone": {
      "description": "The milestone id, as asked for.",
      "type": "string"
    },
    "nodes": {
      "description": "Every issue of the milestone, in canonical order.",
      "items": {
        "$ref": "#/$defs/MilestoneNode"
      },
      "type": "array"
    },
    "outcome": {
      "$ref": "#/$defs/AttestedText",
      "description": "What is true once it is real, as authored."
    },
    "parallelizable": {
      "description": "The startable work partitioned into subsets that may run at the same time.",
      "items": {
        "$ref": "#/$defs/ParallelSet"
      },
      "type": "array"
    },
    "rank": {
      "$ref": "#/$defs/AttestedCount",
      "description": "Its layer in the milestone graph: what orders the roadmap."
    },
    "ready": {
      "description": "The issues a worker may pick up now.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "record": {
      "description": "Repository-relative path of the canonical record, when there is one.",
      "type": [
        "string",
        "null"
      ]
    },
    "review": {
      "description": "The issues awaiting confirmation.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "status": {
      "$ref": "#/$defs/AttestedText",
      "description": "The derived milestone status."
    },
    "title": {
      "$ref": "#/$defs/AttestedText",
      "description": "One line naming the outcome, as authored."
    },
    "waiting": {
      "description": "The issues waiting only on the milestone gate.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "milestone",
    "declared",
    "title",
    "outcome",
    "status",
    "rank",
    "depends_on",
    "blocked_by",
    "dependents",
    "nodes",
    "edges",
    "ready",
    "blocked",
    "waiting",
    "active",
    "review",
    "completion_blocked",
    "complete",
    "cancelled",
    "critical_blockers",
    "parallelizable",
    "cycles",
    "diagnostics",
    "counts"
  ],
  "title": "MilestoneGraph",
  "type": "object"
}