The CLI is the interface; the Makefile retires

ADR-038: The CLI is the interface; the Makefile retires

Status Active · Filed 2026-08-07 · Issue #45

Context

The Makefile arrived with the extraction from strata-g carrying a doctrine in its header: “Job bodies live here, not in the workflow YAML, so ‘run what CI runs’ is always make <target> and the two can’t drift apart.” That was true until ADR-029 moved the docs jobs into composite actions (actions/generate, actions/lint) that invoke luria directly — after which CI’s entire Makefile usage was one line, make test, itself a wrapper for python -m pytest tests -q.

Everything else in the file restated a CLI one-liner, and the restatement drifted on schedule: the ref-status and pending targets had to be chased when ADR-030 removed their commands, the journal target when ADR-036 replaced it. Review named the smell (#45): a vestigial component of the ancestor’s CI, dragged along as a fifth hand-maintained copy of the command surface.

Decision

Delete the Makefile. ci.yml runs python -m pytest tests -q directly; every documentation command is typed as itself; luria --help is the one authoritative list of what you can run, derived from the dispatch table.

The Makefile also leaves the [luria.code] scan globs — there is no longer a file for references to hide in.

Alternatives considered

• Keep it as a convenience layer. The convenience was five saved keystrokes per command, purchased with a copy of the surface that drifted twice in a week and a make help that could quietly disagree with luria --help. The ADR-030 argument applies verbatim: an interface entry is documentation, and these entries’ claims kept going false.
• Swap in a task runner (just, tox, a scripts table). Same restatement, new syntax, plus a tool dependency — the problem was never Make’s syntax.
• Status quo. Free until the next command change, which this week suggests is never far away.

Consequences

• “Run what CI runs” becomes: python -m pytest tests -q and luria lint — both stated in CLAUDE.md’s map, both single commands.
• One of #45’s four hand-maintained restatements of the command surface is gone with the file; the README table remains, tracked there.
• An adopter who copied the old Makefile keeps a working copy — it only ever called public commands — but the scaffold never shipped one, so nothing downstream changes.