BOXES -- CURRENT SPECIFICATION ANALYSIS
Revision: 2026-10-10 (named boxes with symmetry pruning)
Status: Final. Specification complete for the agreed scope; optional search-advisor handoff ready.
Specification: ../../../probs/problem-boxes-advisor.lisp
Handoff: spec-analysis-search-handoff.txt
History: the counts/occupancy model and its full check record are preserved in
git (commit ec7b9ab and earlier). This file describes only the current named-box
revision.

1. AUTHORITY AND SCOPE

Requirements: problem-analysis.txt. Earlier working records (pre-spec
snapshot, analysis history, withdrawn draft, counts-model record) were
removed 2026-10-11 and remain in git history.

The specification was authored section by section with the user's review.
Comparison with the user's earlier probs/problem-boxes.lisp (from 2026-10-10)
reviews the spec advisor itself; findings that change the advisor are
recorded in doc/spec-advisor.md, not here.

2. CURRENT MODEL AND REQUIREMENT MAPPING

Objective: one globally shortest sequence of unit pickup, placement and
gate-crossing actions; tied optima need not all be returned. Walking within an
area is free and uncounted.

Given instance, preserved unchanged: agent1, box1 and box2, area1-area4,
plate1-plate3, gate1-gate3; agent1 and box1 start in area1, box2 in area2;
gate1 joins area1/area2, gate2 area1/area3, gate3 area3/area4; plate1 and plate2
are in area1, plate3 in area3; plateN controls gateN. Goal: (loc agent1 area4).

Changing state:
- (loc object $area): the agent's area and each box's area. A box on a plate
  keeps its area; a held box has no area.
- (holding agent $box): the box the agent holds, if any.
- (on $box $plate :bijective): which box is on which plate, looked up either way.
Gate openness is derived from its controlling plate's occupancy (GATE-OPEN?);
no gate state is stored.

Static facts: gate endpoints, plate areas, the one-to-one plate/gate wiring,
and two facts derived at initialization -- each area's plate list and each
area's gate list.

Requirement -> implementation:
- Empty hands to pick up; carry at most one -> PICKUP requires no HOLDING fact;
  PLACE requires one.
- Local handling only -> PICKUP requires the box in the agent's area; PLACE uses
  only the agent's area and that area's plates.
- Ground storage unlimited; plate holds one box -> ground placement always
  allowed; plate placement only when CLEARTOP?.
- Recovering a box from a plate closes its gate immediately -> PICKUP retracts ON;
  openness is always derived, never stored.
- Cross an open incident gate either way, carrying allowed -> CROSS-GATE iterates
  the area's gate list, tests GATE-OPEN?, and moves only the agent; a held box
  has no area, so it moves implicitly.
- Each transition is one unit action -> three actions of cost 1; each legal
  alternative is emitted by its own ASSERT.

3. REDUCTIONS (agreed in problem-analysis.txt)

- No stepping onto plates: the lone agent cannot use its own temporary gate
  opening, so plate visits are omitted from the search model.
- Interchangeable boxes: boxes keep their names, and engine symmetry pruning
  (ww-set *symmetry-pruning* t) merges arrangements that differ only by box
  names. Distinct area/plate allocations remain distinct. Solutions name
  actual boxes.
- No repeated arrangements: GRAPH search keeps the cheapest arrival at each
  complete arrangement.

4. ENHANCEMENTS FOR LARGER INSTANCES

- Combined actions: PLACE emits ground and every empty local plate as separate
  alternatives; CROSS-GATE emits every open local gate.
- Local lists: AREA-PLATES and AREA-GATES are built once by
  INITIALIZE-TOPOLOGY-INDEXES, so actions consider only local candidates.
- Remaining-steps bound: MIN-STEPS-REMAINING? is a placeholder computed by one
  query from facts already present: crossings still needed (0 in area4, 1 from
  an area next to it, otherwise 2), plus one placement, and one pickup if the
  agent's hands are empty, when every gate into area4 is closed. Sound because
  the final crossing needs an open gate into area4, which needs a box placed on
  its plate. Start-state value 4 (true optimum 10). The earlier all-open crossing-distance bound (an init action plus
  a plain-Lisp breadth-first helper) was removed 2026-10-10 as unmeasured
  complexity; designing a stronger bound is a search-advisor question. The goal
  area appears in both this query and DEFINE-GOAL; change both together.
- Symmetry pruning: on for this problem. Whether its overhead pays off on
  larger instances is untested and belongs to the search advisor.

5. EVIDENCE FOR THE CURRENT REVISION

- User-reported (2026-10-10): the current revision stages and finds the
  ten-action optimum, matching the independent witness and lower-bound
  deduction in problem-analysis.txt section 5.
- 2026-10-10 revision: lookups used only by the effect (the area's plate list in
  PLACE, gate list in CROSS-GATE) moved from the precondition into the effect,
  following the revised spec-advisor section 2.4. User-reported: stages without
  warnings and still returns the ten-action optimum.
- Settings in the file: planning, MIN-LENGTH, GRAPH, symmetry pruning on,
  depth cutoff 0, 16 threads.
- The topology indexes are unchanged in logic since their passing checks
  under the counts model; those checks (now deleted scripts) are historical
  and were not rerun on this revision.
- 2026-10-10: crossing-distance bound replaced by the one-query placeholder.
  User-reported: stages without warnings, start-state bound 4, ten-action
  optimum returned.
- User-reported staging output (2026-10-10): one symmetry family, BOX1/BOX2
  as interchangeable rows of type BOX; AGENT1 and AREA4 excluded as goal-
  referenced; global (closed-list) strategy. (The start-state bound of 2
  reported then came from the since-removed crossing-distance bound.)
- 2026-10-11: GATE-OPEN? simplified to look up the box on the gate's plate
  directly, replacing a negation of CLEARTOP?; same meaning. Restaging not
  yet reported.
- Not yet recorded for this revision: state/time counts and bound
  evaluation/prune counters.

6. LIMITATIONS AND NEXT STEP

- Performance on larger instances (symmetry overhead, bound benefit, graph
  memory, 16-thread benefit) is unmeasured; owner is the search advisor.
- Authored input assumes boxes start on the ground; a box starting on a plate
  or in hand needs its ON or HOLDING fact (and no LOC for a held box).
- Next: none for the spec advisor. Optional search-advisor work starts from
  spec-analysis-search-handoff.txt.
