Clarify prepared notification timing and context

docs/roadmap/remediation.md

@@ -7,7 +7,7 @@ testing, documentation, and agent policies.
 
 ## 1. Complete The Public Prepared-Notification Contract
 
-Priority: P3. Status: open. Owning stage: Stage 8.
+Priority: P3. Status: complete. Owning stage: Stage 8.
 
 Location: [RunRequest.OnPrepared GoDoc](../../types.go#L97).
 
@@ -37,6 +37,12 @@ for every failed request, forced callback interruption, or terminal observation
 after panic. This is a documentation completion, not a runtime change. Existing
 behavioral tests already cover these semantics; duplicate tests are unnecessary.
 
+Completion: expanded the field's GoDoc to state invocation cardinality,
+non-repetition during retry/repair, and operation-context scope, including the
+distinction from the coordinator's next-turn callback context. Runtime behavior
+is unchanged. GoDoc rendering and the existing focused race-enabled notification,
+retry/repair, and coordinated-budget tests passed.
+
 ## Stage Review Summary
 
 | Stage | Result |
@@ -48,7 +54,7 @@ behavioral tests already cover these semantics; duplicate tests are unnecessary.
 | 5 — Phase budgets | Tests cover preparation, capacity waiting, retry backoff, generation/repair, validation, notification time, and stable terminal outcomes. |
 | 6 — Ownership and failures | Public tests cover detached messages, cache metadata, nested parameters, schema, credentials, frozen sources, retained diagnostics, and panic cleanup. |
 | 7 — Coordination | Fresh turn budgets, parent-context assessment, released capacity, sibling use, observer composition, and explicit grouping are covered. |
-| 8 — Documentation and example | Maintained example and consumer/internal documentation reflect the feature; complete the canonical GoDoc as described in finding 1. |
+| 8 — Documentation and example | Maintained example, consumer/internal documentation, and the completed canonical GoDoc reflect the feature; finding 1 is resolved. |
 
 No runtime correctness defect, additional architectural gap, or inadvertently
 strengthened caller restriction or guarantee was identified in this review.

types.go

@@ -95,13 +95,18 @@ type RunRequest struct {
 	// collaborators that ignore context cannot be forcibly interrupted.
 	OperationTimeout time.Duration `json:"-" yaml:"-"`
 	// OnPrepared synchronously receives detached, credential-redacted details of
-	// the logical request after preparation and admission, before generation,
-	// if execution reaches that point. Admission remains held, and callback time
-	// consumes OperationTimeout. The callback owns the delivered mutable values;
-	// its closure is shared and must synchronize any shared state. It has no
-	// error return, and a panic propagates after resource cleanup. Prepare and
-	// ValidateRequest do not invoke it; PrepareExecution retains the selected
-	// function for RunPrepared and Discard releases it.
+	// the logical request after preparation and admission, before the first
+	// generation, at most once per logical execution if it reaches that point.
+	// Transient retries and structural repair do not repeat the notification.
+	// Its context is the operation-scoped context, subject to OperationTimeout
+	// and parent cancellation/deadlines. In [Engine.Coordinate], this differs
+	// from the parent context passed to the next-turn callback.
+	// Admission remains held, and callback time consumes OperationTimeout. The
+	// callback owns the delivered mutable values; its closure is shared and must
+	// synchronize any shared state. It has no error return, and a panic propagates
+	// after resource cleanup. Prepare and ValidateRequest do not invoke it;
+	// PrepareExecution retains the selected function for RunPrepared and Discard
+	// releases it.
 	OnPrepared func(context.Context, PreparedRun) `json:"-" yaml:"-"`
 	// CaptureExchange requests an immutable snapshot of a completed run, even
 	// when its structural validation fails. Operational errors return no result.