diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..824dca6 --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,83 @@ +# Configuration Handoff And Repair Review + +Reviewed implementation stages 1–17 against +[the implementation plan](implementation.md), +[the feature roadmap](next-release-considerations.md), and accepted ADRs +[0001](../adr/0001-configuration-boundary.md) and +[0002](../adr/0002-shared-configuration-data-model.md). +Implementation baseline: `40f8a6825359b4923645256e230a050dfdb00710`; +reviewed changes begin after `248d0db`. + +## Findings + +### 1. Narrow The Pre-Handoff Mutation Wording To The Accepted Expectation + +Status: open. Priority: P3. Implementation stage: 16. + +Locations: `engine.go:280` and `docs/consumers/pkg-promptkit.md:132`. + +`NewFromConfig` says callers **must not mutate** selected settings between loading +and handoff; the consumer guide repeats that blanket instruction. The accepted +roadmap instead asks callers to hand off before changes that invalidate the +frozen inspection/provenance evidence, and expressly treats this as a usage +expectation rather than a new enforcement mechanism. The published wording +prohibits even value-preserving reassignment or copying, which needs no such +restriction. + +Required change: describe the narrower consistency expectation in both owners. +Explain that construction consumes the resolved settings while inspection retains +the completed load's frozen evidence, so callers should keep those consistent at +handoff. Preserve the existing protection against mutation after construction. +No mutation detection, extra validation pass, or new error is needed. + +Verification: review both passages against the feature roadmap's ownership +paragraph; ensure they no longer impose an unconditional mutation prohibition. +This is a documentation correction and does not require a new runtime test. + +### 2. Keep Application-Field Sensitivity Policy With The Application + +Status: open. Priority: P3. Implementation stage: 16. + +Location: `docs/formats.md:235–236`. + +The backend format reference says an unrecognized backend field is application +data and **must not contain secrets**. The accepted extension-point contract +assigns interpretation, validation, and sensitivity rules for those fields to +the application. The implementation follows that contract: inline fields remain +in native inspection, application sensitivity predicates compose with PromptKit's, +and those fields are omitted from resource reports and provider parameters. +The added prohibition unnecessarily narrows the application-owned data contract. + +Required change: retain the useful warning that a raw `api_key` extension is not +a PromptKit credential input and is not automatically redacted by PromptKit. +State that the application owns sensitivity declarations and disclosure policy +for its extension fields, rather than prohibiting their contents. Review the +adjacent profile wording for the same distinction between PromptKit credentials +and application-owned data. Do not add automatic credential behavior or a new +validator for application fields. + +Verification: compare the revised text with the feature roadmap's +application-specific-fields contract and existing focused-inspection sensitivity +coverage. No change to execution or redaction implementation is needed. + +## Review Results And Validation + +- Stage 1: ConfigKit v1.4.0, unchanged Go minimum, and commit-pinned attribution + match the selected module and its notices. +- Stages 2–3: configuration and runtime inputs resolve mode-dependent repair + budgets; explicit zero and null/omission, whole-contract replacement, prepared + retention, and existing repair accounting are covered. +- Stages 4–9: shared settings aliases, composed stateless rules, final-metadata + resource capture, native focused inspection, explicit source mounting, and + shared constructor/assembly paths match the target architecture. +- Stages 10–15: migrated tests and maintained offline examples exercise the + changed boundaries, including concurrent loads, cross-filesystem inheritance, + application extensions, ownership, and standalone/handoff equivalence. +- Stages 16–17: canonical documentation is updated, subject to the two wording + corrections above. No additional functional or architectural defect was found. + +Fresh checks passed with Go 1.27.4, `GOTOOLCHAIN=local`, and `GOWORK=off`: +`go test -race ./...` and `go vet ./...`. Changed Go files have no `gofmt` +differences, and the implementation diff passes `git diff --check`. + +This review changes only this findings document; it does not implement fixes.