devagent-physical-engine 1.0.0__tar.gz → 1.2.0__tar.gz

devagent_physical_engine-1.2.0/PKG-INFO

@@ -0,0 +1,976 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 1.2.0
+Summary: Production-grade verification-first robotics evidence runtime with customer Twin lineage, measured physical verification, deterministic replay inspection, regression, and FAT evidence.
+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
+Keywords: robotics,industrial-automation,agentic-ai,ros2,verification,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)
+
+**Verification-first commissioning engineering for robotics and industrial automation: customer Twin import, deterministic verification, measured physical evidence, replayable evidence lineage, change-impact regression, and auditable FAT evidence.**
+
+> **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 one practical question before engineers travel onsite:
+
+> **What can be proven about this robot cell, what failed, what changed, and what evidence supports the conclusion?**
+
+## What v1.2.0 is
+
+DevAgent Physical Engine `v1.2.0` is a Production/Stable **bounded software workflow** for:
+
+- durable customer `Project / Site / Workcell` identity;
+- explicit customer Twin evidence and immutable Twin revisions;
+- deterministic structural and measured physical requirement checks;
+- nominal, boundary, pairwise-boundary, and fault verification-plan generation;
+- exact-Twin physical measurement artifacts;
+- canonical physical-motion evidence and runtime measurement binding;
+- immutable evidence bundles with artifact IDs, SHA-256 hashes, and Twin scope;
+- fail-closed replay reconstruction of stored run/case/seed/reset-state/motion lineage;
+- a read-only local/static Evidence Viewer for customer inspection;
+- change-impact and baseline/current regression analysis;
+- FAT evidence in Markdown, HTML, and JSON;
+- content-addressed project evidence and release artifacts.
+
+It does **not** claim that a customer robot cell is commissioned, functionally safe, or authorized for production execution.
+
+```text
+customer_review_ready
+production_engineering_ready
+physical_qualification = false
+site_qualification = false
+real_execution_allowed = false
+```
+
+`production_engineering_ready=true` means the supported engineering-evidence chain is complete. It is **not** a safety certificate or permission to command a production robot.
+
+## Product workflow
+
+```text
+CUSTOMER PROJECT / SITE / WORKCELL
+                |
+                v
+CUSTOMER ASSETS + EXPLICIT TWIN EVIDENCE
+                |
+                v
+IMMUTABLE TWIN REVISION
+                |
+                v
+REQUIREMENTS
+                |
+                v
+VERIFICATION PLAN
+ nominal / boundary / pairwise / faults
+                |
+                v
+QUALIFIED SIMULATION / SHADOW EXECUTION
+                |
+                v
+MEASURED PHYSICAL EVIDENCE
+ cycle / clearance / TCP / tracking / collision
+                |
+                v
+DETERMINISTIC VERDICTS
+ PASS / FAIL / NOT_TESTED
+                |
+                v
+EVIDENCE BUNDLE + REPLAY RECONSTRUCTION
+ requirement / Twin / run / case / motion / hashes
+                |
+                v
+CHANGE IMPACT + REGRESSION
+                |
+                v
+FAT REPORT + READ-ONLY EVIDENCE VIEWER
+```
+
+A generated verification plan is **not execution evidence**. Planned cases remain `planned_not_executed` until a runtime actually produces measured evidence.
+
+A replay reconstruction is also **not re-execution**. `devagent-commercial replay` proves that DevAgent can reconstruct and verify the exact persisted physical case/motion lineage; a separately qualified simulation adapter must perform any actual rerun and create new evidence.
+
+Unknown facts remain unknown. Unsupported requirements remain `NOT_TESTED`. A CAD, URDF, or mesh file does not prove pose, scale, TCP, calibration, collision geometry, or physics simply because the file exists.
+
+## Install
+
+Python 3.11+ is required.
+
+```bash
+python -m pip install --upgrade devagent-physical-engine==1.2.0
+```
+
+Verify the installed version:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+```
+
+Expected:
+
+```text
+1.2.0
+```
+
+The package installs three CLIs:
+
+```text
+devagent-commercial   customer project / Twin / requirements / evidence / replay / FAT workflow
+devagent-physical     deterministic core, project inspection, ROS setup/qualification
+devagent-physical-ai  provider-backed natural-language engineering front end
+```
+
+`pip install` does **not** install ROS 2, Gazebo, MoveIt, OEM drivers, or privileged operating-system packages.
+
+### Optional AI providers
+
+```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]"
+# or all supported provider SDKs
+python -m pip install "devagent-physical-engine[ai]"
+```
+
+Typical credential variables:
+
+```bash
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+export GEMINI_API_KEY="..."   # GOOGLE_API_KEY is also accepted for Gemini
+```
+
+Check SDK and credential availability without a provider network call:
+
+```bash
+devagent-physical-ai doctor --provider openai
+```
+
+A live provider qualification uses provider API credits:
+
+```bash
+devagent-physical-ai qualify \
+  --provider openai \
+  --model YOUR_MODEL
+```
+
+# Commercial workflow: end to end
+
+The default SQLite project/evidence database is:
+
+```text
+~/.devagent/projects.db
+```
+
+To use a dedicated database, put `--db` immediately after `devagent-commercial`:
+
+```bash
+devagent-commercial --db ./customer-projects.db status warehouse-cnc-04
+```
+
+The same project database can be inspected with:
+
+```bash
+devagent-physical project --db ./customer-projects.db show warehouse-cnc-04
+```
+
+## 1. Create the customer project
+
+```bash
+devagent-commercial init warehouse-cnc-04 \
+  --name "Warehouse CNC Loading Cell 04" \
+  --site atl-01 \
+  --workcell cnc-04
+```
+
+Keep the same project ID when the cell changes. New evidence creates new immutable Twin revisions instead of overwriting history.
+
+## 2. Prepare customer Twin evidence
+
+A customer folder can contain engineering assets plus exactly one DevAgent Twin manifest:
+
+```text
+customer-cell/
+├── devagent-twin.yaml
+├── robot.urdf
+├── robot.srdf
+├── gripper.step
+├── fixture.stl
+└── calibration.csv
+```
+
+Supported inventory suffixes include:
+
+```text
+.urdf .xacro .srdf .stl .dae .obj .step .stp .iges .igs
+.yaml .yml .json .csv
+```
+
+Customer assets are SHA-256 fingerprinted with bounded streaming I/O and may be up to 512 MiB per file. Symlinks and ambiguous multiple root `devagent-twin.*` manifests are rejected. Structured manifest input is intentionally subject to a smaller bounded text limit.
+
+Physical facts are promoted only through one explicit manifest:
+
+```text
+devagent-twin.yaml
+devagent-twin.yml
+devagent-twin.json
+```
+
+Start from the template:
+
+- [examples/commercial/devagent-twin.yaml](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/devagent-twin.yaml)
+
+**Do not use the template values as customer evidence.** Replace geometry, pose, TCP, payload, frames, physics values, and `source_ref` with actual customer/imported/measured evidence.
+
+Minimal pattern:
+
+```yaml
+schema_version: 1
+length_unit: mm
+angle_unit: deg
+
+engineering_request:
+  robot: ur5e
+  operation: load
+  object_id: BOX_101
+  source: conveyor_a
+  destination: cnc_04
+  tool: parallel_gripper
+  payload_kg: 1.5
+  purpose: simulate
+
+robot_base_pose:
+  x: 0
+  y: 0
+  z: 0
+  roll: 0
+  pitch: 0
+  yaw: 0
+  origin: measured
+  source_ref: SITE_SURVEY_2026_09_01
+```
+
+DevAgent does not silently promote `estimated` or `default` values into customer evidence.
+
+## 3. Import the Twin and resolve missing information
+
+```bash
+devagent-commercial import-twin warehouse-cnc-04 ./customer-cell \
+  | tee twin-import.json
+```
+
+The JSON result includes `twin_revision_id`, `twin_state`, `information_requests`, discovered asset hashes, and an immutable evidence artifact.
+
+If `information_requests` is non-empty, obtain real engineering evidence and import again. Do not guess TCP, robot base, calibration, geometry, or physics values merely to make the Twin pass.
+
+List immutable revisions:
+
+```bash
+devagent-physical project revisions warehouse-cnc-04 \
+  | tee twin-revisions.json
+```
+
+Capture the latest revision ID and exact Twin hash without requiring `jq`:
+
+```bash
+TWIN_REVISION=$(python - <<'PY'
+import json
+p = json.load(open("twin-revisions.json", encoding="utf-8"))
+print(p["revisions"][-1]["revision_id"])
+PY
+)
+
+TWIN_HASH=$(python - <<'PY'
+import json
+p = json.load(open("twin-revisions.json", encoding="utf-8"))
+print(p["revisions"][-1]["twin_hash"])
+PY
+)
+
+printf 'revision=%s\ntwin_hash=%s\n' "$TWIN_REVISION" "$TWIN_HASH"
+```
+
+Never bind measurement evidence from one Twin revision to another Twin revision.
+
+## 4. Define deterministic requirements
+
+Production example:
+
+- [examples/commercial/requirements-production.csv](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements-production.csv)
+
+```csv
+requirement_id,text,check,target,expected,severity
+REQ-001,Twin shall be physics ready,physics_allowed,,true,must
+REQ-101,Cycle time shall be less than or equal to 8 seconds,cycle_time_max_s,8.0,,must
+REQ-102,Minimum clearance shall be at least 30 millimeters,minimum_clearance_m,0.03,,must
+REQ-103,Final TCP error shall be at most 2 millimeters,final_tcp_error_max_m,0.002,,must
+REQ-104,Maximum tracking error shall be at most 0.03 radians,max_tracking_error_rad,0.03,,must
+REQ-105,Trajectory shall remain collision free,collision_free,,true,must
+REQ-106,Physical task shall complete,physical_completed,,true,must
+```
+
+Record the requirement set:
+
+```bash
+devagent-commercial requirements warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv \
+  | tee requirement-artifact.json
+```
+
+Unsupported prose remains `NOT_TESTED`; an LLM cannot auto-pass it.
+
+## 5. Generate a bounded verification plan
+
+Example:
+
+- [examples/commercial/verification-plan.yaml](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/verification-plan.yaml)
+
+```yaml
+max_cases: 128
+variation:
+  object_x_mm: [-20, 0, 20]
+  object_y_mm: [-20, 0, 20]
+  payload_kg: [1.0, 3.0, 5.0]
+  speed_pct: [70, 85, 100]
+faults:
+  - missing_part
+  - controller_timeout
+  - sensor_latency
+```
+
+```bash
+devagent-commercial verification-plan warehouse-cnc-04 \
+  examples/commercial/verification-plan.yaml \
+  --revision "$TWIN_REVISION" \
+  | tee verification-plan-artifact.json
+```
+
+The generator creates bounded nominal, single-parameter boundary, pairwise-boundary, and explicit fault cases. It does **not** claim they were executed.
+
+## 6. Execute the supported scope and record real measurements
+
+A measurement artifact must come from the simulation, hardware-shadow, or site-measurement workflow that actually produced the metrics.
+
+Supported measured fields are:
+
+```text
+cycle_time_s
+minimum_clearance_m
+final_tcp_error_m
+max_tracking_error_rad
+sample_count
+collision_free
+completed
+```
+
+Schema/example:
+
+- [examples/commercial/physical-measurement.json](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/physical-measurement.json)
+
+Replace the example metrics with actual run output and replace `twin_hash` with the exact `$TWIN_HASH` captured above.
+
+```json
+{
+  "case_id": "nominal-load",
+  "backend": "gazebo_moveit",
+  "source_kind": "simulation",
+  "run_id": "physical-20260901T120000000000Z",
+  "qualification_ref": "~/.devagent/physical-qualification/physical-20260901T120000000000Z",
+  "twin_hash": "EXACT_TWIN_SHA256",
+  "metrics": {
+    "cycle_time_s": 7.43,
+    "minimum_clearance_m": 0.038,
+    "final_tcp_error_m": 0.0016,
+    "max_tracking_error_rad": 0.021,
+    "collision_free": true,
+    "completed": true,
+    "sample_count": 264
+  }
+}
+```
+
+Record external measurement evidence against the exact Twin revision:
+
+```bash
+devagent-commercial record-measurement warehouse-cnc-04 \
+  physical-measurement.json \
+  --revision "$TWIN_REVISION" \
+  | tee physical-evidence.json
+```
+
+Capture the content-addressed artifact ID:
+
+```bash
+MEASUREMENT_ARTIFACT=$(python - <<'PY'
+import json
+p = json.load(open("physical-evidence.json", encoding="utf-8"))
+print(p["artifact_id"])
+PY
+)
+```
+
+The recorder rejects malformed/non-finite/negative metrics, exact-Twin hash mismatch, invalid source kinds, and inconsistent positive-clearance/collision claims.
+
+### Preferred typed runtime binding
+
+If the runtime already owns `PhysicalMotionPlan` and `MotionExecutionMetrics`, prefer the typed binding over manually retyping metric JSON. In v1.2 this path also persists the canonical physical motion as immutable project evidence, enabling strong replay lineage.
+
+```python
+from devagent_physical_engine import (
+    CommercialProjectRepository,
+    PhysicalEvidenceRecorder,
+)
+
+repository = CommercialProjectRepository("~/.devagent/projects.db")
+recorder = PhysicalEvidenceRecorder(repository)
+
+artifact = recorder.record_motion_metrics(
+    project_id="warehouse-cnc-04",
+    motion=physical_motion_plan,       # PhysicalMotionPlan produced by the runtime
+    metrics=motion_execution_metrics,  # MotionExecutionMetrics from execution
+    backend="gazebo_moveit",
+    run_id="physical-20260901T120000000000Z",
+    qualification_ref="~/.devagent/physical-qualification/physical-20260901T120000000000Z",
+    revision_id="twin-r0001",
+    case_id="case-0001",
+)
+```
+
+The typed bridge checks the motion/Twin binding and persists:
+
+```text
+physical_measurement
+physical_motion_plan
+runtime_measurement_binding
+```
+
+including exact artifact hashes, motion fingerprint, planner identity, metric origin, run ID, and qualification reference.
+
+## 7. Run the requirement campaign
+
+```bash
+devagent-commercial campaign warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv \
+  --revision "$TWIN_REVISION" \
+  --measurement "$MEASUREMENT_ARTIFACT" \
+  | tee campaign.json
+```
+
+Capture the campaign artifact:
+
+```bash
+CAMPAIGN_ARTIFACT=$(python - <<'PY'
+import json
+p = json.load(open("campaign.json", encoding="utf-8"))
+print(p["artifact_id"])
+PY
+)
+```
+
+A missing metric or unsupported check yields `NOT_TESTED`, never PASS. Failed/not-tested `must` requirements block bounded release readiness.
+
+## 8. Generate the first FAT evidence report
+
+For the first campaign, no regression baseline exists yet:
+
+```bash
+devagent-commercial fat-report warehouse-cnc-04 \
+  "$CAMPAIGN_ARTIFACT" \
+  --output FAT_REPORT.html \
+  | tee fat-artifact.json
+```
+
+Supported output extensions are `.md`, `.html`, `.htm`, and `.json`. The immutable `fat_report` artifact stores Markdown, escaped customer-facing HTML, and structured JSON from the same evidence lineage.
+
+## 9. Build the v1.2 evidence bundle
+
+After a campaign exists, bind the exact engineering chain into one immutable trace artifact:
+
+```bash
+devagent-commercial evidence-bundle warehouse-cnc-04 \
+  "$CAMPAIGN_ARTIFACT" \
+  | tee evidence-bundle.json
+```
+
+You can bind exact optional artifacts explicitly:
+
+```bash
+devagent-commercial evidence-bundle warehouse-cnc-04 \
+  "$CAMPAIGN_ARTIFACT" \
+  --verification-plan "$PLAN_ARTIFACT" \
+  --regression "$REGRESSION_ARTIFACT" \
+  --fat-report "$FAT_ARTIFACT" \
+  | tee evidence-bundle.json
+```
+
+The bundle records exact references containing:
+
+```text
+artifact_id
+artifact_type
+artifact_hash
+twin_revision_id
+```
+
+and requirement traces containing verdict, observed value, expected threshold, reason, and evidence references.
+
+Capture the bundle ID:
+
+```bash
+EVIDENCE_BUNDLE=$(python - <<'PY'
+import json
+p = json.load(open("evidence-bundle.json", encoding="utf-8"))
+print(p["artifact_id"])
+PY
+)
+```
+
+## 10. Verify replay reconstruction
+
+`replay` is intentionally a verification command, not a robot-control command:
+
+```bash
+devagent-commercial replay warehouse-cnc-04 \
+  "$EVIDENCE_BUNDLE" \
+  --qualification-root ~/.devagent/physical-qualification \
+  --output replay-manifest.json \
+  --record
+```
+
+Before reconstruction, the hardened replay boundary verifies every bundle reference:
+
+```text
+artifact ID
+artifact type
+artifact SHA-256
+Twin revision scope
+```
+
+It then verifies the persisted physical qualification evidence:
+
+```text
+trusted qualification-store root
+run_id
+Twin SHA-256
+case_id
+case evidence hash
+case fingerprint
+seed
+reset state
+case parameters
+canonical motion fingerprint
+commercial physical_motion_plan fingerprint
+```
+
+Successful output includes:
+
+```text
+replayable = true
+execution_performed = false
+replay_manifest_hash = ...
+```
+
+`--record` writes immutable `replay_verification` evidence after successful reconstruction.
+
+**Important:** this does not command Gazebo, MoveIt, a real robot, an OEM controller, a PLC, or a safety PLC. A qualified simulation adapter may consume a verified replay manifest for an actual rerun, and that rerun must create new measured evidence.
+
+If exact lineage cannot be proven, replay fails closed. Exit code `24` means the evidence bundle is not replayable under the supplied qualification store/run evidence.
+
+## 11. Inspect the Evidence Viewer
+
+For customer sharing, generate a self-contained static HTML file:
+
+```bash
+devagent-commercial evidence-viewer warehouse-cnc-04 \
+  --output DEVAGENT_EVIDENCE.html
+```
+
+For local inspection:
+
+```bash
+devagent-commercial evidence-viewer warehouse-cnc-04 \
+  --open-browser
+```
+
+Default local URL:
+
+```text
+http://127.0.0.1:8765/
+```
+
+The built-in viewer is deliberately constrained:
+
+- loopback host only (`127.0.0.1`, `localhost`, or `::1`);
+- read-only GET surface;
+- no write endpoint;
+- no robot-control endpoint;
+- customer strings HTML-escaped;
+- `Cache-Control: no-store`;
+- restrictive Content Security Policy.
+
+It shows:
+
+- project/site/workcell identity;
+- customer-review readiness;
+- production-engineering evidence readiness;
+- explicit physical/site authority boundary;
+- requirement verdicts;
+- observed and expected values;
+- evidence references;
+- readiness blockers;
+- immutable artifact IDs and SHA-256 hashes;
+- exact Twin revision hashes.
+
+Inspect the normalized graph as JSON when integrating another UI or audit tool:
+
+```bash
+devagent-commercial evidence-graph warehouse-cnc-04 \
+  > evidence-graph.json
+```
+
+The graph is derived from the existing immutable project store. It is **not a second source of truth**.
+
+## 12. Create a new Twin revision when the cell changes
+
+When robot base, tool/TCP, fixture, workpiece, controller setting, or other evidence changes, update/import the evidence again instead of overwriting history:
+
+```bash
+devagent-commercial import-twin warehouse-cnc-04 ./customer-cell-revision-2
+```
+
+Then inspect the new revision:
+
+```bash
+devagent-physical project revisions warehouse-cnc-04
+```
+
+Compute conservative requirement impact:
+
+```bash
+devagent-commercial impact warehouse-cnc-04 \
+  twin-r0001 twin-r0002 \
+  examples/commercial/requirements-production.csv \
+  | tee impact.json
+```
+
+Capture its artifact ID:
+
+```bash
+IMPACT_ARTIFACT=$(python - <<'PY'
+import json
+p = json.load(open("impact.json", encoding="utf-8"))
+print(p["artifact_id"])
+PY
+)
+```
+
+Run the current campaign on the new Twin/measurement evidence, then compare baseline/current campaign artifacts:
+
+```bash
+devagent-commercial regression warehouse-cnc-04 \
+  "$BASELINE_CAMPAIGN" "$CURRENT_CAMPAIGN" \
+  --impact "$IMPACT_ARTIFACT" \
+  | tee regression.json
+```
+
+Capture regression evidence:
+
+```bash
+REGRESSION_ARTIFACT=$(python - <<'PY'
+import json
+p = json.load(open("regression.json", encoding="utf-8"))
+print(p["artifact_id"])
+PY
+)
+```
+
+A PASS -> non-PASS transition is a regression. Numeric observed values are compared as deltas. Stale evidence cannot preserve current readiness.
+
+Generate the regression-aware FAT report:
+
+```bash
+devagent-commercial fat-report warehouse-cnc-04 \
+  "$CURRENT_CAMPAIGN" \
+  --regression "$REGRESSION_ARTIFACT" \
+  --output FAT_REPORT_CURRENT.html
+```
+
+Then build a new evidence bundle for the current campaign and inspect/replay that exact lineage.
+
+## 13. Inspect readiness and evidence artifacts
+
+```bash
+devagent-commercial status warehouse-cnc-04
+devagent-commercial artifacts warehouse-cnc-04
+```
+
+Useful artifact filters:
+
+```bash
+devagent-commercial artifacts warehouse-cnc-04 --type physical_measurement
+devagent-commercial artifacts warehouse-cnc-04 --type physical_motion_plan
+devagent-commercial artifacts warehouse-cnc-04 --type runtime_measurement_binding
+devagent-commercial artifacts warehouse-cnc-04 --type verification_plan
+devagent-commercial artifacts warehouse-cnc-04 --type commercial_campaign
+devagent-commercial artifacts warehouse-cnc-04 --type change_impact
+devagent-commercial artifacts warehouse-cnc-04 --type commercial_regression
+devagent-commercial artifacts warehouse-cnc-04 --type fat_report
+devagent-commercial artifacts warehouse-cnc-04 --type evidence_bundle
+devagent-commercial artifacts warehouse-cnc-04 --type replay_verification
+```
+
+# Evidence origin versus qualification authority
+
+Evidence Trust uses origin labels to tell the reviewer where measurements came from:
+
+```text
+MODEL_ONLY
+SIMULATION_MEASURED
+SHADOW_MEASURED
+SITE_MEASURED
+```
+
+These labels are **not certification levels** and do not automatically promote physical/site authority.
+
+For example, this is a bounded engineering claim:
+
+```text
+REQ-102: modeled clearance >= 30 mm
+Observed: 37.2 mm
+Verdict: PASS
+Origin: SIMULATION_MEASURED
+Twin: twin-r0007
+Twin SHA-256: ...
+Measurement artifact: art-...
+Motion artifact: art-...
+Replay reconstruction: verified
+```
+
+It means the identified Twin/runtime/case evidence satisfied the deterministic modeled requirement. It does **not** mean the real workcell is safe for production.
+
+# Supported deterministic requirement checks
+
+Structural/Twin checks:
+
+- `planning_allowed`
+- `physics_allowed`
+- `entity_present`
+- `validation_issue_absent`
+- `twin_state`
+
+Measured physical checks:
+
+- `cycle_time_max_s`
+- `minimum_clearance_m`
+- `final_tcp_error_max_m`
+- `max_tracking_error_rad`
+- `collision_free`
+- `physical_completed`
+
+A physical requirement without exact-Twin measurement evidence is `NOT_TESTED`.
+
+# CLI exit codes for automation
+
+`devagent-commercial` intentionally returns non-zero for engineering blockers so shell/CI automation does not silently treat a failed verification as success.
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | command completed and its verdict/readiness gate passed where applicable |
+| `10` | project/input/commercial contract error |
+| `12` | imported Twin is invalid |
+| `20` | campaign completed but is not release-ready |
+| `21` | regression comparison detected a regression |
+| `22` | FAT report generated but bounded release-readiness is false |
+| `23` | project status is not `commercial_v1_ready` |
+| `24` | evidence replay reconstruction is not currently replayable |
+
+Preserve the command JSON output even when the process returns a non-zero engineering verdict.
+
+# AI engineering front end
+
+AI is optional and remains outside deterministic execution authority.
+
+Interpret a natural-language request:
+
+```bash
+devagent-physical-ai request \
+  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04." \
+  --provider openai \
+  --model YOUR_MODEL
+```
+
+Run the engineering agent:
+
+```bash
+devagent-physical-ai engineer \
+  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04. Simulate and verify the plan." \
+  --provider openai \
+  --model YOUR_MODEL
+```
+
+Task-specific `--visualize` remains deliberately narrow: v1.2 retains the supported nominal UR5e `load` reference-workcell path and fails closed outside that scope.
+
+```bash
+devagent-physical-ai engineer \
+  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04. Simulate and verify the plan." \
+  --provider openai \
+  --model YOUR_MODEL \
+  --visualize
+```
+
+`--visual-demo` is different: it runs a visual UR5e demo after engineering verification, but it is **not** claimed to be the requested BOX/source/destination task-specific motion.
+
+# Physical simulation setup and qualification
+
+Reference direction:
+
+```text
+Ubuntu 24.04
+ROS 2 Jazzy
+Gazebo Harmonic
+gz_ros2_control
+Universal Robots ROS 2 driver
+ur_simulation_gz
+MoveIt 2
+```
+
+Preview system changes:
+
+```bash
+devagent-physical setup --profile ur5e-sim --dry-run
+```
+
+Apply the supported setup explicitly:
+
+```bash
+devagent-physical setup --profile ur5e-sim --yes
+```
+
+Check and qualify the target runtime:
+
+```bash
+devagent-physical ros doctor
+devagent-physical ros qualify-trajectory-runtime
+```
+
+Other reference commands:
+
+```bash
+devagent-physical ros launch --dry-run
+devagent-physical ros acceptance
+devagent-physical ros demo
+devagent-physical qualify
+```
+
+Hosted Python CI cannot prove graphical Gazebo, MoveIt `move_group`, TF, controller actions, or OEM drivers. Physical-simulation qualification must run on the exact workstation/adapter stack. ABB, FANUC, KUKA, or other registry entries do not imply equal physical qualification.
+
+# Evidence and authority rules
+
+DevAgent is fail-closed by design:
+
+- AI cannot authorize real robot execution.
+- Missing customer facts remain unknown.
+- Unsupported prose remains `NOT_TESTED`.
+- Measurements bind to an immutable Twin revision/hash.
+- Non-finite and malformed physical metrics are rejected.
+- Stale campaign/regression/FAT evidence cannot preserve current readiness after evidence lineage changes.
+- A verification plan is not execution evidence.
+- A replay reconstruction is not execution evidence from a new run.
+- Evidence bundles are content-addressed and replay validates referenced artifact IDs/types/hashes/Twin scope before reconstruction.
+- The Evidence Viewer is read-only and exposes no robot-control endpoint.
+- Simulation evidence does not override guarding, risk assessment, safety PLC validation, OEM controller validation, site acceptance, or engineer sign-off.
+
+Readiness concepts remain intentionally separate:
+
+```text
+customer_review_ready
+    bounded customer requirement/evidence review is complete
+
+production_engineering_ready
+    supported physical requirements passed using exact-Twin measured evidence
+    with run/qualification provenance
+
+physical_qualification / site_qualification / real_execution_allowed
+    false in the v1.2 commercial evidence workflow
+```
+
+# Example files
+
+- [Twin manifest template](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/devagent-twin.yaml)
+- [Basic structural requirements](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements.csv)
+- [Production requirement checks](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements-production.csv)
+- [Verification-plan input](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/verification-plan.yaml)
+- [Physical-measurement schema/example](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/physical-measurement.json)
+
+The examples are templates/schema examples; they are not customer-site evidence.
+
+# Release quality
+
+Every PR/main update runs Python 3.11/3.12/3.13 regression, compilation, Ruff checks, branch coverage, a dedicated >=90% production-authority coverage gate, a dedicated >=90% Evidence Trust/replay coverage gate, package build/clean-install smoke, CLI Evidence Trust smoke, and runtime dependency vulnerability audit.
+
+Releases are created only from exact green `main`, rebuilt from the exact tag, clean-installed, supplied with CycloneDX SBOM + SHA-256 checksums, attached to GitHub Release, and published to PyPI through Trusted Publishing with digital attestations.
+
+# Documentation
+
+- [Evidence Trust v1.2](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/EVIDENCE_TRUST_V12.md)
+- [Production Grade v1.1](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_GRADE_V1_1.md)
+- [Production readiness](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_READINESS.md)
+- [Commercial V1](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_V1.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)
+- [Robot platform and Twin](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ROBOT_PLATFORM_AND_TWIN.md)
+- [Measured physical runtime](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/MEASURED_PHYSICAL_RUNTIME.md)
+- [Qualification](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/QUALIFICATION.md)
+- [Optimization](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/OPTIMIZATION.md)
+- [AI providers](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AI_PROVIDERS.md)
+- [PyPI release process](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PYPI_RELEASE.md)
+
+## Project status
+
+**v1.2.0 — Production/Stable software workflow with customer Twin evidence, measured physical requirement verification, immutable evidence bundles, hardened replay reconstruction, read-only Evidence Viewer, change-impact regression, and FAT Markdown/HTML/JSON evidence.**
+
+Production/Stable applies to the bounded software/API/CLI/evidence workflow. Physical qualification remains robot-, adapter-, workstation-, and evidence-specific. Customer-site qualification, functional-safety certification, and production-hardware command authority are not claimed and remain locked by default.
+
+## 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.