DevAgent Smart Physical Engine

Verification-first commissioning engineering for robotics and industrial automation.

DevAgent turns customer engineering inputs into a bounded, evidence-driven pre-site commissioning workflow. AI may help interpret and propose; deterministic engines validate, compile, execute qualified verification, measure evidence, detect regression, and gate promotion.

OEM robot controllers, PLCs, safety PLCs, certified safety systems, and qualified site processes remain authoritative. DevAgent does not convert simulation into site qualification or functional-safety certification.

Engine in action

Exact-Twin simulation in Gazebo Harmonic
_{Real DevAgent engine run with the bounded UR5e workcell, customer-cell entities, physics, and simulation state visible.}

Robot task execution Gazebo view during the bounded pick–transport–place workflow.

MoveIt motion planning RViz planning-scene view used alongside the qualified ROS 2 / MoveIt execution path.

_{Real engine screenshots — not product renders. ROS 2 Jazzy · Gazebo Harmonic · MoveIt 2 · Pilz · UR5e exact-Twin verification.}

v2.0 commissioning verification flow

Customer engineering files
        ↓
Immutable project + Twin revision
        ↓
Engineering review
        ↓
Requirements + findings + risks + changes
        ↓
Deterministic criterion mapping
        ↓
Requirement-driven verification plan
        ↓
Verification-scope authority
        ↓
Deterministic checks + qualified physical evidence
        ↓
Evidence Graph
        ↓
PASS / FAIL / NOT_TESTED
        ↓
Change Impact + Regression
        ↓
FAT Report + Evidence Bundle
        ↓
Immutable pre-site commissioning decision

The final bounded decision is one of:

READY_FOR_PRE_SITE_COMMISSIONING
NOT_READY_FOR_PRE_SITE_COMMISSIONING

That decision means the declared pre-site engineering scope has complete, current evidence according to DevAgent's installed authority contracts. It does not mean the real site is commissioned.

Quick start

Python 3.11+ is required.

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

Verify the installed package:

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

Expected:

2.0.0

Run the normal customer workflow:

devagent verify ./customer-project

Request qualified simulation where available:

devagent verify ./customer-project --simulate

Open the Evidence Viewer and keep the engineering terminal active:

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

Machine-readable CI output:

devagent verify ./customer-project --json

Default locations:

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

Commercial commissioning workflow

The normal end-to-end customer path is devagent verify. It performs requirement normalization, deterministic mapping, requirement-driven case planning/mapping, verification orchestration, evidence recording, regression, and reporting within the qualified scope.

devagent-commercial is the lower-level immutable project/evidence/control-plane interface. It is useful for explicit artifact operations, CI, audit, and commissioning-readiness inspection.

Example low-level operations:

devagent-commercial --db ~/.devagent/projects.db init CELL-01 \
  --name "Customer Cell" \
  --site SITE-01 \
  --workcell CNC-LOAD

devagent-commercial --db ~/.devagent/projects.db import-twin CELL-01 ./customer-project

devagent-commercial --db ~/.devagent/projects.db requirements CELL-01 requirements.yaml

devagent-commercial --db ~/.devagent/projects.db engineering-review CELL-01 <requirement-set-artifact-id>

devagent-commercial --db ~/.devagent/projects.db verification-plan CELL-01 verification.yaml

devagent-commercial --db ~/.devagent/projects.db campaign CELL-01 requirements.yaml \
  --measurement <physical-measurement-artifact-id>

devagent-commercial --db ~/.devagent/projects.db fat-report CELL-01 <campaign-artifact-id>

devagent-commercial --db ~/.devagent/projects.db evidence-bundle CELL-01 <campaign-artifact-id>

devagent-commercial --db ~/.devagent/projects.db commissioning-readiness CELL-01

devagent-commercial --db ~/.devagent/projects.db commissioning-status CELL-01

verification-plan records an explicit deterministic plan from the supplied spec. It does not invent a requirement→case mapping. Final commissioning readiness requires exact current requirement-to-case lineage; the one-command workflow records that mapping, and low-level/custom integrations must record equivalent immutable lineage instead of bypassing the gate.

Use finding-disposition to record an immutable engineering disposition. A blocking finding cannot be resolved without current-Twin evidence.

What DevAgent proves

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

Requirement / report test
        ↓
Declarative verification capability
        ↓
Exact Twin revision/hash
        ↓
Exact verification plan + case mapping
        ↓
Qualified evidence reuse or qualified execution
        ↓
Measured evidence
        ↓
Deterministic verdict
        ↓
PASS / FAIL / NOT_TESTED

A generated plan is not physical proof. A replay is not a new execution. An AI response is not engineering evidence. A simulation result does not grant site qualification.

Engineering findings and risk authority

v2.0 records first-class immutable artifacts for:

engineering_finding
engineering_review
engineering_finding_disposition

High and critical findings are structurally blocking. AI or a human reviewer may propose findings, but findings do not create PASS authority.

A blocking finding may be marked resolved only when the disposition references evidence bound to the current Twin scope. Acknowledged, deferred, or accepted-risk records remain explicit and do not silently promote readiness.

Verification-scope authority

A verification plan is not trusted merely because it belongs to the same Twin.

VerificationScopeAuthority deterministically reconstructs the expected test space from the exact current campaign requirements and compares the stored plan and requirement-to-case mapping with that expected scope.

If a requirement change alters payload, boundary, or fault coverage but an old plan/map is reused, readiness fails closed.

Physical evidence authority

Internal simulation / hardware-shadow evidence

A standalone measurement JSON cannot grant final readiness merely by claiming gazebo_moveit, a run ID, and a qualification reference.

Internal evidence must preserve an exact immutable chain:

physical_measurement
        ↓
runtime_measurement_binding
        ↓
physical_motion_plan
        ↓
exact Twin + run + qualification lineage

External simulator evidence

External evidence is imported as candidate evidence and is independently gated by installed provider policy.

Built-in provider identities include:

ABB RobotStudio
FANUC ROBOGUIDE
KUKA.Sim
Visual Components
RoboDK
Siemens Process Simulate

These identities do not imply qualification. A provider remains candidate-only unless a code-reviewed policy explicitly qualifies its version/export schema and binds exact source provenance, candidate evidence, Twin hash, metrics, and qualification reference.

Whole-project staleness

Each pre-site decision records a deterministic readiness-state snapshot hash.

A previous READY result becomes stale when readiness-relevant state changes, including:

Twin revision
requirement set
engineering review
finding / disposition
verification plan
requirement-case mapping
physical measurement / runtime binding
campaign
change impact
regression
FAT report
evidence bundle

This also catches same-Twin changes. commissioning-status verifies both the decision hash and the current project-state snapshot before reporting READY.

Evidence Graph and replay

The read-only Evidence Graph links requirements, Twin revisions, campaigns, findings, dispositions, measurements, motion plans, regressions, FAT reports, evidence bundles, and final readiness decisions.

devagent-commercial --db ~/.devagent/projects.db evidence-graph CELL-01

Write a self-contained viewer:

devagent-commercial --db ~/.devagent/projects.db evidence-viewer CELL-01 \
  --output ./EVIDENCE.html

Replay reconstructs persisted evidence identity. It never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.

Interactive engineering session

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

status
tests
test SELECTOR
simulate SELECTOR
simulate all
simulate --fresh SELECTOR
simulate --fresh all
rerun SELECTOR
rerun failed
rerun blocked
rerun affected
rerun all
replay
report
log
help
quit

test SELECTOR evaluates existing evidence without commanding the simulator.

simulate TEST-X reuses exact qualified evidence when available and executes only when the mapped physical case is missing.

simulate --fresh TEST-X and physical rerun ... explicitly request new execution and append new immutable evidence.

Report-wide fresh execution still deduplicates shared physical case IDs.

Qualified visual-execution scope

Measured report-test execution remains intentionally narrow:

robot:       UR5e
operation:   load
case scope:  qualified mapped physical report cases within the packaged authority
runtime:     Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz

The target-proven UR5e path retains controller-manager/action readiness binding, canonical Twin/PlanningScene verification, conservative Pilz PTP/LIN motion, workpiece attach/carry/release semantics, controller-feedback tracking evidence, and post-release settle verification.

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

ABB IRB1200 remains a separate experimental visual simulation path. FANUC/KUKA and other robot/vendor paths retain their truthful support tiers until separately qualified.

Inspect robot support:

devagent robots
devagent robot doctor abb_irb1200
devagent robot visualize abb_irb1200

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.

If critical information is missing or ambiguous, DevAgent asks for information instead of inventing engineering facts.

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 progress/debug trace and does not replace immutable evidence artifacts.

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 runtime prerequisites:

devagent-physical ros doctor
devagent robot doctor 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  project, evidence, findings, FAT, regression, commissioning-readiness workflow
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end

Simple Mode exit codes

Project status

v2.0.0 — Production/Stable software workflow; commissioning verification control plane with fail-closed pre-site readiness

v2.0.0 adds immutable engineering findings/dispositions, deterministic verification-scope authority, stronger internal/external evidence authority, commissioning-aware Evidence Graph lineage, whole-project staleness detection, and an immutable pre-site commissioning readiness decision.

Production-oriented software capabilities include:

one-command customer intake
XLSX/CSV/YAML/JSON requirement normalization
immutable project/Twin lineage
engineering review + first-class risk findings
evidence-backed finding dispositions
validated Requirement → Criterion mapping
optional provider-backed advisory criterion proposals
requirement-driven nominal / boundary / fault case generation
verification-scope authority against current requirements
exact Requirement → Mapping → Verification Plan → Case provenance
case-centric qualified evidence reuse
explicit fresh physical execution
verification-owned simulator lifecycle cleanup
mixed deterministic + physical report orchestration
truthful PASS / FAIL / NOT_TESTED
runtime-bound internal physical evidence authority
policy-bound external simulator evidence authority
commissioning-aware Evidence Graph
whole-project readiness staleness detection
change impact + regression
professional FAT report
Evidence Bundle + replay
immutable READY / NOT_READY pre-site commissioning decision
provider-neutral optional AI front end

Production/Stable describes the bounded software workflow. The target-proven UR5e claim remains limited to the qualified packaged scope and acceptance environment. v2.0.0 does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, commissioned, or authorized for autonomous real execution.

Current hard authority boundaries remain:

site_qualification = false
functional_safety_certification = false
commissioning_completed = false
real_execution_allowed = false

unless separately proven by an appropriate qualified process.

Documentation

v2.0.0 release notes: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V2_0_0.md

v1.9.1 release notes: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V1_9_1.md

v1.9.0 release notes: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V1_9_0.md

One-command verification: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ONE_COMMAND_VERIFY_V13.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.