ADR-016: Repository Task Runner

• Status: Accepted
• Date: 2026-08-18
• Roadmap task: F1-006
• Decision owners: developer experience maintainers

Context

Munderecat combines a Next.js workspace, Python data pipelines, local Supabase services, documentation and later release tooling. Contributors need a stable command vocabulary that does not require remembering each tool’s working directory and safety flags. That vocabulary must not duplicate package, dependency, migration or domain logic already owned by pnpm, uv and Supabase CLI.

The roadmap already specifies commands such as make bootstrap, make db-reset, make verify, make docs-dev and domain pipeline targets. F1-021 also explicitly requires make docs-dev and make docs-check.

Decision

GNU Make is the repository’s sole public task runner.

• The root Makefile is the canonical command index.
• Recipes support GNU Make 3.81 and POSIX sh, which covers the baseline macOS environment and common Linux CI/contributor environments.
• Recipes remain thin adapters. They invoke exact project tools and public package scripts rather than parsing lockfiles, implementing builds or reproducing migration logic.
• A second runner configuration is not added. Internal scripts may exist when real orchestration complexity warrants them, but Make remains their public entrypoint.
• make help lists only real, working public targets. Future command names are added by their owning roadmap tasks, not as successful placeholders.

Initial Command Contract

Environment And Verification

• make bootstrap installs the pnpm graph with --frozen-lockfile and the uv environment with --locked. It may populate ignored local caches and environments but cannot update either lockfile.
• make web-dev starts the current Next.js application; make dev is its present convenience alias. Future multi-service development may extend dev without changing web-dev.
• make web-check delegates lint, strict typecheck and production build to the web package.
• make python-check verifies uv.lock offline with Python downloads disabled.
• make verify aggregates the current non-Docker checks. F1-012 will own CI and any broader verification matrix.

Local Database

All database targets follow ADR-015:

• the project-pinned Supabase CLI is used through pnpm,
• --workdir db is always explicit,
• db-reset always includes --local,
• the dedicated network’s requested bridge binding is verified before start,
• startup failure calls normal Supabase stop and removes a network created by that attempt,
• normal db-stop preserves Supabase backup state, then removes the detached network,
• wildcard host publication emits a warning and is never described as loopback isolation,
• db-check stops the stack even when its status probe fails.

F1-031 remains responsible for hard host-port isolation, per-agent project and port allocation, credentials and role separation. F1-006 does not weaken or claim completion of that gate.

Consequences

Benefits

• Contributor and CI commands share one discoverable vocabulary.
• Safety-critical flags such as Supabase workdir and --local are centralized.
• Pinned tools retain ownership of behavior, keeping Make recipes small and reviewable.
• Future docs and pipeline tasks can add stable commands incrementally without changing the runner.

Costs

• Windows contributors need an environment providing GNU Make and POSIX shell, such as WSL; native Windows Make compatibility is not claimed.
• Long-running development targets retain normal foreground process behavior.
• Make does not provide typed arguments or a rich plugin model; complex logic must move to a tested script while retaining a Make entrypoint.

Alternatives Considered

Root package.json Scripts

This would avoid a separate executable for JavaScript contributors, but it makes Python, Docker, documentation and release operations appear owned by the Node package graph. The roadmap’s established make vocabulary and polyglot boundary favored Make.

just

just offers cleaner recipe syntax, but adds a bootstrap binary that is not otherwise needed. GNU Make is already present in the baseline environment and matches roadmap commands.

Shell Scripts As The Public Interface

Scripts are suitable implementation units but provide no single discoverable target index or dependency composition. They may support future complex tasks, but are not the top-level command vocabulary.

Multiple Native Tool Commands Only

Requiring contributors to invoke pnpm, uv, Supabase and Docker commands directly avoids a wrapper, but repeats safety flags and working-directory knowledge in documentation and CI. It was rejected as error-prone.

Revisit Conditions

• A supported contributor or CI platform cannot run GNU Make/POSIX recipes.
• Recipe complexity repeatedly exceeds thin orchestration and tested scripts do not restore clarity.
• The project adopts a cross-platform runner that materially reduces bootstrap requirements without duplicating tool ownership.