@opensoftware/contracts 1.6.0 → 1.8.0

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.6.0",
+    "version": "1.8.0",
     "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
@@ -116,6 +116,355 @@
           }
         }
       }
+    },
+    "/v1/runs": {
+      "post": {
+        "operationId": "ForemanApi_startRun",
+        "description": "Start a run of the factory's workflow for a work item. The same work item again answers the run it started.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WorkItem"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs/{runId}": {
+      "get": {
+        "operationId": "ForemanApi_getRun",
+        "description": "A run: its state and the state of each stage.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs/{runId}/signals": {
+      "post": {
+        "operationId": "ForemanApi_signalRun",
+        "description": "Steer the running stage's agent, or cancel the run.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "202": {
+            "description": "The request has been accepted for processing, but processing has not yet completed.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The request conflicts with the current state of the server.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RunSignal"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/work-items": {
+      "post": {
+        "operationId": "IntakeApi_submitWork",
+        "description": "Put work into the inbox. A submission with the dedupe key of a work item answers that work item.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WorkSubmission"
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "IntakeApi_findWorkItem",
+        "description": "The work item with this dedupe key, such as an issue's link (ADR 0065).",
+        "parameters": [
+          {
+            "name": "dedupeKey",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "explode": false
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/work-items/{workItemId}": {
+      "get": {
+        "operationId": "IntakeApi_getWorkItem",
+        "description": "A work item, its status and every request that asked for it.",
+        "parameters": [
+          {
+            "name": "workItemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "security": [
@@ -347,6 +696,37 @@
         "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$",
         "description": "A path inside the bundle: relative, forward slashes, no \"..\"."
       },
+      "CheckName": {
+        "type": "string",
+        "minLength": 1,
+        "description": "The name of a check on the forge: a commit status context."
+      },
+      "CheckState": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "success",
+          "failure",
+          "error"
+        ],
+        "description": "foreman: the state of a check on the forge (forge port)."
+      },
+      "CheckView": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "$ref": "#/components/schemas/CheckName"
+          },
+          "state": {
+            "$ref": "#/components/schemas/CheckState"
+          }
+        },
+        "required": [
+          "name",
+          "state"
+        ],
+        "description": "foreman: a check that a stage waits for, as the foreman last read it on the run's pull request (ADR 0069)."
+      },
       "CommitHash": {
         "type": "string",
         "pattern": "^[0-9a-f]{7,40}$",
@@ -894,63 +1274,165 @@
             },
             "description": "The groups whose members may decide. Empty when the policy approved without a person."
           },
-          "escalateTo": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Name"
-            },
-            "description": "The groups asked after the escalation time."
+          "escalateTo": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups asked after the escalation time."
+          },
+          "channel": {
+            "type": "string",
+            "description": "Where people decide, for example \"slack:C0GATES\"."
+          },
+          "state": {
+            "$ref": "#/components/schemas/GateState"
+          },
+          "waitingFor": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups that may decide now. Only while the gate is pending."
+          },
+          "requestedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expiresAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the gate expires without a decision."
+          },
+          "record": {
+            "$ref": "#/components/schemas/GateRecord",
+            "description": "The record, once the gate is decided."
+          }
+        },
+        "required": [
+          "id",
+          "workItem",
+          "stage",
+          "summary",
+          "approvers",
+          "channel",
+          "state",
+          "requestedAt"
+        ],
+        "description": "gatekeeper: a gate as the HTTP API shows it (ADR 0048)."
+      },
+      "Hostname": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$",
+        "description": "A hostname without scheme or port, for example \"api.linear.app\"."
+      },
+      "Identifier": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128,
+        "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+      },
+      "IssueLabeled": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "issue.labeled@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/IssueLabeledData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "forge adapters: a label was added to an issue."
+      },
+      "IssueLabeledData": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The issue."
+          },
+          "repository": {
+            "type": "string",
+            "format": "uri"
+          },
+          "number": {
+            "type": "integer",
+            "minimum": 1
           },
-          "channel": {
+          "title": {
             "type": "string",
-            "description": "Where people decide, for example \"slack:C0GATES\"."
+            "minLength": 1
           },
-          "state": {
-            "$ref": "#/components/schemas/GateState"
+          "body": {
+            "type": "string"
           },
-          "waitingFor": {
+          "author": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who opened the issue."
+          },
+          "labels": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/Name"
+              "type": "string"
             },
-            "description": "The groups that may decide now. Only while the gate is pending."
+            "description": "Every label of the issue after the change."
           },
-          "requestedAt": {
-            "type": "string",
-            "format": "date-time"
-          },
-          "expiresAt": {
+          "label": {
             "type": "string",
-            "format": "date-time",
-            "description": "When the gate expires without a decision."
-          },
-          "record": {
-            "$ref": "#/components/schemas/GateRecord",
-            "description": "The record, once the gate is decided."
+            "description": "The label that was added, when the forge names it."
           }
         },
         "required": [
-          "id",
-          "workItem",
-          "stage",
-          "summary",
-          "approvers",
-          "channel",
-          "state",
-          "requestedAt"
-        ],
-        "description": "gatekeeper: a gate as the HTTP API shows it (ADR 0048)."
-      },
-      "Hostname": {
-        "type": "string",
-        "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$",
-        "description": "A hostname without scheme or port, for example \"api.linear.app\"."
-      },
-      "Identifier": {
-        "type": "string",
-        "minLength": 1,
-        "maxLength": 128,
-        "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+          "url",
+          "repository",
+          "number",
+          "title",
+          "author",
+          "labels"
+        ]
       },
       "Link": {
         "type": "object",
@@ -1548,119 +2030,308 @@
             "$ref": "#/components/schemas/Name",
             "description": "Where the run was started from, for example \"slack\", \"github\", \"cli\"."
           },
-          "osf.origin.url": {
+          "osf.origin.url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "osf.harness.name": {
+            "$ref": "#/components/schemas/Name",
+            "description": "Harness adapter, for example \"claude-code\"."
+          },
+          "osf.harness.version": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "service.name",
+          "osf.run.id",
+          "osf.work_item.id",
+          "osf.factory.version",
+          "osf.requester.kind",
+          "osf.requester.id",
+          "osf.source",
+          "osf.harness.name"
+        ],
+        "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
+      },
+      "RunSignal": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/RunSignalType"
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The steering message. Required with \"steer\"."
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "description": "foreman: a signal to a run: \"steer\" with a message for the running stage's agent, or \"cancel\"."
+      },
+      "RunSignalType": {
+        "type": "string",
+        "enum": [
+          "steer",
+          "cancel"
+        ],
+        "description": "foreman: what a person tells a run."
+      },
+      "RunSpan": {
+        "type": "object",
+        "properties": {
+          "gen_ai.operation.name": {
+            "type": "string",
+            "const": "invoke_agent"
+          },
+          "gen_ai.provider.name": {
+            "type": "string"
+          },
+          "gen_ai.agent.name": {
+            "type": "string"
+          },
+          "gen_ai.conversation.id": {
+            "type": "string",
+            "description": "The harness session ID."
+          },
+          "gen_ai.request.model": {
+            "type": "string"
+          },
+          "gen_ai.response.model": {
+            "type": "string"
+          },
+          "gen_ai.usage.input_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "gen_ai.usage.output_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "gen_ai.usage.cache_read.input_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "gen_ai.usage.cache_write.input_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "osf.outcome": {
+            "$ref": "#/components/schemas/RunOutcome"
+          },
+          "osf.cost.usd": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Cost of all model calls of the run, from the inference gateway."
+          },
+          "osf.transcript.uri": {
+            "type": "string",
+            "format": "uri",
+            "description": "Full transcript, stored when the run ends."
+          },
+          "osf.artifact.uris": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            },
+            "description": "Artifacts of the run: reports, screenshots, videos."
+          },
+          "osf.pull_request.urls": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "osf.issue.urls": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "osf.evidence_bundle.uri": {
+            "type": "string",
+            "format": "uri"
+          },
+          "osf.agent_trace.uri": {
+            "type": "string",
+            "format": "uri",
+            "description": "Agent Trace record with line attribution of the run's changes."
+          }
+        },
+        "required": [
+          "gen_ai.operation.name",
+          "osf.outcome"
+        ],
+        "description": "Attributes of the root span of the run. GenAI names where a convention exists."
+      },
+      "RunStarted": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "run.started@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/RunStartedData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "foreman: a run started (ADR 0067)."
+      },
+      "RunStartedData": {
+        "type": "object",
+        "properties": {
+          "runId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "workItemId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "factory": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The name of the factory."
+          },
+          "factoryVersion": {
+            "$ref": "#/components/schemas/CommitHash"
+          },
+          "stages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The stages of the run's workflow, in order."
+          },
+          "startedAt": {
             "type": "string",
-            "format": "uri"
+            "format": "date-time"
           },
-          "osf.harness.name": {
-            "$ref": "#/components/schemas/Name",
-            "description": "Harness adapter, for example \"claude-code\"."
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
           },
-          "osf.harness.version": {
-            "type": "string"
+          "source": {
+            "$ref": "#/components/schemas/Name"
           }
         },
         "required": [
-          "service.name",
-          "osf.run.id",
-          "osf.work_item.id",
-          "osf.factory.version",
-          "osf.requester.kind",
-          "osf.requester.id",
-          "osf.source",
-          "osf.harness.name"
+          "runId",
+          "workItemId",
+          "factory",
+          "factoryVersion",
+          "stages",
+          "startedAt",
+          "requester",
+          "source"
+        ]
+      },
+      "RunState": {
+        "type": "string",
+        "enum": [
+          "running",
+          "blocked",
+          "complete",
+          "failed",
+          "cancelled"
         ],
-        "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
+        "description": "foreman: where a run stands (vision scenario ORCH-008)."
       },
-      "RunSpan": {
+      "RunView": {
         "type": "object",
         "properties": {
-          "gen_ai.operation.name": {
-            "type": "string",
-            "const": "invoke_agent"
-          },
-          "gen_ai.provider.name": {
-            "type": "string"
-          },
-          "gen_ai.agent.name": {
-            "type": "string"
-          },
-          "gen_ai.conversation.id": {
+          "runId": {
             "type": "string",
-            "description": "The harness session ID."
-          },
-          "gen_ai.request.model": {
-            "type": "string"
-          },
-          "gen_ai.response.model": {
-            "type": "string"
-          },
-          "gen_ai.usage.input_tokens": {
-            "type": "integer",
-            "minimum": 0
-          },
-          "gen_ai.usage.output_tokens": {
-            "type": "integer",
-            "minimum": 0
+            "pattern": "^run_[0-9a-f]{20}$",
+            "description": "\"run_\" and 20 hex digits of the SHA-256 of the work item's ID."
           },
-          "gen_ai.usage.cache_read.input_tokens": {
-            "type": "integer",
-            "minimum": 0
+          "workItem": {
+            "$ref": "#/components/schemas/WorkItem"
           },
-          "gen_ai.usage.cache_write.input_tokens": {
-            "type": "integer",
-            "minimum": 0
+          "factory": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The name of the factory."
           },
-          "osf.outcome": {
-            "$ref": "#/components/schemas/RunOutcome"
+          "factoryVersion": {
+            "$ref": "#/components/schemas/CommitHash",
+            "description": "The commit of the factory definition the run started with."
           },
-          "osf.cost.usd": {
-            "type": "number",
-            "minimum": 0,
-            "description": "Cost of all model calls of the run, from the inference gateway."
+          "state": {
+            "$ref": "#/components/schemas/RunState"
           },
-          "osf.transcript.uri": {
+          "pullRequest": {
             "type": "string",
             "format": "uri",
-            "description": "Full transcript, stored when the run ends."
+            "description": "The last pull request link that an agent of the run wrote (ADR 0069)."
           },
-          "osf.artifact.uris": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "format": "uri"
-            },
-            "description": "Artifacts of the run: reports, screenshots, videos."
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
           },
-          "osf.pull_request.urls": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "format": "uri"
-            }
+          "endedAt": {
+            "type": "string",
+            "format": "date-time"
           },
-          "osf.issue.urls": {
+          "stages": {
             "type": "array",
             "items": {
-              "type": "string",
-              "format": "uri"
-            }
-          },
-          "osf.evidence_bundle.uri": {
-            "type": "string",
-            "format": "uri"
-          },
-          "osf.agent_trace.uri": {
-            "type": "string",
-            "format": "uri",
-            "description": "Agent Trace record with line attribution of the run's changes."
+              "$ref": "#/components/schemas/StageView"
+            },
+            "description": "The stages of the workflow, in order."
           }
         },
         "required": [
-          "gen_ai.operation.name",
-          "osf.outcome"
+          "runId",
+          "workItem",
+          "factory",
+          "factoryVersion",
+          "state",
+          "startedAt",
+          "stages"
         ],
-        "description": "Attributes of the root span of the run. GenAI names where a convention exists."
+        "description": "foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067)."
       },
       "Sandbox": {
         "type": "object",
@@ -2021,6 +2692,13 @@
             "$ref": "#/components/schemas/Gate",
             "description": "The stage waits for a decision before it starts."
           },
+          "checks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CheckName"
+            },
+            "description": "Checks that must succeed on the run's pull request before the stage starts, by their names on the forge, for\nexample \"verify\" (ADR 0069)."
+          },
           "evidence": {
             "$ref": "#/components/schemas/EvidenceRequirement",
             "description": "Whether the stage must produce an evidence bundle."
@@ -2031,6 +2709,69 @@
         ],
         "additionalProperties": false
       },
+      "StageState": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "blocked",
+          "running",
+          "succeeded",
+          "failed",
+          "rejected",
+          "cancelled"
+        ],
+        "description": "foreman: where a stage of a run stands."
+      },
+      "StageView": {
+        "type": "object",
+        "properties": {
+          "stage": {
+            "$ref": "#/components/schemas/Name"
+          },
+          "agent": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The agent that runs the stage."
+          },
+          "state": {
+            "$ref": "#/components/schemas/StageState"
+          },
+          "sessionId": {
+            "type": "string",
+            "description": "The harness session of the stage's agent, once it started."
+          },
+          "gateId": {
+            "type": "string",
+            "pattern": "^g[0-9a-f]{16}$",
+            "description": "The gate that decides whether the stage starts, once it was requested."
+          },
+          "checks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CheckView"
+            },
+            "description": "The checks the stage waits for, once the foreman read them (ADR 0069)."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why the stage ended without success, when the foreman knows."
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "endedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "stage",
+          "agent",
+          "state"
+        ],
+        "description": "foreman: one stage of a run (ADR 0067)."
+      },
       "TraceId": {
         "type": "string",
         "pattern": "^[0-9a-f]{32}$",
@@ -2104,6 +2845,13 @@
         ],
         "description": "One unit of requested work: the `data` of a `work.received@v1` CloudEvent."
       },
+      "WorkItemStatus": {
+        "type": "string",
+        "enum": [
+          "received"
+        ],
+        "description": "Where a work item stands."
+      },
       "WorkItemType": {
         "type": "string",
         "enum": [
@@ -2113,6 +2861,36 @@
           "automation"
         ]
       },
+      "WorkItemView": {
+        "type": "object",
+        "properties": {
+          "workItem": {
+            "$ref": "#/components/schemas/WorkItem",
+            "description": "Its ID is \"wi_\" and 20 hex digits of the SHA-256 of its dedupe key."
+          },
+          "status": {
+            "$ref": "#/components/schemas/WorkItemStatus"
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "requests": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/WorkRequest"
+            },
+            "description": "Every submission that asked for the work item, oldest first; one per origin."
+          }
+        },
+        "required": [
+          "workItem",
+          "status",
+          "receivedAt",
+          "requests"
+        ],
+        "description": "intake: a work item as the HTTP API shows it (ADR 0063)."
+      },
       "WorkReceived": {
         "type": "object",
         "properties": {
@@ -2166,6 +2944,70 @@
           "data"
         ],
         "description": "intake: a work item was accepted."
+      },
+      "WorkRequest": {
+        "type": "object",
+        "properties": {
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "origin": {
+            "$ref": "#/components/schemas/Origin"
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "requester",
+          "origin",
+          "receivedAt"
+        ],
+        "description": "intake: one submission that asked for a work item."
+      },
+      "WorkSubmission": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/WorkItemType",
+            "description": "Default: task."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          },
+          "description": {
+            "type": "string"
+          },
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "origin": {
+            "$ref": "#/components/schemas/Origin"
+          },
+          "dedupeKey": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Requests with the same key become one work item. Default: the origin's url, else \"<source>:<externalId>\"."
+          },
+          "surface": {
+            "type": "string"
+          },
+          "links": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Link"
+            }
+          }
+        },
+        "required": [
+          "title",
+          "requester",
+          "origin"
+        ],
+        "description": "intake: work to put into the inbox, a work item without its ID (ADR 0063)."
       }
     },
     "securitySchemes": {