03aadec1ba
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
123 lines
5.4 KiB
Markdown
123 lines
5.4 KiB
Markdown
# Project Instructions for AI Agents
|
|
|
|
This file provides instructions and context for AI coding agents working on this project.
|
|
|
|
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
|
|
## Beads Issue Tracker
|
|
|
|
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
|
|
|
|
### Quick Reference
|
|
|
|
```bash
|
|
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:**
|
|
|
|
1. **File issues for remaining work** - Create issues for anything that needs follow-up
|
|
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
|
3. **Update issue status** - Close finished work, update in-progress items
|
|
4. **PUSH TO REMOTE** - This is MANDATORY:
|
|
```bash
|
|
git pull --rebase
|
|
bd dolt push
|
|
git push
|
|
git status # MUST show "up to date with origin"
|
|
```
|
|
5. **Clean up** - Clear stashes, prune remote branches
|
|
6. **Verify** - All changes committed AND pushed
|
|
7. **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
|
|
<!-- END BEADS INTEGRATION -->
|
|
|
|
|
|
## Build & Test
|
|
|
|
```bash
|
|
pip install -e .
|
|
pytest
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
homemaker-layout is a Python successor to the Perl [Urb](../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`:
|
|
|
|
```bash
|
|
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.
|