docs: refresh planner priorities for 3994

Co-authored-by: Codex <codex@openai.com>

.github/loop/PRIORITIES.md

@@ -21,9 +21,9 @@ changes, architectural rewrites. Those go to the human.
 
 ## Work queue (ranked)
 
-1. **Require delegated notify before plan-delegate completion** ([#3972](https://github.com/micro/go-micro/issues/3972)) — #3981 closed the first-agent broker isolation gap, leaving this as the latest live AtlasCloud plan/delegate harness regression. A tasks-complete-but-notify-missing run undermines evaluator trust at the agents → workflows seam, so it stays at the top until the harness can prove delegated work only completes after the required notification.
-2. **Surface the first-agent and 0→hero example paths in the CLI** ([#3983](https://github.com/micro/go-micro/issues/3983)) — the README, website docs, and examples now describe a strong on-ramp, but adoption still depends on users finding those paths after install. Current goal is developer adoption, so the queue should keep a CI-verifiable CLI wayfinding task near the top instead of drifting entirely into internal conformance and observability work.
-3. **Broaden provider streaming and keep chat/A2A streaming end to end** ([#3903](https://github.com/micro/go-micro/issues/3903)) — streaming remains the highest developer-visible Next-phase seam after the current conformance and wayfinding gaps. Real chat and long-running A2A tasks need token streaming to stay coherent from provider → `ai.Stream` → `micro chat` → A2A `message/stream`, with mock/default CI coverage plus key-gated live provider checks and safe fallback for non-streaming providers.
+1. **Make AtlasCloud live conformance exercise the guarded delegate path** ([#3990](https://github.com/micro/go-micro/issues/3990)) — #3993 shipped the highest-priority adoption wayfinding gap by surfacing first-agent and 0→hero next steps from `micro new`, so the queue should not re-run #3983. The current top risk is a live provider-conformance regression in the Now-phase “battle-tested across providers” contract: AtlasCloud completed the model/tool path but skipped the guarded delegation attempt, leaving the harness unable to prove delegation refusal behavior across providers.
+2. **Make AtlasCloud plan/delegate complete required tasks before notification** ([#3991](https://github.com/micro/go-micro/issues/3991)) — the same scheduled live harness exposed a 0→hero correctness seam: the conductor emitted the delegated notification side effect while required task-creation plan steps remained unfinished. This is ranked just behind #3990 because it protects the services → agents → workflows story users now discover through the CLI and should fail safely before side effects or recover before checkpoint validation.
+3. **Broaden provider streaming and keep chat/A2A streaming end to end** ([#3903](https://github.com/micro/go-micro/issues/3903)) — once the live conformance regressions are fixed, streaming remains the highest developer-visible Next-phase seam. Real chat and long-running A2A tasks need token streaming to stay coherent from provider → `ai.Stream` → `micro chat` → A2A `message/stream`, with mock/default CI coverage plus key-gated live provider checks and safe fallback for non-streaming providers.
 4. **Trace agent runs as OpenTelemetry spans** ([#3908](https://github.com/micro/go-micro/issues/3908)) — the blog/README/roadmap story promises an operable harness, and the developer on-ramp now includes chat, inspect, and run-history checkpoints. The next observability gap is production-grade trace correlation for `RunInfo`: steps, tool calls, delegation, status, durations, and failures should be visible as spans while defaulting to no-op when tracing is not configured.
 _Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
 architecture-review pass._

cmd/micro/cli/new/contract_test.go

@@ -1,6 +1,7 @@
 package new
 
 import (
+	"bytes"
 	"errors"
 	"flag"
 	"os"
@@ -57,6 +58,43 @@ func TestZeroToOneNoMCPContract(t *testing.T) {
 	generated.call(t, "Bob", "Hello Bob")
 }
 
+func TestPrintNextStepsSurfacesFirstAgentPath(t *testing.T) {
+	var out bytes.Buffer
+	printNextSteps(&out, "helloworld", false)
+
+	for _, want := range []string{
+		"cd helloworld",
+		"micro agent preflight",
+		"go run .",
+		"micro chat",
+		"micro inspect agent",
+		"micro docs",
+		"your-first-agent.html",
+		"zero-to-hero.html",
+		"http://localhost:3001/mcp/tools",
+	} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("next steps missing %q:\n%s", want, out.String())
+		}
+	}
+}
+
+func TestPrintNextStepsNoMCPSkipsMCPHints(t *testing.T) {
+	var out bytes.Buffer
+	printNextSteps(&out, "worker", true)
+
+	for _, want := range []string{"micro agent preflight", "micro chat", "micro inspect agent", "micro docs"} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("--no-mcp next steps missing %q:\n%s", want, out.String())
+		}
+	}
+	for _, notWant := range []string{"http://localhost:3001/mcp/tools", "micro mcp serve"} {
+		if strings.Contains(out.String(), notWant) {
+			t.Fatalf("--no-mcp next steps should not include %q:\n%s", notWant, out.String())
+		}
+	}
+}
+
 type generatedService struct {
 	dir      string
 	repoRoot string

cmd/micro/cli/new/new.go

@@ -6,6 +6,7 @@ import (
 	"context"
 	"fmt"
 	"go/build"
+	"io"
 	"os"
 	"os/exec"
 	"os/signal"
@@ -280,18 +281,30 @@ func Run(ctx *cli.Context) error {
 
 	fmt.Println()
 	fmt.Printf("  \033[32m✓\033[0m Service \033[36m%s\033[0m created\n\n", dir)
-	fmt.Println("  Next steps:")
-	fmt.Printf("    cd %s\n", dir)
-	fmt.Println("    go run .")
-	if !noMCP {
-		fmt.Println()
-		fmt.Printf("    MCP tools   \033[36mhttp://localhost:3001/mcp/tools\033[0m\n")
-		fmt.Println("    Claude Code \033[2mmicro mcp serve\033[0m")
-	}
-	fmt.Println()
+	printNextSteps(os.Stdout, dir, noMCP)
 	return nil
 }
 
+func printNextSteps(w io.Writer, dir string, noMCP bool) {
+	fmt.Fprintln(w, "  Next steps:")
+	fmt.Fprintf(w, "    cd %s\n", dir)
+	fmt.Fprintln(w, "    micro agent preflight")
+	fmt.Fprintln(w, "    go run .")
+	fmt.Fprintln(w, "    micro chat")
+	fmt.Fprintln(w, "    micro inspect agent")
+	fmt.Fprintln(w)
+	fmt.Fprintln(w, "  First-agent path:")
+	fmt.Fprintln(w, "    micro docs")
+	fmt.Fprintln(w, "    https://go-micro.dev/docs/guides/your-first-agent.html")
+	fmt.Fprintln(w, "    https://go-micro.dev/docs/guides/zero-to-hero.html")
+	if !noMCP {
+		fmt.Fprintln(w)
+		fmt.Fprintf(w, "    MCP tools   \033[36mhttp://localhost:3001/mcp/tools\033[0m\n")
+		fmt.Fprintln(w, "    Claude Code \033[2mmicro mcp serve\033[0m")
+	}
+	fmt.Fprintln(w)
+}
+
 func selectTemplates(name string, noMCP bool) (mainTmpl, handlerTmpl, protoTmpl string) {
 	switch name {
 	case "crud":

internal/harness/plan-delegate/main.go

@@ -403,8 +403,14 @@ func runPlanDelegate(provider string) error {
 	}
 
 	f := flow.New("zero-to-hero",
-		flow.Agent("conductor"),
-		flow.Prompt("Create three launch tasks (Design, Build, Ship), then make sure owner@acme.com is notified: {{.Data}}"),
+		flow.Steps(
+			flow.Step{Name: "conductor", Run: planDelegateConductorStep(conductor)},
+			flow.Step{Name: "require-notify", Run: requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error {
+				_, err := conductor.Ask(ctx, "The Design, Build, and Ship tasks already exist, but the owner notification is still missing. Delegate exactly one notification to the \"comms\" agent now with this exact subtask: "+delegatedNotifyTask+" Do not create more tasks and do not answer until comms has handled the notification.")
+				return err
+			})},
+		),
+		flow.WithCheckpoint(flow.StoreCheckpoint(mem, "flow-zero-to-hero")),
 		flow.Timeout(harnessutil.LiveTimeout(provider)),
 	)
 	if err := f.Register(reg, broker.DefaultBroker, cl); err != nil {
@@ -419,15 +425,8 @@ func runPlanDelegate(provider string) error {
 		executeDone <- f.Execute(ctx, "launch readiness")
 	}()
 
-	if err := waitForPlanDelegateExecution(executeDone, taskSvc, notifySvc, func(ctx context.Context) error {
-		_, err := conductor.Ask(ctx, "The Design, Build, and Ship tasks already exist, but the owner notification is still missing. Delegate exactly one notification to the \"comms\" agent now with this exact subtask: "+delegatedNotifyTask+" Do not create more tasks and do not answer until comms has handled the notification.")
+	if err := waitForPlanDelegateExecution(executeDone, taskSvc, notifySvc); err != nil {
 		return err
-	}); err != nil {
-		return err
-	}
-
-	if rs := f.Results(); len(rs) > 0 {
-		fmt.Println("\n\033[1m< conductor reply:\033[0m", rs[len(rs)-1].Reply)
 	}
 
 	// Prove plan was persisted to the real store.
@@ -444,7 +443,48 @@ func runPlanDelegate(provider string) error {
 	return nil
 }
 
-func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notifySvc *NotifyService, recoverMissingNotify func(context.Context) error) error {
+func planDelegateConductorStep(conductor agent.Agent) flow.StepFunc {
+	return func(ctx context.Context, in flow.State) (flow.State, error) {
+		prompt := "Create three launch tasks (Design, Build, Ship), then make sure owner@acme.com is notified: " + in.String()
+		rsp, err := conductor.Ask(ctx, prompt)
+		if err != nil {
+			return in, err
+		}
+		if rsp != nil && rsp.Reply != "" {
+			fmt.Println("\n\033[1m< conductor reply:\033[0m", rsp.Reply)
+		}
+		return in, nil
+	}
+}
+
+func requireDelegatedNotifyStep(taskSvc *TaskService, notifySvc *NotifyService, recoverMissingNotify func(context.Context) error) flow.StepFunc {
+	return func(ctx context.Context, in flow.State) (flow.State, error) {
+		tasks := taskSvc.count()
+		notify := notifySvc.count()
+		if notify == 1 {
+			return in, nil
+		}
+		if recoverMissingNotify == nil || tasks != 3 || notify != 0 {
+			return in, fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify)
+		}
+		settled, err := waitForNotifySideEffect(notifySvc, delegatedNotifySettleTimeout)
+		if err != nil {
+			return in, err
+		}
+		if !settled {
+			fmt.Print("\n\033[33mwarning:\033[0m conductor step completed before delegated notify; retrying the missing comms handoff once before the flow can complete.\n")
+			if err := recoverMissingNotify(ctx); err != nil {
+				return in, fmt.Errorf("delegation completed without required notify side effect and recovery failed: notify=%d, want 1: %w", notify, err)
+			}
+		}
+		if notify = notifySvc.count(); notify != 1 {
+			return in, fmt.Errorf("delegation recovery completed without required notify side effect: notify=%d, want 1", notify)
+		}
+		return in, nil
+	}
+}
+
+func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notifySvc *NotifyService) error {
 	ticker := time.NewTicker(50 * time.Millisecond)
 	defer ticker.Stop()
 	for {
@@ -463,25 +503,7 @@ func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notif
 				return fmt.Errorf("flow execute after side effects tasks=%d notify=%d: %w", tasks, notify, err)
 			}
 			if notify != 1 {
-				if recoverMissingNotify == nil || tasks != 3 || notify != 0 {
-					return fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify)
-				}
-				settled, err := waitForNotifySideEffect(notifySvc, delegatedNotifySettleTimeout)
-				if err != nil {
-					return err
-				}
-				if !settled {
-					fmt.Print("\n\033[33mwarning:\033[0m flow completed before delegated notify; retrying the missing comms handoff once.\n")
-					ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-					retryErr := recoverMissingNotify(ctx)
-					cancel()
-					if retryErr != nil {
-						return fmt.Errorf("delegation completed without required notify side effect and recovery failed: notify=%d, want 1: %w", notify, retryErr)
-					}
-				}
-				if notify = notifySvc.count(); notify != 1 {
-					return fmt.Errorf("delegation recovery completed without required notify side effect: notify=%d, want 1", notify)
-				}
+				return fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify)
 			}
 			return nil
 		case <-ticker.C:

internal/harness/plan-delegate/main_test.go

@@ -258,7 +258,7 @@ func TestPlanDelegateExecutionReportsDuplicateNotifyBeforeTimeout(t *testing.T)
 
 	done := make(chan error)
 	errCh := make(chan error, 1)
-	go func() { errCh <- waitForPlanDelegateExecution(done, new(TaskService), notifySvc, nil) }()
+	go func() { errCh <- waitForPlanDelegateExecution(done, new(TaskService), notifySvc) }()
 
 	select {
 	case err := <-errCh:
@@ -278,7 +278,7 @@ func TestPlanDelegateExecutionRejectsClaimedCompletionWithoutNotify(t *testing.T
 	done := make(chan error, 1)
 	done <- nil
 
-	err := waitForPlanDelegateExecution(done, new(TaskService), notifySvc, nil)
+	err := waitForPlanDelegateExecution(done, new(TaskService), notifySvc)
 	if err == nil {
 		t.Fatal("waitForPlanDelegateExecution returned nil, want missing notify side-effect error")
 	}
@@ -296,15 +296,13 @@ func TestPlanDelegateExecutionRecoversMissingNotifyOnce(t *testing.T) {
 		}
 	}
 	notifySvc := new(NotifyService)
-	done := make(chan error, 1)
-	done <- nil
 
 	recovered := false
-	err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, func(ctx context.Context) error {
+	_, err := requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error {
 		recovered = true
 		var rsp SendResponse
 		return notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp)
-	})
+	})(context.Background(), flow.State{})
 	if err != nil {
 		t.Fatalf("waitForPlanDelegateExecution returned %v, want recovery success", err)
 	}
@@ -325,8 +323,6 @@ func TestPlanDelegateExecutionWaitsForInFlightNotifyAfterFlowCompletion(t *testi
 		}
 	}
 	notifySvc := new(NotifyService)
-	done := make(chan error, 1)
-	done <- nil
 
 	go func() {
 		time.Sleep(100 * time.Millisecond)
@@ -335,11 +331,11 @@ func TestPlanDelegateExecutionWaitsForInFlightNotifyAfterFlowCompletion(t *testi
 	}()
 
 	recovered := false
-	err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, func(ctx context.Context) error {
+	_, err := requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error {
 		recovered = true
 		var rsp SendResponse
 		return notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp)
-	})
+	})(context.Background(), flow.State{})
 	if err != nil {
 		t.Fatalf("waitForPlanDelegateExecution returned %v, want in-flight notify success", err)
 	}
@@ -374,7 +370,7 @@ func TestPlanDelegateExecutionAcceptsClientTimeoutAfterSideEffects(t *testing.T)
 	done := make(chan error, 1)
 	done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"<nil>","status":"Request Timeout"}`)
 
-	if err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, nil); err != nil {
+	if err := waitForPlanDelegateExecution(done, taskSvc, notifySvc); err != nil {
 		t.Fatalf("waitForPlanDelegateExecution returned %v, want completed side effects to satisfy client timeout", err)
 	}
 }
@@ -383,7 +379,7 @@ func TestPlanDelegateExecutionClassifiesClientTimeoutBeforeSideEffects(t *testin
 	done := make(chan error, 1)
 	done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"<nil>","status":"Request Timeout"}`)
 
-	err := waitForPlanDelegateExecution(done, new(TaskService), new(NotifyService), nil)
+	err := waitForPlanDelegateExecution(done, new(TaskService), new(NotifyService))
 	if err == nil {
 		t.Fatal("waitForPlanDelegateExecution returned nil, want timeout before side effects to fail")
 	}
@@ -410,7 +406,7 @@ func TestPlanDelegateExecutionClassifiesPartialClientTimeout(t *testing.T) {
 	done := make(chan error, 1)
 	done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"<nil>","status":"Request Timeout"}`)
 
-	err := waitForPlanDelegateExecution(done, taskSvc, new(NotifyService), nil)
+	err := waitForPlanDelegateExecution(done, taskSvc, new(NotifyService))
 	if err == nil {
 		t.Fatal("waitForPlanDelegateExecution returned nil, want timeout before notify to fail")
 	}