relay-flow 0.3.9-alpha → 0.3.11-alpha

package/internal/task/jira/helpers_test.go

@@ -24,6 +24,9 @@ func (f *fakeClient) ValidateAssignee(context.Context, string, string) error { r
 func (f *fakeClient) ValidateStatus(context.Context, string, string) error { return nil }
 
 func (f *fakeClient) View(context.Context, string) ([]byte, error) {
+	if f.fake.viewJSON != nil {
+		return f.fake.viewJSON, nil
+	}
 	return []byte(`{"fields":{"labels":[],"subtasks":[]}}`), nil
 }
 
@@ -46,8 +49,14 @@ func (f *fakeClient) Transition(_ context.Context, key, status, assignee string)
 	return nil
 }
 
-func (f *fakeClient) EnsureLabel(_ context.Context, key, label string) error {
-	f.fake.labelCalls = append(f.fake.labelCalls, key+":"+label)
+func (f *fakeClient) EnsureLabel(ctx context.Context, key, label string) error {
+	return f.EnsureLabels(ctx, key, []string{label})
+}
+
+func (f *fakeClient) EnsureLabels(_ context.Context, key string, labels []string) error {
+	for _, label := range labels {
+		f.fake.labelCalls = append(f.fake.labelCalls, key+":"+label)
+	}
 	return nil
 }
 

package/internal/task/jira/jira.go

@@ -4,6 +4,8 @@ package jira
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -64,17 +66,16 @@ const (
 	defaultWorkTaskStatus     = "In Progress"
 	defaultEndParentStatus    = "Done"
 	currentUserAssigneeFilter = "currentUser()"
-	defaultMailboxDescription = `Parent ticket: {{ticket}}
-Workflow: {{workflow}}
-Node: {{node}}
-Node type: {{nodeType}}
-Agent: {{agent}}
-Mailbox: {{mailbox}}
-
-Node work:
+	defaultMailboxDescription = `{{ticket}} / {{node}} — {{nodeType}} — {{agent}}
 {{nodeDescription}}
 
-Read this mailbox's comments for feedback from previous nodes.`
+Success routes:
+{{successRoutes}}
+
+Failure routes:
+{{failureRoutes}}
+
+{{report}}`
 	defaultSummaryComment = `Summary for {{node}}
 
 {{summaryReport}}`
@@ -91,6 +92,7 @@ var knownTextVars = map[string]bool{
 	"nodeDescription": true, "nextSteps": true, "successRoutes": true,
 	"failureRoutes": true, "mailbox": true, "sourceNode": true,
 	"targetNode": true, "summaryReport": true, "feedbackReport": true,
+	"report": true,
 }
 
 // DefaultConfig supplies Jira task-system text defaults for relay-flow init.
@@ -113,6 +115,72 @@ var (
 // claimLabel is the permanent workflow claim label.
 func claimLabel(workflow string) string { return "wf:" + workflow }
 
+// claimOwnerLabel is a durable provider-owned provenance label. The owner
+// identity is hashed so the marker does not expose an email address in Jira
+// labels; the adapter compares it with the same normalized assignee identities
+// used by filters. A marker remains after reassignment, so another server
+// cannot silently take over an existing wf: claim. Only an explicit
+// provider-side handoff may replace it; automatic routing never does.
+const claimOwnerLabelPrefix = "wf-owner:"
+
+func claimOwnerToken(owner string) string {
+	owner = strings.ToLower(strings.TrimSpace(owner))
+	if owner == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(owner))
+	return hex.EncodeToString(sum[:])
+}
+
+func claimOwnerLabel(workflow, owner string) string {
+	token := claimOwnerToken(owner)
+	if token == "" {
+		return ""
+	}
+	return claimOwnerLabelPrefix + workflow + ":" + token
+}
+
+func claimOwnerMarkers(labels []string, workflow string) []string {
+	prefix := claimOwnerLabelPrefix + workflow + ":"
+	markers := make([]string, 0, 1)
+	for _, label := range labels {
+		if strings.HasPrefix(label, prefix) {
+			markers = append(markers, label)
+		}
+	}
+	return markers
+}
+
+func hasForeignClaimOwnerMarker(labels []string, workflow string) bool {
+	currentPrefix := claimOwnerLabelPrefix + workflow + ":"
+	for _, label := range labels {
+		if strings.HasPrefix(label, claimOwnerLabelPrefix) && !strings.HasPrefix(label, currentPrefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func claimOwnerMatches(labels []string, workflow string, assignees []string) bool {
+	markers := claimOwnerMarkers(labels, workflow)
+	if len(markers) != 1 {
+		return false
+	}
+	for _, assignee := range assignees {
+		if markers[0] == claimOwnerLabel(workflow, assignee) {
+			return true
+		}
+	}
+	return false
+}
+
+func claimedWorkflow(ticket task.Ticket) string {
+	if len(ticket.WorkflowClaims) != 1 || !strings.HasPrefix(ticket.WorkflowClaims[0], "wf:") {
+		return ""
+	}
+	return strings.TrimPrefix(ticket.WorkflowClaims[0], "wf:")
+}
+
 func jiraRegistrationFields(ctx context.Context, values config.RawValues) ([]task.RegistrationField, error) {
 	fields := []task.RegistrationField{
 		{Key: "project", Title: "Jira project"},
@@ -441,6 +509,11 @@ func validateTemplates(templates Templates) error {
 			}
 		}
 	}
+	for _, key := range []string{"report", "ticket", "node", "nodeType", "agent", "nodeDescription", "successRoutes", "failureRoutes"} {
+		if !strings.Contains(templates.MailboxDescription, "{{"+key+"}}") {
+			return fmt.Errorf("mailboxDescription must contain {{%s}}", key)
+		}
+	}
 	if !strings.Contains(templates.SummaryComment, "{{summaryReport}}") {
 		return fmt.Errorf("summaryComment must contain {{summaryReport}}")
 	}
@@ -467,11 +540,11 @@ func (s *system) RenderText(kind task.TextKind, data task.TextData) (string, err
 		"runID": data.RunID, "ticket": data.Ticket,
 		"workflow": data.Workflow, "repo": data.Repo, "node": data.Node,
 		"nodeType": data.NodeType, "agent": data.Agent,
-		"nodeDescription": data.NodeDescription, "nextSteps": data.NextSteps,
+		"nodeDescription": strings.ReplaceAll(data.NodeDescription, "{{ticket}}", data.Ticket), "nextSteps": data.NextSteps,
 		"successRoutes": data.SuccessRoutes, "failureRoutes": data.FailureRoutes,
 		"mailbox": data.Mailbox, "sourceNode": data.SourceNode,
 		"targetNode": data.TargetNode, "summaryReport": data.SummaryReport,
-		"feedbackReport": data.FeedbackReport,
+		"feedbackReport": data.FeedbackReport, "report": data.Report,
 	}
 	return textVarPattern.ReplaceAllStringFunc(tmpl, func(match string) string {
 		return values[textVarPattern.FindStringSubmatch(match)[1]]
@@ -566,14 +639,165 @@ func (s *system) resolveAssigneeFilters(values []string) ([]string, error) {
 	return resolved, nil
 }
 
+// CompileOwnershipFilter compiles only the effective assignee predicate used
+// to isolate claimed tickets. Lifecycle fields deliberately do not enter this
+// matcher because claimed routing must survive status and label changes.
+func (s *system) CompileOwnershipFilter(workflowTaskConfig config.RawValues) (func(task.Ticket) bool, error) {
+	merged := config.Merge(s.base, workflowTaskConfig)
+	cfg, err := decodeConfig(merged)
+	if err != nil {
+		return nil, err
+	}
+	assignees, err := s.resolveAssigneeFilters(cfg.Filters.Assignees)
+	if err != nil {
+		return nil, err
+	}
+	return func(ticket task.Ticket) bool {
+		if len(assignees) == 0 {
+			return true
+		}
+		workflow := claimedWorkflow(ticket)
+		owner := strField(ticket.Fields, "assignee")
+		return workflow != "" && containsFold(assignees, owner) &&
+			claimOwnerMatches(strSliceField(ticket.Fields, "labels"), workflow, []string{owner})
+	}, nil
+}
+
+func (s *system) ownershipAssignees(workflowTaskConfig config.RawValues) ([]string, error) {
+	merged := config.Merge(s.base, workflowTaskConfig)
+	cfg, err := decodeConfig(merged)
+	if err != nil {
+		return nil, err
+	}
+	return s.resolveAssigneeFilters(cfg.Filters.Assignees)
+}
+
 // --- Claim ---
 
 // Claim adds wf:<workflow> using the claims already inspected by routing.
-// Jira's label-add operation is idempotent.
+// Jira's label-add operation is idempotent. Automatic routing uses
+// ClaimIfOwned so the final ownership read happens immediately before this
+// write; this narrow method remains the task.System primitive.
 func (s *system) Claim(ctx context.Context, ticket task.TicketRef, workflow string) error {
 	return s.cli.EnsureLabel(ctx, ticket.Key, claimLabel(workflow))
 }
 
+// ValidateOwnership re-reads the current Jira assignee and claim-owner
+// marker. Both must satisfy the effective ownership filter; the provenance
+// marker additionally prevents a different owner from taking over a claim.
+func (s *system) ValidateOwnership(ctx context.Context, ticket task.TicketRef, workflow string, workflowTaskConfig config.RawValues) error {
+	assignees, err := s.ownershipAssignees(workflowTaskConfig)
+	if err != nil {
+		return err
+	}
+	if len(assignees) == 0 {
+		return nil
+	}
+	key := ticket.Key
+	if strings.TrimSpace(key) == "" {
+		key = ticket.ID
+	}
+	raw, err := s.cli.View(ctx, key)
+	if err != nil {
+		return fmt.Errorf("jira: read ticket %s ownership: %w", key, err)
+	}
+	current, err := normalizeIssue(raw)
+	if err != nil {
+		return fmt.Errorf("jira: parse ticket %s ownership: %w", key, err)
+	}
+	owner := strField(current.Fields, "assignee")
+	if !containsFold(assignees, owner) ||
+		!claimOwnerMatches(strSliceField(current.Fields, "labels"), workflow, []string{owner}) {
+		return &task.OwnershipMismatchError{Ticket: key, Workflow: workflow}
+	}
+	return nil
+}
+
+// ClaimIfOwned closes the poll-to-claim race with an adapter-owned final
+// read/check immediately before the idempotent Jira label update. The owner
+// marker is written before the wf: label so a crash cannot leave a new claim
+// with no provenance; a later poll can finish the idempotent label update.
+func (s *system) ClaimIfOwned(ctx context.Context, ticket task.TicketRef, workflow string, workflowTaskConfig config.RawValues) error {
+	assignees, err := s.ownershipAssignees(workflowTaskConfig)
+	if err != nil {
+		return err
+	}
+	if len(assignees) == 0 {
+		return s.Claim(ctx, ticket, workflow)
+	}
+	key := ticket.Key
+	if strings.TrimSpace(key) == "" {
+		key = ticket.ID
+	}
+	raw, err := s.cli.View(ctx, key)
+	if err != nil {
+		return fmt.Errorf("jira: read ticket %s before claim: %w", key, err)
+	}
+	current, err := normalizeIssue(raw)
+	if err != nil {
+		return fmt.Errorf("jira: parse ticket %s before claim: %w", key, err)
+	}
+	owner := strField(current.Fields, "assignee")
+	if !containsFold(assignees, owner) {
+		return &task.OwnershipMismatchError{Ticket: key, Workflow: workflow}
+	}
+	labels := strSliceField(current.Fields, "labels")
+	markers := claimOwnerMarkers(labels, workflow)
+	if hasForeignClaimOwnerMarker(labels, workflow) || len(markers) > 1 || (len(markers) == 1 && !claimOwnerMatches(labels, workflow, []string{owner})) {
+		return &task.OwnershipMismatchError{Ticket: key, Workflow: workflow}
+	}
+	if len(current.WorkflowClaims) > 0 {
+		if len(current.WorkflowClaims) != 1 || current.WorkflowClaims[0] != claimLabel(workflow) || len(markers) != 1 {
+			return &task.OwnershipMismatchError{Ticket: key, Workflow: workflow}
+		}
+		return s.cli.EnsureLabels(ctx, key, []string{markers[0], claimLabel(workflow)})
+	}
+	ownerLabel := claimOwnerLabel(workflow, owner)
+	if ownerLabel == "" {
+		return &task.OwnershipMismatchError{Ticket: key, Workflow: workflow}
+	}
+	return s.cli.EnsureLabels(ctx, key, []string{ownerLabel, claimLabel(workflow)})
+}
+
+// BackfillClaimOwner is an explicit repair operation for a legacy claim that
+// has no provenance marker. It never removes labels or comments and is not
+// called by automatic routing; an operator/provider handoff must invoke it.
+func (s *system) BackfillClaimOwner(ctx context.Context, ticket task.TicketRef, workflow string, workflowTaskConfig config.RawValues) error {
+	assignees, err := s.ownershipAssignees(workflowTaskConfig)
+	if err != nil {
+		return err
+	}
+	if len(assignees) == 0 {
+		return nil
+	}
+	key := ticket.Key
+	if strings.TrimSpace(key) == "" {
+		key = ticket.ID
+	}
+	raw, err := s.cli.View(ctx, key)
+	if err != nil {
+		return fmt.Errorf("jira: read ticket %s for ownership backfill: %w", key, err)
+	}
+	current, err := normalizeIssue(raw)
+	if err != nil {
+		return fmt.Errorf("jira: parse ticket %s for ownership backfill: %w", key, err)
+	}
+	owner := strField(current.Fields, "assignee")
+	if !containsFold(assignees, owner) ||
+		len(current.WorkflowClaims) != 1 || current.WorkflowClaims[0] != claimLabel(workflow) {
+		return &task.OwnershipMismatchError{Ticket: key, Workflow: workflow}
+	}
+	labels := strSliceField(current.Fields, "labels")
+	markers := claimOwnerMarkers(labels, workflow)
+	if len(markers) > 1 || (len(markers) == 1 && !claimOwnerMatches(labels, workflow, []string{owner})) {
+		return &task.OwnershipMismatchError{Ticket: key, Workflow: workflow}
+	}
+	if len(markers) == 1 {
+		return nil
+	}
+	return s.cli.EnsureLabels(ctx, key, []string{claimOwnerLabel(workflow, owner)})
+}
+
 // --- Config validation ---
 
 // ValidateConfig strictly validates the workflow and every node task config
@@ -917,7 +1141,12 @@ func strSliceField(fields map[string]any, key string) []string {
 }
 
 var (
-	_ task.System            = (*system)(nil)
-	_ task.LifecycleDefaults = (*system)(nil)
-	_ task.RestartPreparer   = (*system)(nil)
+	_ task.System                  = (*system)(nil)
+	_ task.OwnershipCapabilities   = (*system)(nil)
+	_ task.OwnershipFilterCompiler = (*system)(nil)
+	_ task.OwnershipValidator      = (*system)(nil)
+	_ task.ConditionalClaimer      = (*system)(nil)
+	_ task.ClaimOwnerBackfiller    = (*system)(nil)
+	_ task.LifecycleDefaults       = (*system)(nil)
+	_ task.RestartPreparer         = (*system)(nil)
 )

package/internal/task/jira/normalize.go

@@ -66,25 +66,40 @@ func normalizeSearchResponse(raw []byte) ([]task.Ticket, error) {
 		if hasOpenBlocker(issue) {
 			continue
 		}
-		fields := map[string]any{
-			"status":    issue.Fields.Status.Name,
-			"issueType": issue.Fields.IssueType.Name,
-			"labels":    append([]string{}, issue.Fields.Labels...),
-		}
-		if issue.Fields.Assignee != nil {
-			fields["assignee"] = issue.Fields.Assignee.EmailAddress
-		}
-		out = append(out, task.Ticket{
-			ID:             issue.ID,
-			Key:            issue.Key,
-			Title:          issue.Fields.Summary,
-			WorkflowClaims: claimLabels(issue.Fields.Labels),
-			Fields:         fields,
-		})
+		out = append(out, normalizeIssueValue(issue))
 	}
 	return out, nil
 }
 
+// normalizeIssue parses a single Jira issue returned by View. Search returns
+// an array, while final claim ownership checks use the task-system's single
+// issue response shape.
+func normalizeIssue(raw []byte) (task.Ticket, error) {
+	var issue rawIssue
+	if err := json.Unmarshal(raw, &issue); err != nil {
+		return task.Ticket{}, err
+	}
+	return normalizeIssueValue(issue), nil
+}
+
+func normalizeIssueValue(issue rawIssue) task.Ticket {
+	fields := map[string]any{
+		"status":    issue.Fields.Status.Name,
+		"issueType": issue.Fields.IssueType.Name,
+		"labels":    append([]string{}, issue.Fields.Labels...),
+	}
+	if issue.Fields.Assignee != nil {
+		fields["assignee"] = issue.Fields.Assignee.EmailAddress
+	}
+	return task.Ticket{
+		ID:             issue.ID,
+		Key:            issue.Key,
+		Title:          issue.Fields.Summary,
+		WorkflowClaims: claimLabels(issue.Fields.Labels),
+		Fields:         fields,
+	}
+}
+
 func hasOpenBlocker(issue rawIssue) bool {
 	for _, link := range issue.Fields.IssueLinks {
 		if link.Type.Name == "Blocks" && link.InwardIssue != nil &&

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

@@ -52,6 +52,7 @@ type Client interface {
 	CreateSubtasks(context.Context, string, string, string, []SubtaskSpec) ([]CreatedSubtask, error)
 	UpdateMailbox(context.Context, string, string, string) error
 	EnsureLabel(context.Context, string, string) error
+	EnsureLabels(context.Context, string, []string) error
 	Transition(context.Context, string, string, string) error
 	ListComments(context.Context, string) ([]string, error)
 	AddComment(context.Context, string, string) error
@@ -265,7 +266,7 @@ func (c *HTTPClient) loadStatuses(ctx context.Context, project string) (map[stri
 }
 
 func (c *HTTPClient) View(ctx context.Context, key string) ([]byte, error) {
-	q := url.Values{"fields": {"summary,status,issuetype,labels,subtasks"}}
+	q := url.Values{"fields": {"summary,status,issuetype,labels,assignee,subtasks"}}
 	var raw json.RawMessage
 	if err := c.request(ctx, http.MethodGet, "/rest/api/3/issue/"+url.PathEscape(key), q, nil, &raw, true); err != nil {
 		return nil, err
@@ -347,7 +348,21 @@ func (c *HTTPClient) UpdateMailbox(ctx context.Context, key, description, label
 }
 
 func (c *HTTPClient) EnsureLabel(ctx context.Context, key, label string) error {
-	body := map[string]any{"update": map[string]any{"labels": []any{map[string]any{"add": label}}}}
+	return c.EnsureLabels(ctx, key, []string{label})
+}
+
+func (c *HTTPClient) EnsureLabels(ctx context.Context, key string, labels []string) error {
+	updates := make([]any, 0, len(labels))
+	for _, label := range labels {
+		if strings.TrimSpace(label) == "" {
+			continue
+		}
+		updates = append(updates, map[string]any{"add": label})
+	}
+	if len(updates) == 0 {
+		return errors.New("at least one Jira label is required")
+	}
+	body := map[string]any{"update": map[string]any{"labels": updates}}
 	return c.request(ctx, http.MethodPut, "/rest/api/3/issue/"+url.PathEscape(key), nil, body, nil, false)
 }
 

package/internal/task/jira/templates_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/run"
 	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
 func TestTaskTextTemplatesExposeValues(t *testing.T) {
@@ -17,7 +18,7 @@ func TestTaskTextTemplatesExposeValues(t *testing.T) {
 	sys, err := newSystem(context.Background(), &fakeClient{fake: fake}, task.RepoSpec{
 		Name: "payments",
 		RootConfig: config.RawValues{"templates": map[string]any{
-			"mailboxDescription": "mailbox {{runID}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{nodeType}}|{{agent}}|{{nodeDescription}}|{{nextSteps}}|{{successRoutes}}|{{failureRoutes}}|{{mailbox}}",
+			"mailboxDescription": "mailbox {{runID}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{nodeType}}|{{agent}}|{{nodeDescription}}|{{nextSteps}}|{{successRoutes}}|{{failureRoutes}}|{{mailbox}}|{{report}}",
 			"summaryComment":     "summary {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{summaryReport}}",
 			"feedbackComment":    "feedback {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{feedbackReport}}",
 		}},
@@ -31,7 +32,7 @@ func TestTaskTextTemplatesExposeValues(t *testing.T) {
 		Node: "review", NodeType: "hitl", Agent: "reviewer", NodeDescription: "Review changes.",
 		NextSteps: "implement; end", SuccessRoutes: "end", FailureRoutes: "implement",
 		Mailbox: "PAY-3", SourceNode: "review", TargetNode: "implement",
-		SummaryReport: "COMPLETED:\nreviewed", FeedbackReport: "REQUIRED ACTIONS:\nfix it",
+		SummaryReport: "COMPLETED:\nreviewed", FeedbackReport: "REQUIRED ACTIONS:\nfix it", Report: "STATUS: success | failure",
 	}
 	description, err := sys.RenderText(task.TextMailboxDescription, data)
 	if err != nil {
@@ -52,12 +53,47 @@ func TestTaskTextTemplatesExposeValues(t *testing.T) {
 	}
 }
 
+func TestJiraDefaultMailboxDescriptionIsCompact(t *testing.T) {
+	sys, err := newSystem(context.Background(), &fakeClient{fake: &fakeJira{}}, task.RepoSpec{
+		Name: "payments", RepoConfig: testRepoConfig(nil),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	data := task.TextData{
+		Ticket: "PAY-101", Node: "coder", NodeType: "agent", Agent: "coder",
+		NodeDescription: "Implement the change.", SuccessRoutes: "reviewer — when: ready",
+		FailureRoutes: "coder — when: retry", Report: workflow.ReportFormat,
+	}
+	description, err := sys.RenderText(task.TextMailboxDescription, data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "PAY-101 / coder — agent — coder\nImplement the change.\n\nSuccess routes:\nreviewer — when: ready\n\nFailure routes:\ncoder — when: retry\n\n" + workflow.ReportFormat
+	if description != want {
+		t.Fatalf("description = %q, want %q", description, want)
+	}
+	if strings.Contains(description, "comment history") {
+		t.Fatal("Jira description requested comment history")
+	}
+	data.NodeDescription = "Read the parent Jira ticket for this step:\nacli jira workitem view \"{{ticket}}\" --fields \"summary,description\" --json"
+	withParent, err := sys.RenderText(task.TextMailboxDescription, data)
+	if err != nil || !strings.Contains(withParent, `acli jira workitem view "PAY-101" --fields "summary,description" --json`) {
+		t.Fatalf("node-specific parent instruction = %q, %v", withParent, err)
+	}
+}
+
 func TestCommentTemplatesRequireReportValues(t *testing.T) {
 	for _, tc := range []struct {
 		name      string
 		override  map[string]any
 		wantError string
 	}{
+		{name: "description", override: map[string]any{"mailboxDescription": "missing"}, wantError: "mailboxDescription must contain {{report}}"},
+		{name: "report only", override: map[string]any{"mailboxDescription": "{{report}}"}, wantError: "mailboxDescription must contain {{ticket}}"},
+		{name: "no node work", override: map[string]any{"mailboxDescription": strings.Replace(defaultMailboxDescription, "{{nodeDescription}}", "No work provided", 1)}, wantError: "mailboxDescription must contain {{nodeDescription}}"},
+		{name: "no success routes", override: map[string]any{"mailboxDescription": strings.Replace(defaultMailboxDescription, "{{successRoutes}}", "None", 1)}, wantError: "mailboxDescription must contain {{successRoutes}}"},
+		{name: "no failure routes", override: map[string]any{"mailboxDescription": strings.Replace(defaultMailboxDescription, "{{failureRoutes}}", "None", 1)}, wantError: "mailboxDescription must contain {{failureRoutes}}"},
 		{name: "summary", override: map[string]any{"summaryComment": "missing"}, wantError: "summaryComment must contain {{summaryReport}}"},
 		{name: "feedback", override: map[string]any{"feedbackComment": "missing"}, wantError: "feedbackComment must contain {{feedbackReport}}"},
 		{name: "unknown", override: map[string]any{"mailboxDescription": "{{mailboxInstructions}}"}, wantError: "unknown template variable {{mailboxInstructions}}"},

package/internal/task/jira/transition_defaults_test.go

@@ -29,7 +29,9 @@ type fakeJira struct {
 	transitionErr     error
 	events            []string
 	// searchJSON is the raw Jira search response Poll serves.
-	searchJSON    []byte
+	searchJSON []byte
+	// viewJSON is the single-issue response used by final ownership checks.
+	viewJSON      []byte
 	comments      []string
 	addedComments []string
 	labelCalls    []string

package/internal/task/task.go

@@ -4,6 +4,8 @@ package task
 
 import (
 	"context"
+	"errors"
+	"fmt"
 
 	"github.com/rajpopat27/relay-flow/internal/config"
 )
@@ -68,6 +70,7 @@ type TextData struct {
 	TargetNode      string
 	SummaryReport   string
 	FeedbackReport  string
+	Report          string
 }
 
 type Target struct {
@@ -99,6 +102,70 @@ type System interface {
 	ResetForRecovery(ctx context.Context, parent TicketRef, mailboxes []Mailbox, taskConfig config.RawValues) error
 }
 
+// ErrOwnershipMismatch identifies a task-system ownership predicate that did
+// not accept the current ticket. Adapters return OwnershipMismatchError from
+// their last-mile claim check and from claimed-run revalidation; core can
+// classify the race without learning provider-specific owner fields.
+var ErrOwnershipMismatch = errors.New("ticket owner does not match workflow")
+
+// OwnershipMismatchError is the provider-neutral shape of an ownership
+// rejection. It intentionally omits the current owner so diagnostics do not
+// expose unnecessary personal data.
+type OwnershipMismatchError struct {
+	Ticket   string
+	Workflow string
+}
+
+func (e *OwnershipMismatchError) Error() string {
+	return fmt.Sprintf("ticket %s is not owned by workflow %s", e.Ticket, e.Workflow)
+}
+
+func (e *OwnershipMismatchError) Unwrap() error { return ErrOwnershipMismatch }
+
+// OwnershipFilterCompiler is one part of the required automatic-routing
+// ownership capability set. The returned matcher contains only the
+// ownership/assignee predicate from the effective workflow config; it must not
+// repeat lifecycle filters such as status, issue type, or ordinary labels on a
+// claimed-ticket route.
+type OwnershipFilterCompiler interface {
+	CompileOwnershipFilter(workflowTaskConfig config.RawValues) (func(Ticket) bool, error)
+}
+
+// OwnershipValidator is one part of the required automatic-routing
+// ownership capability set. It is used at the last-mile boundary and before
+// claimed-run recovery, re-reading the provider-owned ticket and evaluating
+// the effective ownership predicate.
+type OwnershipValidator interface {
+	ValidateOwnership(ctx context.Context, ticket TicketRef, workflow string, workflowTaskConfig config.RawValues) error
+}
+
+// ConditionalClaimer is one part of the required automatic-routing
+// ownership capability set. It replaces Claim for an unassigned poll result;
+// the adapter performs its final ownership read immediately before the
+// idempotent workflow-label write, closing the poll-to-claim reassignment race.
+type ConditionalClaimer interface {
+	ClaimIfOwned(ctx context.Context, ticket TicketRef, workflow string, workflowTaskConfig config.RawValues) error
+}
+
+// OwnershipCapabilities is the complete capability set required by an
+// adapter that participates in automatic workflow routing. Keeping this as a
+// separate boundary leaves the core System contract focused on task
+// primitives while allowing registration to fail closed when an adapter would
+// otherwise silently fall back to unrestricted Claim behavior.
+type OwnershipCapabilities interface {
+	OwnershipFilterCompiler
+	OwnershipValidator
+	ConditionalClaimer
+}
+
+// ClaimOwnerBackfiller is an explicit provider-side repair capability for a
+// legacy wf: claim that predates ownership provenance. Normal routing never
+// invokes it; an operator/provider workflow may add the durable marker after
+// verifying the live assignee, without removing the existing claim or history.
+type ClaimOwnerBackfiller interface {
+	BackfillClaimOwner(ctx context.Context, ticket TicketRef, workflow string, workflowTaskConfig config.RawValues) error
+}
+
 // AgentEnvironment is an optional adapter capability. It returns the
 // task-system workspace environment an agent process must receive so agent
 // task commands address the same workspace as relay-flow. Values are

package/internal/workflow/report.go

@@ -9,6 +9,13 @@ import (
 // represents an intentionally empty section.
 const None = "None"
 
+// ReportFormat is the canonical agent-facing contract. Runtime plugins parse
+// these four fields into the existing structured Report wire shape.
+const ReportFormat = `STATUS: success | failure
+NEXT STEP: <one valid route>
+SUMMARY: <concise result>
+FEEDBACK: <concise handoff, or None when NEXT STEP is end>`
+
 type Summary struct {
 	Completed        string `json:"completed"`
 	Commits          string `json:"commits"`
@@ -43,6 +50,9 @@ func (w *Workflow) ValidateReport(node string, report Report) error {
 	if report.Status != OutcomeSuccess && report.Status != OutcomeFailure {
 		return fmt.Errorf("report status %q must be %q or %q", report.Status, OutcomeSuccess, OutcomeFailure)
 	}
+	if report.Status == OutcomeFailure && report.NextStep == EndNode {
+		return fmt.Errorf("failure reports cannot select %q", EndNode)
+	}
 	for _, field := range []struct{ name, value string }{
 		{"summary.completed", report.Summary.Completed},
 		{"summary.commits", report.Summary.Commits},

package/internal/workflow/report_test.go

@@ -181,6 +181,22 @@ func TestValidateReportStatusValues(t *testing.T) {
 	}
 }
 
+func TestValidateReportRejectsFailureToEndEvenIfRouteTableContainsIt(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+	node := wf.Nodes["coding"]
+	node.OnFailure = append(node.OnFailure, workflow.Route{Target: workflow.EndNode})
+	wf.Nodes["coding"] = node
+	r := workflow.Report{
+		Status:   workflow.OutcomeFailure,
+		NextStep: workflow.EndNode,
+		Summary:  fullSummary(),
+		Feedback: noneFeedback(),
+	}
+	if err := wf.ValidateReport("coding", r); err == nil {
+		t.Fatal("failure report selecting end accepted")
+	}
+}
+
 func TestValidateReportNextStepMustMatchStatusRoute(t *testing.T) {
 	wf := parse(t, "basicFlow", minimalValid)