ah-wd4 DECISION: move the task board from Vikunja to beads+Dolt (full swap vs hybrid mirror) Lined Up

Three independent Opus researchers audited this on 2026-07-20 (board contract / beads capabilities / human workflow). Consensus: writing the adapter is the EASY part; the cost is infrastructure and the human write path.

FEASIBILITY (good news): ports.Board is only 6 methods (Snapshot, MoveToBucket, Comment, Comments, CreateTask, SwapLabel), 22 call sites all in internal/reconcile, and everything else (attempts, runs, lineage, Q&A links) lives in the SQLite store. domain/ is Vikunja-free; bucket names are domain constants. Adapter est. a few hundred lines, minus the 238-line markdown->HTML converter which a plain-text board does not need. All 9 canonical buckets ARE expressible via beads custom statuses with active/wip/done/frozen categories, wired into the ready_issues view at SQL level. bd ready --claim is a real compare-and-swap (ErrAlreadyClaimed) — stronger than what we have today. Comments live in their own table, NOT mixed with the events audit log, so the ask-user answer detector is safe from machine-generated lines.

BLOCKERS (the real cost):
1. NO Go library (all packages are internal/), no MCP, no HTTP daemon. The only interfaces are fork/exec of bd --json (~250ms warm) or raw MySQL to a dolt sql-server.
2. Embedded mode is single-process and BLOCKS UNBOUNDEDLY — measured bd count waiting 43s behind a 40s external DB hold, no timeout knob. Upstream design doc calls multi-process embedded 'unsupported'. Migrating to dolt sql-server mode is MANDATORY (backup + bd init --server + restore; different data dir; a new server process to supervise).
3. Human write path. Vikunja is the human INPUT surface, not just storage; the viewer is read-only. The killer interaction is ask-user: a card parked in Question (or a live agent polling /api/tool/answer against a 30m timeout) waits on a human comment. Today that is typed from any device in <=20s; under beads it is laptop-only bd comment behind a ~5min auto-push debounce (~17% of a run timeout per exchange). Lowering the interval does not fix the failure CLASS: a local write that reports success and is invisible to the daemon.
4. Every write is a Dolt commit — a comment per state change plus per-heartbeat progress = write amplification into a version-controlled DAG that auto-pushes. bd batch help names this; bd compact/gc/flatten are the cleanup treadmill.
5. int64 task IDs are load-bearing (branch task-<id>, zellij session, archive filename, tool-token binding, HTTP API, notification URL). Beads ids are strings (ah-1cx.1). Recommended fix: repo-wide int64->string (mechanical, compiler-verified, ~10 files) over a synthetic mapping table that can drift.
6. Snapshot must NEVER be partial: a card missing from a snapshot is treated as vanished and the daemon KILLS the live run and cancels the record. Any adapter must enumerate transactionally or prove completeness (the Vikunja adapter refuses a truncated bucket rather than dropping tasks). Watch bd list default limits.
7. Same-field concurrent updates are last-writer-wins with no optimistic locking (upstream open question #3); only --claim has CAS. Contradicts the SPEC principle that human intent wins and the daemon aligns.
8. No change notification, by product charter ('Beads does not need sub-second sync'). Poll the events table by created_at. NOTE: this is NOT a real blocker for us — the Vikunja webhook is explicitly only an acceleration of the 20s poll, and agent-completion latency rides the separate run-exit poke.

WHAT IMPROVES: Task Spec escapes the rich-text editor (plainTextFromHTML exists ONLY to undo Vikunja HTML mangling of YAML frontmatter — becomes deletable); first-class deferred/--defer beats an unmapped Someday column; dependency-aware bd ready for free; agent and human share one tracker beside the code; full history/diff/branching. Attachments are a non-issue (zero code references).

OPTIONS:
A) HYBRID MIRROR (low risk): keep Vikunja as the board, add a one-way exporter into beads for reporting/milestones. No reconcile changes at all. Note the milestone viewer at dolt.srht.bigb.es/~bigbes/agents-dev/view/milestones already delivers most of this value today.
B) FULL SWAP, gated on prerequisites: migrate beads to dolt sql-server mode; daemon speaks MySQL directly (or bd --json --sandbox with pushes on its own timer); map ready->status open (REQUIRED: the CAS claim hardcodes status='open'); use metadata JSON for daemon-private state; events.created_at as poll cursor; batch comment writes + scheduled compaction; int64->string ids; AND build a human write path — 3 POST endpoints on the existing httpapi (comment / status / label) reusing the proven bearer-token pattern, plus a small form in the viewer. Because the daemon runs on agent-1 next to the authoritative working set, writes through it have ZERO sync latency and take the laptop out of the write path entirely.

RECOMMENDATION: do not swap while the viewer is read-only. Either stay on Vikunja, or commit to option B including the write path — the write path is what makes it viable, not the adapter. Implementation beads to be filed once this decision is made.

HANDOFF DESIGN — human write path for a beads-backed board. Written 2026-07-20 for a worker with
no prior conversation context. Read this whole section before touching code.

== WHY THIS EXISTS ==
Vikunja is not merely storage for agenthubd: it is the surface through which a HUMAN expresses
intent, which the daemon then observes. SPEC.md:36 and :41-43 state the contract — the board is
desired state owned by the human, the SQLite store plus runtime is actual state owned by the
daemon, and "the daemon never fights a human drag: human intent wins". Replacing the board with
beads+Dolt while the only web UI is READ-ONLY removes the human's write surface. That is the sole
remaining blocker to the migration; everything else is tractable work (see the description).

== THE COMPLETE HUMAN INTENT VOCABULARY (do not add verbs beyond these without re-deriving) ==
Every human gesture the daemon can observe reduces to four writes. Evidence is by interaction:

1. COMMENT — the only latency-critical write. Two cases:
   a. Card parked in Question: reconcile.go:1151 handleQuestion -> Comments() -> tools.go:263-278
      detectAnswer. It finds the LAST comment containing marker "agent-hub:awaiting-answer"
      (reconcile.go:1105); if ANY comment follows it, that trailing comment IS the answer.
   b. Mid-run: tools.go:210-238 ToolAskUser parks the card while the agent stays LIVE polling
      GET /api/tool/answer (tools.go:245-252). The run is burning against cfg.Timeout (default 30m,
      enforced in check()). Delivery latency here is on the critical path of a running agent.
   CONSEQUENCE: any write path slower than ~1 min materially degrades (b). A 5-minute
   auto-push debounce consumes ~17% of a default run budget per exchange.

2. STATUS CHANGE — highest-frequency gesture; five human actions share this one operation:
   trigger work (drag to Ready -> reconcile.go:234-235 handleReady + domain.CanClaim);
   promote an agent-created task out of Triage (created by tools.go:344-350 into
   cfg.AgentTasks.TargetBucket, default triage; Triage is a PARKED bucket, reconcile.go:238-244 —
   never a claim source); cancel/kill (reconcile.go:254-256 handleTerminal:1525-1560 -> runner.Kill,
   outcome killed); route from In Review; park out of the way (unmapped bucket, reconcile.go:228-232).

3. CREATE TASK — title + description + initial status. The description carries the Task Spec YAML
   frontmatter (role/model/skills/timeout), parsed by internal/spec/frontmatter.go:36-58.

4. EDIT DESCRIPTION / LABELS — easy to under-rate. When the daemon REJECTS a Task Spec it bounces
   the card to Triage (reconcile.go:380) with a comment that literally instructs: "Fix the Task
   Spec in the description, then drag the card back to Ready" (comments.go:51-59). Without an edit
   path a rejected card is unrecoverable from any device that lacks the bd CLI. Labels are the same
   operation class: the type:<name> label selects the task-type preset (spec.go:194-217) and is read
   by verdict routing (routing.go:23-42). Exactly one type:* label is legal.

NOT needed: assignees, priorities, due dates, attachments, ordering, reactions. The daemon reads
none of them (grep -rni attachment internal/ returns zero hits). BoardTask carries only
{ID, Title, Description, Bucket, Labels, UpdatedAt} and UpdatedAt has zero readers.

== TWO DELIVERY SHAPES — evaluate SHAPE A FIRST, it may be nearly free ==

SHAPE A: one shared Dolt sql-server; no new code.
  Run dolt sql-server on agent-1 beside the daemon; point every bd client at it over the network.
  bd supports this explicitly: 'bd dolt set host <ip> [--update-config]', plus port/user/database,
  BEADS_DOLT_SERVER_MODE=1, bd init --server (see bd dolt --help; docs/DOLT.md in the beads source
  says server mode "connects to a running dolt sql-server for multi-client access ... enables
  concurrent agents"). With ONE database there is no push, no pull, no debounce, no divergence and
  no merge conflicts. Solves every desk interaction at ~zero engineering cost.
  DOES NOT solve: any device without bd + network access to the server (i.e. phone).
  Costs: a supervised sql-server process; network exposure of the DB port; migration from embedded
  to server mode is backup + 'bd init --server' + restore with a DIFFERENT data dir
  (.beads/dolt/ vs .beads/embeddeddolt/) — not a flag flip.

SHAPE B: HTTP write endpoints on the daemon's existing httpapi.
  POST  /api/v1/board/:id/comment  {"text": "..."}                  -> interaction 1 (DO FIRST)
  POST  /api/v1/board/:id/status   {"status": "open"}               -> interaction 2 (DO SECOND)
  POST  /api/v1/board             {"title","description","status"}  -> interaction 3
  PATCH /api/v1/board/:id         {"description","labels"}          -> interaction 4
  Why the daemon and not the viewer: the daemon runs ON agent-1 next to the authoritative Dolt
  working set, so a write through it has ZERO sync latency — it mutates the DB the reconciler reads
  and pushes on the daemon's own schedule. This takes the laptop out of the write path, which is
  what eliminates the failure CLASS (a local write that reports success and is invisible to the
  daemon). Lowering the auto-push interval only narrows the window; it does not remove the class.
  MINIMUM VIABLE SLICE = comment + status. Those two cover the blocker and the highest-frequency
  gesture. Create/edit can lag because filing new work is a desk activity anyway.

== NON-OBVIOUS COSTS OF SHAPE B (largest hidden cost; read before estimating) ==
- The daemon is LOOPBACK-ONLY today: config.example.yaml line 1, listen: "127.0.0.1:9100".
  A human-facing write API means binding off-loopback, which drags in TLS and a real auth story.
- Auth machinery to REUSE, not reinvent: internal/reconcile/tools.go:60-137 mints per-task 256-bit
  bearer tokens with a constant-time compare; internal/httpapi/httpapi.go:311-353 does HMAC-SHA256
  verification for the Vikunja webhook. What is genuinely NEW is an OPERATOR token with a different
  lifetime and scope than a per-run token. Do not reuse per-task tokens for humans.
- TWO WRITE PATHS CAN DIVERGE: if the laptop keeps writing a LOCAL Dolt DB while the HTTP API writes
  agent-1's, the merge problem returns. Shape A avoids this by construction. If shipping B alone,
  point the laptop's bd at agent-1 as well, or consciously accept Dolt merges.
- Viewer integration: wire the existing read-only viewer's issue rows to POST at these endpoints
  (https://dolt.srht.bigb.es/~bigbes/agents-dev/view/milestones). It already renders id/title/
  priority/type/status and milestone progress; it is a sourcehut-style page with Log in/Register
  in the nav, so an auth context may already exist there.

== INVARIANTS ANY IMPLEMENTATION MUST NOT BREAK ==
1. NEVER return a partial board from Snapshot. A card missing from a snapshot is treated as VANISHED:
   reconcile.go:1659 handleVanished KILLS the live run and marks the record cancelled. The Vikunja
   adapter refuses a truncated bucket rather than dropping tasks (vikunja/board.go:95-99). See the
   open spike on SearchIssues/IssueFilter default limits — this is the gating unknown.
2. Do NOT let machine-generated audit lines into the COMMENT stream. detectAnswer takes the LAST
   comment unconditionally, so an injected "status changed to X" line would be consumed as the
   human's answer. Beads keeps comments in their own table separate from the events audit log, so
   this is currently safe — preserve that separation.
3. Move-then-comment, never comment-then-move (reconcile.go:376-379, :413-414, :1371-1373, :1494-1496).
   Only a successful move earns a comment, so a persistently failing move cannot spam one comment
   per tick.
4. Persist-before-move; never assume a write landed and never re-read to confirm. Every failed move
   converges on a later tick (heal branch reconcile.go:286-299, alignCardToRecord:1436). This
   tolerance is what makes a non-transactional board safe.
5. 'ready' MUST map to beads status 'open'. The atomic claim CAS hardcodes it:
   internal/storage/issueops/claim.go:47-58 UPDATE ... WHERE id=? AND status='open'. A custom
   'ready:active' status would appear in bd ready but would NOT be claimable.

== BEADS PUBLIC API (use it; do NOT import internal/ and do NOT shell out to the CLI) ==
Root package github.com/steveyegge/beads (MIT). Verified against the v1.1.0 source zip.
  Open(ctx, dbPath) / OpenFromConfig(ctx, beadsDir)  -- the latter respects dolt_mode in
    metadata.json, so embedded-vs-server is CONFIGURATION not code.
  Storage interface maps ~1:1 to ports.Board:
    SearchIssues / GetReadyWork      -> Snapshot      (SEE SPIKE: default limit unverified)
    UpdateIssue(id, {"status": ...}) -> MoveToBucket
    AddIssueComment / GetIssueComments (typed, ordered) -> Comment / Comments
    CreateIssue                      -> CreateTask
    AddLabel + RemoveLabel           -> SwapLabel
  RunInTransaction(ctx, commitMsg, fn) batches many writes into ONE Dolt commit with rollback on
    error or panic — use it to (a) kill write amplification and (b) make SwapLabel ATOMIC, which is
    strictly better than the current Vikunja adapter's documented non-atomic add-then-remove.
  GetAllEventsSince(ctx, since time.Time) is a typed change-feed cursor — no hand-rolled SQL.
  RemoteStore (via type assertion) exposes Push/Pull so the daemon controls push timing itself.
Escape hatches if the public API ever falls short, in order of preference: direct SQL (bd's own docs
recommend this for extensions); vendor the MIT-licensed code; a shim module declared under
github.com/steveyegge/beads/<x> plus a replace directive (Go's internal rule is a path-prefix check
on the IMPORTING package path, so this legally compiles). internal/ carries no compat guarantees.

UNBLOCKED by ah-wd4.1 (closed): the gating technical unknown is settled and it does NOT rule out a beads-backed Board adapter. beads v1.1.2's SearchIssues with a zero-value IssueFilter is an honest full enumeration — measured exact at 87, 700 and 2500 issues with no default page size — and it returns every status including closed and deferred, because the default hiding is CLI-side only. A safe Snapshot is buildable: count → list → count with a parity assertion and a REFUSAL on mismatch, mirroring internal/vikunja/board.go:95-99. See ah-wd4.1's close reason for the exact call, filter, assertion and the four traps (dead Offset, per-table limit fan-out, Statistics.TotalIssues excluding wisps, cross-table duplicate IDs).

So the decision is now a PRODUCT decision, not a technical one. The remaining questions for the full-swap-vs-hybrid-mirror call:
- Vikunja's kanban board is the human interface. beads has a Dolt web UI, but does dragging a card between buckets have an equivalent? The whole reconciler design rests on 'the board is the desired state owned by the human', and a human moving a card is the primary input.
- The Vikunja adapter is delivered, live-proven and defends against truncation already. What does the swap BUY — one datastore instead of two, and beads-native task hierarchy? Weigh that against re-proving a live path that currently works.
- A hybrid mirror means two sources of truth for the same card and a sync direction to define. That is usually worse than either pure option unless one side is strictly read-only.
- Note the notifier/board split: cards carry comments (result summaries, failure diagnostics, Q&A answers, delegation reports). Does beads have a comment surface a human reads as naturally?