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

devagent_physical_engine-1.3.1/PKG-INFO

@@ -0,0 +1,1290 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 1.3.1
+Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, deterministic Twin lineage, measured physical verification, 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.**
+
+DevAgent turns an ordinary customer engineering folder into a bounded, traceable verification workflow:
+
+```text
+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 + replayable lineage
+```
+
+> **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 a practical commissioning question before engineers travel onsite:
+
+> **What can be proven about this cell, what failed, what is still unknown, what changed, and what evidence supports the conclusion?**
+
+---
+
+## Quick start
+
+Python 3.11+ is required.
+
+Install:
+
+```bash
+python -m pip install --upgrade devagent-physical-engine==1.3.1
+```
+
+Verify the installed version:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+```
+
+Expected:
+
+```text
+1.3.1
+```
+
+Run DevAgent on the customer project folder:
+
+```bash
+devagent verify ./customer-project
+```
+
+That is the normal starting point.
+
+You do **not** need to manually initialize a DevAgent project, choose artifact IDs, convert an XLSX sheet to CSV, or understand the internal evidence database before using Simple Mode.
+
+Request physical simulation when an exact qualified execution path exists:
+
+```bash
+devagent verify ./customer-project --simulate
+```
+
+Open the generated Evidence Viewer after verification:
+
+```bash
+devagent verify ./customer-project --simulate --open
+```
+
+`--open` requests the report in a **new browser tab** after the terminal verification summary is complete. DevAgent requests that the browser not raise itself over the terminal, then the CLI returns so the same terminal can be used for replay and inspection commands. Desktop/browser policy may still choose to focus the new tab.
+
+For machine-readable output:
+
+```bash
+devagent verify ./customer-project --json
+```
+
+Use a dedicated evidence database and results directory when required:
+
+```bash
+devagent verify ./customer-project \
+  --db ./customer-projects.db \
+  --output ./verification-results \
+  --json
+```
+
+Default locations:
+
+```text
+Evidence database: ~/.devagent/projects.db
+Results:           <customer-project>/devagent-results/
+```
+
+---
+
+# What the user sees in the terminal
+
+Human Simple Mode keeps the terminal as the primary run surface. Example:
+
+```text
+[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 will remain available: .../EVIDENCE.html
+[DevAgent +   1.26s] REPORT        DISPATCHED browser request completed; terminal is available
+```
+
+If verification runs longer than five seconds, DevAgent emits a heartbeat such as:
+
+```text
+[DevAgent +   5.00s] ENGINE        RUNNING    verification is still active
+```
+
+The same human progress trace is persisted to:
+
+```text
+<customer-project>/devagent-results/RUN.log
+```
+
+After an Evidence Bundle exists, DevAgent prints a copy/paste replay command. Example:
+
+```bash
+devagent-commercial --db ~/.devagent/projects.db replay \
+  acme-cell \
+  EVIDENCE_BUNDLE_ARTIFACT \
+  --output ./devagent-results/REPLAY.json
+```
+
+If simulation was blocked and no measured runtime case exists, replay is expected to fail closed. If qualified simulation runtime evidence exists, replay reconstructs and verifies that exact persisted case without commanding a robot.
+
+To suppress human progress while keeping the final human summary:
+
+```bash
+devagent verify ./customer-project --no-progress
+```
+
+`--json` remains machine-clean and suppresses human progress automatically.
+
+---
+
+# How to use the engine
+
+## 1. Give DevAgent the engineering folder you already have
+
+A typical project may look like this:
+
+```text
+ACME_CNC_CELL_TEST/
+├── project.yaml
+├── requirements.xlsx
+├── ur5e.urdf
+├── tcp.yaml
+├── layout.yaml
+├── robot_program/
+│   └── mission.yaml
+├── drawings.step
+├── safety_requirements.pdf
+└── expected/
+    └── expected_findings.json
+```
+
+The filenames do not all have to match this example. DevAgent inventories the source tree, fingerprints files with SHA-256, assigns bounded roles, and normalizes supported structured evidence.
+
+Important rule:
+
+```text
+file discovered != engineering fact proven
+```
+
+A URDF, Xacro, STEP, STL, PDF, YAML, or JSON file does not automatically prove pose, TCP, calibration, collision geometry, physics, safety, or production readiness.
+
+### What DevAgent does during intake
+
+```text
+CUSTOMER FOLDER
+      |
+      v
+FILE INVENTORY + SHA-256
+      |
+      v
+ROLE CLASSIFICATION
+      |
+      +--> expected/ test data -> NEVER engineering authority
+      |
+      v
+REQUIREMENT NORMALIZATION
+      |
+      v
+EXPLICIT FACT EXTRACTION
+      |
+      v
+PROPOSED TWIN NORMALIZATION
+      |
+      v
+DETERMINISTIC TWIN VALIDATION
+      |
+      +--> missing or ambiguous facts -> QUESTIONS.md
+      |
+      v
+VERIFICATION PLAN / CAMPAIGN / FAT
+      |
+      v
+EVIDENCE VIEWER + RUN LOG + REPLAY HANDOFF
+```
+
+Unknown facts remain unknown. DevAgent does not fill engineering gaps with guesses.
+
+---
+
+## 2. First-run example: incomplete customer information
+
+Assume the customer provides this `project.yaml`:
+
+```yaml
+project_id: acme-cell
+name: ACME Cell
+site_id: atl-01
+workcell_id: cell-01
+```
+
+and also provides robot/layout/TCP/requirements files, but does not say exactly what task the robot must perform.
+
+Run:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST
+```
+
+DevAgent creates the project automatically and may return:
+
+```text
+State: needs_information
+```
+
+Typical questions may include:
+
+```text
+engineering_request_operation_missing
+engineering_request_object_id_missing
+engineering_request_source_missing
+engineering_request_destination_missing
+```
+
+The questions are also written to:
+
+```text
+ACME_CNC_CELL_TEST/devagent-results/QUESTIONS.md
+```
+
+This is expected fail-closed behavior. DevAgent will not invent the operation, workpiece, source, or destination simply to produce a green report.
+
+Typical first-run output:
+
+```text
+ACME_CNC_CELL_TEST/
+└── devagent-results/
+    ├── RUN.log
+    ├── SUMMARY.json
+    ├── INTAKE.json
+    ├── QUESTIONS.md
+    └── normalized/
+        └── requirements.csv
+```
+
+Fix the source engineering information, then run the same command again.
+
+---
+
+## 3. Complete ACME example
+
+The following example uses the same input shape exercised by the v1.3 one-command acceptance tests.
+
+### `project.yaml`
+
+```yaml
+project_id: acme-cell
+name: ACME Cell
+site_id: atl-01
+workcell_id: cell-01
+
+robot_base_pose:
+  x: 0
+  y: 0
+  z: 0
+  roll: 0
+  pitch: 0
+  yaw: 0
+
+engineering_request:
+  robot: ur5e
+  operation: load
+  object_id: BOX_101
+  source: conveyor_a
+  destination: cnc_04
+  tool: gripper
+  payload_kg: 1.5
+```
+
+### `tcp.yaml`
+
+```yaml
+tcp:
+  x: 0
+  y: 0
+  z: 180
+  roll: 0
+  pitch: 0
+  yaw: 0
+```
+
+### `layout.yaml`
+
+```yaml
+entities:
+  - id: conveyor_a
+    type: conveyor
+    pose:
+      x: 700
+      y: 0
+      z: 850
+    geometry:
+      kind: box
+      dimensions: [2000, 600, 800]
+
+  - id: cnc_04
+    type: machine
+    pose:
+      x: 1200
+      y: 400
+      z: 0
+    geometry:
+      kind: box
+      dimensions: [1400, 1200, 1800]
+
+  - id: BOX_101
+    type: workpiece
+    pose:
+      x: 700
+      y: 0
+      z: 900
+    geometry:
+      kind: box
+      dimensions: [200, 100, 50]
+```
+
+### `ur5e.urdf`
+
+Use the customer's real robot model. A minimal test fixture can look like:
+
+```xml
+<robot name="ur5e"/>
+```
+
+Do not treat a placeholder URDF as production geometry evidence.
+
+### `requirements.xlsx`
+
+A conventional first worksheet can contain columns such as:
+
+| requirement_id | text | check | target | expected | severity |
+| --- | --- | --- | ---: | --- | --- |
+| REQ-101 | Cycle time <= 8 s | cycle_time_max_s | 8.0 | true | must |
+| REQ-102 | E-stop accessible |  |  | true | must |
+
+Simple Mode can normalize common requirement ID, text, check, threshold/target, expected-value, and severity/criticality column names without requiring OpenPyXL at runtime.
+
+If the spreadsheet columns are ambiguous, DevAgent asks for clarification rather than guessing which column is authoritative.
+
+Run:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST
+```
+
+When enough explicit evidence exists to build the Twin and deterministic campaign, the results directory can expand to:
+
+```text
+ACME_CNC_CELL_TEST/
+└── devagent-results/
+    ├── RUN.log
+    ├── SUMMARY.json
+    ├── INTAKE.json
+    ├── QUESTIONS.md
+    ├── normalized/
+    │   ├── requirements.csv
+    │   └── devagent-twin.yaml
+    ├── FAT_REPORT.html
+    ├── EVIDENCE.html
+    └── REPLAY.json          # when replay succeeds with --output
+```
+
+`normalized/devagent-twin.yaml` is generated evidence mapping. It is not an independent source of truth and does not bypass Twin validation.
+
+---
+
+## 4. Request simulation
+
+Run:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST --simulate
+```
+
+`--simulate` means:
+
+```text
+request measured physical simulation if the exact imported-Twin execution path is qualified
+```
+
+It does **not** mean:
+
+```text
+run any available demo and label it customer evidence
+```
+
+The current one-command safety boundary is:
+
+```text
+IMPORTED CUSTOMER TWIN
+        |
+        v
+EXACT QUALIFIED EXECUTION ADAPTER?
+        |
+   +----+----+
+   |         |
+  YES        NO
+   |         |
+execute     simulation_state=blocked
+measure     exit 31 when --simulate was requested
+record      no fake measurement
+```
+
+For example, the repository contains a UR5e reference simulation stack, but:
+
+```text
+reference UR5e demo != customer imported Twin evidence
+```
+
+If the exact imported-customer execution adapter is not qualified, DevAgent reports a bounded reason such as:
+
+```text
+imported_customer_twin_execution_adapter_not_yet_qualified
+```
+
+or:
+
+```text
+twin_not_ready_for_physics
+```
+
+That is intentional. A blocked simulation is more trustworthy than a visually impressive but unrelated demo.
+
+---
+
+## 5. Open the Evidence Viewer and continue in the terminal
+
+When evidence lineage can be rendered:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST --open
+```
+
+or:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST --simulate --open
+```
+
+The sequence is intentionally:
+
+```text
+terminal verification completes
+        ↓
+final summary printed
+        ↓
+replay command printed
+        ↓
+Evidence Viewer requested in a new browser tab
+        ↓
+CLI returns
+        ↓
+same terminal is available for replay / artifact inspection / next command
+```
+
+The viewer is read-only and is intended to answer:
+
+- Which requirement was evaluated?
+- What was the verdict?
+- What value was observed?
+- What threshold or expected value was used?
+- Which Twin revision was evaluated?
+- Which evidence artifact supports the result?
+- Which SHA-256 hashes bind the evidence?
+- What is still blocked or not tested?
+
+The trust principle is simple:
+
+> **Do not trust a PASS label by itself. Inspect the evidence behind it.**
+
+---
+
+# Understanding the results
+
+## `RUN.log`
+
+Persistent copy of the human terminal progress trace. It is presentation/debug evidence and does not replace immutable engineering artifacts.
+
+Inspect it later:
+
+```bash
+cat ./customer-project/devagent-results/RUN.log
+```
+
+or follow it while another process is running:
+
+```bash
+tail -f ./customer-project/devagent-results/RUN.log
+```
+
+## `SUMMARY.json`
+
+This is the primary machine-readable result of Simple Mode.
+
+Important fields include:
+
+```text
+project_id
+state
+twin_revision_id
+twin_state
+requirements_file
+verification_plan_artifact_id
+campaign_artifact_id
+fat_artifact_id
+evidence_bundle_artifact_id
+evidence_viewer
+simulation_requested
+simulation_state
+simulation_reason
+release_ready
+real_execution_allowed
+questions
+```
+
+A green software workflow never changes this hard safety boundary by itself:
+
+```text
+real_execution_allowed = false
+```
+
+## `INTAKE.json`
+
+Records the source-file inventory and SHA-256 fingerprints so the customer can see exactly what DevAgent inspected.
+
+Each discovered file is associated with a bounded role and authority decision.
+
+Examples:
+
+```text
+requirements.xlsx       -> requirements
+layout.yaml              -> engineering_data
+ur5e.urdf                -> robot_model
+safety_requirements.pdf  -> manual engineering document
+expected/...             -> test_oracle, used_for_authority=false
+```
+
+## `QUESTIONS.md`
+
+Contains missing or ambiguous engineering facts that prevented deterministic promotion.
+
+Use it as an engineering punch list, update the original customer files, and rerun:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST
+```
+
+## `FAT_REPORT.html`
+
+Customer-readable verification report generated when a campaign can be built.
+
+A missing metric or unsupported requirement is not silently changed to PASS. It remains `NOT_TESTED` or otherwise blocks readiness.
+
+## `EVIDENCE.html`
+
+Read-only evidence view of requirement/Twin/artifact lineage.
+
+## `REPLAY.json`
+
+Written only when replay reconstruction succeeds and `--output` was supplied. It is a canonical replay manifest, not a new robot or simulator execution.
+
+---
+
+# Requirements and verdicts
+
+Supported deterministic structural/Twin checks include:
+
+```text
+planning_allowed
+physics_allowed
+entity_present
+validation_issue_absent
+twin_state
+```
+
+Measured physical checks include:
+
+```text
+cycle_time_max_s
+minimum_clearance_m
+final_tcp_error_max_m
+max_tracking_error_rad
+collision_free
+physical_completed
+```
+
+The verdict model is intentionally bounded:
+
+```text
+PASS
+FAIL
+NOT_TESTED
+```
+
+A requirement that needs measured physical evidence cannot PASS from prose, a CAD filename, or a generated verification plan.
+
+Example:
+
+```text
+Requirement: cycle time <= 8.0 s
+Measurement available: no
+Verdict: NOT_TESTED
+```
+
+When exact-Twin measured evidence exists:
+
+```text
+Requirement: cycle time <= 8.0 s
+Observed: 7.42 s
+Threshold: 8.0 s
+Verdict: PASS
+Evidence: exact measurement artifact + Twin revision/hash
+```
+
+---
+
+# XLSX, PDF, and expected-data policies
+
+## XLSX requirements
+
+Simple Mode supports conventional `requirements.xlsx` first-worksheet normalization.
+
+Common semantic columns include:
+
+```text
+requirement ID
+requirement text / description
+check / metric
+target / threshold
+expected value
+severity / criticality / priority
+```
+
+If multiple requirement sources are present and authority becomes ambiguous, DevAgent fails closed rather than silently merging them.
+
+## PDF documents
+
+PDFs are inventoried and fingerprinted for review.
+
+v1.3 does **not** silently OCR arbitrary safety PDFs and convert extracted prose into deterministic PASS evidence.
+
+A safety requirement without a supported deterministic check remains manual/`NOT_TESTED` until appropriate evidence exists.
+
+## `expected/` folders
+
+A root `expected/` folder is treated as test-fixture oracle data:
+
+```text
+expected/
+  -> inventoried
+  -> SHA-256 recorded
+  -> role = test_oracle
+  -> used_for_authority = false
+```
+
+This prevents a fixture from proving its own expected answer.
+
+---
+
+# Simple Mode exit codes
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | bounded verification is release-ready |
+| `10` | customer input or operational contract failure |
+| `30` | more engineering information is required |
+| `31` | simulation was requested but the exact execution path is blocked/unqualified |
+| `32` | verification completed but release readiness is still false |
+
+Non-zero engineering exits are intentional and machine-friendly.
+
+Example CI use:
+
+```bash
+devagent verify ./customer-project --json > devagent-result.json
+rc=$?
+
+case "$rc" in
+  0)  echo "bounded verification ready" ;;
+  30) echo "customer information required" ;;
+  31) echo "simulation path blocked" ;;
+  32) echo "verification complete but not release-ready" ;;
+  *)  echo "input or operational failure" ;;
+esac
+```
+
+---
+
+# When to use Simple Mode vs Expert Mode
+
+Use **Simple Mode** for the normal customer workflow:
+
+```bash
+devagent verify ./customer-project
+```
+
+Use **Expert Mode** when you need explicit control over:
+
+- project identity;
+- immutable Twin revisions;
+- explicit requirement artifacts;
+- measurement binding;
+- campaign artifact IDs;
+- regression baselines;
+- Evidence Bundle generation;
+- replay reconstruction;
+- external CI/orchestration;
+- qualification workflows.
+
+Installed CLIs:
+
+```text
+devagent             one-command customer verification
+devagent-commercial  expert commercial/evidence workflow
+devagent-physical    deterministic core + ROS/qualification tools
+devagent-physical-ai optional provider-backed engineering front end
+```
+
+---
+
+# Expert Mode example
+
+The default project/evidence database is:
+
+```text
+~/.devagent/projects.db
+```
+
+## 1. Create project identity
+
+```bash
+devagent-commercial init warehouse-cnc-04 \
+  --name "Warehouse CNC Loading Cell 04" \
+  --site atl-01 \
+  --workcell cnc-04
+```
+
+## 2. Import explicit customer Twin evidence
+
+```bash
+devagent-commercial import-twin warehouse-cnc-04 ./customer-cell \
+  | tee twin-import.json
+```
+
+List immutable revisions:
+
+```bash
+devagent-physical project \
+  --db ~/.devagent/projects.db \
+  revisions warehouse-cnc-04
+```
+
+Twin manifest example:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/devagent-twin.yaml
+
+Do not use template values as customer evidence.
+
+## 3. Load requirements
+
+```bash
+devagent-commercial requirements warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv
+```
+
+Example requirements file:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements-production.csv
+
+## 4. Generate verification plan
+
+```bash
+devagent-commercial verification-plan warehouse-cnc-04 \
+  examples/commercial/verification-plan.yaml \
+  --revision twin-r0001
+```
+
+Planning creates bounded test intent. It is not execution evidence.
+
+## 5. Record measured evidence
+
+```bash
+devagent-commercial record-measurement warehouse-cnc-04 \
+  physical-measurement.json \
+  --revision twin-r0001
+```
+
+Example schema:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/physical-measurement.json
+
+Preferred integrations use the typed `PhysicalEvidenceRecorder.record_motion_metrics(...)` path so measurement, canonical motion, planner/source graph, qualification reference, and Twin hash remain bound together.
+
+## 6. Run deterministic campaign
+
+```bash
+devagent-commercial campaign warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv \
+  --revision twin-r0001 \
+  --measurement ARTIFACT_ID
+```
+
+## 7. Generate FAT report
+
+```bash
+devagent-commercial fat-report warehouse-cnc-04 \
+  CAMPAIGN_ARTIFACT \
+  --output FAT_REPORT.html
+```
+
+## 8. Build Evidence Bundle
+
+```bash
+devagent-commercial evidence-bundle \
+  warehouse-cnc-04 \
+  CAMPAIGN_ARTIFACT
+```
+
+The bundle binds requirement results to exact artifact IDs, artifact hashes, Twin revision, and Twin hash.
+
+## 9. Inspect evidence graph
+
+```bash
+devagent-commercial evidence-graph warehouse-cnc-04 \
+  > evidence-graph.json
+```
+
+## 10. Generate static Evidence Viewer
+
+```bash
+devagent-commercial evidence-viewer warehouse-cnc-04 \
+  --output DEVAGENT_EVIDENCE.html
+```
+
+## 11. Replay persisted lineage
+
+Read-only inspection first:
+
+```bash
+devagent-commercial replay \
+  warehouse-cnc-04 \
+  EVIDENCE_BUNDLE \
+  --qualification-root ~/.devagent/physical-qualification \
+  --output replay-manifest.json
+```
+
+Optionally record immutable `replay_verification` evidence after a successful reconstruction:
+
+```bash
+devagent-commercial replay \
+  warehouse-cnc-04 \
+  EVIDENCE_BUNDLE \
+  --qualification-root ~/.devagent/physical-qualification \
+  --output replay-manifest.json \
+  --record
+```
+
+Replay verifies persisted identity before reconstruction:
+
+```text
+artifact ID
+artifact type
+artifact SHA-256
+Twin revision/hash
+run_id
+case_id
+case evidence hash
+seed
+reset state
+parameters
+canonical motion fingerprint
+```
+
+A successful replay inspection reports:
+
+```text
+replayable = true
+execution_performed = false
+```
+
+Replay reconstruction does not command Gazebo, MoveIt, a robot, PLC, or safety PLC.
+
+## 12. Change impact
+
+After importing a new Twin revision:
+
+```bash
+devagent-commercial impact warehouse-cnc-04 \
+  twin-r0001 twin-r0002 \
+  examples/commercial/requirements-production.csv
+```
+
+## 13. Regression
+
+```bash
+devagent-commercial regression warehouse-cnc-04 \
+  BASELINE_CAMPAIGN CURRENT_CAMPAIGN \
+  --impact CHANGE_IMPACT_ARTIFACT
+```
+
+A previous PASS does not remain authoritative after a changed Twin unless the required evidence chain remains valid for the new revision.
+
+## 14. Project status
+
+```bash
+devagent-commercial status warehouse-cnc-04
+```
+
+Inspect artifacts:
+
+```bash
+devagent-commercial artifacts warehouse-cnc-04
+```
+
+Useful artifact types include:
+
+```text
+customer_twin_import
+one_command_twin_normalization
+requirement_set
+verification_plan
+physical_measurement
+physical_motion_plan
+runtime_measurement_binding
+commercial_campaign
+change_impact
+commercial_regression
+fat_report
+evidence_bundle
+replay_verification
+```
+
+---
+
+# 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
+Universal Robots ROS 2 driver
+ur_simulation_gz
+MoveIt 2
+```
+
+Preview setup changes:
+
+```bash
+devagent-physical setup --profile ur5e-sim --dry-run
+```
+
+Apply explicitly:
+
+```bash
+devagent-physical setup --profile ur5e-sim --yes
+```
+
+Check runtime readiness:
+
+```bash
+devagent-physical ros doctor
+```
+
+Qualify trajectory runtime:
+
+```bash
+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 a graphical Gazebo runtime, MoveIt `move_group`, TF, controller actions, OEM drivers, or an arbitrary imported workcell. Physical qualification must run on the exact workstation/adapter stack.
+
+---
+
+# Optional AI providers
+
+AI is optional and remains outside deterministic authority.
+
+Install one provider:
+
+```bash
+python -m pip install "devagent-physical-engine[openai]"
+```
+
+```bash
+python -m pip install "devagent-physical-engine[anthropic]"
+```
+
+```bash
+python -m pip install "devagent-physical-engine[gemini]"
+```
+
+Or all provider SDKs:
+
+```bash
+python -m pip install "devagent-physical-engine[ai]"
+```
+
+Typical credentials:
+
+```bash
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+export GEMINI_API_KEY="..."
+```
+
+Check provider setup without using the provider as physical authority:
+
+```bash
+devagent-physical-ai doctor --provider openai
+```
+
+Example natural-language engineering request:
+
+```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
+```
+
+The model can help interpret and propose engineering intent. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.
+
+---
+
+# Evidence and authority model
+
+DevAgent deliberately separates four things that are often incorrectly mixed together:
+
+```text
+1. requirement
+2. test intent
+3. measured evidence
+4. authority/readiness
+```
+
+A verification plan proves only that a test was planned.
+
+A model-only result proves only the model-level property that was actually evaluated.
+
+A physical requirement requires physical measurement evidence.
+
+A replay reconstruction proves persisted evidence lineage can be reconstructed; it is not a new simulation run.
+
+A simulation PASS does not equal site commissioning.
+
+A complete customer FAT report does not equal functional-safety certification.
+
+Current hard boundary:
+
+```text
+physical_qualification = false unless separately qualified evidence says otherwise
+site_qualification = false
+real_execution_allowed = false
+```
+
+This architecture is intentional:
+
+```text
+Agents propose.
+Deterministic engines compile and verify.
+Existing certified controllers execute.
+```
+
+---
+
+# What DevAgent should be used for
+
+DevAgent is designed to help engineering teams:
+
+- reduce FAT preparation and verification effort;
+- discover missing engineering information before travel;
+- identify requirement failures before onsite commissioning;
+- create repeatable deterministic test plans;
+- bind physical measurements to exact Twin revisions;
+- detect regression after engineering changes;
+- preserve evidence provenance;
+- produce customer-readable FAT evidence;
+- reduce dependence on manual artifact bookkeeping;
+- make verification results inspectable rather than opaque.
+
+It is **not** a replacement for:
+
+- OEM robot controllers;
+- PLC logic authority;
+- safety PLCs;
+- certified safety functions;
+- site acceptance responsibility;
+- functional-safety engineering;
+- real-world commissioning judgment.
+
+---
+
+# Project status
+
+**v1.3.1 — Production/Stable software workflow**
+
+The bounded software/evidence workflow is production-oriented and continuously tested across Python 3.11, 3.12, and 3.13.
+
+The v1.3.1 patch release includes:
+
+```text
+one-command customer intake
+XLSX requirement normalization
+immutable project/Twin lineage
+deterministic verification campaigns
+measured evidence binding
+FAT generation
+professional Evidence Viewer report palette
+terminal stage-by-stage progress + RUN.log
+new-tab report handoff without intentionally raising over terminal
+copy/paste replay command after Evidence Bundle generation
+Evidence Bundle
+replay reconstruction
+change impact
+regression
+provider-neutral optional AI front end
+```
+
+Software quality gates include dedicated coverage thresholds for:
+
+```text
+One-Command customer workflow
+Production Authority
+Evidence Trust / Replay
+```
+
+Production/Stable describes the bounded software workflow. It does not claim arbitrary customer cells are physically or site qualified.
+
+---
+
+# 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
+
+Natural-language engineering:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/NATURAL_LANGUAGE_ENGINEERING.md
+
+AI providers:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AI_PROVIDERS.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
+
+Optimization:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/OPTIMIZATION.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 the complete ownership and usage terms.