Route-then-mirror is not atomic: a failure between the two writes strands an Outcome on Next while Actionless

[capo-the-ai-bot]

User Story

As a user whose device dies or loses the race mid-route, I want an Outcome to never come to rest on Next with no Action, so it does not sit in the re-clarification queue forever waiting for a step that already half-happened.

Context

Several surfaces route an Outcome to Next and then, in a second write, mirror the Outcome's title into its current Action when the Outcome is Actionless (the title-as-action fallback — an empty next-action phrase means the Outcome's title, written only while the Outcome is Actionless; issue #691). The two writes are not atomic:

await _commit(RoutingKind.nextAction, actionText: …);   // write 1: intent, clarified, stamp
await …mirrorTitleIfActionless(id, title);              // write 2: the Action

A throw, a crash, or an unlucky interleaving between them leaves the row on Next and Actionless. That state is not self-correcting in a benign way: TodoDao._needsReviewWhere's Actionless branch has no freshness gate, so the Outcome re-surfaces in the Daily Planning re-clarification queue every morning until it acquires an Action.

Raised by CodeRabbit on PR #707 and deferred there deliberately: it is a class, not a single site, and the repo's policy is that class-wide surveys get their own PR.

Known sites (verify and extend — this list is a starting point, not a survey)

• app/lib/widgets/process_to_handlers.dart — _nextWithDialog's blank-save branch, via ClarificationService.mirrorTitleIfActionless.
• app/lib/widgets/clarify_card.dart — _onAfterRoute ships the identical route-then-mirror shape and predates PR fix(clarify): fall back to the title on an empty next-action save (#691) #707.

Scope

• Survey the class: find every site that routes and then mirrors (or otherwise completes) in a second write.
• Make the route and its Action write commit together, so the row is never observably on Next while Actionless. TodoDao.setCurrentActionTextIfActionless is already atomic in itself; what is missing is a primitive that commits it with the routing.
• Prefer one new DAO/service primitive that all sites adopt over per-site patching — two independent fixes would re-create the drift this issue exists to remove.
• Update any fakes/test doubles that stand in for the service, and cover the interleaving with a test rather than only the happy path.

Acceptance Criteria

• Routing to Next with a title-as-action fallback commits the intent and the Action in one transaction.
• A failure injected between the old two writes cannot leave the row on Next and Actionless.
• Every site in the surveyed class uses the same primitive; none retains a bespoke route-then-mirror pair.
• Regression test drives the interleaving directly and is proven to fail against the current two-write shape.
• No behavioural change to the cancel path or the blank-title stall (both must still leave the item unresolved).

Out of Scope

• The Waiting For half of the title-as-action policy. It is currently applied only on clarify surfaces (ClarifyDraft.assemble, ClarifyCard's mirror) and not by ProcessToHandlers._waitingFor, which is documented as intent-only. That mismatch is recorded as a Flagged ambiguity in CONTEXT.md § GTD Core and wants its own decision, not a fix bundled here.
• _needsReviewWhere's missing freshness gate on the Actionless branch — that is the behaviour that makes this bug persistent, but it is deliberate (an Actionless Outcome genuinely does need attention).

Related

• Saving an empty next action during review should resolve the item as Next and advance, not stall on the item #691 / PR fix(clarify): fall back to the title on an empty next-action save (#691) #707 — introduced mirrorTitleIfActionless and the two-write shape at this site; deferred this finding.
• The title-as-action fallback policy this concerns is stated in app/lib/widgets/process_to_handlers.dart (_nextWithDialog's dartdoc — cancel vs blank save, and the blank-title stall) and TodoDao.setCurrentActionTextIfActionless. It had an ADR, 0049-empty-next-action-means-the-title.md, removed in 816381a6 as one of the bug-fix ADRs; its reasoning is recoverable with git show 816381a6^:docs/adr/0049-empty-next-action-means-the-title.md.
• Routing handlers check subject existence outside the write transaction (TOCTOU) #444 — routing handlers check subject existence outside the write transaction (the same "a write only counts if it landed" family).
• app/lib/database/daos/todo_dao.dart — setCurrentActionTextIfActionless, _needsReviewWhere.

[capo-the-ai-bot]

Additional consequence from the originating review thread (PR #707), worth capturing because it is user-visible rather than just a data-state problem:

If the mirror write throws, _runOnce reports the route as failed and therefore does not advance the review. So the failure mode is not only "row stranded on Next while Actionless" — it is also the user being held on the same card, which is precisely the stall #691 exists to remove. The route has already committed at that point, so the item is simultaneously resolved in the store and unresolved in the UI.

Add to the acceptance criteria:

• A failure in the Action write does not leave the review advanced-in-store but stalled-on-screen; the route and the advance agree.