promptkit/docs/roadmap/remediation.md

Conversation Continuation Review Remediation

Review Scope

Reviewed all 13 stages of the implementation plan against the accepted target, 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, exchange declarations and accessor, and consumer guidance.

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.