Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.9.0
Summary: Verification-first robotics commissioning runtime with declarative customer report tests, case-centric evidence reuse, qualified UR5e Gazebo/MoveIt execution, exact-Twin lineage, selective verification, regression, replay, and FAT reporting.
Author: Tom Ha
License: All Rights Reserved
Project-URL: Homepage, https://github.com/tomha85/devagent-physical-engine
Project-URL: Repository, https://github.com/tomha85/devagent-physical-engine
Project-URL: Issues, https://github.com/tomha85/devagent-physical-engine/issues
Project-URL: Sponsor, https://github.com/sponsors/tomha85
Keywords: robotics,industrial-automation,agentic-ai,ros2,gazebo,moveit,pilz,verification,selective-testing,digital-twin,fat-testing,regression,evidence,replay
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: NOTICE
Requires-Dist: PyYAML<7,>=6.0
Provides-Extra: openai
Requires-Dist: openai<4,>=3.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=1.0; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai<3,>=2.0; extra == "gemini"
Provides-Extra: ai
Requires-Dist: openai<4,>=3.0; extra == "ai"
Requires-Dist: anthropic<2,>=1.0; extra == "ai"
Requires-Dist: google-genai<3,>=2.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: build==1.6.0; extra == "dev"
Requires-Dist: twine==7.0.0; extra == "dev"
Requires-Dist: coverage[toml]<8,>=7.6; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Requires-Dist: pip-audit<3,>=2.9; extra == "dev"
Dynamic: license-file

# DevAgent Smart Physical Engine

[![PyPI](https://img.shields.io/pypi/v/devagent-physical-engine.svg)](https://pypi.org/project/devagent-physical-engine/)
[![Python](https://img.shields.io/pypi/pyversions/devagent-physical-engine.svg)](https://pypi.org/project/devagent-physical-engine/)
[![Status: Production/Stable](https://img.shields.io/badge/status-production%2Fstable-blue.svg)](#project-status)
[![Sponsor DevAgent Physical Engine](https://img.shields.io/badge/Sponsor-DevAgent%20Physical%20Engine-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/tomha85)

**Verification-first commissioning engineering for robotics and industrial automation.**

> ❤️ **DevAgent Smart Physical Engine is independently developed.** If it saves your team engineering time, consider [sponsoring continued development](https://github.com/sponsors/tomha85).

## Engine in action

<p align="center">
  <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-21.png" width="100%" alt="DevAgent Smart Physical Engine exact-Twin UR5e workcell running in Gazebo Harmonic">
</p>

<p align="center">
  <b>Exact-Twin simulation in Gazebo Harmonic</b><br>
  <sub>Real DevAgent engine run with the bounded UR5e workcell, customer-cell entities, physics, and simulation state visible.</sub>
</p>

<table>
  <tr>
    <td width="50%" align="center">
      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-15-17.png" width="100%" alt="DevAgent Smart Physical Engine robot task execution in Gazebo">
      <br><b>Robot task execution</b><br>
      <sub>Gazebo view during the bounded pick–transport–place workflow.</sub>
    </td>
    <td width="50%" align="center">
      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-32.png" width="100%" alt="DevAgent Smart Physical Engine MoveIt motion planning scene in RViz">
      <br><b>MoveIt motion planning</b><br>
      <sub>RViz planning-scene view used alongside the qualified ROS 2 / MoveIt execution path.</sub>
    </td>
  </tr>
</table>

<p align="center"><sub><b>Real engine screenshots — not product renders.</b> ROS 2 Jazzy · Gazebo Harmonic · MoveIt 2 · Pilz · UR5e exact-Twin verification.</sub></p>

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

```text
customer engineering files
    ↓
intake + SHA-256 inventory
    ↓
customer report test IDs + declarative verification contracts
    ↓
immutable Digital Twin revision
    ↓
requirement-driven nominal / boundary / fault cases
    ↓
reuse exact qualified case evidence when available
    ↓
execute each missing qualified physical case once
    ↓
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.

```bash
python -m pip install --upgrade devagent-physical-engine==1.9.0
```

Verify the installed package:

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

Expected:

```text
1.9.0
```

Run the normal customer workflow:

```bash
devagent verify ./customer-project
```

Request simulation:

```bash
devagent verify ./customer-project --simulate
```

Open the Evidence Viewer and keep the engineering terminal active:

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

For machine-readable CI output:

```bash
devagent verify ./customer-project --json
```

Inspect truthful robot support tiers:

```bash
devagent robots
```

For the exact ABB IRB1200 experimental visual runtime:

```bash
devagent robot doctor abb_irb1200
devagent robot visualize abb_irb1200
```

Default locations:

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

## What DevAgent proves

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

```text
report test / requirement
  ↓
declarative verification capability
  ↓
verification case when physical execution is required
  ↓
exact Twin revision/hash
  ↓
qualified evidence reuse or 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:

```text
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:

```text
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:

```text
devagent> tests
devagent> simulate TEST-PERF-001
```

Measured physical criteria include:

```text
cycle_time_max_s
minimum_clearance_m
final_tcp_error_max_m
max_tracking_error_rad
collision_free
physical_completed
```

Structural/Twin criteria include:

```text
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:

```text
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:

```text
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:

```text
approach_pick    PTP → LIN
lift_departure   LIN
transfer_place   PTP → LIN
retreat_home     LIN → PTP
```

Conservative limits:

```text
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:

```text
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:

```text
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:

```text
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:

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

The result is classified deterministically as one of:

```text
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:

```bash
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:

```text
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:

```text
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:

```text
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.

## v1.8.8 canonical world integrity gate before GRASP

v1.8.8 packages the latest workpiece-lifecycle diagnostics as an unambiguous release version so target acceptance no longer runs newer code while reporting `1.8.6`.

Before ATTACH, DevAgent now reasserts the exact canonical Twin workpiece into the live MoveIt world, synchronously reads the object back, normalizes ROS `uint8/octet` primitive representations safely, and requires exact identity/frame/geometry plus bounded pose agreement before attachment is attempted. Primitive type `0` remains invalid; DevAgent does not infer BOX/CYLINDER from dimensions or weaken collision checking.

The lifecycle receipt records the pre/post primitive type representation, canonical-world reassert result, semantic verification, and the exact inner failure code. Existing target poses, conservative Pilz motion limits, tool/workpiece geometry, site-qualification boundaries, and `real_execution_allowed = false` remain unchanged.

Hosted CI qualifies the software/build/install contract. The ROS/Gazebo/MoveIt workstation still requires a fresh target acceptance run of the released 1.8.8 artifact before this specific workpiece path can be called physically qualified.

## v1.8.9 target-proven complete Pick–Transport–Place lifecycle

v1.8.9 completes and target-proves the qualified UR5e nominal `pick_transport_place` report path on the intended ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz workstation. The acceptance run completed `approach_pick → grasp → lift_departure → transfer_departure → transfer_place → release → retreat_home → verify` and returned `SELECTIVE PASSED` for `TEST-PERF-001`.

The release fixes the lifecycle by separating engineering authorities instead of weakening checks:

```text
OEM / ros2_control controller
  → owns its configured FollowJointTrajectory execution tolerance

DevAgent
  → independently records desired-vs-actual controller feedback
  → preserves the 0.03 rad commissioning tracking gate
  → verifies exact Twin/MoveIt scene semantics
  → verifies carried workpiece pose before release
  → verifies Gazebo post-release resting pose within 5 mm / 1°
  → synchronizes MoveIt to the actual Gazebo-released pose before retreat
```

The qualified place verifier now evaluates the same exact workpiece↔destination-support contact contract used by the planner instead of checking the place path against inconsistent global ACM semantics. Controller feedback cadence is diagnostic evidence rather than an invented minimum-rate execution contract.

Release is a measured two-authority handoff: while the carrier owns the object, the tool/grasp-derived carried pose is authoritative; after the carrier stops, Gazebo physics owns the released object and the Twin resting pose is the verification target. DevAgent records every settle sample in `release-settle-trace.json` and does not teleport the object into tolerance.

MoveIt DETACH is deterministic. DevAgent removes attachment ownership while the robot is stationary, explicitly ADD/overwrites the world collision object with exact verified geometry at the actual Gazebo-settled pose, then requires full scene readback and semantic verification before retreat is permitted. A stale implicit MoveIt detach pose remains a hard failure.

This qualification is intentionally bounded to the packaged UR5e nominal report-test scope. It does not grant arbitrary customer-cell qualification, site qualification, functional-safety certification, or autonomous real-robot execution authority.

## v1.9.0 dynamic customer report verification

v1.9.0 changes report orchestration from test-name-driven behavior to declarative verification capabilities while preserving the target-proven v1.8.9 physical runtime.

Customer test IDs are opaque. A report row can declare its verification behavior with fields such as:

```text
test_id
verification_mode
metric
comparator
target / expected
evidence_authority
```

For example, `FAT-CUSTOM-947` can request the physical metric `max_workpiece_tilt_deg <= 3.0` without adding a `TEST-FAT-CUSTOM-947` code branch.

Interactive execution is case-centric:

```text
devagent> simulate FAT-CUSTOM-947
  → resolve the exact report contract
  → resolve Requirement → Mapping → Plan → Case lineage
  → reuse exact qualified case evidence first
  → execute the mapped physical case only when evidence is missing
  → evaluate the requested metric generically

devagent> simulate all
  → evaluate deterministic report rows without simulation
  → deduplicate physical case identities
  → reuse existing qualified measurements
  → execute each missing unique qualified physical case once
  → share each measurement across compatible report rows
```

A requested metric that the qualified adapter does not measure remains `NOT_TESTED`. DevAgent does not fabricate the value and does not repeatedly rerun the robot merely because the metric is unavailable.

The typed physical evidence path now permits bounded finite numeric/boolean customer metrics while retaining stricter semantic consistency validation for known safety metrics. This expands the report schema, not simulator authority: a qualified adapter must actually produce the requested measurement.

Hosted regression includes an arbitrary customer report test using `FAT-CUSTOM-947` and `max_workpiece_tilt_deg`, proving preservation through intake, campaign creation, case mapping, selective simulation, verdict evaluation, and later `simulate all` evidence reuse.

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

## Qualified visual-execution scope

Measured report-test execution remains intentionally narrow:

```text
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
```

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:

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

Selectors can be customer-defined requirement IDs, customer-defined test IDs, or bounded groups:

```text
CUSTOM-REQ-77
FAT-CUSTOM-947
failed
blocked
affected
all
```

`test SELECTOR` evaluates the selected criterion from existing qualified evidence without commanding the simulator.

`simulate TEST-X` executes or reuses only the physical case required by that report row.

`simulate all` creates a report-wide capability execution plan, evaluates deterministic rows directly, deduplicates physical cases, reuses exact qualified evidence first, and executes only missing unique qualified cases.

`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:

```text
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:

```text
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:

```text
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:

```text
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:

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

Apply explicitly:

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

Check the UR5e runtime:

```bash
devagent-physical ros doctor
```

Check ABB IRB1200 visual runtime prerequisites:

```bash
devagent robot doctor abb_irb1200
```

Launch ABB IRB1200 Gazebo + MoveIt + RViz preview:

```bash
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.

```bash
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:

```bash
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

```text
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

| Exit | Meaning |
| ---: | --- |
| `0` | bounded full verification is release-ready |
| `10` | customer input or operational contract failure |
| `30` | more engineering information is required |
| `31` | requested simulation is blocked/unqualified |
| `32` | verification completed but full release readiness is false |

# Project status

**v1.9.0 — Production/Stable software workflow; dynamic customer report verification with target-proven qualified UR5e physical baseline**

v1.9.0 adds data-driven report verification on top of the target-proven v1.8.9 physical runtime. Customer test IDs are opaque, report behavior is routed from declarative capability fields, arbitrary finite typed physical metrics can flow through evidence when a qualified adapter measures them, and report-wide simulation deduplicates physical cases so one qualified case measurement can satisfy multiple compatible KPIs without repeated robot motion.

The physical qualification claim itself remains grounded in the v1.8.9 target acceptance: the exact candidate completed the bounded UR5e nominal report lifecycle on the intended workstation with exact Twin readback, Pilz preflight, verified GRASP, scoped support contact, Gazebo carry, transfer/place, physical release/settle, explicit MoveIt detach/world reassert, retreat, and final verification.

Production-oriented software capabilities include:

```text
one-command customer intake
XLSX/CSV/YAML/JSON requirement normalization
opaque customer-defined report test IDs
declarative verification mode / metric / comparator / target / evidence authority
generic finite numeric/boolean physical metrics with bounded validation
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
case-centric qualified evidence reuse
report-wide physical-case deduplication
mixed deterministic + physical `simulate all` orchestration
truthful NOT_TESTED for unavailable/unsupported evidence
truthful robot support tiers
qualified UR5e report-test visual execution contract
direct UR5e controller-manager/action readiness binding
controller-native execution tolerance + independent DevAgent tracking evidence
canonical MoveIt workpiece lifecycle with world-integrity gate
semantic workpiece pose/geometry verification with persistent diagnostics
scoped destination-support place contact with matching preexecution semantics
persistent ROS↔Gazebo workpiece carrier
separate carried-pose and released-resting-pose authorities
read-only Gazebo post-release settle verification at 5 mm / 1°
deterministic two-phase MoveIt detach/world reassert at measured Gazebo pose
release-settle trace evidence
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. The target-proven UR5e claim remains limited to the qualified packaged nominal report path and exact acceptance environment. It does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, or authorized for autonomous real execution.

## Documentation

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

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.
