Add scene candidates and measured Task Program execution

agent_context/MAP.yaml

@@ -201,6 +201,22 @@ topics:
     tests/sim/motion/planners/, tests/compute/]
   related_topics: [simulation-system, robot-system, ik-solvers, atomic-actions]
   status: active
+- id: scene-expansion
+  title: Scene Expansion
+  aliases: [scene expansion, scene augmentation, scene variant, 场景扩增, 场景变体]
+  keywords: [SceneExpansionCfg, ScenePoseChange, SceneVariant, FixedSceneCandidateSource,
+    ScenePreparationResult, SceneVariantEpisodeResult, execute_scene_variant]
+  paths: [topics/scene-expansion/scene-expansion.md]
+  source_of_truth:
+  - embodichain/lab/sim/scene_expansion/
+  - embodichain/lab/task_program/integrations/scene_expansion.py
+  - embodichain/lab/gym/envs/embodied_env.py
+  - embodichain/lab/gym/envs/demo.py
+  watch_paths: [embodichain/lab/sim/scene_expansion/,
+    embodichain/lab/task_program/integrations/scene_expansion.py,
+    tests/sim/scene_expansion/, tests/gym/envs/task_program/test_scene_expansion.py]
+  related_topics: [simulation-system, task-programs, robot-workspace, motion-planning, gen-sim, data-pipeline]
+  status: active
 - id: rl-learning
   title: RL Learning Pipeline
   aliases: [rl learning, rl config, reinforcement learning, 强化学习, 训练配置]

agent_context/topics/motion-planning/motion-planning.md

@@ -77,6 +77,10 @@ encode prepared actions rather than retiming a second time.
 
 ## Trajectory augmentation boundary
 
+Scene layout proposals and their Task Program execution adapter belong to
+[scene expansion](../scene-expansion/scene-expansion.md). The trajectory
+contracts below operate within a specified scene and initial state.
+
 `motion/expansion/` owns callable-free Expansion Profiles, immutable templates
 and candidates, sampled limit checks and coverage. `load_expansion_profile()`
 strictly decodes the task-local resource, separate from environment

agent_context/topics/robot-workspace/robot-workspace.md

@@ -4,6 +4,10 @@ Workspace analysis caches kinematic reachability; runtime sampling reuses cached
 joint configurations with the current robot base. This does not establish
 collision-free motion, grasp validity or task success.
 
+[Scene expansion](../scene-expansion/scene-expansion.md) owns scene proposals
+and the Task Program attempt boundary. Workspace results alone do not supply
+physical preparation or acceptance of those proposals.
+
 ## Entry points
 
 Paths below are relative to `embodichain/lab/sim/` unless qualified.

agent_context/topics/scene-expansion/scene-expansion.md

@@ -0,0 +1,90 @@
+# Scene expansion
+
+Scene expansion proposes changes before a new Task Program execution. The core
+is independent of Task Program, GenSim and Gym; injected host callbacks own the
+actual scene preparation and measured task evidence.
+
+## Entry points
+
+| Request | Owner |
+|---|---|
+| Shared proposal contracts and fixed source | `embodichain/lab/sim/scene_expansion/` |
+| Candidate limits and movable entity permissions | `scene_expansion/cfg.py` in that package |
+| Arena poses and proposal identity | `scene_expansion/contracts.py` in that package |
+| One Task Program attempt and result metadata | `embodichain/lab/task_program/integrations/scene_expansion.py` |
+| Reset-time persistence eligibility | `embodichain/lab/gym/envs/embodied_env.py` |
+| Action consumption and recording lifecycle | `embodichain/lab/gym/envs/demo.py` |
+
+## Resolution and ownership
+
+```text
+SceneExpansionCfg + authored pose changes
+  -> FixedSceneCandidateSource -> SceneVariant
+  -> injected prepare_scene -> ScenePreparationResult
+  -> canonical Task Program bridge -> execute_demo_episode -> env.step
+  -> measured_validator -> SceneVariantEpisodeResult
+  -> caller-owned reset commit/discard
+```
+
+`FixedSceneCandidateSource` snapshots only its budgeted prefix and owns no
+execution lifecycle. Core contracts describe changes to existing physical
+entities, not a replacement SceneGraph or runtime registry. Current execution
+is B=1 and requires a Task Program; explicit canonical bridge creation prevents
+legacy segment overrides from changing the selected source.
+
+The preparation callback is responsible for restore/application, physical
+settling, actual initial-state checks, saved-state identity, binding refresh and
+recording observation refresh. Generic execution does not provide those
+physical operations. The measured callback supplies task-specific state and
+event evidence. Gym remains the owner of reset, stepping and recording; no new
+generation session or persistence writer is introduced.
+
+The attempt guard spans preparation, execution and measurement. It suppresses
+automatic reset and blocks persistence during explicit callback resets, even
+when those resets replace episode annotations. Rejected recording buffers must
+be discarded by reset before retrying; beginning another demo or replacing its
+metadata does not create a clean recording boundary.
+
+## Invariants
+
+- A changed pose is a proper 4x4 entity-to-local-arena Z-up transform, excluding
+  replication offsets. Numeric inputs become immutable tuples.
+- Proposal identity includes parent scene, seed, ordinal, geometry and
+  provenance. It is independent of physical slots and distinct from actual
+  settled initial-state and execution-attempt identities.
+- Only declared movable entity UIDs may change. Candidate and metadata
+  containers are owned; duplicate entity IDs and invalid configuration fail
+  explicitly rather than becoming ordinary geometric rejections.
+- Initial checks, program completion and measured acceptance remain separate.
+  Program success requires normal completion and the acceptance mask of the
+  selected canonical bridge, alongside successful demo execution. Generic Gym
+  success cannot replace that evidence. Empty or unavailable required checks
+  cannot accept data; projected effects do not replace physical evidence.
+- Failed or unverified recordings block reset-time dataset, camera and
+  trajectory saves, including explicit commit rows. Rejection stays attached
+  to the buffers until reset discards them; a successful retry without reset
+  cannot make those buffers eligible. Acceptance is not a persistence receipt.
+
+Use [robot workspace](../robot-workspace/robot-workspace.md) for reachability
+cache and frame contracts, [motion planning](../motion-planning/motion-planning.md)
+for trajectories/collision worlds, and [Task Programs](../task-programs/task-programs.md)
+for compilation, live grounding and runtime evidence. Those capabilities do
+not by themselves provide scene restoration or certify a new layout.
+
+## Change sites and validation
+
+Keep layout/proposal algorithms under `lab/sim/scene_expansion`; put
+task-specific adaptation under Task Program integrations. Keep GenSim scene
+materialization in its own backend instead of introducing imports into the
+core. Extend the host boundary when adding physical preparation, and
+preserve Gym lifecycle ownership.
+
+```bash
+pytest -q tests/sim/scene_expansion
+pytest -q tests/gym/envs/task_program/test_scene_expansion.py
+python docs/scripts/check_api_docs.py
+```
+
+The focused tests exercise immutable geometry and identities, bounded source
+consumption, real demo dispatch and reset-time recording gates using CPU ports.
+They do not establish physical success across robot models or scene layouts.

agent_context/topics/task-programs/task-programs.md

@@ -91,6 +91,7 @@ not by Task Program or Gym.
 - [Language and semantic integration](configuration.md): strict decoding, scene/profile contracts, component ownership and service allowlists.
 - [Assurance and execution](execution.md): measured/projected effects, acceptance, parallel calls and MLLM boundaries.
 - [Dataset persistence](../data-pipeline/data-pipeline.md): recorder commits, fragments, failures and finalization.
+- [Scene expansion](../scene-expansion/scene-expansion.md): fixed scene proposals, injected preparation, independent measured acceptance and reset-time persistence gates.
 
 ## Reference integrations
 

docs/architecture/README.md

@@ -12,6 +12,7 @@ Local and CI Sphinx builds regenerate their own version-specific assets.
 - [Original Task Program sample](task-program.sample.json): unchanged historical contract example.
 - [Earlier frontend snapshot](preview.snapshot.json): retained as a reference, no longer consumed by the app.
 - [GenSim / TaskSpec design](gen-sim-taskspec-design.md): current implementation status, ownership boundaries, and staged target architecture.
+- [Task Program scene expansion design](task-program-scene-expansion-design.md): workspace integration, shared expert generation workflow, and three-developer implementation plan.
 
 `agent_context/MAP.yaml` remains the sole topic inventory. Groups are presentation
 choices. Neither import declarations nor adjacency establish runtime order. Every
@@ -20,10 +21,10 @@ ownership. This is selected static coverage, not a complete dependency graph.
 The generated text reference lists topics without represented nodes and overview
 nodes without mapped relationships, using MAP at the snapshot revision. Neither
 a represented topic nor a missing edge establishes complete coverage or independence.
-The current snapshot represents all 18 MAP topics and all 10 top-level production
-packages. Frontend data tests enforce these entry-point checks and ensure every
-selected node appears in a view. Specialist modules are included in the searchable
-text reference even when omitted from the overview.
+The current snapshot represents every MAP topic and top-level production package
+at its pinned source revision. Frontend data tests enforce these entry-point
+checks and ensure every selected node appears in a view. Specialist modules are
+included in the searchable text reference even when omitted from the overview.
 
 ## Generate and validate