[Dev-iL]

The problem: a newcomer to Hamilton, person or AI agent, can't learn from the repository what its overloaded words mean: "adapter" names three different things. The guides they would start from send them wrong: CONTRIBUTING.md and the README link a setup guide that isn't there, and the setup guide's install command installs neither the dev nor the test dependency group.

What changes: CONTEXT.md, a glossary of eight terms that mean something specific here, each checked against the code it describes; and fixes to CONTRIBUTING.md, the README, the developer setup guide and two SQL lineage records, each listed below.

Where this sits: split out of #1806 at the review's request into three stacked pull requests, one commit each; this is the bottom:

1. this pull request, commit 8da307bf;
2. Record eight foundational decisions, reconstructed from the codebase #1809, the decision records;
3. Add scripts/verify, a command that runs the checks CI runs, one recipe per area #1806, scripts/verify.

They merge bottom-up, each rebased onto main after the one below lands. This one depends on neither of the others.

Shown working, at 8da307b:

• uv run prek run --all-files --hook-stage pre-merge-commit: passes, license headers included.
• python3 linkcheck.py . 8da307bf (described below): 6 Markdown files, 6 relative links checked, 0 problems.
• No workflow runs here: it touches no path in any workflow's pull_request filter.

Decisions:

• Author's call: split Add scripts/verify, a command that runs the checks CI runs, one recipe per area #1806 into three stacked pull requests, one commit each, as the review asked, rather than keeping one pull request.
• The documentation fixes go with the glossary, the part of Add scripts/verify, a command that runs the checks CI runs, one recipe per area #1806 the review called useful and no one disputed, so they can land first.

Debt left: nothing checks the glossary against the code after this commit; a renamed class or a new kind of adapter needs a hand edit.

Before and after (an illustrative example). Task: name a new class that plugs into execution.

• Before: you search the code for "adapter" and find three things under that name: DataLoader classes in the adapter registry, HamiltonGraphAdapter subclasses, and the lifecycle adapters passed to Builder.with_adapters. Then you guess which one your class is.
• After: CONTEXT.md's "adapter" entry names the three meanings and the code behind each, so you can pick the term that matches what your class does.

What changes, in full

• CONTEXT.md defines eight terms: the three things called an adapter; function versus node; function modifier and its phases; config, inputs and overrides; result builder; hook, method and validator; materializers versus the data loader and saver decorators; and extension versus plugin module.
• CONTRIBUTING.md
  • linked a root developer_setup.md that doesn't exist; it now links writeups/developer_setup.md;
  • described CircleCI; that section is removed;
  • said "getting setup"; it now says "getting set up";
  • gains "Finding your way around", with one bullet for the glossary.
• README.md linked the same missing developer_setup.md; it now links writeups/developer_setup.md.
• writeups/developer_setup.md
  • installed with pip install '.[dev,test]', but dev and test are dependency groups, not extras, so that command installed neither; it now uses uv sync --group test;
  • its unit-test section described CircleCI, .ci/ scripts and requirements-test.txt; it now uses uv run pytest, says which CI step each command mirrors, and where the workflow keeps the exact commands;
  • gains "Some tests need more than Python packages": Graphviz's dot for the graph-rendering tests, and HAMILTON_TEST_POSTGRES_URL for the PostgreSQL tests;
  • its PyCharm steps now point at the interpreter in .venv.
• writeups/adr/2609-02 and 2609-03 cite each other by their own numbers, with links.

How the link check works

linkcheck.py <repo> <commit> is a short script of mine, kept outside the repository. It checks that every relative link in the Markdown files the commit changes resolves in that commit's tree, and that those files mention no glossary, record or harness file the tree lacks, so this pull request can land before the two above it.