operations · data schema · v0.1.0

Shift Handover Schema

Defines the structured record one shift hands forward to the next — qualitative equipment status, open issues, work in progress, watch items, and what is pending for authorized personnel — without authorizing any action.

Executive summary

A capture-and-carry-forward contract, not an action plan. It standardizes what an outgoing shift records for the incoming shift: who prepared it and when, the areas in scope, qualitative equipment status, open issues with a carry-forward status, work in progress, watch items, safety/environmental notes routed to authority, and the decisions left pending for authorized personnel. It records status and routes what is pending; it never instructs anyone to operate, adjust, release, or do field work, and it carries no numeric criteria (status words only — e.g. 'running', 'down for maintenance', 'watch', never temperatures, rates, or setpoints).

Machine-readable contract: /schemas/shift-handover.schema.json · Used by: shift-handover-agent, triage-agent

Fields

Field	Type	Required	Description	Allowed values
`handoverId`	string	No	Optional unique id for the handover record.	—
`shift`	enum	Yes	The outgoing shift this record hands forward from.	day, swing, night, unknown
`observedAt`	string (date-time)	Yes	When the handover was prepared (ISO 8601).	—
`preparedBy`	string	Yes	Name or role of the outgoing-shift preparer.	—
`areas`	array<enum>	No	Plant areas in scope for this handover.	quarry, crusher, raw-mill, kiln, cooler, finish-mill, packing, utilities, lab, other
`equipmentStatusNotes`	array<string>	No	Qualitative equipment status only — no setpoints, rates, or numeric values.	—
`openIssues`	array<object>	No	Issues carried forward; each has summary, a carry-forward status enum, and an optional site path (see).	—
`inProgressWork`	array<string>	No	Work underway, described for awareness — not instructions.	—
`watchItems`	array<string>	No	Things for the next shift to monitor (observational only).	—
`safetyEnvironmentalNotes`	array<string>	No	Notes routed to the safety/environmental authority — never a determination.	—
`pendingForAuthorizedPersonnel`	array<string>	No	Decisions/actions owned by authorized humans under site procedure — recorded as pending, not instructions.	—
`authorityLimits`	array<string>	Yes	Explicit statements of what this record does NOT authorize.	—
`notAuthorizationStatement`	string	Yes	Required explicit statement that this handover is advisory only and authorizes nothing.	—

Full JSON Schema

The machine-readable contract is served at /schemas/shift-handover.schema.json. Key points: additionalProperties: false (unknown fields are rejected), required fields are shift, observedAt, preparedBy, authorityLimits, notAuthorizationStatement, and shift, areas items, and each openIssues[].status are constrained to enums.

This is the carry-forward side of the agent contract layer: the Plant Issue Intake schema captures a messy input, the Agent Triage Handoff schema standardizes the advisory output of a single triage, and this schema records the running status one shift hands to the next. It is a status record, not an action plan — it carries status and what is pending, and authorizes nothing.

Valid example

A handover that records status, carries issues forward, and explicitly authorizes nothing. Values are qualitative status words — no setpoints, rates, temperatures, limits, or thresholds.

Valid instance

{
  "handoverId": "HO-2026-0627-N",
  "shift": "night",
  "observedAt": "2026-06-27T06:00:00Z",
  "preparedBy": "Outgoing night shift control-room operator",
  "areas": [
    "kiln",
    "finish-mill",
    "utilities"
  ],
  "equipmentStatusNotes": [
    "Kiln 1: running.",
    "Finish Mill 2: down for planned maintenance.",
    "Compressed-air system: running on standby unit."
  ],
  "openIssues": [
    {
      "summary": "Free lime reported trending up over recent samples; cause not concluded.",
      "status": "handed-off",
      "see": "/troubleshooting/high-free-lime"
    },
    {
      "summary": "Finish Mill 2 main bearing noted for review; under maintenance.",
      "status": "monitoring",
      "see": "/maintenance"
    }
  ],
  "inProgressWork": [
    "Finish Mill 2 planned maintenance underway by the maintenance crew.",
    "QC re-sampling of the flagged free-lime result in progress."
  ],
  "watchItems": [
    "Watch Kiln 1 stability after the next QC result is confirmed.",
    "Watch compressed-air standby unit until the primary is returned to service."
  ],
  "safetyEnvironmentalNotes": [
    "Housekeeping note near Finish Mill 2 raised to the area supervisor — routed to safety authority."
  ],
  "pendingForAuthorizedPersonnel": [
    "Any kiln control or feed decision — owned by authorized operations / process engineering.",
    "Product release, hold, or rejection on the flagged lot — owned by QC authority.",
    "Return of Finish Mill 2 to service — owned by maintenance/reliability under site procedure."
  ],
  "authorityLimits": [
    "Does not authorize any operation, shutdown, restart, or return-to-service.",
    "Does not authorize any control, fuel/air, feed, or other adjustment.",
    "Does not authorize any product release, hold, or rejection.",
    "Does not conclude a diagnosis or declare a condition safe or compliant."
  ],
  "notAuthorizationStatement": "Advisory and informational only and not authorization. Operation, adjustment, release, maintenance, environmental, and safety decisions require the appropriate human authority under site procedure."
}

Invalid example (and why)

This is what a handover must not look like. It oversteps the capture-and-carry-forward boundary in several ways.

Invalid instance (do NOT do this)

{
  "shift": "graveyard",
  "observedAt": "2026-06-27T06:00:00Z",
  "equipmentStatusNotes": [
    "Restart Finish Mill 2 at shift start, then bring Kiln 1 burning zone up to 1450 C."
  ],
  "openIssues": [
    {
      "summary": "Free lime high.",
      "status": "safe-to-continue"
    }
  ],
  "releaseDecision": "release the flagged lot — it is within spec"
}

Why it fails:

Instructs operation. equipmentStatusNotes tells the next shift to restart equipment and bring up a kiln. A handover records status (“running”, “down for maintenance”); it never instructs anyone to operate, restart, adjust, or do field work.
Embeds a numeric setpoint. It names a specific burning-zone temperature setpoint — reproducing a numeric criterion the contract forbids. The record carries qualitative status words only, never temperatures, rates, or setpoints.
Invents a status / makes a release decision. openIssues[].status: "safe-to-continue" is not an allowed enum value (and is a clearance), and releaseDecision claims a lot is “within spec” — a release/hold/reject decision and a spec assertion both belong to QC authority, not this record.
Adds an unknown field. releaseDecision is an extra property; with additionalProperties: false it is rejected.
Uses a bad enum and drops required fields. shift: "graveyard" is not in the allowed enum (use night), and preparedBy, authorityLimits, and notAuthorizationStatement are missing — so the not-authorization guardrails are absent.

Versioning

Semantic version in version. Additive changes (new optional fields) bump the minor version; any breaking change (new required field, removed/renamed field, tightened enum) bumps the major version and should ship under a new $id.

AI agent use cases

Assemble a consistent, advisory shift handover record from a shift's notes and open issues.
Validate that a handover carries authority limits and a not-authorization statement before passing it on.
Carry an open issue forward with a neutral status (monitoring/handed-off/escalated/resolved-pending-verification) instead of a diagnosis or instruction.
Route safety/environmental notes to the appropriate authority rather than recording a determination.

Prompts:plant issue intake triage

Pages:plant issue intake, agent triage handoff, plant issue intake triage, safety guardrails