Merge pull request #1 from ChanMeng666/feat/physical-correctness-circulation

feat: physical-correctness & circulation pass (Claude × Codex, ADR 0006)

Author: ChanMeng666

AGENTS.md

@@ -100,8 +100,11 @@ usage), and source can come from stdin (`-`). Beyond `compile`/`watch`/`fmt`/`ex
 `arch spec` (print the whole language — `spec.llm.md`), `arch describe` (semantic JSON: rooms,
 areas, adjacency, door connections — backed by `describe()` in `src/describe.ts`), `arch lint`
 (architectural soundness `W_*` warnings — `src/lint.ts`), `arch validate` (parse+resolve+lint, no
-render), and `arch new` (scaffold). `describe`/`lint` share the pure analysis layer in
-`src/analyze.ts`; all are exported from `src/index.ts`. This is the standard interface for AI agents
+render; `--strict`/`--fail-on-warning` makes warnings fail too — the pipeline ship-gate), `arch new`
+(scaffold), and `arch repair` (the explicit opt-in source-to-source corrector — pushes furniture out
+of walls and emits new `.arch` + a change log; `src/repair.ts`, see ADR 0006). `describe`/`lint` share
+the pure analysis layer in `src/analyze.ts` (+ `src/analyze/occupancy.ts`, the circulation
+flood-fill); all are exported from `src/index.ts`. This is the standard interface for AI agents
 — there is intentionally no MCP server (see the README's agent section).
 
 ## Architecture & Conventions

CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — physical-correctness & circulation (Claude × Codex adversarial pass)
+
+A second Claude Code × Codex review (prompted by AI-generated plans that rendered with furniture
+through walls, fixtures piled in doorways, and rooms with no door) hardened the renderer and the
+soundness layer, **without** turning `compile()` into an arranger. See the new
+[ADR 0006](docs/adr/0006-solver-as-explicit-transform.md): a solver may exist only as an explicit
+source-to-source transform, never as invisible render behavior.
+
+- **Render fidelity:** `dims auto walls` annotates each distinct wall thickness once (deduped); the
+  new mode is also included in `dims auto all`. Per-room dimensions (`dims auto rooms`) now sit in the
+  page margin on the side each room faces, instead of overlapping the room label/area inside the room.
+- **New lint rules (advisory, deterministic facts — ADR 0005-compliant):**
+  `W_FURNITURE_WALL_COLLISION` (a piece drawn through a wall solid, via AABB intrusion over
+  `segmentRectangle`, opening-aware), `W_DOORWAY_BLOCKED` (furniture in a door's clear landing — the
+  walk-through path, distinct from the swing arc), and `W_ROOM_NO_CLEAR_PATH` (a grid flood-fill in
+  `analyze/occupancy.ts` finds a room whose doorways can't reach a usable patch of floor). New ruleset
+  knobs `doorwayLandingMm` and `minClearAreaM2`; the accessibility profile tightens the landing depth.
+- **Strict gating:** `arch validate --strict` (alias `--fail-on-warning`) makes advisory warnings
+  fail too (exit `2`) — the gate a generation pipeline runs so it can't ship a plan lint flagged. The
+  agent contract (`SKILL.md`, `spec.llm.md`) now mandates this gate and an explicit furniture-placement
+  discipline (back fixtures to walls with `against wall`, keep every room reachable, keep doorways
+  clear).
+- **Catalogued footprints:** a known fixture placed `against wall` may omit `size` and take its
+  conventional footprint from `fixtures-catalog.ts` (closed-form, never a guess).
+- **`arch repair`:** a new opt-in, source-to-source corrector. It pushes furniture out of walls and
+  emits **new `.arch` source plus a change log** (never an invisible edit); ambiguous, scripted, or
+  `against wall` pieces are reported, not guessed. Exported as `repair()` from the public API.
+- **eval:** the offline harness now fails any golden that has a physical-correctness violation (the
+  three new codes), guarding authorability regressions.
+
+### Fixed
+
+- The formatter (`arch fmt`) silently dropped the `dims auto` directive; it is now preserved.
+
 ## [1.3.2] - 2026-06-28
 
 ### Changed — docs site & playground brought up to v1.3 (no compiler changes)

SKILL.md

@@ -33,10 +33,34 @@ npx @chanmeng666/archlang help
 5. **Verify intent without an image:** `arch describe plan.arch --json` returns the rooms (with
    areas and adjacency), what each door connects, and totals. Confirm the room count, labels, and
    areas match what was asked.
-6. **Check soundness:** `arch lint plan.arch --json` flags habitability problems: a room with no
-   door, a windowless bedroom, an implausibly small room, a too-narrow door, no entrance, a bathroom
-   reachable only through a bedroom, a bathroom not fully walled in, a door whose swing hits furniture
-   or another door, and a bath/kitchen with no fixtures. Fix the warnings or tell the user about them.
+6. **Gate on soundness — don't ship a flagged plan.** Run `arch validate plan.arch --strict --json`
+   (parse + resolve + lint in one pass). `--strict` makes **every advisory warning fail** too
+   (exit `2`), so this is the gate a generation pipeline runs before it ships. If not `ok`, read each
+   `diagnostics[].fix`, edit the source, and re-run until it passes — or, if a warning is a deliberate
+   choice, tell the user explicitly. The lint flags: a room with no door, a windowless bedroom, an
+   implausibly small room, a too-narrow door, no entrance, a bathroom reachable only through a bedroom,
+   a bathroom not fully walled in, a door whose swing hits furniture/another door, a bath/kitchen with
+   no fixtures, **furniture drawn through a wall (`W_FURNITURE_WALL_COLLISION`)**, **a fixture blocking
+   a doorway (`W_DOORWAY_BLOCKED`)**, and **a room packed so you can't step in
+   (`W_ROOM_NO_CLEAR_PATH`)**.
+
+## Placement discipline (write it right the first time)
+
+A geometry-blind generator that emits absolute coordinates and ignores lint produces plans that
+render but are physically wrong (furniture through walls, fixtures piled in doorways, rooms with no
+door). Avoid that by construction:
+
+- **Every room needs a way in.** Put a `door` or a cased `opening` on a wall of *every* room — an
+  open-plan space still needs a modeled opening to the space it connects to, or it reads as sealed.
+- **Back plumbing/kitchen fixtures onto a wall with `against wall <id>`, not raw `at`.** `against wall`
+  is closed-form and fails loudly if ambiguous, so the fixture lands flush against the real wall face
+  instead of floating or penetrating. Use `in <roomId>` so the side is inferred.
+- **Keep furniture inside the room and out of the walls.** A piece's whole footprint must sit within
+  the room rectangle; never let it cross a wall centerline (that's `W_FURNITURE_WALL_COLLISION`).
+- **Leave the doorway clear.** Keep furniture out of the straight approach on both sides of every door
+  (≥300 mm), and out of the leaf's swing arc — so a person can actually walk in.
+- **Verify, then gate.** `arch describe --json` to confirm the intent (rooms, areas, access graph),
+  then `arch validate --strict --json` to prove it's sound before you ship.
 
 ## Commands
 
@@ -46,8 +70,9 @@ arch compile plan.arch -o out.svg --json   # render (also -f dxf|pdf|png)
 echo '<source>' | arch compile - -o - -f svg   # compile stdin → SVG on stdout
 arch describe plan.arch --json         # semantic facts: rooms, areas, adjacency, door connections
 arch lint plan.arch --json             # architectural soundness warnings
-arch validate plan.arch --json         # parse + resolve + lint, no render (fast check)
+arch validate plan.arch --strict --json   # parse + resolve + lint; --strict fails on warnings too (the ship gate)
 arch fmt plan.arch --write             # canonical formatting
+arch repair plan.arch -o fixed.arch    # emit corrected source (furniture pushed out of walls) + change log
 arch new -o plan.arch                  # scaffold a starter plan
 arch explain E_ROOM_SIZE --json        # look up any diagnostic code
 ```
@@ -60,7 +85,9 @@ arch explain E_ROOM_SIZE --json        # look up any diagnostic code
 - **Fixtures draw real symbols:** `furniture wc|basin|shower|bathtub|kitchen_sink|counter|fridge|stove …`
   renders a plan symbol (not an empty box); standard sizes are also in `lib/fixtures.arch`. Put fixtures
   in every bath and kitchen so the plan reads professionally and lint stays quiet.
-- **`dims auto`** draws dimension strings for you (`overall`, `rooms`, or `all`) — no need to place each `dim`.
+- **`dims auto`** draws dimension strings for you (`overall`, `rooms`, `walls`, or `all`) — no need to
+  place each `dim`. `rooms` puts each room's size in the margin (clear of the label); `walls` annotates
+  each distinct wall thickness once.
 - Edit is cheap: "make the bedroom 1 m wider" is a one-number change, then recompile.
 
 Treat the CLI as the source of truth — author, render, and verify through it rather than reasoning

docs/adr/0006-solver-as-explicit-transform.md

@@ -0,0 +1,77 @@
+# 6. A solver is an explicit source transform, never invisible render behavior
+
+- **Status:** Accepted
+- **Date:** 2026-06 (v1.4 planning)
+
+## Context
+
+[ADR 0005](0005-no-invisible-architect.md) drew the line that `compile()` renders facts
+and `lint` advises, but neither *arranges*. A second adversarial review (Claude Code ×
+Codex), prompted by AI-generated plans that rendered with furniture penetrating walls,
+fixtures piled in doorways, and rooms with no door, re-opened the obvious question:
+
+> Building games (The Sims, Project Highrise) never let a player drag a sofa through a
+> wall. Why can't ArchLang borrow those algorithms so AI-authored plans are automatically
+> physically correct and circulation-sound?
+
+The review found the failing plans were mostly an **integration failure**, not a missing
+solver: ArchLang's lint *already* flagged the unreachable rooms, floating fixtures, and
+obstructed door swings — the upstream generator ignored every warning and shipped anyway.
+But it also exposed a real risk: the natural "fix" is to let the compiler nudge the sofa
+out of the wall. That is the ADR 0005 temptation again, now wearing a physics costume.
+
+The key clarification: **the boundary is not "deterministic vs non-deterministic."** A
+deterministic routine that moves a sofa, picks a wall, or reroutes circulation is *still
+designing* — it can be pure and byte-stable and still break the promise that source
+coordinates mean exactly what they say. The real line is **faithful rendering vs choosing
+intent.**
+
+## Decision
+
+Amend ADR 0005 with one clause:
+
+> **A constraint-solver / arranger may exist in ArchLang only as an explicit, opt-in
+> command whose output is new `.arch` source plus a change log. It may never run inside
+> `compile()`, and it may never alter render output for a given source.**
+
+Concretely:
+
+- **`compile()` stays faithful.** When furniture overlaps a wall or a fixture blocks a
+  door, the renderer draws exactly what was authored. It does **not** clip, snap, or
+  relax — doing so would silently hide an authoring error. Catching the problem is
+  `lint`'s job (`W_FURNITURE_WALL_COLLISION`, `W_DOORWAY_BLOCKED`, `W_ROOM_NO_CLEAR_PATH`).
+- **Closed-form, unambiguous placement remains core-legal** (as ADR 0005 already allows):
+  `against wall <id>`, relational room placement — every target explicit, fail-fast on
+  ambiguity, no search.
+- **Any *corrective* arranging is a source-to-source transform.** A future `arch repair`
+  reads a `.arch`, emits a *new, inspectable* `.arch` plus a per-move change log
+  explaining what it did and why, and refuses (with a diagnostic) anything it cannot
+  resolve unambiguously. The author reviews the diff; nothing happens invisibly.
+
+| Where it belongs | Example |
+|------------------|---------|
+| `compile()` | render the authored plan, faithfully; **never** auto-correct |
+| `lint` (advisory facts) | AABB furniture-vs-wall collision; door-landing clearance; grid flood-fill circulation reachability |
+| explicit transform (`arch repair`, agent loop) | move a fixture to its nearest legal wall; nudge furniture out of a wall; emit new source |
+
+This also settles which "game algorithms" map where. **AABB collision** and **grid
+flood-fill / navmesh reachability** are legitimate *fact* computations and live in
+`analyze`/`lint`. **Force-directed relaxation, simulated annealing, and rectangle
+packing** are policy-heavy arrangers; they are out of scope for `compile()` and belong
+only behind the explicit-transform seam, if ever.
+
+## Consequences
+
+**Pros.** `compile()` keeps its zero-surprise, byte-stable guarantee even as physical-
+correctness intelligence grows. Every correction is reviewable source, never hidden
+behavior. The new lint rules give an AI author a strong enough signal to converge on a
+sound plan on its own (especially under `arch validate --strict`).
+
+**Cons.** A physically broken plan still renders broken (with loud warnings) until
+someone — the agent, `arch repair`, or a human — fixes the source. ArchLang remains a
+compiler with a separate, opt-in corrector, not a forgiving drag-and-drop design tool.
+We accept that: it is the same trade ADR 0004 and 0005 already made, extended to physics
+and circulation.
+
+This ADR governs the v1.4+ roadmap (furniture-vs-wall and doorway-clearance lint, the
+circulation flood-fill, `arch validate --strict`, and the `arch repair` transform).

docs/error-codes.md

@@ -5,7 +5,7 @@
 Every diagnostic carries a stable code. Look one up with `arch explain <CODE>`
 (e.g. `arch explain E_ROOM_SIZE`). Errors abort rendering; warnings do not.
 
-**34 errors** · **24 warnings**
+**34 errors** · **27 warnings**
 
 | Code | Severity | Summary |
 | --- | --- | --- |
@@ -47,15 +47,18 @@ Every diagnostic carries a stable code. Look one up with `arch explain <CODE>`
 | [`W_BEDROOM_NO_WINDOW`](#w_bedroom_no_window) | warning | Bedroom has no window. |
 | [`W_DOOR_CLEARANCE`](#w_door_clearance) | warning | Door is narrower than the minimum clear width. |
 | [`W_DOOR_OFF_WALL`](#w_door_off_wall) | warning | Door does not lie on any wall. |
+| [`W_DOORWAY_BLOCKED`](#w_doorway_blocked) | warning | A doorway's landing is blocked. |
 | [`W_EMPTY_PLAN`](#w_empty_plan) | warning | Empty plan. |
 | [`W_FIXTURE_FLOATING`](#w_fixture_floating) | warning | A plumbing/kitchen fixture is not against a wall. |
 | [`W_FIXTURE_WRONG_ROOM`](#w_fixture_wrong_room) | warning | Fixture sits outside its declared room. |
 | [`W_FURN_CLEARANCE`](#w_furn_clearance) | warning | A fixture's use-space is blocked. |
 | [`W_FURNITURE_OVERLAP`](#w_furniture_overlap) | warning | Two pieces of furniture overlap. |
+| [`W_FURNITURE_WALL_COLLISION`](#w_furniture_wall_collision) | warning | Furniture penetrates a wall. |
 | [`W_HATCH_SCALE`](#w_hatch_scale) | warning | Hatch scale must be positive; using 1. |
 | [`W_NO_ENTRANCE`](#w_no_entrance) | warning | The plan has no exterior door. |
 | [`W_OPENING_OFF_WALL`](#w_opening_off_wall) | warning | Opening does not lie on any wall. |
 | [`W_ROOM_DISCONNECTED`](#w_room_disconnected) | warning | Room has no door — it can't be entered. |
+| [`W_ROOM_NO_CLEAR_PATH`](#w_room_no_clear_path) | warning | A room cannot be entered or crossed. |
 | [`W_ROOM_NO_FIXTURE`](#w_room_no_fixture) | warning | Bathroom or kitchen has no fixtures. |
 | [`W_ROOM_NOT_ENCLOSED`](#w_room_not_enclosed) | warning | Bathroom is not fully enclosed. |
 | [`W_ROOM_OVERLAP`](#w_room_overlap) | warning | Rooms overlap. |
@@ -530,6 +533,19 @@ door at (0,0) width 500 wall exterior   # lint: under 700 mm
 door at (9999,9999) width 900   # warning: not on a wall
 ```
 
+## W_DOORWAY_BLOCKED
+
+*warning* — A doorway's landing is blocked.
+
+**Cause.** A piece of furniture/fixture sits in the clear landing space immediately on either side of a door opening, so you cannot pass through the doorway even when the leaf is open. This is the approach path, distinct from the leaf's swing arc (`W_SWING_OBSTRUCTED`).
+
+**Fix.** Clear the space directly in front of and behind the door, or move the door.
+
+```arch
+door at (6000,3000) width 800
+furniture wc at (5800,3050) size 700x400   # lint: WC blocks the doorway
+```
+
 ## W_EMPTY_PLAN
 
 *warning* — Empty plan.
@@ -592,6 +608,18 @@ furniture sofa at (300,300) size 2000x900
 furniture bed  at (1000,500) size 1500x2000   # lint: overlaps the sofa
 ```
 
+## W_FURNITURE_WALL_COLLISION
+
+*warning* — Furniture penetrates a wall.
+
+**Cause.** A furniture/fixture rectangle intrudes into a wall's solid (it crosses the wall's thickness band rather than sitting flush against its face), so it would physically pass through the wall — a coordinate or size mistake. A piece merely touching the wall face is fine.
+
+**Fix.** Move or resize the piece so it sits fully inside the room (against the wall face, not through it), or anchor it with `against wall <id>`.
+
+```arch
+furniture sofa at (350,2300) size 2000x900   # lint: crosses the partition at y3000
+```
+
 ## W_HATCH_SCALE
 
 *warning* — Hatch scale must be positive; using 1.
@@ -640,6 +668,18 @@ opening at (9999,9999) width 1000   # warning: not on a wall
 room id=r at (0,0) size 3000x3000   # lint: no door on its perimeter
 ```
 
+## W_ROOM_NO_CLEAR_PATH
+
+*warning* — A room cannot be entered or crossed.
+
+**Cause.** Furniture, fixtures, door swings and their clearances fill the room so densely that a person stepping through a door/opening has no clear floor path into the usable space — the room is technically reachable but physically blocked.
+
+**Fix.** Open up the layout: move or shrink the furniture nearest the door so there is a continuous walkable strip from each entrance into the room.
+
+```arch
+furniture shower at (5000,3000) size 2000x2000   # lint: fills the bathroom against its only door
+```
+
 ## W_ROOM_NO_FIXTURE
 
 *warning* — Bathroom or kitchen has no fixtures.

docs/language-reference.md

@@ -49,7 +49,7 @@ plan "My Home" {
 | `grid <n>` | Snap module in mm. All coordinates round to the nearest multiple. `0` disables. | `0` |
 | `scale 1:50` | Printed scale, shown in the title block. | none |
 | `north up\|down\|left\|right\|<deg>` | North direction for the north arrow. | `up` |
-| `dims auto [overall\|rooms\|all]` | Auto-draw dimension strings without hand-placing each `dim`: `overall` (the bounding extents), `rooms` (each room's width + height), or `all` (both; the default when no scope is given). | off |
+| `dims auto [overall\|rooms\|walls\|all]` | Auto-draw dimension strings without hand-placing each `dim`: `overall` (the bounding extents), `rooms` (each room's width + height, placed in the page margin on the side the room faces), `walls` (one deduped thickness call-out per distinct wall thickness), or `all` (all three; the default when no scope is given). | off |
 
 ## Values & expressions
 
@@ -374,7 +374,7 @@ opening id=o_living at (4000,3700) width 900 wall partition   # living ↔ hall,
 
 ```
 furniture <kind> [id=<id>] at (x,y) size <w>x<h> [label "<text>"] [rotate 0|90|180|270] [in <room>]
-furniture <kind> [id=<id>] against wall <ref> [segment <n>] [offset <mm>] [side left|right] size <along>x<depth> [label "<text>"] [in <room>]
+furniture <kind> [id=<id>] against wall <ref> [segment <n>] [offset <mm>] [side left|right] [size <along>x<depth>] [label "<text>"] [in <room>]
 ```
 
 A schematic labelled rectangle (bed, sofa, desk…). Known plumbing & kitchen
@@ -385,8 +385,10 @@ labelled rectangle.
 
 A piece can be placed two ways: absolutely with `at (x,y)` (optionally turned with
 `rotate`), or snapped **`against wall <ref>`** so its back sits on the wall and its
-rotation is derived for you. `in <room>` records which room owns the piece (used by
-the lint rules). The full placement rules, the fixture symbol catalogue, and the
+rotation is derived for you. A known fixture placed `against wall` may **omit `size`**
+to take its catalogued footprint (e.g. `furniture wc against wall w1 in bath`); `at`
+placement and uncatalogued kinds still need an explicit `size`. `in <room>` records
+which room owns the piece (used by the lint rules). The full placement rules, the fixture symbol catalogue, and the
 fixture-aware lint checks live on the dedicated **[Furniture & fixtures](furniture.md)**
 page. Standard fixtures are also importable components at typical residential sizes: