diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..d98ceed --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,87 @@ +# ConfigKit and PromptKit adoption review + +Reviewed revision: `e70a0ef301a3d34f64a6cba86dd68b728436534d`. +Status: one open finding. Reviewed 2026-11-21. + +## Scope and results + +Reviewed all seven stages of the [implementation plan](implementation.md) +against the accepted [feature roadmap](configkit-v1.4.0-promptkit-v0.24.0.md), +the implementation, changed tests, and documentation. + +| Stage | Review result | +| --- | --- | +| 1 — Dependencies | Both integrations select ConfigKit v1.4.0; ckprompt selects PromptKit v0.24.0. Core and the Go minimum remain at the planned versions. Changed attribution identifies the selected upstream commits. | +| 2 — Native path enumeration | Optional `View.Paths` and the metadata fallback preserve the distinction between an unavailable reader and an empty native list. Existing metadata-backed filters remain in use. | +| 3 — Subtree adapter | The typed loader/path API shares acquisition and diagnostics, delegates focused inspection and comparison, and retains whole-load evidence and native ancestor differences. | +| 4 — PromptKit migration | Native inspection supplies the new path capability; fixtures use the new destinations. Native schema, repair-budget, hash, requirements, and supported error evidence pass through the existing adapters. | +| 5 — Shared-load example | Shared loading and storage scope wiring are present, but campaign prompt-ID derivation has the correctness defect in R1. | +| 6 — Documentation | Current guidance and candidate notes describe the new APIs and migration, distinguishing candidates from published dependencies. | +| 7 — Validation and coordination | Workspace and isolated-local-dependency checks pass. The ckprompt released-dependency limitation and coordinated releases are explicitly pending as planned. | + +No additional strengthened contract, prohibition, or guarantee requiring +remediation was identified. The recorded ConfigKit filesystem-error identity +limitation follows the upstream error contract and is not an integration defect. + +## R1 — Campaign prompt-ID changes fail configuration resolution + +Priority: P2. Status: open. + +Relevant code: the application resolve callback in +[`loadApplicationConfig`](../../integrations/ckprompt/examples/composed/main.go), +particularly the prompt-ID assignment and resolution record at lines 136–138. +This is maintained example code; the generic scope adapters are not the cause. + +When the selected campaign's `prompt_id` differs from `briefing`, the callback +renames the example's default prompt. It records normalization only at +`/promptkit/prompts//id`. `promptkit.Configure` registers this list as an +identified sequence. Changing an identity changes collection membership, which +requires a record covering the list or an ancestor under ConfigKit's +[resolution contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/docs/config.md). +The leaf record does not cover that change. + +Reproduced from `integrations/ckprompt/examples/composed` with Go 1.27.4 and the +aligned workspace: + +```sh +GOTOOLCHAIN=local go run . config validate --scope app \ + --set '/campaigns/spring/prompt_id="custom"' --format json +``` + +Actual behavior: loading fails with `resolve.unrecorded_change` at +`/promptkit/prompts`, the report marks the app scope failed, and the application +exits with status 1. The same failure occurs when a main configuration selects +that campaign prompt ID. Because resolution is shared, it also prevents engine +construction and inspection through other scopes for that configuration. + +Expected behavior: the application result and engine expose the selected valid +campaign prompt ID, with a correctly recorded derivation. The earlier example +constructed the prompt with `chosen.PromptID`; Stage 5 requires preservation of +campaign selection while moving its derivation into the shared load. Neither +the campaign configuration nor the roadmap restricts the ID to `briefing`. + +Remediation: record the membership change at `promptPath` +(`/promptkit/prompts`) when renaming the prompt, retaining the campaign +dependencies and reason. Alternatively, restructure campaign prompt derivation +to create/select the intended entry and record any collection membership change +at that same native collection boundary. Keep ConfigKit's audit enabled and +preserve application selection; restricting IDs to the hard-coded default would +hide the regression. + +Extend the existing composed-example coverage with a non-default campaign +prompt ID. Verify successful loading, the selected resource in the catalog, and +agreement between shared inspection and engine inspection. Existing fixtures +all select `briefing`, so their passing results do not exercise this branch. + +## Verification + +With Go 1.27.4, the core and ckconfig independent default suites passed. All +three aligned workspace suites passed, including maintained examples. ckprompt's +isolated default suite also passed with an external temporary modfile replacing +only ckconfig with the local module; the repository module files were unchanged. +That result does not establish an independent build against the still-selected +published ckconfig v0.9.0, as already recorded in +[release coordination](future.md#pending-integration-release-coordination). + +The R1 reproduction fails despite those passing suites. No production code or +tests were modified during this review.