§39.7: access requirements become a declared usage: attribute (homemaker-py-sel)

Closes the second namespace sharing a first character with programme codes: the
usage prefixes b/t/l/k, under which a room silently inherited another room's
connectivity rules from its spelling.

usage is a plain, MANDATORY attribute of the space definition -- not a lookup
table. An interim design proposed a top-level usage_classes: table binding
author-coined names to behaviour; withdrawn, because an indirect name->behaviour
mapping living apart from the thing it describes is exactly the shape of the
prefix rule §39 exists to remove, it would be the only such table in a schema
where every other space property is a plain attribute, and the need it served
was already met -- "building specific" is about what a room is CALLED, and
name: is already free text.

Rule that settles it: a usage value exists iff the engine treats it differently
somewhere. Config selects among behaviours; it cannot invent them.

- programme.USAGES (living/kitchen/bedroom/toilet/utility/none) plus the
  behaviour groupings PRIVATE_USAGES / PRIVATE_STRIPS / TOILET_STRIPS /
  SOCIABLE_USAGES. Missing or unknown usage is a load error naming the code,
  from BOTH parse paths.
- Code-level, never leaf-level: usage_of(leaf.type) is looked up fresh, so a
  retype changes the class automatically. 51 sites assign leaf.type, and
  share/share_type plus the r5a resurrection are the precedent for why
  leaf-level attributes rot.
- graph.has_circulation takes the usage map and trims on declared class;
  fitness.access and the public-access check likewise. fitness._t0 is DELETED --
  no first-character type test remains anywhere in the codebase.
- utility is distinct from bedroom (same access requirements today) because it
  is a different use and gives derive_interchange_classes an axis to relax on.
- A toilet now keeps its edge to a terminal room -- the Brand adjacency, which
  the old b-before-t loop ordering severed.
- All 107 corpus entries migrated by experiments/migrate_usage_key.py, comments
  and layout preserved.

MEASURED -- the connectivity model was ~4x too permissive. `none` is not
neutral: nothing is trimmed, so the graph may route THROUGH the room, and 34 of
52 codes had no class (Dental Surgery, Records Room, Utilities Closet all served
as corridors). Edges trimmed, prefix-inferred vs declared, 3 seeds each:
  harbor-house   18 (9%)  -> 79 (39%)   inaccessible fails 0 -> 4
  health-centre  12 (8%)  -> 59 (40%)   inaccessible fails 2 -> 3
  maple-court    53 (17%) -> 123 (39%)  inaccessible fails 1 -> 5

Re-baseline (seed 1, 20k, harbor): 58 fails (15h/43s) -> 61 (16h/45s), now
reporting 1-inaccessible-usable-space x2 plus level 0 and level 1 not connected.
The count rose because the objective got honest -- those failures were always
true of the layout and the old model could not see them. Every harbor number
before this was measured against a graph crediting routes through store
cupboards.

Sharpens §38.2: the objective pays x60-85 to delete circulation, and until now
the deleted corridors were not missed because storage stood in for them. With
that substitution gone, homemaker-py-2v1 is the remaining half -- and now
measurable, because the fails it should prevent actually fire.

350 passed (+5 new), same 7 pre-existing fixture failures, lint unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MJ84Feep79Hhm3E4zZJmnB

2026-08-26 13:39:41 +00:00

5.4 KiB

Raw Blame History

Project Instructions for AI Agents

This file provides instructions and context for AI coding agents working on this project.

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
Run bd prime for detailed command reference and session close protocol
Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Room-code namespaces (DESIGN.md §39.4/§39.6)

Leaf types share a first character across three namespaces:

C / O / S — generic structural types (circulation / outside / sahn), uppercase, reserved. A programme code spelled exactly one of these is rejected at load.
programme room codes — lowercase, may start with any letter. The generic tests match C/O/S exactly, so cr1 is a room, not circulation.
usage: — every space declares its access-requirement class (living/kitchen/bedroom/toilet/utility/none), mandatory, no fallback (DESIGN.md §39.7). A code's spelling decides nothing: name: is free text, usage: drives behaviour. There is no first-character type test left anywhere in the codebase.

When adding or editing a programme, run python experiments/audit_programme_config.py — it reports reserved-name collisions, the usage class each code picks up, and per-room-spec satisfiability.

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

File issues for remaining work - Create issues for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

PUSH TO REMOTE - This is MANDATORY:

git pull --rebase
bd dolt push
git push
git status  # MUST show "up to date with origin"

Clean up - Clear stashes, prune remote branches
Verify - All changes committed AND pushed
Hand off - Provide context for next session

CRITICAL RULES:

Work is NOT complete until git push succeeds
NEVER stop before pushing - that leaves work stranded locally
NEVER say "ready to push when you are" - YOU must push
If push fails, resolve and retry until it succeeds

Build & Test

pip install -e .
pytest

Architecture Overview

homemaker-layout is a Python successor to the Perl Urb project. It represents a building as a binary slicing tree where leaves carry target dimensions from the programme and division ratios are solved bottom-up (inverting Urb's top-down approach). The evolutionary search explores topology, types, and adjacency only.

Key modules:

dom.py — read/write Urb .dom YAML into a Node tree
geometry.py — faithful port of Urb's top-down geometry
programme.py — parse patterns.config space requirements
solver.py — bottom-up ratio solve (scipy)
shapecurve.py — Otten/Stockmeyer shape-curve DP: exact size/width/proportion feasibility for a frozen topology, any storey count (DESIGN.md §37.2/§37.4-§37.6); used as driver._evaluate's NM warm-start/hard pre-filter
cpsat.py — exact room-code-to-leaf labelling via OR-Tools CP-SAT for a fixed topology (DESIGN.md §37.7); replaces operators._assign_adjacency_aware's greedy/beam room placement behind assign_solver="cpsat", and powers the operators.mutate_reassign in-search repair operator
fitness.py — native Python fitness evaluator (replaces Perl oracle)
fitness_cmd.py — homemaker-fitness CLI entry point
collapse_cmd.py — homemaker-collapse CLI: finish-time global cell→room collapse (94g)
graph.py — leaf-adjacency graph for programme-driven fitness checks
genome.py — topology genome: base-floor tree + per-storey deltas
operators.py — high-locality mutation and subtree crossover
innerloop.py — ratio optimisation inner loop (Nelder-Mead / CMA-ES)
driver.py — memetic search outer loop
evolve.py — homemaker-evolve CLI entry point
oracle.py — legacy Perl shim, kept for validation only; do not use in new code
bubble.py — 3D bubble-diagram adjacency fitness-signal prototype (DESIGN.md §27, mi7); validated NULL, not wired into fitness.py — reference only, do not build on without a new formulation

Conventions & Patterns

Scoring .dom files

Use the native homemaker-fitness command. Like the old urb-fitness.pl, you must cd to the directory containing the .dom file first — the tool resolves patterns.config, costs.config, and writes .score/.fails relative to cwd:

cd /home/bruno/src/homemaker-layout/examples/programme-house
homemaker-fitness cf0b8a77e8b2325f92a7e7d150184a55.dom

The score is written to <file>.dom.score and failures to <file>.dom.fails; the numeric score is also printed to stderr.

Do not use urb-fitness.pl directly — oracle.py and the Perl tool are kept only for cross-validation.

5.4 KiB Raw Blame History