From 101a2840d43f6902dc0b9e9f24d37a9ca70b6455 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 6 Nov 2026 16:40:33 +0000 Subject: [PATCH] Record resource inspection documentation gaps --- docs/roadmap/remediation.md | 95 +++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/roadmap/remediation.md diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..62aa34d --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,95 @@ +# Resource Inspection Implementation Review + +## Scope And Results + +Reviewed the twelve stages of [implementation.md](implementation.md) against +the accepted [feature roadmap](inspect-backend.md) and the current code and +documentation at `f083ad5`. The implementation commits run from `8add7c4` +through `f083ad5`, following planning commit `8563379`. + +The selected code architecture is implemented. Resource inspection delegates +from the facade through the internal engine to captured configuration records; +execution keeps its backend-completed targets, and requirement discovery keeps +its lightweight metadata path. Public projections detach mutable values. +Typed sources use ordinary ConfigKit mapping, composition, and resource context. + +One documentation finding remains. No correctness defect or unintended new +restriction or guarantee was identified in the reviewed implementation. The +resource-oriented profile result and changed post-handoff null fallback are +deliberately selected compatibility changes, not accidental regressions. + +## Findings + +### R1. Reconcile Remaining Inspection Contract Documentation [P2] + +**Status:** Open. **Affected stages:** 1, 11, and final reconciliation in 12. + +**Locations:** + +- [Package GoDoc](../../doc.go), lines 50–68: the JSON section still explicitly + lists `ProfileInspection` and `PromptInspection` among values without stable + JSON representations. +- [Configuration migration guidance](../consumers/configuration-migration.md), + lines 133–139: it still says that `InspectProfile` applies backend completion. + +These statements contradict the implemented result contracts in +[resource_inspection.go](../../resource_inspection.go), the method GoDoc in +[engine.go](../../engine.go), and the updated +[consumer guidance](../consumers/pkg-promptkit.md#inspect-a-profile-before-prompt-work). +The result types now deliberately own JSON/YAML keys, nesting, and omission +semantics. Profile inspection reports only the resolved profile's fields; +backend-completed settings belong to request preparation. + +**Impact:** Consumers consulting package documentation are told that the new +generic rendering contract is unavailable. Consumers following the migration +guide may still expect backend endpoints, credential sources, or provider +defaults in a profile report even though those fields can now be absent. This +undermines the primary migration and reporting purpose of the feature. + +**Required correction:** + +1. Update the package GoDoc's serialization description to include the selected + resource-result contract and remove the contradictory exclusions. Link to + the result/method owners for details. Preserve the distinction from source + inputs, provenance inspection, and unrelated values without a serialization + contract; do not add byte-format, ordering, or round-trip guarantees. +2. Replace the migration guide's backend-completion claim with the resolved + resource boundary and point readers needing completed request settings to + the existing preparation APIs/current consumer guidance. +3. Check the remaining current documentation for equivalent stale claims. + Published historical release notes should remain unchanged. + +**Verification:** Review the rendered package GoDoc and the affected migration +passage against the implemented types and method behavior; check edited local +links and whitespace. This is a documentation correction and does not require +another implementation path, compatibility field, or new runtime test. + +## Stage-By-Stage Review Record + +| Stage | Evidence inspected and result | +| --- | --- | +| 1 — Result declarations | `resource_inspection.go` and nested diagnostic tags in `backends.go` match the selected fields and optional-pointer representation. Package-level serialization documentation still needs R1. | +| 2 — Null interpretation | `captureExecutionProfile` uses configured pointer/map presence; profile-only tri-state capture is removed. Target and isolation tests cover null/omission fallback, inherited null, empty-string clearing, map overlay, and the required-key rule. | +| 3 — Backend/profile resources | `internal/configuration/resources.go` reads indexed resolved records, not completed targets. Adapter tests cover partial/inherited profiles, derived queue defaults, missing IDs, and configured/inherited diagnostics. | +| 4 — Prompt resources | Prompt capture retains the resolved record, materialized messages, and required/repair presence. Prompt tests cover inherited imported text and omitted versus explicit values; inspection does not reopen sources or resolve referenced profiles/schemas. | +| 5 — Facade wiring | The internal engine's resource interface delegates to the snapshot after namespace qualification. Root conversion detaches pointers, collections, and nested diagnostics; backend not-found mapping is local to `InspectBackend`. Public error and cancellation tests pass. | +| 6 — Existing consumers | Superseded runner wrappers and their dedicated tests are removed. Execution helpers and the narrow requirement repository remain. Existing profile, inheritance, source, namespace, bundle, and preparation-example tests are migrated. | +| 7 — Generic encoding | `resource_serialization_test.go` encodes real results with ordinary JSON and YAML encoders and checks semantic keys, omission, explicit values, empty collections, diagnostic objects, and provider nulls. The existing YAML dependency is direct; its version is unchanged. | +| 8 — Isolation/selection | Public tests cover scoped backend lookup, qualified bypass, no namespace fallback, independent results, concurrent inspection/mutation, offline references, execution fallback, and retained null provenance. | +| 9 — Typed sources | `prompts.go` and `BackendSource` use explicit mapping construction with optional pointers/collections and sibling `extends`. They do not validate incomplete records, resolve inheritance, or read content files. | +| 10 — Real composition | Typed-source tests cover snapshots, layered completion, nested settings, order, inheritance, explicit values, relative file context, invalid final definitions, and empty top-level input. | +| 11 — Documentation | Main consumer, format, and internal guidance, README, and the unpublished v0.20.0 release note reflect the selected changes. Two remaining current-documentation contradictions require R1. | +| 12 — Combined validation | Race-enabled suite, vet, module tidy comparison, formatting, and changed Markdown link-target checks pass. The documentation finding prevents declaring reconciliation fully complete. | + +## Validation Performed + +Using Go 1.27.3 with `GOTOOLCHAIN=local`, `GOWORK=off`, and `GOPROXY=off`: + +- `go test -race ./...` passed, including the maintained offline examples. +- `go vet ./...` passed. +- `go mod tidy -diff` reported no changes. +- Formatting checks on surviving changed Go files and `git diff --check` passed. +- Local link targets in the changed Markdown documents exist. + +The review made no production-code or test changes. These checks do not include +live provider diagnostics, release publication, or downstream application changes.