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 index 5220ef5..3c4842d 100644 --- a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md +++ b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md @@ -1,8 +1,10 @@ # ConfigKit v1.4.0 and PromptKit v0.24.0 adoption Status: agreed adoption direction; implementation pending. Prepared 2026-11-21. -This document defines the target and remaining work, not implemented behavior -or authorization to publish releases. +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 @@ -108,9 +110,9 @@ 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. -Choose the concrete Go shape during implementation planning, considering the -existing [View and provider contracts](../../integrations/ckconfig/contracts.go). -Do not turn this small capability into a parallel inspection model. +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 @@ -135,9 +137,9 @@ discovery, explanations, source evidence, and comparison. Applications retain configuration acquisition and selection; the adapter supplies standard CLI integration and delegates domain operations to ConfigKit. -Design this adapter together with the shared native path-enumeration capability. -Demonstrate one application section, such as storage settings, in the maintained -composed example. The section name is illustrative, not a new reserved scope. +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. @@ -173,8 +175,8 @@ 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; exact declaration and internal factoring are implementation-plan -details within that direction. +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 @@ -192,118 +194,45 @@ implementation. Existing projections, such as requirements reports, should retai the meaning of the updated native results. Hash semantics, schema resolution, repair behavior, and error identities remain upstream-owned. -## Work needed +## Compatibility and delivery -### Dependency and configuration migration +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. -1. Update both integration module graphs to ConfigKit v1.4.0 and ckprompt to - PromptKit v0.24.0. Tidy checksums and review the resulting graph. Update - affected root and module-local attribution entries and pinned source links - under the [OSS policy](../policy/oss.md). -2. Move complete-document PromptKit settings beneath `promptkit`. Use - `SettingsInput` for wrapperless settings fragments and `CollectionInput` for - collection fragments where appropriate. Discovery inputs remain root-mounted - unless the application sets their destination. Migrate fixture paths, - configuration overrides, and report assertions to the native locations; - resource IDs themselves do not gain a `promptkit` prefix. -3. Replace removed `Config.SchemaDir`, `WithSchemaFS`, and `WithSchemaFile` uses - with the applicable upstream configuration and resource contexts. Schema - selection supports inline values, source-relative `schema_file`, and - `schema_path` under an explicit applicable `schema_root`, including collection - roots. There is no implicit working-directory root. Follow upstream's - self-contained-schema rules rather than implementing resolution locally. -4. Update affected builders or examples from `*OutputContract` to - `*OutputContractInput` for `RunRequest.Validation`. Preserve whole-contract - replacement. Omitted/null repair budgets resolve to one for `basic`, `json`, - and `json_schema`, and zero for `none`; explicit zero disables repair. - Do not silently force the previous default in the integration. Document the - possible extra generation call, latency, and usage for application execution. -5. Account for `PromptOutputInspection.RepairAttempts` becoming a resolved - integer. Preserve native zero values and new schema fields in reports. - Applications own resource-version policy and sensitivity of extension fields; - do not recreate removed PromptKit validation in CommandKit. +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. -Old root-level resources can be accepted as application data while disappearing -from PromptKit catalogs. Migration verification must therefore check selected -resources and reports, not just successful engine construction. +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. -### Adapter and example work +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. -- Implement the accepted result-loader-plus-path API and scoped enumeration - through the shared configuration provider boundary together. Reuse existing - acquisition, diagnostics, comparison, and outcome conventions where they serve - the native capability; finalize the declaration and factoring in the plan. -- Wire PromptKit's native enumeration directly through the shared capability; - avoid an extra conversion layer solely to reuse the new adapter. -- Demonstrate registration and inspection of one application subtree, including - comparison and preservation of available diagnostics on failure. -- Restructure the composed example around the shared load, with local fixtures - and the existing injected client for smoke demonstrations. Update its consumer - walkthrough and meaningful tests together. -- Retain error causes, independent diagnostics, and available report evidence - through existing classification and delivery paths. The included v0.23.3 - timeout/cancellation corrections should flow through without a local substitute. -- Replace the removed-schema-option fixture with a supported fixture for the - failure-classification behavior it was testing. Schema-file reads now occur - during preparation; do not preserve an obsolete constructor failure merely - to keep that test's shape. - -### Documentation and release preparation - -Update the canonical owners as implementation lands: exported GoDoc for changed -provider capabilities, [CLI reference](../cli.md) for scoped paths and reports, -[consumer guide](../consumers/guide.md) for shared loading and migration, -[developer guidance](../development.md) for working examples and dependency -alignment, and internal documentation where mechanics change. Link upstream -for its formats and rules rather than maintaining another schema reference. - -Prepare integration release notes that identify the breaking PromptKit migration -and any changed ckconfig provider API. Select independent versions under the -[release policy](../policy/release.md); publish ckconfig before ckprompt, then -select that released ckconfig in ckprompt. The downstream integration release -advances at least its minor version under the existing alignment policy. -No core release is needed solely for this adoption. Unrelated core work, including -the optional Scriptorium proposal, is not a prerequisite. - -During development, use the aligned workspace to exercise both local integration -changes. Validate ckconfig independently against its published dependencies; -after ckconfig publication, validate ckprompt independently against that release. -Follow the [release runbook](../release.md) for candidate preparation and -publication rather than introducing a separate process or new release gates. - -## Validation and completion checklist - -Use the [testing policy](../policy/testing.md): test CommandKit's adaptation and -operator behavior, not upstream domain algorithms. Extend existing coverage -where sufficient; compare meaningful report values rather than incidental YAML -layout or hash literals. Tests remain offline and credential-independent. - -- [ ] Both integration graphs and affected attribution select the target releases. -- [ ] Configuration fixtures and maintained examples use the new layout and - supported schema APIs; expected resources remain discoverable. -- [ ] The composed example demonstrates application-owned shared loading through - existing callbacks, including distinct comparison selections. -- [ ] Scoped path enumeration uses upstream's listing; existing CLI filters and - metadata descriptions still work. A representative whole-load sibling verifies - that the adapter does not substitute full metadata enumeration. -- [ ] The public ckconfig adapter exposes a native subtree through the standard - scope commands using the ordinary typed loader and an explicit path, with a - maintained example and focused coverage of acquisition, native comparison, and - whole-load diagnostics/error propagation. Its public handoff is documented. -- [ ] Explicit paths, source evidence, focused rendering, and comparison preserve - native meaning and error handling, including available ancestor evidence. -- [ ] Reports preserve returned schema fields, repair-budget zero, and the new - message-content hash. Requirements projections preserve updated native evidence. -- [ ] Request-builder replacements and supported failure fixtures use the new - public APIs; error identity and existing outcome behavior remain covered at - CommandKit's boundary. -- [ ] Run each affected module's default suite independently and the aligned - workspace suites using the developer guide. Record any interim dependency - limitation honestly; workspace success alone is not independent-module evidence. -- [ ] Canonical documentation, upgrade guidance, and candidate notes match the - implemented result; validate local links and documentation diffs. -- [ ] Prepare and, when authorized, release ckconfig then ckprompt according to - the runbook; record remaining coordination work 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 @@ -344,10 +273,8 @@ 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. -## Planning readiness +## Execution status -No significant open decisions remain before preparing the implementation plan. -The plan should settle the exact Go declarations, shared enumeration capability, -internal factoring, example changes, and focused validation within the accepted -scope. These are engineering details, not additional product decisions or -authority to expand the contracts. Implementation and release work remain pending. +The [staged implementation plan](implementation.md) is ready. No significant +product decisions remain open. Implementation and release work remain pending; +the plan records their separate completion evidence within this accepted scope. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..fb4cead --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,377 @@ +# ConfigKit and PromptKit adoption implementation plan + +Status: ready for implementation; no stages completed. 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: pending. + +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: pending. + +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: pending. + +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: pending. + +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: pending. + +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: 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: pending. + +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.