d0567d7a74
Owner's decision: "we need to abandon the perl oracle, this was only useful when initially porting, but I suspect many of the remaining problems have been carried in from the perl (such as the weird scoring of outdoor and circulation space, which definitely needs fixing)". 39 supports that second clause. Every defect the section found is inherited, not introduced: the two-sided crinkliness gaussian that double-charges surplus daylight (39.14), quality as a product over a variable number of factors (39.18), value_supported priced as value_inside so a terrace was worth more per m2 than a room (39.19), and circulation returning 0.07 per unit cost (hxi). So parity with the oracle was never a safety net -- it was a commitment to reproduce those defects. Each of 39.14, 39.18 and 39.19 would have been a parity failure had parity ever been checked, and keeping the tests would have meant reverting the fixes or explaining the failures away. Removed: oracle.py, test_oracle.py, the two parity tests and their fixture machinery in test_dom_corpus.py, innerloop.OracleEvaluator with its use_native and urb_root plumbing, the same plumbing through driver, and fourteen experiments/ scripts that could only run against Perl. Several of those are cited in earlier DESIGN sections; the citations now point into git history, which is the honest state -- they had been unrunnable since the oracle root (/home/bruno/src/urb) stopped being present. run_search is superseded by run_search_scaled, which does the same job natively. Kept: dump_areas.pl/.py, which validate GEOMETRY against Urb (4.1) rather than fitness, and the prose in fitness_cmd.py and dom.py explaining why the .score/.fails formats are shaped as they are. Provenance is worth keeping; a dead code path is not. CLAUDE.md updated: fitness.py is the only evaluator, and "Urb did it this way" is no longer an argument that a constant is right. 39.16 is the standing counterweight in the other direction -- the crinkliness target WAS right and twice looked wrong only because the code reading it was misunderstood. Inheritance is neither evidence for nor against. 410 passed. The 69 removed cases account exactly: 64 parity (all skipped, since no oracle .score was ever committed), 4 in test_oracle.py, and the guard test 39.20 added as a stopgap. Closes homemaker-py-118. Files homemaker-py-bk9 for the re-baseline that 39.19 made necessary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MJ84Feep79Hhm3E4zZJmnB
131 lines
5.9 KiB
Markdown
131 lines
5.9 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
|
|
- `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.
|
|
|
|
`fitness.py` is the **only** evaluator. The Perl oracle it was ported from —
|
|
`oracle.py`, `urb-fitness.pl`, and the parity tests against them — is gone
|
|
(DESIGN.md §39.21). Those parity tests had never actually run: no oracle
|
|
`.score` was ever committed, so on a clean checkout every case skipped, and the
|
|
only cases that ever executed compared the native scorer with itself (§39.20).
|
|
|
|
The corollary matters when reading the objective: a constant or a rule that
|
|
looks odd is **not** thereby validated by "Urb did it this way". Several
|
|
defects found in §39 were carried straight over from the Perl — see §39.19 on
|
|
`value_supported`, and `homemaker-py-hxi` on circulation, which the owner has
|
|
ruled needs fixing.
|