Plan the ConfigKit and PromptKit adoption
This commit is contained in:
@@ -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.
|
||||
|
||||
377
docs/roadmap/implementation.md
Normal file
377
docs/roadmap/implementation.md
Normal 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.
|
||||
Reference in New Issue
Block a user