relay-flow 0.2.7-alpha → 0.2.9-alpha

package/internal/task/jira/lifecycle_inheritance_test.go

@@ -16,7 +16,7 @@ import (
 //
 // The adapter therefore returns its inherited transitionTo/assignee values as
 // part of its lifecycle defaults, producing the effective precedence
-// built-in default < root < repo < workflow < node.
+// registered lifecycle value < root/repo inherited operation value < workflow < node.
 //
 // internal/task/beads/lifecycle_inheritance_test.go is the sibling of this
 // file and asserts the same invariants against the Beads adapter. Keep the two
@@ -26,7 +26,7 @@ import (
 // scopes that never appear in an ApplyTaskConfig argument.
 func repoScopedSystem(t *testing.T, fake *fakeJira, repoValues config.RawValues) task.System {
 	t.Helper()
-	repoConfig := config.Merge(config.RawValues{"project": "PAY", "component": "api"}, repoValues)
+	repoConfig := config.Merge(testRepoConfig(nil), repoValues)
 	sys, err := newSystem(context.Background(), &fakeClient{fake: fake}, task.RepoSpec{
 		Name:       "payments",
 		RepoConfig: repoConfig,
@@ -66,7 +66,7 @@ func TestLifecycleDefaultsCarryInheritedTransitionTo(t *testing.T) {
 			t.Fatal(err)
 		}
 		if len(fake.parentTransitions) != 1 || fake.parentTransitions[0] != "In Review" {
-			t.Fatalf("parent transitions = %v, want the inherited repo value to beat the built-in default",
+			t.Fatalf("parent transitions = %v, want the inherited repo value to beat the registered lifecycle value",
 				fake.parentTransitions)
 		}
 	})
@@ -82,7 +82,7 @@ func TestLifecycleDefaultsCarryInheritedTransitionTo(t *testing.T) {
 			t.Fatal(err)
 		}
 		if len(fake.taskTransitions) != 1 || fake.taskTransitions[0] != "In Review" {
-			t.Fatalf("mailbox transitions = %v, want the inherited repo value to beat the built-in default",
+			t.Fatalf("mailbox transitions = %v, want the inherited repo value to beat the registered lifecycle value",
 				fake.taskTransitions)
 		}
 	})
@@ -113,7 +113,7 @@ func TestLifecycleDefaultsPrecedenceDefaultRepoWorkflowNode(t *testing.T) {
 		node     config.RawValues
 		want     string
 	}{
-		{name: "repo beats built-in default", want: "Repo Status"},
+		{name: "repo operation value beats lifecycle value", want: "Repo Status"},
 		{
 			name:     "workflow beats repo",
 			workflow: config.RawValues{"transitionTo": map[string]any{"taskStatus": "Workflow Status"}},

package/internal/task/jira/rest/client.go

@@ -35,6 +35,14 @@ type CreatedSubtask struct {
 	Key string
 }
 
+// StatusProvider discovers the actual statuses configured for a Jira project.
+// It is intentionally separate from Client so existing adapter test doubles
+// and replaceable REST clients do not need provider-specific discovery unless
+// registration needs it.
+type StatusProvider interface {
+	Statuses(context.Context, string) ([]string, error)
+}
+
 type Client interface {
 	ValidateCredentials(context.Context) error
 	Search(context.Context, string) ([]byte, error)
@@ -70,6 +78,7 @@ type HTTPClient struct {
 	transitions  map[string]transitionInfo
 	accounts     map[string]string
 	statuses     map[string]map[string]bool
+	statusNames  map[string][]string
 	subtaskTypes map[string]string
 }
 
@@ -97,6 +106,7 @@ func New(site, email, token string) (*HTTPClient, error) {
 		transitions:  map[string]transitionInfo{},
 		accounts:     map[string]string{},
 		statuses:     map[string]map[string]bool{},
+		statusNames:  map[string][]string{},
 		subtaskTypes: map[string]string{},
 	}, nil
 }
@@ -186,43 +196,72 @@ func (c *HTTPClient) accountID(ctx context.Context, project, assignee string) (s
 	return "", fmt.Errorf("assignee %q is not assignable in project %s", assignee, project)
 }
 
+// Statuses returns the status names configured for all issue types in a Jira
+// project, preserving Jira's response order and removing case-insensitive
+// duplicates. The same discovery populates the subtask issue-type cache used
+// when mailboxes are created.
+func (c *HTTPClient) Statuses(ctx context.Context, project string) ([]string, error) {
+	_, names, err := c.loadStatuses(ctx, project)
+	if err != nil {
+		return nil, err
+	}
+	return append([]string(nil), names...), nil
+}
+
 func (c *HTTPClient) ValidateStatus(ctx context.Context, project, status string) error {
+	statuses, _, err := c.loadStatuses(ctx, project)
+	if err != nil {
+		return err
+	}
+	if !statuses[strings.ToLower(status)] {
+		return fmt.Errorf("status %q is not valid in project %s", status, project)
+	}
+	return nil
+}
+
+func (c *HTTPClient) loadStatuses(ctx context.Context, project string) (map[string]bool, []string, error) {
 	c.mu.Lock()
 	statuses, ok := c.statuses[project]
+	names := append([]string(nil), c.statusNames[project]...)
 	c.mu.Unlock()
-	if !ok {
-		var issueTypes []struct {
-			ID       string `json:"id"`
-			Subtask  bool   `json:"subtask"`
-			Statuses []struct {
-				Name string `json:"name"`
-			} `json:"statuses"`
-		}
-		path := "/rest/api/3/project/" + url.PathEscape(project) + "/statuses"
-		if err := c.request(ctx, http.MethodGet, path, nil, nil, &issueTypes, true); err != nil {
-			return err
-		}
-		statuses = map[string]bool{}
-		subtaskType := ""
-		for _, issueType := range issueTypes {
-			if issueType.Subtask && subtaskType == "" {
-				subtaskType = issueType.ID
-			}
-			for _, candidate := range issueType.Statuses {
-				statuses[strings.ToLower(candidate.Name)] = true
+	if ok {
+		return statuses, names, nil
+	}
+	var issueTypes []struct {
+		ID       string `json:"id"`
+		Subtask  bool   `json:"subtask"`
+		Statuses []struct {
+			Name string `json:"name"`
+		} `json:"statuses"`
+	}
+	path := "/rest/api/3/project/" + url.PathEscape(project) + "/statuses"
+	if err := c.request(ctx, http.MethodGet, path, nil, nil, &issueTypes, true); err != nil {
+		return nil, nil, err
+	}
+	statuses = map[string]bool{}
+	names = make([]string, 0)
+	subtaskType := ""
+	for _, issueType := range issueTypes {
+		if issueType.Subtask && subtaskType == "" {
+			subtaskType = issueType.ID
+		}
+		for _, candidate := range issueType.Statuses {
+			name := strings.TrimSpace(candidate.Name)
+			if name == "" || statuses[strings.ToLower(name)] {
+				continue
 			}
+			statuses[strings.ToLower(name)] = true
+			names = append(names, name)
 		}
-		c.mu.Lock()
-		c.statuses[project] = statuses
-		if subtaskType != "" {
-			c.subtaskTypes[project] = subtaskType
-		}
-		c.mu.Unlock()
 	}
-	if !statuses[strings.ToLower(status)] {
-		return fmt.Errorf("status %q is not valid in project %s", status, project)
+	c.mu.Lock()
+	c.statuses[project] = statuses
+	c.statusNames[project] = append([]string(nil), names...)
+	if subtaskType != "" {
+		c.subtaskTypes[project] = subtaskType
 	}
-	return nil
+	c.mu.Unlock()
+	return statuses, names, nil
 }
 
 func (c *HTTPClient) View(ctx context.Context, key string) ([]byte, error) {
@@ -251,7 +290,7 @@ func (c *HTTPClient) CreateSubtasks(ctx context.Context, parent, project, label
 	subtaskType := c.subtaskTypes[project]
 	c.mu.Unlock()
 	if subtaskType == "" {
-		if err := c.ValidateStatus(ctx, project, "To Do"); err != nil {
+		if _, _, err := c.loadStatuses(ctx, project); err != nil {
 			return nil, err
 		}
 		c.mu.Lock()
@@ -290,7 +329,10 @@ func (c *HTTPClient) CreateSubtasks(ctx context.Context, parent, project, label
 		}
 		created = append(created, result.Issues...)
 		for _, issue := range result.Issues {
-			c.setIssueState(issue.Key, "Sub-task", "To Do")
+			// Jira chooses the subtask's initial status from the project
+			// workflow. Leave the status unknown so the first transition reads
+			// the actual state instead of assuming a conventional name.
+			c.setIssueState(issue.Key, "Sub-task", "")
 		}
 	}
 	return created, nil

package/internal/task/jira/rest/client_test.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"reflect"
 	"strings"
 	"sync"
 	"testing"
@@ -93,6 +94,30 @@ func TestNewRejectsNonHTTPSRemoteSite(t *testing.T) {
 	}
 }
 
+func TestStatusesDiscoversProjectWorkflowStatuses(t *testing.T) {
+	s := newJiraServer(t, func(w http.ResponseWriter, r *http.Request, _ []byte) {
+		if r.Method != http.MethodGet || r.URL.Path != "/rest/api/3/project/PAY/statuses" {
+			http.NotFound(w, r)
+			return
+		}
+		writeJSON(w, []any{
+			map[string]any{"id": "100", "subtask": true, "statuses": []any{
+				map[string]any{"name": "Open"},
+				map[string]any{"name": "Working"},
+				map[string]any{"name": "Closed"},
+			}},
+		})
+	})
+	statuses, err := s.client(t).Statuses(context.Background(), "PAY")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"Open", "Working", "Closed"}
+	if !reflect.DeepEqual(statuses, want) {
+		t.Fatalf("statuses = %v, want %v", statuses, want)
+	}
+}
+
 func TestSearchPaginatesAndRequestsIssueLinks(t *testing.T) {
 	s := newJiraServer(t, func(w http.ResponseWriter, r *http.Request, body []byte) {
 		if r.URL.Path != "/rest/api/3/search/jql" || r.Method != http.MethodPost {

package/internal/task/jira/status_defaults_test.go

@@ -0,0 +1,134 @@
+package jira
+
+import (
+	"context"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+func TestStatusRegistrationDefaultsOnlySelectAvailableConventions(t *testing.T) {
+	withConventions := statusRegistrationField("statusDefaults.start", "Start", []string{"Open", "In Progress", "Closed"}, defaultStartParentStatus)
+	if withConventions.Default != defaultStartParentStatus {
+		t.Fatalf("default = %q, want %q", withConventions.Default, defaultStartParentStatus)
+	}
+	withoutConventions := statusRegistrationField("statusDefaults.end", "End", []string{"Open", "Working", "Closed"}, defaultEndParentStatus)
+	if withoutConventions.Default != "" {
+		t.Fatalf("missing conventional default = %q, want empty", withoutConventions.Default)
+	}
+	if !reflect.DeepEqual(withoutConventions.Options, []string{"Open", "Working", "Closed"}) {
+		t.Fatalf("options = %v", withoutConventions.Options)
+	}
+}
+
+func TestRepositoryStatusDefaultsDriveLifecycleAndMailboxCompletion(t *testing.T) {
+	fake := &fakeJira{}
+	sys, err := newSystem(context.Background(), &fakeClient{fake: fake}, task.RepoSpec{
+		Name: "payments",
+		RepoConfig: config.RawValues{
+			"project":   "PAY",
+			"component": "api",
+			"statusDefaults": map[string]any{
+				"start": "Open",
+				"work":  "Working",
+				"end":   "Closed",
+			},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defaults := task.LifecycleDefaults(sys)
+	parent := task.TicketRef{ID: "1", Key: "PAY-101"}
+	mailbox := task.Mailbox{ID: "2", Key: "PAY-102", Node: "coding"}
+
+	if err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent}, defaults.StartDefaults()); err != nil {
+		t.Fatal(err)
+	}
+	if err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent, Mailbox: &mailbox}, defaults.WorkDefaults()); err != nil {
+		t.Fatal(err)
+	}
+	if err := sys.CompleteMailbox(context.Background(), mailbox); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.parentTransitions) != 1 || fake.parentTransitions[0] != "Open" {
+		t.Fatalf("parent transitions = %v, want [Open]", fake.parentTransitions)
+	}
+	if len(fake.taskTransitions) != 2 || fake.taskTransitions[0] != "Working" || fake.taskTransitions[1] != "Closed" {
+		t.Fatalf("mailbox transitions = %v, want [Working Closed]", fake.taskTransitions)
+	}
+}
+
+func TestJiraRegistrationRejectsComponentOverride(t *testing.T) {
+	err := validateJiraRegistration(context.Background(), task.RepoRegistrationSpec{
+		Name: "payments",
+		RepoConfig: config.RawValues{
+			"project":   "PAY",
+			"component": "other-component",
+			"statusDefaults": map[string]any{
+				"start": "Open", "work": "Working", "end": "Closed",
+			},
+		},
+	})
+	if err == nil || !strings.Contains(err.Error(), "must match repository name") {
+		t.Fatalf("component override error = %v", err)
+	}
+}
+
+func TestJiraConstructionRejectsRootStatusDefaults(t *testing.T) {
+	_, err := newSystem(context.Background(), &fakeClient{fake: &fakeJira{}}, task.RepoSpec{
+		Name:       "payments",
+		RootConfig: config.RawValues{"statusDefaults": map[string]any{}},
+		RepoConfig: testRepoConfig(nil),
+	})
+	if err == nil || !strings.Contains(err.Error(), "configured per repository") {
+		t.Fatalf("root statusDefaults error = %v", err)
+	}
+}
+
+func TestJiraValidateConfigRejectsNonRepositoryStatusDefaults(t *testing.T) {
+	sys := newSystemWithFake(t, &fakeJira{})
+	for _, tc := range []struct {
+		name string
+		node bool
+	}{
+		{name: "workflow"},
+		{name: "node", node: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			workflowConfig := config.RawValues{}
+			nodeConfig := map[string]config.RawValues{}
+			if tc.node {
+				nodeConfig["coding"] = config.RawValues{"statusDefaults": map[string]any{}}
+			} else {
+				workflowConfig["statusDefaults"] = map[string]any{}
+			}
+			err := sys.ValidateConfig(context.Background(), workflowConfig, nodeConfig)
+			if err == nil || !strings.Contains(err.Error(), "configured per repository") {
+				t.Fatalf("validation error = %v", err)
+			}
+		})
+	}
+}
+
+func TestJiraConstructionRequiresCompleteRepositoryStatusDefaults(t *testing.T) {
+	for _, repoConfig := range []config.RawValues{
+		{"project": "PAY", "component": "api"},
+		{"project": "PAY", "component": "api", "statusDefaults": map[string]any{}},
+		{"project": "PAY", "component": "api", "statusDefaults": map[string]any{
+			"start": "Open", "work": "Working",
+		}},
+	} {
+		client := &validationClient{}
+		_, err := newSystem(context.Background(), client, task.RepoSpec{Name: "payments", RepoConfig: repoConfig})
+		if err == nil {
+			t.Fatalf("repo config %#v was accepted without complete status defaults", repoConfig)
+		}
+		if len(client.statuses) != 0 {
+			t.Fatalf("status probes = %v for invalid repository config, want none", client.statuses)
+		}
+	}
+}

package/internal/task/jira/templates_test.go

@@ -21,7 +21,7 @@ func TestTaskTextTemplatesExposeValues(t *testing.T) {
 			"summaryComment":     "summary {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{summaryReport}}",
 			"feedbackComment":    "feedback {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{feedbackReport}}",
 		}},
-		RepoConfig: config.RawValues{"project": "PAY", "component": "api"},
+		RepoConfig: testRepoConfig(nil),
 	})
 	if err != nil {
 		t.Fatal(err)
@@ -91,7 +91,7 @@ func TestTaskTemplatesRenderSharedReportContractValues(t *testing.T) {
 	}
 	fixture := fixtures["work"]
 	sys, err := newSystem(context.Background(), &fakeClient{fake: &fakeJira{}}, task.RepoSpec{
-		Name: "payments", RepoConfig: config.RawValues{"project": "PAY", "component": "api"},
+		Name: "payments", RepoConfig: testRepoConfig(nil),
 	})
 	if err != nil {
 		t.Fatal(err)

package/internal/task/jira/testdata/jira_search_issues.json

@@ -15,7 +15,7 @@
           "48x48": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png"
         },
         "displayName": "Raj Popat",
-        "emailAddress": "raj.popat@wolterskluwer.com",
+        "emailAddress": "test.user@example.com",
         "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/user?accountId=712020%3Adad5df85-a7bd-4337-b858-0faf9012a009",
         "timeZone": "America/New_York"
       },
@@ -48,7 +48,7 @@
     },
     "fieldsToInclude": null,
     "id": "157320",
-    "key": "GHCOS-41242",
+    "key": "DEMO-41242",
     "names": null,
     "operations": null,
     "properties": null,
@@ -74,7 +74,7 @@
           "48x48": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png"
         },
         "displayName": "Raj Popat",
-        "emailAddress": "raj.popat@wolterskluwer.com",
+        "emailAddress": "test.user@example.com",
         "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/user?accountId=712020%3Adad5df85-a7bd-4337-b858-0faf9012a009",
         "timeZone": "America/New_York"
       },
@@ -107,7 +107,7 @@
     },
     "fieldsToInclude": null,
     "id": "155110",
-    "key": "GHCOS-41175",
+    "key": "DEMO-41175",
     "names": null,
     "operations": null,
     "properties": null,

package/internal/task/jira/transition_defaults_test.go

@@ -10,11 +10,9 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/task"
 )
 
-// 3.5: Jira transition defaults per specs/workflow-definition "Jira
-// transition defaults are deterministic": omitted transitions default to
-// parent In Progress at start, mailbox In Progress at agent/HITL work
-// nodes, and parent Done at end; an omitted work-node parent transition
-// leaves the parent unchanged.
+// Jira repository status defaults are deterministic: omitted transitions use
+// the registered start/work/end values, and an omitted work-node parent
+// transition leaves the parent unchanged.
 //
 // This test is package-local (package jira) so it can drive the adapter's
 // ApplyTaskConfig against a test-local fake client without inventing an
@@ -128,10 +126,8 @@ func TestEndDefaultParentDone(t *testing.T) {
 	sys := newSystemWithFake(t, fake)
 	parent := task.TicketRef{ID: "1", Key: "PAY-101", Title: "parent"}
 
-	// end: omitted transitionTo. The end effective config carries no
-	// transition; the adapter must still default the parent to Done. Run
-	// orchestration merges EndDefaults under the end node config before
-	// applying it to the parent target.
+	// end: omitted transitionTo. Run orchestration merges the registered
+	// EndDefaults under the end node config before applying it to the parent.
 	endCfg := config.Merge(sys.(task.LifecycleDefaults).EndDefaults(), config.RawValues{})
 	if err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent}, endCfg); err != nil {
 		t.Fatalf("ApplyTaskConfig end failed: %v", err)
@@ -156,8 +152,8 @@ func TestPrepareRestartReopensMailboxesWithoutChangingParent(t *testing.T) {
 	if err := preparer.PrepareRestart(context.Background(), parent, mailboxes); err != nil {
 		t.Fatalf("PrepareRestart failed: %v", err)
 	}
-	if len(fake.taskTransitions) != 2 || fake.taskTransitions[0] != "To Do" || fake.taskTransitions[1] != "To Do" {
-		t.Fatalf("mailbox transitions = %v, want two To Do transitions", fake.taskTransitions)
+	if len(fake.taskTransitions) != 2 || fake.taskTransitions[0] != defaultStartParentStatus || fake.taskTransitions[1] != defaultStartParentStatus {
+		t.Fatalf("mailbox transitions = %v, want two %s transitions", fake.taskTransitions, defaultStartParentStatus)
 	}
 	if len(fake.parentTransitions) != 0 {
 		t.Fatalf("parent transitions = %v, want none (start owns parent status)", fake.parentTransitions)
@@ -165,7 +161,7 @@ func TestPrepareRestartReopensMailboxesWithoutChangingParent(t *testing.T) {
 }
 
 func TestPrepareRestartPreservesHumanJiraStateOnConflict(t *testing.T) {
-	fake := &fakeJira{transitionErr: errors.New(`transition to "To Do" is not available for PAY-102`)}
+	fake := &fakeJira{transitionErr: errors.New(`transition to "In Progress" is not available for PAY-102`)}
 	sys := newSystemWithFake(t, fake)
 	preparer := sys.(task.RestartPreparer)
 	err := preparer.PrepareRestart(context.Background(), task.TicketRef{Key: "PAY-101"}, []task.Mailbox{

package/internal/task/jira/validation_test.go

@@ -88,7 +88,9 @@ func TestValidateConfigProbesWorkflowAssignee(t *testing.T) {
 
 func taskSpec(root, repo config.RawValues) task.RepoSpec {
 	if repo == nil {
-		repo = config.RawValues{"project": "PAY", "component": "api"}
+		repo = testRepoConfig(nil)
+	} else {
+		repo = config.Merge(testRepoConfig(nil), repo)
 	}
 	return task.RepoSpec{Name: "payments", RootConfig: root, RepoConfig: repo}
 }

package/internal/task/registration.go

@@ -0,0 +1,59 @@
+package task
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+)
+
+// RegistrationField describes one task-plugin-owned repository-registration
+// value. The CLI only renders this metadata; it does not interpret provider
+// names or status vocabulary. A field with Options is rendered as a select,
+// otherwise it is rendered as free text. Derived fields are filled from the
+// runner candidate name and are never prompted.
+type RegistrationField struct {
+	Key     string   `json:"key"`
+	Title   string   `json:"title"`
+	Options []string `json:"options,omitempty"`
+	Default string   `json:"default,omitempty"`
+	Derived bool     `json:"derived,omitempty"`
+}
+
+// Registration describes the fields needed by a task plugin for one repo
+// registration.
+type Registration struct {
+	Fields []RegistrationField `json:"fields"`
+}
+
+// RegistrationFields returns task-plugin-owned registration metadata for the
+// supplied values. Values use the plugin's registration keys (including
+// dotted keys such as statusDefaults.start) and are intentionally opaque to
+// core.
+func RegistrationFields(ctx context.Context, name string, values config.RawValues) ([]RegistrationField, error) {
+	f, err := lookup(name)
+	if err != nil {
+		return nil, err
+	}
+	if f.RegistrationFields == nil {
+		return nil, fmt.Errorf("task plugin %q does not provide repository registration fields", name)
+	}
+	return f.RegistrationFields(ctx, values)
+}
+
+// ValidateRegistration lets a task plugin validate registration values,
+// including remote project/workflow metadata, before the repository is
+// persisted. Plugins that do not need this phase remain unchanged.
+func ValidateRegistration(ctx context.Context, name string, spec RepoRegistrationSpec) error {
+	f, err := lookup(name)
+	if err != nil {
+		return err
+	}
+	if f.ValidateRegistration == nil {
+		return nil
+	}
+	if err := f.ValidateRegistration(ctx, spec); err != nil {
+		return fmt.Errorf("task registration: %w", err)
+	}
+	return nil
+}

package/internal/workflow/workflow.go

@@ -62,6 +62,7 @@ type NudgeTemplateData struct {
 	Workflow   string
 	Repo       string
 	Node       string
+	Mailbox    string
 	NextSteps  string
 }
 
@@ -70,7 +71,7 @@ var namePattern = regexp.MustCompile(`^[a-z][a-zA-Z0-9]*$`)
 var nudgeVarPattern = regexp.MustCompile(`\{\{([^{}]*)\}\}`)
 
 var knownNudgeVars = map[string]bool{
-	"taskSystem": true, "ticket": true, "workflow": true, "repo": true, "node": true, "nextSteps": true,
+	"taskSystem": true, "ticket": true, "workflow": true, "repo": true, "node": true, "mailbox": true, "nextSteps": true,
 }
 
 // Parse strictly decodes a workflow YAML document. Unknown fields and
@@ -326,6 +327,8 @@ func (w *Workflow) RenderNudge(node string, data NudgeTemplateData) (string, err
 			return data.Repo
 		case "node":
 			return data.Node
+		case "mailbox":
+			return data.Mailbox
 		case "nextSteps":
 			return data.NextSteps
 		}

package/internal/workflow/workflow_test.go

@@ -350,7 +350,7 @@ func TestValidateGraphReachability(t *testing.T) {
 
 func TestValidateNudgeTemplate(t *testing.T) {
 	t.Run("supported variables", func(t *testing.T) {
-		yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"{{taskSystem}} {{ticket}} {{workflow}} {{repo}} {{node}} {{nextSteps}}\"", 1)
+		yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"{{taskSystem}} {{ticket}} {{workflow}} {{repo}} {{node}} {{mailbox}} {{nextSteps}}\"", 1)
 		wf := parse(t, "basicFlow", yaml)
 		if err := wf.Validate(); err != nil {
 			t.Fatalf("supported nudge variables rejected: %v", err)
@@ -389,16 +389,16 @@ func TestCleanupRunnerOnEndDefaultsFalse(t *testing.T) {
 }
 
 func TestRenderNudge(t *testing.T) {
-	yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"task={{taskSystem}} ticket={{ticket}} wf={{workflow}} repo={{repo}} node={{node}} steps={{nextSteps}}\"", 1)
+	yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"task={{taskSystem}} ticket={{ticket}} wf={{workflow}} repo={{repo}} node={{node}} mailbox={{mailbox}} steps={{nextSteps}}\"", 1)
 	wf := parse(t, "basicFlow", yaml)
 	for _, taskSystem := range []string{"jira", "linear"} {
 		out, err := wf.RenderNudge("coding", workflow.NudgeTemplateData{
-			TaskSystem: taskSystem, Ticket: "PAY-101", Workflow: "basicFlow", Repo: "payments", Node: "coding", NextSteps: "end",
+			TaskSystem: taskSystem, Ticket: "PAY-101", Workflow: "basicFlow", Repo: "payments", Node: "coding", Mailbox: "PAY-101.1", NextSteps: "end",
 		})
 		if err != nil {
 			t.Fatalf("RenderNudge(%s) failed: %v", taskSystem, err)
 		}
-		want := "task=" + taskSystem + " ticket=PAY-101 wf=basicFlow repo=payments node=coding steps=end"
+		want := "task=" + taskSystem + " ticket=PAY-101 wf=basicFlow repo=payments node=coding mailbox=PAY-101.1 steps=end"
 		if out != want {
 			t.Fatalf("RenderNudge(%s) = %q, want %q", taskSystem, out, want)
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-flow",
-  "version": "0.2.7-alpha",
+  "version": "0.2.9-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",