# Project Instructions for AI Agents ## READ THIS BEFORE CHANGING ANYTHING **`HANDOFF.md` section 0 is the specification for HOW to work here. Read it before any port.** Then section 9 for state and standing gotchas. `../PROJECT-MEMORY.md` carries what does not live in the repo. **For what to work on, run `bd ready`.** The parity ledger is a beads DAG, not a table in HANDOFF — section 5c says why and how to read one. This is a **feature-for-feature, UI/UX-compatible replacement for Ultimate Doom Builder that runs in a browser**, for Reese's own use, in UDMF for UZDoom. "For their own use" is **not a reduced scope** — parity is the requirement, visual (3D) mode included. **Every defect in this project's history came from inventing a mechanism instead of reading one.** Not from carelessness and not from hard problems: from plausible reasoning that happened to be wrong. Section 0 lists each one with what it cost. Reese's standing instruction, in their words: *"always do everything how udb does it"*, *"no skipping — we gotta port things exactly"*, *"parity is key; 1:1. drift is death"*, ***"drift is death and grounding is god"***, *"anything should be easy, because we're not deriving or figuring out anything. IT'S ALL THERE IN UDB."* The last one is an operating instruction, not encouragement: when something looks like it needs designing, the answer is already in UDB's source and the job is to go read it. ### The method, in short — the long form is section 0 1. **Find the reference before writing the code, and cite `File.cs:line`.** If you cannot point at a file and a line, you are guessing. `citecheck.js` verifies every citation in the tree resolves and still says what it claims. 2. **Read the WHOLE function**, not the part that looks relevant. 3. **Port it line by line, including the parts that look arbitrary.** A 0.1-unit tie-break bonus, a which-way-does-the-neighbour-turn test, an inclusive rather than exclusive bound — those are the parts doing the work. A cleaner version that "does the same thing" reliably does not. 4. **Add no guards the reference lacks.** Being stricter than UDB is drift in the same way being looser is. Both have happened. 5. **A failing check is data.** The code is the likely culprit, not the certain one. Change an assertion only once you can say precisely why the old one was wrong, and write that reason into the test. 6. **Mutation-test what you port, and check the FIXTURE can discriminate.** Revert each behaviour and watch a test go red. A fixture that answers the same either way reports "caught" and proves nothing. 7. **Verify a patch APPLIED, not that the suite passed.** Grep for the new symbol. A green suite proves nothing about an edit that never ran. 8. **Never hand-type a mirrored table — re-dump it**, and if you add one, add its checker at the same time. 9. **Write down the direction of any deliberate divergence.** An undocumented divergence is drift wearing a hat. 10. **Deferrals are OWED, not decided.** "There is no X yet" is a missing feature. **File the stopping point as a bead.** ### Standing decisions — do not relitigate without new information Vanilla JS, ES modules, **no build step** (no bundler, no TypeScript). **Not a port** of UDB, and not built on deotg, jzbuilder or wad-together — each was measured and rejected. **UDB is the specification, not the base**; its `.cfg` tree is reusable as data. **Ear clipping, not poly2tri.** Do not recalibrate `UDB_STYLE` to the reference maps. ### More than one agent works in this tree at once Re-read a file immediately before patching it, keep edits surgical, never restore a whole file from a backup without diffing it against disk first, and **do not read a changed test count as evidence about your own change** — diff the test NAMES. ## 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 # View issue details bd update --claim # Claim work bd close # 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 **Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns. ## Agent Context Profiles The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. - **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. - **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. - **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. ## Session Completion This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. 1. **File issues for remaining work** - Create beads 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. **Handle git/sync by active profile**: ```bash # Conservative/minimal/default: report status and proposed commands; wait for approval. git status # Team-maintainer opt-in only, unless current instructions forbid it: git pull --rebase git push git status ``` 5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step **Critical rules:** - Explicit user or orchestrator instructions override this Beads block. - Do not commit or push without clear authority from the active profile or the current user request. - If a required sync or push is blocked, stop and report the exact command and error. ## Where the durable context lives - **`HANDOFF.md`** — section 0 (method + evidence), 5d (the one addition), 9 (state and standing gotchas). Section 8 is a LOG of finished work, not a plan, and its "5c row" mentions are historical. - **beads** — the parity ledger itself: `bd ready`, `bd blocked`, `bd show`. - **`../PROJECT-MEMORY.md`** — who the project is for, what is on disk. - **`~/.claude/projects/-Users-penelopede-Desktop-Work-WWWDB/memory/`** — the file-based memory, **in use and authoritative**. `MEMORY.md` indexes six entries, including `always-implement-udb-exactly`. - **beads** — the work itself. `bd prime` injects the `s0-*` memories that mirror the method above. **The generic beads guidance above says not to use MEMORY.md files. That does not apply here** — this project's memory directory predates beads, carries the standing instruction and the evidence table, and is kept in step with the `s0-*` bd memories deliberately. Keep both. ## Build & test No build step. Vanilla ES modules, no dependencies. ```bash node selftest.js # the fast gate, no external files node dialogrender.js # createDialog's DOM assembly, under a shim node citecheck.js # every File.cs:line citation resolves node conformance.js refs/udb/Assets/Common/Configurations node dialogparity.js refs/udb/Source/Core/Windows --layout node dialogparity.js refs/udb/Source/Core/Windows --dialog node menuparity.js refs/udb/Source node configparity.js refs/udb/Source/Core node infoparity.js refs/udb/Source/Core/Controls node typeparity.js refs/udb node gzlightcheck.js # the GZDoom light table vs GZGeneral.cs node mkicons.js --check node stackcheck.js "$HOME/Desktop/Work/rhythm doom_orig/firstwad/maps/" ``` The pages need a server, because ES modules do not load over `file://`. Use **`serve.py`**, not `python3 -m http.server` — it sends `Cache-Control: no-store`, and a stale module cache has cost hours more than once. In the Claude Code browser pane, even that is not enough: **open a NEW TAB.** `refs/` is fetched, not authored — `./fetch-references.sh` rebuilds it. `demo-config.json` is generated. Both degrade quietly when absent. **An empty grep over `refs/` is not evidence that the reference is absent.** The `grep` an agent gets in this project's shells is ugrep with `-I`, which treats a file containing one byte of invalid UTF-8 as binary and prints NOTHING — no hits, no warning, exit 1. UDB ships two such files, and one of them is `Vector2D.cs`, which is among the most cited files here: `Vector2D.Distance` is at `Vector2D.cs:228` and a grep for it came back silent. `./fetch-references.sh` now repairs those bytes on every run (wwwdb-e21), so run it if a search over `refs/` looks impossibly empty — or search with `/usr/bin/grep`, which does not care. Concluding "UDB has no such function" and deriving a replacement is exactly the defect section 0 is about, and this is a machine for manufacturing that conclusion. ## Conventions - Every ported function carries the `File.cs:line` it came from. - A mirrored table is dumped from the source, never typed, and has a checker. - Modals must not leak events to the map: `modalOpen()` and `typingInField()` gate every mouse and key handler, and any new global handler needs both. - Dialog layout is UDB's own, derived from the designer geometry — two-column tabs included. - Never redistribute `refs/`, Reese's maps, `demo-config.json`, `local-resources.json` or `acs/`.