relay-flow 0.2.1-alpha → 0.2.3-alpha

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

@@ -2,109 +2,146 @@ package rest
 
 import (
 	"encoding/json"
-	"regexp"
 	"strings"
+
+	"github.com/yuin/goldmark"
+	"github.com/yuin/goldmark/ast"
+	"github.com/yuin/goldmark/text"
 )
 
-var orderedItem = regexp.MustCompile(`^\d+\.\s+`)
+var markdown = goldmark.New()
 
-func ADF(text string) map[string]any {
-	lines := strings.Split(strings.ReplaceAll(text, "\r\n", "\n"), "\n")
-	content := make([]any, 0)
-	for i := 0; i < len(lines); {
-		line := strings.TrimSpace(lines[i])
-		if line == "" {
-			i++
-			continue
-		}
-		if strings.HasPrefix(line, "```") {
-			i++
-			code := make([]string, 0)
-			for i < len(lines) && !strings.HasPrefix(strings.TrimSpace(lines[i]), "```") {
-				code = append(code, lines[i])
-				i++
-			}
-			if i < len(lines) {
-				i++
-			}
-			content = append(content, map[string]any{"type": "codeBlock", "content": []any{textNode(strings.Join(code, "\n"))}})
-			continue
-		}
-		if strings.HasPrefix(line, "- ") || orderedItem.MatchString(line) {
-			ordered := orderedItem.MatchString(line)
-			items := make([]any, 0)
-			for i < len(lines) {
-				item := strings.TrimSpace(lines[i])
-				if ordered {
-					if !orderedItem.MatchString(item) {
-						break
-					}
-					item = orderedItem.ReplaceAllString(item, "")
-				} else {
-					if !strings.HasPrefix(item, "- ") {
-						break
-					}
-					item = strings.TrimPrefix(item, "- ")
-				}
-				items = append(items, map[string]any{
-					"type":    "listItem",
-					"content": []any{paragraph(item)},
-				})
-				i++
-			}
-			kind := "bulletList"
-			if ordered {
-				kind = "orderedList"
-			}
-			content = append(content, map[string]any{"type": kind, "content": items})
-			continue
-		}
-		if heading(line) {
+// ADF converts explicit Markdown syntax to Atlassian Document Format.
+func ADF(value string) map[string]any {
+	source := []byte(strings.ReplaceAll(value, "\r\n", "\n"))
+	document := markdown.Parser().Parse(text.NewReader(source))
+	content := blockContent(document, source)
+	if len(content) == 0 {
+		content = []any{paragraph(nil)}
+	}
+	return map[string]any{"type": "doc", "version": 1, "content": content}
+}
+
+func blockContent(parent ast.Node, source []byte) []any {
+	content := make([]any, 0, parent.ChildCount())
+	for node := parent.FirstChild(); node != nil; node = node.NextSibling() {
+		switch node := node.(type) {
+		case *ast.Heading:
 			content = append(content, map[string]any{
 				"type":    "heading",
-				"attrs":   map[string]any{"level": 3},
-				"content": []any{textNode(strings.TrimSuffix(line, ":"))},
+				"attrs":   map[string]any{"level": node.Level},
+				"content": inlineContent(node, source, nil),
 			})
-			i++
-			continue
+		case *ast.Paragraph, *ast.TextBlock:
+			content = append(content, paragraph(inlineContent(node, source, nil)))
+		case *ast.List:
+			content = append(content, list(node, source))
+		case *ast.FencedCodeBlock:
+			content = append(content, codeBlock(node.Text(source), node.Language(source)))
+		case *ast.CodeBlock:
+			content = append(content, codeBlock(node.Text(source), nil))
+		case *ast.HTMLBlock:
+			content = append(content, paragraph([]any{textNode(string(node.Text(source)), nil)}))
+		default:
+			content = append(content, blockContent(node, source)...)
 		}
-		content = append(content, paragraph(line))
-		i++
-	}
-	if len(content) == 0 {
-		content = append(content, paragraph(""))
 	}
-	return map[string]any{"type": "doc", "version": 1, "content": content}
+	return content
 }
 
-func heading(line string) bool {
-	if len(line) > 80 {
-		return false
+func list(value *ast.List, source []byte) map[string]any {
+	items := make([]any, 0, value.ChildCount())
+	for child := value.FirstChild(); child != nil; child = child.NextSibling() {
+		itemContent := blockContent(child, source)
+		if len(itemContent) == 0 {
+			itemContent = []any{paragraph(nil)}
+		}
+		items = append(items, map[string]any{"type": "listItem", "content": itemContent})
+	}
+
+	kind := "bulletList"
+	result := map[string]any{"type": kind, "content": items}
+	if value.IsOrdered() {
+		result["type"] = "orderedList"
+		if value.Start != 1 {
+			result["attrs"] = map[string]any{"order": value.Start}
+		}
 	}
-	return strings.HasSuffix(line, ":") || (line == strings.ToUpper(line) && strings.IndexFunc(line, func(r rune) bool { return r >= 'A' && r <= 'Z' }) >= 0)
+	return result
 }
 
-func paragraph(text string) map[string]any {
-	if text == "" {
-		return map[string]any{"type": "paragraph"}
+func codeBlock(value, language []byte) map[string]any {
+	result := map[string]any{
+		"type":    "codeBlock",
+		"content": []any{textNode(strings.TrimSuffix(string(value), "\n"), nil)},
 	}
-	return map[string]any{"type": "paragraph", "content": inlineContent(text)}
+	if len(language) != 0 {
+		result["attrs"] = map[string]any{"language": string(language)}
+	}
+	return result
 }
 
-func inlineContent(text string) []any {
-	if strings.HasPrefix(text, "<!--") {
-		return []any{textNode(text)}
+func paragraph(content []any) map[string]any {
+	result := map[string]any{"type": "paragraph"}
+	if len(content) != 0 {
+		result["content"] = content
 	}
-	if i := strings.Index(text, ":"); i > 0 && i < 40 {
-		label := textNode(text[:i+1])
-		label["marks"] = []any{map[string]any{"type": "strong"}}
-		return []any{label, textNode(text[i+1:])}
+	return result
+}
+
+func inlineContent(parent ast.Node, source []byte, marks []any) []any {
+	content := make([]any, 0, parent.ChildCount())
+	for node := parent.FirstChild(); node != nil; node = node.NextSibling() {
+		switch node := node.(type) {
+		case *ast.Text:
+			if value := string(node.Text(source)); value != "" {
+				content = append(content, textNode(value, marks))
+			}
+			if node.HardLineBreak() {
+				content = append(content, map[string]any{"type": "hardBreak"})
+			} else if node.SoftLineBreak() {
+				content = append(content, textNode(" ", marks))
+			}
+		case *ast.String:
+			if value := string(node.Value); value != "" {
+				content = append(content, textNode(value, marks))
+			}
+		case *ast.Emphasis:
+			kind := "em"
+			if node.Level == 2 {
+				kind = "strong"
+			}
+			content = append(content, inlineContent(node, source, withMark(marks, map[string]any{"type": kind}))...)
+		case *ast.Link:
+			mark := map[string]any{"type": "link", "attrs": map[string]any{"href": string(node.Destination)}}
+			content = append(content, inlineContent(node, source, withMark(marks, mark))...)
+		case *ast.AutoLink:
+			content = append(content, textNode(string(node.Label(source)), withMark(marks, map[string]any{
+				"type": "link", "attrs": map[string]any{"href": string(node.URL(source))},
+			})))
+		case *ast.CodeSpan:
+			content = append(content, inlineContent(node, source, withMark(marks, map[string]any{"type": "code"}))...)
+		case *ast.RawHTML:
+			content = append(content, textNode(string(node.Text(source)), marks))
+		default:
+			content = append(content, inlineContent(node, source, marks)...)
+		}
 	}
-	return []any{textNode(text)}
+	return content
 }
 
-func textNode(text string) map[string]any {
-	return map[string]any{"type": "text", "text": text}
+func withMark(marks []any, mark map[string]any) []any {
+	result := make([]any, len(marks), len(marks)+1)
+	copy(result, marks)
+	return append(result, mark)
+}
+
+func textNode(value string, marks []any) map[string]any {
+	result := map[string]any{"type": "text", "text": value}
+	if len(marks) != 0 {
+		result["marks"] = marks
+	}
+	return result
 }
 
 func ADFText(raw json.RawMessage) string {

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

@@ -0,0 +1,60 @@
+package rest
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestADFConvertsExplicitMarkdown(t *testing.T) {
+	doc := ADF("# Heading\n\nWords with **strong**, *emphasis*, [a link](https://example.com), and `code`.\n\n1. first\n2. second\n\n```go\nfmt.Println(\"ok\")\n```")
+	content := doc["content"].([]any)
+
+	if got := content[0].(map[string]any); got["type"] != "heading" || !reflect.DeepEqual(got["attrs"], map[string]any{"level": 1}) {
+		t.Fatalf("heading = %#v", got)
+	}
+
+	raw, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{
+		`"type":"strong"`,
+		`"type":"em"`,
+		`"attrs":{"href":"https://example.com"},"type":"link"`,
+		`"type":"code"`,
+		`"type":"orderedList"`,
+		`"attrs":{"language":"go"}`,
+		`"type":"codeBlock"`,
+	} {
+		if !strings.Contains(string(raw), want) {
+			t.Errorf("ADF missing %s: %s", want, raw)
+		}
+	}
+}
+
+func TestADFDoesNotInferFormatting(t *testing.T) {
+	doc := ADF("SUMMARY\n\nNode: implement\n\nHTTPS://EXAMPLE.COM")
+	raw, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(raw), `"type":"heading"`) || strings.Contains(string(raw), `"type":"strong"`) {
+		t.Fatalf("plain text was inferred as formatting: %s", raw)
+	}
+	if got := len(doc["content"].([]any)); got != 3 {
+		t.Fatalf("paragraph count = %d, want 3", got)
+	}
+}
+
+func TestADFMarkerRoundTrip(t *testing.T) {
+	const marker = "<!-- run-1:summary -->"
+	raw, err := json.Marshal(ADF("Done.\n\n" + marker))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := ADFText(raw); !strings.Contains(got, marker) {
+		t.Fatalf("ADFText() = %q, want marker %q", got, marker)
+	}
+}

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

@@ -355,7 +355,7 @@ func TestErrorRedactsToken(t *testing.T) {
 }
 
 func TestADFFormatsHeadingsListsAndRoundTripsMarker(t *testing.T) {
-	doc := ADF("SUMMARY\n\nNode: implement\n\n- first\n- second\n\n```\ngo test ./...\n```\n\n<!-- visit:summary -->")
+	doc := ADF("### Summary\n\n**Node:** implement\n\n- first\n- second\n\n```\ngo test ./...\n```\n\n<!-- visit:summary -->")
 	raw, err := json.Marshal(doc)
 	if err != nil {
 		t.Fatal(err)

package/internal/task/jira/templates_test.go

@@ -0,0 +1,118 @@
+package jira
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+func TestTaskTextTemplatesExposeValues(t *testing.T) {
+	fake := &fakeJira{}
+	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}}",
+			"summaryComment":     "summary {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{summaryReport}}",
+			"feedbackComment":    "feedback {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{feedbackReport}}",
+		}},
+		RepoConfig: config.RawValues{"project": "PAY", "component": "api"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	data := task.TextData{
+		RunID: "run-1", Ticket: "PAY-1", Workflow: "flow", Repo: "payments",
+		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",
+	}
+	description, err := sys.RenderText(task.TextMailboxDescription, data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"run-1", "PAY-1", "flow", "payments", "review", "hitl", "reviewer", "Review changes.", "implement; end", "PAY-3"} {
+		if !strings.Contains(description, want) {
+			t.Fatalf("description missing %q: %q", want, description)
+		}
+	}
+	summary, err := sys.RenderText(task.TextSummaryComment, data)
+	if err != nil || !strings.Contains(summary, data.SummaryReport) {
+		t.Fatalf("summary = %q, %v", summary, err)
+	}
+	feedback, err := sys.RenderText(task.TextFeedbackComment, data)
+	if err != nil || !strings.Contains(feedback, "feedback review|implement|PAY-3") || !strings.Contains(feedback, data.FeedbackReport) {
+		t.Fatalf("feedback = %q, %v", feedback, err)
+	}
+}
+
+func TestCommentTemplatesRequireReportValues(t *testing.T) {
+	for _, tc := range []struct {
+		name      string
+		override  map[string]any
+		wantError string
+	}{
+		{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}}"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			raw := config.Merge(DefaultConfig(), config.RawValues{"templates": tc.override})
+			var cfg Config
+			if err := config.DecodeStrict(raw, &cfg); err != nil {
+				t.Fatal(err)
+			}
+			err := validateTemplates(cfg.Templates)
+			if err == nil || !strings.Contains(err.Error(), tc.wantError) {
+				t.Fatalf("validateTemplates error = %v, want %q", err, tc.wantError)
+			}
+		})
+	}
+}
+
+func TestTaskTemplatesRenderSharedReportContractValues(t *testing.T) {
+	b, err := os.ReadFile("../../../testdata/report-contract.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var fixtures map[string]struct {
+		Envelope       run.ReportRequest `json:"envelope"`
+		SummaryReport  string            `json:"summaryReport"`
+		FeedbackReport string            `json:"feedbackReport"`
+	}
+	if err := json.Unmarshal(b, &fixtures); err != nil {
+		t.Fatal(err)
+	}
+	fixture := fixtures["work"]
+	sys, err := newSystem(context.Background(), &fakeClient{fake: &fakeJira{}}, task.RepoSpec{
+		Name: "payments", RepoConfig: config.RawValues{"project": "PAY", "component": "api"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	data := task.TextData{
+		Node: "coding", SourceNode: "coding", TargetNode: "coding", Mailbox: "PAY-101:coding",
+		SummaryReport: fixture.SummaryReport, FeedbackReport: fixture.FeedbackReport,
+	}
+	summary, err := sys.RenderText(task.TextSummaryComment, data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if summary != "Summary for coding\n\n"+fixture.SummaryReport {
+		t.Fatalf("summary template did not render shared summaryReport:\n%s", summary)
+	}
+	feedback, err := sys.RenderText(task.TextFeedbackComment, data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantFeedback := "Feedback from coding to coding mailbox PAY-101:coding\n\n" + fixture.FeedbackReport
+	if feedback != wantFeedback {
+		t.Fatalf("feedback template did not render shared feedbackReport:\n%s", feedback)
+	}
+}

package/internal/task/jira/transition_defaults_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/retry"
 	"github.com/rajpopat27/relay-flow/internal/task"
 )
 
@@ -27,6 +28,7 @@ type fakeJira struct {
 	taskTransitions   []string
 	assignments       []string
 	assignErr         error
+	transitionErr     error
 	events            []string
 	// searchJSON is the raw Jira search response Poll serves.
 	searchJSON    []byte
@@ -128,8 +130,10 @@ func TestEndDefaultParentDone(t *testing.T) {
 
 	// end: omitted transitionTo. The end effective config carries no
 	// transition; the adapter must still default the parent to Done. Run
-	// orchestration applies the end node config to the parent target.
-	if err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent}, endConfig(config.RawValues{})); err != nil {
+	// orchestration merges EndDefaults under the end node config before
+	// applying it to the parent target.
+	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)
 	}
 	if len(fake.parentTransitions) != 1 || fake.parentTransitions[0] != "Done" {
@@ -137,6 +141,47 @@ func TestEndDefaultParentDone(t *testing.T) {
 	}
 }
 
+func TestPrepareRestartReopensMailboxesWithoutChangingParent(t *testing.T) {
+	fake := &fakeJira{}
+	sys := newSystemWithFake(t, fake)
+	preparer, ok := sys.(task.RestartPreparer)
+	if !ok {
+		t.Fatal("Jira system does not implement RestartPreparer")
+	}
+	parent := task.TicketRef{ID: "1", Key: "PAY-101"}
+	mailboxes := []task.Mailbox{
+		{ID: "2", Key: "PAY-102", Node: "coding"},
+		{ID: "3", Key: "PAY-103", Node: "review"},
+	}
+	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.parentTransitions) != 0 {
+		t.Fatalf("parent transitions = %v, want none (start owns parent status)", fake.parentTransitions)
+	}
+}
+
+func TestPrepareRestartPreservesHumanJiraStateOnConflict(t *testing.T) {
+	fake := &fakeJira{transitionErr: errors.New(`transition to "To Do" 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{
+		{ID: "2", Key: "PAY-102", Node: "coding"},
+	})
+	if err == nil {
+		t.Fatal("incompatible Jira mailbox status was accepted")
+	}
+	if got := retry.Classify(err).Kind; got != retry.Conflict {
+		t.Fatalf("failure kind = %q, want conflict: %v", got, err)
+	}
+	if len(fake.parentTransitions) != 0 {
+		t.Fatalf("parent transitions = %v, want none", fake.parentTransitions)
+	}
+}
+
 func TestExplicitTransitionsWin(t *testing.T) {
 	fake := &fakeJira{}
 	sys := newSystemWithFake(t, fake)

package/internal/task/task.go

@@ -37,6 +37,37 @@ type MailboxSpec struct {
 	Title       string           `json:"title"`
 	Description string           `json:"description"`
 	TaskConfig  config.RawValues `json:"taskConfig,omitempty"`
+	TextData    TextData         `json:"textData"`
+}
+
+type TextKind string
+
+const (
+	TextMailboxDescription TextKind = "mailboxDescription"
+	TextSummaryComment     TextKind = "summaryComment"
+	TextFeedbackComment    TextKind = "feedbackComment"
+)
+
+// TextData contains existing run, mailbox, and node values supplied to a
+// task-system text template. The task system owns rendering; harness prompt
+// templates are a separate contract.
+type TextData struct {
+	RunID           string
+	Ticket          string
+	Workflow        string
+	Repo            string
+	Node            string
+	NodeType        string
+	Agent           string
+	NodeDescription string
+	NextSteps       string
+	SuccessRoutes   string
+	FailureRoutes   string
+	Mailbox         string
+	SourceNode      string
+	TargetNode      string
+	SummaryReport   string
+	FeedbackReport  string
 }
 
 type Target struct {
@@ -59,6 +90,7 @@ type System interface {
 	Claim(ctx context.Context, ticket TicketRef, workflow string) error
 
 	ValidateConfig(ctx context.Context, workflowTaskConfig config.RawValues, nodeTaskConfigs map[string]config.RawValues) error
+	RenderText(kind TextKind, data TextData) (string, error)
 	EnsureMailboxes(ctx context.Context, parent TicketRef, workflow string, specs []MailboxSpec) (map[string]Mailbox, error)
 	ApplyTaskConfig(ctx context.Context, target Target, taskConfig config.RawValues) error
 	CompleteMailbox(ctx context.Context, mailbox Mailbox) error
@@ -67,6 +99,14 @@ type System interface {
 	ResetForRecovery(ctx context.Context, parent TicketRef, mailboxes []Mailbox, taskConfig config.RawValues) error
 }
 
+// RestartPreparer is an optional adapter capability used only by explicit
+// run restarts. It reopens relay-owned mailbox state while preserving all
+// comments, labels, and descriptions. A human-owned incompatible state must
+// be returned as retry.ConflictError; core never names provider statuses.
+type RestartPreparer interface {
+	PrepareRestart(ctx context.Context, parent TicketRef, mailboxes []Mailbox) error
+}
+
 // LifecycleDefaults is an optional adapter capability: a System whose
 // taskConfig carries lifecycle-dependent defaults (e.g. Jira's deterministic
 // transitionTo defaults) exposes them here. The lifecycle-aware caller

package/internal/workflow/report_test.go

@@ -1,9 +1,12 @@
 package workflow_test
 
 import (
+	"encoding/json"
+	"os"
 	"strings"
 	"testing"
 
+	"github.com/rajpopat27/relay-flow/internal/run"
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
@@ -39,6 +42,48 @@ func noneFeedback() workflow.Feedback {
 	}
 }
 
+type reportContractFixture struct {
+	AssistantText  string            `json:"assistantText"`
+	Envelope       run.ReportRequest `json:"envelope"`
+	SummaryReport  string            `json:"summaryReport"`
+	FeedbackReport string            `json:"feedbackReport"`
+}
+
+func reportContractFixtures(t *testing.T) map[string]reportContractFixture {
+	t.Helper()
+	b, err := os.ReadFile("../../testdata/report-contract.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var fixtures map[string]reportContractFixture
+	if err := json.Unmarshal(b, &fixtures); err != nil {
+		t.Fatal(err)
+	}
+	return fixtures
+}
+
+func TestSharedReportContractFixtureMatchesGoValidation(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+	fixtures := reportContractFixtures(t)
+	for _, name := range []string{"work", "end"} {
+		t.Run(name, func(t *testing.T) {
+			fixture := fixtures[name]
+			if fixture.Envelope.Report.Summary.Completed == "" || fixture.Envelope.Report.Feedback.ReasonForNextStep == "" {
+				t.Fatal("shared report fixture must contain both summary and feedback")
+			}
+			if err := wf.ValidateReport(fixture.Envelope.Node, fixture.Envelope.Report); err != nil {
+				t.Fatalf("shared report fixture rejected: %v", err)
+			}
+		})
+	}
+
+	invalidEnd := fixtures["end"].Envelope.Report
+	invalidEnd.Feedback.RequiredActions = "do more work"
+	if err := wf.ValidateReport("coding", invalidEnd); err == nil {
+		t.Fatal("end fixture with feedback content accepted")
+	}
+}
+
 func TestValidateReportAcceptsCompleteSuccess(t *testing.T) {
 	wf := parse(t, "basicFlow", minimalValid)
 	r := workflow.Report{

package/package.json

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