delivery.feature

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The feature's id, as `product.features` gives it."
    }
  },
  "required": [
    "id"
  ],
  "description": "The input of `delivery.feature`: which feature.",
  "title": "DeliveryFeatureInput"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The feature's id."
    },
    "title": {
      "type": "string",
      "description": "Its title."
    },
    "status": {
      "type": "string",
      "description": "The status its file declares. Editorial, and not one of the dimensions."
    },
    "exists": {
      "type": "boolean",
      "description": "The conjunction: true only when every dimension passes."
    },
    "delivery": {
      "$ref": "#/$defs/DeliveryState",
      "description": "Delivered, or the development stage and what blocks it."
    },
    "dimensions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Dimension"
      },
      "description": "Every dimension, in the order of the conjunction."
    },
    "implementation": {
      "$ref": "#/$defs/Implementation",
      "description": "What it is implemented by."
    }
  },
  "required": [
    "id",
    "title",
    "status",
    "exists",
    "delivery",
    "dimensions",
    "implementation"
  ],
  "description": "One feature against the invariant.",
  "title": "FeatureDelivery",
  "$defs": {
    "DeliveryState": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "const": "delivered"
            }
          },
          "required": [
            "state"
          ],
          "description": "Every dimension passes."
        },
        {
          "type": "object",
          "properties": {
            "stage": {
              "$ref": "#/$defs/DevelopmentStage",
              "description": "How far development has carried it."
            },
            "blocking": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/DimensionId"
              },
              "description": "The dimensions that do not pass, in the order of the conjunction."
            },
            "state": {
              "type": "string",
              "const": "not_delivered"
            }
          },
          "required": [
            "state",
            "stage",
            "blocking"
          ],
          "description": "At least one dimension does not pass."
        }
      ],
      "description": "Delivered, or not — and when not, how far development got and which dimensions stand in\nthe way. Two variants of one type rather than a flag beside a stage: a delivered feature\nhas no stage to report, and a stage can never be read as delivery."
    },
    "DevelopmentStage": {
      "oneOf": [
        {
          "type": "string",
          "const": "unknown",
          "description": "Git could not say where its implementation is."
        },
        {
          "type": "string",
          "const": "not_implemented",
          "description": "It names no implementation, or nothing ever committed one."
        },
        {
          "type": "string",
          "const": "implemented_on_branch",
          "description": "Its latest implementation revision is on a branch and not on the trunk."
        },
        {
          "type": "string",
          "const": "on_master",
          "description": "Its implementation is on the trunk."
        },
        {
          "type": "string",
          "const": "tested",
          "description": "On the trunk, with every required test current."
        },
        {
          "type": "string",
          "const": "deployed",
          "description": "Tested, and contained in what the public site serves."
        }
      ],
      "description": "How far development has carried a feature that does not exist yet. A ladder: a rung is\nreached only when every rung below it passes, so a feature whose tests are unknown is\n`on_master` even when the site already serves it."
    },
    "DimensionId": {
      "oneOf": [
        {
          "type": "string",
          "const": "on_master",
          "description": "The feature's latest implementation revision is reachable from the trunk."
        },
        {
          "type": "string",
          "const": "deployed",
          "description": "The public site's identity commit contains that revision."
        },
        {
          "type": "string",
          "const": "publicly_verified",
          "description": "The publication was verified from outside: the site answers with a clean identity,\na second probe agrees, and GitHub's own build of the published branch succeeded."
        },
        {
          "type": "string",
          "const": "required_tests_current",
          "description": "Every test the feature requires has a current passing execution."
        },
        {
          "type": "string",
          "const": "test_evidence_published",
          "description": "The evidence of those executions is published."
        },
        {
          "type": "string",
          "const": "ui_linked",
          "description": "The feature is linked from the user interface."
        }
      ],
      "description": "The six dimensions of the delivery invariant, in the order the conjunction is written."
    },
    "Dimension": {
      "type": "object",
      "properties": {
        "dimension": {
          "$ref": "#/$defs/DimensionId",
          "description": "Which dimension."
        },
        "verdict": {
          "$ref": "#/$defs/DeliveryVerdict",
          "description": "Pass, fail or unknown."
        },
        "reason": {
          "type": "string",
          "description": "What was observed, in one sentence."
        },
        "remediation": {
          "type": [
            "string",
            "null"
          ],
          "description": "What would change the verdict; absent on a pass."
        }
      },
      "required": [
        "dimension",
        "verdict",
        "reason"
      ],
      "description": "One dimension, decided: the verdict, the sentence that decided it, and what would move it."
    },
    "DeliveryVerdict": {
      "oneOf": [
        {
          "type": "string",
          "const": "pass",
          "description": "The dimension holds, and the reason says what was observed."
        },
        {
          "type": "string",
          "const": "fail",
          "description": "The dimension was measured and does not hold."
        },
        {
          "type": "string",
          "const": "unknown",
          "description": "The dimension could not be measured. Not a pass."
        }
      ],
      "description": "One dimension's answer. Three values and never two: a question that could not be asked\nis not a question answered yes, and it is not one answered no either."
    },
    "Implementation": {
      "type": "object",
      "properties": {
        "paths": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Repository-relative paths, derived from what the feature names: the source file of\nevery capability module, `lib/<command>.sh` of every shell command the dispatcher\nsources, and the `implementation` of every claim."
        },
        "head_revision": {
          "type": [
            "string",
            "null"
          ],
          "description": "The latest commit touching them reachable from `HEAD`."
        },
        "master_revision": {
          "type": [
            "string",
            "null"
          ],
          "description": "The latest commit touching them reachable from the trunk."
        }
      },
      "required": [
        "paths"
      ],
      "description": "The paths a feature is implemented by and the revisions that last touched them."
    }
  }
}