Upload 2 files

CONTEXT_FOR_CLAUDE_ADSO.md

@@ -0,0 +1,1071 @@
+# CONTEXT FOR CLAUDE — ADSO FLOOR-PLAN AUTOMATION PROJECT
+
+## 1. PURPOSE
+
+This is a handoff/context document for a Claude session working on the existing
+floor-plan automation repository.
+
+The project is an automated floor-plan generation system. The repository already
+contains an upstream input-understanding pipeline and a downstream deterministic
+layout-generation pipeline.
+
+The current goal is to build a reliable system that can eventually generate and
+compare many valid, space-efficient floor layouts for customer-defined office
+requirements, while preserving exact geometry, clearances, boundaries, doors,
+pillars, and other architectural constraints.
+
+IMPORTANT:
+- Do not replace or redesign the existing upstream Normalize -> Perceive ->
+  SpaceModel stages.
+- The current implementation/testing covers a limited set of architectural and
+  product types, primarily private-room behavior, base kit, default configuration,
+  and some optional items.
+- More architectural types and product types will be added later by developers.
+- Do not invent new product standards or architectural rules from general LLM
+  knowledge.
+
+---
+
+# 2. ARCHITECTURE NAME
+
+## ADSO
+
+**Agentic Deterministic Spatial Optimization Architecture**
+
+Full name:
+
+> Agentic Deterministic Spatial Optimization Architecture for Automated
+> Floor-Plan Generation.
+
+Core principle:
+
+> The Agent decides WHAT to try; the deterministic system decides WHICH valid
+> alternatives to explore and EXACTLY WHERE they go.
+
+The LLM/Agent must never become the authority for final geometry, measurements,
+collision detection, clearance validation, boundary containment, or hard
+architectural validity.
+
+---
+
+# 3. FINAL TARGET ARCHITECTURE
+
+```text
+CUSTOMER REQUIREMENTS
+        |
+        v
+REQUIREMENT INTERPRETER
+(LLM / Agent)
+        |
+        v
+EXISTING INPUT UNDERSTANDING
+  Normalize
+  Perceive
+  SpaceModel
+        |
+        v
+REAL BUILDING / PLACEABLE FLOOR
+  walls
+  inner-face boundary
+  doors
+  windows
+  pillars / obstacles
+        |
+        v
+DESIGN-SPACE SEMANTICS
+  products
+  quantities
+  relationships
+  orientations
+  references
+  architectural rules
+        |
+        v
+DETERMINISTIC SEARCH / SOLVER
+  candidate generation
+  movement / orientation
+  office placement
+  alternatives
+  deduplication
+  ranking
+  future backtracking
+        |
+        v
+DECLARATIVE PLACEMENTS
+        |
+        v
+DETERMINISTIC RESOLVER
+        |
+        v
+EXACT INTEGER-MM GEOMETRY
+        |
+        v
+HARD VALIDATOR / GATE
+  shell boundary
+  collisions
+  pillars
+  doors / functional access
+  clearances
+  architectural rules
+        |
+        v
+SPATIAL QUALITY / OBJECTIVE
+  residual usability
+  route width
+  directness
+  enclosure efficiency
+  compactness
+  obstacle effects
+        |
+        v
+BEST VALID LAYOUT(S)
+        |
+        v
+VISION CRITIC
+        |
+        v
+LLM / AGENT REFINEMENT
+        |
+        +--------------------> iterate
+```
+
+---
+
+# 4. AUTHORITY BOUNDARIES
+
+## Normalize
+
+Existing upstream stage.
+
+Purpose:
+- clean/normalize input geometry
+- prepare reliable geometry for later processing
+
+Do not replace or redesign this stage in the current work.
+
+## Perceive
+
+Existing upstream stage.
+
+Purpose:
+- understand/detect walls, doors, windows, pillars, and other input entities
+
+Do not replace or redesign this stage in the current work.
+
+## SpaceModel
+
+Existing semantic representation of the input building.
+
+It represents and relates:
+- shell
+- walls
+- doors
+- windows
+- pillars
+- floor
+- references
+- semantic relationships
+
+## Customer Requirements
+
+Defines WHAT each office/tenant needs.
+
+A customer may request:
+- one office
+- several offices
+- different products/quantities per office
+- same products/quantities in multiple offices
+- different functional needs per office
+
+## LLM / Agent
+
+Responsible for:
+- interpreting requirements
+- high-level strategy
+- deciding what to try
+- interpreting failures
+- calling deterministic spatial tools
+- later explaining/rationalizing the selected result
+
+Must NOT:
+- calculate final coordinates
+- invent product standards
+- invent architectural clearance values
+- override the Gate
+- declare an invalid layout valid
+
+## Deterministic Search
+
+Responsible for:
+- candidate generation
+- product movement/orientation
+- room/office placement
+- alternative layouts
+- deduplication
+- ranking
+- future backtracking/global search
+
+## Resolver
+
+Responsible for:
+- resolving declared semantic placement/reference relationships
+- exact geometry
+- exact integer-mm coordinates
+
+R-3 established the resolver as the single geometry authority for the migrated
+private-office base-kit relationships.
+
+## Geometry / CAD Layer
+
+Responsible for exact geometric representation/output.
+
+## Gate
+
+The Gate is the SOLE BLOCKING PHYSICAL/ARCHITECTURAL VALIDATION AUTHORITY.
+
+It validates:
+- shell/inner-floor containment
+- collisions
+- pillars/obstacles
+- clearances
+- door functionality/access
+- reachability
+- minimum widths
+- architectural rules
+
+Do not duplicate Gate ownership in the objective or resolver.
+
+## Objective
+
+Ranks already-valid candidates.
+
+It must not create new hard constraints.
+
+---
+
+# 5. CORE USER REQUIREMENTS THE FINAL SYSTEM MUST SUPPORT
+
+## Single-office / single-tenant
+
+One customer brief can request one office.
+
+## Multi-office / multi-tenant
+
+Each office can have its own product set and quantities.
+
+Example:
+
+```text
+Office A:
+  table + owner chair + 2 visitors + pedestal
+
+Office B:
+  different products / quantities
+```
+
+Or:
+
+```text
+Office A:
+  2 desks + 4 chairs
+
+Office B:
+  2 desks + 4 chairs
+```
+
+Even if two offices have the same products and quantities, their geometry may
+still differ if the rules permit different valid arrangements.
+
+The global solver must eventually reason over the whole floor rather than
+permanently assigning an office to one computational region.
+
+---
+
+# 6. REAL FLOOR / INNER SHELL BOUNDARY
+
+The actual placeable floor is the whole usable floor bounded by the inner face
+of the building shell.
+
+IMPORTANT:
+- The inner face of the input shell is the real geometric limit.
+- Regions and seams are computational decomposition, NOT permanent architectural
+  boundaries.
+- A generated office may span region boundaries.
+- Future global search must use the whole placeable floor.
+
+Never let generated geometry cross the actual inner shell boundary.
+
+---
+
+# 7. DOOR FUNCTIONAL CONSTRAINTS
+
+Doors are not merely gaps.
+
+Door behavior must remain functional:
+- access
+- opening/swing
+- approach
+- clearance
+- relationship to furniture
+- relationship to pathways
+
+The owner-face migration proved why semantic information matters:
+a missing owner face could make `door_serves_visitor_end` pass vacuously.
+S3-1c corrected this.
+
+Never allow missing semantic information to silently disable a blocking rule.
+
+---
+
+# 8. PRODUCT VARIABILITY
+
+Products are not necessarily the same across customer requests.
+
+The final system must eventually support:
+- different product types
+- different quantities
+- optional items
+- orientation
+- movement
+- product relationships
+- legitimate grouping/separation where explicitly supported
+- future architectural/product types
+
+Current tests are intentionally limited to existing repository semantics,
+mainly private-room behavior, base kit, default configuration and optional
+items such as pedestal/waste_bin.
+
+Future developers will add more architectural types after the current limited
+system is stable.
+
+Do NOT invent product behavior just because geometry technically allows it.
+
+---
+
+# 9. EXACT MEASUREMENT / MILLIMETRE REQUIREMENT
+
+The system must preserve exact geometry and measurements.
+
+Target:
+- integer-mm geometry
+- exact gaps/clearances
+- exact orientation
+- exact product dimensions
+- exact boundary checks
+
+Important distinction:
+
+```text
+Search
+  -> chooses candidate position
+
+Resolver
+  -> calculates exact geometry
+
+Gate
+  -> validates exact geometry
+```
+
+Do NOT brute-force every coordinate at every 1 mm everywhere. That would cause
+combinatorial explosion.
+
+Instead, candidate values should be semantically legitimate, while the geometry
+itself remains exact.
+
+`Placement.along_mm` already supports exact signed movement along a reference.
+
+Example:
+
+```text
+table
+  |
+  | 150 mm perpendicular gap
+  v
+pedestal
+```
+
+Move the pedestal 300 mm along the table:
+- `along_mm = 300`
+- `offset_mm` remains 150
+- resolver recomputes exact X/Y
+- perpendicular table-to-pedestal gap remains exactly 150 mm
+
+---
+
+# 10. R-3 STATUS — RESOLVER MIGRATION COMPLETE
+
+Verified stages:
+
+```text
+S3-1a  side semantics                 PASS
+S3-1b  individual product instances  PASS
+S3-1c  owner face semantics           PASS
+S3-1d  orientation                    PASS
+S3-2   table / center migration       PASS
+S3-3   owner / behind migration       PASS
+S3-4   visitors / facing migration    PASS
+S3-5   beside-table migration         PASS
+S3-6   single geometry authority      PASS
+```
+
+Repeated verification showed:
+- 0.000 mm geometry differences
+- unchanged measurements
+- unchanged hard validation
+- unchanged frozen baselines
+- unchanged DXF drawn content
+
+Current ownership:
+- center/table -> resolver
+- behind/owner -> resolver
+- facing/visitors -> resolver
+- beside-table -> resolver
+- along_wall -> still search/placer responsibility
+- pathways -> current placer/build layer
+- enclosure -> current placer/build layer
+- Gate -> sole validation authority
+
+`ANY_WALL` remains search policy. The resolver resolves known references; it
+does not choose an arbitrary wall.
+
+---
+
+# 11. APPROVED PRODUCT / PLACEMENT SEMANTICS
+
+## beside_table
+
+Approved domain meaning:
+
+```text
+reference = table
+gap = item_side_gap_mm = 150 mm minimum
+alignment = centered on the table side
+additional beside items stack outward
+```
+
+Example:
+
+```text
+table -> 150 -> pedestal -> 150 -> waste_bin
+```
+
+No new clearance was invented.
+
+## along_mm
+
+`offset_mm`:
+- perpendicular distance from reference
+- remains non-negative under its current semantics
+
+`along_mm`:
+- signed displacement along reference face
+- independent from offset
+- geometric parameter
+- not a clearance
+
+## visitor count
+
+Count expands into individual producer placements:
+
+```text
+visitor#1
+visitor#2
+visitor#3
+```
+
+Resolver does NOT own count semantics.
+
+The row is centered with deterministic arithmetic derived from:
+- product width
+- existing `item_side_gap_mm`
+
+---
+
+# 12. V1 STATUS — KIT ENUMERATION COMPLETE
+
+V1 was implemented and VERIFIED.
+
+Purpose:
+- stop keeping only the first valid kit placement
+- expose already-supported kit alternatives
+- compare multiple valid placements
+
+V1 does:
+- kit-level enumeration only
+- existing face order
+- existing offset order
+- existing `fits()`
+- deterministic bounded enumeration
+- geometry/arrangement reporting
+
+V1 does NOT:
+- invent product alternatives
+- invent grouping
+- invent relations
+- add clearances
+- scan arbitrary 1 mm values
+- modify room-level search
+- modify multi-office global search
+
+V1 measured many fitting kit positions while the old system kept one.
+
+V1 feature flag:
+```yaml
+office:
+  candidate_enumeration: false
+```
+
+Flag OFF:
+- S0.5 = 0 differences
+- diversity = 0 differences
+- winner unchanged
+- DXF unchanged
+- measurements unchanged
+
+---
+
+# 13. VISUAL REPORT REQUIREMENT
+
+Visual reporting is now mandatory for layout-generation stages.
+
+Every future report should include rendered layouts in Markdown.
+
+Use:
+- same scale
+- same extents
+- same annotation scheme
+
+Show where relevant:
+- shell
+- actual inner-face boundary
+- walls
+- doors
+- windows
+- pillars
+- products
+- generated partitions
+- pathways
+- office labels
+- entrances
+- important dimensions
+
+Measurements displayed on images MUST come from deterministic geometry.
+Do not manually type approximate dimensions.
+
+Visual review is supplementary:
+- it can reveal awkward layouts, dead pockets, clustering, pathway issues, etc.
+- it cannot override deterministic geometry or Gate validation.
+
+---
+
+# 14. V1 FINDING THAT MOTIVATED V2
+
+V1 exposed multiple valid kit positions, but the current objective scored them
+identically.
+
+Thus:
+
+```text
+different valid geometry
+        |
+        v
+same score
+```
+
+Reason:
+the old objective could not "see" furniture placement inside a room.
+
+V2 exists to make the objective spatially aware.
+
+---
+
+# 15. V2 OBJECTIVE POLICY
+
+Approved decisions:
+
+## X1 — two-flag split
+
+Approved.
+
+```yaml
+office:
+  objective_v2: false
+```
+
+V2 first MEASURES new metrics at weight 0.
+Promoting weights is a separate explicit decision.
+
+## X2 — sequence
+
+Approved:
+
+```text
+C1 in-room residual
+    ->
+C2 route width
+    ->
+discrimination benchmark
+    ->
+C4 enclosure efficiency
+    ->
+C3 pathway directness
+C5 group compactness
+C6 obstacle cost
+    ->
+weight decisions later
+```
+
+## X3
+
+Preferred in-room circulation width is DEFERRED.
+
+Do not invent a preferred 1500 mm in-room rule.
+Do not reuse `min_common_corridor_mm = 1500` for in-room preference.
+
+## X4
+
+Approved:
+required functional clearance is NOT automatically dead/waste.
+
+Examples:
+- seat approach
+- occupant pull-back
+- circulation behind seating
+- storage access
+
+## X5
+
+Keep current `space_efficiency` weight during V2 measurement.
+Do not change it yet.
+
+---
+
+# 16. C1 STATUS
+
+C1 = in-room residual classification.
+
+C1 implemented:
+- room interior clipped to real usable floor
+- subtract furniture
+- subtract partitions
+- subtract door swing
+- classify remaining floor
+- reuse existing residual classes/settings
+- reachability seeded from room door gap
+- required functional clearance excluded from dead total
+- weight 0
+
+C1 implementation and zero-diff verification PASSED.
+
+However, C1's explicit STOP condition FAILED honestly.
+
+For four V1 candidates:
+- room residual interior same area
+- room residual connectivity same
+- `room_residual_quality = 1.0000` for all
+
+while `widest_mm` changed.
+
+Reason:
+rigid translation conserves leftover area and connectivity, so area/connectivity
+ratios remain identical.
+
+DO NOT patch C1.
+DO NOT add a shape term to C1.
+DO NOT change weights.
+
+C1 is complete/honest but insufficient alone.
+
+---
+
+# 17. CURRENT ACTIVE TASK — C2 ONLY
+
+## C2: in-room route-width measurement
+
+Purpose:
+- measure spatial quality C1 cannot distinguish
+- measure narrowest clear route width along reachable path from room door to
+  required destinations
+- reuse existing deterministic clearance/raster/reachability machinery
+
+Existing primitives to reuse where possible:
+- `check_in_room_circulation`
+- `clear_square_width`
+- clearance field
+- reachability/flood machinery
+
+C2 is a MEASUREMENT first.
+
+Do NOT:
+- create a new hard constraint
+- invent preferred 1500 mm in-room standard
+- reuse `min_common_corridor_mm = 1500`
+- change weights
+- tune metric merely to make candidates differ
+
+If normalization needs an unsupported threshold:
+- report raw width
+- weight stays 0
+- request domain decision later
+
+---
+
+# 18. C2 FIRST TEST
+
+Use the same four V1 kit positions that had:
+
+```text
+score = 0.6124
+room_residual_quality = 1.0000
+```
+
+C2 must determine whether route geometry differs.
+
+Use rendered layouts to verify numerical C2 measurement matches visible geometry.
+
+If C2 also produces exactly one value for all four candidates:
+STOP and report why.
+
+Do not force discrimination.
+
+---
+
+# 19. C2 CLEARANCE SEMANTICS
+
+Required functional clearances are not waste.
+
+Do not classify these as dead space merely because they are empty:
+- seat approach
+- pull-back
+- circulation behind seating
+- storage access
+
+C2 measures route width/access quality and must not penalize compliance.
+
+---
+
+# 20. C2 BOUNDARY / DOOR
+
+C2 must remain aware of:
+- actual inner-face floor boundary
+- room partitions
+- furniture
+- door gap
+- door functional zone
+- pillars/obstacles
+
+Reachability must start from the actual room door gap.
+
+Gate remains the sole blocking authority.
+
+C2 only measures quality.
+
+---
+
+# 21. C2 FEATURE FLAG
+
+Keep:
+
+```yaml
+office:
+  objective_v2: false
+```
+
+by default.
+
+When ON:
+- compute C1
+- compute C2
+- report both
+
+but:
+- C1 weight = 0
+- C2 weight = 0
+
+Therefore:
+- score unchanged
+- winner unchanged
+- baselines unchanged
+
+---
+
+# 22. C2 VERIFICATION REQUIREMENTS
+
+After implementing C2, run:
+
+1. C2 unit tests
+2. full suite
+3. S0.5
+4. diversity
+5. D4 probes
+6. recipe_replay
+7. dxf_roundtrip
+8. geometry_json
+9. artifact/audit verification
+10. discrimination benchmark
+11. rendered visual report
+
+Flag OFF:
+- S0.5 = 0 differences
+- diversity = 0 differences
+- winner unchanged
+- DXF unchanged
+- measurements unchanged
+
+Flag ON:
+- C1 reported
+- C2 reported
+- both weights remain 0
+- score unchanged
+- winner unchanged
+
+---
+
+# 23. PERMANENT VISUAL REPORT FOR C2+
+
+Every C2/V2/V3/V4/V5/V6 layout report must include dimensioned rendered layouts.
+
+For the four comparison candidates:
+- same scale
+- same extents
+- same annotations
+
+Show:
+- shell / inner boundary
+- room
+- furniture
+- door
+- pathway
+- relevant dimensions
+- C1 result
+- C2 result
+
+Measurements must come from deterministic geometry.
+
+If rendering cannot be generated:
+visual verification remains UNVERIFIED.
+
+---
+
+# 24. FUTURE ROADMAP
+
+```text
+Existing Normalize / Perceive / SpaceModel     EXISTING
+
+R-3 deterministic resolver migration            COMPLETE
+
+V1 kit enumeration                              COMPLETE
+
+V2 objective measurement                        CURRENT
+    C1 in-room residual                         COMPLETE, stop failed
+    C2 route width                              CURRENT TASK
+    discrimination benchmark                    later
+    C4/C3/C5/C6                                 later
+
+V3 legitimate internal product alternatives      later
+V4 irregular enclosure                          later
+V5 global multi-office optimization              later
+V6 pathway optimization                          later
+LLM/Agent orchestration                         later
+Vision refinement                               later
+```
+
+---
+
+# 25. FUTURE V3 / V4 / V5
+
+## V3 — legitimate internal design alternatives
+
+Only after product/domain standards are explicitly decided.
+
+Potential pending questions include:
+- owner_beside
+- opposite-side beside item
+- split visitor rows
+- optional-item alternative placement
+- daylight-driven orientation
+
+Never invent these from general LLM knowledge.
+
+## V4 — irregular enclosure
+
+Current enclosure is rectangular.
+
+Future:
+- rectilinear polygon / union of rectangles
+- derived from products
+- clearances
+- pathways
+- door access
+- clipped to usable floor
+- not clipped to a computational region
+
+## V5 — global multi-office
+
+Future:
+
+```text
+Customer requirements
+    |
+    +-- Office A brief
+    +-- Office B brief
+    +-- Office C brief
+          |
+          v
+per-office alternatives
+          |
+          v
+global combinations
+          |
+          v
+backtracking
+          |
+          v
+shared circulation
+          |
+          v
+whole-floor objective
+          |
+          v
+best valid complete floor
+```
+
+The system must not permanently trap offices inside one region.
+
+---
+
+# 26. FINAL TARGET BEHAVIOR
+
+Ultimately the system should:
+
+1. Understand the real input shell.
+2. Understand the actual inner floor boundary.
+3. Understand walls, doors, windows, pillars and constraints.
+4. Understand each customer-defined office/tenant brief.
+5. Generate multiple legitimate alternatives.
+6. Move/orient products using exact integer-mm geometry.
+7. Preserve all required dimensions and clearances.
+8. Track product movement.
+9. Respect inner-shell boundary.
+10. Respect functional door constraints.
+11. Validate every candidate deterministically.
+12. Measure usable and residual space.
+13. Compare candidate layouts.
+14. Optimize single-office and multi-office floors.
+15. Derive appropriate office enclosure.
+16. Generate sensible pathways.
+17. Later use Agent + Vision to guide/refine strategy.
+
+Ultimate objective:
+
+> Generate and compare many legitimate, buildable layouts and select the most
+> space-efficient one without sacrificing dimensional accuracy or violating
+> real architectural constraints.
+
+---
+
+# 27. NON-NEGOTIABLE PRINCIPLES
+
+1. Preserve Normalize -> Perceive -> SpaceModel.
+2. Customer requirements can differ per office.
+3. Products can differ across customer briefs.
+4. Product standards must not be invented.
+5. Geometry remains deterministic.
+6. Target geometry is integer-mm.
+7. Every movement/orientation needs a known geometric meaning.
+8. Actual inner shell face is the true boundary.
+9. Doors have functional constraints.
+10. Pillars and obstacles remain deterministic constraints.
+11. Gate is the sole blocking authority.
+12. Resolver is the geometry authority for migrated relationships.
+13. Search chooses alternatives; resolver calculates geometry.
+14. Objective ranks valid candidates; it does not validate them.
+15. Vision is supplementary.
+16. Visual reports are mandatory for layout-generation stages.
+17. Failed STOP conditions must be reported, not tuned away.
+18. Frozen baselines must not be refreshed to absorb changes.
+19. Regions/seams are not permanent architectural boundaries.
+20. Whole-floor optimization is the eventual multi-office goal.
+
+---
+
+# 28. CURRENT STOP POINT / INSTRUCTION
+
+CURRENT TASK:
+
+**Implement C2 only.**
+
+C1:
+- implemented
+- verified
+- STOP condition failed honestly
+- no patch approved
+
+V1:
+- verified and complete
+
+R-3:
+- verified and complete
+
+The current session MUST NOT automatically continue beyond C2.
+
+Immediate instruction:
+
+> C1 is approved as implemented, but its STOP condition failed as expected.
+>
+> Do NOT patch C1.
+> Do NOT add a shape term to C1.
+> Do NOT change weights.
+>
+> NEXT = C2 ONLY.
+>
+> Implement C2 as an in-room route-width measurement using existing deterministic
+> clearance/raster/reachability machinery.
+>
+> Do NOT invent a preferred 1500 mm in-room rule.
+> Do NOT reuse `min_common_corridor_mm = 1500`.
+> Do NOT create a new hard constraint.
+> Do NOT change weights.
+>
+> Test the same four V1 kit positions.
+>
+> C2 must determine whether route geometry differs.
+>
+> If C2 also produces exactly one value for all candidates:
+> STOP and report why.
+>
+> Required visual report:
+> - same scale
+> - same extents
+> - shell / inner boundary
+> - room
+> - furniture
+> - door
+> - pathway
+> - dimensions from deterministic geometry
+> - C1 result
+> - C2 result
+>
+> Keep:
+> `objective_v2 = false`
+>
+> C1 weight = 0
+> C2 weight = 0
+>
+> Run:
+> 1. C2 unit tests
+> 2. full suite
+> 3. S0.5
+> 4. diversity
+> 5. D4 probes
+> 6. recipe_replay
+> 7. dxf_roundtrip
+> 8. geometry_json
+> 9. artifact/audit verification
+> 10. discrimination benchmark
+> 11. rendered visual report
+>
+> Do NOT implement C3/C4/C5/C6, weight changes, V1b, V3, V4, V5, V6 or Agent
+> orchestration.
+>
+> STOP after C2 verification and report.

floorplan-core.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e034ac1938f2ed07312bf3e5adc594547fbb0427f59bd92dcf386fb953726137
+size 2024990