Record conversation API documentation review finding

docs/roadmap/remediation.md

@@ -0,0 +1,65 @@
+# Conversation Continuation Review Remediation
+
+## Review Scope
+
+Reviewed all 13 stages of the [implementation plan](implementation.md) against
+the [accepted target](conversation-continuation.md), implementation, tests, and
+documentation. Baseline: `5c135c5`, including the implementation commits after
+`5cc3fa0`.
+
+The implementation retains the intended boundaries: immutable parent-linked
+history, ordinary preparation and execution for continuations, a separate
+sequential coordinator, and explicitly selected observer-based groups. No runtime
+correctness defect or inadvertently strengthened restriction was identified.
+The remaining finding concerns the durable public documentation in Stage 13.
+
+Validation completed with the locally installed Go 1.27.3 toolchain,
+`GOTOOLCHAIN=local`, `GOWORK=off`, and a writable temporary build cache:
+
+- `go test -race ./...` passed, including the maintained examples.
+- `go vet ./...` passed.
+- `git diff --check` passed.
+
+## 1. Complete The Public Exchange Capture And Continuation Contract
+
+**Priority:** P2. **Status:** Open. **Plan stage:** 13.
+
+**Locations:** [request fields](../../types.go),
+[exchange declarations and accessor](../../exchange.go), and
+[consumer guidance](../consumers/pkg-promptkit.md#capture-and-continue-a-conversation).
+
+The `CaptureExchange` and `ContinueFrom` GoDoc currently provides only a short
+description of opt-in capture, invalid handles, and fresh follow-up settings.
+The `Exchange` and `Details` comments describe reuse and detached history, but do
+not define its exact contents or explain that inspection uses only retained
+state. Important selected semantics remain documented only in temporary roadmaps
+or prose/internal guidance:
+
+- History contains the effective original request and exact final assistant
+  content, preserving roles and cache metadata; intermediate structural-repair
+  candidates and corrective instructions are excluded.
+- Continuation assembles captured history, rendered follow-up definition
+  messages, and caller-appended messages in that order, without re-rendering or
+  reading the original inputs. It adds no history-size limit or truncation.
+- `PrepareExecution` retains capture selection for execution of its snapshot;
+  preparation and concrete-request validation alone produce no completed exchange.
+- `Details` reads the retained snapshot without rendering, filesystem reads, or
+  provider calls. Its run identities identify the originating execution and
+  immediate parent execution.
+
+These behaviors are implemented. The gap is that the exported declarations and
+GoDoc do not yet own their complete contract as required by the documentation
+policy and the final implementation stage. Retiring the roadmap would otherwise
+leave consumers and future maintainers without a complete canonical reference.
+
+**Required remediation:** Document these existing semantics at the appropriate
+request fields, exchange type/details, and prepared-execution declarations, using
+GoDoc cross-references instead of repeating the same contract across declarations.
+Link the new consumer walkthrough to those public owners. Preserve the selected
+scope: do not add persistence, limits, stronger serialization guarantees, or
+private storage/allocation promises while documenting the behavior.
+
+**Verification:** Check the comments against the existing capture, continuation,
+prepared-execution, ownership, and repair tests and implementation. Validate the
+affected documentation links and diff. This is documentation remediation; it
+does not require changing runtime behavior or duplicating existing tests.