ADR 0001: Repository Maintenance Model

• Status: Accepted
• Date: 2026-03-02

Context

Merlin is maintained by a very small team while carrying out-of-tree changes on top of IREE and nested LLVM forks. Maintenance cost and upstream drift are key risks.

Decision

1. Keep upstream forks pinned and patch-driven:
2. Pins: build_tools/patches/manifest.env
3. Ordered patch series: build_tools/patches/series.*
4. Prefer out-of-tree Merlin logic in this repository.
5. Use one stable developer entrypoint:
6. tools/merlin.py
7. Add CI gates for:
8. script lint/syntax
9. CLI docs drift (docs/reference/cli.md)
10. patch verify
11. drift check
12. Keep board flows in benchmark/target/<board>/ with deploy/run/parser scripts and environment templates.

Consequences

Positive:

1. Lower maintenance overhead for 1-2 maintainers.
2. Faster detection of upstream drift and accidental fork edits.
3. Clearer onboarding via single command interface and process docs.

Trade-offs:

1. Requires disciplined patch refresh/update when in-tree fork edits happen.
2. Some workflows remain script wrappers around existing build systems.