docs: Makefile contract, the rules a Makefile change is reviewed against

[oharboe]

flow/Makefile keeps to a handful of conventions that have grown up over time and were never written down. This writes them down in docs/contrib/MakefileContract.md as hard-stop rules, so that automated review of AI changes to flow/Makefile, flow/scripts/*.mk, the stage .tcl scripts and variables.yaml has something to check against. Each rule says what breaks when it is broken.

• Targets: a do- target never builds anything; dependencies live only on the file targets and stage aliases; open_*, gui_*, web_* and run never build anything; the graph never depends on a variable.
• Steps: a step never writes into its inputs, never skips an output because it exists, never reads a file it does not declare or an input it does not use, never leaves configuration for a later step, never draws an unseeded random number, and never calls exit on failure; PRE_<STEP>_TCL hooks run after load_design.
• Variables: never = for a variable a design sets; never export VAR := $(VAR) for one the environment supplies; only the Makefile sets RESULTS_DIR and the other tree directories; every variable is in variables.yaml, and one with a default is read as $::env(VAR); positive names, no duplicates, no default-off toggles, no $(shell awk/sed ...).

The rules come from review threads on this repository, among them #4672, #4682, #4685, #4586 and #4573. Existing code that breaks a rule is called out as debt, not precedent: for example, exit 1 in floorplan.tcl and util.tcl, and AUTO_MEMORIES's generated memories.json as a do-yosys prerequisite.

AGENTS.md (and CLAUDE.md, which links to it) gets one line pointing agents at the page, and the Developer's Guide and docs/toc.yml list it.

Documentation only.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a new 'Makefile Contract' developer guide (docs/contrib/MakefileContract.md) that establishes clear rules and conventions for modifying the OpenROAD Flow (ORFS) Makefile, stage scripts, and variables. It also updates AGENTS.md, DeveloperGuide.md, and the table of contents to link to this new document. The review feedback suggests a helpful clarification to specify that the rule against overwriting set variables applies specifically to configuration or environment variables, rather than local script variables.

[openroad-ci]

🔍 QoR check

Metrics reflect the PR merge build — i.e. what will land on the target branch.

Commit fcf42b0 · Jenkins build #3 · Baseline: build · View build on dashboard

62 design(s) checked — 0 with regression(s), 0 without a comparable baseline.

[dsengupta0628]

Thanks for writing these down. Very helpful.
Small requests: Three places where the page doesn't match today's code:

1. "The graph never depends on a variable." LEC_CHECK/SEC_CHECK (Makefile:450, 465, 567, 573, 681, 687), SYNTH_USE_SYN (Makefile:441) and AUTO_MEMORIES (Makefile:268) all change the graph, including the check-kepler-formal prerequisite the page gives as an allowed example.
   Please add a short "Known debt" list to MakefileContract.md that names these. The PR description's examples (exit 1 in floorplan.tcl/util.tcl, memories.json) can go there too.
2. "A variable is never missing from variables.yaml." WORK_HOME and the four tree directories are not in it, and Makefile-only helpers (DO_STEP_DEPS_*, UNSET_AND_MAKE) would fail the rule too.
   In MakefileContract.md, please limit the rule to variables a design, platform or user sets, or a stage script reads. Add WORK_HOME to the known-debt list.
3. Scope. The config.mk platform-default rule covers flow/platforms/*/config.mk and flow/designs/**/config.mk, but those paths are missing from the scope list, so they never get checked against it.
   Please add those two paths to the intro of MakefileContract.md and to the line in AGENTS.md.

[oharboe]

Thanks! Addressed 2 and 3. For 1, rather than a list that goes stale as items are fixed or added, the page now says any place where the code disagrees with a rule is technical debt, from an expedient solution or older code. LEC_CHECK/SEC_CHECK, SYNTH_USE_SYN, AUTO_MEMORIES and exit 1 in floorplan.tcl/util.tcl are examples of that debt. WORK_HOME is not debt: Makefile-only variables can be documented without being in variables.yaml, and the rule now says so.

[oharboe]

My intention is not perfection of this documentation of first try, but to have enough of a baseline that contributors get more autonomy by having improved AI authoring and review.

[dsengupta0628]

All good. Thanks- I approved. But system doesn't let me merge your code or enable auto merge. I think you need someone with write permission in this repo. @eder-matheus ?