feat(boatstack): delivery.terminal — the standing goal becomes a typed setpoint (#239)

* feat(boatstack): flow watch — bounded observe-compare loop over the frontier

New `flow watch` verb: re-observe the read-only frontier on an interval and
exit on the first row-signature change (position, actor, lifecycle, failing
checks), immediately when nothing can move, or at the deadline with a
distinct exit code (1) so callers can tell change from timeout. Time flows
through injectable seams so the loop is provable without real waiting; a
failing gh observation degrades rows to Unknown and the loop stays bounded.

The watch observes and exits — it never executes a transition and never
writes, pinned across ticks including a terminal MERGED observation. SKILL.md
and workflow.md document composing watch with the loop (watch exits →
next-status → continue).

control-law: watch-observes-and-exits-never-acts

Disclosure-Reviewed: reviewed — public-safe only, private facet kept out of this commit

* feat(boatstack): delivery.terminal — the standing goal becomes a typed setpoint

New optional config block delivery.terminal: "published" (default, byte-
identical behavior pinned by conformance) or "merged" (the flow's advisors
keep reporting the standing goal past publish). Resolution is state-then-
config-then-default: activation snapshots the non-default goal onto
DeliveryState.Goal (additive omitempty, no schema bump, preserved across
plan amendments), so a mid-flight config change never changes an in-progress
delivery's goal and a fresh session hydrates the goal from the repository
instead of the operator restating it.

FlowNext gains a Terminal field; only the widened goal earns a rendered
line. The oracle's Goal stays StatePublished — the delivery machine models
no transition past publish; Terminal is the operator-facing setpoint layer.
Every invalid or unreadable input resolves to the narrower published goal.

control-law: terminal-goal-defaults-to-published-and-hydrates-from-state-then-config

Disclosure-Reviewed: reviewed — public-safe only, private facet kept out of this commit

* fix(boatstack): normalize JSON-escaped Windows paths in the terminal golden test

The byte-identical default-vs-published comparison blanks the per-fixture
temp repo path out of both captures; on Windows the JSON capture carries the
path with escaped backslashes, so the raw-path replacement missed it and the
two fixtures diverged on their temp paths alone. Blank both the raw and the
JSON-escaped forms.

Disclosure-Reviewed: reviewed — public-safe only, private facet kept out of this commit

Author: bigboateng

labs/12-product-engineering-loop/boatstack-distribution/CONFIGURATION.md

@@ -15,6 +15,7 @@ boatstack-user-config-field:workflow.visual_evidence_publish.mode
 boatstack-user-config-field:workflow.visual_evidence_publish.host
 boatstack-user-config-field:workflow.visual_evidence_publish.expiry
 boatstack-user-config-field:workflow.ignored_deliveries
+boatstack-user-config-field:delivery.terminal
 boatstack-user-config-field:workspace.enabled
 boatstack-user-config-field:workspace.mode
 boatstack-user-config-field:workspace.cleanup
@@ -41,6 +42,7 @@ Boatstack's installer owns the complete `.boatstack-project.json` shape. Edit on
 | Add frontend PR screenshots | `workflow.pr_visual_evidence` | `suggest` exposes missing screenshots as a gap; `require` blocks completed publication. |
 | Render screenshots inline on a private PR | `workflow.visual_evidence_publish.*` | `mode: external-host` uploads the captured PNGs to an anonymous expiring host so the comment renders inline even on a private repo; opt-in, never automatic. |
 | Ignore old ambiguous deliveries | `workflow.ignored_deliveries` | Listed feature slugs are excluded from delivery-ambiguity resolution so past work stops blocking new work; new, unlisted ambiguous deliveries still pause. |
+| Pursue the PR to merge, not just to open | `delivery.terminal` | `merged` keeps the read-only flow advisors naming post-publish steps (watch checks, route corrections) until the PR is observed merged; the default `published` ends the flow when the PR is open, exactly as before. |
 | Use fresh feature workspaces | `workspace.*` | Boatstack creates and cleans branches or linked worktrees under the selected policy. |
 | Limit generated host surfaces | `adapters` | Export generates only the selected supported adapters. |
 
@@ -143,6 +145,18 @@ List feature slugs here to drop past deliveries from the ambiguity check so hist
 
 Workspace `mode` is `worktree` or `branch`; cleanup is `confirm`, `auto`, or `off`; and cleanup eligibility begins after `merge` or `ship`. `reap` is `confirm`, `auto`, or `off`: when a delivery's PR is confirmed merged, Boatstack sweeps every terminal (merged or abandoned) Boatstack workspace at once — `confirm` asks the operator once before reclaiming them, `auto` reclaims without asking, and `off` disables the sweep. Supported adapters are `cursor`, `claude`, `codex`, `gemini`, and `github`. Empty or omitted adapters enable all supported surfaces.
 
+## Delivery goal
+
+```json
+{
+  "delivery": {
+    "terminal": "merged"
+  }
+}
+```
+
+`delivery.terminal` names the state a delivery pursues before the flow reports nothing left to do. The default `published` ends the flow when the slice's pull request is open, exactly as before. `merged` keeps the read-only flow advisors (`next-status`, `flow next`, `flow frontier`, `flow watch`) naming post-publish steps — watch the checks, route a correction, surface merge eligibility — until the pull request is observed merged. The goal a delivery starts under is snapshotted with the delivery, so changing this value never changes an in-progress delivery's goal. Boatstack itself never merges a pull request under any setting.
+
 ## Installer-owned fields
 
 The installer maintains `schema_version`, `project.name`, and integration records. Select gstack or Spec Kit through installation and update flows. Their `requested`, `status`, `version`, and `detail` values are receipts and provenance, not hand-edited workflow switches.

labs/12-product-engineering-loop/boatstack-distribution/release-notes/2026-07-28-configurable-delivery-terminal.md

@@ -0,0 +1,5 @@
+### You can now tell Boatstack the goal is a merged PR, not just an open one
+
+A new `delivery.terminal` setting names the state a delivery pursues before the flow reports nothing left to do. The default, `published`, keeps today's behavior exactly: the flow ends when your pull request is open. Setting `merged` tells the read-only flow advisors to keep reporting the standing goal until the pull request is observed merged; the prescribed post-publish steps arrive in the next update.
+
+The goal a delivery starts under is saved with that delivery, so changing the setting mid-flight never silently changes an in-progress delivery's goal, and a fresh session hydrates the goal from your repository instead of you restating it. Invalid or unreadable values always resolve to the narrower `published` goal, and Boatstack itself never merges a pull request under any setting.

labs/12-product-engineering-loop/product-engineering-loop/config_documentation_test.go

@@ -113,6 +113,7 @@ func TestSerializedConfigurationSurfaceIsDocumentedInternally(t *testing.T) {
 func TestPublicConfigurationGuideContainsOnlySupportedUserControls(t *testing.T) {
 	want := []string{
 		"adapters",
+		"delivery.terminal",
 		"project.commands",
 		"project.context",
 		"project.default_branch",

labs/12-product-engineering-loop/product-engineering-loop/delivery.go

@@ -66,6 +66,13 @@ type DeliveryState struct {
 	RepairAttempt       int             `json:"repair_attempt,omitempty"`
 	SupersededReceipts  []string        `json:"superseded_receipts,omitempty"`
 	ParentDelivery      string          `json:"parent_delivery,omitempty"`
+	// Goal snapshots the non-default delivery terminal ("merged") this
+	// delivery was activated under, so a mid-flight config change never
+	// silently changes an in-progress delivery's goal. Empty means: resolve
+	// from config at read time (and keeps a default-config state file
+	// byte-identical to the pre-field format).
+	// control-law: terminal-goal-defaults-to-published-and-hydrates-from-state-then-config
+	Goal string `json:"goal,omitempty"`
 }
 
 type DeliveryGateReceipt struct {
@@ -377,6 +384,7 @@ func initializeDeliveryState(repo, feature, planPath, lockPath string) error {
 		SchemaVersion: deliveryStateSchemaVersion, Feature: feature, PlanLockHash: lockHash,
 		ActiveIndex: 0, Slices: slices, Mode: "NORMAL",
 		ParentDelivery: strings.TrimSpace(stringValue(plan["parent_delivery"])),
+		Goal:           deliveryGoalSnapshot(repo),
 	})
 }
 
@@ -485,6 +493,7 @@ func reconcileAmendedDeliveryState(existing DeliveryState, newSlices []DeliveryS
 		Slices:            merged,
 		Mode:              "NORMAL",
 		ParentDelivery:    existing.ParentDelivery,
+		Goal:              existing.Goal,
 	}
 }
 

labs/12-product-engineering-loop/product-engineering-loop/delivery_terminal.go

@@ -0,0 +1,71 @@
+package boatstack
+
+import "strings"
+
+// The delivery terminal is the standing goal of the flow — the state past
+// which nothing more is owed. It resolves in a fixed order: the goal the
+// delivery was ACTIVATED under (state.Goal — hysteresis, so a mid-flight
+// config change never silently changes an in-progress delivery's goal), then
+// the repository config (delivery.terminal), then the published default.
+// Every unreadable or invalid input resolves to the narrower published goal:
+// a goal is widened only by an explicit, verifiable operator choice.
+// control-law: terminal-goal-defaults-to-published-and-hydrates-from-state-then-config
+type DeliveryTerminal string
+
+const (
+	// TerminalPublished — the flow is done when the slice's PR is open.
+	TerminalPublished DeliveryTerminal = "published"
+	// TerminalMerged — the flow keeps naming read-only post-publish steps
+	// until the PR is observed merged.
+	TerminalMerged DeliveryTerminal = "merged"
+)
+
+func normalizeDeliveryTerminal(value string) (DeliveryTerminal, bool) {
+	switch strings.ToLower(strings.TrimSpace(value)) {
+	case string(TerminalPublished):
+		return TerminalPublished, true
+	case string(TerminalMerged):
+		return TerminalMerged, true
+	default:
+		return "", false
+	}
+}
+
+// configuredDeliveryTerminal reads the repository's standing terminal from
+// the project config. Absent, invalid, or unreadable configuration resolves
+// to published — never an error, because the terminal is consulted from
+// read-only paths that must not gain a new failure mode.
+func configuredDeliveryTerminal(repo string) DeliveryTerminal {
+	config, _, err := LoadConfig(WorkspaceFor(repo).ProjectConfigPath())
+	if err != nil || config.Delivery == nil {
+		return TerminalPublished
+	}
+	if terminal, ok := normalizeDeliveryTerminal(config.Delivery.Terminal); ok {
+		return terminal
+	}
+	return TerminalPublished
+}
+
+// resolveDeliveryTerminal resolves the terminal for one feature: the
+// activation snapshot first, then config, then the default.
+func resolveDeliveryTerminal(repo, feature string) DeliveryTerminal {
+	if strings.TrimSpace(feature) != "" {
+		if state, err := LoadDeliveryState(repo, feature); err == nil {
+			if terminal, ok := normalizeDeliveryTerminal(state.Goal); ok {
+				return terminal
+			}
+		}
+	}
+	return configuredDeliveryTerminal(repo)
+}
+
+// deliveryGoalSnapshot is what activation records on the new delivery state.
+// Only the non-default goal is snapshotted: a default-config delivery keeps
+// an empty Goal, so its persisted state is byte-identical to before this
+// field existed.
+func deliveryGoalSnapshot(repo string) string {
+	if configuredDeliveryTerminal(repo) == TerminalMerged {
+		return string(TerminalMerged)
+	}
+	return ""
+}

labs/12-product-engineering-loop/product-engineering-loop/delivery_terminal_conformance_test.go

@@ -0,0 +1,215 @@
+package boatstack
+
+// control-law: terminal-goal-defaults-to-published-and-hydrates-from-state-then-config
+//
+// The delivery terminal — the standing goal of the flow — resolves in a fixed
+// order: the goal the delivery was ACTIVATED under (state.Goal), then the
+// repository config (delivery.terminal), then the published default. The
+// default is a hard no-op: with no delivery block (or an explicit
+// "published"), every advisory output is identical to the pre-field
+// behavior, because a goal this standing is widened only by an explicit
+// operator choice, never by an upgrade. Invalid and unreadable inputs
+// resolve to the NARROWER published goal (fail-closed direction: the wider
+// goal implies more agent-owned steps).
+//
+// Test classes: positive (config merged → Terminal merged; activation
+// snapshots the non-default goal), relation (state.Goal overrides config both
+// ways — hysteresis), negative (invalid config value fails validation;
+// invalid state.Goal is ignored), bypass (default vs explicit published →
+// byte-identical rendering and JSON across the slice lifecycle), failure-state
+// (a pre-field state file without goal loads clean and resolves from config).
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func writeTerminalConfig(t *testing.T, repo, terminal string) {
+	t.Helper()
+	config := testConfig()
+	if terminal != "" {
+		config.Delivery = &DeliveryPolicy{Terminal: terminal}
+	}
+	value, err := MarshalJSON(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(repo, ".product-loop", "project.json"), value, 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// Positive: the configured terminal surfaces on the advisory, and only the
+// widened goal earns a rendered line.
+func TestConfiguredTerminalSurfacesOnAdvisory(t *testing.T) {
+	repo := nextTestRepo(t)
+	writeNextDelivery(t, repo, "feature", "BUILD", 0)
+	writeTerminalConfig(t, repo, "merged")
+
+	next, err := NextControl(repo, "feature")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if next.Terminal != TerminalMerged {
+		t.Fatalf("terminal = %q, want merged", next.Terminal)
+	}
+	if !strings.Contains(FormatFlowNext(next), "Terminal goal: merged") {
+		t.Fatal("widened goal must be visible in the rendering")
+	}
+}
+
+// Relation: the activation snapshot outranks config in BOTH directions — a
+// delivery keeps the goal it was started under when config flips mid-flight.
+func TestActivationSnapshotOverridesConfig(t *testing.T) {
+	repo := nextTestRepo(t)
+	writeNextDelivery(t, repo, "feature", "BUILD", 0)
+
+	// Delivery activated under merged; config later narrowed to published.
+	state, err := LoadDeliveryState(repo, "feature")
+	if err != nil {
+		t.Fatal(err)
+	}
+	state.Goal = string(TerminalMerged)
+	if err := saveDeliveryState(repo, state); err != nil {
+		t.Fatal(err)
+	}
+	writeTerminalConfig(t, repo, "published")
+	if got := resolveDeliveryTerminal(repo, "feature"); got != TerminalMerged {
+		t.Fatalf("mid-flight narrowing changed the goal: %q", got)
+	}
+
+	// Delivery activated under the default; config later widened to merged.
+	// The empty snapshot means "resolve from config", so the widening applies.
+	state.Goal = ""
+	if err := saveDeliveryState(repo, state); err != nil {
+		t.Fatal(err)
+	}
+	writeTerminalConfig(t, repo, "merged")
+	if got := resolveDeliveryTerminal(repo, "feature"); got != TerminalMerged {
+		t.Fatalf("config terminal not hydrated: %q", got)
+	}
+
+	// An invalid snapshot value is ignored, never trusted.
+	state.Goal = "deployed"
+	if err := saveDeliveryState(repo, state); err != nil {
+		t.Fatal(err)
+	}
+	writeTerminalConfig(t, repo, "")
+	if got := resolveDeliveryTerminal(repo, "feature"); got != TerminalPublished {
+		t.Fatalf("invalid snapshot must resolve to published: %q", got)
+	}
+}
+
+// Positive: first activation snapshots the non-default goal onto the new
+// delivery state; the default snapshots nothing (byte-stable state files).
+func TestActivationSnapshotsNonDefaultGoalOnly(t *testing.T) {
+	for _, test := range []struct {
+		terminal string
+		wantGoal string
+	}{
+		{"merged", "merged"},
+		{"published", ""},
+		{"", ""},
+	} {
+		repo := nextTestRepo(t)
+		writeTerminalConfig(t, repo, test.terminal)
+		if got := deliveryGoalSnapshot(repo); got != test.wantGoal {
+			t.Fatalf("terminal %q: snapshot = %q, want %q", test.terminal, got, test.wantGoal)
+		}
+	}
+}
+
+// Negative: an explicit invalid enum fails config validation fail-closed.
+func TestInvalidTerminalRejectedByValidation(t *testing.T) {
+	config := testConfig()
+	config.Delivery = &DeliveryPolicy{Terminal: "deployed"}
+	if err := ValidateConfig(config); err == nil || !strings.Contains(err.Error(), "delivery.terminal") {
+		t.Fatalf("invalid terminal accepted: %v", err)
+	}
+	config.Delivery = &DeliveryPolicy{}
+	if err := ValidateConfig(config); err != nil {
+		t.Fatalf("empty terminal must stay legal: %v", err)
+	}
+}
+
+// Bypass: the default is a hard no-op — for every slice-lifecycle stage, the
+// advisory under an absent delivery block is byte-identical (JSON and
+// rendering) to an explicit published terminal, and carries no merged
+// wording anywhere.
+func TestDefaultTerminalIsByteIdenticalToExplicitPublished(t *testing.T) {
+	for _, stage := range []string{"BUILD", "TEST_PASSED", "REVIEW_PASSED", "PUBLISHED"} {
+		capture := func(terminal string) (string, string) {
+			repo := nextTestRepo(t)
+			activeIndex := 0
+			if stage == "PUBLISHED" {
+				activeIndex = 1
+			}
+			writeNextDelivery(t, repo, "feature", stage, activeIndex)
+			writeTerminalConfig(t, repo, terminal)
+			if stage == "PUBLISHED" {
+				updateRecoveryDelivery(t, repo, "feature", "feat/phase", "https://example.invalid/pr/9", "")
+				withRecoveryGh(t, phaseObservationPayload("OPEN", "", "CLEAN", rollupCheckRunPass))
+			}
+			next, err := NextControl(repo, "feature")
+			if err != nil {
+				t.Fatal(err)
+			}
+			// The repo path differs per fixture; blank it out of the compared
+			// values so only behavior is compared. JSON escapes Windows path
+			// separators, so the escaped form must be blanked too.
+			value, err := MarshalJSON(next)
+			if err != nil {
+				t.Fatal(err)
+			}
+			escaped, err := json.Marshal(repo)
+			if err != nil {
+				t.Fatal(err)
+			}
+			blank := func(s string) string {
+				s = strings.ReplaceAll(s, strings.Trim(string(escaped), `"`), "<repo>")
+				return strings.ReplaceAll(s, repo, "<repo>")
+			}
+			return blank(string(value)), blank(FormatFlowNext(next))
+		}
+		defaultJSON, defaultText := capture("")
+		publishedJSON, publishedText := capture("published")
+		if defaultJSON != publishedJSON {
+			t.Fatalf("stage %s: default and explicit published diverge:\n%s\n---\n%s", stage, defaultJSON, publishedJSON)
+		}
+		if defaultText != publishedText {
+			t.Fatalf("stage %s: rendering diverges:\n%s\n---\n%s", stage, defaultText, publishedText)
+		}
+		if strings.Contains(defaultText, "merged (delivery.terminal)") {
+			t.Fatalf("stage %s: default rendering mentions the widened goal:\n%s", stage, defaultText)
+		}
+	}
+}
+
+// Failure-state: a pre-field state file (no goal key) loads clean and
+// resolves from config — the migration law is untouched by the additive
+// field.
+func TestPreFieldStateResolvesFromConfig(t *testing.T) {
+	repo := nextTestRepo(t)
+	writeNextDelivery(t, repo, "feature", "BUILD", 0)
+	statePath, err := deliveryStatePath(repo, "feature")
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(raw), "\"goal\"") {
+		t.Fatal("fixture unexpectedly contains a goal key")
+	}
+	writeTerminalConfig(t, repo, "merged")
+	if got := resolveDeliveryTerminal(repo, "feature"); got != TerminalMerged {
+		t.Fatalf("pre-field state did not hydrate from config: %q", got)
+	}
+	if _, err := LoadDeliveryState(repo, "feature"); err != nil {
+		t.Fatalf("pre-field state failed to load: %v", err)
+	}
+}

labs/12-product-engineering-loop/product-engineering-loop/export.go

@@ -128,6 +128,9 @@ func ValidateConfig(config ProjectConfig) error {
 	if err := validateWorkspaceConfig(config.Workspace); err != nil {
 		return err
 	}
+	if err := validateDeliveryConfig(config.Delivery); err != nil {
+		return err
+	}
 	if policy := strings.TrimSpace(config.Workflow.PRVisualEvidence); policy != "" && policy != "off" && policy != "suggest" && policy != "require" {
 		return fmt.Errorf("workflow.pr_visual_evidence must be \"off\", \"suggest\", or \"require\"")
 	}
@@ -137,6 +140,18 @@ func ValidateConfig(config ProjectConfig) error {
 	return nil
 }
 
+// validateDeliveryConfig rejects only explicit invalid enum values. A nil
+// block or empty terminal resolves to the published default at use.
+func validateDeliveryConfig(delivery *DeliveryPolicy) error {
+	if delivery == nil {
+		return nil
+	}
+	if terminal := delivery.Terminal; terminal != "" && terminal != "published" && terminal != "merged" {
+		return fmt.Errorf("delivery.terminal must be \"published\" or \"merged\"")
+	}
+	return nil
+}
+
 // validateVisualEvidencePublish rejects only explicit invalid enum values. A nil
 // block or empty fields are legal and resolve to defaults at use, so configs written
 // before this block existed remain valid.