diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..694dfc3 --- /dev/null +++ b/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.