From 1c778d7ad3edb6837749d9fd683f416e716de532 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 14:42:23 +0000 Subject: [PATCH] Plan ConfigKit adoption sprint --- docs/roadmap/configkit-v1.1.0.md | 128 ++-- docs/roadmap/deferred.md | 2 +- docs/roadmap/implementation.md | 610 ++++++++---------- .../integration-dependency-alignment.md | 2 +- 4 files changed, 315 insertions(+), 427 deletions(-) diff --git a/docs/roadmap/configkit-v1.1.0.md b/docs/roadmap/configkit-v1.1.0.md index d9e111d..a58958d 100644 --- a/docs/roadmap/configkit-v1.1.0.md +++ b/docs/roadmap/configkit-v1.1.0.md @@ -1,9 +1,10 @@ # ConfigKit v1.1.0 adoption -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. +Status: adoption scope selected; implementation has not begun. This roadmap +defines the embedded `ckconfig` dependency and source-report target. +[Selected scope decisions](#selected-scope-decisions) distinguish adoption from +deferred extensions. The [implementation plan](implementation.md) owns stage +order, concrete changes, and validation steps. ## Purpose and authority @@ -19,9 +20,10 @@ This follows the clarified integration goal and the existing [architecture policy](../policy/architecture.md#backend-and-library-integration). The [agent](../policy/agents.md), [testing](../policy/testing.md), [documentation](../policy/documentation.md), [release](../policy/release.md), and -[OSS](../policy/oss.md) policies govern implementation. This roadmap proposes -work; current contracts remain in GoDoc, the [CLI reference](../cli.md), and the -[consumer guide](../consumers/guide.md) until implementation lands. +[OSS](../policy/oss.md) policies govern implementation. This roadmap records +the selected target; current contracts remain in GoDoc, the +[CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md) until +implementation lands. ## Current baseline and review evidence @@ -146,12 +148,12 @@ CLI contract when implemented. ### Deferred inspection expansion -Metadata inspection and path discovery are recommended as the next functional -sprint after adoption (OD-3). Failed-load source inventory, detailed comparison, +Metadata inspection and path discovery are the next functional work proposed +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. +of this adoption scope or a new requirement on existing providers. ### Consumer migration and module coordination @@ -176,7 +178,7 @@ 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 +### Independent module compatibility 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 @@ -184,67 +186,26 @@ 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: +During that interval, each module's independent validation uses its own declared +dependencies with workspace discovery off. The unchanged ckprompt and composed +example retain published ckconfig v0.2.0 and their existing upstream libraries; +their success does not establish compatibility with migrated local ckconfig. +Development and consumer guidance explain the temporary mismatch. Existing +ignored workspace files remain local; restoring aligned workspace composition +belongs to the later ckprompt migration. -```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 ./...) -``` +### Release preparation -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. +The target candidate is ckconfig v0.3.0, with full tag +`integrations/ckconfig/v0.3.0`, subject to the existing fresh-version guards. +A pre-v1 minor fits the intentional ConfigKit type-identity, consumer-minimum, +and report-schema changes. Its checked-in note explains these changes and +consumer migration, with the usual immutable licensing footer. Current module +notices describe the selected graph and pinned upstream source. -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. **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. 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, 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. -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. - 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. - A pre-v1 minor fits these intentional compatibility changes. Use the existing - selected-module release procedure when publication is requested; this plan - adds no release gate. Source publication and hosted Gitea delivery retain - their separate outcomes. +Adoption includes release preparation, not source publication or hosted +delivery. The existing [release procedure](../release.md) owns those operations +and their separate outcomes when requested; this target adds no release gate. ## Completion evidence @@ -252,34 +213,33 @@ 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 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. +Completion evidence distinguishes independent module validation from the +temporary workspace composition mismatch. OD-3 through OD-6 remain in deferred +work; their implementation is not a completion condition for adoption. A future +source release is reported separately from implementation completion. -## Recommended scope decisions +## Selected scope decisions -These dispositions record the review recommendations for the adoption sprint. -They define its planned scope, not implemented contracts or authorization to +These dispositions record the user's selected adoption scope. +They define the target, not implemented contracts or authorization to publish. Deferred features still need focused API and CLI design. -| Decision | Recommended disposition | Reason | +| Decision | Selected 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-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep adoption 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-3: Metadata and path discovery | Defer to the next functional work 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. | +| OD-5: Detailed comparison | Defer; retain the existing reduced report during adoption. | A richer form needs a report-selection and compatibility decision. | +| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering during adoption. | Coordinate machine-readable records with shared reporting and outcome delivery. | -The first sprint therefore covers dependency and API migration, source-report +Adoption 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. Coordinating both integrations before release remains an alternative if a -matched adoption path becomes necessary. It would expand the sprint to include +matched adoption path becomes necessary. It would expand the scope 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 diff --git a/docs/roadmap/deferred.md b/docs/roadmap/deferred.md index e31c370..a8767b9 100644 --- a/docs/roadmap/deferred.md +++ b/docs/roadmap/deferred.md @@ -27,7 +27,7 @@ relevant ADRs. ### Configuration inspection extensions -The [ConfigKit v1.1.0 adoption review](configkit-v1.1.0.md#recommended-scope-decisions) +The [ConfigKit v1.1.0 adoption review](configkit-v1.1.0.md#selected-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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 5800142..0ab85c4 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,374 +1,302 @@ -# CommandKit vanity migration and dependency alignment plan +# ConfigKit v1.1.0 adoption implementation plan -Status: Stages 1–7 complete. +Status: planned; Stages 1–6 are not started. -This plan is for the Luna coding agent implementing the -[feature roadmap](integration-dependency-alignment.md). Follow the stages in -integer order during one end-to-end sprint. Unpublished editing states may be -temporarily inconsistent. Each published module must be a coherent, committed -candidate validated by its ordinary release workflow. +This plan is for a Luna coding agent implementing the selected +[ConfigKit adoption target](configkit-v1.1.0.md). Follow Stage 1 through Stage 6 +in order as one end-to-end sprint. Intermediate editing states need not compile +or form independently usable releases. Reach and validate the complete selected +end state before claiming completion; do not introduce compatibility machinery +merely to make an intermediate stage pass. -This planning pass changes documentation only. The target includes three real -source releases because later modules need downloadable predecessors. The -publication stages below describe that future work; this planning request does -not perform or authorize Git pushes. Honor the user's implementation/publication -scope when executing the plan, and report any unperformed release as pending. +This planning pass changes documentation only. Execution prepares a ckconfig +release candidate; source publication, hosted delivery, ckprompt migration, and +the deferred inspection extensions are outside this sprint. Do not push or +create release tags as part of these stages. The user's later publication +instructions and the [release procedure](../release.md) govern those operations. -Read [development guidance](../development.md), the -[agent policy](../policy/agents.md), [architecture policy](../policy/architecture.md), -[testing policy](../policy/testing.md), -[documentation policy](../policy/documentation.md), -[release policy](../policy/release.md), and [OSS policy](../policy/oss.md) for -the work they govern. Follow `AGENTS.md` codebase-memory discovery instructions. -The [release procedure](../release.md) remains the owner of operational commands. +Start with [development guidance](../development.md) and follow the +[agent](../policy/agents.md), [architecture](../policy/architecture.md), +[testing](../policy/testing.md), [documentation](../policy/documentation.md), +[release](../policy/release.md), and [OSS](../policy/oss.md) policies for the work +they govern. Use the repository's codebase-memory tools for code discovery. +The completed [vanity migration plan and publication evidence](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/16584084b1b8a87dac959334ede8a47a8cfb8c0b/docs/roadmap/implementation.md) +remain in Git history; do not restart that work or the completed ReleaseKit +adoption/remediation. -The previous plan's [completed ReleaseKit v0.9.0 stages and evidence](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a/docs/roadmap/implementation.md) -remain in Git history. R1/R2 in [remediation.md](remediation.md) and the ReleaseKit -adoption are complete; do not restart them or rewrite their historical evidence. +## Baseline and fixed choices -## Baseline and fixed decisions +Source/review baseline: `16584084b1b8a87dac959334ede8a47a8cfb8c0b`. +The planning commit changes roadmap documents, not module code. -Planning baseline: `c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a`. +| Item | Baseline | Selected end state | +| --- | --- | --- | +| ckconfig module | `go.maximumdirect.net/ckconfig`, published v0.2.0 | Same module identity; prepare v0.3.0 | +| ConfigKit | `gitea.maximumdirect.net/eric/ConfigKit v0.8.0` | `go.maximumdirect.net/configkit v1.1.0` | +| ckconfig Go minimum | Go 1.26.0 | Go 1.27.0 | +| Core dependency | `go.maximumdirect.net/commandkit v0.3.0` | Retain v0.3.0 | +| Maintainer toolchain | Go 1.26.8 | Go 1.27.0 for preparation, validation, and ReleaseKit execution | +| Other module minimums | Core and ckprompt: Go 1.26.0 | Retain their independent minimums | -| Module directory | Current module path | Target module path | Target version and full tag | -| --- | --- | --- | --- | -| `.` | `gitea.maximumdirect.net/eric/CommandKit` | `go.maximumdirect.net/commandkit` | v0.3.0; `v0.3.0` | -| `integrations/ckconfig` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `go.maximumdirect.net/ckconfig` | v0.2.0; `integrations/ckconfig/v0.2.0` | -| `integrations/ckprompt` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `go.maximumdirect.net/ckprompt` | v0.2.0; `integrations/ckprompt/v0.2.0` | +ConfigKit v1.1.0 is published at +`191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9`. Its module requires Go 1.27.0; +the prior disposable migration passed ckconfig and its example tests on that +toolchain. The selected report changes have not yet been implemented or tested. -- Both integrations currently require core v0.2.0; ckprompt also requires - ckconfig v0.1.0. Their source uses newer core APIs. Independent baseline suites - fail; temporary local-source selections pass only when ckprompt also uses - current ckconfig. The feature roadmap records those diagnostics. -- Target ckconfig requires `go.maximumdirect.net/commandkit v0.3.0`. Target - ckprompt requires that core and `go.maximumdirect.net/ckconfig v0.2.0`. -- Vanity discovery is verified. The integration metadata's fourth field maps - the short paths to the existing physical directories. Existing tags still - declare old identities. Discovery alone does not complete module migration. -- Preserve package names, exported declaration shapes, runtime behavior, Go - 1.26.0 consumer minimums, and the Go 1.26.8 maintainer toolchain. Preserve root - ReleaseKit v0.9.0 selection, scripts, profiles, endpoints, and validators. -- Retain ConfigKit v0.8.0 and PromptKit v0.16.0; no upstream library upgrade is - selected. Inspect tidy's actual graph changes and update affected attribution. -- The three proposed tags were unused at planning time. Existing publication - guards recheck freshness; never move/reuse a published tag. A conflict needs - a deliberate new version selection and matching dependent metadata/notes. -- Retain ignored `go.work` and `go.work.sum`, and the supplied ignored - `.releasekit/gitea-token` without reading its contents. No credential or live - provider is needed for local validation. Source publication uses the existing - Git endpoint; hosted delivery remains a separate operation/outcome. +The feature roadmap's selected OD-1/OD-2 choices apply: migrate ckconfig first +and include empty-import-selection evidence. OD-3 through OD-6 and source-ID +filtering remain in [deferred work](deferred.md#configuration-inspection-extensions). +Retain the existing configuration operations, provider facets, loading and +comparison coordination, diagnostics, outcomes, and reduced diff report. +ConfigKit owns domain semantics; this sprint adapts its public capabilities. -Do not rename physical module directories or flatten integration tag prefixes. -Do not add an old-path forwarding module, type-interoperability layer, API -rollback, permanent validation shim, or new recurring release gate. These are -outside the selected migration, not new restrictions on application behavior. +Retain root ReleaseKit v0.9.0, the release launchers and profiles, physical +module directories, and integration tag prefixes. Core and ckprompt code and +module selections are outside this adoption. Published old releases and notes +remain immutable. A new adapter layer, legacy import bridge, duplicate legacy +report fields, or local reimplementation of ConfigKit semantics is unnecessary. -## Execution and validation conventions +Preserve ignored `go.work`, `go.work.sum`, and `.releasekit/gitea-token` without +reading credential contents. Use `GOWORK=off GOTOOLCHAIN=local` throughout module +preparation, validation, and example runs. Local ckprompt will not compose with +migrated local ckconfig until its later ConfigKit/PromptKit migration; its +independent suite continues to use published ckconfig v0.2.0. Do not edit +ckprompt or introduce replacements to conceal this temporary mismatch. -Use Go 1.26.8 on `PATH` following the existing -[toolchain setup](../release.md#release-toolchain). The ignored workspace declares -Go 1.26.10 at baseline; preserve it. Use `GOWORK=off GOTOOLCHAIN=local` for module -preparation and independent validation. Use normal dependency retrieval during -preparation; ReleaseKit runs the final selected-module suite offline/read-only. +## Stage 1: Migrate the dependency, imports, and removed Go APIs -Migrate module-owned source, tests, and examples together. Apply integration -path mappings before the broader core prefix when a replacement tool is used; -`go.maximumdirect.net/commandkit/integrations/ckconfig` is not the selected -ckconfig identity. Preserve import aliases such as `commandkit`. Core `internal` -imports must use the new core prefix. Review identity-sensitive strings as well -as Go import declarations. +1. Inspect the worktree and preserve unrelated work. Select Go 1.27.0 on + `PATH` and confirm it with `GOWORK=off GOTOOLCHAIN=local go version`. + This version was available during planning. Reuse an existing installation, + or install/download `golang.org/dl/go1.27.0` using the established SDK setup + pattern in the release procedure. Do not change the ignored workspace to + select the toolchain. +2. In `integrations/ckconfig/go.mod`, set `go 1.27.0`, remove the old ConfigKit + requirement, and require `go.maximumdirect.net/configkit v1.1.0`. Keep the + core requirement and YAML selection unless ordinary resolution establishes + a required change. Do not tidy root/ckprompt merely to raise their minima. +3. Migrate ckconfig-owned Go imports, including tests and the simple example, + to the new ConfigKit identity. Preserve the package alias `configkit`. + Inspect literals and documentation references separately from imports; + old repository URLs in published history are not import-path defects. +4. Adapt the native source-field accesses in `sources.go` to + `DestinationIsFallback` and `VersionEvidence`. Use + `configkit.SourceVersionEvidence` in affected test fixtures. The public + `SourceReader` contract still returns `[]configkit.SourceInfo` through the + new import identity; it needs no additional methods. +5. Update removed APIs actually used by the tests: `Definition.Secret` becomes + `Sensitive` in `comparison_adapter_test.go`, `diff_execution_test.go`, and + `diff_report_render_test.go`; the normalization call in + `TestFromConfigKitCompareIgnoresDefaultAndResolutionHistoryForEqualValues` + becomes `RecordNormalization(path, reason)`. Preserve the existing + application mutation and assertions. Search for any other used removed + symbols and use the pinned upstream migration mapping, not aliases or + replacement domain logic. +6. After import migration, prepare dependencies and run `go mod tidy` from + ckconfig with workspace discovery off and the selected local toolchain. + Use normal dependency retrieval during preparation; inspect the authentic + resulting `go.mod`/`go.sum` changes. Do not fabricate sums or use a sibling + checkout as a dependency. Format changed Go files. -Update current prose and GoDoc for the module being migrated. Treat repository, -license, and immutable historical source links separately from Go import paths. -Keep published notes, accepted ADR history, and completed review evidence intact. -Do not globally replace every old URL or migrate unrelated upstream identities. +**Stage result:** ckconfig selects the released vanity dependency and current +Go APIs. Report spelling and new evidence are completed by the next stages; +there is no requirement to keep this intermediate state independently usable. -Publication steps use the existing protocol: prepare dependencies, review and -commit the final selected candidate on `main`, publish that candidate commit to -the authoritative branch, and invoke the module's release wrapper. The wrapper -runs the owning complete suite once, selected file checks, and publication -guards, then creates/pushes the intended tag. It does not push `main` for you. -Run validation-only `check` for diagnosis when useful; do not make it a required -duplicate suite before `publish`. Do not add CI/proxy polling or post-push -read-back as a successful-publication gate. Reuse evidence for unchanged content. +## Stage 2: Align source-report vocabulary and add empty-import evidence -Each release has its own candidate commit, suite result, and publication outcome. -The next module's dependency download is preparation for that next release; -failure to download does not undo completion of the predecessor's source push. -Use a command-scoped direct download to diagnose proxy lag if necessary rather -than permanently changing proxy settings. Retain authentic downloaded sums. +Work in `integrations/ckconfig/sources.go`. Keep its existing report preparation +and delivery path; no new provider capability or operation is needed. -## Stage 1: Migrate core identity and prepare its release candidate +1. Rename DTO fields/types and both text/YAML keys to match the upstream terms: + `DestinationIsFallback` / `destination_is_fallback`, and + `VersionEvidence` / `version_evidence`. Rename `sourceVersionCheckDTO` to + `sourceVersionEvidenceDTO`. Continue projecting all existing version, + location, presence, null, and redaction fields as returned. Allow the native + main layer value to appear as `main`; do not translate it back to `base`. +2. Add `EmptyImportSelections` to each source DTO, serialized as + `empty_import_selections` after `version_evidence`. Use an ordinary slice of + a small DTO with fields in this order: `path` string, `location` using the + existing `locationDTO`, and `selector` string. No `omitempty` is needed: + initialize the slice so sources without records serialize as `[]`. +3. For every native record, project `Path.String()`, its supplied location's + source ID/line/column, and `string(Selector)`. Preserve source and record + order, source-local coordinates, empty strings, and zero coordinates. + Forward selector strings without validating or remapping them. Apply no + additional import discovery, filesystem access, or domain interpretation. +4. Extend the text writer with the same field names and field order. For an + empty slice, print `empty_import_selections: []`. For nonempty slices, print + one indented record per entry with `path`, `location`, and `selector`. + Follow the existing text style: quote path/source-ID/selector strings with + `strconv.Quote` and render a location as + `{source_id: "...", line: N, column: N}`. YAML uses the equivalent mapping. +5. The current text writer uses `continue` after printing a null version check. + Restructure that conditional so a null `version_evidence` does not skip the + new empty-import field. Every reported source includes both fields, with + `version_evidence: null` where the upstream pointer is nil. -**Completed.** The root module, owned imports, component build identity, -consumer guidance, and v0.3.0 release note use the new core identity. The -focused build-identity test passed offline with Go 1.26.8; affected links and -whitespace were checked. The complete candidate suite belongs to publication. +**Stage result:** both report forms use the current vocabulary and expose +empty-import evidence, including when no version evidence exists. Existing +source inventory, explanation, diagnostic, and outcome semantics are retained. -1. Change only the root module declaration to `go.maximumdirect.net/commandkit`. - Migrate root-owned imports in production files, root/external tests, internal - packages, and `examples/core`. Leave nested module migration to Stages 3/5. - Preserve the root tool declaration and other dependency versions; prepare - caches and tidy the root with workspace discovery off. -2. Update `commandKitModulePath` in `builtins.go` to the new core identity. - `version --scope commandkit` uses it to find build information. Retain its - existing application/component scopes, tag/replacement handling, and `dev` - fallback; do not add a legacy-identity fallback. -3. Adapt existing identity/import-path test expectations. In - `TestCommandKitBuildIdentityProjectsEffectiveModuleVersion`, make at least - one existing successful tagged case supply the literal new module path - independently of `commandKitModulePath`. Otherwise a stale constant and its - self-referencing fixtures could agree while real version lookup fails. - Preserve all existing replacement/development cases and boundary assertions. -4. Update the root row in README's module table, current core imports and - installation guidance in `docs/consumers/guide.md`, affected developer and - internal guidance, example documentation, and GoDoc. Describe integrations - according to their implemented identity until their migration stages land; - keep the matched future set in migration guidance explicit. -5. Refresh `docs/releases/v0.3.0.md` against the full v0.2.0-to-candidate change: - aliases, reporting migration, completion, ReleaseKit maintenance, and the new - core import path. Explain consumer updates and the forthcoming matched - integration versions. Use current procedure URLs with immutable `v0.3.0` - source/licensing links. Keep the declared toolchains unchanged. -6. Format changed Go files. Review root-owned imports/identity literals and - module metadata; check affected prose links and whitespace. Run the existing - focused identity test with prepared caches: +## Stage 3: Update focused report and adapter coverage + +1. Extend `TestSourcesProjectNativeEvidenceInTextAndYAML` in `sources_test.go` + rather than building another report-test framework. Update fixtures and + assertions to the new native fields and report keys. Check that legacy + `destination_unresolved` and `version_check` keys are absent from emitted + source records; existing published history need not be scanned away. +2. Add controlled empty-import records to the source-reader fixture. Use + multiple records with distinguishable paths, selectors, and locations so + the test detects loss, reordering, or incorrect projection. Include a + source with nil version evidence and nonempty import records to cover the + text-writer conditional, and a source with no import records to verify `[]` + in both forms. Preserve the existing null/redacted version-evidence cases, + source order, zero-value coverage, and inventory-read count assertions. +3. Use the native `LayerMain` value in an appropriate fixture and verify that + returned source/explanation layer names are presented faithfully. Reuse + existing assertions where they already cover native origin projection; + do not add a separate test of ConfigKit's layer or provenance rules. +4. Keep existing tests of loader request forwarding, comparison coordination, + diagnostics, cancellation, error identity, output failures, and safe native + snapshot adaptation. Adjust removed APIs or intentionally changed report + expectations only. Do not rewrite behavior assertions merely to make an + unexpected regression pass. +5. Run the focused source tests with prepared dependencies, from ckconfig: ```sh GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \ - go test -mod=readonly -count=1 -run '^TestCommandKitBuildIdentityProjectsEffectiveModuleVersion$' . + go test -mod=readonly -count=1 -run '^TestSources' . ``` -**Stage result:** a reviewed core v0.3.0 candidate with the new identity, correct -component version lookup, migrated root consumers, and current release notes. -The full root suite belongs to Stage 2's normal publication workflow. +**Stage result:** durable coverage establishes CommandKit's new report +projection. The fake native inventory supplies evidence; tests do not establish +whether ConfigKit discovers imports, checks versions, matches records, or +classifies sensitive data correctly. -## Stage 2: Validate and publish core v0.3.0 +## Stage 4: Update current guidance and prepare the release note -**Completed.** Core `go.maximumdirect.net/commandkit v0.3.0` was published as -tag `v0.3.0` at candidate `e256eb1cc02a0c72c4e23c4967ed1caeaef17008`. -The ordinary Go 1.26.8 release workflow passed the complete root suite and -selected file checks before the successful source-tag push. +1. Update ckconfig README, GoDoc, and `examples/simple/README.md` for the new + dependency identity and Go minimum, and the planned ckconfig v0.3.0 with + core v0.3.0. Keep package/provider usage consistent with actual code. + Review maintained fixtures for source controls or removed APIs; migrate + genuine old controls where present, without changing application fields + merely because they have similar names. +2. Update `docs/cli.md`'s configuration-source section with the renamed keys, + main layer value, and `empty_import_selections` schema from Stage 2, + including the empty-list shape. Update origin-layer examples where they + describe adopted ConfigKit results. Retain existing command grammar, + formats, status behavior, and reduced comparison report. Use upstream terms + directly and link to the pinned upstream contracts for their semantics. +3. Update `docs/consumers/guide.md` and README's module-selection summary to + distinguish two cases: the newly prepared ckconfig v0.3.0 with ConfigKit + v1.1.0, and the existing matched ckconfig/ckprompt v0.2.0 pair. Do not imply + that ckprompt v0.2.0 composes with new ckconfig. Qualify upstream links where + ckconfig and unchanged ckprompt now use different ConfigKit versions. +4. Document the consumer migration: ConfigKit import/type identity, Go 1.27.0, + changed report keys, and added source evidence. Link to upstream migration + guidance for source-root `configkit` controls becoming `config`, import + requiredness/defaults, collection registrations/operations, removed public + APIs, and CLI-assignment order. Keep the detailed configuration reference + upstream rather than creating a parallel CommandKit contract. +5. In `docs/release.md`, select Go 1.27.0 as the maintainer toolchain and adapt + its existing install/download/PATH example. In that procedure and the + consumer guide, distinguish ckconfig's Go 1.27.0 minimum from core and + unchanged ckprompt's Go 1.26.0 minima. Keep ReleaseKit v0.9.0 and its + existing launcher, profiles, guards, publication, delivery, and recovery + workflow. This does not require code or profile changes. +6. Replace the development guide's unqualified three-module workspace advice + with interim guidance: preserve ignored workspace files and use + `GOWORK=off GOTOOLCHAIN=local` for preparation, suites, and example runs. + Explain that ckprompt's independent suite and composed example use its + published ckconfig v0.2.0 dependency; full local workspace composition is + pending the later ckprompt migration. Restore aligned workspace guidance + during that later work, including the workspace Go version as needed. +7. Create `integrations/ckconfig/docs/releases/v0.3.0.md`, subject to the + existing fresh-version selection, explaining the complete v0.2.0-to-candidate + changes and migration actions. End with `COPYRIGHT | LICENSE | ATTRIBUTION` + links to the corresponding module-local paths under + `https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/`. + Future tag links need not resolve before publication. Preserve old notes. -1. Review and commit the complete core candidate under the local commit policy. - Confirm that unrelated/private files and ignored workspaces are excluded. - The independently released integration sources may still declare old paths; - that does not make their suites a prerequisite for this root release. -2. From the repository root, execute the existing publication sequence within - the authorized release scope: +**Stage result:** current owners describe implemented adoption and the interim +module relationship; a checked-in candidate release note is ready. No deferred +feature, release publication, or external application migration is claimed. + +## Stage 5: Align module attribution with the actual selected graph + +1. From ckconfig, inspect `GOWORK=off GOTOOLCHAIN=local go list -m -json all` + after tidy. Compare it with the existing module attribution. ConfigKit's + own tool requirement does not select CommandKit's release tool: retain the + root-selected ReleaseKit v0.9.0 and inspect the effective transitive graph. +2. Update `integrations/ckconfig/docs/oss/attribution.md`'s ConfigKit entry to + `go.maximumdirect.net/configkit v1.1.0` and pinned commit + `191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9` on the new forge. Verify its + actual copyright, grant, license, and applicable notices. Reuse existing + complete standard license texts when they match the selected terms. +3. Remove/update entries for dependencies no longer selected or whose selected + versions changed; the baseline includes old-path ReleaseKit v0.4.1 and its + dependencies as well as vanity ReleaseKit v0.9.0. Follow the actual graph, + not a global old-host replacement or an assumption that every tool module + disappears. Keep the House Format and exact-revision notice/source links. +4. Core and ckprompt dependency selections remain unchanged. Preserve their + corresponding notices and published release records. Update shared material + only if its actual scope or selection changes; adoption alone does not + require revising unrelated grants or copying upstream policy documents. + +**Stage result:** ckconfig's notices correspond to its real selected modules, +with authentic source/license references and no unrelated attribution rewrite. + +## Stage 6: Validate the final state and finish the sprint + +1. Format changed Go files; inspect final diffs and module metadata. Confirm + ckconfig-owned Go imports use the vanity ConfigKit identity, the old + requirement is gone, its Go minimum is 1.27.0, core stays at v0.3.0, and no + local replacements/workspaces enter tracked module inputs. Confirm root + and ckprompt still have their existing module selections and Go minima. +2. Prepare any missing dependency caches for all three modules using normal + retrieval with workspace discovery off. On Go 1.27.0, run each independent + complete suite with read-only offline dependencies: ```sh - git push origin HEAD:refs/heads/main - ./scripts/release core v0.3.0 + GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \ + go test -mod=readonly -count=1 ./... + (cd integrations/ckconfig && \ + GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \ + go test -mod=readonly -count=1 ./...) + (cd integrations/ckprompt && \ + GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \ + go test -mod=readonly -count=1 ./...) ``` -3. Require the real selected-module suite and file checks to pass. Fix actual - failures in scope and commit the corrected candidate before retrying. On a - failed/ambiguous push, use the existing publication evidence and recovery - procedure. Do not force refs, bypass guards, or treat a local tag as publication. -4. Record the candidate commit, module path, full tag, validation outcome, and - confirmed source outcome here. A successful tag push completes this source - release; move to dependent preparation without waiting for hosted pages. + This includes ckconfig's maintained example tests. Record the unchanged + modules' results as validation of their own published dependency graphs, + not composition with local migrated ckconfig. Do not add a workspace shim + or change ckprompt to obtain a green three-module workspace. +3. Exercise the simple example's `config sources` text/YAML reports and its + existing fixture comparison with workspace discovery off. Use a controlled + native source fixture from Stage 3 for nonempty import evidence; a new + application import system or live service is unnecessary. Confirm only the + selected presentation and wiring behavior, not upstream domain correctness. +4. Check affected current documentation, local links/fragments, whitespace, + candidate note paths, attribution entries, and pinned-source provenance. + Ensure future behavior is not described as implemented, and distinguish + prepared v0.3.0 from a published release. Run `git diff --check` and the + staged counterpart, including intended new files in the review. +5. Record stage completion, final validation evidence, and the temporary + workspace mismatch in this plan. Mark the feature roadmap's implementation + status accordingly while leaving publication and external adoption pending. + Keep deferred capabilities in their owning record without starting them. +6. Review the worktree and staged changes, commit completed units under the + agent policy with concise messages, and finish with a clean worktree apart + from explicitly preserved unrelated work. Summarize the module/dependency + changes, report migration, tests, commits, and remaining ckprompt follow-up. + Do not publish; the normal selected-module release workflow remains the + owner of future candidate validation, guards, and publication outcomes. -**Stage result:** core v0.3.0 is source-published with -`module go.maximumdirect.net/commandkit`. Actual download of this version and its -sums is part of Stage 3, not a new completion gate for core publication. +**Stage result:** the selected ckconfig adoption is implemented, documented, +validated, committed, and prepared for a later release request. Intermediate +compile failures and deferred work are not substitutes for this final result. -## Stage 3: Migrate ckconfig and prepare its independent candidate - -**Completed.** Ckconfig declares `go.maximumdirect.net/ckconfig`, imports the -new core identity, and downloaded `go.maximumdirect.net/commandkit v0.3.0` -with authentic sums. The resolved graph retains ConfigKit v0.8.0 and selects -both the older ReleaseKit v0.4.1 and vanity ReleaseKit v0.9.0 tool modules; -module-local attribution and current guidance reflect those selections. The -v0.2.0 release note is prepared; independent suite validation follows. - -1. In `integrations/ckconfig`, migrate the module declaration to - `go.maximumdirect.net/ckconfig`. Update all owned imports, tests, and the - maintained simple example to that self-path and the new core path. Keep - package names and existing adapter behavior. -2. Replace its old core dependency key with the published new-path version. - From the ckconfig module directory, use: - - ```sh - GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckconfig -droprequire=gitea.maximumdirect.net/eric/CommandKit -require=go.maximumdirect.net/commandkit@v0.3.0 - GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0 - GOWORK=off GOTOOLCHAIN=local go mod tidy - ``` - - Perform source import migration before tidy to avoid resolving old imports. - Keep real downloaded sums. If retrieval is unavailable, resolve dependency - preparation before proceeding; do not fabricate metadata or substitute a - local replacement as final release evidence. -3. Inspect the actual direct and indirect graph, including tool requirements. - Preserve ConfigKit v0.8.0 and unrelated versions. Update affected notices in - `integrations/ckconfig/docs/oss/attribution.md` under the OSS policy using the - actual selected source revisions; add/retain applicable license texts. Do - not assume similarly named old/new upstream modules are interchangeable. -4. Prepare `integrations/ckconfig/docs/releases/v0.2.0.md` with product - `CommandKit ckconfig`, the new module/core paths, compatible dependency set, - and relevant reporting/completion migration. Immutable footer/source URLs - use the full tag `integrations/ckconfig/v0.2.0` and correct physical files. -5. Update README's ckconfig row, consumer module/import examples, the simple - example guidance, affected GoDoc, and relevant current release/development - references. Explain that applications moving to the new core identity also - use the matched new integration identity. -6. Format changed Go files. Review for stale owned imports/direct requirement - keys, accidental replacements/workspace files, and unexplained graph churn. - Check current links and whitespace. The owning complete suite runs in - Stage 4; a local workspace pass is not a substitute. - -**Stage result:** a ckconfig v0.2.0 candidate whose actual dependency is -downloaded `go.maximumdirect.net/commandkit v0.3.0`, with authentic metadata and -aligned current documentation/attribution. - -## Stage 4: Validate and publish ckconfig v0.2.0 - -**Completed.** `go.maximumdirect.net/ckconfig v0.2.0` was published as -`integrations/ckconfig/v0.2.0` at candidate -`92a327db9752e7a898d14f56e86fbdee027b3126`. The ordinary Go 1.26.8 release -workflow passed the independent suite, maintained example, and selected file -checks before the successful source-tag push. - -Review and commit the complete ckconfig candidate. From the repository root, -use the same authoritative-branch protocol as Stage 2: - -```sh -git push origin HEAD:refs/heads/main -./scripts/release ckconfig v0.2.0 -``` - -The normal release command must pass the independent ckconfig suite, including -its maintained example, with workspace discovery off and without dependency -redirection. It must also pass selected committed-file checks and publication -guards. Do not insert the earlier temporary Go shim or weaken a selected check. -Apply the existing failed/ambiguous-publication procedure if needed. - -Record the candidate, path, version, full tag, validation, and source outcome. -The intended tag is `integrations/ckconfig/v0.2.0`; the physical directory remains -`integrations/ckconfig` despite the short vanity module path. - -**Stage result:** compatible ckconfig v0.2.0 is source-published under its vanity -identity. Downloading it for ckprompt is the next module's preparation. - -## Stage 5: Migrate ckprompt and prepare its independent candidate - -**Completed.** Ckprompt declares `go.maximumdirect.net/ckprompt`, uses the -new core and ckconfig imports, and downloaded their v0.3.0 and v0.2.0 releases -with authentic sums. ConfigKit v0.8.0 and PromptKit v0.16.0 remain selected; -attribution records both distinct ReleaseKit tool modules in the resolved -graph. The v0.2.0 note and current consumer guidance are prepared; independent -suite validation follows. - -1. Migrate `integrations/ckprompt` to `go.maximumdirect.net/ckprompt`. Update its - owned source/tests and composed example to import the new core, ckconfig, - and ckprompt paths. Preserve PromptKit adaptation and reporting behavior. -2. From that module directory, replace both old CommandKit dependency keys: - - ```sh - GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckprompt -droprequire=gitea.maximumdirect.net/eric/CommandKit -droprequire=gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig -require=go.maximumdirect.net/commandkit@v0.3.0 -require=go.maximumdirect.net/ckconfig@v0.2.0 - GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0 go.maximumdirect.net/ckconfig@v0.2.0 - GOWORK=off GOTOOLCHAIN=local go mod tidy - ``` - - Migrate imports before tidy. Retain actual downloaded sums; resolve fetch - failures as preparation rather than masking them with local source. A new - core with old ckconfig v0.1.0 is the known incompatible combination. -3. Review graph changes while retaining ConfigKit v0.8.0 and PromptKit v0.16.0. - Update affected module-local attribution and immutable notice links based on - the resolved graph, including transitive tools. Keep actual upstream module - identities distinct from the three CommandKit identities being migrated. -4. Prepare `integrations/ckprompt/docs/releases/v0.2.0.md` with product - `CommandKit ckprompt`, new imports/dependencies, and consumer migration. - Footer/source links use full tag `integrations/ckprompt/v0.2.0` and physical - module-local files. Preserve the published v0.1.0 record. -5. Update README's ckprompt row, consumer composition/import examples, composed - example guidance, affected GoDoc, and remaining current module descriptions. - Keep URLs to hosted repository files separate from Go package links. -6. Format changed Go files and review remaining owned old-path imports or direct - requirement keys, metadata, links, and whitespace. Keep the ordinary source - checks intact; the independent suite runs in Stage 6. - -**Stage result:** ckprompt v0.2.0 composes the real new-path core and ckconfig -versions in its declared graph, with current guidance and authentic metadata. - -## Stage 6: Validate and publish ckprompt v0.2.0 - -**Completed.** `go.maximumdirect.net/ckprompt v0.2.0` was published as -`integrations/ckprompt/v0.2.0` at candidate -`3f1ed2f107d381530312a5f96e108444aec30c17`. The ordinary Go 1.26.8 release -workflow passed the independent suite, composed example, and selected file -checks before the successful source-tag push. - -Review and commit the complete ckprompt candidate. From the repository root: - -```sh -git push origin HEAD:refs/heads/main -./scripts/release ckprompt v0.2.0 -``` - -The normal publication workflow must pass the independent ckprompt suite and -composed consumer with actual downloaded predecessors, plus selected file and -publication checks. Preserve the offline/read-only suite environment and -ordinary recovery handling. No workspace or replacement shim supplies final -release evidence. - -Record its candidate, module identity, full tag -`integrations/ckprompt/v0.2.0`, suite outcome, and source-publication outcome. -Report any separate hosted delivery under its own outcome; page publication -is not required to establish dependency alignment. - -**Stage result:** all three matched source releases are published with vanity -module declarations and verified independent dependency graphs. - -## Stage 7: Audit the completed migration and record evidence - -**Completed.** The cumulative migration was reviewed: all three module -declarations, owned Go imports, examples, direct dependencies, and the core -build identity use the selected vanity paths. Physical module directories, tag -prefixes, Go minimums, ReleaseKit selection, scripts, profiles, and production -API shapes remain unchanged. Current guidance and module attribution reflect -the matched dependency graph; historical records remain intact. - -The source releases and their independent Go 1.26.8 publication suites are -recorded in Stages 2, 4, and 6. Earlier local-source diagnostics in the feature -roadmap were preparation evidence, not release validation. Hosted delivery is -separate and was not performed as part of this source migration. - -1. Review the cumulative diff against the feature roadmap. Confirm all three - module declarations, owned imports, examples, direct dependency keys, and - component build identity use the new paths. Preserve physical directories, - tag prefixes, root ReleaseKit selection, scripts/profiles, exported shapes, - Go minimums, and upstream versions apart from explained graph consequences. -2. Check that tests and current guidance use the new identities while historical - notes, accepted ADRs, and immutable source URLs retain their historical - meaning. Resolve current dependency-readiness claims that are now stale. - Do not mechanically rewrite every old-path reference in completed records. -3. Record each final candidate's exact commit, full tag, suite result, and - publication outcome. Identify diagnostic-only earlier evidence separately. - Reuse each successful publication suite for its unchanged candidate; do not - require another complete run just to finish this stage. Any later code or - metadata correction belongs in a new candidate/version under release policy. -4. Mark stages complete only with their stated evidence and update the feature - roadmap's status/link here. Preserve this record and prior immutable plans; - apply normal roadmap retirement only during later preparation. If publication - was outside the authorized implementation scope or could not finish, record - the actual prepared state and pending release stages rather than claiming - alignment is complete. -5. Review new evidence prose, links/fragments, intended staged files, and - `git diff --check` / `git diff --cached --check`. Commit any remaining - nonempty documentation unit with a short plain-English message, following - the local commit policy. Finish with a clean tracked worktree when only - planned work is present; preserve unrelated and ignored local files. - -**Stage result:** the implemented and published matched version set has accurate -source/validation evidence, current migration guidance, and committed tracking. -Source release and hosted-delivery outcomes remain separate. - -## Open Questions - -None required to choose the implementation. Vanity paths, target versions, -physical layout, dependency order, validation ownership, and compatibility scope -are selected in the roadmap. Publication authorization is an execution-scope -constraint, not a reason to invent different versions, fabricated sums, or a -local-only substitute for the target end state. +No required scope questions remain open. Routine implementation choices follow +the selected upstream contracts and the report shape fixed above; deferred +extensions do not need to be designed to complete this sprint. diff --git a/docs/roadmap/integration-dependency-alignment.md b/docs/roadmap/integration-dependency-alignment.md index d372bb8..a3aa849 100644 --- a/docs/roadmap/integration-dependency-alignment.md +++ b/docs/roadmap/integration-dependency-alignment.md @@ -1,7 +1,7 @@ # Integration dependency alignment and vanity-path migration Status: the vanity migration and matched source releases are complete. The -[implementation plan](implementation.md) records candidate commits, validation, +[completed implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/16584084b1b8a87dac959334ede8a47a8cfb8c0b/docs/roadmap/implementation.md) records candidate commits, validation, and publication outcomes; this roadmap retains the target and review history. ## Purpose and authority