DevAgent Smart Physical Engine

Verification-first commissioning engineering for robotics and industrial automation.

DevAgent turns a customer engineering folder into a bounded verification workflow with immutable Digital Twin lineage, deterministic requirement verdicts, requirement-driven test cases, exact-Twin measured simulation evidence, regression analysis, FAT reporting, replay inspection, and selective retesting.

customer engineering files
    ↓
intake + SHA-256 inventory
    ↓
validated Requirement → Criterion mapping
    ↓
immutable Digital Twin revision
    ↓
requirement-driven nominal / boundary / fault cases
    ↓
qualified exact-Twin simulation when supported
    ↓
measured evidence
    ↓
PASS / FAIL / NOT_TESTED
    ↓
regression + FAT report + Evidence Viewer

AI proposes. Deterministic engines validate, compile, verify, measure, and gate promotion. OEM robot controllers, PLCs, safety PLCs, and certified safety systems remain authoritative.

Quick start

Python 3.11+ is required.

python -m pip install --upgrade devagent-physical-engine==1.8.6

Verify the installed package:

python -c "import devagent_physical_engine as d; print(d.__version__)"

Expected:

1.8.6

Run the normal customer workflow:

devagent verify ./customer-project

Request simulation:

devagent verify ./customer-project --simulate

Open the Evidence Viewer and keep the engineering terminal active:

devagent verify ./customer-project --simulate --open

For machine-readable CI output:

devagent verify ./customer-project --json

Inspect truthful robot support tiers:

devagent robots

For the exact ABB IRB1200 experimental visual runtime:

devagent robot doctor abb_irb1200
devagent robot visualize abb_irb1200

Default locations:

Evidence database: ~/.devagent/projects.db
Results:           <customer-project>/devagent-results/

What DevAgent proves

DevAgent separates planning, execution, measurement, verdicts, and authority.

requirement
  ↓
verification criterion
  ↓
verification case
  ↓
exact Twin revision/hash
  ↓
qualified simulation when available
  ↓
measured evidence
  ↓
PASS / FAIL / NOT_TESTED

A generated plan is not physical proof. A replay is not a new execution. A simulation result does not grant site qualification or real-robot authority.

Current hard boundaries remain:

site_qualification = false
real_execution_allowed = false

unless separately proven by an appropriate qualified process.

v1.6 report-test visual execution foundation

v1.6 connected report tests to the exact stored Twin instead of a separate demo scene.

A supported physical report test follows:

Requirement
  → stable Test ID
  → immutable Requirement → Case mapping
  → exact Verification Plan ID/hash
  → exact Case ID
  → exact Twin revision/hash
  → qualified Gazebo/MoveIt execution
  → typed physical_measurement artifact
  → deterministic verdict

Interactive example:

devagent> tests
devagent> simulate TEST-PERF-001

Measured physical criteria include:

cycle_time_max_s
minimum_clearance_m
final_tcp_error_max_m
max_tracking_error_rad
collision_free
physical_completed

Structural/Twin criteria include:

planning_allowed
physics_allowed
entity_present
validation_issue_absent
twin_state

A requirement without deterministic evidence remains NOT_TESTED; it is never auto-passed from prose or AI interpretation.

v1.6.1 support-contact lift hotfix

The packaged UR5e reference load starts with the workpiece resting on its source support. During attached-object lift departure, DevAgent preserves the complete live MoveIt Allowed Collision Matrix and temporarily enables exactly the attached-workpiece ↔ source-support pair.

That allowance is scoped only to lift departure. Transfer/place keep normal collision checking. DevAgent does not globally disable collision checking or replace the live matrix with an unsafe sparse matrix.

v1.6.2 slower measured visual execution

The packaged visual task uses conservative MoveIt scaling so motion is inspectable while remaining real trajectory execution:

velocity scale:      12%
acceleration scale:   8%

The joint-state recorder also rejects duplicate/backward ROS timestamps instead of manufacturing synthetic time. Collision, endpoint, tracking, Twin-lineage, and authority checks remain fail-closed.

v1.7 industrial PTP/LIN execution

v1.7 moves the qualified UR5e report test to the MoveIt Pilz Industrial Motion Planner rather than hand-building interpolation.

The bounded task sequence is:

HOME
  ↓ PTP
PRE_PICK
  ↓ LIN
PICK
  ↓ grasp hard boundary
LIFT
  ↓ LIN support departure hard boundary
TRANSFER
  ↓ PTP
PLACE
  ↓ LIN release hard boundary
RETRACT
  ↓ LIN
HOME
  ↓ PTP

Original v1.7 execution groups:

approach_pick    PTP → LIN
lift_departure   LIN
transfer_place   PTP → LIN
retreat_home     LIN → PTP

Conservative limits:

PTP velocity scale:       10%
PTP acceleration scale:    6%
LIN velocity scale:        6%
LIN acceleration scale:    4%
requested blend radius:   12 mm
workpiece follow target:   60 Hz

MoveIt/Pilz owns geometry, timestamps, collision checking, velocity/acceleration time parameterization, and the returned RobotTrajectory. DevAgent does not fake smoothness with teleports or sleeps.

v1.7.1 adaptive Pilz blend hotfix

A real ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz target-stack run showed:

approach_pick    PASS
lift_departure   PASS
transfer_place   Pilz FAILURE(99999)
execution        NOT STARTED

Pilz can reject a sequence when a requested blend sphere is not feasible for that specific geometry. v1.7.1 therefore keeps the same PTP/LIN targets, attached/world scene contract, collision policy, velocity/acceleration limits, and execution authority while retrying only the internal blend radius:

12 mm
  ↓ if Pilz returns pilz_sequence_planning_failed
6 mm
  ↓
3 mm
  ↓
0 mm

Every candidate is still planned and collision-checked by MoveIt/Pilz. DevAgent selects the largest candidate Pilz actually accepts. If the zero-blend candidate fails, execution remains blocked.

The fallback is intentionally narrow:

no target modification
no planner-type substitution
no collision disable
no speed increase
no hand-built interpolation
no fake PASS
no fallback to an unqualified simulator or robot

The selected blend radii and every planning attempt receipt remain attached to motion metadata for auditability.

v1.7.2 transfer/place diagnostic hotfix

A target-stack qualification run proved that transfer_place still returned Pilz FAILURE(99999) for every v1.7.1 blend candidate, including zero blend. v1.7.2 therefore does not keep guessing at blend values. When that exact bounded failure occurs, DevAgent remains fail-closed and runs two independent plan-only probes against the same attached-workpiece PlanningScene:

lift target
   ↓
transfer PTP probe
   ↓ independent start at transfer target
place LIN probe

The result is classified deterministically as one of:

pilz_transfer_segment_planning_failed
pilz_place_segment_planning_failed
pilz_transfer_and_place_segment_planning_failed
pilz_transfer_place_sequence_composition_failed

Each probe writes its own request/receipt plus a transfer-place-diagnostic.json summary. These probes never execute motion and never relax targets, planner types, collision policy, attached-workpiece scene state, velocity/acceleration limits, Twin lineage, or real-execution authority. Their purpose is to identify the exact target-stack defect before changing physical execution semantics.

v1.8 truthful robot support + ABB IRB1200 visual runtime

v1.8 makes robot support explicit instead of implying that every built-in robot profile has the same simulator authority.

Support is exposed through:

devagent robots
devagent robot doctor <robot>
devagent robot visualize <robot>

The exact abb_irb1200 profile adds an experimental visual runtime using Ubuntu 24.04, ROS 2 Jazzy, Gazebo Harmonic, gz_ros2_control, upstream ABB IRB1200 geometry, MoveIt, and RViz. Runtime readiness is bounded on controller state, /joint_states, FollowJointTrajectory, move_group, and RViz availability.

For the Golden ABB cell, DevAgent can load the waypoint seed, pre-plan every phase through MoveIt before sending any simulated trajectory, then execute the preview while Gazebo/RViz remain open for inspection.

This is intentionally visual simulation availability, not measured FAT qualification. ABB preview evidence is not promoted to a qualified physical measurement, and real_execution_allowed remains false. The normal One-Command ABB FAT path continues to fail closed until an exact-Twin measured ABB execution adapter is separately qualified.

Generic abb_irb, FANUC CRX, and KUKA KR profiles remain model-only until equivalent vendor/model visual runtimes are implemented and qualified.

v1.8.1 direct UR5e controller/action readiness hotfix

A real UR5e target-stack run proved that Gazebo, gz_ros2_control, the controller manager, joint-state broadcaster, and scaled_joint_trajectory_controller could all initialize successfully while DevAgent remained stuck in startup readiness until the 120-second timeout. The old UR5e readiness gate depended on ROS CLI graph commands and expected the unscaled /joint_trajectory_controller/follow_joint_trajectory action even when the active controller was the scaled UR controller.

v1.8.1 makes UR5e readiness and trajectory execution use one controller-binding contract. A short-lived direct rclpy probe calls /controller_manager/list_controllers, deterministically selects the active trajectory controller, verifies its exact FollowJointTrajectory action server, and returns the bound action name. Required UR5e joint-state readiness continues to use the direct machine joint-state probe.

The readiness gate therefore no longer depends on a long-lived ros2 daemon, ros2 node list, ros2 topic list, or ros2 action list. It remains fail-closed on missing controller-manager service, no active trajectory controller, ambiguous active controllers, a missing trajectory action server, or missing required UR5e joint state. No collision rule, Pilz target, motion speed, Twin lineage, site-qualification boundary, or real-execution authority is relaxed.

v1.8.2 scoped destination-support place contact

A clean v1.8.1 UR5e target-stack run reached exact-Twin read-back and independently proved that transfer PTP planning succeeds while the attached-workpiece place LIN segment fails. v1.8.2 converts that evidence into a narrow placement contract rather than disabling collision checking.

The qualified report runtime now uses hard transfer/place boundaries:

approach_pick       PTP → LIN
lift_departure      LIN
transfer_departure  PTP
transfer_place      LIN   # place only
retreat_home        LIN → PTP

transfer_departure remains normally collision checked. Only the single zero-blend place LIN planning request may add one request-local Allowed Collision Matrix pair:

attached workpiece ↔ declared destination support

The place probe starts from the complete live MoveIt ACM, preserves every existing entry, enables only that symmetric pair, and applies the matrix only to the request-local PlanningScene diff. The transfer path cannot inherit the allowance. No global/live destination-contact lease remains active after planning.

The v1.8.2 place receipt records the exact destination support id, workpiece id, phase, and contact scope. Missing destination identity, a non-attached scene, a non-LIN place planner, nonzero place blending, malformed support identity, or mismatched receipt fails closed.

The release does not change real-execution authority, site qualification, target poses, conservative motion scales, or the rule that every motion group must preflight successfully before execution begins.

v1.8.3 synchronous verified workpiece attach

A clean v1.8.2 target-stack run proved all five industrial preflight groups and actual approach_pick execution, then failed closed at GRASP with workpiece_lifecycle_failed:apply_planning_scene_rejected.

The attach request previously combined an AttachedCollisionObject.ADD with a redundant same-ID world CollisionObject.REMOVE. MoveIt applies attached-object state first, which already transitions the same-ID object out of the world. Processing the later redundant world REMOVE can therefore make synchronous /apply_planning_scene report failure even though the attachment transition was already attempted.

v1.8.3 makes the attach transition service-safe and deterministic: the request contains only the authoritative attached-object ADD. DevAgent then synchronously reads the PlanningScene back and requires all of the following before motion may continue:

workpiece absent from world
exactly one attached object with the expected id
attached link == verified tool mount link
attached primitive geometry is valid
attachment pose/geometry hash matches the expected attachment hash

Detach semantics remain explicit attached-object REMOVE plus world-object ADD at the verified placement pose. No collision rule, tool/workpiece geometry, TCP, touch link, target pose, motion speed, planner, site-qualification boundary, or real-execution authority is relaxed.

v1.8.4 PyPI metadata compliance hotfix

v1.8.4 carries the exact v1.8.3 runtime semantics and shortens only the package Core Metadata Summary so it satisfies PyPI's 512-character limit. A regression test now parses pyproject.toml and rejects an empty or over-limit project description before release.

This metadata hotfix does not change the UR5e attach/detach lifecycle, collision policy, motion planning, Twin lineage, site-qualification boundary, or real-execution authority.

v1.8.5 quaternion-invariant verified workpiece attach

A clean v1.8.4 UR5e target-stack run proved that synchronous /apply_planning_scene attachment now succeeds, world/attached state reaches strict read-back, and the remaining GRASP blocker is workpiece_attachment_hash_mismatch.

MoveIt round-trips attached-object rotations through Eigen. Unit quaternions q and -q represent the same physical rotation, but a raw component hash treats those two equivalent representations as different. v1.8.5 canonicalizes equivalent quaternion signs before workpiece attachment hashing using the same deterministic positive-w / first-nonzero-component rule already used by the qualified tool-scene path.

Verification remains strict for attachment identity, link, geometry contract, position, and physical rotation. This is not a tolerance-based PASS and does not change target geometry, TCP, collision policy, planner types, motion speeds, controller binding, Twin lineage, site qualification, or real-execution authority. If a hash mismatch remains, DevAgent records expected and observed hashes plus canonical expected/object/primitive/effective attachment poses for target diagnosis.

v1.8.6 canonical semantic workpiece lifecycle

A clean v1.8.5 UR5e target-stack run again reached all five industrial preflight groups and executed approach_pick, while GRASP still failed with workpiece_attachment_hash_mismatch. That target evidence proved raw SHA equality of floating pose representations was too brittle to remain physical PASS authority.

v1.8.6 uses MoveIt's canonical existing-object lifecycle. Before GRASP, DevAgent reads back and semantically verifies the exact world workpiece. Attach then sends an ID-only AttachedCollisionObject.ADD; MoveIt transfers the already-verified world object's geometry and pose into the AttachedBody on the verified tool link. Release sends an ID-only attached-object REMOVE; MoveIt restores that same AttachedBody to the world at its current global pose.

The lifecycle remains fail-closed. Attach requires exact object identity, exact attached link, exact touch-link set, exact geometry kind, dimensions within 1e-9 m, position error no greater than 0.1 mm, and orientation error no greater than 1e-4 rad. Detach similarly verifies restored world identity, geometry, destination frame, position, and orientation. Representation hashes remain recorded for audit diagnostics but do not override the explicit physical-semantic checks.

Every lifecycle transition persists a deterministic receipt containing probe stdout/stderr plus expected/observed semantic diagnostics. Any failure includes the receipt path so the next target-stack blocker can be diagnosed directly instead of being collapsed to a generic lifecycle code.

This release does not disable collision checking, change the verified tool/workpiece geometry, modify motion targets, planner types or speeds, detach early, grant site qualification, or expand real-execution authority.

Qualified visual-execution scope

Measured report-test execution remains intentionally narrow:

robot:       UR5e
operation:   load
case scope:  one nominal mapped physical report case
runtime:     Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz

Unsupported customer Twins, unqualified robot profiles, boundary/fault cases outside the qualified scope, ambiguous case mappings, or incomplete lineage fail closed.

ABB IRB1200 is separately exposed as SIMULATION_AVAILABLE_EXPERIMENTAL: Gazebo/MoveIt/RViz preview is available, but it does not silently enter the UR5e measured FAT executor and cannot promote physical evidence.

Interactive engineering session

Use --interactive, or --open from a real terminal, to keep a bounded prompt:

status
tests
test SELECTOR
simulate [SELECTOR]
rerun [SELECTOR]
rerun failed
rerun blocked
rerun affected
replay
report
log
help
quit

Selectors can be requirement IDs, test IDs, or bounded groups:

REQ-PERF-001
TEST-PERF-001
failed
blocked
affected
all

test SELECTOR evaluates deterministic/evidence checks without commanding the simulator.

simulate TEST-X requests qualified execution of the selected mapped physical report case.

replay reconstructs persisted evidence identity; it never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.

Customer input

A customer folder can contain the engineering material the team already has:

ACME_CNC_CELL_TEST/
├── project.yaml
├── requirements.xlsx
├── devagent-twin.yaml
├── robot.urdf
├── robot.urdf.xacro
├── robot.srdf
├── tcp.yaml
├── calibration.yaml
├── layout/
│   ├── cell_layout.yaml
│   └── meshes/
├── robot_program/
│   └── mission.yaml
└── expected/
    └── expected_findings.json

Important rule:

file discovered != engineering fact proven

DevAgent fingerprints and classifies files, but filenames do not prove poses, TCPs, calibrations, collision geometry, safety behavior, or physical performance.

The root expected/ folder is test-oracle material and is never promoted as engineering authority.

If critical information is missing or ambiguous, DevAgent writes questions into the project results instead of guessing.

Results and evidence

Typical output:

customer-project/
└── devagent-results/
    ├── RUN.log
    ├── SUMMARY.json
    ├── INTAKE.json
    ├── QUESTIONS.md
    ├── normalized/
    │   ├── requirements.csv
    │   └── devagent-twin.yaml
    ├── report-test-visualization/
    ├── FAT_REPORT.html
    └── EVIDENCE.html

EVIDENCE.html is read-only engineering evidence. RUN.log is a human debug/progress trace and does not replace immutable evidence artifacts.

Repeat runs compare the immediately previous campaign with the current campaign before a new FAT artifact is finalized.

Physical simulation setup

pip install does not install ROS 2, Gazebo, MoveIt, OEM drivers, or privileged operating-system packages.

Reference stack:

Ubuntu 24.04
ROS 2 Jazzy
Gazebo Harmonic
gz_ros2_control
MoveIt 2

UR5e measured report-test execution additionally uses the Universal Robots ROS 2 driver, ur_simulation_gz, and Pilz Industrial Motion Planner.

Preview UR5e setup:

devagent-physical setup --profile ur5e-sim --dry-run

Apply explicitly:

devagent-physical setup --profile ur5e-sim --yes

Check the UR5e runtime:

devagent-physical ros doctor

Check ABB IRB1200 visual runtime prerequisites:

devagent robot doctor abb_irb1200

Launch ABB IRB1200 Gazebo + MoveIt + RViz preview:

devagent robot visualize abb_irb1200

Hosted CI validates deterministic software contracts. It does not pretend to execute a graphical ROS/Gazebo/MoveIt target stack. Target-stack acceptance must run on the intended workstation.

Optional AI providers

AI is optional and advisory.

python -m pip install "devagent-physical-engine[openai]"
python -m pip install "devagent-physical-engine[anthropic]"
python -m pip install "devagent-physical-engine[gemini]"
python -m pip install "devagent-physical-engine[ai]"

Typical credentials:

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."

Provider-backed interpretation cannot grant physical truth, site qualification, functional-safety certification, or real-execution authority.

Installed CLIs

devagent             one-command verification, interactive report testing, robot support/visualization
devagent-commercial  commercial/evidence workflow
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end

Simple Mode exit codes

Project status

v1.8.6 — Production/Stable software workflow

v1.8.6 retains v1.8.5 quaternion canonicalization, v1.8.4 PyPI metadata compliance, v1.8.3 synchronous service-safe attachment, v1.8.2 scoped destination-support place contact, and v1.8.1 direct UR5e controller/action binding. It upgrades the workpiece lifecycle to canonical MoveIt existing-object world↔attached transitions, strict physical-semantic pose/geometry verification, and persistent expected/observed lifecycle diagnostics instead of using floating representation SHA equality as PASS authority.

Production-oriented software capabilities include:

one-command customer intake
XLSX requirement normalization
validated Requirement → Criterion mapping
optional provider-backed advisory criterion proposals
requirement-driven nominal / boundary / fault case generation
immutable project/Twin lineage
exact Requirement → Mapping → Verification Plan → Case provenance
truthful robot support tiers
qualified UR5e report-test visual execution contract
direct UR5e controller-manager/action readiness binding
canonical MoveIt existing-object workpiece attach/detach
semantic workpiece pose/geometry verification with persistent diagnostics
scoped destination-support place contact
experimental exact ABB IRB1200 Gazebo/MoveIt/RViz preview
industrial Pilz PTP / LIN planning
adaptive bounded blend selection
plan-only transfer/place segment diagnostics
lift-only source-support contact lease + exact restore
Gazebo/MoveIt selected-case visualization
typed physical measurement binding
deterministic campaigns
repeat-run regression
professional FAT / Evidence Viewer
interactive selective verification
Evidence Bundle + replay
change impact + regression
provider-neutral optional AI front end

Production/Stable describes the bounded software workflow. It does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, or authorized for autonomous real execution.

Documentation

One-command verification: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ONE_COMMAND_VERIFY_V13.md

Report-test visual execution foundation: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/REPORT_TEST_VISUAL_EXECUTION_V16.md

Evidence Trust / replay / viewer: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/EVIDENCE_TRUST_V12.md

Measured physical runtime: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/MEASURED_PHYSICAL_RUNTIME.md

Commercial project spine: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_PROJECT_SPINE.md

Architecture: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md

Canonical Twin runtime: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/CANONICAL_TWIN_RUNTIME.md

Laptop acceptance: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/LAPTOP_ACCEPTANCE.md

Ownership

DevAgent Smart Physical Engine
Copyright © 2026 Tom Ha
Original creator: Tom Ha
Original project: https://github.com/tomha85/devagent-physical-engine
All rights reserved.

See repository LICENSE, NOTICE, and COPYRIGHT for complete ownership and usage terms.