Record the execution controls review finding

docs/roadmap/remediation.md

@@ -0,0 +1,66 @@
+# Execution Controls Review
+
+Reviewed implementation stages 1–8 against commit `57b62d3`, the
+[implementation plan](implementation.md), the accepted
+[feature roadmap](execution-controls.md), and the applicable architecture,
+testing, documentation, and agent policies.
+
+## 1. Complete The Public Prepared-Notification Contract
+
+Priority: P3. Status: open. Owning stage: Stage 8.
+
+Location: [RunRequest.OnPrepared GoDoc](../../types.go#L97).
+
+The public GoDoc describes synchronous delivery, detached ownership, held
+admission, and split preparation, but omits two explicitly selected lifecycle
+facts:
+
+- Notification occurs at most once per logical execution, when execution
+  reaches that point before the first generation. Transient retries and
+  structural repair do not repeat it.
+- The callback receives the operation context, including the selected operation
+  deadline when enabled and inherited parent cancellation. In coordination this
+  is distinct from the parent context delivered to the next-turn callback.
+
+These facts are already implemented by the
+[shared execution boundary](../../internal/usecase/runner.go#L186) and covered
+by the notification, retry/repair, and coordinator contract tests. They are also
+expressly selected in the roadmap's
+[accepted callback decision](execution-controls.md#3-what-is-the-prepared-details-callback-contract).
+However, Go declarations and GoDoc own the exact public API contract; consumers
+should not need a temporary roadmap or implementation inspection to discover
+invocation cardinality or the scope of their callback's context.
+
+Required remediation: add these two facts to the field's GoDoc. Preserve
+conditional delivery and cooperative cancellation; do not promise notification
+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.
+
+## Stage Review Summary
+
+| Stage | Result |
+| --- | --- |
+| 1 — API and conversion | Selected fields and sentinel are present; callback conversion captures the chosen function and detaches details only when selected. |
+| 2 — Ordinary timeout | One internal scope covers ordinary execution; per-invocation cause attribution and public error projection precede terminal observation. |
+| 3 — Split preparation | Handles retain duration and callback without an idle timer; claim/discard and cleanup behavior are preserved. |
+| 4 — Prepared notification | Both execution paths use the actual shared snapshot, with context checks and held admission; retries and repair do not notify again. |
+| 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. |
+
+No runtime correctness defect, additional architectural gap, or inadvertently
+strengthened caller restriction or guarantee was identified in this review.
+
+## Validation
+
+- The complete package suite passed under `go test -race ./...` when combining
+  the initial run with successful reruns of `internal/configuration` and
+  `internal/llm`. Those two packages initially failed solely because the sandbox
+  disallowed their local `httptest` listeners; their reruns permitted listeners.
+- `go vet ./...` passed using Go 1.27.3 with `GOTOOLCHAIN=local`, `GOWORK=off`,
+  and offline module resolution.
+- Changed Go files are formatted. `git diff --check` and local document-target
+  checks passed. No implementation, dependency, policy, or release files were
+  changed during the review.