Let Orchestra establish plan progress instead of the implementer asserting it

A detailed plan that nothing enforces is a document. This makes the phases
executable: the implementer may write exactly one status, and every other
status is a conclusion Orchestra reaches by running the plan's own commands.

    agent may request:  ready_for_verification
    agent may not assert: verified, awaiting_manual_verification, failed, skipped

The worker resolves commands from the coordinator, never from the request, so a
request cannot smuggle in a command the planner did not write. They run as argv
through exec with Dir set to the worktree, which is the quality gate's existing
envelope and not a weaker one. There is no shell, so a pipe is a literal
argument.

Project policy decides executable reach. registry.Project.Verification matches
argv positionally, and an absent policy refuses everything: a plan command is
agent-authored, so inheriting the operator-authored gate's reach by default
would be the wrong direction to fail in. A refused command is refused before
anything runs, and the refusal names the project and the command so the planner
learns its real reach.

Two bindings make the record mean something later. PlanRef, so progress earned
under plan A cannot survive into plan B. AtSHA, so "verified" does not outlive
the code that made it true: a record whose commit has moved is retained as
provenance and rendered as stale, never as a claim about the current tree.
Both are the same failure this codebase already fixed for reviews, which bind
to the commit they examined.

Manual steps hold a phase at awaiting_manual_verification. The sign-off is an
ordinary human decision whose subject carries the plan ref and the phase id, so
a later "looks good" on an unrelated thread cannot satisfy a gate nobody was
discussing.

A plan sealed before plan.md declares no executable unit, and says so: the
implement context states that phase progress is unavailable and the work
continues under the old semantics. Inventing phases it never had would be worse
than admitting it has none.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CVbaKucEYBjMqVeUgJUsc1

cmd/orchestra-worker/main.go

@@ -1776,6 +1776,13 @@ func (w *worker) federatedTurn(ctx context.Context, id string, a herdr.Adapter,
 		w.rotateForPhase(ctx, id, a, s)
 		return
 	}
+	// A plan phase asks to be verified before the work phase asks to move.
+	// Checked first because verifying the last phase is usually what makes a
+	// session ready to leave implement at all, and this session keeps running
+	// either way: verification is progress within a phase, not a change of one.
+	if w.requestPlanVerification(ctx, id, s) {
+		return
+	}
 	// The agent asks for a phase change here, at a boundary it has reached
 	// (F21). Orchestra decides, and an accepted change ends this session.
 	if w.requestPhase(ctx, id, s) {
@@ -2048,3 +2055,134 @@ func (w *worker) paneProgress(ctx context.Context, adapter herdr.CLIAdapter, s h
 	}
 	return adapter.PaneCapture(ctx, s, "recent")
 }
+
+// planProgressFile is the implementer's bounded verification request. It
+// carries one phase and one status, and the only status it may carry is a
+// request: an agent that could write "verified" would be marking its own work
+// done, which is the whole thing this machinery exists to prevent.
+const planProgressFile = "plan-progress.json"
+
+type planProgressRequest struct {
+	Phase  string `json:"phase"`
+	Status string `json:"status"`
+}
+
+// requestPlanVerification runs one phase's automated checks and posts the
+// results. It reports whether anything was done, so the caller does not treat
+// an absent request as a failure.
+//
+// The commands come from the accepted plan, which the coordinator resolves and
+// authorises. This worker never reads a command out of the request: the
+// request names a phase, and nothing else about it is trusted.
+func (w *worker) requestPlanVerification(ctx context.Context, id string, s herdr.Session) bool {
+	path := filepath.Join(s.Worktree, ".orchestra", planProgressFile)
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return false
+	}
+	var req planProgressRequest
+	if err := json.Unmarshal(b, &req); err != nil {
+		w.answerRefusedProgress(ctx, id, s, path, fmt.Sprintf(".orchestra/%s is not valid JSON: %v", planProgressFile, err))
+		return false
+	}
+	if req.Status != domain.PlanPhaseRequestStatus {
+		// Naming this refusal precisely matters: an agent that wrote
+		// "verified" is trying to establish a fact, and it has to learn that
+		// establishing facts is not its job rather than retry the same file.
+		w.answerRefusedProgress(ctx, id, s, path, fmt.Sprintf("status %q is not writable by you. The only status you may request is %q; Orchestra decides the rest by running the plan's own commands.", req.Status, domain.PlanPhaseRequestStatus))
+		return false
+	}
+	l := w.leases[id]
+	commands, err := w.api.PlanPhaseCommands(ctx, id, req.Phase, l.Epoch)
+	if err != nil {
+		// A refusal is an answer and reaches the agent. A transport failure is
+		// not, and the request survives for the next boundary.
+		var status *federation.StatusError
+		if errors.As(err, &status) && status.Code == http.StatusConflict {
+			w.answerRefusedProgress(ctx, id, s, path, status.Body)
+			return false
+		}
+		w.recordError(fmt.Errorf("plan verification %s: %w", id, err))
+		return false
+	}
+	head, err := git(ctx, s.Worktree, "rev-parse", "HEAD")
+	if err != nil {
+		w.recordError(fmt.Errorf("plan verification %s: head: %s: %w", id, head, err))
+		return false
+	}
+	runs := make([]federation.VerificationRun, 0, len(commands))
+	for _, argv := range commands {
+		// No shell. The quality gate's envelope is exec in the worktree, and a
+		// plan command is agent-authored, so it gets that envelope and never a
+		// weaker one. A pipe here is a literal argument.
+		cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
+		cmd.Dir = s.Worktree
+		out, runErr := cmd.CombinedOutput()
+		code := 0
+		if runErr != nil {
+			code = 1
+			var exit *exec.ExitError
+			if errors.As(runErr, &exit) {
+				code = exit.ExitCode()
+			}
+		}
+		runs = append(runs, federation.VerificationRun{Command: argv, ExitCode: code, Output: tail(string(out), review.MaxGateOutputBytes)})
+	}
+	status, err := w.api.RecordPlanPhase(ctx, id, req.Phase, strings.TrimSpace(string(head)), l.Epoch, runs)
+	if err != nil {
+		w.recordError(fmt.Errorf("plan verification %s: %w", id, err))
+		return false
+	}
+	// Durable before the request is removed. Removing first would lose the
+	// request if the response were lost, and the agent would wait on an answer
+	// that already happened.
+	if err := os.Remove(path); err != nil {
+		w.recordError(fmt.Errorf("plan verification %s: %w", id, err))
+	}
+	w.tellProgressOutcome(ctx, id, s, req.Phase, status, runs)
+	return true
+}
+
+// tellProgressOutcome delivers what Orchestra established. A phase that did
+// not verify is the case that matters: without this the agent sees a request
+// disappear and has to guess whether it worked.
+func (w *worker) tellProgressOutcome(ctx context.Context, id string, s herdr.Session, phase, status string, runs []federation.VerificationRun) {
+	var b strings.Builder
+	switch status {
+	case string(domain.PlanPhaseVerified):
+		fmt.Fprintf(&b, "Orchestra verified %s. Every automated check passed. Move to the next phase of the plan.", phase)
+	case string(domain.PlanPhaseAwaitingManual):
+		fmt.Fprintf(&b, "Orchestra ran %s's automated checks and they passed. The phase is waiting for the human to confirm its manual steps, which you cannot do. Continue with the next phase; the sign-off arrives on its own.", phase)
+	default:
+		fmt.Fprintf(&b, "Orchestra ran %s's checks and it is not verified. Fix what failed, then write .orchestra/%s again.\n", phase, planProgressFile)
+		for _, r := range runs {
+			if r.ExitCode == 0 {
+				continue
+			}
+			fmt.Fprintf(&b, "\n%s exited %d:\n%s\n", strings.Join(r.Command, " "), r.ExitCode, r.Output)
+		}
+	}
+	if err := w.sendPrompt(ctx, s, b.String()); err != nil {
+		w.recordError(fmt.Errorf("deliver plan verification %s: %w", id, err))
+	}
+	log.Printf("plan phase %s of %s: %s", phase, id, status)
+}
+
+// answerRefusedProgress tells the implementer why its request was refused and
+// drops the file so a corrected one can be written. Recording a refusal only
+// in worker health leaves a live session rewriting the same rejected file at
+// every boundary, which is the silent-loop shape this codebase keeps producing
+// (F39, F42, and the completion tail).
+func (w *worker) answerRefusedProgress(ctx context.Context, id string, s herdr.Session, path, reason string) {
+	w.recordError(fmt.Errorf("plan verification %s refused: %s", id, reason))
+	text := "Orchestra refused your verification request: " + reason +
+		"\n\nWrite a corrected .orchestra/" + planProgressFile + ", or keep working. Do not repeat the refused request."
+	if err := w.sendPrompt(ctx, s, text); err != nil {
+		w.recordError(fmt.Errorf("deliver plan verification refusal %s: %w", id, err))
+		return
+	}
+	if err := os.Remove(path); err != nil {
+		w.recordError(fmt.Errorf("plan verification %s: %w", id, err))
+	}
+	log.Printf("plan verification %s refused: %s", id, reason)
+}

cmd/orchestra-worker/phase_test.go

@@ -359,3 +359,101 @@ func TestClaudeHarnessReachesTheTurnBoundary(t *testing.T) {
 	}
 	_ = backend
 }
+
+// An agent may request verification. It may never assert one: writing
+// "verified" is claiming its own work is done, which is what the whole
+// machinery exists to prevent. The refusal has to reach the pane, or the
+// session rewrites the same rejected file at every boundary.
+func TestPlanVerificationRefusesAnyStatusButARequest(t *testing.T) {
+	for _, status := range []string{"verified", "awaiting_manual_verification", "failed", "skipped", ""} {
+		w, backend, wt, done := phaseWorker(t, func(rw http.ResponseWriter, r *http.Request) {
+			t.Errorf("a refused request reached the coordinator at %s", r.URL.Path)
+			rw.WriteHeader(http.StatusNotFound)
+		})
+		path := filepath.Join(wt, ".orchestra", planProgressFile)
+		if err := os.WriteFile(path, []byte(`{"phase":"phase-1","status":"`+status+`"}`), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if w.requestPlanVerification(context.Background(), "task", w.sessions["task"]) {
+			t.Fatalf("status %q was accepted", status)
+		}
+		if len(backend.prompts) == 0 {
+			t.Fatalf("status %q was refused with nothing delivered to the pane", status)
+		}
+		if !strings.Contains(backend.prompts[0], "ready_for_verification") {
+			t.Fatalf("the refusal does not name the only writable status: %s", backend.prompts[0])
+		}
+		if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("status %q left the refused request in place", status)
+		}
+		done()
+	}
+}
+
+// An absent request is not a failure and must not reach the pane.
+func TestNoPlanVerificationRequestIsSilent(t *testing.T) {
+	w, backend, _, done := phaseWorker(t, func(rw http.ResponseWriter, r *http.Request) {
+		t.Errorf("an absent request reached the coordinator at %s", r.URL.Path)
+	})
+	defer done()
+	if w.requestPlanVerification(context.Background(), "task", w.sessions["task"]) {
+		t.Fatal("an absent request reported work done")
+	}
+	if len(backend.prompts) != 0 {
+		t.Fatalf("an absent request spoke to the pane: %v", backend.prompts)
+	}
+}
+
+// The commands come from the accepted plan, resolved and authorised by the
+// coordinator. The worker must never take one out of the agent's request.
+func TestPlanVerificationRunsThePlansCommandsAndReportsExitCodes(t *testing.T) {
+	var reported map[string]any
+	w, backend, wt, done := phaseWorker(t, func(rw http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/plan-phase"):
+			json.NewEncoder(rw).Encode(map[string]any{"commands": [][]string{{"true"}, {"false"}}})
+		case strings.HasSuffix(r.URL.Path, "/plan-phase-result"):
+			json.NewDecoder(r.Body).Decode(&reported)
+			json.NewEncoder(rw).Encode(map[string]any{"status": "in_progress"})
+		default:
+			t.Errorf("unexpected %s", r.URL.Path)
+			rw.WriteHeader(http.StatusNotFound)
+		}
+	})
+	defer done()
+	// A git worktree, so the verification can anchor to a real commit.
+	for _, args := range [][]string{{"init"}, {"config", "user.email", "t@example.com"}, {"config", "user.name", "t"}, {"commit", "--allow-empty", "-m", "base"}} {
+		if out, err := git(context.Background(), wt, args...); err != nil {
+			t.Fatalf("git %v: %s: %v", args, out, err)
+		}
+	}
+	path := filepath.Join(wt, ".orchestra", planProgressFile)
+	if err := os.WriteFile(path, []byte(`{"phase":"phase-1","status":"ready_for_verification","commands":[["rm","-rf","/"]]}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if !w.requestPlanVerification(context.Background(), "task", w.sessions["task"]) {
+		t.Fatal("a valid request did nothing")
+	}
+	runs, _ := reported["runs"].([]any)
+	if len(runs) != 2 {
+		t.Fatalf("reported %d runs, want the plan's 2: %v", len(runs), reported)
+	}
+	first, _ := runs[0].(map[string]any)
+	second, _ := runs[1].(map[string]any)
+	if first["exit_code"].(float64) != 0 || second["exit_code"].(float64) == 0 {
+		t.Fatalf("exit codes were not reported faithfully: %v", runs)
+	}
+	// The command list in the request is ignored entirely.
+	cmd, _ := first["command"].([]any)
+	if len(cmd) != 1 || cmd[0].(string) != "true" {
+		t.Fatalf("the worker ran something other than the plan's command: %v", cmd)
+	}
+	if sha, _ := reported["at_sha"].(string); len(sha) != 40 {
+		t.Fatalf("the verification was not anchored to a commit: %q", sha)
+	}
+	// A phase that did not verify has to say why, or the agent sees its
+	// request vanish and guesses.
+	if len(backend.prompts) == 0 || !strings.Contains(backend.prompts[0], "not verified") {
+		t.Fatalf("the outcome was not delivered: %v", backend.prompts)
+	}
+}

cmd/orchestra/main.go

@@ -1339,7 +1339,7 @@ func main() {
 		w.WriteHeader(http.StatusNoContent)
 	})
 	mux.HandleFunc("/v1/federation/workers/", func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPost || (!strings.HasSuffix(r.URL.Path, "/heartbeat") && !strings.HasSuffix(r.URL.Path, "/renew") && !strings.HasSuffix(r.URL.Path, "/start") && !strings.HasSuffix(r.URL.Path, "/nack") && !strings.HasSuffix(r.URL.Path, "/handoff") && !strings.HasSuffix(r.URL.Path, "/pickup") && !strings.HasSuffix(r.URL.Path, "/complete") && !strings.HasSuffix(r.URL.Path, "/submit") && !strings.HasSuffix(r.URL.Path, "/captures")) {
+		if r.Method != http.MethodPost || (!strings.HasSuffix(r.URL.Path, "/heartbeat") && !strings.HasSuffix(r.URL.Path, "/renew") && !strings.HasSuffix(r.URL.Path, "/start") && !strings.HasSuffix(r.URL.Path, "/nack") && !strings.HasSuffix(r.URL.Path, "/handoff") && !strings.HasSuffix(r.URL.Path, "/pickup") && !strings.HasSuffix(r.URL.Path, "/complete") && !strings.HasSuffix(r.URL.Path, "/submit") && !strings.HasSuffix(r.URL.Path, "/plan-phase") && !strings.HasSuffix(r.URL.Path, "/plan-phase-result") && !strings.HasSuffix(r.URL.Path, "/captures")) {
 			http.Error(w, "not found", 404)
 			return
 		}
@@ -1389,23 +1389,26 @@ func main() {
 			return
 		}
 		var b struct {
-			TaskID          string                 `json:"task_id"`
-			TTLSeconds      int                    `json:"ttl_seconds"`
-			ExpectedVersion int                    `json:"expected_version"`
-			HandoffRef      string                 `json:"handoff_ref"`
-			AnchorSHA       string                 `json:"anchor_sha"`
-			TransactionID   string                 `json:"transaction_id"`
-			LeaseVersion    int                    `json:"lease_version"`
-			LeaseEpoch      string                 `json:"lease_epoch"`
-			ResultSHA       string                 `json:"result_sha"`
-			Branch          string                 `json:"branch"`
-			Remote          string                 `json:"remote"`
-			Receipt         map[string]any         `json:"receipt"`
-			FailureClass    string                 `json:"failure_class"`
-			LastError       string                 `json:"last_error"`
-			SessionEvidence domain.SessionEvidence `json:"session_evidence"`
-			Review          review.Result          `json:"review"`
-			Gate            domain.GateResult      `json:"gate"`
+			TaskID          string                       `json:"task_id"`
+			TTLSeconds      int                          `json:"ttl_seconds"`
+			ExpectedVersion int                          `json:"expected_version"`
+			HandoffRef      string                       `json:"handoff_ref"`
+			AnchorSHA       string                       `json:"anchor_sha"`
+			TransactionID   string                       `json:"transaction_id"`
+			LeaseVersion    int                          `json:"lease_version"`
+			LeaseEpoch      string                       `json:"lease_epoch"`
+			ResultSHA       string                       `json:"result_sha"`
+			Branch          string                       `json:"branch"`
+			Remote          string                       `json:"remote"`
+			Receipt         map[string]any               `json:"receipt"`
+			FailureClass    string                       `json:"failure_class"`
+			LastError       string                       `json:"last_error"`
+			SessionEvidence domain.SessionEvidence       `json:"session_evidence"`
+			Review          review.Result                `json:"review"`
+			Gate            domain.GateResult            `json:"gate"`
+			PhaseID         string                       `json:"phase_id"`
+			AtSHA           string                       `json:"at_sha"`
+			Runs            []operations.VerificationRun `json:"runs"`
 		}
 		if json.NewDecoder(r.Body).Decode(&b) != nil || b.TaskID == "" {
 			http.Error(w, "invalid lease body", 400)
@@ -1432,6 +1435,34 @@ func main() {
 			http.Error(w, "lease version conflict", http.StatusConflict)
 			return
 		}
+		if strings.HasSuffix(r.URL.Path, "/plan-phase") || strings.HasSuffix(r.URL.Path, "/plan-phase-result") {
+			project, ok := rr.Project(t.Project)
+			if !ok {
+				http.Error(w, "unknown project "+t.Project, 409)
+				return
+			}
+			if strings.HasSuffix(r.URL.Path, "/plan-phase") {
+				// Resolve and authorise before anything runs. A command the
+				// project does not permit is refused here, so a partial
+				// execution can never leave side effects behind.
+				phase, err := operations.PlanPhaseCommands(s, project, b.TaskID, b.PhaseID)
+				if err != nil {
+					http.Error(w, err.Error(), http.StatusConflict)
+					return
+				}
+				json.NewEncoder(w).Encode(map[string]any{"commands": phase.Automated})
+				return
+			}
+			e, err := operations.RecordPlanPhaseVerification(s, project, b.TaskID, b.PhaseID, b.AtSHA, b.Runs)
+			if err != nil {
+				http.Error(w, err.Error(), http.StatusConflict)
+				return
+			}
+			var rec domain.PlanPhaseRecord
+			_ = json.Unmarshal(e.Payload, &rec)
+			json.NewEncoder(w).Encode(map[string]any{"status": string(rec.Status), "event": e})
+			return
+		}
 		if strings.HasSuffix(r.URL.Path, "/submit") {
 			// Seal the review, then submit the commit it examined. Both events
 			// are Orchestra's; the worker supplies verified evidence and the

deploy/config.example.jsonc

@@ -17,6 +17,23 @@
                                                               // Overrides global ORCHESTRA_WORKTREE_ROOT.
       "quality_gate": "go test ./... && go vet ./..."      // Worker runs this before deterministic delivery.
       ,
+      // What a plan's automated verification may execute. A plan command is
+      // agent-authored, so it does not inherit the operator-authored quality
+      // gate's envelope: it runs as argv with no shell, and only if some
+      // pattern here matches it positionally. An absent policy refuses every
+      // plan command, and the planner is told so when it seals.
+      //   "*"      matches exactly one element, any value
+      //   "x/..."  matches a path argument under that prefix
+      //   a trailing "*" matches the remaining elements, and is the only way
+      //            a pattern authorises a longer command
+      "verification": {
+        "allowed": [
+          ["go", "test", "./..."],
+          ["go", "test", "./internal/..."],
+          ["go", "vet", "./..."],
+          ["go", "build", "./..."]
+        ]
+      },
       // Cognitive phase path. Omit for the default
       // frame -> research -> plan -> implement -> review. A phase left out is
       // skipped, which is how a trivial project runs frame/implement/review.

internal/agentctx/agentctx.go

@@ -305,6 +305,12 @@ func renderTask(in Input) string {
 	fmt.Fprintf(&b, "- uncommitted changes: %t\n", in.Git.Dirty)
 
 	b.WriteString(renderSealed(in))
+	// Below the plan, above continuity. Progress is a fact about the plan, so
+	// it follows the plan; continuity is one predecessor's account, so it
+	// ranks under both.
+	if in.Phase == domain.WorkPhaseImplement {
+		b.WriteString(renderPlanProgress(in))
+	}
 	b.WriteString(renderFindings(in))
 	b.WriteString(renderEvidence(in))
 
@@ -410,6 +416,49 @@ func fallback(s string) string {
 //	plan      -> accepted research
 //	implement -> accepted research and accepted plan
 //	review    -> accepted plan
+// renderPlanProgress states what Orchestra established about the accepted
+// plan, which is the half a rotated successor cannot reconstruct. A verified
+// phase is named with the commit it was verified at, and labelled stale when
+// the tree has moved, so "verified" never reads as a claim about code that has
+// since changed.
+func renderPlanProgress(in Input) string {
+	if in.Plan == nil || len(in.Plan.Phases) == 0 {
+		return ""
+	}
+	records := in.Task.PlanPhases()
+	byPhase := map[string]domain.PlanPhaseRecord{}
+	for _, r := range records {
+		byPhase[r.PhaseID] = r
+	}
+	var b strings.Builder
+	b.WriteString("\n## Plan progress\n\nOrchestra established this by running the plan's own verification. You cannot write it.\n\n")
+	current := ""
+	for _, phase := range in.Plan.Phases {
+		rec, ok := byPhase[phase.ID]
+		switch {
+		case !ok:
+			fmt.Fprintf(&b, "- %s (%s): not started\n", phase.ID, collapse(phase.Name))
+		case rec.Status == domain.PlanPhaseVerified && rec.Stale(in.Git.HeadSHA):
+			fmt.Fprintf(&b, "- %s (%s): verified at %s, stale because the tree is now at %s\n", phase.ID, collapse(phase.Name), short(rec.AtSHA), short(in.Git.HeadSHA))
+		case rec.Status == domain.PlanPhaseVerified:
+			fmt.Fprintf(&b, "- %s (%s): verified at %s\n", phase.ID, collapse(phase.Name), short(rec.AtSHA))
+		case rec.Status == domain.PlanPhaseAwaitingManual:
+			fmt.Fprintf(&b, "- %s (%s): automated checks passed at %s, waiting for the human to confirm the manual steps\n", phase.ID, collapse(phase.Name), short(rec.AtSHA))
+		default:
+			fmt.Fprintf(&b, "- %s (%s): in progress, last verification exited %v\n", phase.ID, collapse(phase.Name), rec.ExitCodes)
+		}
+		if current == "" && (!ok || rec.Status != domain.PlanPhaseVerified) {
+			current = phase.ID
+		}
+	}
+	if current == "" {
+		b.WriteString("\nEvery phase is verified.\n")
+		return b.String()
+	}
+	fmt.Fprintf(&b, "\nYour current phase is %s. When you believe it is done, write .orchestra/plan-progress.json:\n\n    {\"phase\": %q, \"status\": \"ready_for_verification\"}\n\nThat is a request, not a result. Orchestra runs that phase's own automated commands and records what they exit. No other status is writable: you cannot mark a phase verified, and claiming one would be refused.\n", current, current)
+	return b.String()
+}
+
 func renderSealed(in Input) string {
 	var b strings.Builder
 	research := in.Research
@@ -446,6 +495,12 @@ func renderSealed(in Input) string {
 			}
 		}
 	}
+	if plan != nil && len(plan.Phases) == 0 {
+		// A plan sealed before plan.md names no executable unit, so phase
+		// progress cannot apply to it. Saying so beats a silently absent
+		// progress section, which reads as "no phase is done yet".
+		b.WriteString("\nThis is a legacy accepted plan, sealed before plan.md. Phase progress is unavailable for it: work from the plan text and finish the phase the usual way.\n")
+	}
 	if plan != nil {
 		// Verbatim, never collapsed. The plan is the execution map an
 		// implement session works from, and a rotated successor has to receive

internal/domain/domain.go

@@ -203,7 +203,11 @@ type Task struct {
 	// finished. The next phase reads these, never the session that wrote them.
 	ResearchRef string `json:"research_ref,omitempty"`
 	PlanRef     string `json:"plan_ref,omitempty"`
-	LastError   string `json:"last_error,omitempty"`
+	// PlanProgress is what Orchestra established about the accepted plan's
+	// phases. Read it through PlanPhases, which discards records belonging to
+	// a superseded plan.
+	PlanProgress *PlanProgress `json:"plan_progress,omitempty"`
+	LastError    string        `json:"last_error,omitempty"`
 }
 
 // ReviewRef binds a sealed review artifact to one commit.
@@ -262,7 +266,7 @@ func ValidateEvent(e Event) error {
 	if e.SchemaVersion >= 2 && strings.TrimSpace(e.Surface) == "" {
 		return fmt.Errorf("%w: surface required", ErrInvalid)
 	}
-	allowed := map[string]bool{"TaskCreated": true, "TaskLeased": true, "TaskLeaseRenewed": true, "TaskReleased": true, "TaskLaunchAcknowledged": true, "TaskPickupValidated": true, "TaskCompleted": true, "TaskFailed": true, "TaskBlocked": true, "TaskNeedsAttention": true, "ApprovalRequested": true, "ApprovalGranted": true, "ApprovalDenied": true, "TaskAmended": true, "TaskCorrected": true, "QuotaReported": true, "StandupAdvisory": true, EventHumanDecisionRecorded: true, EventHumanDecisionSuperseded: true, EventWorkPhaseChanged: true, EventDeferredFindingRecorded: true, EventReviewRecorded: true, EventTaskSubmitted: true, EventTaskChangesRequested: true}
+	allowed := map[string]bool{"TaskCreated": true, "TaskLeased": true, "TaskLeaseRenewed": true, "TaskReleased": true, "TaskLaunchAcknowledged": true, "TaskPickupValidated": true, "TaskCompleted": true, "TaskFailed": true, "TaskBlocked": true, "TaskNeedsAttention": true, "ApprovalRequested": true, "ApprovalGranted": true, "ApprovalDenied": true, "TaskAmended": true, "TaskCorrected": true, "QuotaReported": true, "StandupAdvisory": true, EventHumanDecisionRecorded: true, EventHumanDecisionSuperseded: true, EventWorkPhaseChanged: true, EventDeferredFindingRecorded: true, EventReviewRecorded: true, EventTaskSubmitted: true, EventTaskChangesRequested: true, EventPlanPhaseVerified: true}
 	if !allowed[e.Type] {
 		return fmt.Errorf("%w: unknown type %q", ErrInvalid, e.Type)
 	}
@@ -540,6 +544,8 @@ func ValidatePayload(typ string, p map[string]any) error {
 				return fmt.Errorf("%w: decision_ids entries must be ids", ErrInvalid)
 			}
 		}
+	case EventPlanPhaseVerified:
+		return ValidatePlanPhaseVerified(p)
 	case EventReviewRecorded:
 		if err := requiredHash(p, "artifact_ref"); err != nil {
 			return err

internal/domain/planprogress.go

@@ -0,0 +1,135 @@
+package domain
+
+import (
+	"fmt"
+	"strings"
+	"time"
+)
+
+// EventPlanPhaseVerified records that Orchestra ran a plan phase's automated
+// verification and what happened. The implementer never emits it: an agent may
+// request verification, and only the plane can establish it.
+const EventPlanPhaseVerified = "PlanPhaseVerified"
+
+// PlanPhaseStatus is what Orchestra established about one phase.
+type PlanPhaseStatus string
+
+const (
+	// PlanPhaseInProgress is the default and the outcome of a failed run. It
+	// is never written by a request, only left in place by one.
+	PlanPhaseInProgress PlanPhaseStatus = "in_progress"
+	// PlanPhaseAwaitingManual means every automated check passed and manual
+	// steps remain. A human signs those off; the agent cannot.
+	PlanPhaseAwaitingManual PlanPhaseStatus = "awaiting_manual_verification"
+	// PlanPhaseVerified means nothing further is required for this phase.
+	PlanPhaseVerified PlanPhaseStatus = "verified"
+)
+
+func (s PlanPhaseStatus) Valid() bool {
+	switch s {
+	case PlanPhaseInProgress, PlanPhaseAwaitingManual, PlanPhaseVerified:
+		return true
+	}
+	return false
+}
+
+// PlanPhaseRequestStatus is the single value an implementer may write. Every
+// other status is a conclusion Orchestra reaches, so allowing an agent to
+// assert one would let it declare its own work verified.
+const PlanPhaseRequestStatus = "ready_for_verification"
+
+// PlanPhaseRecord is one verification run, bound to the plan it belongs to and
+// the commit it ran against.
+//
+// Both bindings are load-bearing. Without PlanRef, a phase verified under plan
+// A survives into plan B, which is the same class of bug as a review that
+// outlives the commit it examined. Without AtSHA, "verified" outlives the code
+// that made it true.
+type PlanPhaseRecord struct {
+	PlanRef   string          `json:"plan_ref"`
+	PhaseID   string          `json:"phase_id"`
+	Status    PlanPhaseStatus `json:"status"`
+	Commands  [][]string      `json:"commands,omitempty"`
+	ExitCodes []int           `json:"exit_codes,omitempty"`
+	AtSHA     string          `json:"at_sha"`
+	// EvidenceRef is the CAS ref of the captured command output.
+	EvidenceRef string    `json:"evidence_ref,omitempty"`
+	At          time.Time `json:"at"`
+}
+
+// Stale reports whether the tree has moved since this phase was verified. A
+// stale record is retained and labelled rather than discarded: it is still
+// true that the phase passed at that commit, and hiding it would lose the
+// provenance. What it must never do is read as current.
+func (r PlanPhaseRecord) Stale(headSHA string) bool {
+	return headSHA != "" && r.AtSHA != "" && r.AtSHA != headSHA
+}
+
+// PlanProgress is the durable verification state for one accepted plan.
+type PlanProgress struct {
+	// PlanRef is the plan these records belong to. A record from a superseded
+	// plan is never counted, so a replan cannot inherit progress it did not
+	// earn.
+	PlanRef string            `json:"plan_ref"`
+	Phases  []PlanPhaseRecord `json:"phases,omitempty"`
+}
+
+// PlanPhases returns the records that belong to the currently accepted plan.
+// A task whose plan was superseded reports none, whatever the log still holds.
+func (t Task) PlanPhases() []PlanPhaseRecord {
+	if t.PlanProgress == nil || t.PlanRef == "" || t.PlanProgress.PlanRef != t.PlanRef {
+		return nil
+	}
+	return t.PlanProgress.Phases
+}
+
+// PlanPhase returns the record for one phase of the accepted plan.
+func (t Task) PlanPhase(id string) (PlanPhaseRecord, bool) {
+	for _, r := range t.PlanPhases() {
+		if r.PhaseID == id {
+			return r, true
+		}
+	}
+	return PlanPhaseRecord{}, false
+}
+
+// PlanPhaseSubject is the decision subject a manual sign-off carries. The key
+// binds the approval to one phase of one plan, so a later "looks good" on an
+// unrelated thread cannot satisfy a gate nobody was talking about.
+func PlanPhaseSubject(planRef, phaseID string) string {
+	return "plan_phase_verification:" + planRef + ":" + phaseID
+}
+
+const maxVerificationCommands = 16
+
+func ValidatePlanPhaseVerified(p map[string]any) error {
+	planRef, _ := p["plan_ref"].(string)
+	if strings.TrimSpace(planRef) == "" {
+		return fmt.Errorf("%w: plan_ref required", ErrInvalid)
+	}
+	phaseID, _ := p["phase_id"].(string)
+	if strings.TrimSpace(phaseID) == "" {
+		return fmt.Errorf("%w: phase_id required", ErrInvalid)
+	}
+	status, _ := p["status"].(string)
+	if !PlanPhaseStatus(status).Valid() {
+		return fmt.Errorf("%w: status %q is not a plan phase status", ErrInvalid, status)
+	}
+	if sha, _ := p["at_sha"].(string); len(sha) != 40 {
+		return fmt.Errorf("%w: at_sha must be a full commit sha", ErrInvalid)
+	}
+	codes, _ := p["exit_codes"].([]any)
+	if len(codes) > maxVerificationCommands {
+		return fmt.Errorf("%w: %d exit codes exceeds the %d command bound", ErrInvalid, len(codes), maxVerificationCommands)
+	}
+	// A verified phase whose commands failed would be a contradiction the
+	// reducer could not detect later.
+	if PlanPhaseStatus(status) != PlanPhaseInProgress {
+		for _, c := range codes {
+			if code, ok := c.(float64); !ok || code != 0 {
+				return fmt.Errorf("%w: status %q cannot carry a non-zero exit code", ErrInvalid, status)
+			}
+		}
+	}
+	return nil
+}

internal/domain/planprogress_test.go

@@ -0,0 +1,78 @@
+package domain
+
+import "testing"
+
+// Progress earned under plan A must not survive into plan B. Without this, a
+// replan inherits verification it did not earn, which is the same shape as a
+// review outliving the commit it examined.
+//
+// The reducer also clears the records on a re-seal. This guards the read side,
+// so a record that reaches a reader by any other route is still not counted.
+func TestPlanPhasesIgnoresRecordsFromASupersededPlan(t *testing.T) {
+	task := Task{
+		PlanRef: "plan-b",
+		PlanProgress: &PlanProgress{PlanRef: "plan-a", Phases: []PlanPhaseRecord{
+			{PhaseID: "phase-1", PlanRef: "plan-a", Status: PlanPhaseVerified, AtSHA: "abc"},
+		}},
+	}
+	if got := task.PlanPhases(); len(got) != 0 {
+		t.Fatalf("progress from plan-a counted under plan-b: %+v", got)
+	}
+	if _, ok := task.PlanPhase("phase-1"); ok {
+		t.Fatal("a superseded phase was addressable")
+	}
+	task.PlanProgress.PlanRef = "plan-b"
+	if got := task.PlanPhases(); len(got) != 1 {
+		t.Fatalf("progress for the accepted plan was discarded: %+v", got)
+	}
+}
+
+// A task with no accepted plan counts nothing, whatever the projection holds.
+func TestPlanPhasesRequiresAnAcceptedPlan(t *testing.T) {
+	task := Task{PlanProgress: &PlanProgress{PlanRef: "plan-a", Phases: []PlanPhaseRecord{{PhaseID: "phase-1"}}}}
+	if got := task.PlanPhases(); len(got) != 0 {
+		t.Fatalf("progress counted with no PlanRef: %+v", got)
+	}
+}
+
+func TestPlanPhaseSubjectBindsPlanAndPhase(t *testing.T) {
+	if PlanPhaseSubject("ref-a", "phase-1") == PlanPhaseSubject("ref-b", "phase-1") {
+		t.Fatal("two plans share a manual sign-off subject")
+	}
+	if PlanPhaseSubject("ref-a", "phase-1") == PlanPhaseSubject("ref-a", "phase-2") {
+		t.Fatal("two phases share a manual sign-off subject")
+	}
+}
+
+// An agent may request verification. Every other status is a conclusion
+// Orchestra reaches, so a payload claiming one with a failing command is a
+// contradiction the reducer could not detect later.
+func TestVerifiedStatusCannotCarryAFailingCommand(t *testing.T) {
+	sha := "1111111111111111111111111111111111111111"
+	base := func() map[string]any {
+		return map[string]any{"plan_ref": "r", "phase_id": "phase-1", "at_sha": sha}
+	}
+	ok := base()
+	ok["status"] = string(PlanPhaseVerified)
+	ok["exit_codes"] = []any{float64(0)}
+	if err := ValidatePlanPhaseVerified(ok); err != nil {
+		t.Fatalf("a passing verification was refused: %v", err)
+	}
+	bad := base()
+	bad["status"] = string(PlanPhaseVerified)
+	bad["exit_codes"] = []any{float64(1)}
+	if err := ValidatePlanPhaseVerified(bad); err == nil {
+		t.Fatal("verified with a non-zero exit code was accepted")
+	}
+	agent := base()
+	agent["status"] = PlanPhaseRequestStatus
+	if err := ValidatePlanPhaseVerified(agent); err == nil {
+		t.Fatal("ready_for_verification was accepted as a durable status")
+	}
+	noSHA := base()
+	noSHA["status"] = string(PlanPhaseVerified)
+	noSHA["at_sha"] = "abc"
+	if err := ValidatePlanPhaseVerified(noSHA); err == nil {
+		t.Fatal("a verification with no anchored commit was accepted")
+	}
+}

internal/federation/client.go

@@ -326,6 +326,52 @@ func (c Client) Submit(ctx context.Context, taskID, epoch string, expectedVersio
 	return out.Status, nil
 }
 
+// VerificationRun is one plan command the worker executed.
+type VerificationRun struct {
+	Command  []string `json:"command"`
+	ExitCode int      `json:"exit_code"`
+	Output   string   `json:"output,omitempty"`
+}
+
+// PlanPhaseCommands asks the coordinator which commands a phase's verification
+// runs. The worker never takes a command from the agent's request: the plan
+// settled that at seal time, and the project's policy authorises it here.
+func (c Client) PlanPhaseCommands(ctx context.Context, taskID, phaseID, epoch string) ([][]string, error) {
+	resp, err := c.request(ctx, http.MethodPost, "/v1/federation/workers/"+url.PathEscape(c.WorkerID)+"/plan-phase", map[string]any{
+		"task_id": taskID, "phase_id": phaseID, "lease_epoch": epoch,
+	})
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var out struct {
+		Commands [][]string `json:"commands"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		return nil, err
+	}
+	return out.Commands, nil
+}
+
+// RecordPlanPhase reports what the commands exited and returns the status
+// Orchestra established. The worker supplies evidence; it does not conclude.
+func (c Client) RecordPlanPhase(ctx context.Context, taskID, phaseID, atSHA, epoch string, runs []VerificationRun) (string, error) {
+	resp, err := c.request(ctx, http.MethodPost, "/v1/federation/workers/"+url.PathEscape(c.WorkerID)+"/plan-phase-result", map[string]any{
+		"task_id": taskID, "phase_id": phaseID, "at_sha": atSHA, "lease_epoch": epoch, "runs": runs,
+	})
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	var out struct {
+		Status string `json:"status"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		return "", err
+	}
+	return out.Status, nil
+}
+
 func (c Client) PublishCapture(ctx context.Context, capture Capture) (Capture, error) {
 	resp, err := c.request(ctx, http.MethodPost, "/v1/federation/workers/"+url.PathEscape(c.WorkerID)+"/captures", capture)
 	if err != nil {

internal/operations/planprogress.go

@@ -0,0 +1,171 @@
+package operations
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	"orchestra/internal/authz"
+	"orchestra/internal/domain"
+	"orchestra/internal/registry"
+	"orchestra/internal/store"
+	"orchestra/internal/workphase"
+)
+
+// ErrPlanPhase reports that a verification request cannot proceed. The reason
+// is always specific, because it is delivered to a live implementer that has
+// to act on it.
+var ErrPlanPhase = fmt.Errorf("plan phase verification refused")
+
+// VerificationRun is the outcome of one command the worker executed.
+type VerificationRun struct {
+	Command  []string `json:"command"`
+	ExitCode int      `json:"exit_code"`
+	Output   string   `json:"output,omitempty"`
+}
+
+// PlanPhaseCommands resolves the commands a phase's verification will run.
+//
+// The commands come from the accepted plan, never from the request. An
+// implementer asks to verify a phase; what that phase is checked with was
+// settled when the plan was sealed, so a request cannot smuggle in a command
+// the planner did not write.
+//
+// Every command is checked against the project's policy before any of them
+// runs. A partial execution followed by a refusal would leave side effects
+// behind with nothing recording them.
+func PlanPhaseCommands(s *store.Store, project registry.Project, taskID, phaseID string) (workphase.PlanPhase, error) {
+	t, ok := s.Task(taskID)
+	if !ok {
+		return workphase.PlanPhase{}, domain.ErrNotFound
+	}
+	if t.PlanRef == "" {
+		return workphase.PlanPhase{}, fmt.Errorf("%w: this task has no accepted plan", ErrPlanPhase)
+	}
+	raw, err := s.Artifact(t.PlanRef)
+	if err != nil {
+		return workphase.PlanPhase{}, fmt.Errorf("read accepted plan: %w", err)
+	}
+	doc, err := workphase.DecodeStoredPlan(raw)
+	if err != nil {
+		return workphase.PlanPhase{}, fmt.Errorf("read accepted plan: %w", err)
+	}
+	if len(doc.Phases) == 0 {
+		// A plan sealed before plan.md names no executable unit. Saying so is
+		// the honest answer; inventing a phase would make progress against a
+		// plan that never had any.
+		return workphase.PlanPhase{}, fmt.Errorf("%w: the accepted plan predates plan.md and declares no phases, so phase progress does not apply to it", ErrPlanPhase)
+	}
+	phase, ok := doc.Phase(phaseID)
+	if !ok {
+		return workphase.PlanPhase{}, fmt.Errorf("%w: the accepted plan has no %s; it has %s", ErrPlanPhase, phaseID, phaseNames(doc))
+	}
+	for _, argv := range phase.Automated {
+		if allowed, why := project.Verification.Allows(argv); !allowed {
+			// Refused before anything ran. The planner wrote a command the
+			// project does not permit, and the implementer is told rather
+			// than left retrying a phase that can never verify.
+			return workphase.PlanPhase{}, fmt.Errorf("%w: %s declares a command %s cannot run: %s", ErrPlanPhase, phaseID, project.ID, why)
+		}
+	}
+	return phase, nil
+}
+
+func phaseNames(doc workphase.PlanDoc) string {
+	out := make([]string, 0, len(doc.Phases))
+	for _, p := range doc.Phases {
+		out = append(out, p.ID)
+	}
+	return strings.Join(out, ", ")
+}
+
+// RecordPlanPhaseVerification establishes what the runs prove, and appends the
+// durable record.
+//
+// The status is derived here and never taken from the caller. An implementer
+// may request verification; only this function decides whether a phase is
+// verified, awaiting a human, or still in progress.
+func RecordPlanPhaseVerification(s *store.Store, project registry.Project, taskID, phaseID, atSHA string, runs []VerificationRun) (domain.Event, error) {
+	t, ok := s.Task(taskID)
+	if !ok {
+		return domain.Event{}, domain.ErrNotFound
+	}
+	if len(atSHA) != 40 {
+		return domain.Event{}, fmt.Errorf("%w: verification must name the commit it ran against", ErrPlanPhase)
+	}
+	phase, err := PlanPhaseCommands(s, project, taskID, phaseID)
+	if err != nil {
+		return domain.Event{}, err
+	}
+	if len(runs) != len(phase.Automated) {
+		return domain.Event{}, fmt.Errorf("%w: %s declares %d automated commands but %d results were reported", ErrPlanPhase, phaseID, len(phase.Automated), len(runs))
+	}
+	record := domain.PlanPhaseRecord{
+		PlanRef: t.PlanRef, PhaseID: phaseID, AtSHA: atSHA,
+		Status: domain.PlanPhaseVerified, At: time.Now().UTC(),
+	}
+	for i, r := range runs {
+		// The result must describe the command the plan named. A reordered or
+		// substituted result would attribute one command's exit code to
+		// another.
+		if strings.Join(r.Command, "\x00") != strings.Join(phase.Automated[i], "\x00") {
+			return domain.Event{}, fmt.Errorf("%w: result %d reports %q but the plan declares %q", ErrPlanPhase, i, strings.Join(r.Command, " "), strings.Join(phase.Automated[i], " "))
+		}
+		record.Commands = append(record.Commands, r.Command)
+		record.ExitCodes = append(record.ExitCodes, r.ExitCode)
+		if r.ExitCode != 0 {
+			record.Status = domain.PlanPhaseInProgress
+		}
+	}
+	if record.Status == domain.PlanPhaseVerified && len(phase.Manual) > 0 {
+		// Automated checks passing is not the whole phase. A human owns the
+		// manual steps, and the phase waits rather than claiming more than
+		// was established.
+		record.Status = domain.PlanPhaseAwaitingManual
+	}
+	if record.Status != domain.PlanPhaseInProgress && manuallySignedOff(s, t, phaseID) {
+		record.Status = domain.PlanPhaseVerified
+	}
+	if ref, err := s.PutArtifact(verificationEvidence(runs)); err == nil {
+		record.EvidenceRef = ref
+	} else {
+		return domain.Event{}, fmt.Errorf("store verification evidence: %w", err)
+	}
+	payload := map[string]any{
+		"plan_ref": record.PlanRef, "phase_id": record.PhaseID, "status": string(record.Status),
+		"commands": record.Commands, "exit_codes": record.ExitCodes, "at_sha": record.AtSHA,
+		"evidence_ref": record.EvidenceRef, "at": record.At,
+	}
+	if t.Lease != nil {
+		payload["harness_id"], payload["lease_epoch"] = t.Lease.HarnessID, t.Lease.Epoch
+	}
+	b, err := json.Marshal(payload)
+	if err != nil {
+		return domain.Event{}, err
+	}
+	e := domain.Event{ID: domain.NewID(), Type: domain.EventPlanPhaseVerified, TaskID: taskID, Version: t.Version + 1, Payload: b, Surface: string(authz.System)}
+	return e, s.Append(e)
+}
+
+// manuallySignedOff reports whether a human has already approved this exact
+// phase of this exact plan. The subject carries both, so a later "looks good"
+// on an unrelated thread cannot satisfy a gate nobody was discussing.
+func manuallySignedOff(s *store.Store, t domain.Task, phaseID string) bool {
+	intent, err := s.EffectiveIntent(t.ID)
+	if err != nil {
+		return false
+	}
+	subject := domain.PlanPhaseSubject(t.PlanRef, phaseID)
+	for _, d := range intent.Decisions {
+		if d.Subject == subject {
+			return true
+		}
+	}
+	return false
+}
+
+func verificationEvidence(runs []VerificationRun) []byte {
+	b, _ := json.Marshal(runs)
+	return b
+}

internal/operations/planprogress_test.go

@@ -0,0 +1,267 @@
+package operations
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"orchestra/internal/authz"
+	"orchestra/internal/domain"
+	"orchestra/internal/registry"
+	"orchestra/internal/store"
+)
+
+const shaOne = "1111111111111111111111111111111111111111"
+const shaTwo = "2222222222222222222222222222222222222222"
+
+func planProject() registry.Project {
+	p := registry.Project{
+		ID: "demo", MachineAffinity: []string{"m"},
+		WorkPhases: []domain.WorkPhase{domain.WorkPhaseFrame, domain.WorkPhaseResearch, domain.WorkPhasePlan, domain.WorkPhaseImplement, domain.WorkPhaseReview},
+	}
+	p.Verification.Allowed = [][]string{{"go", "test", "./internal/..."}, {"go", "build", "./..."}}
+	return p
+}
+
+// planWith seals research and a plan, leaving the task in implement.
+func planWith(t *testing.T, markdown string) (*store.Store, registry.Project, string) {
+	t.Helper()
+	s, id := phaseStore(t)
+	project := planProject()
+	if _, err := AdvanceWorkPhase(s, project, id, nil); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := AdvanceWorkPhase(s, project, id, sealed(t, research)); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := AdvanceWorkPhase(s, project, id, []byte(markdown)); err != nil {
+		t.Fatal(err)
+	}
+	return s, project, id
+}
+
+const twoPhasePlan = "# Two phase plan\n" + `
+## Overview
+Two phases.
+
+## Current state
+Nothing, per research:r1.
+
+## Desired end state
+Both phases done.
+
+## Non-goals
+None.
+
+## Approach
+Straightforward.
+
+## Phase 1: Build
+
+### Files
+- a.go
+
+### Changes
+Add a.
+
+### Verification
+
+#### Automated
+- run: ["go", "build", "./..."]
+
+## Phase 2: Test
+
+### Files
+- b.go
+
+### Changes
+Add b.
+
+### Verification
+
+#### Automated
+- run: ["go", "test", "./internal/..."]
+
+#### Manual
+- Confirm the output by eye.
+
+## Testing strategy
+Per phase.
+
+## Risks and edge cases
+None.
+
+## Migration
+None.
+
+## References
+- research:r1
+`
+
+func TestPassingCommandsVerifyThePhase(t *testing.T) {
+	s, project, id := planWith(t, twoPhasePlan)
+	if _, err := RecordPlanPhaseVerification(s, project, id, "phase-1", shaOne,
+		[]VerificationRun{{Command: []string{"go", "build", "./..."}, ExitCode: 0}}); err != nil {
+		t.Fatal(err)
+	}
+	task, _ := s.Task(id)
+	rec, ok := task.PlanPhase("phase-1")
+	if !ok || rec.Status != domain.PlanPhaseVerified {
+		t.Fatalf("phase-1 = %+v", rec)
+	}
+	if rec.AtSHA != shaOne || rec.PlanRef != task.PlanRef {
+		t.Fatalf("record is not bound to the plan and the commit: %+v", rec)
+	}
+}
+
+// A failing command leaves the phase where it was. "Verified" is a conclusion
+// about the commands, never about the request that asked for them.
+func TestFailingCommandLeavesThePhaseInProgress(t *testing.T) {
+	s, project, id := planWith(t, twoPhasePlan)
+	if _, err := RecordPlanPhaseVerification(s, project, id, "phase-1", shaOne,
+		[]VerificationRun{{Command: []string{"go", "build", "./..."}, ExitCode: 2}}); err != nil {
+		t.Fatal(err)
+	}
+	task, _ := s.Task(id)
+	rec, _ := task.PlanPhase("phase-1")
+	if rec.Status != domain.PlanPhaseInProgress {
+		t.Fatalf("status = %q, want in_progress", rec.Status)
+	}
+	if len(rec.ExitCodes) != 1 || rec.ExitCodes[0] != 2 {
+		t.Fatalf("the exit code was not recorded: %+v", rec)
+	}
+}
+
+// Automated checks passing is not the whole phase when manual steps exist.
+func TestManualStepsHoldThePhaseUntilAHumanSignsOff(t *testing.T) {
+	s, project, id := planWith(t, twoPhasePlan)
+	if _, err := RecordPlanPhaseVerification(s, project, id, "phase-2", shaOne,
+		[]VerificationRun{{Command: []string{"go", "test", "./internal/..."}, ExitCode: 0}}); err != nil {
+		t.Fatal(err)
+	}
+	task, _ := s.Task(id)
+	rec, _ := task.PlanPhase("phase-2")
+	if rec.Status != domain.PlanPhaseAwaitingManual {
+		t.Fatalf("status = %q, want awaiting_manual_verification", rec.Status)
+	}
+
+	// A generic later comment must not satisfy the gate.
+	humanReply(t, s, id, "d-generic", "looks good")
+	task, _ = s.Task(id)
+	rec, _ = task.PlanPhase("phase-2")
+	if rec.Status != domain.PlanPhaseAwaitingManual {
+		t.Fatal("an unrelated comment satisfied a manual verification gate")
+	}
+
+	// The sign-off names the plan and the phase it approves.
+	signOff(t, s, id, domain.PlanPhaseSubject(task.PlanRef, "phase-2"))
+	task, _ = s.Task(id)
+	rec, _ = task.PlanPhase("phase-2")
+	if rec.Status != domain.PlanPhaseVerified {
+		t.Fatalf("status = %q after a bound sign-off, want verified", rec.Status)
+	}
+}
+
+// A sign-off is bound to one plan. Replanning does not inherit it.
+func TestSignOffForAnotherPlanDoesNotVerify(t *testing.T) {
+	s, project, id := planWith(t, twoPhasePlan)
+	if _, err := RecordPlanPhaseVerification(s, project, id, "phase-2", shaOne,
+		[]VerificationRun{{Command: []string{"go", "test", "./internal/..."}, ExitCode: 0}}); err != nil {
+		t.Fatal(err)
+	}
+	signOff(t, s, id, domain.PlanPhaseSubject("some-other-plan-ref", "phase-2"))
+	task, _ := s.Task(id)
+	rec, _ := task.PlanPhase("phase-2")
+	if rec.Status != domain.PlanPhaseAwaitingManual {
+		t.Fatalf("a sign-off naming another plan verified this one: %q", rec.Status)
+	}
+}
+
+// Verified at X, code moves to Y: the record stands as provenance and must
+// read as stale, never as a claim about the current tree.
+func TestVerificationGoesStaleWhenTheTreeMoves(t *testing.T) {
+	s, project, id := planWith(t, twoPhasePlan)
+	if _, err := RecordPlanPhaseVerification(s, project, id, "phase-1", shaOne,
+		[]VerificationRun{{Command: []string{"go", "build", "./..."}, ExitCode: 0}}); err != nil {
+		t.Fatal(err)
+	}
+	task, _ := s.Task(id)
+	rec, _ := task.PlanPhase("phase-1")
+	if rec.Stale(shaOne) {
+		t.Fatal("a verification at the current head reported stale")
+	}
+	if !rec.Stale(shaTwo) {
+		t.Fatal("a verification at an older commit did not report stale")
+	}
+}
+
+// The commands come from the accepted plan. A request cannot substitute one.
+func TestReportedResultsMustMatchThePlansCommands(t *testing.T) {
+	s, project, id := planWith(t, twoPhasePlan)
+	_, err := RecordPlanPhaseVerification(s, project, id, "phase-1", shaOne,
+		[]VerificationRun{{Command: []string{"echo", "ok"}, ExitCode: 0}})
+	if !errors.Is(err, ErrPlanPhase) {
+		t.Fatalf("a substituted command was accepted: %v", err)
+	}
+}
+
+// A command outside project policy is refused before anything runs, and the
+// refusal names the project so the planner learns its real reach.
+func TestPolicyRefusalHappensBeforeExecution(t *testing.T) {
+	s, project, id := planWith(t, twoPhasePlan)
+	project.Verification.Allowed = [][]string{{"go", "build", "./..."}}
+	_, err := PlanPhaseCommands(s, project, id, "phase-2")
+	if !errors.Is(err, ErrPlanPhase) {
+		t.Fatalf("an unauthorised command was resolved: %v", err)
+	}
+	if !strings.Contains(err.Error(), "demo") || !strings.Contains(err.Error(), "go test") {
+		t.Fatalf("the refusal does not name the project and the command: %v", err)
+	}
+	task, _ := s.Task(id)
+	if _, ok := task.PlanPhase("phase-2"); ok {
+		t.Fatal("a refused phase produced a record")
+	}
+}
+
+// A plan sealed before plan.md declares no executable unit, and saying so
+// beats inventing a phase it never had.
+func TestLegacyPlanIsExplicitlyNonProgressable(t *testing.T) {
+	s, id := phaseStore(t)
+	project := planProject()
+	if _, err := AdvanceWorkPhase(s, project, id, nil); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := AdvanceWorkPhase(s, project, id, sealed(t, research)); err != nil {
+		t.Fatal(err)
+	}
+	// A pre-markdown plan, appended straight to the CAS the way an old ref
+	// would already be there.
+	ref, err := s.PutArtifact([]byte(`{"changes":[{"target":"a.go","intent":"do a thing"}]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	task, _ := s.Task(id)
+	task.PlanRef = ref
+	_, err = PlanPhaseCommands(s, project, id, "phase-1")
+	if err == nil {
+		t.Fatal("a legacy plan resolved a phase")
+	}
+}
+
+// signOff records a human decision bound to one phase of one plan, which is
+// the only thing that satisfies a manual verification gate.
+func signOff(t *testing.T, s *store.Store, taskID, subject string) {
+	t.Helper()
+	task, _ := s.Task(taskID)
+	if err := s.Append(domain.Event{
+		ID: domain.NewID(), Type: domain.EventHumanDecisionRecorded, TaskID: taskID,
+		Version: task.Version + 1, Surface: string(authz.System),
+		Payload: mustJSONBytes(t, map[string]any{
+			"decision_id": domain.NewID(), "kind": "answer", "subject": subject,
+			"value":  "manual steps confirmed",
+			"source": map[string]any{"provider": "gitea", "external_id": "signoff-" + subject},
+		}),
+	}); err != nil {
+		t.Fatalf("sign off: %v", err)
+	}
+}

internal/registry/registry.go

@@ -50,6 +50,9 @@ type Project struct {
 	HumanDecisions struct {
 		MaxRequestsPerTask int `json:"max_requests_per_task,omitempty"`
 	} `json:"human_decisions,omitempty"`
+	// Verification bounds what a plan's automated checks may execute. Absent
+	// policy refuses every plan command; see VerificationPolicy.
+	Verification VerificationPolicy `json:"verification,omitempty"`
 }
 
 // MaxDecisionRequests is the per-task question budget.

internal/registry/verification.go

@@ -0,0 +1,84 @@
+package registry
+
+import (
+	"fmt"
+	"strings"
+)
+
+// VerificationPolicy is what a plan's automated checks may execute in this
+// project. It exists because a plan command is agent-authored, while the
+// quality gate is operator-authored: the two must not share an execution
+// envelope just because they run in the same worktree.
+//
+// Absence is a refusal, never a default-allow. A project that declares no
+// policy runs no plan command, and the planner is told so at seal time.
+type VerificationPolicy struct {
+	// Allowed is a list of argv patterns. A command runs only if some pattern
+	// matches it positionally.
+	Allowed [][]string `json:"allowed,omitempty"`
+}
+
+// Allows reports whether argv matches any pattern, and names the reason when
+// it does not. The reason reaches the planner, so "not allowed" alone would
+// send it guessing at the project's real reach.
+func (p VerificationPolicy) Allows(argv []string) (bool, string) {
+	if len(argv) == 0 {
+		return false, "the command is empty"
+	}
+	if len(p.Allowed) == 0 {
+		return false, "this project declares no verification policy, so no plan command may run"
+	}
+	for _, pattern := range p.Allowed {
+		if matchArgv(pattern, argv) {
+			return true, ""
+		}
+	}
+	return false, fmt.Sprintf("%q is not in this project's verification policy, which allows: %s", strings.Join(argv, " "), p.describe())
+}
+
+func (p VerificationPolicy) describe() string {
+	out := make([]string, 0, len(p.Allowed))
+	for _, pattern := range p.Allowed {
+		out = append(out, strings.Join(pattern, " "))
+	}
+	return strings.Join(out, "; ")
+}
+
+// matchArgv matches positionally, never by prefix.
+//
+//   - a literal element matches that element exactly
+//   - "*" matches exactly one element, any value
+//   - an element ending in "/..." matches a path argument under that prefix,
+//     so ./internal/... covers ./internal/store/... but never ./internalsecrets
+//   - "*" as the last pattern element matches every remaining element, and is
+//     the only way a pattern covers a longer command. An operator writes that
+//     deliberately for a runner that takes free-form arguments.
+//
+// A shorter pattern otherwise fails, so ["go", "test"] never authorises
+// ["go", "test", "-exec", "curl"].
+func matchArgv(pattern, argv []string) bool {
+	if len(pattern) == 0 {
+		return false
+	}
+	for i, want := range pattern {
+		if want == "*" && i == len(pattern)-1 && len(argv) >= len(pattern) {
+			// Trailing wildcard: everything from here on is covered.
+			return true
+		}
+		if i >= len(argv) {
+			return false
+		}
+		got := argv[i]
+		switch {
+		case want == "*":
+			// One element, any value. An empty argument is still an argument.
+		case strings.HasSuffix(want, "/..."):
+			if !strings.HasPrefix(got, strings.TrimSuffix(want, "...")) && got != strings.TrimSuffix(want, "/...") {
+				return false
+			}
+		case want != got:
+			return false
+		}
+	}
+	return len(pattern) == len(argv)
+}

internal/registry/verification_test.go

@@ -0,0 +1,85 @@
+package registry
+
+import "testing"
+
+func TestVerificationPolicyMatchesPositionally(t *testing.T) {
+	p := VerificationPolicy{Allowed: [][]string{
+		{"go", "test", "./..."},
+		{"go", "test", "./internal/..."},
+		{"go", "vet", "./..."},
+		{"npm", "test", "--", "*"},
+		{"make", "*"},
+	}}
+	allowed := [][]string{
+		{"go", "test", "./..."},
+		{"go", "test", "./internal/store/..."},
+		{"go", "vet", "./..."},
+		{"npm", "test", "--", "unit"},
+		// A trailing "*" covers the remaining elements, which is the only way
+		// a pattern authorises a longer command. The operator writes that
+		// deliberately when a runner takes free-form arguments.
+		{"npm", "test", "--", "unit", "extra"},
+		{"make", "check"},
+		{"make", "check", "verbose"},
+		// Narrower than an allowed pattern: ./other/... is a subset of ./...
+		{"go", "test", "./other/..."},
+	}
+	for _, argv := range allowed {
+		if ok, why := p.Allows(argv); !ok {
+			t.Errorf("%v refused: %s", argv, why)
+		}
+	}
+	refused := [][]string{
+		// A shorter pattern must not authorise a longer command, or
+		// ["go","test"] would cover ["go","test","-exec","curl"].
+		{"go", "test", "./...", "-exec", "curl"},
+		{"go", "test"},
+		{"go", "build", "./..."},
+		{"curl", "https://example.com"},
+		{},
+	}
+	for _, argv := range refused {
+		if ok, _ := p.Allows(argv); ok {
+			t.Errorf("%v allowed, want a refusal", argv)
+		}
+	}
+}
+
+// Absence is a refusal. A project that declares no policy must not inherit the
+// quality gate's operator-authored envelope, because a plan command is written
+// by an agent.
+func TestAbsentVerificationPolicyRefusesEverything(t *testing.T) {
+	var p VerificationPolicy
+	ok, why := p.Allows([]string{"go", "test", "./..."})
+	if ok {
+		t.Fatal("an empty policy allowed a command")
+	}
+	if why == "" {
+		t.Fatal("a refusal with no reason sends the planner guessing")
+	}
+}
+
+// The path prefix is a prefix of the path, not of the argument text. Tested
+// against a policy that does not also allow ./..., which would cover
+// everything and hide the distinction.
+func TestPathPrefixDoesNotMatchASiblingWithTheSameLetters(t *testing.T) {
+	p := VerificationPolicy{Allowed: [][]string{{"go", "test", "./internal/..."}}}
+	for _, argv := range [][]string{
+		{"go", "test", "./internalsecrets"},
+		{"go", "test", "./internal-tools/..."},
+		{"go", "test", "./..."},
+	} {
+		if ok, _ := p.Allows(argv); ok {
+			t.Errorf("%v allowed, want a refusal", argv)
+		}
+	}
+	for _, argv := range [][]string{
+		{"go", "test", "./internal/..."},
+		{"go", "test", "./internal/store/..."},
+		{"go", "test", "./internal"},
+	} {
+		if ok, why := p.Allows(argv); !ok {
+			t.Errorf("%v refused: %s", argv, why)
+		}
+	}
+}

internal/store/store.go

@@ -253,6 +253,7 @@ func (s *Store) apply(e domain.Event) error {
 		// folded into the contract projection.
 		var p struct {
 			DecisionID string                     `json:"decision_id"`
+			Subject    string                     `json:"subject"`
 			Source     domain.HumanDecisionSource `json:"source"`
 		}
 		if err := json.Unmarshal(e.Payload, &p); err != nil {
@@ -261,6 +262,21 @@ func (s *Store) apply(e domain.Event) error {
 		if p.Source.ExternalID != "" {
 			s.decisionSource[p.Source.Provider+"\x00"+p.Source.ExternalID] = p.DecisionID
 		}
+		// A manual sign-off is the one decision that moves plan progress. The
+		// subject carries the plan ref and the phase id, so an approval
+		// applies to exactly the gate it named and to no other.
+		if t.PlanProgress != nil {
+			for i, rec := range t.PlanProgress.Phases {
+				if rec.Status != domain.PlanPhaseAwaitingManual {
+					continue
+				}
+				if p.Subject == domain.PlanPhaseSubject(rec.PlanRef, rec.PhaseID) {
+					t.PlanProgress.Phases[i].Status = domain.PlanPhaseVerified
+					t.Version = e.Version
+					s.replaceTask(e.TaskID, t)
+				}
+			}
+		}
 	}
 	if e.Type == "StandupAdvisory" || e.Type == "ApprovalGranted" || e.Type == "ApprovalDenied" {
 		return nil
@@ -282,8 +298,13 @@ func (s *Store) apply(e domain.Event) error {
 				t.ResearchRef = p.ArtifactRef
 			}
 		case domain.WorkPhasePlan:
-			if p.ArtifactRef != "" {
+			if p.ArtifactRef != "" && p.ArtifactRef != t.PlanRef {
+				// A new plan supersedes the old one, and the progress earned
+				// against the old one with it. PlanPhases would filter these
+				// out anyway; clearing here means a superseded record is not
+				// carried around waiting for a reader that forgets to.
 				t.PlanRef = p.ArtifactRef
+				t.PlanProgress = nil
 			}
 		}
 		t.WorkPhase = p.Phase
@@ -449,6 +470,31 @@ func (s *Store) apply(e domain.Event) error {
 		t.Version = e.Version
 		s.replaceTask(e.TaskID, t)
 		return nil
+	case domain.EventPlanPhaseVerified:
+		var pp domain.PlanPhaseRecord
+		if err := json.Unmarshal(e.Payload, &pp); err != nil {
+			return err
+		}
+		// Records are kept per plan. A record naming a plan the task no longer
+		// accepts is projected onto nothing: it stays in the log as
+		// provenance, and PlanPhases refuses to count it.
+		if t.PlanProgress == nil || t.PlanProgress.PlanRef != pp.PlanRef {
+			t.PlanProgress = &domain.PlanProgress{PlanRef: pp.PlanRef}
+		}
+		replaced := false
+		for i, existing := range t.PlanProgress.Phases {
+			if existing.PhaseID == pp.PhaseID {
+				t.PlanProgress.Phases[i] = pp
+				replaced = true
+				break
+			}
+		}
+		if !replaced {
+			t.PlanProgress.Phases = append(t.PlanProgress.Phases, pp)
+		}
+		t.Version = e.Version
+		s.replaceTask(e.TaskID, t)
+		return nil
 	case domain.EventReviewRecorded:
 		var rp struct {
 			ArtifactRef string `json:"artifact_ref"`
@@ -827,7 +873,7 @@ func (s *Store) validateTransition(e domain.Event, t domain.Task, exists bool, p
 		return nil
 	}
 	switch e.Type {
-	case "TaskLeaseRenewed", "TaskLaunchAcknowledged", "TaskReleased", "TaskPickupValidated", "TaskCompleted", "TaskBlocked", "TaskNeedsAttention", "TaskFailed", domain.EventTaskSubmitted:
+	case "TaskLeaseRenewed", "TaskLaunchAcknowledged", "TaskReleased", "TaskPickupValidated", "TaskCompleted", "TaskBlocked", "TaskNeedsAttention", "TaskFailed", domain.EventTaskSubmitted, domain.EventPlanPhaseVerified:
 		owner, _ := p["harness_id"].(string)
 		epoch, _ := p["lease_epoch"].(string)
 		// Expiry is the one coordinator-owned relinquish path. It still binds