DevAgent Smart Physical Engine

Verification-first commissioning engineering for robotics and industrial automation.

DevAgent turns an ordinary customer engineering folder into a bounded verification workflow with immutable Twin lineage, deterministic requirement verdicts, measured evidence, replay inspection, FAT reporting, and selective retesting.

customer files
    ↓
intake + SHA-256 inventory
    ↓
requirements + explicit engineering facts
    ↓
immutable Digital Twin revision
    ↓
deterministic verification plan
    ↓
measured evidence when a qualified execution path exists
    ↓
PASS / FAIL / NOT_TESTED
    ↓
FAT report + Evidence Viewer
    ↓
selective retest / replay / regression

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.4.0

Verify the package:

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

Expected:

1.4.0

Run the normal customer workflow:

devagent verify ./customer-project

Request simulation when the exact imported-Twin execution path is qualified:

devagent verify ./customer-project --simulate

Open the Evidence Viewer and keep a human engineering terminal session:

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

For machine-readable CI output:

devagent verify ./customer-project --json

Simple Mode automatically handles project identity, customer-file inventory, supported XLSX requirement normalization, bounded Twin normalization, deterministic campaign generation, FAT generation, and evidence rendering. The user does not need to manually manage artifact IDs for the normal workflow.

Default locations:

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

Customer input

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

ACME_CNC_CELL_TEST/
├── project.yaml
├── requirements.xlsx
├── ur5e.urdf
├── robot.urdf.xacro
├── ur5e_robotiq.srdf
├── tcp.yaml
├── calibration.yaml
├── layout/
│   ├── cell_layout.yaml
│   └── meshes/
├── robot_program/
│   └── mission.yaml
├── safety_requirements.pdf
└── 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. PDF documents can be inventoried for review, but arbitrary PDF prose is not silently converted into deterministic PASS evidence.

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.

What the terminal shows

Human Simple Mode keeps the terminal as the primary progress surface:

[DevAgent +   0.00s] START         RUNNING    source=ACME_CNC_CELL_TEST
[DevAgent +   0.00s] INTAKE        RUNNING    scanning and classifying customer engineering files
[DevAgent +   0.42s] REQUIREMENTS  READY      customer requirements normalized
[DevAgent +   0.61s] TWIN          NORMALIZED customer Twin draft normalized
[DevAgent +   0.85s] PROJECT       READY      project_id=acme-cell
[DevAgent +   0.91s] PLAN          READY      artifact=...
[DevAgent +   1.02s] SIMULATION    BLOCKED    imported_customer_twin_execution_adapter_not_yet_qualified
[DevAgent +   1.11s] CAMPAIGN      COMPLETE   artifact=...
[DevAgent +   1.18s] FAT           COMPLETE   artifact=...
[DevAgent +   1.24s] EVIDENCE      COMPLETE   bundle=...
[DevAgent +   1.25s] COMPLETE      DONE       state=verification_incomplete release_ready=False real_execution_allowed=False
[DevAgent +   1.25s] REPORT        OPENING    new tab requested; terminal remains active

Progress is also persisted to:

<customer-project>/devagent-results/RUN.log

If the browser chooses to take focus, the DevAgent process still remains alive in the terminal. Return to the terminal and continue with the interactive session.

Use --no-progress to suppress human progress. --json remains machine-clean and never enters the interactive prompt.

Interactive engineering session

With --open in a real TTY, or with explicit --interactive, DevAgent keeps a bounded engineering prompt after the full verification run:

Interactive engineering session
Type 'help' for commands.

devagent>

Useful commands:

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

Examples:

devagent> tests
devagent> test REQ-CAL-001
devagent> test TEST-CAL-001
devagent> simulate REQ-FUN-001
devagent> rerun failed
devagent> rerun blocked
devagent> rerun affected

Use --no-interactive when --open should open the report but the CLI should exit afterward.

v1.4 selective verification

Selective verification reduces unnecessary FAT/retest work without changing the authority model.

Stable Requirement → Test identity

DevAgent derives a stable deterministic test identity from a requirement identity:

REQ-FUN-001 → TEST-FUN-001
REQ-CAL-001 → TEST-CAL-001

The mapping identifies the verification criterion. It does not by itself authorize a physical simulation case.

test SELECTOR

Example:

devagent> test REQ-CAL-001

or:

devagent> test TEST-CAL-001

test re-evaluates only the selected requirement/test scope using the exact Twin and currently available immutable evidence. It does not launch a robot or simulator.

The result is recorded separately as:

selective_verification_run

A selective artifact includes:

requested selector
selector kind
parent campaign ID/hash
Twin revision/hash
resolved requirement IDs
resolved test IDs
verification contracts
dependencies
measurement/evidence references
verdicts

Every selective run explicitly preserves:

full_campaign_executed = false
release_ready = false
real_execution_allowed = false

A selective PASS is therefore not silently promoted into a full FAT PASS.

simulate SELECTOR

Example:

devagent> simulate REQ-CAL-001

Selective physical execution is stricter than deterministic test.

The required chain is:

Requirement
    ↓
stable Test contract
    ↓
explicit verification-test mapping
    ↓
exact physical case ID(s)
    ↓
qualified selective execution adapter
    ↓
measured simulation artifact
    ↓
selective verdict

DevAgent never guesses a physical case from requirement prose. Requirement/Test → physical case mapping must be explicit engineering provenance.

If no mapping exists:

state  = blocked
reason = requirement_has_no_qualified_physical_test_mapping
execution_performed = false

If the mapping exists but the selective executor is not qualified:

state  = blocked
reason = selective_execution_adapter_not_qualified
execution_performed = false

Current v1.4 qualification intentionally supports one explicitly mapped physical case per selective execution. Multiple mapped cases remain fail-closed until aggregation semantics are separately qualified:

selective_multi_case_aggregation_not_yet_qualified

Explicit physical test mapping

Expert integrations can use the public API:

from devagent_physical_engine import VerificationTestMappingRecorder

mapping = VerificationTestMappingRecorder(repository).record(
    project_id="acme-cell",
    revision_id="twin-r0001",
    verification_plan_artifact_id="art-plan",
    bindings={
        "REQ-CAL-001": ["case-0001"],
    },
    source_ref="engineering-map.yaml",
)

The recorder validates that the requirement is a physical requirement, the plan belongs to the exact Twin revision, and every case ID exists in that immutable verification plan.

The mapping itself has:

execution_authority = false
physical_qualification = false
site_qualification = false
real_execution_allowed = false

Selectors

Supported selectors are:

REQ-...       one requirement
TEST-...      one deterministic test identity
failed        requirements that failed the parent campaign
blocked       NOT_TESTED requirements plus currently blocked selective scope
affected      requirements selected by latest exact-Twin change-impact evidence
all           all requirements in the parent campaign

For example:

devagent> rerun failed

re-evaluates only the requirements that failed instead of rerunning the entire campaign.

devagent> rerun affected

uses change-impact evidence to retest only affected requirements.

A selector is resolved deterministically. Unknown selectors fail closed.

Full simulation vs selective simulation vs replay

These operations are intentionally different:

Replay never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.

Selective verification never upgrades real-execution authority.

Results directory

A normal project can produce:

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

EVIDENCE.html is a read-only professional evidence viewer. It shows requirement verdicts, observed/expected values, blockers, artifact IDs/hashes, and Twin revision hashes. The viewer can be refreshed after selective runs so the new immutable selective artifacts are inspectable.

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

Requirement verdict model

Supported deterministic structural/Twin checks include:

planning_allowed
physics_allowed
entity_present
validation_issue_absent
twin_state

Measured physical checks include:

cycle_time_max_s
minimum_clearance_m
final_tcp_error_max_m
max_tracking_error_rad
collision_free
physical_completed

Verdicts remain bounded:

PASS
FAIL
NOT_TESTED

A requirement requiring measured physical evidence cannot PASS from prose, a CAD filename, a generated plan, or AI interpretation.

Example:

Requirement: cycle time <= 8.0 s
Measurement available: no
Verdict: NOT_TESTED

With exact-Twin measured evidence:

Requirement: cycle time <= 8.0 s
Observed: 7.42 s
Threshold: 8.0 s
Verdict: PASS
Evidence: exact measurement artifact + Twin revision/hash

Simple Mode exit codes

Selective results are represented by immutable artifacts inside the interactive session; they do not rewrite the full-run exit contract.

Expert Mode

Installed CLIs:

devagent             one-command customer verification + interactive selective retesting
devagent-commercial  expert commercial/evidence workflow
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end

Typical Expert Mode flow:

project identity
    ↓
customer Twin import
    ↓
requirements
    ↓
verification plan
    ↓
measured evidence
    ↓
commercial campaign
    ↓
FAT report
    ↓
Evidence Bundle
    ↓
replay / change impact / regression

Example commands:

devagent-commercial init warehouse-cnc-04 \
  --name "Warehouse CNC Loading Cell 04" \
  --site atl-01 \
  --workcell cnc-04

devagent-commercial import-twin warehouse-cnc-04 ./customer-cell

devagent-commercial requirements warehouse-cnc-04 \
  examples/commercial/requirements-production.csv

devagent-commercial verification-plan warehouse-cnc-04 \
  examples/commercial/verification-plan.yaml \
  --revision twin-r0001

devagent-commercial record-measurement warehouse-cnc-04 \
  physical-measurement.json \
  --revision twin-r0001

devagent-commercial campaign warehouse-cnc-04 \
  examples/commercial/requirements-production.csv \
  --revision twin-r0001 \
  --measurement ARTIFACT_ID

devagent-commercial fat-report warehouse-cnc-04 \
  CAMPAIGN_ARTIFACT \
  --output FAT_REPORT.html

devagent-commercial evidence-bundle warehouse-cnc-04 CAMPAIGN_ARTIFACT

devagent-commercial evidence-graph warehouse-cnc-04 > evidence-graph.json

devagent-commercial evidence-viewer warehouse-cnc-04 \
  --output DEVAGENT_EVIDENCE.html

devagent-commercial replay warehouse-cnc-04 EVIDENCE_BUNDLE \
  --qualification-root ~/.devagent/physical-qualification \
  --output replay-manifest.json

Replay reconstruction reports execution_performed=false and never substitutes for a new simulation run.

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

Qualify trajectory runtime:

devagent-physical ros qualify-trajectory-runtime

Hosted Python CI does not prove a graphical Gazebo runtime, move_group, TF, controller actions, OEM drivers, or an arbitrary customer cell. Physical qualification must run on the exact 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:

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

Typical credentials:

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

Provider-backed engineering interpretation can propose intent and mappings. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.

Evidence and 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 an engineer bound to a physical 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 boundary remains:

site_qualification = false
real_execution_allowed = false

Physical qualification is true only when separately qualified evidence explicitly establishes it.

The operating principle remains:

Agents propose.
Deterministic engines compile and verify.
Existing certified controllers execute.

Project status

v1.4.0 — Production/Stable software workflow

v1.4.0 adds selective verification execution while preserving the existing fail-closed authority model.

Production-oriented software capabilities include:

one-command customer intake
XLSX requirement normalization
immutable project/Twin lineage
deterministic full campaigns
measured evidence binding
professional FAT/Evidence Viewer
terminal progress + RUN.log
interactive engineering session
Requirement → Test selectors
selective deterministic retest
selective physical execution contract
explicit Requirement/Test → Case mapping
failed / blocked / affected retest selectors
Evidence Bundle + replay
change impact + regression
provider-neutral optional AI front end

Quality gates include Python 3.11/3.12/3.13 regression, package clean-install, dependency audit, global branch coverage, One-Command coverage, 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, or safe for autonomous real execution.

Documentation

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

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.