Record configuration migration review findings
This commit is contained in:
83
docs/roadmap/remediation.md
Normal file
83
docs/roadmap/remediation.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user