From 16584084b1b8a87dac959334ede8a47a8cfb8c0b Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 14:32:02 +0000 Subject: [PATCH] Record ConfigKit adoption scope and deferred inspection work --- docs/roadmap/configkit-v1.1.0.md | 258 +++++++++++-------------------- docs/roadmap/deferred.md | 49 +++++- 2 files changed, 139 insertions(+), 168 deletions(-) diff --git a/docs/roadmap/configkit-v1.1.0.md b/docs/roadmap/configkit-v1.1.0.md index 50721e1..d9e111d 100644 --- a/docs/roadmap/configkit-v1.1.0.md +++ b/docs/roadmap/configkit-v1.1.0.md @@ -1,9 +1,9 @@ # ConfigKit v1.1.0 adoption -Status: proposed; dependency and report changes are not implemented. This -roadmap covers the embedded `ckconfig` integration, the API coverage review, -and recommended extensions. Release coordination and capability scope have -recommendations under [Open Decisions](#open-decisions). +Status: recommended adoption scope recorded; implementation has not begun. +This roadmap covers the embedded `ckconfig` dependency and source-report +migration. [Recommended scope decisions](#recommended-scope-decisions) record +the first sprint and the extensions deferred to later work. ## Purpose and authority @@ -138,40 +138,20 @@ link to the owning inspection contract for their semantics. Describe the report migration plainly in the release note. The target uses the new field names without duplicate legacy report fields. -ConfigKit's source inventory also supplies `EmptyImportSelections`, with -declaration path, location, and selector. OD-2 addresses including this evidence -in the existing source report; it is not yet a selected report-schema addition. +Include `EmptyImportSelections` as `empty_import_selections` in both text and +YAML source reports under OD-2. Project each declaration path, location, and +native selector in the returned record order. Emit `empty_import_selections: []` +when there are no records. These are planned report changes; update the owning +CLI contract when implemented. -### Recommended inspection expansion +### Deferred inspection expansion -After the dependency and source-report adoption, prioritize an optional -metadata capability for field inspection, path discovery, and provenance -history. A narrow provider facet could expose ConfigKit's public `Metadata` -value directly. `FromConfigKit` can supply it from the loaded result; custom -scopes can declare the operations for which they provide the capability. -This is a proposed extension, not a new requirement on existing providers. - -Use upstream `Lookup` and `IsExplicit` for effective field metadata, -`HistoricalPaths` for observed-path enumeration, and `History` for definition, -inheritance, and resolution records. `HistoricalPaths` includes effective and -removed paths; it is not simply a list of current fields. Scope the report to -the returned upstream evidence rather than inferring an independent provenance -model. Command names, selectors, and report shapes need a focused design once -this extension is selected; this roadmap does not establish their grammar. - -Field-origin inventories are currently among the -[deferred proposals](deferred.md#other-deferred-proposals). OD-3 proposes -reconsidering that scope based on the reviewed public API. If selected, update -that record and the owning CLI/API documentation with implementation. Retaining -the proposal here does not by itself mark the extension accepted or implemented. - -Failed-load source inspection, detailed comparison reports, and structured -diagnostics remain separately considered additions under OD-4 through OD-6. -They use existing upstream evidence, but each changes CommandKit's presentation -or outcome coordination and needs its own scope choice. In particular, source -inventory output on an acquisition error would retain the failed outcome; -additional comparison detail would expose the native left/right snapshots, -presence/redaction fields, and `HiddenChanged` already returned to the provider. +Metadata inspection and path discovery are recommended as the next functional +sprint after adoption (OD-3). Failed-load source inventory, detailed comparison, +and structured diagnostics remain separate later proposals (OD-4 through OD-6). +The [configuration inspection extensions](deferred.md#configuration-inspection-extensions) +record owns their proposed capabilities and design considerations. None is part +of this adoption sprint or a new requirement on existing providers. ### Consumer migration and module coordination @@ -192,54 +172,72 @@ compatibility loader or impose new configuration restrictions. ckprompt's current ConfigKit types come from the old package identity. It cannot simply select the new ckconfig release while retaining that wiring. Its later adoption needs a coordinated ConfigKit/PromptKit migration and review of its -own adapters and composed example. OD-1 determines scheduling; this roadmap does -not select an unreviewed PromptKit release or claim a new matched integration set. +own adapters and composed example. Under OD-1, prepare ckconfig independently +first and review ckprompt next. This roadmap does not select an unreviewed +PromptKit release or claim a new matched integration set. + +### Interim workspace guidance + +Once local ckconfig uses the vanity ConfigKit types, the usual three-module +`go.work` selects it for local ckprompt as well. Until ckprompt migrates, its +old-path ConfigKit inspection and comparison types cannot satisfy the new +ckconfig contracts. This is a temporary composition mismatch, even though each +module can be validated independently against its own dependencies. + +During that interval, preserve the ignored local workspace and use `GOWORK=off` +for dependency preparation, tests, and example runs. From the repository root, +with the selected Go 1.27 toolchain on `PATH` and dependencies prepared: + +```sh +GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./... +(cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...) +(cd integrations/ckprompt && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...) +``` + +The unchanged ckprompt suite and composed example then use published ckconfig +v0.2.0 and their existing upstream dependencies. Their success does not validate +composition with the migrated local ckconfig. Keep local replacements and +workspace files out of the adoption commit. Resume three-module workspace and +composed-consumer validation after ckprompt's migration; update the ignored +workspace's Go version as needed for its member modules at that point. + +When the dependency change lands, update the development guide's workspace +instructions to explain this interval. Restore the aligned-workspace guidance +when ckprompt adopts the new dependencies. Until implementation, the existing +development instructions describe the current compatible baseline. ## Work from the baseline -1. **Confirm scope choices and prepare module metadata.** Resolve OD-1 and - OD-2 and record which proposed extensions, if any, join the adoption release. - Deferred extensions need not block the dependency migration. Select the +1. **Prepare module metadata for the recommended scope.** Follow OD-1 and + OD-2; OD-3 through OD-6 remain deferred. Select the Go 1.27 maintainer toolchain, update ckconfig's requirement, imports, and minimum, and regenerate authentic sums with workspace discovery off. Inspect the resulting dependency graph; do not commit local replacements or environment files as an adoption mechanism. 2. **Adapt APIs and source reports.** Update the native source field accesses, - DTOs, text/YAML output, affected tests, and example code. Apply the selected - empty-import-evidence choice. Preserve current coordination and outcomes - except where an explicitly selected extension changes presentation, such as - retaining a failure alongside returned source evidence. Adapt upstream - results rather than adding domain validation. -3. **Design and implement selected extensions.** Treat metadata inspection and - path discovery as the next functional work item under OD-3, whether included - here or scheduled next. Define its optional provider capability, CLI usage, - and report projection together. For any OD-4 through OD-6 feature selected, - specify its report delivery and outcome behavior before implementation. - Reuse native records and rendering where suitable; avoid a second domain - implementation or a generic framework solely to mirror upstream APIs. -4. **Update canonical documentation and notices.** Revise the ckconfig README + DTOs, text/YAML output, affected tests, and example code. Add empty-import + evidence, including empty lists and record order. Preserve + current coordination and outcomes. Adapt upstream results rather than + adding domain validation. +3. **Update canonical documentation and notices.** Revise the ckconfig README and GoDoc, [CLI source-report reference](../cli.md#list-configuration-sources), - consumer guide, and release toolchain instructions with the implemented - changes. Review the selected graph and upstream notices, then update - ckconfig attribution with the vanity identity, selected versions, and pinned - source links. Update other module notices only when their actual selections + consumer guide, release toolchain instructions, and development workspace + guidance with the implemented changes. Review the selected graph and + upstream notices, then update ckconfig attribution with the vanity identity, + selected versions, and pinned source links. Update other module notices only when their actual selections change. Preserve published release history. -5. **Validate the selected end state.** Run the ckconfig suite, including its +4. **Validate the selected end state.** Run the ckconfig suite, including its maintained example, independently with `GOWORK=off` and read-only module metadata on the selected Go 1.27 toolchain. Update focused adapter/report assertions for the new vocabulary and faithful projection of returned evidence. Preserve coverage of request forwarding, diagnostics, cancellation, output failures, and supported error identity. Assertions establish CommandKit adaptation; ConfigKit owns tests of its domain correctness. - For selected metadata capabilities, verify query forwarding and returned - field/history projection. For failed-load inventory or detailed comparison, - verify the selected report and outcome coordination without re-establishing - upstream acquisition, provenance matching, or sensitivity behavior. - Review changed Markdown links, fragments, and examples. If coordinated - ckprompt work is selected, also validate that module and the composed consumer - against the proposed dependency set; local-workspace success alone does not - establish independent module compatibility. -6. **Prepare the integration release.** Propose ckconfig v0.3.0, subject to the + Review changed Markdown links, fragments, and examples. Use the interim + workspace guidance for unchanged modules; record that their independent + checks do not establish compatibility with the migrated ckconfig. Full + composed-workspace validation belongs to the later ckprompt migration. +5. **Prepare the integration release.** Propose ckconfig v0.3.0, subject to the existing fresh-version guards, with tag `integrations/ckconfig/v0.3.0`. Explain changed ConfigKit type identity, Go minimum, report fields, and consumer migration in its checked-in note with the usual licensing footer. @@ -254,107 +252,35 @@ Implementation is complete when ckconfig's actual module metadata and imports select the new dependency, the selected report changes faithfully expose its returned evidence, the module suite and maintained consumer pass independently, and current documentation, notices, and release preparation describe that state. -Record resolved scope choices, final validation evidence, and the status of -each proposed extension. Features selected for this implementation need their -own provider/report evidence; recording a deferred proposal does not demonstrate -its implementation. A future source release is reported separately from -implementation completion; preparing this roadmap does not publish a version +Record final validation evidence and the temporary workspace composition +status. OD-3 through OD-6 remain in deferred work; their implementation is not +a completion condition for this sprint. A future source release is reported +separately from implementation completion; preparing this roadmap does not publish a version or migrate external applications. -## Open Decisions +## Recommended scope decisions -### OD-1: Release ckconfig first or coordinate both integrations? +These dispositions record the review recommendations for the adoption sprint. +They define its planned scope, not implemented contracts or authorization to +publish. Deferred features still need focused API and CLI design. -**Recommendation:** implement and release ckconfig independently first, and -review ckprompt's upstream migration as the next integration task. This keeps -the current scope concrete and uses the established independent module releases. -Existing ckprompt v0.2.0 consumers retain their published dependency set; document -that moving them to the new ckconfig needs the corresponding ckprompt migration. -The tradeoff is an interval with no newly aligned release pair. +| Decision | Recommended disposition | Reason | +| --- | --- | --- | +| OD-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep this sprint focused. Document the temporary workspace mismatch and lack of a newly aligned release pair. | +| OD-2: Empty-import evidence | Include `empty_import_selections`, with `[]` when empty, in text and YAML source reports. | Exposes existing upstream evidence alongside the other report-schema changes. | +| OD-3: Metadata and path discovery | Defer to the next functional sprint after adoption. | A coherent optional capability needs its own field/history report and command design. | +| OD-4: Failed-load source inventory | Defer to a separate source-inspection enhancement. | Requires source evidence on error and deliberate report/failure coordination. | +| OD-5: Detailed comparison | Defer; retain the existing reduced report in this sprint. | A richer form needs a report-selection and compatibility decision. | +| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering in this sprint. | Coordinate machine-readable records with shared reporting and outcome delivery. | -**Viable alternative:** complete the ConfigKit/PromptKit review and both -integration migrations before releasing the next pair, publishing ckconfig first -in dependency order. This gives composed consumers a coordinated adoption path -and validates the shared type boundaries together. It expands this work into -PromptKit adoption and delays ckconfig availability while that review and -implementation proceed. No simultaneous tag publication is needed. +The first sprint therefore covers dependency and API migration, source-report +terminology and empty-import evidence, documentation and notices, independent +module validation, and ckconfig release preparation. Core retains its own Go +minimum. Application loaders continue to own discovery and loading policy. -### OD-2: Include empty-import-selection evidence in this adoption? - -**Recommendation:** add `empty_import_selections` to the existing text/YAML -source report, projecting ConfigKit's declaration path, location, selector, and -record order. This exposes structured source evidence already available -upstream without a new command or a second explanation engine. It adds report -mapping and focused projection coverage alongside the other schema changes; -the exact empty-list presentation should be settled with the implemented report. - -**Viable alternative:** limit this release to migrating the evidence already -reported, and defer this additive field to a later inspection enhancement. That -reduces the immediate report change and test scope, and still makes the native -metadata available to Go consumers of ConfigKit. CLI consumers would continue -to lack this upstream evidence, and a later release would need another report -and documentation update. - -### OD-3: When and how should metadata inspection and path discovery land? - -**Recommendation:** make optional metadata inspection and path discovery the -next functional expansion after adoption. Expose the upstream metadata queries -through an optional facet, and design field and history reports together. This -adds explicitness, path discovery, and provenance information that current -explanations do not fully expose, while keeping existing providers usable. -It requires a focused CLI/API design and a later release if staged separately. - -**Viable alternative:** include that coherent expansion in the adoption release. -This gives consumers the broader inspection surface with one migration and -documentation update. It increases the current release's API, report, and -validation scope and can delay the dependency upgrade. Either schedule can use -the same upstream-owned query semantics; final command grammar remains a design -choice rather than a contract selected by this roadmap. - -### OD-4: Expose acquired sources when a configuration load fails? - -**Recommendation:** evaluate this as a separate source-inspection enhancement, -presenting `LoadError`'s returned inventory while retaining the load failure and -diagnostics. It makes upstream acquisition evidence available for troubleshooting -without treating the operation as successful. The design must account for -returning the source facet on error and delivering a report before terminal -failure presentation; that coordination is additional to mechanical adoption. - -**Viable alternative:** include this behavior in the adoption release alongside -the source-report changes. It delivers successful and failed-load inventory -inspection together and avoids another source-report release. It broadens the -current adapter and outcome changes and requires focused coverage of report -delivery failures as well as acquisition failure. Retaining current diagnostic -context alone until that work is selected remains viable. - -### OD-5: Add a detailed native comparison report? - -**Recommendation:** consider an additional report form in a later comparison -enhancement, retaining the current reduced form for its established operator -use. The detailed form would project `Path`, both snapshots, and `HiddenChanged` -from native records, making already-returned evidence available to CLI consumers. -Supporting two forms adds selection, presentation, and documentation work; -choose the interface when the feature is selected. - -**Viable alternative:** replace the reduced report with native-record projection -in a pre-v1 minor release. One report form is simpler to maintain and exposes -all current comparison fields directly. It requires deliberate migration of -published report consumers and changes the concise additions/changes/deletions -workflow. Keeping only the current form is also viable when that workflow meets -consumer needs; richer reporting is a capability proposal, not a correctness fix. - -### OD-6: Where should structured diagnostic reporting be introduced? - -**Recommendation:** retain native diagnostic rendering for this adoption and -consider structured records with CommandKit's shared reporting design. That -keeps result and diagnostic delivery consistent across integrations and custom -commands. It defers machine-readable native codes, paths, severities, and -locations until their report channel and outcome behavior are designed. - -**Viable alternative:** add an optional ckconfig-specific diagnostic report that -projects ConfigKit's records directly. This could deliver useful structured -evidence sooner without redesigning the shared reporting API. It introduces a -separate presentation path whose interaction with ordinary results, warnings, -and terminal failures needs definition and may later need alignment with other -families. It is a lower-priority extension rather than a dependency-adoption -requirement. +Coordinating both integrations before release remains an alternative if a +matched adoption path becomes necessary. It would expand the sprint to include +PromptKit review and ckprompt migration; publication would still proceed in +dependency order. The [deferred feature record](deferred.md#configuration-inspection-extensions) +retains the capability proposals and unresolved design choices for OD-3 through +OD-6, plus the possible source-ID filter. diff --git a/docs/roadmap/deferred.md b/docs/roadmap/deferred.md index 4d8f6b4..e31c370 100644 --- a/docs/roadmap/deferred.md +++ b/docs/roadmap/deferred.md @@ -25,6 +25,50 @@ unselected extensions to the delivered ConfigKit comparison. Consider them only for a concrete consumer need and a deliberate API/behavior decision under the relevant ADRs. +### Configuration inspection extensions + +The [ConfigKit v1.1.0 adoption review](configkit-v1.1.0.md#recommended-scope-decisions) +recommends the following work after dependency and source-report adoption. +Metadata inspection is the recommended next functional sprint; the other +features have no selected sequence or delivery date. These proposals do not +establish command grammar, report schemas, or new provider requirements. +ConfigKit's public APIs own the evidence and its semantics. + +- **Optional field metadata, path discovery, and history (OD-3).** Expose native + `Metadata.Lookup`, `IsExplicit`, `HistoricalPaths`, and `History` through an + optional provider capability. Design field and history reports together, + keeping existing providers usable. Distinguish effective paths from removed + historical paths: a failed `Lookup` must not suppress available `History`. + Validate that distinction and faithful projection of returned field/change + records without recreating upstream provenance logic. Historical enumeration + is not an exhaustive inventory of possible schema fields. This gives the + earlier field-origin inventory proposal a concrete, upstream-backed scope; + command names, selectors, and report shapes remain to be designed. +- **Failed-load source inventory (OD-4).** Present acquired source evidence from + `LoadError.Sources()` while retaining the failed outcome and diagnostics. + Design how an adapter returns its source facet on error and how result output + precedes terminal failure presentation. Cover acquisition and report-delivery + failures together; current diagnostic context remains available meanwhile. +- **Detailed comparison (OD-5).** Consider an additional form projecting native + `Difference` paths, both snapshots, presence/redaction fields, and + `HiddenChanged`. The adoption sprint retains the reduced + additions/changes/deletions report. Decide later whether a detailed form + complements it or replaces it through a deliberate compatibility change. +- **Structured diagnostics (OD-6).** Consider machine-readable native codes, + paths, severities, and locations alongside CommandKit's shared reporting + design. Define result/diagnostic channels, warning and terminal-failure + interaction, and delivery outcomes. A ckconfig-specific report remains an + alternative, with its cross-family alignment considered explicitly. +- **Source-ID filtering.** Consider selecting a record already available in the + source inventory. Native `Source(id)` lookup is a convenience; this proposal + need not introduce another command or require a lookup method from every + custom source provider. + +Discovery, import defaults, collection identities, and field-level resolution +recording remain available through application loaders. Standard inspection of +resource contexts or secrets-directory bootstrap has no immediate proposal; +those capabilities primarily serve application loading and startup. + ### Alias completion and discovery The delivered [shell completion feature](../cli.md#shell-completion) provides @@ -47,8 +91,9 @@ operator or consumer need and an appropriate ownership/behavior decision: - JSON reports and output-file management or reloadable export. - Shell completion extensions, including alias discovery described above and dynamic discovery of configured or remote values. -- Configuration mutation, generic value assignment, and exhaustive field-origin - inventories. +- Configuration mutation and generic value assignment. Field metadata and + provenance inspection are scoped under + [configuration inspection extensions](#configuration-inspection-extensions). - Credential diagnostics beyond PromptKit's native smoke checks and additional live provider probes. - Additional component identity registration and domain artifact catalogs.