This page tracks the current state of the codebase audit, summarizes resolved issues, lists open issues by priority tier, documents proposal alignment gaps, and outlines future work. The canonical source for issue details is `CODEBASE_AUDIT.txt` in the repository root; this page provides a navigable overview with cross-references to the relevant wiki pages.
---
## Resolved Issues
The following issues have been fixed and archived to `archive/CODEBASE_AUDIT_RESOLVED.txt`. They are listed here for completeness.
These issues directly block the thesis evaluation and results sections.
| Issue | Description | Effort | Documented In |
|-------|-------------|--------|---------------|
| #55 | **Hardcoded scene -- no scenario variation.** Scene parameterization infrastructure exists (`SceneConfig`, presets, CLI flags) but no batch evaluation runner uses it. | Partially done | [Scene Environment](Scene_Environment) |
| #76 | **No evaluation framework (PA-1).** No success rate measurement, no planning time collection, no baselines, no experiment runner. The thesis cannot have a Results section without this. | ~1-2 weeks | See PA-1 below |
| #81 | **Missing recursive object discovery (PA-2).** The proposal claims free space partitioning will recursively discover new objects. The implementation is a single-pass octree. | ~2-3 days or document as future work | [Spatial Reasoning](Spatial_Reasoning) |
### Tier 3b -- Architectural
| Issue | Description | Effort | Documented In |
|-------|-------------|--------|---------------|
| #93 | **Actions are not generic -- hidden sub-actions in execution.**`sense` contains a hidden move; `pick` contains 3 hidden moves + 3 IK solves + gripper control + constraint weld; `place` same pattern. The planner cannot reason about these sub-actions. | ~1-2 weeks | [Design Decisions](Design_Decisions), [Execution Pipeline](Execution_Pipeline) |
### Tier 4 -- Deferrable
These are accepted simplifications or fidelity improvements.
| Issue | Description | Status | Documented In |
|-------|-------------|--------|---------------|
| #44 | Shadows not recomputed after occluder relocation -- stale registry. | Accepted. Raycasting by body ID compensates. | [Spatial Reasoning](Spatial_Reasoning) |
| #73 | `shadow_occluder_map` goes stale on replan. | Low impact. Derived predicates compensate. | [Planning System](Planning_System) |
| #59 | Objects fly away on first grasp -- constraint-based grasping. | Accepted. Friction grasping is a fidelity improvement, not correctness fix. | [Design Decisions](Design_Decisions) |
| #77 | Object dimensions exceed gripper capacity (0.15 m cubes vs 0.08 m max opening). | Blocks #59. Fix together if pursued. | [Design Decisions](Design_Decisions) |
### Tier 5 -- Dead Code Inventory
Documented and preserved per codebase policy. No action needed.
| Issue | Description | Lines |
|-------|-------------|-------|
| #87 | Dead methods/properties across codebase | ~160 lines |
| PA-6 | **Only top-down grasps.** No lateral or angled grasps. Limits evaluation scenarios. | Implicit | Known limitation | [Robot Control and Streams](Robot_Control_and_Streams) |
---
## Future Work
### Evaluation Framework (PA-1, #76)
The highest-priority missing component. Required deliverables:
-**Batch evaluation runner**: Execute the pipeline across multiple scene configurations with different random seeds.
-**Metric collection**: Success rate, planning time per plan, total plan cost (number of actions), number of replans.
-**Scene variation**: Use the existing `scalability_scene()` preset with varying `n_occluders` and `n_targets`.
-**Baselines**: At minimum, compare against uniform voxelization (fixed-resolution grid) and fixed semantic regions (hand-defined zones).
### Recursive Object Discovery (PA-2, #81)
The proposal describes a recursive process: after free-space partitioning, if new objects are found within a partition, the process repeats. Implementing this would require:
1. A perception step inside `FreeSpaceGenerator` to detect objects within free cells.
2. Re-running shadow calculation for newly detected objects.
3. Re-running free-space generation with the updated boxel set.
Alternatively, document this as an accepted simplification for the single-camera tabletop scenario where all objects are detected upfront.
### Friction-Based Grasping (#59, #77)
Replacing constraint-based grasping with friction-based grasping requires:
1. Resizing objects to fit in the Panda's 0.08 m gripper opening (#77).
2. Adjusting grasp Z offsets so fingers contact the object sides.
3. Setting appropriate `lateralFriction` on objects and gripper shapes.
4. Testing grip stability across different object shapes.
### Grasp Diversity (PA-6)
Extending `sample_grasp()` to produce lateral and angled grasps would enable handling scenes with:
- Objects near walls or edges.
- Stacked objects.
- Objects in narrow gaps.
### Incremental Boxel Recomputation
After relocating an occluder, only the affected shadows and free-space cells need recomputation. Currently the system uses a stale registry (#44). Incremental updates would improve accuracy without the cost of full recomputation.
### Action Decomposition (#93)
Decomposing pick/place into sub-actions in the PDDL domain (approach, grasp, lift as separate actions with their own streams) would allow the planner to:
- Optimize approach/retreat paths.
- Detect collisions on approach waypoints.
- Reason about post-action configurations.
The trade-off is 3x more stream evaluations and a more complex domain.
---
**See Also:**
-[Design Decisions](Design_Decisions) -- Rationale for the accepted deviations listed here.
-[Planning System](Planning_System) -- The replanning architecture that compensates for some of these limitations.
-[Scene Environment](Scene_Environment) -- Scene parameterization infrastructure (#55).
-[Architecture Overview](Architecture_Overview) -- Overall system structure.
