Add item lifecycle state machine with location-aware push strategy

Formalize the wanted item lifecycle as a first-class state machine so
the TUI and command handlers share one source of truth for valid
transitions. Add location detection (local/origin/upstream) and
choose the minimum push operation per transition in PR mode.

- lifecycle.go: ValidateTransition(), DetectItemLocation(), ResolvePushTarget()
- lifecycle_test.go: table-driven tests for all transitions + push strategies
- dolt.go: QueryItemStatusAsOf() using AS OF syntax
- branch_helpers.go: location field, location-aware Push(), PR description refresh
- pr_refresh.go: auto-update GitHub/DoltHub PR body after branch push
- 8 command handlers: replace inline status checks with ValidateTransition()

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: julianknutsen

cmd/wl/branch_helpers.go

@@ -18,6 +18,7 @@ type mutationContext struct {
 	branch   string // computed branch name, empty in wild-west mode
 	noPush   bool
 	stdout   io.Writer
+	location *commons.ItemLocation // detected item location across remotes
 }
 
 // newMutationContext creates a mutation context for the given config and wanted ID.
@@ -39,8 +40,8 @@ func (m *mutationContext) BranchName() string {
 	return m.branch
 }
 
-// Setup prepares the mutation context: checks dolt, syncs upstream, and
-// (in PR mode) checks out the item branch.
+// Setup prepares the mutation context: checks dolt, syncs upstream, detects
+// item location, and (in PR mode) checks out the item branch.
 // The returned cleanup function must be deferred to return to main.
 func (m *mutationContext) Setup() (cleanup func(), err error) {
 	noop := func() {}
@@ -53,6 +54,13 @@ func (m *mutationContext) Setup() (cleanup func(), err error) {
 	if syncErr != nil {
 		fmt.Fprintf(m.stdout, "  warning: upstream sync failed: %v\n", syncErr)
 	}
+
+	// Detect item location across remotes (best-effort).
+	if m.wantedID != "" {
+		loc, _ := commons.DetectItemLocation(m.cfg.LocalDir, m.wantedID)
+		m.location = loc
+	}
+
 	if m.branch == "" {
 		return noop, nil
 	}
@@ -65,14 +73,49 @@ func (m *mutationContext) Setup() (cleanup func(), err error) {
 }
 
 // Push pushes changes to the appropriate remote(s).
+// Uses location detection in PR mode to minimize push operations.
 // In wild-west mode: PushWithSync (upstream + origin).
-// In PR mode: PushBranch (origin only).
+// In PR mode with branches: PushBranch (origin only).
+// In PR mode on main: uses ResolvePushTarget for location-aware pushing.
 func (m *mutationContext) Push() error {
 	if m.noPush {
 		return nil
 	}
+	// PR mode with branch — push branch to origin, then refresh any existing PR.
 	if m.branch != "" {
-		return commons.PushBranch(m.cfg.LocalDir, m.branch, m.stdout)
+		if err := commons.PushBranch(m.cfg.LocalDir, m.branch, m.stdout); err != nil {
+			return err
+		}
+		m.refreshPR()
+		return nil
+	}
+
+	// Wild-west mode without location info — existing behavior.
+	if m.location == nil || m.cfg.ResolveMode() != federation.ModePR {
+		return commons.PushWithSync(m.cfg.LocalDir, m.stdout)
+	}
+
+	// PR mode on main — use location-aware push.
+	// Re-read local status after the mutation has been applied.
+	m.location.LocalStatus = commons.QueryItemStatusAsOf(m.cfg.LocalDir, m.wantedID, "")
+	target := commons.ResolvePushTarget("pr", m.location)
+
+	if target.PushUpstream {
+		return commons.PushWithSync(m.cfg.LocalDir, m.stdout)
+	}
+	if target.PushOrigin {
+		if err := commons.PushOriginMain(m.cfg.LocalDir, m.stdout); err != nil {
+			return err
+		}
+	}
+
+	m.printHint(target)
+	return nil
+}
+
+// printHint shows a next-step hint based on the push target.
+func (m *mutationContext) printHint(target commons.PushTarget) {
+	if target.Hint != "" {
+		fmt.Fprintf(m.stdout, "  %s\n", style.Dim.Render(target.Hint))
 	}
-	return commons.PushWithSync(m.cfg.LocalDir, m.stdout)
 }

cmd/wl/cmd_accept.go

@@ -152,8 +152,8 @@ func acceptCompletion(store commons.WLCommonsStore, wantedID, rigHandle string,
 		return nil, fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "in_review" {
-		return nil, fmt.Errorf("wanted item %s is not in_review (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionAccept); err != nil {
+		return nil, fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if item.PostedBy != rigHandle {

cmd/wl/cmd_claim.go

@@ -88,8 +88,8 @@ func claimWanted(store commons.WLCommonsStore, wantedID, rigHandle string) (*com
 		return nil, fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "open" {
-		return nil, fmt.Errorf("wanted item %s is not open (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionClaim); err != nil {
+		return nil, fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if err := store.ClaimWanted(wantedID, rigHandle); err != nil {

cmd/wl/cmd_close.go

@@ -87,8 +87,8 @@ func closeWanted(store commons.WLCommonsStore, wantedID, rigHandle string) error
 		return fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "in_review" {
-		return fmt.Errorf("wanted item %s is not in_review (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionClose); err != nil {
+		return fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if item.PostedBy != rigHandle {

cmd/wl/cmd_delete.go

@@ -85,8 +85,8 @@ func deleteWanted(store commons.WLCommonsStore, wantedID string) error {
 		return fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "open" {
-		return fmt.Errorf("wanted item %s is not open (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionDelete); err != nil {
+		return fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if err := store.DeleteWanted(wantedID); err != nil {

cmd/wl/cmd_done.go

@@ -102,8 +102,8 @@ func submitDone(store commons.WLCommonsStore, wantedID, rigHandle, evidence, com
 		return fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "claimed" {
-		return fmt.Errorf("wanted item %s is not claimed (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionDone); err != nil {
+		return fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if item.ClaimedBy != rigHandle {

cmd/wl/cmd_reject.go

@@ -94,8 +94,8 @@ func rejectCompletion(store commons.WLCommonsStore, wantedID, rigHandle, reason
 		return fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "in_review" {
-		return fmt.Errorf("wanted item %s is not in_review (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionReject); err != nil {
+		return fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if item.PostedBy != rigHandle {

cmd/wl/cmd_unclaim.go

@@ -87,8 +87,8 @@ func unclaimWanted(store commons.WLCommonsStore, wantedID, rigHandle string) (*c
 		return nil, fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "claimed" {
-		return nil, fmt.Errorf("wanted item %s is not claimed (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionUnclaim); err != nil {
+		return nil, fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if item.ClaimedBy != rigHandle && item.PostedBy != rigHandle {

cmd/wl/cmd_update.go

@@ -160,8 +160,8 @@ func updateWanted(store commons.WLCommonsStore, wantedID string, fields *commons
 		return fmt.Errorf("querying wanted item: %w", err)
 	}
 
-	if item.Status != "open" {
-		return fmt.Errorf("wanted item %s is not open (status: %s)", wantedID, item.Status)
+	if _, err := commons.ValidateTransition(item.Status, commons.TransitionUpdate); err != nil {
+		return fmt.Errorf("wanted item %s: %w", wantedID, err)
 	}
 
 	if err := store.UpdateWanted(wantedID, fields); err != nil {

cmd/wl/pr_refresh.go

@@ -0,0 +1,102 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"os/exec"
+
+	"github.com/julianknutsen/wasteland/internal/federation"
+	"github.com/julianknutsen/wasteland/internal/remote"
+)
+
+// refreshPR updates the description of an existing PR after a successful push.
+// Best-effort: failures print a warning but don't block the mutation.
+func (m *mutationContext) refreshPR() {
+	if m.branch == "" {
+		return
+	}
+
+	switch m.cfg.ResolveProviderType() {
+	case "github":
+		m.refreshGitHubPR()
+	case "dolthub":
+		m.refreshDoltHubPR()
+	}
+}
+
+func (m *mutationContext) refreshGitHubPR() {
+	ghPath, err := exec.LookPath("gh")
+	if err != nil {
+		return
+	}
+
+	client := newGHClient(ghPath)
+	head := m.cfg.ForkOrg + ":" + m.branch
+	_, number := client.FindPR(m.cfg.Upstream, head)
+	if number == "" {
+		return
+	}
+
+	body, err := m.generateDiffMarkdown()
+	if err != nil {
+		return
+	}
+
+	if err := client.UpdatePR(m.cfg.Upstream, number, map[string]string{"body": body}); err != nil {
+		fmt.Fprintf(m.stdout, "  warning: could not update PR description: %v\n", err)
+		return
+	}
+	fmt.Fprintf(m.stdout, "  Updated PR description\n")
+}
+
+func (m *mutationContext) refreshDoltHubPR() {
+	token := os.Getenv("DOLTHUB_TOKEN")
+	if token == "" {
+		return
+	}
+
+	upstreamOrg, db, err := federation.ParseUpstream(m.cfg.Upstream)
+	if err != nil {
+		return
+	}
+
+	provider := remote.NewDoltHubProvider(token)
+	_, prID := provider.FindPR(upstreamOrg, db, m.cfg.ForkOrg, m.branch)
+	if prID == "" {
+		return
+	}
+
+	body, err := m.generateDiffMarkdown()
+	if err != nil {
+		return
+	}
+
+	doltPath, _ := exec.LookPath("dolt")
+	title := wantedTitleFromBranch(doltPath, m.cfg.LocalDir, m.branch)
+	prTitle := fmt.Sprintf("[wl] %s", title)
+
+	if err := provider.UpdatePR(upstreamOrg, db, prID, prTitle, body); err != nil {
+		fmt.Fprintf(m.stdout, "  warning: could not update PR description: %v\n", err)
+		return
+	}
+	fmt.Fprintf(m.stdout, "  Updated PR description\n")
+}
+
+// generateDiffMarkdown renders a markdown diff between the branch and its base.
+// Uses three-dot diff (base...branch) which compares refs directly and does
+// not depend on the current checkout.
+func (m *mutationContext) generateDiffMarkdown() (string, error) {
+	doltPath, err := exec.LookPath("dolt")
+	if err != nil {
+		return "", err
+	}
+
+	base := diffBase(m.cfg.LocalDir, doltPath)
+
+	var buf bytes.Buffer
+	if err := renderMarkdownDiff(&buf, m.cfg.LocalDir, doltPath, m.branch, base); err != nil {
+		return "", err
+	}
+	return buf.String(), nil
+}