# 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/` 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 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 Status: complete. Focused constructor tests passed for shared capture, explicit bundle behavior, and invalid handoffs; broader integration coverage follows. 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 Status: complete. Configuration tests passed under the race detector, source helper tests passed, and the updated benchmarks ran without thresholds. 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 Status: complete. Internal engine and use-case tests passed under the race detector using registered loads and captured configuration. 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 Status: complete. The root and internal test suites passed with updated request inputs, explicit fragment mounts, native paths, and the shared-model boundary. 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 Status: complete. External handoff integration tests passed under the race detector, including concurrent loads, source contexts, and ownership checks. 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 Status: complete. Focused facade inspection tests passed under the race detector, including redaction, frozen history, diagnostics, and comparison. 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 Status: complete. All three maintained offline example test packages passed. 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 Status: complete. Canonical guides, GoDoc, architecture, and internal component descriptions cover the new configuration and repair contracts; local links and focused tests passed. 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.