Physical work: products, installations, devices and actions on the world

Load when the output includes anything physical (a device, a product made or fitted, an installation, equipment), or when the work issues commands that move, heat, dispense, spend or send: actuators, relays, motors, valves, heaters, robots, vehicles, instruments, machine tools, building controls, and services behind an API that ship, pay, dispense, dispatch or message a person. Software lets you try, look and revert; the physical world lets you do none of those, so the habits that make an agent good at software make it dangerous here.

The chain a physical result passes through, each link its own piece of evidence: specified, ordered within authority, received, inspected, assembled or installed, commissioned, accepted, handed over. An order is not receipt; receipt is not a passed inspection; a passed inspection is not an installation; passing software tests is not system acceptance.

Specification and interfaces

• Specify what is to be made or installed so it can be checked: dimensions and tolerances, materials, ratings (voltage, current, pressure, temperature, load), environment (indoor, outdoor, ingress protection, temperature range), standards it must meet, and how each will be verified.
• Record every interface between parts and between the physical and the software side: connectors and pinouts, protocols and message formats, mounting, power, units, and which side owns each (§Hybrid versions and compatibility).
• Design the controls with the person in mind: the button where the thumb is, one meaning per light, a sound or a feel for each state a light shows, the reset explained on the device (design.md).

Procurement, receipt and inspection

1. Order within authority. A purchase is an action outside the working environment: within the standing spending limit, or with the owner’s yes to the exact order (supplier, part numbers, quantities, price, delivery date). Record the order and the supplier’s confirmed delivery date as a dependency in the plan (planning.md §Dependencies and the schedule).
2. On delivery, record receipt against the order: what arrived, part numbers, quantities, lot or serial numbers, condition of packaging, and what is missing or wrong. A courier’s “delivered” is not receipt; someone must count it.
3. Inspect before use, against the specification: the checks (dimensions, markings, a functional test, a sample measurement), who did them, when, and the result. Parts that fail are quarantined and returned or replaced, and the forecast updated.
4. A late or wrong delivery changes the forecast and the next ready work; it never lets anyone mark installation done, and it is not a reason to rebuild unrelated work.

Parts, suppliers and lead times

• The bill of materials at the planned quantity, with each part’s source, price, lead time and a second source (or a design that tolerates the substitute). Compare part families, not just one part (decisions.md §Options).
• Cost at quantity against the price people will pay, with certification, tooling, packaging and shipping included.
• Lead times drive the schedule: record delivery dates and the work that depends on receipt and inspection; calculate float and the effect of delay on completion (planning.md §Critical path and resources). A long lead time alone does not make a delivery critical. Prioritise ordering from that schedule, within procurement authority.
• At each review, recheck prices, stock and end-of-life notices, and route around a part that went out of stock or up in price.

Assembly, test jigs and calibration

• Assembly is a written procedure a person other than the designer can follow: steps, tools, torque or settings, and the check after each critical step.
• A test jig or fixture checks every unit the same way, with its own verification (a known-good and a known-bad unit through it).
• Calibration and provisioning (identity, keys, configuration, firmware version) are procedures with records per unit: which unit, which values, by whom, when.

Installation, commissioning and acceptance

1. Ready to install means: the parts received and inspected, the compatible software and configuration versions available (§Hybrid versions and compatibility), the site ready (access, power, mounting, conditions), the installer available, and the work authorised.
2. Install by the written procedure, recording what was installed where, with serial numbers and versions (the as-built record).
3. Commission on site against a checklist written before the visit: one row per function in the acceptance criteria (each sensor, each alert, each failure path, the safe state), each run on the installed configuration under the real conditions, with the result recorded. List anything outstanding (a punch list) with owners. Write the as-built record and the handover the same day, marking pending whatever a blocker still holds.
4. Inspections the law requires (electrical, gas, structural, radio, medical, food and the like) are done by a competent, qualified person and recorded; an agent’s review never substitutes for them.
5. Acceptance is the acceptor checking the installed result against the acceptance criteria and signing it off, with the punch list closed or agreed.
6. Act for real once, observed, with confirmation where it is required, then record the verdict.
7. Handover: ../templates/handover.md (operator, manuals, spares, service schedule, warranty).

Commands and observed outcomes

Reading is not commanding. Reading a sensor, a status, a meter or a log changes nothing in the world, so it needs no action contract and no approval beyond access to the device. Commissioning, diagnosis and resumption start by reading the installed device. Only an action that changes the world (a relay, a valve, a motor, a payment, a message) needs the contract below and its authority.

Before any command reaches the physical world, write its contract:

• the target state it should leave the world in;
• the independent observation that will confirm it (a sensor, a limit switch, a flow meter, a camera, a delivery scan, a person), not the echo of the command;
• the deadline by which the observation must match;
• the safe state if it does not;
• whether it can be undone;
• the units of every number.

An action whose contract you cannot fill in is not ready to run. Then:

• Confirm through the independent observation, timestamped after the action. The controller accepting the command, the cloud queueing it, the relay switching or the API returning 200 are not outcomes: the valve behind the relay may be seized. If the only readback is the device reporting its own setpoint, the result is not verified. Evidence that cannot tell “done” from “not done” (a cached reading, a status that echoes the setpoint, a frame from before the action) is not evidence.
• Wait with a deadline, polling until the observation matches or the deadline passes; at the deadline go to the safe state and report the last thing observed. Not a sleep, and not forever.
• Make commands idempotent, or do not retry them: absolute targets (“set to closed”) rather than changes (“close”, “move 10 mm further”) or toggles. Where an action is inherently not idempotent (dispense, pay, send, cut), retry only after an observation proves the first attempt did not happen, and use an idempotency key wherever the service supports one. “Dispense 10 ml” retried after a timeout dispenses 20.
• State units at every boundary: in names (temp_c, distance_mm), configuration keys and logs; convert once, at the edge, with a test using a value that differs between the two units (millimetres and inches, Celsius and Fahrenheit, local time and UTC, the robot’s frame and the world’s).
• Keep an action log: for every command, when, what, to which target, why, the observation before and after, and the verdict, so a person can reconstruct what was done to the world from the log.
• Report one row per physical action: its target, its contract, the safeguards found, the safeguards added, and the result. Verified means an independent observation confirmed the outcome; failed means the observation contradicted it, or a failure path reached an unsafe state; not verified means no independent observation was possible, and why. Each fix comes with a test that drives the simulator into the failure and asserts the safe state.
• Inventory first: every action the code or task can take on the world, with its target, whether it can be undone and its current safeguards. Look at every exit toward hardware or a real-world service (drivers; serial, GPIO, I2C, Modbus, CAN, MQTT or HTTP clients; vendor SDKs; order, payment and messaging APIs), the configuration that chooses the target, retry and reconnect logic, sensor reads that become decisions, and every limit, interlock, emergency stop and watchdog, and where each is missing.

Safety states and irreversible actions

• Decide the safe state for each actuator, and make every failure path go there: unreadable sensor, lost connection, unparseable reply, exception, timeout. A sensor that cannot be read must never become a default value that keeps the heater on. Where “safe” depends on context (a door that must stay unlocked for a fire exit, a heater protecting against frost), write that down and escalate to a person instead of guessing. Fail toward stopped: when in doubt, do less.
• Enforce limits below the agent: clamp or refuse any setpoint outside the safe physical range in code, and confirm the device or hardware enforces its own limits independently. The agent must never be the only thing between a typo and full power.
• A watchdog on anything that runs until told to stop: the device returns to its safe state if the controller does not refresh it within a bounded interval, or the command carries its own duration. Prove it by killing the controlling process mid-run and observing the device stop. Assume the agent will vanish mid-action.
• A person’s yes for anything that cannot be undone: spending money, sending something to a person, cutting, drilling, dispensing, deleting physical records, moving near people. Show the exact action and its parameters and wait for the yes; a standing authorisation is explicit, scoped and written down. Irreversible means slow down: rehearse in simulation, then do it once for real with someone watching.
• Consider the conditions it runs in: power loss, heat, interference, a person nearby.
• Fix the most dangerous gaps first: failure paths that do not reach the safe state; control channels anyone can use; retries of non-idempotent actions; missing watchdogs and limits; updates that can strand a device; real hardware by default; confirmation from the command’s echo; no action log.

Access to devices

• The control channel is authenticated and authorised: credentials the device checks, scoped to what each caller may do, over an encrypted link, with no default passwords. An endpoint that accepts commands from anything that can reach it is a finding, however private the network is meant to be.
• Limit how often a command can be accepted, so a loop or an attacker cannot cycle a relay or a valve to destruction.

Certification

• Identify the certifications the product needs where it will be sold or installed (radio, electrical safety, electromagnetic compatibility, medical, food contact, toys, pressure and the like), and found them as an area at the start (product.md §Areas and owners): they shape the design and the schedule.
• The marks and declarations ship with the product, and certification is in hand before it ships, not after.

Packaging, shipping, repairs and recalls

• Packaging that survives shipping, tested.
• The first power-on and setup done by someone new, with only what is in the box.
• Spare parts and consumables available; a returns and repair path.
• A way to reach every unit if something must be recalled or updated: who has which serial numbers, and how to contact them.
• The certification marks and declarations shipped with it (§Certification).
• Customs and shipping rules for each place it goes.
• Stage releases: a small first batch, updates that can be paused, and devices that cannot be left unable to start.

Hybrid versions and compatibility

• Record which hardware revision, firmware version, software version and configuration work together, and check the combination at installation.
• Updates are verified before they are applied, applied so that a power cut midway leaves the previous version running, and reversible in one step. An update that can leave a device unable to start is an irreversible physical action like any other.
• Plan the parallel work honestly: software can be built and tested while hardware is in transit, but field commissioning depends on received and inspected hardware, compatible software and an available installer. A delayed sensor or an unavailable installer changes the forecast and the next ready work; it does not make installation complete.

Simulation and what it can establish

• The default target is the simulator or a dry run. Reaching real hardware or a live service takes an explicit setting, and the first line of output names which one is in use.
• Rehearse every action and every failure in simulation (sensor unreadable, device offline, reply timed out, process killed mid-action) and confirm each lands in the safe state, with a test.
• A simulated result establishes how the workflow behaves; it does not establish a real installation, a real measurement or a safety result. Label simulated steps as simulated in every record and report.
• Physical tests leave physical traces: the smallest quantities, lowest energies and widest clearances that still show the behaviour, and put the world back afterwards.