[rules] Refactor flow API: split Outcome into ReconcileOutcome and EnsureOutcome

Redesign the reconciliation flow API in controller .mdc rules:

- Split single `flow.Outcome` type into specialized types:
  - `flow.ReconcileOutcome` for Reconcile methods
  - `flow.EnsureOutcome` for ensure helpers (carries change/lock flags)
  - Plain `error` for create/delete/patch/step helpers

- Replace phase API:
  - `BeginPhase/EndPhase` → scoped constructors with `OnEnd` methods:
    - `BeginRootReconcile` (root Reconcile, no OnEnd)
    - `BeginReconcile` + `rf.OnEnd(&outcome)` (non-root Reconcile)
    - `BeginEnsure` + `ef.OnEnd(&outcome)` (ensure helpers)
    - `BeginStep` + `sf.OnEnd(&err)` (step helpers returning error)

- Update terminology throughout:
  - "phase" → "phase scope"
  - "Outcome" → "ReconcileOutcome" / "EnsureOutcome"

- Simplify helper return types:
  - Create/Delete/Patch helpers: MUST return `error`, NOT outcome
  - Compute helpers: MUST NOT return EnsureOutcome
  - Ensure helpers: MUST create ensure phase scope, accept ctx

- Restructure controller-reconciliation-flow.mdc for clarity

Signed-off-by: David Magton <[email protected]>

Author: dmgtn

.cursor/rules/controller-reconcile-helper-apply.mdc

@@ -167,11 +167,12 @@ func applyFoo(
 
 ---
 
-## Flow phases and **Outcome**
+## Flow phase scopes and outcomes
 
-- **ApplyReconcileHelpers** MUST NOT create a `reconcile/flow` **phase** (they do not accept `ctx context.Context`; see `controller-reconcile-helper.mdc`).
-- **ApplyReconcileHelpers** MUST NOT return **Outcome** (in code: `flow.Outcome`) (they are “in-memory write” steps).
-  - If a failure is possible, return `error` and let the calling function convert it into `flow.Fail(err)` (or equivalent **flow** handling).
+- **ApplyReconcileHelpers** MUST NOT create a `reconcile/flow` **phase scope** (they do not accept `ctx context.Context`; see `controller-reconcile-helper.mdc`).
+- **ApplyReconcileHelpers** MUST NOT return **ReconcileOutcome** (`flow.ReconcileOutcome`) or **EnsureOutcome** (`flow.EnsureOutcome`) (they are “in-memory write” steps).
+  - If a failure is possible, return `error` and let the caller convert it into a flow result in its own scope
+    (for example, `rf.Fail(err)` in a reconcile scope or `ef.Err(err)` in an ensure scope).
 
 ---
 
@@ -212,11 +213,12 @@ func applyFoo(obj *v1alpha1.Foo, target TargetFoo) {
 }
 ```
 
-❌ Returning `flow.Outcome` / doing flow control inside apply:
+❌ Returning a reconcile/ensure outcome / doing flow control inside apply:
 ```go
-func applyFoo(obj *v1alpha1.Foo, target TargetFoo) flow.Outcome {
+func applyFoo(obj *v1alpha1.Foo, target TargetFoo) flow.ReconcileOutcome {
+    var rf flow.ReconcileFlow
     obj.Spec = target.Spec
-    return flow.Continue() // forbidden: apply helpers do not return flow control
+    return rf.Continue() // forbidden: apply helpers do not return flow control
 }
 ```
 

.cursor/rules/controller-reconcile-helper-compute.mdc

@@ -23,8 +23,8 @@ Summary only; if anything differs, follow normative sections below.
 - They MAY use **ConstructionReconcileHelpers** (`new*`, `build*`, `make*`, `compose*`) for internal in-memory construction, as long as the compute helper’s purity/determinism/non-I/O contract remains satisfied.
 - They treat `obj` and all caller-provided inputs as **read-only inputs** and MUST NOT mutate them (including via **Aliasing** of maps/slices; **Clone** before modifying derived maps/slices).
 - They MUST NOT perform **Kubernetes API I/O**, call **DeepCopy**, execute patches, or make any **patch ordering** / **patch type decision** decisions.
-- If a **ComputeReconcileHelper** returns **Outcome** (in code: `flow.Outcome`), it MUST use it only for **flow control** (continue/done/requeue) and/or **errors**.
-- A **ComputeReconcileHelper** MUST NOT use **Outcome** change tracking (`ReportChanged`, `ReportChangedIf`) or **Optimistic-lock signaling** (`RequireOptimisticLock`).
+- A **ComputeReconcileHelper** MUST return computed values (and optionally `error`) and MUST NOT report object mutations or optimistic-lock intent.
+  In particular, a **ComputeReconcileHelper** MUST NOT return `flow.EnsureOutcome` and MUST NOT call `ReportChanged*` / `RequireOptimisticLock`.
 - If `computeTarget*` derives **target** values for **both** **patch domains** (**main patch domain** + **status patch domain**) that will later be used by **IsInSyncReconcileHelper** and/or **ApplyReconcileHelper**, it MUST return **two separate** values (**target main** + **target status**), not a mixed struct.
 - New code MUST NOT introduce `computeDesired*` helpers. Replace legacy “desired” helpers with **intended**/**target**/**report** helpers.
 - If a **ComputeReconcileHelper** depends on previous compute output, the dependency MUST be explicit in the signature as args **after `obj`**.
@@ -159,44 +159,36 @@ Or, for **report** computations when the helper needs data from `Reconciler`:
 func (r *Reconciler) computeFooReport(obj *v1alpha1.Foo, intendedFoo IntendedFoo, actualFoo ActualFoo, targetFoo TargetFoo) (FooReport, error)
 ```
 
-### Complex compute with flow control
-Prefer returning **Outcome** (in code, the type is `flow.Outcome`) and writing to `out`:
-```go
-func computeIntendedFoo(ctx context.Context, obj *v1alpha1.Foo, out *IntendedFoo) flow.Outcome
-```
-
-Or, if a compute helper needs data from `Reconciler`:
-```go
-func (r *Reconciler) computeIntendedFoo(ctx context.Context, obj *v1alpha1.Foo, out *IntendedFoo) flow.Outcome
-```
+### Complex compute with structured logging
 
-Or, for **actual** computations:
-```go
-func computeActualFoo(ctx context.Context, obj *v1alpha1.Foo, out *ActualFoo) flow.Outcome
-```
+When a compute helper is large and benefits from phase-scoped logging/panic logging, it SHOULD:
+- accept `ctx context.Context`,
+- compute into explicit `out` args,
+- return `error`,
+- and use a step scope (`flow.BeginStep`) for standardized `phase start/end` logs.
 
-Or, for **actual** computations when the helper needs data from `Reconciler`:
+Preferred signature:
 ```go
-func (r *Reconciler) computeActualFoo(ctx context.Context, obj *v1alpha1.Foo, out *ActualFoo) flow.Outcome
+func computeIntendedFoo(ctx context.Context, obj *v1alpha1.Foo, out *IntendedFoo) error
 ```
 
-Or, for **target** computations:
+Or, if a compute helper needs data from `Reconciler`:
 ```go
-func computeTargetFoo(ctx context.Context, obj *v1alpha1.Foo, intendedFoo IntendedFoo, actualFoo ActualFoo, out *TargetFoo) flow.Outcome
+func (r *Reconciler) computeIntendedFoo(ctx context.Context, obj *v1alpha1.Foo, out *IntendedFoo) error
 ```
 
 Or, for **target** computations that also emit a **report** in one pass:
 ```go
-func computeTargetFoo(ctx context.Context, obj *v1alpha1.Foo, intendedFoo IntendedFoo, actualFoo ActualFoo, outTarget *TargetFoo, outReport *FooReport) flow.Outcome
+func computeTargetFoo(
+    ctx context.Context,
+    obj *v1alpha1.Foo,
+    intendedFoo IntendedFoo,
+    actualFoo ActualFoo,
+    outTarget *TargetFoo,
+    outReport *FooReport,
+) error
 ```
 
-Or, for **report** computations:
-```go
-func computeFooReport(ctx context.Context, obj *v1alpha1.Foo, intendedFoo IntendedFoo, actualFoo ActualFoo, targetFoo TargetFoo, out *FooReport) flow.Outcome
-```
-
-> This keeps the call site clean and avoids `(flow.Outcome, DesiredFoo, error)` tuples.
-
 ### Dependent compute
 If a compute helper depends on previous compute output, the dependency MUST be explicit and come **after `obj`**:
 ```go
@@ -257,7 +249,7 @@ See the common determinism contract in `controller-reconcile-helper.mdc`.
 In particular, avoid producing “equivalent but different” outputs across runs (e.g., unstable ordering).
 - **ComputeReconcileHelpers** MAY use extracted computation/caching components owned by the reconciler (e.g. “world view” / “planner” / “topology scorer”, caches), as described in `controller-file-structure.mdc` (“Additional components”), as long as they do not violate the I/O boundaries above.
   - Note: cache population is a side effect and an additional source of state; therefore, the helper is deterministic only relative to that state. For the same explicit inputs and the same state of these components, the result MUST be the same.
-- If a **ComputeReconcileHelper** returns **Outcome** (in code: `flow.Outcome`), its **flow decision** and **error** MUST be stable for the same inputs and object state.
+- Errors (when returned) MUST be stable for the same inputs and object state (no nondeterministic branching / hidden I/O).
 
 > Practical reason: nondeterminism creates patch churn and flaky tests.
 
@@ -277,44 +269,42 @@ See the common read-only contract in `controller-reconcile-helper.mdc` (especial
 
 ---
 
-## Flow phases and **Outcome**
+## Phase scopes (optional)
 
-- A **ComputeReconcileHelper** MUST NOT create a `reconcile/flow` **phase** by default.
-- A **large** **ComputeReconcileHelper** MAY create a `reconcile/flow` **phase** (`flow.BeginPhase` / `flow.EndPhase`) **only when it improves structure or diagnostics**.
-  - Otherwise (small/straightforward compute), it MUST NOT create a **phase**.
-  - If it creates a **phase** (or writes logs), it MUST accept `ctx context.Context` (see `controller-reconcile-helper.mdc`).
-- If a **ComputeReconcileHelper** returns **Outcome** (in code: `flow.Outcome`), it MUST use helpers from `internal/reconciliation/flow`:
-  - `flow.Continue()`, `flow.Done()`, `flow.Fail(err)`, `flow.RequeueAfter(dur)`.
+- A **ComputeReconcileHelper** MUST NOT create a phase scope by default.
+- A **large** **ComputeReconcileHelper** MAY create a step phase scope (`flow.BeginStep` + deferred `sf.OnEnd(&err)`)
+  **only when it improves structure or diagnostics**.
+  - Otherwise (small/straightforward compute), it MUST NOT create a phase scope.
+  - If it creates a step phase scope (or writes logs), it MUST accept `ctx context.Context` (see `controller-reconcile-helper.mdc`).
+  - Step scope placement rules are defined in `controller-reconciliation-flow.mdc`.
 
-### **Outcome** change / optimistic-lock reporting
+### Change reporting and optimistic-lock signaling
 
-**ComputeReconcileHelpers** MUST NOT report object changes or optimistic-lock requirements via **Outcome** (in code: `flow.Outcome`):
+**ComputeReconcileHelpers** MUST NOT report object changes or optimistic-lock requirements:
+- MUST NOT return `flow.EnsureOutcome`
 - MUST NOT call `ReportChanged` / `ReportChangedIf`
 - MUST NOT call `RequireOptimisticLock`
 
-Rationale: `Outcome.DidChange()` / `Outcome.OptimisticLockRequired()` semantically mean
+Rationale: change reporting / optimistic-lock intent semantically mean
 “this helper already mutated the target object and the subsequent save of that mutation must use **Optimistic locking** semantics”.
 **ComputeReconcileHelpers** do not mutate `obj` by contract.
 
----
-
-### Returning results when using **Outcome**
-
-If a **ComputeReconcileHelper** returns **Outcome** (in code: `flow.Outcome`), it MAY write its computed result into an explicit output argument passed by pointer (e.g. `*DesiredState` / `*ActualState`) instead of returning that result as an additional return value.
-
-- It MUST NOT write the result into `obj`.
+### Step scope pattern (illustrative)
 
-Example pattern (illustrative):
 ```go
-func (r *Reconciler) computeIntendedX(ctx context.Context, obj *v1alpha1.X, out *IntendedX) flow.Outcome {
+func computeIntendedFoo(ctx context.Context, obj *v1alpha1.Foo, out *IntendedFoo) (err error) {
+    sf := flow.BeginStep(ctx, "compute-intended-foo")
+    defer sf.OnEnd(&err)
+    ctx = sf.Ctx()
+
     if out == nil {
-        return flow.Fail(fmt.Errorf("out is nil"))
+        return sf.Errf("out is nil")
     }
 
     // compute into *out (pure)
-    *out = IntendedX{ /* ... */ }
+    *out = IntendedFoo{ /* ... */ }
 
-    return flow.Continue()
+    return nil
 }
 ```
 
@@ -368,7 +358,6 @@ Notes (SHOULD):
 
 - See the common error handling rules in `controller-reconcile-helper.mdc`.
 - **ComputeReconcileHelpers** SHOULD generally return errors as-is.
-  - If a **ComputeReconcileHelper** returns **Outcome** (in code: `flow.Outcome`), use `flow.Fail(err)` for errors.
 
   **Allowed (rare)**: when propagating a **non-local** error (e.g., from parsing/validation libs or injected pure components) and additional context is necessary to **disambiguate multiple different error sources** within the same calling **Reconcile method**, a **ComputeReconcileHelper** MAY wrap with small, local context:
   - prefer `fmt.Errorf("<local-action>: %w", err)`
@@ -487,10 +476,14 @@ func computeActualFoo(obj *v1alpha1.Foo) ActualFoo {
 }
 ```
 
-❌ Using `flow.Outcome` change / optimistic-lock reporting in compute:
+❌ Using change reporting / optimistic-lock signaling in compute:
 ```go
-func computeTargetFoo(ctx context.Context, obj *v1alpha1.Foo, intendedFoo IntendedFoo, actualFoo ActualFoo, out *TargetFoo) flow.Outcome {
+func computeTargetFoo(ctx context.Context, obj *v1alpha1.Foo, intendedFoo IntendedFoo, actualFoo ActualFoo, out *TargetFoo) error {
     *out = TargetFoo{ /* ... */ }
-    return flow.Continue().ReportChanged().RequireOptimisticLock() // forbidden in compute
+
+    // forbidden: compute helpers do not mutate obj and must not signal persistence semantics
+    _ = flow.EnsureOutcome{}.ReportChanged() // (illustrative) forbidden category mixing
+
+    return nil
 }
 ```

.cursor/rules/controller-reconcile-helper-construction.mdc

@@ -26,8 +26,8 @@ Summary only; if anything differs, follow normative sections below.
   - Clone maps/slices before editing; avoid returning references that alias caller-owned storage unless explicitly documented and safe.
 - MUST NOT:
   - do Kubernetes API I/O, filesystem/network/env reads, or use time/random sources,
-  - log/print, accept `context.Context`, start `reconcile/flow` phases, or call `DeepCopy`,
-  - return `flow.Outcome` or make flow/patch orchestration decisions (patch ordering/strategy/execution).
+  - log/print, accept `context.Context`, start `reconcile/flow` phase scopes (`flow.BeginReconcile` / `flow.BeginEnsure` / `flow.BeginStep`), or call `DeepCopy`,
+  - return `flow.ReconcileOutcome` / `flow.EnsureOutcome` or make flow/patch orchestration decisions (patch ordering/strategy/execution).
 - MUST be plain functions (no `Reconciler` receiver) and may only call other **construction** helpers.
 - If the primary goal is a reconciliation pipeline artifact (**intended/actual/target/report**) or domain decision-making, prefer **ComputeReconcileHelper** (`compute*`) and use construction helpers only as sub-steps.
 
@@ -244,10 +244,10 @@ Important distinctions:
 
 ---
 
-## Flow phases and **Outcome**
+## Flow phase scopes and outcomes
 
-- **ConstructionReconcileHelpers** MUST NOT create a `reconcile/flow` **phase**.
-- **ConstructionReconcileHelpers** MUST NOT return **Outcome** (in code: `flow.Outcome`).
+- **ConstructionReconcileHelpers** MUST NOT create a `reconcile/flow` **phase scope** (`flow.BeginReconcile` / `flow.BeginEnsure` / `flow.BeginStep`).
+- **ConstructionReconcileHelpers** MUST NOT return **ReconcileOutcome** (`flow.ReconcileOutcome`) or **EnsureOutcome** (`flow.EnsureOutcome`).
 - **ConstructionReconcileHelpers** MUST NOT log (they do not accept `ctx context.Context`).
 
 ---
@@ -284,16 +284,18 @@ func newFoo(ctx context.Context, c client.Client, obj *v1alpha1.Foo) (FooOut, er
 func buildFoo(ctx context.Context, obj *v1alpha1.Foo) FooOut {
     l := log.FromContext(ctx)
     l.Info("building foo") // forbidden: no logging/phases in construction helpers
-    flow.BeginPhase(ctx, "buildFoo") // forbidden
+    rf := flow.BeginReconcile(ctx, "build-foo") // forbidden: no flow phase scopes in construction helpers
+    _ = rf
     return FooOut{}
 }
 ```
 
 ❌ Returning `flow.Outcome` / doing flow control:
 
 ```go
-func makeFoo(obj *v1alpha1.Foo) flow.Outcome {
-    return flow.Continue() // forbidden: construction helpers do not return Outcome
+func makeFoo(obj *v1alpha1.Foo) flow.ReconcileOutcome {
+    var rf flow.ReconcileFlow
+    return rf.Continue() // forbidden: construction helpers do not return reconcile outcomes
 }
 ```
 

.cursor/rules/controller-reconcile-helper-create.mdc

@@ -58,14 +58,6 @@ Typical create helpers are used for child resources to encapsulate the mechanica
 
 ### Simple create
 ```go
-func (r *Reconciler) createSKN(
-    ctx context.Context,
-    obj *v1alpha1.SomeKindName,
-) flow.Outcome
-```
-
-Or, if **Outcome** (in code, the type is `flow.Outcome`) is intentionally not used:
-```go
 func (r *Reconciler) createSKN(
     ctx context.Context,
     obj *v1alpha1.SomeKindName,
@@ -148,20 +140,18 @@ See the common read-only contract in `controller-reconcile-helper.mdc` (especial
 
 ---
 
-## Flow phases and **Outcome**
+## Flow phase scopes and outcomes
 
-- **CreateReconcileHelpers** MUST NOT create a `reconcile/flow` **phase** — they should stay mechanical and short.
-- If a **CreateReconcileHelper** returns **Outcome** (in code: `flow.Outcome`), it SHOULD use helpers from `internal/reconciliation/flow`:
-  - `flow.Continue()`, `flow.Done()`, `flow.Fail(err)`, `flow.RequeueAfter(dur)`.
-  - Prefer encoding retry/requeue policy explicitly in the returned **Outcome**.
+- **CreateReconcileHelpers** MUST NOT create a `reconcile/flow` **phase scope** — they should stay mechanical and short.
+- **CreateReconcileHelpers** MUST return `error` and MUST NOT return **ReconcileOutcome** (`flow.ReconcileOutcome`) or **EnsureOutcome** (`flow.EnsureOutcome`).
+  - Any retry/requeue policy belongs to the calling **Reconcile method** (use `ReconcileFlow` there).
 
 ---
 
 ## Error handling
 
 - See the common error handling rules in `controller-reconcile-helper.mdc`.
 - A **CreateReconcileHelper** SHOULD be mechanically thin: if the single `Create(...)` call fails, return the error **without wrapping**.
-  - If returning **Outcome** (in code: `flow.Outcome`), use `flow.Fail(err)` (or equivalent) with the original `err`.
 - A **CreateReconcileHelper** MUST NOT enrich errors with additional context (including **object identity** such as `namespace/name`, UID, object key).
   - Error enrichment (action + **object identity** + **phase**) is the calling **Reconcile method**’s responsibility.
 
@@ -171,18 +161,18 @@ See the common read-only contract in `controller-reconcile-helper.mdc` (especial
 
 ❌ Doing existence checks (`Get/List`) or any extra Kubernetes API calls:
 ```go
-func (r *Reconciler) createEON(ctx context.Context, obj *v1alpha1.EON) flow.Outcome {
+func (r *Reconciler) createEON(ctx context.Context, obj *v1alpha1.EON) error {
     // forbidden: extra API call
     var existing v1alpha1.EON
     if err := r.client.Get(ctx, client.ObjectKeyFromObject(obj), &existing); err == nil {
-        return flow.Continue() // "already exists" decision belongs to Reconcile methods
+        return nil // "already exists" decision belongs to Reconcile methods
     }
 
     // forbidden: second API call in the same helper if create proceeds
     if err := r.client.Create(ctx, obj); err != nil {
-        return flow.Fail(err)
+        return err
     }
-    return flow.Continue()
+    return nil
 }
 ```