Plan the ConfigKit and PromptKit adoption

This commit is contained in:
2026-11-21 19:25:05 +00:00
parent 320526d3fc
commit 946181a13e
2 changed files with 427 additions and 123 deletions

View File

@@ -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.

View File

@@ -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.