[oharboe]

ORFS writes each design into four directories. A single directory would work just as well for the flow; the four exist for the reader. When the directory says what a file is, a user finds the design, a measurement of it, the log of a failed step, or the scaffolding, without reading the Makefile.

That only holds while every file follows the same rule, and today the rule is unwritten. This PR writes down the one master already follows, so that the directory a file lands in is the least surprising one. It changes no files of the flow.

The rules

What a file is decides its directory, not who reads it:

• RESULTS_DIR: the design, in any format. Netlists, .odb, .def, .gds, .sdc, routing guides, placement scripts, the checkpoint a failed step leaves, memory inventories.
• REPORTS_DIR: measurements of the design, for tools or people to read. No step's result depends on it.
• LOG_DIR: logs, and each step's metrics .json next to its log.
• OBJECTS_DIR: what is not the design. Files a step derives from the platform (klayout.lyt), a step's own intermediate files (abc.constr, rtlmp/, surgery/), caches, and stopgaps that wait for a cleaner implementation.

Files that don't follow the rules today

Moving a file surprises everyone who knows where it is, so each one is a case of its own: a separate PR, opened only after the rules are agreed, and only when the move is worth the surprise.

File, in RESULTS_DIR today	Is	Rule says
maze.log	a log	LOG_DIR
6_lvs.lvsdb	a measurement; 6_drc.lyrdb is already in REPORTS_DIR	REPORTS_DIR
6_nets_rc.csv, 6_segments_rc.csv	measurements (write_rc, correlate_rc)	REPORTS_DIR

Candidates for removal

Found while sorting files under the rules. Each one is a separate PR, or no PR if a reason to keep it turns up.

Candidate	Why
mem_hierarchical.json branch of make memory	Nothing writes the file since a0c0c87 removed synth_stats.tcl
output_guide.mod in clean_route	Nothing writes it
WRAP_LEFS / WRAP_LIBS (util/cell-veneer)	A veneer around SRAM macros for place and route. Only gf12 designs use it, and public CI cannot run them. Owners of those designs: is it still needed?

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request adds a new "Directories" section to docs/contrib/MakefileContract.md to document the structure and purpose of the four main directories: RESULTS_DIR, OBJECTS_DIR, REPORTS_DIR, and LOG_DIR. The review feedback suggests formatting the LOG_DIR description to be fully bolded to maintain consistency with the other directory definitions.