ADR-001 appendix: Phase 2 backend design review

Date: 2026-07-20
Decision: SQLite prior stands. Do not build a Beads primary backend. Do not escalate to a dual coded TaskProvider spike.

Beads design review (Step A)

Questions from ADR §4.5 (“still unclear”):

Question	Answer from docs/CLI inspection
Display-id mapping for branches/CI (`FUL-n`)	Beads uses hash ids (`bd-a1b2`). Mapping would be a permanent alias layer or a rename of Mainark’s branch/CI convention. Answerable without coding: Beads does not natively own `FUL-n`.
Atomic claim without leaking Beads concepts	Claim is `bd update --claim` against Beads status/assignee. Mainark’s pipeline already has its own `status` / claim semantics. A Beads SoT would either duplicate claim or leak `bd` statuses into domain types. Answerable without coding: leakage or dual graphs.

Ownership: Beads/Dolt would be a second embedded database Mainark must reason about — the same class of problem as Linear (graph in someone else’s model), even if offline.

Agent ergonomics (bd ready, deps) are real advantages, but insufficient to falsify the SQLite prior given identity + ownership answers above.

Spike acceptance (SQLite candidate)

Criterion	Plan
Concurrent claims	`UPDATE … WHERE work_status='todo'` compare-and-swap
Atomic state transitions	Single-statement updates + `issue_events` append in same connection
Durability / backup	Copy `SQLITE_PATH` (WAL); document restore
Event logging	`issue_events` table
Offline	No Linear calls when `TASK_BACKEND=sqlite`
Implementation complexity	Extend existing `issues` repo; zero new runtime deps
Identity	`id_sequences` → `FUL-n`
Ownership	Mainark schema

Outcome

Phase 2B: implement SqliteTaskProvider only (TASK_BACKEND=sqlite).
Default remains linear until Phase 3 sign-off.
Beads: leave fail-fast stub; optional agent scratch later, not SoT.