2026-11-21 13:42:10 +00:00
|
|
|
# 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
|
2026-11-21 13:51:26 +00:00
|
|
|
[configuration boundary ADR](../adr/0001-configuration-boundary.md) and apply
|
|
|
|
|
[ADR 0002's shared configuration data exception](../adr/0002-shared-configuration-data-model.md).
|
2026-11-21 13:42:10 +00:00
|
|
|
|
|
|
|
|
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.
|
2026-11-21 13:51:26 +00:00
|
|
|
- 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.
|
2026-11-21 13:42:10 +00:00
|
|
|
- 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
|
|
|
|
|
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
|
|
|
|
|
| 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` |
|
|
|
|
|
|
2026-11-21 13:51:26 +00:00
|
|
|
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
|
2026-11-21 13:42:10 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
|
|
|
|
|
2026-11-21 14:10:22 +00:00
|
|
|
Status: complete. Focused configuration, domain, and public source tests passed.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
|
|
|
|
|
2026-11-21 14:12:34 +00:00
|
|
|
Status: complete. Internal use-case tests and the facade build passed; existing
|
|
|
|
|
public test and example call sites remain scheduled for migration below.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-21 13:51:26 +00:00
|
|
|
## Stage 4 — Add The Shared Settings Schema And Root Aliases
|
|
|
|
|
|
2026-11-21 14:15:14 +00:00
|
|
|
Status: complete. Adapter tests and external settings-decoding tests passed;
|
|
|
|
|
the standalone envelope retains its existing version field until loader migration.
|
|
|
|
|
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
4. Keep existing source helpers independent. Do not add `Extends` to the effective
|
|
|
|
|
schema or silently change primitive/null rules such as `Required bool`.
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
|
|
|
|
|
Evidence: an external application can declare its field as `promptkit.Settings`
|
2026-11-21 13:51:26 +00:00
|
|
|
and construct its nested values without importing internal packages. Public and
|
|
|
|
|
adapter settings share one declaration set with no conversion layer between them.
|
2026-11-21 13:42:10 +00:00
|
|
|
|
|
|
|
|
## Stage 5 — Extract Stateless Component Rules At Native Paths
|
|
|
|
|
|
2026-11-21 14:18:15 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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.
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
|
|
|
|
|
2026-11-21 14:20:46 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
Focus: `internal/configuration/load.go`, `prompts.go`, `targets.go`, and
|
|
|
|
|
`resources.go`.
|
|
|
|
|
|
2026-11-21 13:51:26 +00:00
|
|
|
1. Extract capture from loading: accept the shared effective settings plus the
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
|
|
|
|
|
2026-11-21 14:21:39 +00:00
|
|
|
Status: complete. Focused race-tested checks cover native cross-root comparison,
|
|
|
|
|
historical paths, and detached diagnostics; broader facade coverage follows.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
|
|
|
|
|
2026-11-21 14:22:41 +00:00
|
|
|
Status: complete. Focused mounting tests passed for bundled, collection,
|
|
|
|
|
ordinary fragment, and sequence-item sources without eager acquisition.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
|
|
|
|
|
2026-11-21 14:24:30 +00:00
|
|
|
Status: complete. Focused constructor tests passed for shared capture, explicit
|
|
|
|
|
bundle behavior, and invalid handoffs; broader integration coverage follows.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
2026-11-21 13:51:26 +00:00
|
|
|
focused view, and capture original-result diagnostics. Pass the selected shared
|
|
|
|
|
settings and native evidence directly to the internal capture operation.
|
2026-11-21 13:42:10 +00:00
|
|
|
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.
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
|
|
|
|
|
2026-11-21 14:29:06 +00:00
|
|
|
Status: complete. Configuration tests passed under the race detector, source
|
|
|
|
|
helper tests passed, and the updated benchmarks ran without thresholds.
|
|
|
|
|
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
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
|
2026-11-21 13:51:26 +00:00
|
|
|
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.
|
2026-11-21 13:42:10 +00:00
|
|
|
Remove dead generic-result bridges, version checks, resolver side maps,
|
2026-11-21 13:51:26 +00:00
|
|
|
equivalent-settings conversion scaffolding, and compatibility code left during
|
|
|
|
|
staging. Preserve meaningful domain conversions and ownership copies.
|
2026-11-21 13:42:10 +00:00
|
|
|
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,
|
2026-11-21 13:51:26 +00:00
|
|
|
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
|
2026-11-21 13:42:10 +00:00
|
|
|
remains open; private helper names and file organization may follow the existing
|
|
|
|
|
code without changing these public shapes or scope.
|