Imported from Cayman-Wang/3d_trajectory_recovery (AGENTS.md). Install upstream with npx skills add Cayman-Wang/3d_trajectory_recovery. Copyright stays with the author.

/Home/atr2/wym/mmm2027_3d_trajectory_recovery Agent Rules

Scope and Safety

• All file-changing work for this workspace must stay within /Home/atr2/wym/mmm2027_3d_trajectory_recovery after resolving paths, unless a task explicitly names another path under /Home/atr2/wym.
• Do not modify files, Git state, permissions, configuration, environments, or artifacts in the frozen legacy repository at /Home/atr2/wym/trajectory_recovery_3dv_mmm_paper. It is a read-only historical source.
• Do not use sudo or make system-wide changes.
• Paper manuscripts (Markdown/LaTeX/PDF and drafts) are maintained only in the local paper workspace and must not be written to this server project.

Current Status (read before planning)

• candidate1 (1303-frame Alien): early development and exploration evidence; its raw 59 GB capture does not enter the formal paper pipeline.
• calibration route 1915 (Alien): parameter calibration and same-route post-selection diagnostics completed; oracle v1/v2 (1 deg), 45-episode T3 state semantics, degradation matrix and T5 attempt2 evidence archived under evidence/.
• test route: formal 2554-frame capture, clean and blackout-10 analysis completed (data/test_route_2554/, evidence/test_route_2554/).
• Alien is the formal recovery experiment model; F-15 is fully deprecated and removed from code/config/launchers/tests.
• DJI-01 / DJI-02: assets and pose-lock validation passed; no full trajectory capture/recovery experiment yet.
• All five readiness fields (tracklet_bbox_depth_ready, final_4d_geometry_ready, benchmark_ready, formal_mask_gt_ready, actor_to_pixel_binding_proven) and condition4 remain unchanged from the legacy project (currently not advanced by migration).
• T5 valid authoritative result: t5_attempt2_w16_cpu_only (65 tasks, 390 seed rows, 78 aggregate rows, 30 clean-equivalence checks passed; five seeds are the same-route perturbation repeats).
• Frozen test-route protocol: 1 deg min ray angle, 32 px reprojection threshold, 128 RANSAC iterations, >= 2 physical cameras, seeds 20260808-20260812, max 2 predicted frames, 3rd missing frame breaks the segment.

Defensive Code Policy

• Do not overuse defensive code or duplicate validation.
• Before adding any new defensive mechanism, obtain the project owner's explicit prior approval. This includes runtime guards; input validation; hard-coded SHA256, size, path, or row-count locks; manifest checks; fail-closed branches; fallbacks; and extra readiness or freeze gates.
• No category is exempt from this approval requirement.
• This rule does not authorize removing or weakening existing controls. Any such change also requires explicit project-owner approval.

Path Conventions

• Use the environment roots PROJECT_ROOT, CONFIG_ROOT, DATA_ROOT, ASSET_ROOT, EVIDENCE_ROOT, OUTPUT_ROOT, ARTIFACT_ROOT exported by bin/project_env.sh instead of hard-coded absolute paths.
• src/mmm2027_3d_trajectory_recovery/paths.py resolves project-relative paths under PROJECT_ROOT by default; do not add new path locks.
• bin/paper_env.sh is a compatibility forwarder only; new entries source bin/project_env.sh.
• Machine-local overrides (interpreters, external runtimes) live in the untracked environment/local.env; no paper_server.env or external re-ID / DGGT / MapAnything dependencies.

Subagent Use

• Prefer subagents for clearly split read-only search, document reading, provenance checks, cross-file checks, narrow validation, and isolated local verification.
• When multiple agents are used, assign explicit, non-overlapping file ownership.
• Every delegated task must state its goal, allowed paths, stop condition, and expected output.
• The main agent owns final design choices, diff review, validation decisions, and final reporting.

Model Selection

• Explorer-style search, document, provenance, and narrow validation tasks: prefer gpt-5.6-luna with low reasoning when available; otherwise use gpt-5.6-terra with low.
• Worker-style bounded implementation and tests: prefer gpt-5.6-terra with low or medium reasoning, with an explicit isolated ownership boundary.
• Reserve the main agent model for overall planning, cross-module tradeoffs, final integration, critical review, or explicit user request.
• If a preferred model is unavailable, use the lowest-cost available replacement that fits the task and state the actual replacement model in the final report.