devagent-physical-engine 0.11.6__tar.gz → 0.12.0__tar.gz

{devagent_physical_engine-0.11.6/src/devagent_physical_engine.egg-info → devagent_physical_engine-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devagent-physical-engine
-Version: 0.11.6
+Version: 0.12.0
 Summary: Verification-first agentic engineering, simulation, and evidence runtime for robotics and industrial automation.
 Author: Tom Ha
 License: All Rights Reserved
@@ -66,7 +66,7 @@ Core principles:
 - **Deterministic verification** — task graphs, motion contracts, collision constraints, scene state, and promotion gates are checked outside the model.
 - **Exact Twin binding** — physical motion is bound to a canonical Twin and immutable fingerprints rather than free-form model text.
 - **Measured simulation** — supported ROS 2 / Gazebo / MoveIt paths collect runtime evidence instead of treating a generated plan as proof.
-- **Fail-closed visualization** — DevAgent never substitutes a canned motion and labels it as the requested task.
+- **No fake task visualization** — generic demo motion is never labeled as the requested BOX/source/destination task.
 - **Real execution remains locked** — simulation success is not site qualification, functional-safety certification, or permission to run production hardware.
 
 ## Install
@@ -135,42 +135,77 @@ While the command runs, stage-by-stage progress is printed to `stderr` and the f
 ```text
 [DevAgent +   0.00s] START        provider=openai model=<model-id>
 [DevAgent +   0.00s] INTERPRETER  understanding engineering request
-[DevAgent +   6.84s] INTERPRETER  validated request_id=REQ-...
-[DevAgent +   6.84s] PLANNER      revision=0 generating high-level task graph
-[DevAgent +  12.21s] CRITIC       revision=0 reviewing verified plan
-[DevAgent +  15.77s] SIMULATION   running deterministic model execution
-[DevAgent +  15.78s] COMPLETE     ready_for_twin_simulation=true
+[DevAgent +   4.20s] PLANNER      revision=0 generating high-level task graph
+[DevAgent +  10.30s] CRITIC       revision=0 reviewing verified plan
+[DevAgent +  13.10s] SIMULATION   deterministic model execution completed
+[DevAgent +  13.11s] COMPLETE     ready_for_twin_simulation=true
 ```
 
 Use `--quiet` when a script or CI job needs JSON without terminal progress.
 
-## Visual simulation
+## Task-specific visual simulation
 
-There are two deliberately different visualization modes.
-
-To prove that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, use the explicit visual demo:
+For the supported v0.12 UR5e `load` scope, `--visualize` continues from the verified high-level task into a physical simulation path:
 
 ```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 <model-id> \
-  --visual-demo
+  --visualize
+```
+
+The current task-specific path uses the packaged `ur5e_reference_load_cell_v1` canonical workcell. The request identities remain exact (`BOX_101`, `conveyor_a`, `cnc_04`), while the reference source/destination poses, primitive geometry, nominal workpiece geometry, and reference tool are deterministic template facts rather than guessed customer-site facts.
+
+The runtime then performs this bounded sequence:
+
+```text
+validated AI task graph
+        |
+        v
+packaged canonical UR5e load Twin
+        |
+        v
+Gazebo + MoveIt world materialization and read-back
+        |
+        v
+MoveIt FK cross-check of reference pick/place targets
+        |
+        v
+MoveIt joint-space plan for each physical phase
+        |
+        v
+pre-pick -> pick -> attach BOX -> lift -> transfer -> place
+        |
+        v
+BOX visually follows tool0 while attached in Gazebo
+        |
+        v
+verified destination pose -> detach -> retract -> home
+        |
+        v
+measured motion/evidence report
 ```
 
-`--visual-demo` runs the packaged UR5e motion smoke through the ROS simulation stack. It is intentionally reported as `task_specific=false`; it proves the visualization/motion stack is working, not that the exact BOX task has been physically planned.
+On a successful run, Gazebo / MoveIt remains open by default so the engineer can inspect the final workcell. Add `--close-after` to close it after success.
+
+The packaged reference workcell is **not customer-site geometry**. Arbitrary plant layouts require an imported or user-declared physical Twin with trusted poses, collision geometry, tool/TCP information, and workpiece properties. DevAgent does not invent those site facts from a natural-language prompt.
 
-To request visualization of the **exact engineering task**, use:
+The v0.12 implementation remains evidence-gated: source/CI success does not prove the ROS target campaign has passed on a particular workstation. Use the executable qualification below before treating the task-specific path as qualified on that target.
+
+### Visual stack demo
+
+To test only that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, without claiming that motion represents the requested BOX task, use:
 
 ```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 <model-id> \
-  --visualize
+  --visual-demo
 ```
 
-Task-specific visualization fails closed until the runtime has enough physical evidence to construct the exact scene and compile an exact `PhysicalMotionPlan`. Required evidence includes robot/source/destination poses, collision geometry, workpiece geometry, tool/TCP information, and the compiled physical motion. DevAgent will not display an unrelated canned movement and call it the requested task.
+`--visual-demo` is explicitly reported as `task_specific=false`.
 
 ## How it works
 
@@ -192,13 +227,13 @@ VERIFIED HIGH-LEVEL TASK GRAPH
 CANONICAL PHYSICAL TWIN + IMMUTABLE HASH
                 |
                 v
-EXACT PHYSICAL MOTION CONTRACT
+MOVEIT-COMPILED PHYSICAL MOTION CONTRACTS
                 |
                 v
 GAZEBO / MOVEIT MATERIALIZATION + READ-BACK
                 |
                 v
-COLLISION / CLEARANCE / TOOL / WORKPIECE VERIFICATION
+COLLISION / TOOL / WORKPIECE VERIFICATION
                 |
                 v
 ROS 2 SIMULATION + MEASURED RUNTIME EVIDENCE
@@ -212,6 +247,8 @@ REAL HARDWARE AUTHORIZATION REMAINS SEPARATELY LOCKED
 
 The high-level AI task graph and the physical motion plan are not the same artifact. A `pick -> move -> place` graph is engineering intent. Gazebo execution requires a physically grounded Twin and compiled trajectory. This separation prevents an AI-generated task description from becoming an implicit motor command.
 
+For a nominal low-risk `load` simulation, the Critic remains advisory after deterministic compilation and verification. If it repeatedly requests subjective revisions but never rejects the plan, DevAgent may use a bounded deterministic advisory fallback after the revision budget is exhausted. A Critic `REJECT`, deterministic violation, higher-risk qualification/commissioning intent, fault injection, physical variation, or explicit engineering threshold still blocks that fallback.
+
 ## General architecture
 
 The architecture has three authority layers:
@@ -260,9 +297,9 @@ This plain-text diagram is intentionally used instead of Mermaid so the same REA
 
 The canonical Twin records robot identity, frames, source/destination entities, workpiece, tool, geometry, physics evidence, controller metadata, uncertainty, and provenance. Unknown physical information remains unknown rather than being filled with AI guesses.
 
-For production-candidate UR5e simulation, the stronger verifier can use MoveIt PlanningScene read-back, runtime-owned tool collision binding, runtime-owned workpiece attach/detach transitions, measured collision distance, conservative continuous-path clearance proof, measured joint states, and MoveIt FK evidence.
+The UR5e canonical adapter can bind one materialization to Gazebo and MoveIt, verify world/scene read-back, apply a runtime-owned tool collision object, verify workpiece attach/detach transitions, execute compiled joint trajectories, record joint states, and compute MoveIt FK metrics.
 
-A stronger pre-execution receipt requires evidence such as:
+The stronger production-candidate verifier can additionally use measured collision distance and conservative continuous-path clearance proof. A stronger pre-execution receipt requires evidence such as:
 
 ```text
 verified=true
@@ -284,7 +321,7 @@ The deterministic robot-profile layer includes abstractions for:
 - KUKA KR family
 - ABB IRB family
 
-Physical simulation and qualification are adapter- and vendor-specific. Current production-candidate physical-runtime work is centered on the UR5e ROS 2 / Gazebo / MoveIt path; a profile existing in the registry does not imply equivalent physical qualification for every vendor.
+Physical simulation and qualification are adapter- and vendor-specific. The v0.12 task-specific visible `load` runtime is UR5e-specific. A profile existing in the registry does not imply equivalent physical qualification for every vendor.
 
 ## ROS 2 / Gazebo reference target
 
@@ -310,7 +347,22 @@ devagent-physical ros demo
 devagent-physical ros qualify-trajectory-runtime
 ```
 
-For the stronger production-candidate target campaign:
+Run the v0.12 task-specific target qualification:
+
+```bash
+python -m devagent_physical_engine.ros2.qualification_v12
+```
+
+This must visibly execute the reference task and produce a passing report before the target workstation's v0.12 task-specific ROS simulation is considered qualified. It still intentionally reports:
+
+```text
+physical_qualification=false
+commissioning_qualification=false
+site_qualification=false
+real_execution_allowed=false
+```
+
+For the stronger continuous-clearance production-candidate campaign:
 
 ```bash
 python -m devagent_physical_engine.ros2.qualification_v11 \
@@ -340,6 +392,8 @@ Provider qualification uses API credits and verifies the bounded Interpreter / P
 
 Repository CI verifies Python 3.11, 3.12, and 3.13, Ruff correctness, branch coverage, package build, clean wheel installation, and runtime dependency vulnerability audit.
 
+ROS/Gazebo/MoveIt executable orchestration is separately target-qualified because hosted Python CI cannot truthfully exercise a graphical Gazebo process, MoveIt `move_group`, TF, ROS controllers, and Gazebo services. Pure reference-workcell contracts and deterministic planning logic remain covered by normal unit/coverage gates.
+
 A green `main` release is tied to the exact CI-tested commit. Release artifacts are rebuilt and verified from the exact tag, checked with Twine, installed into a clean environment, accompanied by SHA256 checksums and an SBOM, attached to the GitHub Release, and published to PyPI through Trusted Publishing.
 
 ## Documentation
@@ -362,9 +416,9 @@ Detailed engineering documentation lives in the repository:
 
 ## Project status
 
-**v0.11.6 — Beta software / evidence-gated physical runtime.**
+**v0.12.0 — Beta software / evidence-gated task-specific physical simulation.**
 
-The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The UR5e physical simulation path remains experimental until its exact target-stack qualification campaign passes. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
+The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The new UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
 
 ## Ownership
 

{devagent_physical_engine-0.11.6 → devagent_physical_engine-0.12.0}/README.md

@@ -25,7 +25,7 @@ Core principles:
 - **Deterministic verification** — task graphs, motion contracts, collision constraints, scene state, and promotion gates are checked outside the model.
 - **Exact Twin binding** — physical motion is bound to a canonical Twin and immutable fingerprints rather than free-form model text.
 - **Measured simulation** — supported ROS 2 / Gazebo / MoveIt paths collect runtime evidence instead of treating a generated plan as proof.
-- **Fail-closed visualization** — DevAgent never substitutes a canned motion and labels it as the requested task.
+- **No fake task visualization** — generic demo motion is never labeled as the requested BOX/source/destination task.
 - **Real execution remains locked** — simulation success is not site qualification, functional-safety certification, or permission to run production hardware.
 
 ## Install
@@ -94,42 +94,77 @@ While the command runs, stage-by-stage progress is printed to `stderr` and the f
 ```text
 [DevAgent +   0.00s] START        provider=openai model=<model-id>
 [DevAgent +   0.00s] INTERPRETER  understanding engineering request
-[DevAgent +   6.84s] INTERPRETER  validated request_id=REQ-...
-[DevAgent +   6.84s] PLANNER      revision=0 generating high-level task graph
-[DevAgent +  12.21s] CRITIC       revision=0 reviewing verified plan
-[DevAgent +  15.77s] SIMULATION   running deterministic model execution
-[DevAgent +  15.78s] COMPLETE     ready_for_twin_simulation=true
+[DevAgent +   4.20s] PLANNER      revision=0 generating high-level task graph
+[DevAgent +  10.30s] CRITIC       revision=0 reviewing verified plan
+[DevAgent +  13.10s] SIMULATION   deterministic model execution completed
+[DevAgent +  13.11s] COMPLETE     ready_for_twin_simulation=true
 ```
 
 Use `--quiet` when a script or CI job needs JSON without terminal progress.
 
-## Visual simulation
+## Task-specific visual simulation
 
-There are two deliberately different visualization modes.
-
-To prove that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, use the explicit visual demo:
+For the supported v0.12 UR5e `load` scope, `--visualize` continues from the verified high-level task into a physical simulation path:
 
 ```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 <model-id> \
-  --visual-demo
+  --visualize
+```
+
+The current task-specific path uses the packaged `ur5e_reference_load_cell_v1` canonical workcell. The request identities remain exact (`BOX_101`, `conveyor_a`, `cnc_04`), while the reference source/destination poses, primitive geometry, nominal workpiece geometry, and reference tool are deterministic template facts rather than guessed customer-site facts.
+
+The runtime then performs this bounded sequence:
+
+```text
+validated AI task graph
+        |
+        v
+packaged canonical UR5e load Twin
+        |
+        v
+Gazebo + MoveIt world materialization and read-back
+        |
+        v
+MoveIt FK cross-check of reference pick/place targets
+        |
+        v
+MoveIt joint-space plan for each physical phase
+        |
+        v
+pre-pick -> pick -> attach BOX -> lift -> transfer -> place
+        |
+        v
+BOX visually follows tool0 while attached in Gazebo
+        |
+        v
+verified destination pose -> detach -> retract -> home
+        |
+        v
+measured motion/evidence report
 ```
 
-`--visual-demo` runs the packaged UR5e motion smoke through the ROS simulation stack. It is intentionally reported as `task_specific=false`; it proves the visualization/motion stack is working, not that the exact BOX task has been physically planned.
+On a successful run, Gazebo / MoveIt remains open by default so the engineer can inspect the final workcell. Add `--close-after` to close it after success.
+
+The packaged reference workcell is **not customer-site geometry**. Arbitrary plant layouts require an imported or user-declared physical Twin with trusted poses, collision geometry, tool/TCP information, and workpiece properties. DevAgent does not invent those site facts from a natural-language prompt.
 
-To request visualization of the **exact engineering task**, use:
+The v0.12 implementation remains evidence-gated: source/CI success does not prove the ROS target campaign has passed on a particular workstation. Use the executable qualification below before treating the task-specific path as qualified on that target.
+
+### Visual stack demo
+
+To test only that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, without claiming that motion represents the requested BOX task, use:
 
 ```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 <model-id> \
-  --visualize
+  --visual-demo
 ```
 
-Task-specific visualization fails closed until the runtime has enough physical evidence to construct the exact scene and compile an exact `PhysicalMotionPlan`. Required evidence includes robot/source/destination poses, collision geometry, workpiece geometry, tool/TCP information, and the compiled physical motion. DevAgent will not display an unrelated canned movement and call it the requested task.
+`--visual-demo` is explicitly reported as `task_specific=false`.
 
 ## How it works
 
@@ -151,13 +186,13 @@ VERIFIED HIGH-LEVEL TASK GRAPH
 CANONICAL PHYSICAL TWIN + IMMUTABLE HASH
                 |
                 v
-EXACT PHYSICAL MOTION CONTRACT
+MOVEIT-COMPILED PHYSICAL MOTION CONTRACTS
                 |
                 v
 GAZEBO / MOVEIT MATERIALIZATION + READ-BACK
                 |
                 v
-COLLISION / CLEARANCE / TOOL / WORKPIECE VERIFICATION
+COLLISION / TOOL / WORKPIECE VERIFICATION
                 |
                 v
 ROS 2 SIMULATION + MEASURED RUNTIME EVIDENCE
@@ -171,6 +206,8 @@ REAL HARDWARE AUTHORIZATION REMAINS SEPARATELY LOCKED
 
 The high-level AI task graph and the physical motion plan are not the same artifact. A `pick -> move -> place` graph is engineering intent. Gazebo execution requires a physically grounded Twin and compiled trajectory. This separation prevents an AI-generated task description from becoming an implicit motor command.
 
+For a nominal low-risk `load` simulation, the Critic remains advisory after deterministic compilation and verification. If it repeatedly requests subjective revisions but never rejects the plan, DevAgent may use a bounded deterministic advisory fallback after the revision budget is exhausted. A Critic `REJECT`, deterministic violation, higher-risk qualification/commissioning intent, fault injection, physical variation, or explicit engineering threshold still blocks that fallback.
+
 ## General architecture
 
 The architecture has three authority layers:
@@ -219,9 +256,9 @@ This plain-text diagram is intentionally used instead of Mermaid so the same REA
 
 The canonical Twin records robot identity, frames, source/destination entities, workpiece, tool, geometry, physics evidence, controller metadata, uncertainty, and provenance. Unknown physical information remains unknown rather than being filled with AI guesses.
 
-For production-candidate UR5e simulation, the stronger verifier can use MoveIt PlanningScene read-back, runtime-owned tool collision binding, runtime-owned workpiece attach/detach transitions, measured collision distance, conservative continuous-path clearance proof, measured joint states, and MoveIt FK evidence.
+The UR5e canonical adapter can bind one materialization to Gazebo and MoveIt, verify world/scene read-back, apply a runtime-owned tool collision object, verify workpiece attach/detach transitions, execute compiled joint trajectories, record joint states, and compute MoveIt FK metrics.
 
-A stronger pre-execution receipt requires evidence such as:
+The stronger production-candidate verifier can additionally use measured collision distance and conservative continuous-path clearance proof. A stronger pre-execution receipt requires evidence such as:
 
 ```text
 verified=true
@@ -243,7 +280,7 @@ The deterministic robot-profile layer includes abstractions for:
 - KUKA KR family
 - ABB IRB family
 
-Physical simulation and qualification are adapter- and vendor-specific. Current production-candidate physical-runtime work is centered on the UR5e ROS 2 / Gazebo / MoveIt path; a profile existing in the registry does not imply equivalent physical qualification for every vendor.
+Physical simulation and qualification are adapter- and vendor-specific. The v0.12 task-specific visible `load` runtime is UR5e-specific. A profile existing in the registry does not imply equivalent physical qualification for every vendor.
 
 ## ROS 2 / Gazebo reference target
 
@@ -269,7 +306,22 @@ devagent-physical ros demo
 devagent-physical ros qualify-trajectory-runtime
 ```
 
-For the stronger production-candidate target campaign:
+Run the v0.12 task-specific target qualification:
+
+```bash
+python -m devagent_physical_engine.ros2.qualification_v12
+```
+
+This must visibly execute the reference task and produce a passing report before the target workstation's v0.12 task-specific ROS simulation is considered qualified. It still intentionally reports:
+
+```text
+physical_qualification=false
+commissioning_qualification=false
+site_qualification=false
+real_execution_allowed=false
+```
+
+For the stronger continuous-clearance production-candidate campaign:
 
 ```bash
 python -m devagent_physical_engine.ros2.qualification_v11 \
@@ -299,6 +351,8 @@ Provider qualification uses API credits and verifies the bounded Interpreter / P
 
 Repository CI verifies Python 3.11, 3.12, and 3.13, Ruff correctness, branch coverage, package build, clean wheel installation, and runtime dependency vulnerability audit.
 
+ROS/Gazebo/MoveIt executable orchestration is separately target-qualified because hosted Python CI cannot truthfully exercise a graphical Gazebo process, MoveIt `move_group`, TF, ROS controllers, and Gazebo services. Pure reference-workcell contracts and deterministic planning logic remain covered by normal unit/coverage gates.
+
 A green `main` release is tied to the exact CI-tested commit. Release artifacts are rebuilt and verified from the exact tag, checked with Twine, installed into a clean environment, accompanied by SHA256 checksums and an SBOM, attached to the GitHub Release, and published to PyPI through Trusted Publishing.
 
 ## Documentation
@@ -321,9 +375,9 @@ Detailed engineering documentation lives in the repository:
 
 ## Project status
 
-**v0.11.6 — Beta software / evidence-gated physical runtime.**
+**v0.12.0 — Beta software / evidence-gated task-specific physical simulation.**
 
-The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The UR5e physical simulation path remains experimental until its exact target-stack qualification campaign passes. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
+The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The new UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.
 
 ## Ownership
 

{devagent_physical_engine-0.11.6 → devagent_physical_engine-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devagent-physical-engine"
-version = "0.11.6"
+version = "0.12.0"
 description = "Verification-first agentic engineering, simulation, and evidence runtime for robotics and industrial automation."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
@@ -57,14 +57,22 @@ where = ["src"]
 branch = true
 source = ["devagent_physical_engine"]
 omit = [
-  # ROS probe scripts and target-stack orchestration require a real ROS/Jazzy/
-  # Gazebo/MoveIt environment. They are qualified by qualification_v11 rather than
-  # pretending hosted unit execution covers them.
+  # ROS probes and executable target-stack orchestration require a real ROS/Jazzy/
+  # Gazebo/MoveIt environment. v0.12 task-specific runtime code is qualified by the
+  # executable qualification_v12 campaign rather than pretending hosted unit CI can
+  # exercise a graphical simulator, move_group, TF, controller actions, or gz services.
+  # Pure contracts/reference-workcell logic remains inside the hosted coverage gate.
   "src/devagent_physical_engine/ros2/*_probe.py",
   "src/devagent_physical_engine/ros2/qualification*.py",
   "src/devagent_physical_engine/ros2/joint_state_recorder.py",
   "src/devagent_physical_engine/ros2/ur5e_adapter.py",
   "src/devagent_physical_engine/ros2/ur5e_v10_adapter.py",
+  "src/devagent_physical_engine/ros2/task_*.py",
+  "src/devagent_physical_engine/ros2/moveit_task_planner.py",
+  "src/devagent_physical_engine/ros2/fk_pose.py",
+  "src/devagent_physical_engine/ros2/gazebo_pose.py",
+  "src/devagent_physical_engine/ros2/workpiece_follow.py",
+  "src/devagent_physical_engine/ros2/workpiece_gazebo_follower.py",
 ]
 
 [tool.coverage.report]

{devagent_physical_engine-0.11.6 → devagent_physical_engine-0.12.0}/src/devagent_physical_engine/__init__.py

@@ -41,4 +41,4 @@ __all__ = [
     "TwinValidator",
 ]
 
-__version__ = "0.11.6"
+__version__ = "0.12.0"

{devagent_physical_engine-0.11.6 → devagent_physical_engine-0.12.0}/src/devagent_physical_engine/agent/coordinator.py

@@ -23,10 +23,18 @@ class VerifiedPlanArtifact:
     planner_evidence: tuple[AgentEvidence, ...]
     critic_evidence: tuple[AgentEvidence, ...]
     revision_rounds: int
+    acceptance_basis: str = "critic_accept"
 
 
 class PlanningCoordinator:
-    """Planner/critic loop with bounded revisions and deterministic plan proof."""
+    """Planner/critic loop with bounded revisions and deterministic plan proof.
+
+    The critic is advisory. A caller may explicitly allow a deterministic fallback for
+    a bounded low-risk simulation scope. That fallback is never used after REJECT and
+    never replaces deterministic graph verification; it only prevents subjective
+    critic scoring from randomly blocking a graph that the deterministic compiler and
+    verifier already proved structurally/safely admissible for that scope.
+    """
 
     def __init__(
         self,
@@ -55,10 +63,13 @@ class PlanningCoordinator:
         *,
         engineering_context: Mapping[str, Any] | None = None,
         progress: ProgressCallback | None = None,
+        allow_deterministic_advisory_fallback: bool = False,
     ) -> VerifiedPlanArtifact:
         feedback: tuple[str, ...] = ()
         planner_evidence: list[AgentEvidence] = []
         critic_evidence: list[AgentEvidence] = []
+        last_graph: TaskGraph | None = None
+        last_revision = 0
 
         for revision in range(self.max_revision_rounds + 1):
             if progress is not None:
@@ -75,6 +86,8 @@ class PlanningCoordinator:
                 engineering_context=engineering_context,
             )
             planner_evidence.append(planned.evidence)
+            last_graph = planned.graph
+            last_revision = revision
             if progress is not None:
                 progress(
                     "PLANNER",
@@ -118,6 +131,7 @@ class PlanningCoordinator:
                     planner_evidence=tuple(planner_evidence),
                     critic_evidence=tuple(critic_evidence),
                     revision_rounds=revision,
+                    acceptance_basis="critic_accept",
                 )
 
             if reviewed.critique.decision is CriticDecision.REJECT:
@@ -142,6 +156,21 @@ class PlanningCoordinator:
                     f"revision={revision} requires another planning round",
                 )
 
+        if allow_deterministic_advisory_fallback and last_graph is not None:
+            if progress is not None:
+                progress(
+                    "PLANNING",
+                    "advisory revision budget exhausted; accepting deterministic-valid low-risk simulation plan",
+                )
+            return VerifiedPlanArtifact(
+                graph=last_graph,
+                graph_hash=task_graph_hash(last_graph),
+                planner_evidence=tuple(planner_evidence),
+                critic_evidence=tuple(critic_evidence),
+                revision_rounds=last_revision,
+                acceptance_basis="deterministic_low_risk_advisory_fallback",
+            )
+
         if progress is not None:
             progress("PLANNING", "revision budget exhausted")
         raise PlanningCoordinationError("revision_budget_exhausted")