From 1138960e9634001c88f8972b2cf96326b0b3baff Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 21:19:47 +0000 Subject: [PATCH] Retire the completed integration release records --- .../configkit-v1.4.0-promptkit-v0.24.0.md | 280 ----------- docs/roadmap/future.md | 24 +- docs/roadmap/implementation.md | 444 ------------------ docs/roadmap/remediation.md | 100 ---- 4 files changed, 6 insertions(+), 842 deletions(-) delete mode 100644 docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/remediation.md diff --git a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md deleted file mode 100644 index 0fea04b..0000000 --- a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md +++ /dev/null @@ -1,280 +0,0 @@ -# ConfigKit v1.4.0 and PromptKit v0.24.0 adoption - -Status: implementation complete; coordinated releases pending. Prepared 2026-11-21. -This document defines the desired target and accepted scope, not implemented -behavior or authorization to publish releases. The -[implementation plan](implementation.md) owns execution stages and completion -evidence. - -## Purpose and ownership - -Adopt the released upstream capabilities through the existing operator command -suite. `ckprompt` should neutrally expose PromptKit's public APIs, using the -implementation with the lowest conceptual complexity and the least -CommandKit-owned domain machinery. ConfigKit and PromptKit continue to own -loading, resolution, validation, preparation, inspection, and comparison. -Applications own construction, startup, credentials, and execution workflows. -Core owns shared CLI parsing, reporting, and delivery. - -For this adoption, minimize complexity borne by applications first, then -complexity maintained by ckconfig. These priorities take precedence over a more -tailored operator experience. Prefer native paths, whole-load evidence, and -existing outcome handling to extra machinery for more polished subtree reports. - -The [architecture policy](../policy/architecture.md) and -[integration ADR](../adr/0004-optional-integration-modules.md) govern these -boundaries. Native delegation preserves upstream meaning; it does not require -removing useful existing CLI projections, filters, or outcome handling. -This adoption introduces no additional ordering, copying, concurrency, -serialization-stability, or isolation guarantees. - -## Baseline and upstream targets - -Reviewed repository revision: `b1c7962f51eb9e81104a291bc1966a90b4e772a3`. - -| Component | Baseline | Adoption target | -| --- | --- | --- | -| CommandKit core | v0.7.0 | No core change required by this scope | -| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0, native scoped path enumeration, and a public native-inspection adapter | -| ckprompt | v0.10.0; PromptKit v0.23.2, ConfigKit v1.2.1, ckconfig v0.9.0 | PromptKit v0.24.0, ConfigKit v1.4.0, and the resulting released ckconfig | -| Go | Consumer minimum 1.27.0; release toolchain 1.27.4 | No change required by these upstream releases | - -Adoption covers the intervening ConfigKit v1.3.0 and PromptKit v0.23.3 changes. -Use the released versions, not unreleased upstream work. The reviewed release -commits are ConfigKit `4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3` and PromptKit -`5ea60e9b96651fd7dfcbc7d05b6f43d131df358f`. - -Upstream sources: - -- [ConfigKit v1.3.0: configured secrets bootstrap](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.3.0/docs/releases/v1.3.0.md). -- [ConfigKit v1.4.0: typed value access and focused inspection](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md). -- [PromptKit v0.23.3: timeout and cancellation identities](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/releases/v0.23.3.md). -- [PromptKit v0.24.0: shared loading, schemas, and preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/releases/v0.24.0.md). -- [PromptKit configuration migration](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md) - and [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md). - -The pre-adoption review used a temporary copy with only dependency declarations -and checksums updated. The ckconfig package and simple-example suites passed. -The ckprompt production packages built, but its test package failed to compile -because `constructor_outcomes_test.go` uses removed `WithSchemaFile`; seven -top-level composed-example tests failed with the old configuration layout. -An offline shared-load probe confirmed both automatic reporting of the new -prepared hash and repair budget, and the path-listing mismatch described below. -These observations establish migration work; they are not final acceptance -evidence for the implementation. - -## Targeted end state - -### One application-owned load, existing integration callbacks - -The maintained composed example demonstrates an application configuration with -`promptkit.Settings` under `promptkit`, rules composed with `promptkit.Configure`, -and a completed ConfigKit result passed directly to `promptkit.NewFromConfig`. -The application result serves configuration inspection and the engine serves -PromptKit commands through the existing loader callbacks and shared invocation -state. This removes the example's separate reconstruction and loading of -PromptKit configuration where the shared result supplies that information. - -The example should make source selection, campaign-derived settings, and -comparison sides understandable. Any reused result must correspond to the -requested selection and relevant application inputs; left and right comparisons -still receive their independently selected configurations. Reuse remains an -application choice, not a CommandKit cache or a new promise about load counts. -Preserve the meaningful selector and lifecycle demonstrations when restructuring -the example. - -Select `BundledOpenRouterUnderlay` before the application-owned load when the -example intends to include that catalog. `NewFromConfig` does not add it or -rerun configuration callbacks. `NewEngine` remains a supported standalone -construction path. No CommandKit constructor wrapper is needed for either path. - -`Result.Value` supplies trusted current Go values, potentially including resolved -secrets and shared references. It is not a replacement for safe inspection in -CLI reports. Continue to use upstream frozen, redacted evidence for configuration -output; the application's handoff follows upstream ownership semantics. - -### Native scoped inspection - -PromptKit's configuration inspection now focuses on `/promptkit`. Its -`HistoricalPaths()` enumerates that focus, while `Metadata()`, source evidence, -and explicit path queries retain whole-load context. For example, a load with -`app_name` and `promptkit` should not acquire `/app_name` in the PromptKit path -list merely because that path exists in the original load's metadata. - -Currently, [ckconfig's explanation handler](../../integrations/ckconfig/explain.go) -enumerates `View.Metadata.HistoricalPaths()`. The -[PromptKit adapter](../../integrations/ckprompt/adapters.go) supplies full metadata, -so this bypasses upstream's new focused enumeration. - -Provide the narrow capability needed for the shared handler to enumerate native -inspection paths. `ckprompt` supplies PromptKit's `HistoricalPaths()` directly; -ckconfig uses metadata to describe the returned paths' presence and explicitness. -Ordinary whole-result scopes continue to enumerate their native metadata paths. -The [implementation plan](implementation.md#stage-2-separate-native-path-enumeration-from-metadata-lookup) -selects the narrow provider extension and preserves existing custom-provider -behavior. This capability is not a parallel inspection model. - -Retain the existing CLI filters (`--under`, `--historical`, and `--explicit`) on -the supplied enumeration. Preserve native application paths, such as -`/promptkit/profiles/0/model`, without rebasing or adding compatibility aliases -for the former document layout. Explicit `--path` queries use upstream semantics, -including queries outside the focus where upstream supports them. Selecting a -scope is not an access-control boundary. - -Continue native comparison and source reporting. Do not filter away upstream -ancestor differences or trim the source catalog to manufacture isolation. -Focused rendering reports the selected subtree; explicit root queries retain -their native whole-document meaning. An absent effective subtree and explicit -null retain their upstream distinction and errors through the existing report -delivery mechanism. Do not invent an empty configuration to hide absence. - -### Public native-inspection adapter - -Include a reusable ckconfig adapter in this adoption and the next ckconfig -release. It registers a named configuration scope backed by ConfigKit's native -subtree inspection, reducing application wiring for effective settings, path -discovery, explanations, source evidence, and comparison. Applications retain -configuration acquisition and selection; the adapter supplies standard CLI -integration and delegates domain operations to ConfigKit. - -The adapter shares the native path-enumeration capability. The maintained -composed example demonstrates one application section, such as storage settings. -The section name is illustrative, not a new reserved scope. -Preserve load diagnostics and error evidence through existing reporting and -outcome conventions. A focused inspection does not independently validate a -subtree or make whole-load evidence local to it. - -Use a small sibling of `FromConfigKit`, with `FromConfigKitSubtree` as the planned -helper name. The application supplies a scope name and summary, an explicit -`configkit.Path`, and its existing typed loader returning -`(*configkit.Result[T], error)` with the same context, selection, input, and state -parameters as `FromConfigKit`. The helper returns the existing `Scope[I, S]`. -Applications need not assemble diagnostic bundles, translate errors, or create -an intermediate inspection representation. - -The adapter obtains source and diagnostic evidence from the result and selects -the native view with `InspectSubtree(path)`. For comparison, it acquires each -side's result, selects the same subtree, and calls native `Inspection.Diff`. -Share existing acquisition and diagnostic/error handling where useful without -introducing a general framework solely to remove repeated lines. - -Retain whole-load diagnostics and validation outcomes. Successful loads with -warnings remain usable; detailed validation retains native findings and sources -through the existing presentation conventions. On failed loading, preserve -available ConfigKit load-error evidence and supported error identity. Other -application errors remain errors without invented ConfigKit findings. Reuse -existing classification and duplicate-presentation handling; do not silently -filter evidence to the selected subtree, ignore failures elsewhere in the load, -or create an independent subtree-validation result. - -This release targets exposing a section from an ordinary typed application -result. An additional entry point for already selected inspection views and -accommodation of different root Go types across comparison sides are outside -this adoption. An options framework is unnecessary for the single path argument. - -PromptKit uses the shared inspection capability directly. It need not pass -through this new helper if that would require converting its public inspection -type merely to fit the helper. The accepted API and evidence direction is recorded -in OD-2 below; the [implementation plan](implementation.md) owns the exact -declaration and internal factoring within that direction. - -### Existing commands expose the new upstream evidence - -| Operator task | Existing command | Adoption behavior | -| --- | --- | --- | -| Inspect a prompt's output contract | `promptkit show prompt ID` | Report native inline schema or schema references and resolved repair budget, including zero | -| Preview the completed request | `promptkit show prepared ID` | Report native `message_content_hash`, resolved contract, and prepared schema evidence without model execution | -| Discover inputs or validate a request | `promptkit requirements show ID`, `promptkit requirements validate ID` | Preserve upstream effective requirements, including application defaults, and current preparation/error semantics | -| Inspect configuration and provenance | `config show`, `sources`, `explain`, `diff`, `validate` with `--scope promptkit` | Use native focused inspection and retain supporting whole-load evidence | -| Exercise native smoke checks | `promptkit test ...` | Continue forwarding selected requests and presenting native evidence and errors | - -Prompt and prepared reports already hand native values to the core reporter. -Keep that path so new fields appear without a second renderer or a local hash -implementation. Existing projections, such as requirements reports, should retain -the meaning of the updated native results. Hash semantics, schema resolution, -repair behavior, and error identities remain upstream-owned. - -## Compatibility and delivery - -The adopted configuration uses native `/promptkit` locations for complete -settings documents and inspection paths; resource IDs retain their names. -Wrapperless fragments and collection fragments use the corresponding upstream -input helpers. Removed schema options are replaced by supported inline, -source-relative, or explicit-root selection. The upstream migration and format -references above own their exact rules. Successful construction alone is not -migration evidence: old root-level resources can become application data while -disappearing from PromptKit catalogs. - -Request builders use the upstream input contract for validation replacements, -including optional repair budgets. Native resolved repair budgets, including -zero, and schema/hash evidence reach reports without a local substitute. -The upstream enabled repair default may add a generation call, latency, and -usage to application execution. Applications retain resource-version policy and -sensitivity decisions for their extension fields. The adoption also retains the -intervening PromptKit timeout and cancellation identity corrections. - -Canonical GoDoc, CLI, consumer, developer, internal, and candidate release -guidance should agree with the completed integration. The maintained composed -example demonstrates shared loading and the native subtree adapter. Validation -protects CommandKit's acquisition, selection, adaptation, reporting, and outcomes; -upstream libraries own validation of their domain algorithms. Tests remain -offline and credential-independent. - -The independently versioned integration releases explain the changed provider -API and breaking PromptKit migration under the [release policy](../policy/release.md). -The coordinated target is released ckconfig followed by ckprompt selecting that -release, with the downstream integration advancing at least its minor version. -The [release runbook](../release.md) owns preparation and publication operations. -Local workspace validation and isolated checks with a local dependency are -identified separately from independent validation against released requirements. -Any remaining release coordination stays recorded until completed. - -No core release is needed solely for this adoption. Unrelated core work, -including the optional Scriptorium proposal, is not a prerequisite. The -[implementation plan](implementation.md) owns dependency migration, focused -coverage, candidate preparation, validation commands, and completion records. - -## Scope retained outside this adoption - -The existing [future work record](future.md) retains output-contract override -flags, appended-message flags, secrets-bootstrap commands, and other deferred -capabilities. ConfigKit v1.3.0's configured bootstrap and overwrite options remain -available to application startup code without a new CommandKit command. -This roadmap selects no new commands, engine-construction convenience API, -automatic configuration migration, core cache, or application execution workflow. -These are scope decisions for this adoption, not additional permanent prohibitions. - -## Resolved decisions - -### OD-1: Include the native-inspection adapter in this adoption — closed - -Include the helper in the next ckconfig release, as part of this roadmap. -Its implementation overlaps the required native enumeration work; designing both -together provides a concrete second use of the shared boundary and avoids -revisiting that boundary immediately after release. Keep the adapter focused on -standard CLI scopes and direct upstream inspection. Preserve native comparison -semantics for the views accepted by the selected API. - -The previous deferral recommendation is superseded. - -### OD-2: Typed result loader, subtree path, and existing evidence handling — closed - -Adopt the result-loader-plus-path approach described under -[public native-inspection adapter](#public-native-inspection-adapter). -Prioritize application simplicity, then ckconfig implementation simplicity, over -tailoring the inspection command's presentation. The complete result already -supplies source and diagnostic evidence; accepting the application's ordinary -loader avoids a new handoff envelope or application-owned adaptation layer. - -Use native paths and comparison, retain whole-load diagnostics and failures, -and reuse existing reporting and outcome conventions. Keep the helper focused -on the selected task; do not add an options framework or another entry point for -arbitrary inspection views in this adoption. Supporting preselected views and -different root types would require a broader acquisition handoff and is not -needed for the selected application workflow. - -## Execution status - -The [staged implementation plan](implementation.md) records the completed local -work and validation evidence. The coordinated integration releases remain pending -as recorded in [future work](future.md#pending-integration-release-coordination). diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 758a5b4..0649476 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -1,7 +1,6 @@ # Future work -Status — integration release coordination, optional shell validation, and future -capability proposals. +Status — optional shell validation and future capability proposals. No delivery dates are selected here. ## Purpose and authority @@ -38,22 +37,11 @@ govern any future implementation. The [CLI reference](../cli.md), public GoDoc, and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining an idea here does not select its syntax, API, priority, or delivery date. -## Pending integration release coordination - -The ConfigKit v1.4.0 and PromptKit v0.24.0 adoption is implemented locally; -publication remains separate. Follow the [release procedure](../release.md) -and obtain the required publication authorization. Prepare and release ckconfig -v0.10.0 first. Then select that actual release in ckprompt, tidy with real -checksums, update matching-version attribution, and run ckprompt's independent -default suite before preparing its v0.11.0 release. Core remains v0.7.0 for this -adoption. Candidate notes and planned versions must be checked again at release -time. Hosted delivery is separately authorized. - -The current ckprompt checkout still requires published ckconfig v0.9.0, which -lacks the new path-reader API. Its aligned workspace and isolated local-replace -tests passed; those checks do not establish an independent build against the -published requirement. See the [implementation record](implementation.md) for -the validation evidence and upstream missing-file error-identity limitation. +The completed ConfigKit v1.4.0 and PromptKit v0.24.0 adoption, audit remediation, +and coordinated integration releases are preserved in the +[release snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/54e951e38a404b4338c7967ac39c6c01159bf76d/docs/roadmap). +ckconfig v0.10.0 and ckprompt v0.11.0 were published with hosted release pages; +ckprompt passed its independent suite against released ckconfig v0.10.0. ## Optional verification diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 8b9f590..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,444 +0,0 @@ -# ConfigKit and PromptKit adoption implementation plan - -Status: implementation complete; coordinated releases pending. Prepared 2026-11-21. -Implementation baseline: `320526d3fc92fac7795b4b5e65c623181680452d`. - -## Authority and execution - -Implement the accepted [feature roadmap](configkit-v1.4.0-promptkit-v0.24.0.md) -in the numbered order below. That document owns intent, scope, upstream targets, -and resolved decisions. This plan selects the API shape, implementation steps, -and completion evidence for a Luna coding agent. - -Read [development guidance](../development.md), the applicable policies in its -reading guide, and ADRs [0003](../adr/0003-configuration-scopes.md) and -[0004](../adr/0004-optional-integration-modules.md). Prefer the codebase knowledge -graph for code discovery. Inspect the actual worktree before editing and preserve -unrelated work, ignored workspace files, and local credentials. - -This is one end-to-end implementation sprint. Continue through all stages without -intermediate approval or compilation gates. Earlier stages may temporarily fail -to build while later migrations are pending. Resolve failures before declaring -the implementation complete. After a focused unit is complete, record its actual -evidence here and commit it under the [agent policy](../policy/agents.md). -Do not create empty commits or claim checks that have not run. - -Implementation approval authorizes the implementation and local commits. Source -publication and hosted delivery follow the [release procedure](../release.md) -when separately authorized. Publication is follow-up coordination, not an internal -gate in this sprint. Stage 7 defines honest pre-publication validation when -ckprompt needs the new, still-unpublished ckconfig API. - -Use the existing command families, reporters, classification, and provider -lifetimes. Keep domain resolution, schemas, validation, preparation, redaction, -and comparison upstream. Do not add a core cache, new commands, constructor -wrapper, arbitrary-view adapter, cross-root-type loader API, or options framework -for this adoption. The roadmap's scope choices do not establish permanent bans. - -## Stage 1: Select the released upstream dependencies - -Status: complete. - -Evidence: With Go 1.27.4 and the workspace disabled, selected the specified -versions using `go get`, ran `go mod tidy` and `go mod download` in both -integrations, and reviewed the module graphs, checksums, and selected upstream -copyright and license material. The upstream license texts match the previously -selected versions; the remaining selected transitive versions are unchanged. -Updated both integration attribution entries. The existing workspace includes -all three modules. The independent ckconfig suite passed. The ckprompt suite -currently fails on removed `WithSchemaFile` and unmigrated composed-example -resources; those migrations are assigned to Stages 4 and 5. - -1. With Go 1.27.4 on `PATH`, update ConfigKit to v1.4.0 in both integration - modules and PromptKit to v0.24.0 in ckprompt. Keep core v0.7.0, the root - module's requirements, and the consumer minimum of Go 1.27.0 unless an actual - dependency requirement demonstrates a necessary change. -2. Prepare dependencies from each integration directory using `GOWORK=off - GOTOOLCHAIN=local go get` for these exact versions, then download/tidy actual - dependencies and review the resulting requirements and checksums. Leave - ckprompt's ckconfig requirement at published v0.9.0 until the new ckconfig - is published. Do not record a fictitious future checksum or commit a local - replacement to make the new API appear published. Repeat tidy after source - migration if temporary compilation errors prevent it now. -3. Use the existing ignored workspace containing the root and both integrations - for development. Preserve it, or create it following the developer guide if - absent. Do not depend on sibling upstream checkouts. -4. Review the selected upstream license and notice material and update affected - module-local and root attribution entries under the [OSS policy](../policy/oss.md). - ConfigKit's selected source is `4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3`; - PromptKit's is `5ea60e9b96651fd7dfcbc7d05b6f43d131df358f`. Update changed - transitive entries only where the selected graphs warrant it. Finalize graph - and notice review after the migrations; no unrelated dependency sweep. - -Completion evidence: reviewed integration module diffs and genuine sums selecting -the two target releases. Record any temporary test/build failures as migration -work for subsequent stages, not reasons to stop. - -## Stage 2: Separate native path enumeration from metadata lookup - -Status: complete. - -Evidence: Added the optional native path reader and metadata fallback, populated -whole-result views, and exercised selected candidates, empty readers, the legacy -fallback, and discovery filters alongside existing missing-metadata coverage. -`GOWORK=off GOTOOLCHAIN=local go test ./...` passed in ckconfig with Go 1.27.4. - -Primary files: [contracts.go](../../integrations/ckconfig/contracts.go), -[explain.go](../../integrations/ckconfig/explain.go), and -[configkit_adapter.go](../../integrations/ckconfig/configkit_adapter.go). - -1. Add this narrow public capability alongside the existing reader interfaces: - - ```go - type PathReader interface { - HistoricalPaths() []configkit.Path - } - ``` - - Add `Paths PathReader` to `View`. It supplies the native discovery candidates. - `Metadata` continues to supply presence, explicitness, and history. Update - GoDoc for `View`, `PathReader`, and `ScopeFeatures.PathDiscovery` together. -2. In `runConfigExplanation` listing mode, retain the metadata requirement. - Enumerate `View.Paths.HistoricalPaths()` when `Paths` is nonnil; otherwise - enumerate `View.Metadata.HistoricalPaths()` for existing custom providers. - A nonnil reader returning nil or an empty slice means an empty native list, - and must not trigger the fallback. Apply the existing `--under`, - `--historical`, and `--explicit` filters to those candidates using metadata. - Keep explicit-path handling on `ExplanationReader`. -3. Populate whole-result `FromConfigKit` views with their metadata as the path - reader. Keep native paths and existing report projection. This change does - not require new sorting, deduplication, path rebasing, or metadata copying. -4. Extend existing discovery tests with a reader whose candidates exclude a - real metadata sibling, a valid empty reader, and the legacy nil-reader - fallback. Exercise the existing filter meanings on supplied candidates. - Retain missing-metadata failure coverage instead of creating a second path - metadata model. - -Completion evidence: focused ckconfig discovery coverage proves that enumeration -comes from the supplied capability while metadata still describes each path. -Existing whole-result discovery remains supported. - -## Stage 3: Add the typed-result subtree scope adapter - -Status: complete. - -Evidence: Added the typed loader and native subtree adapter, sharing acquisition -and comparison coordination with the whole-result adapter. Offline scope and CLI -tests cover focused output and paths, explicit outside-focus explanations, -whole-load warnings and failures, error identity, absence and null, unavailable -inspection, and native comparison including an atomic ancestor. The independent -ckconfig suite passed with Go 1.27.4 and `GOWORK=off GOTOOLCHAIN=local`. - -Add the following public sibling of `FromConfigKit` in the ckconfig package: - -```go -func FromConfigKitSubtree[I, S, T any]( - name, summary string, - path configkit.Path, - load func(context.Context, Selection, I, S) (*configkit.Result[T], error), -) Scope[I, S] -``` - -1. Declare the same operations and path features as `FromConfigKit`. Retain its - application-owned loader, input/state, selection, and operation-list - customization conventions. Attach a nil-loader construction error with - `WithScopeError`; declaration/help/discovery must not invoke loading. -2. Share ordinary result acquisition and diagnostic adaptation with - `FromConfigKit` through a small private helper. Preserve the existing - handling of `LoadError`, nonnil results accompanying other errors, nil-result - failures, findings, sources, and terminal explanations. A successful result - remains the source of whole-load diagnostics. Do not expose a new envelope - or callback framework to applications. -3. After successful loading, call `result.InspectSubtree(path)`. Use the returned - inspection for `Effective`, `Explanation`, and `Paths`, and its whole-load - metadata and sources for the corresponding fields. Keep `Findings` from the - result. If selection returns `false`, return a contextual operational error - with the already acquired source/diagnostic evidence. This covers invalid - paths and results without captured inspection. Do not classify an unavailable - view as invalid user configuration without supporting native evidence. -4. A valid absent scope is a successful acquisition, not an unavailable view. - Let its native writer report an unavailable effective value through existing - show/render delivery handling. Preserve explicit null. Explicit queries, - including root and paths outside the focus, continue to use native semantics. -5. Reuse `loadComparisonSide` and the existing pair-loading cancellation and - diagnostic accumulation conventions. Extract the common pair-acquisition - portion privately if needed to avoid duplicating that coordination. Select - the same path from both successful results and call `leftView.Diff(rightView)`. - Preserve existing left/right selection inputs, shared state, warnings, - explanations, cause wrapping, and checks before the next acquisition or diff. - Do not filter native ancestor differences or compare rendered YAML. - Keep ordinary `FromConfigKit` on its existing same-type `configkit.Diff`. -6. Add focused public-scope/CLI coverage, using real offline ConfigKit results: - focused show/list/explain with a sibling outside the focus; native diff with - distinct selections; whole-load warnings and failed-load findings outside - the focus; and error identity/outcomes for loader failure. Reuse existing - evidence and delivery tests where they already protect the shared path. - Cover valid absence versus null and unavailable inspection without building - an upstream inspection conformance suite. Compare representative diff values - to native results, including a retained atomic ancestor where applicable. - -Completion evidence: standard scope commands expose a native subtree using only -the ordinary typed loader and path. Whole-load failures remain failures and -available evidence survives adaptation. Exported GoDoc describes this handoff. - -## Stage 4: Migrate ckprompt adapters, fixtures, and boundary coverage - -Status: complete. - -Evidence: Migrated discovered settings fragments to `/promptkit`, exposed native -inspection paths, and added shared-load, requirements, schema, prepared-hash, -and request-replacement coverage. `GOTOOLCHAIN=local go test -./integrations/ckprompt` passed in the aligned workspace with Go 1.27.4. The -missing-main-file constructor retains PromptKit's invalid-config identity and -produces an operational outcome with native load diagnostics. ConfigKit's -`LoadError` explicitly does not unwrap underlying filesystem errors, so this -native error cannot also match `os.ErrNotExist` as originally anticipated; -the separate joined-error case verifies forwarding of that identity when supplied. -The composed example migration remains in Stage 5. - -Primary files: [adapters.go](../../integrations/ckprompt/adapters.go), the -integration's existing configuration/comparison/preparation/requirements tests, -and [constructor outcomes](../../integrations/ckprompt/constructor_outcomes_test.go). - -1. Set successful `ConfigScope` views' `Paths` directly to PromptKit's native - `ConfigurationInspection`. Retain its native effective writer, explanation, - full metadata, sources, diagnostics, and native comparison. Do not convert - it into a ConfigKit result to route it through the new adapter. -2. Migrate complete-document test/configuration mappings beneath `promptkit`. - Mount wrapperless fragments through `SettingsInput`, and collection fragments - through `CollectionInput`. Discovery-produced fragments require an explicit - destination when they are not whole documents. Update override paths, - explanation assertions, and comparison paths to native locations such as - `/promptkit/profiles/0/model`; resource IDs and references retain their names. - Review inline maps, byte strings, embedded files, and filesystem fixtures, - not just YAML files. In particular review composition and comparison fixtures. -3. Replace any `Config.SchemaDir`, `WithSchemaFS`, or `WithSchemaFile` uses with - the selected release's supported schema configuration/resource contexts. - In `TestPromptConstructorFailurePrecedence`, replace the missing-schema - constructor with a missing main configuration file passed to `NewEngine`. - Retain the intended operational outcome and `os.ErrNotExist`/PromptKit cause - identity checks, plus joined-error and cancellation precedence. Retain the - real malformed companion-YAML regression and its structured load evidence. - Schema-file failures now belong to preparation, so exercise their forwarding - there only where needed to protect a distinct adapter path. -4. Migrate request-builder replacements to `*promptkit.OutputContractInput` - wherever used. Forward the whole replacement with pointer-valued repair - budgets; omitted stays omitted and explicit zero stays zero. Do not insert - the former repair default. Keep ordinary `OutputContract` uses for resolved - prepared results where that is the upstream type. -5. Keep prompt and prepared values on the existing native reporting path. - Extend focused report tests to compare native returned inline/reference - schema fields, repair-budget zero, and `message_content_hash` with CLI report - values. Preserve text/JSON/YAML behavior through shared serialization tests - and a small representative format selection, not an exhaustive cross-product - of fields and formats. Do not calculate expected hashes locally. -6. Verify requirements projections preserve the native result, including input - metadata supplied by application defaults. Keep preparation, validation, - namespace, smoke, cancellation, diagnostic, and outcome adaptation semantics. - Use existing boundary tests for supported error identities; PromptKit owns - tests of its v0.23.3 HTTP timeout/cancellation algorithms. -7. Add a shared-load fixture with a genuine application sibling outside - `/promptkit`. Through `ConfigScope`, prove list candidates follow native - `HistoricalPaths`, filters still apply, explicit outside-focus paths retain - native behavior, and full source/diagnostic evidence remains available. - Expected values come from native inspection rather than a local scope filter. - -Completion evidence: migrated ckprompt package coverage passes in the aligned -workspace and resource-selection assertions detect silently unmigrated catalogs. -The composed example is completed in Stage 5. - -## Stage 5: Demonstrate shared loading and the subtree adapter - -Status: complete. - -Evidence: The composed example loads application defaults, bundled and local -resources, campaign-derived settings, and storage in one ConfigKit result; -the engine consumes that result and the storage scope uses the subtree adapter. -Updated fixtures and tests exercise native paths, shared inspection and reuse, -storage show/explain/diff and overrides, whole-load failure evidence, and the -existing campaign, comparison, catalog, and lifecycle cases. With Go 1.27.4, -`GOTOOLCHAIN=local go test ./integrations/ckprompt/examples/composed` passed in -the aligned workspace. - -Update the maintained [composed example](../../integrations/ckprompt/examples/composed/main.go), -its fixtures, and its existing tests. A separate consumer example is unnecessary. - -1. Add `PromptKit promptkit.Settings` with `yaml:"promptkit"` to - `appConfiguration`, plus an illustrative typed `storage` section. Keep the - existing campaign data, selector presence, request-builder, session outcome, - alias, completion, and injected-client demonstrations. -2. Move the example's generated resources into the application load. Compose - its definition using `promptkit.Configure` with the settings selector. - Supply the existing local collection and common prompt resources as an - application-owned mapping underlay beneath `promptkit`, so selecting a main - fixture retains the example resources. Keep application defaults in the - application definition. Retain the example's bundled OpenRouter catalog - by selecting `BundledOpenRouterUnderlay()` before this load, once in its input - composition. Engine construction must not perform a second configuration load. -3. Derive campaign-specific profiles and prompt defaults during the application - definition's resolve callback, before PromptKit's composed resolve callback. - Use ConfigKit's resolution recording helpers for changes, with native - `/promptkit/...` paths and relevant campaign dependencies. This keeps frozen - inspection and engine settings consistent. Do not mutate the completed - result's settings to inject a campaign before handing it to the engine. - Preserve existing campaign selection and override precedence, including - explicit empty selections and native conflicting-override errors. -4. Keep `loadApplicationConfig` as the ordinary result loader, retaining its - application-owned successful-result reuse keyed by the full selection and - campaign presence/value. Keep failed loads out of that reuse. In - `loadPromptEngine`, pass that result directly to `promptkit.NewFromConfig` - with `RuntimeConfig` and the existing injected LLM client. Remove the separate - PromptKit source reconstruction and `NewEngine` call from this shared path. - Keep standalone `NewEngine` fixtures elsewhere as supported usage. -5. Register a `storage` scope with `FromConfigKitSubtree`, the existing result - loader, and `configkit.Keys("storage")`. Enable overrides for this scope - because that loader supports them. Apply the existing campaign selector and - its comparison counterpart to this scope as well; retain the app-only limit - selector and input checks. Keep PromptKit scope capability declarations at - their existing supported settings; shared loading itself does not require - expanding its advertised override modes. -6. Give before/after fixtures distinct storage values while retaining campaign - differences. Extend existing tests to demonstrate subtree show/explanation - and comparison through the standard commands and available failed-load - diagnostics. Use package-level adapter tests for the fuller evidence matrix. - Update `--scope all` expectations to include the new application scope and - the fact that the `app` whole-result view now includes PromptKit settings. -7. Retain tests distinguishing left/right configuration, campaigns, overrides, - and repeated invocation state. Confirm help/completion do not acquire an - engine, catalogs still contain selected IDs, and preparation does not call - the LLM client. Smoke examples use the existing local injected client. - Test successful reuse as example behavior, without creating a library-wide - exact-load-count contract or redesigning its small cache. - -Completion evidence: existing composed-example coverage plus focused subtree -cases passes offline. Both scope adapters consume the same application-owned -result for corresponding selections, and comparison sides remain independent. - -## Stage 6: Update canonical guidance and candidate release notes - -Status: complete. - -Evidence: Updated GoDoc, CLI, consumer, development, internal, and composed -example guidance, plus candidate notes for ckconfig v0.10.0 and ckprompt -v0.11.0. Neither candidate tag exists locally or on `origin`. Reviewed selected -module graphs and upstream license material; affected attribution was updated -in Stage 1 and no transitive version changed. Local Markdown links and fragments -passed a repository link check, `git diff --check` passed, and the ckprompt -workspace suite including the example passed with Go 1.27.4. Publication and -the ckprompt released-dependency update remain pending. - -1. Finish exported GoDoc and package guidance in both integrations. Document - `View.Paths` precedence and metadata fallback, the subtree helper signature, - typed loader ownership, whole-load validation/evidence, and native path/diff - behavior. Keep exact upstream format rules linked to the selected releases. -2. Update [CLI guidance](../cli.md) for native scoped listings and explicit paths, - focused rendering, source evidence, and comparison. Update the - [consumer guide](../consumers/guide.md) with the maintained shared-load and - storage-scope example, upstream migration links, and request-builder changes. - Update [development guidance](../development.md) and internal documentation - where the changed mechanics affect them. Describe the local development - dependency state accurately until release coordination is finished. -3. Write candidate notes for ckconfig v0.10.0 and ckprompt v0.11.0. These are the - next minor targets from the reviewed v0.9.0/v0.10.0 baselines. Check existing - notes/tags before creating them; if another release has consumed either - target, use the next appropriate fresh minor and adjust candidate references. - The release command performs authoritative publication guards later. -4. The ckconfig note covers the new adapter and optional reader. Adding a public - `View` field can require migration of positional struct literals; recommend - keyed fields and explain the metadata fallback for existing custom scopes. - The ckprompt note covers the upstream breaking configuration/API migration, - native path changes, removed schema options and explicit schema roots, - `OutputContractInput`, resolved repair-budget zero/defaults, new prepared - evidence, and whole-load context. Mention possible extra generation latency - and usage from upstream's enabled repair default. Include positional - `PreparedRun` literal migration and older JSON's missing-hash behavior where - relevant, linking upstream for its exact contract. -5. Preserve upstream ownership of resource-version policy and extension-field - sensitivity. Keep unrelated deferred CLI capabilities in `future.md`. - Add the required module-specific immutable release footer to each candidate - note. Do not rewrite previously published notes or tags. -6. Finalize affected attribution against the selected module graphs. Review prose - diffs, local links/fragments, copied notices, commands, examples, and future - tag URL paths under the documentation/OSS policies. Published compatibility - tables must distinguish available releases from these candidates. - -Completion evidence: canonical guidance and candidate notes agree with the -implemented APIs and examples, have valid local navigation, and describe the -remaining dependency release coordination without claiming publication. - -## Stage 7: Validate the result and record release coordination - -Status: complete. - -Evidence: With Go 1.27.4, `GOWORK=off GOTOOLCHAIN=local go test ./...` -passed separately in core and ckconfig; ckconfig `go mod tidy` and `go mod -download` completed without further changes. From the root, the aligned -workspace commands `GOTOOLCHAIN=local go test ./...`, `go test -./integrations/ckconfig/...`, and `go test ./integrations/ckprompt/...` all -passed. For isolated ckprompt validation, copied its module files to a temporary -directory, replaced ckconfig with the local module only in that temporary -modfile, ran tidy and `GOWORK=off GOTOOLCHAIN=local go test -modfile=... ./...`, -and removed the temporary files; both package and example passed. This is not -independent validation against the published ckconfig v0.9.0 requirement. -Reviewed the module and attribution diffs, focused evidence, prose whitespace, -and local links and fragments. No core optional dependencies were introduced. -The remaining release order and dependency validation are recorded in -[future work](future.md#pending-integration-release-coordination). The Stage 4 -record explains the upstream missing-file error-identity limitation. - -1. Format changed Go files, finish tidy/download with the workspace disabled - where the module can resolve its selected APIs, and inspect all module and - attribution diffs. Keep downloaded checksum evidence real. Root should not - acquire optional integration dependencies. -2. With Go 1.27.4 selected, run the complete affected independent/default suites - and the aligned workspace suites. From the root, use these commands: - - ```sh - (cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test ./...) - GOTOOLCHAIN=local go test ./... - GOTOOLCHAIN=local go test ./integrations/ckconfig/... - GOTOOLCHAIN=local go test ./integrations/ckprompt/... - ``` - - Run ckprompt's ordinary independent suite once its required ckconfig release - is selected. Before publication, that suite cannot resolve the new API from - its v0.9.0 requirement. For isolated development validation, copy - ckprompt's `go.mod` and matching `go.sum` to a temporary directory, add a - temporary `replace go.maximumdirect.net/ckconfig => ABSOLUTE_LOCAL_CKCONFIG` - with `go mod edit -modfile=...`, and run tidy and `GOWORK=off GOTOOLCHAIN=local - go test -modfile=... ./...` from the ckprompt directory. Remove the temporary - files afterward. Label this result as isolated validation against local - ckconfig, not independent validation against its published requirements. - Do not block subsequent sprint work on the publication dependency. -3. Review focused evidence from Stages 2–5 against the roadmap's targeted end - state. Reuse successful checks for unchanged content. No performance - benchmarks, live provider calls, new CI gates, or mandatory expanded matrices - are needed for this adoption. Investigate concrete failures and rerun the - affected checks after fixes. -4. Run prose whitespace checks and validate affected local links/fragments, - including new notes. Review intended new files as well as tracked diffs. - Record actual commands, outcomes, and any remaining independent-dependency - limitation here; do not mark unrun checks passed. -5. Record pending release coordination in `future.md` before retiring any - completed planning records. Keep this plan's implementation completion - separate from publication status. The follow-up order is ckconfig first, - then ckprompt with that actual released ckconfig selected, real sums/tidy, - updated matching-version attribution, and its independent default suite. - Core remains v0.7.0 for this scope. Follow the runbook for candidate commits, - authorized pushes/tags, and separately authorized hosted delivery. The release - command runs candidate validation itself; no duplicate mandatory preflight. -6. Review and commit the completed implementation units and records under the - agent policy. Report changed APIs and migration requirements, tests and their - limits, commit identifiers, and the pending coordinated integration releases. - Do not pause midway for an approval already covered by implementation scope. - -Completion evidence: all implementation-stage work is finished, focused and -workspace checks pass, ckconfig passes independently, documentation is validated, -and any ckprompt published-dependency validation still awaiting release is -explicitly recorded. Eventual adoption completion includes both coordinated -releases; this sprint does not claim that follow-up has occurred. - -## Open Questions - -None. The feature roadmap resolves product scope and adapter direction; this -plan selects the remaining API, migration, example, and validation approach. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md deleted file mode 100644 index aedd63c..0000000 --- a/docs/roadmap/remediation.md +++ /dev/null @@ -1,100 +0,0 @@ -# ConfigKit and PromptKit adoption review - -Reviewed revision: `e70a0ef301a3d34f64a6cba86dd68b728436534d`. -Status: all findings addressed. Reviewed and remediated 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. The campaign prompt-ID defect identified in R1 has been corrected. | -| 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: completed 2026-11-21. - -Completion: the resolver now records prompt-ID normalization at the collection -path, retaining the existing reason and campaign dependencies. Added -`TestComposedCampaignPromptID` for a main configuration selecting `custom`; -it verifies successful loading, matching application/engine inspection values, -and the selected ID in the CLI catalog. The test failed before the fix and -passed afterward. The original override reproduction also now succeeds. - -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). - -At review time the R1 reproduction failed despite those passing suites; the -review itself changed no production code or tests. - -After remediation, `GOTOOLCHAIN=local go test ./integrations/ckprompt/... --count=1` passed with Go 1.27.4, including the composed example and regression. -The isolated ckprompt suite with a temporary local ckconfig replacement also -passed. The original override command now reports a valid app scope and exits -successfully. The published-dependency release coordination remains unchanged.