Files
promptkit/docs/roadmap/implementation.md

698 lines
42 KiB
Markdown
Raw Normal View History

# Next-Release Configuration And Repair Implementation Plan
## Objective And Authority
Implement both accepted features in
[next-release-considerations.md](next-release-considerations.md): mode-dependent
repair defaults and application-owned, one-load configuration handoff under
`promptkit`. The [integration assessment](configuration-integration-check.md)
establishes feasibility against ConfigKit v1.4.0; it is evidence, not production
code to merge wholesale.
Baseline: PromptKit `07aaee8`, ConfigKit v1.3.0, consumer Go minimum 1.27.0.
Reinspect the working tree before starting. Preserve unrelated work. Read
[development](../development.md) and the applicable policies, especially
[agents](../policy/agents.md), [architecture](../policy/architecture.md),
[testing](../policy/testing.md), [documentation](../policy/documentation.md), and
[OSS](../policy/oss.md). Preserve the accepted
[configuration boundary ADR](../adr/0001-configuration-boundary.md) and apply
[ADR 0002's shared configuration data exception](../adr/0002-shared-configuration-data-model.md).
The audience is a Luna coding agent. Execute the numbered stages in order as a
single end-to-end sprint. Each stage bounds one prompt's work; it is not a
human-review, upstream-publication, or intermediate green-build gate. Intermediate
commits may contain expected compilation failures or unmigrated fixtures. Record
those honestly and continue to the dependent stage. Do not add temporary legacy
loaders or compatibility types merely to keep intermediate states compiling.
Run focused checks when their dependencies are ready; final correctness requires
the complete end state and validation in Stage 17. Follow the commit policy for
completed, nonempty units; do not create empty commits.
## Scope And Design Decisions
- Use the published ConfigKit v1.4.0 module without local replacements. Keep the
consumer minimum at Go 1.27.0. No sibling-repository change is needed.
- Keep the root facade and internal implementation boundary, with ADR 0002's
narrow exception: define the public settings once in `internal/settings` and
expose root aliases. The configuration adapter uses those declarations directly.
No new public settings package or equivalent-model conversion layer is needed.
- ConfigKit owns acquisition, composition, inheritance, source-version policy,
and native inspection. PromptKit interprets final values and captures its
resources. Do not inspect raw contributions or replay history for execution.
- The canonical location is fixed at `/promptkit`. Runtime IDs and namespace
rules do not acquire that prefix. Remove PromptKit-specific resource-version
checks; do not introduce legacy-path detection or another merge pass.
- Registration supplies normalizers, final-value validators, sensitivity, and
sequence identities. Engine construction captures resources without loading
configuration again. Both constructors share capture and engine assembly.
- Retain the runner, repair loop, prepared-execution ownership, capacity pools,
schema preparation, observers, and model clients. Change only the inputs and
wiring needed here; preserve their substantive behavior.
- Application fields remain in resolved settings and native configuration
inspection. Resource inspection and execution use PromptKit-understood fields.
Do not add extension registries, provider parameters, or extension-specific
resource-report payloads.
### Public API To Implement
Use the following names and shapes. Public declarations have GoDoc; the code and
canonical docs become their owners when implemented.
```go
type Configuration interface {
Value(configkit.Path) (any, bool)
InspectSubtree(configkit.Path) (configkit.Inspection, bool)
Diagnostics() []configkit.Diagnostic
}
func Configure[T any](definition configkit.Definition[T],
selectSettings func(*T) *Settings) configkit.Definition[T]
type RuntimeConfig struct {
Timeout time.Duration
HTTPClient *http.Client
TransientRetries *int
}
func NewFromConfig(result Configuration, cfg RuntimeConfig,
opts ...Option) (*Engine, error)
func SettingsInput(source configkit.Source) configkit.Input
func BundledOpenRouterUnderlay() configkit.Underlay
func (v ConfigurationInspection) HistoricalPaths() []configkit.Path
```
`RuntimeConfig` has the existing `Config` runtime-field semantics. Keep the
existing `Config` fields and `NewEngine(Config, ...Option)` API rather than
requiring unrelated changes to its struct literals. The new constructor has no
source fields. Existing collaborator options apply to either constructor;
`WithBundledOpenRouter` selects sources only for `NewEngine` and has no effect on
an already resolved handoff. Nil options keep their existing behavior.
Registration takes a nonnil selector for the application's field. A selector
returning nil means that optional settings section has no values to normalize or
validate; do not allocate it just to register rules. Preserve application
`Defaults` and `Version`. Run pre-existing `Resolve` first, then PromptKit
resolution, propagating its error. Run pre-existing `Validate` first, then
PromptKit validation. OR the sensitivity predicates and append PromptKit sequence
identities using an owned registration slice. Consumers can wrap the returned
callbacks to run other work afterward. No registration tracking is required.
Handoff accepts `Settings`, `*Settings`, an unavailable selection, or a nil
selection at the fixed path. Missing/nil selections contribute no resources;
other section types fail with `ErrInvalidConfig`. Distinguish lookup availability
from explicit input presence using final metadata. A nil result or an unavailable
native inspection view also fails construction; do not synthesize inspection by
loading again. Ordinary construction failures preserve their underlying causes
through the existing public error mapping.
The application includes PromptKit's rules in its original successful load,
through `Configure` or equivalent explicit callback composition. Construction
does not rerun that lifecycle or track which helper registered the rules.
### Settings Model
Declare the following structs once in `internal/settings`, corresponding to the
current adapter records in `internal/configuration/load.go`. Expose each under
the same name in the root package with an alias, such as
`type Settings = settings.Settings`. All configuration fields have explicit
existing snake-case YAML tags; `Application` is the native `map[string]any` field
tagged `yaml:",inline"`. Consumers use the root names in their own typed
configuration and nested composite literals.
| Public type | Fields |
| --- | --- |
| `Settings` | `SchemaRoot *string`; `Backends []BackendSettings`; `Profiles []ProfileSettings`; `Prompts []PromptSettings`; `Collections map[string]CollectionSettings`; `Application` |
| `CollectionSettings` | `ReleaseVersion, SchemaRoot *string`; the same three resource slices; `Application` |
| `BackendSettings` | `ID string`; `Endpoint, APIKeyEnv *string`; `ConcurrencyLimit, QueueCapacity *int`; `ExtraParams map[string]any`; `SmokeTests *BackendSmokeTestConfig`; `Application` |
| `ProfileSettings` | `ID string`; `Backend, Endpoint, Model *string`; `Temperature, TopP *float64`; `MaxTokens, TimeoutSeconds *int`; `ServiceTier, ReasoningEffort, APIKeyEnv *string`; `APIKeyRequired *bool`; `ExtraParams map[string]any`; `Application` |
| `PromptSettings` | `ID string`; `DefaultProfile, Description, SessionID *string`; `Inputs []PromptInputSettings`; `Messages []PromptMessageSettings`; `Output *PromptOutputSettings`; `Application` |
| `PromptInputSettings` | `Name string`; `Required bool`; `ContentType, Description *string` |
| `PromptMessageSettings` | `Role, Content, ContentFile *string`; `CacheControl *PromptCacheControlSettings` |
| `PromptCacheControlSettings` | `Type, TTL *string` |
| `PromptOutputSettings` | `Format, ValidationMode *string`; `Schema any`; `SchemaFile, SchemaPath *string`; `RepairAttempts *int` |
Move the data declarations for `BackendSmokeTestConfig`,
`ReachabilityProbeConfig`, and `AuthenticationProbeConfig` into the same shared
package and expose their existing root names as aliases. Preserve their fields,
JSON/YAML tags, and documented behavior. These types are nested in settings and
already used by source helpers and reports; moving their declarations avoids an
import cycle without merging those helpers or reports into the settings model.
Keep domain smoke values and meaningful conversions to them separate.
Keep all nested PromptKit-owned objects strict. No `Version` or `Extends` field
is needed in this effective settings model: ConfigKit
handles inheritance controls before decoding, and resource `version` data can
reside in the allowed inline maps. Existing `PromptConfig`, `ProfileConfig`, and
`BackendConfig` remain source-construction values, including their `Extends`
fields; they are not substitutes for these decoding types.
The shared package contains data declarations and their field documentation;
loading, normalization, validation, and resource capture stay in their existing
owners. It imports neither the facade nor configuration/engine/domain logic.
The adapter consumes the same settings types as the public API, preserving
nil/empty containers, pointers, and application fields without a settings
conversion round-trip. Root aliases have public GoDoc directing consumers to the
canonical field declarations. Treat the shared declarations as public API, not
as independently changeable private structs.
Keep necessary conversion and ownership copying into execution values and
resource reports. Runtime requests and resolved output contracts remain outside
this exception; their changes are described separately below.
### Repair Input And Resolved Types
Keep public `OutputContract` and internal `domain.OutputContract` as resolved
values with `RepairAttempts int`. Add public `OutputContractInput` with the same
format, validation mode, schema, and schema-path fields, but
`RepairAttempts *int` (`json:"repair_attempts,omitempty"`). Change
`RunRequest.Validation` to `*OutputContractInput`, preserving its field name and
whole-contract replacement semantics. Add the corresponding internal request
input value rather than putting optional budgets on execution contracts.
Configuration `PromptOutputConfig.RepairAttempts`, settings budgets, and runtime
input budgets use pointers. Nil (including final YAML/JSON null) selects zero for
`none`, one for `basic`, `json`, or `json_schema`. Explicit zero disables repair;
two and three remain supported. Existing validation rejects negative budgets,
budgets above three, unknown validation modes, and positive budgets for `none`.
Do not introduce a default validation mode or change existing format defaults.
Public `PromptOutputInspection.RepairAttempts` becomes a concrete `int`, emitted
even when zero; prepared details continue using resolved `OutputContract`.
Actual repair counters remain unchanged integers. Resolve configured budgets
after composition; resolve replacement budgets from the replacement's mode,
without inheriting the prompt's budget. Resolve defaults once, before execution.
### Source And Inspection Decisions
- Keep `PromptSource`, `ProfileSource`, `BackendSource`, and `SchemaRootSource`
producing wrapperless settings fragments. `SettingsInput` mounts a source at
`/promptkit`, with ordinary mapping placement and imports disabled by default;
callers may adjust native input fields. This avoids double-wrapping fragments
mounted in collections.
- `CollectionInput` mounts at `/promptkit/collections/<namespace>` and keeps its
existing namespace validation and enabled-import default. `id`-first files use
native sequence-item placement at `/promptkit/prompts`, `/promptkit/profiles`,
or `/promptkit/backends`, including collection-local equivalents.
- Keep directory/filesystem discovery helpers as source selection with their
existing root destination and discovery/context semantics. Full documents use
the canonical wrapper. Callers mounting discovered wrapperless fragments set
their native destinations explicitly; do not detect document shapes.
- `BundledOpenRouterUnderlay` returns the existing bundled fragment mounted at
`/promptkit`. Applications select it before their load. `NewEngine` still
defaults it on, placing it before caller underlays without mutating them.
- The standalone load uses an envelope containing `PromptKit Settings` and an
inline map for other root settings. Root keys resembling old resource keys
are not specially consumed or rejected. There is no PromptKit version rule
or forced source-version mode; application-owned loads retain their own rules.
- Retain the existing reporting methods and zero-view behavior. Add
`HistoricalPaths() []configkit.Path`, returning nil for the zero facade view.
Use native `Inspection` operations; diagnostics are captured separately from
the original result. Keep the native paths and focused semantics in the feature
roadmap, including unfiltered metadata/explicit queries and ancestor diffs.
## Stage 1 — Upgrade The ConfigKit Dependency
2026-11-21 14:07:51 +00:00
Status: complete. The existing suite passed with Go 1.27.4 and ConfigKit v1.4.0.
Purpose: isolate the prerequisite dependency change from the refactor.
1. Update `go.mod` and `go.sum` to ConfigKit v1.4.0 using the published module.
Keep `go 1.27.0` and unrelated dependency selections unchanged unless module
resolution demonstrably requires a change.
2. Inspect that release's actual notices and update its entry and exact upstream
commit links in `docs/oss/attribution.md` under the OSS policy. Retain applicable
existing license texts; do not infer new licensing requirements from the bump.
3. Run the existing suite against the dependency update while the old layout is
still intact. Use the newest installed local Go patch with `GOTOOLCHAIN=local`
and `GOWORK=off`. Record the result and keep this change separately reviewable.
Evidence: published v1.4.0 is selected, attribution matches, and the unchanged
configuration implementation still passes its tests. This is ordinary development
validation, not an approval gate before Stage 2.
## Stage 2 — Resolve Configuration Repair Defaults
Status: complete. Focused configuration, domain, and public source tests passed.
Focus: `internal/domain`, configuration output decoding/resolution/capture,
resource inspection, and their narrow tests.
1. Add one small source-neutral mode/budget defaulting helper used by both
configuration and runtime input resolution. Keep existing output-contract
legality in the domain validation boundary; do not duplicate the mode table
across adapters.
2. Change the configuration budget to `*int`. During final-value resolution,
record the default at the individual `output/repair_attempts` path when nil.
Use a recorded normalization that also handles explicit null; an absent-only
default operation must not skip null. Leave nonnil explicit values unchanged.
3. Capture the concrete integer into the domain output contract. Remove the
repair-presence side map and report the actual resolved budget in resource
inspection, including zero. Update the public inspection field and converter.
4. Keep `PromptOutputConfig` source-helper pointers: nil omits a field and a
pointer to zero emits zero. Raw native configuration can express null.
5. Add focused configuration cases for each eligible mode, `none`, omission,
null, zero, two/three, rejected bounds, and null clearing an inherited budget.
Verify effective inspection records the resolved value. Preserve required
output fields and schema-selection rules.
Evidence: YAML and typed source inputs produce the selected concrete budgets,
with no change to actual-attempt counters or the repair loop.
## Stage 3 — Separate Runtime Contract Inputs From Resolved Contracts
Status: complete. Internal use-case tests and the facade build passed; existing
public test and example call sites remain scheduled for migration below.
Focus: `types.go`, `convert.go`, `internal/domain/domain.go`, request ownership,
`internal/usecase/runner.go`, and focused runtime tests.
1. Introduce the public/internal input types described above and update
`RunRequest.Validation`, conversions, and relevant request-copy/formatting
paths. Copy the optional budget at the existing request-ownership boundary.
Preserve existing schema ownership and request privacy rules, without adding
a guarantee about concurrent caller writes.
2. Update `resolveOutputContract` to resolve an input replacement into a concrete
contract using the shared helper. Keep replacement rather than merge, existing
empty-format handling, inactive-schema dropping, inline schema decoding,
schema-root binding, and public error identities.
3. Keep configured contracts, prepared runs, validator/repair inputs, and
`RunPrepared` concrete. Prepared execution must not recalculate defaults or
consult later request/configuration mutations.
4. Test omitted versus explicit-zero replacement budgets, eligible defaults,
`none` and invalid budgets, a replacement independent of the configured
budget, and prepared retention. Use an offline client returning invalid then
valid output to prove one default repair; use explicit zero to prove no repair.
Keep existing exhaustion, cancellation, transient retry, and usage tests.
Evidence: the input API distinguishes default from zero while execution and
accounting continue consuming resolved integers. Broader call-site migration is
assigned to Stages 11 and 12; do not retain a legacy request-input alternative.
## Stage 4 — Add The Shared Settings Schema And Root Aliases
Status: complete. Adapter tests and external settings-decoding tests passed;
the standalone envelope retains its existing version field until loader migration.
Focus: `internal/settings`, root settings aliases, `backends.go`, and the
configuration adapter's data declarations.
1. Declare the nine settings structs in the model table in `internal/settings`,
with canonical field GoDoc and YAML tags. Add the three backend smoke/probe
declarations there with their existing fields and serialization tags.
2. Expose root aliases for all twelve data types. Keep existing public smoke/probe
names usable in source helpers and resource reports. The shared package has no
loading, normalization, validation, capture, or execution behavior and no
dependency on the root facade.
3. Replace equivalent adapter decoding records with the shared types, including
nested settings. Remove the obsolete `Version` field and retain the inline
application maps at the five selected levels. Preserve Stage 2's pointer
budgets. Do not add duplicate public/internal settings or conversion helpers;
keep settings-to-domain conversion and owned capture where they do real work.
4. Keep existing source helpers independent. Do not add `Extends` to the effective
schema or silently change primitive/null rules such as `Required bool`.
5. Use external-package decoding tests with nested root-name composite literals,
including smoke/probe settings, nil/empty containers, and application maps.
Verify the existing smoke/probe serialization shape and source-helper use
remain supported. Retain known-field and nested-object validation tests;
normalization and post-capture ownership are exercised in subsequent stages.
Evidence: an external application can declare its field as `promptkit.Settings`
and construct its nested values without importing internal packages. Public and
adapter settings share one declaration set with no conversion layer between them.
## Stage 5 — Extract Stateless Component Rules At Native Paths
Status: complete. Focused registration tests passed under the race detector;
the old adapter tests do not compile against the new envelope and remain scheduled
for migration, while metadata capture moves to the next stage.
Focus: `internal/configuration/load.go`, `resolve_prompts.go`,
`resolve_targets.go`, sensitivity paths, and public `Configure` wiring.
1. Separate configuration rules from `loaded` state. Keep one internal
normalization/validation implementation and the current source-neutral domain
checks. Prefix resource bases, schema roots, validation paths, sensitivity
matching, and sequence registrations with `/promptkit`.
2. Register `id` identities for the three root resource lists and wildcard
collection equivalents. Leave collection/resource runtime identity formation
unchanged. Existing application registrations remain present.
3. Remove the resolver's input-presence capture closure. Presence will come from
final metadata in Stage 6, not a shared mutable map tied to one load.
4. Remove `checkConfigurationVersion` and PromptKit's `VersionRule` installation.
Do not preparse sources, strip version fields, or install a replacement
resource-version policy.
5. Implement `Configure` with the callback composition specified above. Pass the
selected settings pointer directly to the internal rules. Normalize it in
place through ConfigKit's recorded operations, preserving application maps.
Leave application defaults/version rules intact; component defaults such as
queue and repair budgets use resolution. No settings conversion or write-back
reconstruction is needed.
6. Cover callback error propagation, native sensitivity, application validation,
and registration preservation in focused tests. Do not add detection that a
consumer registered a particular helper or used a particular callback order.
Evidence: rules can be reused across loads, including concurrent loads, without
capturing another load's resource state or taking over application version policy.
## Stage 6 — Capture Owned Resources From Final Settings And A Native View
Status: complete. Focused capture tests passed under the race detector, including
mutation isolation and effective cross-filesystem source contexts. The former
generic inspection bridge is removed in the next stage.
Focus: `internal/configuration/load.go`, `prompts.go`, `targets.go`, and
`resources.go`.
1. Extract capture from loading: accept the shared effective settings plus the
native focused `configkit.Inspection` and detached load diagnostics. This
adapter operation is not another ConfigKit lifecycle.
2. Read a final metadata snapshot once for construction and share it across
prompt input presence and field-origin lookup. Replace resolver-side input
maps with capture-time facts, retaining only the facts resource/requirement
reports actually use. Do not query history to infer presence or origins.
3. Resolve content files and schema bindings through the effective field's
origin and the view's `SourceContext`. Preserve mixed filesystems, imports,
mounting, inheritance, overrides, and existing resource containment behavior.
Keep schema reading/compilation at the existing preparation boundary.
4. Detach retained known settings: nested provider maps, schema values, scalar
pointers, resource slices, and collection maps as needed by runtime and
resource inspection. Reuse existing ownership helpers where suitable; a
shallow struct copy or the current trusted cloner's nonrecursive struct case
is not sufficient by itself. Prefer explicit ownership of known data over
cloning arbitrary application extension values.
5. Build the current backend/profile indexes, compiled prompts/hashes,
requirement snapshots, capacity policies, inventories, and collection labels.
Resource reports omit application maps. Preserve partial-profile completion
and all unrelated selection behavior.
6. Retain the native reporting view, diagnostics, and required resource bindings,
rather than the mutable whole application result. The frozen native view can
retain whole-application evidence; do not manufacture isolation or retain
metadata as an execution-time resolver.
Evidence: capture constructs the same executable resources independently of the
application's root Go type and later mutation of its settings.
## Stage 7 — Replace Generic Inspection Storage With The Focused View
Status: complete. Focused race-tested checks cover native cross-root comparison,
historical paths, and detached diagnostics; broader facade coverage follows.
Focus: `internal/configuration/inspection.go` and
`configuration_inspection.go`.
1. Remove the dependency on `*configkit.Result[document]` and `capturedResult()`.
Retain the native non-generic view and diagnostics in the adapter report.
2. Forward existing reporting methods. Add `HistoricalPaths` through both
boundaries, retaining the facade's established nil/zero receiver behavior.
3. Delegate comparisons to native `Inspection.Diff`; remove the generic-result
comparison bridge if no longer needed. Keep the facade's zero-view
`ErrInvalidConfig` and preserve other native errors.
4. Return owned diagnostic records, including copies of `Primary` and `Related`.
Obtain these diagnostics from the original result during handoff, not from the
view, which does not have a diagnostics method.
5. Do not filter metadata, explicit queries, full source catalogs, dependencies,
ancestor differences, or native redaction. Do not rebase paths.
Evidence: the same facade supports views from different application root types,
without custom redaction/history/diff implementations or access to typed config.
## Stage 8 — Mount Bundles And Standalone Fragments Explicitly
Status: complete. Focused mounting tests passed for bundled, collection,
ordinary fragment, and sequence-item sources without eager acquisition.
Focus: `configuration_sources.go`, public source helpers, and
`internal/configuration/bundled.go`.
1. Add `SettingsInput` and `BundledOpenRouterUnderlay` with the source decisions
above. The latter can delegate to the internal bundle helper; it does not read
the bundle during construction of the underlay.
2. Change `CollectionInput`'s destination, preserving imports and caller-adjustable
context. Keep typed source mapping functions wrapperless. Do not change file
discovery or add automatic wrapper/item detection.
3. Mount the embedded OpenRouter fragment with native `Input.Destination`.
Keep the existing asset as a fragment rather than making two copies for
root and collection use. Preserve bundled IDs and resource content.
4. Test ordinary fragments, wrapperless collection files, an `id`-first file with
native item placement, and their source-relative references. Verify creating
helpers alone performs no source acquisition.
Evidence: convenient resource fragments still compose into the sole resolved
location, with no shape recognition or second merge pass.
## Stage 9 — Wire Whole-Result And Standalone Engine Construction
Focus: root `engine.go`, new configuration facade wiring,
`internal/engine/engine.go`, and the former adapter load entry point.
1. Add public `Configuration`, `RuntimeConfig`, and `NewFromConfig`. Select
`Value(Keys("promptkit"))`, handle the accepted terminal forms, obtain the
focused view, and capture original-result diagnostics. Pass the selected shared
settings and native evidence directly to the internal capture operation.
2. Map nil/unavailable inspection, wrong section type, invalid options, and
capture failures through `ErrInvalidConfig`. Preserve wrapped ConfigKit errors
on the source-loading path. Do not run `Configure`, normalize again, inject
bundles, or load any source inside the handoff constructor.
3. Extract shared engine assembly after capture. Preserve runtime settings,
option application order, injected collaborators, capacity ownership,
namespace views, ordinary runner/repair wiring, and diagnostic clients.
4. Make `NewEngine` assemble its selected underlays/main, run one ConfigKit
lifecycle with the public settings envelope and `Configure`, and call the
same handoff/capture/assembly path. A nil main uses `NoSource` as before.
Use the standalone envelope and version behavior specified above.
5. Remove the obsolete independent loader path and mutable typed-result storage.
The internal engine does not import the facade: keep source-loading orchestration
at the facade/configuration boundary, use the shared settings directly, and
pass the captured adapter value inward for assembly.
6. Document before-handoff mutation expectations rather than adding equality,
provenance-consistency, or registration checks. Existing after-construction
mutation protection remains.
Evidence: both constructors own the same runtime resources and use the same
rules, with a single load only on the source-loading path.
## Stage 10 — Migrate Internal Configuration And Source Tests
Focus: `internal/configuration/*_test.go` and source-helper contract tests.
1. Migrate effective-tree paths and document wrappers; leave explicitly mounted
collection/item fragments wrapperless. Update helper tests to the chosen
destinations and unchanged discovery semantics.
2. Replace tests coupled to `state.result.Config`, `capturedResult()`, and resolver
presence maps with resource outcomes or native inspection behavior. Remove
tests whose sole contract was the retired PromptKit resource-version rule.
3. Retain final-effective-value checks, type/semantic errors, resource-ID rules,
collection labels, normalization origins, source context, missing files,
schema capture, listings, and configured capacity behavior.
4. Update repair default expectations deliberately. Tests about unrelated behavior
that require single-pass execution should configure explicit zero; do not
depend accidentally on the changed default.
5. Keep benchmarks representative of the new paths without adding performance
thresholds or a new benchmark acceptance gate.
Evidence: migrated adapter and source tests protect the new public behavior
rather than the removed private storage representation.
## Stage 11 — Migrate Internal Engine And Execution Tests
Focus: existing `internal/engine` and `internal/usecase` tests and their fixtures.
1. Change internal request replacements to the new input type and pointer
budgets; keep resolved contracts and prepared expectations concrete.
2. Adapt internal engine assembly tests to captured configuration rather than
the retired source-loading entry point. Use the same internal rules/capture
in test setup or an external test package where appropriate; do not introduce
a root-package import cycle or restore a second production loader for tests.
3. Migrate documents and paths to the nested location, retaining native fragment
placement where used. Configure explicit zero when a test needs single-pass
behavior independently of the changed default.
4. Preserve focused tests for generation errors, transient retries, repair
accounting/exhaustion, cancellation, deadlines, observers, continuation,
concurrency, smoke diagnostics, and prepared ownership. Run affected packages
as they become ready; record any still-dependent fixture migrations.
Evidence: execution tests use the new input/capture boundaries without changing
unrelated runtime contracts or adding test-only source interpretation.
## Stage 12 — Migrate Existing Public Facade Call Sites And Fixtures
Focus: existing root-package contract tests and their configuration fixtures.
1. Change request replacements to `OutputContractInput` and pointer budgets;
leave resolved expectations as `OutputContract`. Preserve tests for zero,
inactive schema, request privacy/ownership, invalid contracts, and prepared
snapshots rather than mechanically changing their meaning.
2. Wrap whole documents beneath `promptkit`; mount programmatic source fragments
with `SettingsInput` or explicit native destinations. Update fixture paths in
native explanations without changing runtime IDs or stored references.
3. Migrate comparison fixtures and concrete inspection budgets to the new
reporting semantics. Keep application root keys unconsumed instead of making
legacy detection pass.
4. Retain existing public error, ownership, selection, diagnostic, execution, and
hash coverage. Tests requiring no repair should select explicit zero.
5. Run `go test . ./internal/...` as packages become ready to find missed call
sites and repair them; examples migrate in Stage 15. A broad failure from one
missing mount is not permission to delete coverage or loosen expectations
unrelated to the two approved changes.
Evidence: existing substantive facade APIs remain exercised under the new input
and configuration contracts; expected test call-site migrations are complete.
## Stage 13 — Add Application-Owned Handoff Integration Coverage
Focus: a small external-package root integration test group, with real ConfigKit
and PromptKit collaborators and an offline model client.
1. Define an application with sibling settings, `Settings`, and a representative
second component. Preserve callbacks, defaults, version policy, registrations,
sensitivity, normalization order, and validation diagnostics. Reuse the same
configured definition across independent and concurrent loads. Use only root
aliases in consumer declarations; verify normalized fields and retained
application maps are visible to subsequent application callbacks and in the
final result without public/internal settings conversions.
2. Load once and hand the entire result to `NewFromConfig`. Also use a wrapper
exposing only the three `Configuration` methods. Single-use/counted sources
can prove construction does not reacquire configuration; expected message and
schema resource reads must remain allowed.
3. Combine embedded-like and operator filesystems, collection/item placement,
sibling inheritance, and an override from another source. Verify effective
message and schema contexts through preparation and an ordinary offline run.
4. Compare equivalent application-owned and standalone resource reports,
inventories, and prepared execution details. Include bundles selected before
the load and application-only loading without bundles.
5. Exercise missing fields, declared zero settings, typed nil, explicit null,
wrong types, and old-looking application root keys. Test application fields at
all five extension points through composition, application validation,
normalization, configuration reporting, and exclusion from resource reports
and model parameters. Keep recognized and nested-owned-field failures.
6. Mutate caller settings after construction: pointers, slices, nested provider
maps, inline schema arrays/maps, and file-selection strings. Verify owned
resource reports and preparation/run behavior remain captured. Do not invent
before-handoff mutation detection or snapshot filesystem guarantees.
Evidence: a consumer can use the complete new workflow without extraction,
serialization, another load, or knowledge of internal types.
## Stage 14 — Add Focused Inspection Integration Coverage
Focus: the public configuration-inspection facade, reusing minimal fixtures.
1. Verify focused effective output, native redaction including ancestor and
application sensitivity, frozen evidence after caller mutation, and detached
diagnostics forwarded from the original result.
2. Verify scoped `HistoricalPaths` alongside unfiltered `Metadata`; explicit
outside-focus explanations/history remain native. Test `/promptkit` as the
overview location and the empty native path as whole-application explanation.
Source catalogs/contextual evidence remain whole-load evidence.
3. Verify comparison through PromptKit across different application Go root
types: changed PromptKit data is reported; sibling-only records are excluded;
ancestor records retain native behavior. Cover added/removed, absent, null,
and historical-only sections and native errors where relevant to the facade.
An absent effective scope fails rendering without output; explicit null
renders normally.
4. Preserve zero-facade error behavior and writer-error identity. Do not duplicate
ConfigKit's entire comparison/history/redaction suite; use representative
boundary cases to prove delegation and focused semantics.
Evidence: inspection is convenient reporting focus with no claim of isolation
or independent comparison implementation.
## Stage 15 — Update The Three Maintained Offline Examples
Focus: `examples/go-library/{prepare,run,observe}` and their tests/assets.
1. Update preparation to demonstrate an application-owned typed root, explicit
`Configure`, a single load of the existing synthetic collections, and
`NewFromConfig`. Preserve inventory, scoped selection, preparation, and source
context outcomes. Prefix native inspection paths.
2. Keep execution demonstrating standalone `NewEngine`, using explicit mounts or
wrapped documents and its existing offline client.
3. Migrate observation's source assembly and runtime replacement types. Preserve
its controlled retries and application-directed proposal/assessment flow;
explicitly configure repair budgets where they determine example accounting.
4. Keep wrapperless fragments where mounted. Remove obsolete version-policy
explanations/fixtures rather than replacing them with source preprocessing.
5. Run the example tests and review their semantic assertions. Keep the existing
examples as maintained artifacts instead of copying the disposable prototype
or creating another example framework.
Evidence: both construction workflows are demonstrated by tested, credential-free
consumer examples with no paid or live inference calls.
## Stage 16 — Update Canonical Contracts And Migration Guidance
Focus: GoDoc, `README.md`, `docs/formats.md`,
`docs/consumers/pkg-promptkit.md`, `docs/consumers/configuration-migration.md`,
and `docs/internal/{overview,sources,runner}.md`.
1. Document the new public declarations, callback ordering, supported terminal
types, errors, ownership, and runtime-only settings. Link complete workflows
to the maintained examples and exact field contracts to GoDoc/formats.
2. Explain canonical nesting, all five extension points, nested strictness,
source-fragment mounts, application version ownership, bundled-underlay
selection, and ignored old root resource keys. Update ConfigKit references
needed for these contracts to the selected release.
3. Document request migration from `OutputContract` to `OutputContractInput`,
nil/null versus explicit zero, concrete inspection budgets, mode defaults,
and possible added latency/usage only after failed validation. State that a
correction is not guaranteed. Preserve runtime replacement and counter meaning.
4. Explain focused reporting, including full metadata and explicit outside-focus
queries, native ancestor diffs, frozen evidence, and original-load diagnostics.
Remove assertions that the report is exclusively a PromptKit configuration.
5. Update implemented package responsibilities and the architecture policy's
current engine-loading description to the shared registered-load/capture
arrangement. Document the implemented shared data package and root aliases
under ADR 0002, preserving its narrow scope and all remaining facade and
ownership constraints. Keep the accepted ADR decisions unchanged; the
ConfigKit handoff boundary in ADR 0001 still applies.
6. Search current documentation/examples for stale old paths, integer runtime
inputs, source-version enforcement, and old repair defaults. Preserve
published release notes as historical records. This sprint does not prepare
or publish a release; subsequent minor-release notes must explain these
intentional pre-1.0 compatibility changes.
Evidence: implemented contracts have canonical owners and a practical migration
path, with no future behavior described as implemented before it lands.
## Stage 17 — Complete End-To-End Verification And Remove Superseded Machinery
1. Review the final code against both feature sections and the integration
assessment, using ADR 0002 and this plan for the shared-model change from the
prototype. Confirm one settings declaration set, one library rule implementation,
one capture path, one assembly path, and no original-result retention for mutable
application config. Check that root aliases cover only the selected settings
and nested data types and that internal packages do not import the facade.
Remove dead generic-result bridges, version checks, resolver side maps,
equivalent-settings conversion scaffolding, and compatibility code left during
staging. Preserve meaningful domain conversions and ownership copies.
2. Confirm application extensions stay in loaded settings and frozen native
inspection without needing to be carried into execution. Final capture uses
effective metadata only; ordinary runs do not analyze provenance. Preserve
existing hash semantics except changes naturally caused by newly effective
repair budgets; do not add a cross-release hash guarantee.
3. Review tests under the testing policy: internal tests own focused mechanics;
external-package tests own the facade handoff; examples prove representative
workflows. Consolidate redundant prototype-style cases and keep meaningful
ownership, concurrency, source-context, and error regressions.
4. Format changed Go files. With the latest installed local Go patch selected,
`GOTOOLCHAIN=local`, and `GOWORK=off`, run `go test -race ./...` and
`go vet ./...`. The full suite includes the maintained examples; a second
example execution or separate build is not another completion gate.
5. Review changed Markdown links and run `git diff --check`. Inspect complete
diffs/status for unrelated changes, local replacements/workspaces, generated
artifacts, credentials, accidental upstream copies, and stale references.
6. Commit completed, nonempty work with plain-English messages and report final
validation, compatibility changes, and any unfinished work. Do not tag, push,
publish, wait for CI, or require downstream CommandKit/Audita changes to finish
this sprint. Completed planning documents can be retired during subsequent
release preparation under the documentation policy.
Completion requires implemented repair defaults for configuration and runtime
inputs, an application-owned single-load handoff, equivalent standalone loading,
one shared public/adapter settings model, all selected extension/inspection behavior,
owned execution capture, migrated consumer examples/docs, and successful final
validation. No product decision
remains open; private helper names and file organization may follow the existing
code without changing these public shapes or scope.