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
    ↓
selective retest / replay

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

DevAgent is designed to answer: What can be proven about this cell, what failed, what remains unknown, what changed, and what evidence supports the conclusion?

Quick start

Python 3.11+ is required.

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

Verify the installed package:

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

Expected:

1.6.0

Run the normal customer workflow:

devagent verify ./customer-project

Request simulation:

devagent verify ./customer-project --simulate

Open the Evidence Viewer and retain an interactive engineering session:

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

For machine-readable CI output:

devagent verify ./customer-project --json

Default locations:

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

v1.6 report-test visual execution

v1.6 closes the gap between report test cases and the previously separate ROS/Gazebo reference visualization path.

A physical report test can now follow this bounded chain:

Requirement
    ↓
stable Test identity
    ↓
immutable Requirement → Case mapping
    ↓
exact Verification Plan ID/hash
    ↓
exact Case ID
    ↓
exact Twin revision/hash
    ↓
qualified report execution profile
    ↓
Gazebo + MoveIt visible execution
    ↓
typed physical_measurement artifact
    ↓
deterministic PASS / FAIL / NOT_TESTED
    ↓
refreshed Evidence Viewer

Interactive example:

devagent> tests
REQ-PERF-001         TEST-PERF-001        NOT_TESTED  case-0001

devagent> simulate TEST-PERF-001

For a supported qualified case, DevAgent materializes the exact immutable report Twin in the visual runtime. It does not run a separate demo Twin and relabel that result as customer evidence.

The execution runtime binds measured metrics such as:

cycle_time_s
minimum_clearance_m
final_tcp_error_m
max_tracking_error_rad
collision_free
completed
sample_count

The resulting physical_measurement remains scoped to the exact Twin revision/hash and case lineage that produced it.

Qualified scope

The initial packaged visual-execution qualification is intentionally narrow:

robot:       UR5e
operation:   load
profile:     packaged qualified report-execution profile
case scope:  one nominal mapped physical case
runtime:     ROS 2 Jazzy + Gazebo Harmonic + MoveIt 2

Unsupported customer Twins, boundary/fault cases, multiple mapped cases, incomplete mappings, ambiguous case IDs, mismatched verification plans, or unqualified execution profiles fail closed.

DevAgent never substitutes:

devagent-physical ros demo

for report evidence.

Exact lineage hardening

A case ID such as case-0001 is local to its verification plan. v1.6 therefore requires the complete lineage:

Requirement
 → mapping artifact
 → exact Verification Plan ID/hash
 → exact Case ID
 → exact Twin revision/hash
 → execution
 → measurement

If another plan reuses the same case ID, or the mapping references a different plan, report execution is blocked instead of guessing.

Full --simulate also fails closed if any physical requirement lacks an exact case mapping, or if the union of mapped physical cases is outside the currently qualified single-case scope.

Requirement intelligence and test generation

DevAgent maps supported requirement language into deterministic criteria only when the mapping can be validated. Supported measured physical checks include:

cycle_time_max_s
minimum_clearance_m
final_tcp_error_max_m
max_tracking_error_rad
collision_free
physical_completed

Supported structural/Twin checks include:

planning_allowed
physics_allowed
entity_present
validation_issue_absent
twin_state

Provider-backed OpenAI, Anthropic, or Gemini proposals are advisory. They cannot create physical truth, site qualification, or real-execution authority.

Requirement-driven case generation can derive bounded variations and fault cases from explicit engineering requirements, including payload ranges, TCP offset boundaries, missing-workpiece faults, and grasp-verification failures.

A requirement with no deterministic criterion or required measurement remains:

NOT_TESTED

It is never auto-passed from prose, CAD filenames, generated plans, or AI interpretation.

Interactive engineering session

With --open in a real TTY, or with explicit --interactive, DevAgent keeps a bounded engineering 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 re-evaluates existing immutable evidence and does not command a simulator.

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

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

Selective runs never silently promote full FAT readiness.

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
├── ur5e.urdf
├── robot.urdf.xacro
├── ur5e_robotiq.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 it does not treat a filename as proof of pose, TCP, calibration, 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 creates:

<customer-project>/devagent-results/QUESTIONS.md

Update the original customer engineering information and rerun the same command.

Results and evidence

A normal project can produce:

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. It exposes requirement verdicts, observed/expected values, blockers, artifact IDs/hashes, Twin revision hashes, selective runs, and measurement lineage.

RUN.log is the human progress/debug trace. It does not replace immutable engineering evidence.

Repeat runs on the same project automatically compare the immediately previous campaign with the current campaign before the new FAT artifact is generated.

Authority model

DevAgent separates:

requirement
verification intent
physical execution case
measured evidence
verdict
authority/readiness

A plan proves that a test was planned. A mapping proves which case is bound to a requirement. A measurement proves only what was actually measured. A replay proves persisted identity can be reconstructed.

None of those alone equals site commissioning or functional-safety certification.

Current hard boundaries remain:

physical_qualification = false unless separately proven
site_qualification = false
real_execution_allowed = false

The operating principle remains:

Agents propose.
Deterministic engines compile and verify.
Qualified simulators measure bounded scopes.
Existing certified controllers execute real equipment.

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
Universal Robots ROS 2 driver
ur_simulation_gz
MoveIt 2

Preview setup:

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

Apply explicitly:

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

Check runtime:

devagent-physical ros doctor

Hosted Python CI validates software contracts and deterministic execution boundaries. It does not by itself prove a graphical Gazebo runtime, move_group, TF, controller actions, OEM drivers, or an arbitrary customer cell. Physical target-stack qualification must run on the intended workstation/adapter stack.

Optional AI providers

AI is optional and remains outside deterministic authority.

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

Or install all provider adapters:

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 can propose intent or criterion mappings. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.

Installed CLIs

devagent             one-command customer verification + interactive report testing
devagent-commercial  expert 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.6.0 — Production/Stable software workflow

v1.6.0 adds exact-Twin report-test visual execution, immutable Requirement→Mapping→Verification Plan→Case lineage validation, qualified Gazebo/MoveIt execution for the packaged UR5e nominal report profile, typed simulation measurement binding, interactive report-case visualization, and fail-closed handling for unsupported or ambiguous execution scopes.

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 → Case provenance
qualified report-test visual execution contract
Gazebo/MoveIt selected-case visualization
typed physical measurement binding
deterministic full campaigns
repeat-run regression orchestration
professional FAT/Evidence Viewer
terminal progress + RUN.log
interactive engineering session
Requirement → Test selectors
selective deterministic retest
failed / blocked / affected selectors
Evidence Bundle + replay
change impact + regression
provider-neutral optional AI front end

Quality gates include Python 3.11/3.12/3.13 regression, compilation, Ruff correctness checks, package build/clean-install, runtime dependency audit, global branch coverage, One-Command coverage, Commercial Intelligence coverage, report-test visual execution qualification tests, Selective Verification coverage, Production Authority coverage, and Evidence Trust/Replay coverage.

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

v1.6 report-test visual execution:

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

Commercial workflow:

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