|
|
|
|
@@ -15,7 +15,8 @@ Reinspect the working tree before starting. Preserve unrelated work. Read
|
|
|
|
|
[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).
|
|
|
|
|
[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
|
|
|
|
|
@@ -31,10 +32,10 @@ completed, nonempty units; do not create empty commits.
|
|
|
|
|
|
|
|
|
|
- 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. The shared-model
|
|
|
|
|
proposal in [future.md](future.md#shared-configuration-data-model) is not part
|
|
|
|
|
of this sprint: no public aliases for internal settings and no new public
|
|
|
|
|
settings package. Use explicit facade data declarations and typed conversions.
|
|
|
|
|
- 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.
|
|
|
|
|
@@ -111,10 +112,13 @@ does not rerun that lifecycle or track which helper registered the rules.
|
|
|
|
|
|
|
|
|
|
### Settings Model
|
|
|
|
|
|
|
|
|
|
Add ordinary root-package structs with these fields, corresponding to the
|
|
|
|
|
current adapter records in `internal/configuration/load.go`. All configuration
|
|
|
|
|
fields have explicit existing snake-case YAML tags; `Application` is the native
|
|
|
|
|
`map[string]any` field tagged `yaml:",inline"`.
|
|
|
|
|
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 |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
@@ -128,18 +132,33 @@ fields have explicit existing snake-case YAML tags; `Application` is the native
|
|
|
|
|
| `PromptCacheControlSettings` | `Type, TTL *string` |
|
|
|
|
|
| `PromptOutputSettings` | `Format, ValidationMode *string`; `Schema any`; `SchemaFile, SchemaPath *string`; `RepairAttempts *int` |
|
|
|
|
|
|
|
|
|
|
Reuse the existing public backend smoke/probe data types, whose fields and YAML
|
|
|
|
|
bindings already match. Keep all nested PromptKit-owned objects strict. No
|
|
|
|
|
`Version` or `Extends` field is needed in this effective settings model: ConfigKit
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Provide corresponding internal adapter data types where needed for typed
|
|
|
|
|
conversion; public signatures do not expose them. Conversions preserve nil versus
|
|
|
|
|
empty containers, pointers, all known fields, and application maps through
|
|
|
|
|
normalization. They do not serialize, decode again, or apply precedence.
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
@@ -263,27 +282,34 @@ 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 Public Settings Schema And Facade Conversions
|
|
|
|
|
## Stage 4 — Add The Shared Settings Schema And Root Aliases
|
|
|
|
|
|
|
|
|
|
Focus: a root settings file and internal configuration data declarations.
|
|
|
|
|
Focus: `internal/settings`, root settings aliases, `backends.go`, and the
|
|
|
|
|
configuration adapter's data declarations.
|
|
|
|
|
|
|
|
|
|
1. Declare the nine public settings structs in the model table, with precise
|
|
|
|
|
GoDoc and YAML tags; reuse the existing backend smoke/probe structs.
|
|
|
|
|
2. Adapt the internal settings records to expose only the internal data boundary
|
|
|
|
|
needed for explicit conversions. Remove their obsolete `Version` field.
|
|
|
|
|
Add inline application maps at the five selected levels only.
|
|
|
|
|
3. Implement straightforward typed conversion in both directions. Preserve all
|
|
|
|
|
values and unknown maps when returning normalized settings to the application.
|
|
|
|
|
Do not use JSON/YAML round-trips, reflection-based registration, or public
|
|
|
|
|
aliases to internal types. A new code-generation subsystem is unnecessary.
|
|
|
|
|
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. Add small decoding/conversion tests covering nested known fields, nil/empty
|
|
|
|
|
containers, and retained application maps. Resource provider maps and nested
|
|
|
|
|
owned object schemas retain their current validation.
|
|
|
|
|
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`
|
|
|
|
|
without importing internal packages, and normalization can round-trip all fields.
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
@@ -302,10 +328,12 @@ Focus: `internal/configuration/load.go`, `resolve_prompts.go`,
|
|
|
|
|
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. Convert
|
|
|
|
|
selected public settings for the internal rules, write normalized settings
|
|
|
|
|
back, and preserve application maps. Leave application defaults/version rules
|
|
|
|
|
intact; component defaults such as queue and repair budgets use resolution.
|
|
|
|
|
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.
|
|
|
|
|
@@ -318,7 +346,7 @@ capturing another load's resource state or taking over application version polic
|
|
|
|
|
Focus: `internal/configuration/load.go`, `prompts.go`, `targets.go`, and
|
|
|
|
|
`resources.go`.
|
|
|
|
|
|
|
|
|
|
1. Extract capture from loading: accept converted effective settings plus the
|
|
|
|
|
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
|
|
|
|
|
@@ -396,8 +424,8 @@ Focus: root `engine.go`, new configuration facade wiring,
|
|
|
|
|
|
|
|
|
|
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. Forward converted
|
|
|
|
|
settings and native evidence to the internal capture operation.
|
|
|
|
|
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
|
|
|
|
|
@@ -410,9 +438,9 @@ Focus: root `engine.go`, new configuration facade wiring,
|
|
|
|
|
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 need not import the facade: keep source loading and
|
|
|
|
|
public model translation at the facade/configuration boundary and pass the
|
|
|
|
|
captured adapter value inward for assembly.
|
|
|
|
|
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.
|
|
|
|
|
@@ -495,7 +523,10 @@ 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.
|
|
|
|
|
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
|
|
|
|
|
@@ -587,8 +618,10 @@ and `docs/internal/{overview,sources,runner}.md`.
|
|
|
|
|
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. Retain its facade and data-ownership constraints; do not adopt
|
|
|
|
|
the future shared-model exception or alter the accepted ADR.
|
|
|
|
|
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
|
|
|
|
|
@@ -601,10 +634,14 @@ 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. Confirm one library rule implementation, one capture path, one
|
|
|
|
|
assembly path, and no original-result retention for mutable application config.
|
|
|
|
|
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,
|
|
|
|
|
temporary conversion scaffolding, and compatibility code left during staging.
|
|
|
|
|
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
|
|
|
|
|
@@ -629,7 +666,8 @@ path, with no future behavior described as implemented before it lands.
|
|
|
|
|
|
|
|
|
|
Completion requires implemented repair defaults for configuration and runtime
|
|
|
|
|
inputs, an application-owned single-load handoff, equivalent standalone loading,
|
|
|
|
|
all selected extension/inspection behavior, owned execution capture, migrated
|
|
|
|
|
consumer examples/docs, and successful final validation. No product decision
|
|
|
|
|
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.
|
|
|
|
|
|