base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Revise configuration plans to preserve source provenance

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-02 12:20:44 +00:00
parent da8496b45b
commit 0b026861a5
2 changed files with 250 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/roadmap/configkit.md
View File

@@ -1,7 +1,8 @@
# ConfigKit v1 Adoption And Identified Resource Collections
Status: accepted direction; implementation pending. This roadmap describes
future behavior, not the currently supported configuration format.
Status: accepted direction; implementation in progress. The target below includes
the agreed execution-owned normalization adjustment for ConfigKit v1.0.0.
Current consumer documentation remains authoritative for supported behavior.
The companion [implementation plan](implementation.md) owns the ordered sprint
steps and validation assignments.
@@ -20,9 +21,9 @@ authoring guidance, not a prohibition on deliberate same-ID replacement across
configuration layers. Keep ConfigKit responsible for composition and inheritance;
PromptKit interprets the final effective configuration and owns resource meaning.
## Current Baseline
## Pre-Migration Baseline
The repository currently declares Go 1.26.0 and depends on
Before this migration, the repository declared Go 1.26.0 and depended on
`gitea.maximumdirect.net/eric/ConfigKit` v0.8.0. The
[format reference](../formats.md) and [source adapter overview](../internal/sources.md)
describe the implemented behavior:
@@ -59,7 +60,10 @@ Update PromptKit's existing uses of:
| --- | --- |
| `Definition.Secret` | `Definition.Sensitive` |
| `Resolution.InputInfo` | `Resolution.EntryInfo` |
| `Resolution.Record(..., ChangeNormalization, ...)` | `Resolution.RecordNormalization(...)` |
Migrate recording API names where still used; PromptKit's normalization and
defaults follow the execution-owned interpretation described below rather than
requiring ConfigKit resolution records for fields within resource lists.
Audit the remaining exposed inspection types and diagnostic consumers against
the complete [ConfigKit v1.0.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/releases/v1.0.0.md).
@@ -132,6 +136,34 @@ in the assembled list shape, including its index-based paths and provenance.
Do not impose a new execution-order meaning on list position or change the
existing inventory sorting solely because source resources become lists.
### Composed Configuration And Execution Interpretation
Accommodate ConfigKit v1.0.0's atomic sequence-mutation auditing. Retain the
composed typed configuration, field presence, and provenance supplied by
ConfigKit. Apply PromptKit's domain normalization and defaults to owned
interpretations of those final records during engine construction, preserving
existing execution behavior and domain validation.
Configuration inspection, explanations, and diffs describe ConfigKit's composed
values and provenance. They do not include PromptKit-side trimming, endpoint
normalization, or execution defaults as ConfigKit resolution history. Existing
prompt/profile inspection and preparation expose their respective interpreted
metadata or effective execution settings. These views have distinct purposes;
an authored whitespace difference can remain visible in a configuration diff
even when it has no effect on the interpreted setting.
Interpretation preserves exact identities, references, presence/null semantics,
and the association between records and effective index paths. Relative resources
such as `content_file` resolve through the contributing field's ConfigKit origin
and source context. Normalization does not replace that attribution with an
application-generated whole-list origin.
This remains interpretation of the final handoff, not source prevalidation or
another composition pass. It requires no upstream change or new public API.
Field-granular normalization within ConfigKit itself is a separate
[future idea](future.md#field-level-normalization-with-preserved-list-provenance)
to reevaluate after upstream support is available.
### Go Source-Builder Inputs
Add an `ID string` field to `ProfileConfig` and `BackendConfig`. Change
@@ -244,6 +276,8 @@ in arbitrarily named collections. Equal local IDs in separate namespaces remain
independent. Registered identities govern strict composition, inheritance,
layering, and final typed values through ConfigKit. PromptKit retains its domain
validation, presence-aware settings, partial profiles, and exact runtime lookup.
Domain checks use PromptKit's interpreted values without mutating ConfigKit's
retained configuration or replaying source history.
Inherited and replaced prompt fields retain their contributing resource context.
Sensitive provider values remain protected in inspection at index-based paths.
@@ -259,6 +293,9 @@ GoDoc, and maintained examples describe the integrated target when it lands.
Migration guidance covers the new module/types, Go minimum, controls, import
requiredness, identified lists, explicit-ID source builders, sibling inheritance,
removed prompt labels, specification headers, and index-based inspection paths.
It also explains composed configuration inspection versus PromptKit's normalized
metadata and execution settings, including the absence of ConfigKit history for
PromptKit-side normalization/defaults.
Attribution identifies the selected ConfigKit revision and applicable notices.
Deliver this as one coordinated breaking pre-v1 minor upgrade under the existing

245
docs/roadmap/implementation.md
View File

@@ -1,14 +1,30 @@
# ConfigKit v1 And Identified Resources Implementation Plan
Status: ready for implementation.
Status: implementation in progress; resume with Stage 11's normalization recovery.
Implement the accepted [feature roadmap](configkit.md) as one end-to-end sprint.
Each sequentially numbered stage is one prompt-sized assignment for a Luna
coding agent. The roadmap owns intent and policy; this plan owns delivery steps.
## Resume Point And Contract Correction
Stages 1–10 have recorded implementation commits through `e01b232`. Testing in
the former Stage 11 exposed an incompatible assumption in this plan: ConfigKit
v1.0.0 audits a changed sequence as one atomic value, so a field-level record does
not cover that change. Recording the whole list would replace descendant origins
needed for relative resources and inspection.
Resume at the new Stage 11, then Stage 12, which implement the approved
execution-owned interpretation instead. The former unfinished Stages 11–20 are
now Stages 13–22. Preserve the existing uncommitted Stage 11 work and integrate
it into its corresponding assignments; do not reset or restart completed work.
Earlier completion records remain historical evidence, not proof that the revised
normalization target is already implemented. The revised instructions and
Delivery Decisions below govern the final state.
## Baseline And Working Rules
The reviewed baseline is `07a55e45f2a3c68918c12fe5caa3e814ee00227c`, with Go
The original reviewed baseline is `07a55e45f2a3c68918c12fe5caa3e814ee00227c`, with Go
1.26.0, ConfigKit v0.8.0 at the old module path, keyed resource mappings, and
descriptive prompt-version labels. No implementation changes accompany this
plan. The local ConfigKit checkout's v1.0.0 tag resolves to
@@ -99,10 +115,10 @@ Separate three things throughout the adapter:
- local identity: `record.ID`, validated with existing exact local-ID rules;
- runtime identity: existing namespace qualification of that local ID.
Use the index path for presence, normalization/default records, validation,
origins, and sensitivity. Use the full identity for execution-owned maps.
Mutate slice elements in place during resolution; avoid accidentally normalizing
only a range-variable copy. Preserve the retained ConfigKit tree as lists.
Use the index path for presence, validation errors, origins, and sensitivity.
Use the full identity for execution-owned maps. Preserve the retained ConfigKit
tree as composed lists; normalize/default owned interpretations rather than
mutating those lists or recording field/container replacements in them.
Build indexes in bounded passes over final records rather than repeatedly
searching lists by ID during execution. Keep existing inventory sorting; this
is not a promise that every operation is linear or that list order drives runs.
@@ -114,6 +130,59 @@ prevalidate sources or re-resolve history. Non-string/null/missing IDs fail
through the existing typed/schema/domain boundary as appropriate; there is no
filename fallback, trimming, or new namespace constraint.
### Execution-Owned Interpretation And Inspection
Keep one ConfigKit load and one interpretation of its final effective records.
The production resolver captures detached `EntryInfo` presence/null information
as needed but does not mutate resource lists. Never retain the callback context.
ConfigKit's registered final identity checks continue to run normally.
Construct owned normalized resource interpretations during the existing semantic
validation boundary, and validate those values using ConfigKit's `Validation`
context for source-located errors. This can reuse the private record/document
types and existing domain helpers; it does not need a second schema, generic
cloning framework, or a new public resolver API. Retain the interpreted values
for post-load target assembly and prompt materialization so that normalization
does not run again on every request. If validation fails, no engine is published.
Only the owned interpretation may be modified. Copy the slices and nested
structures that normalization writes, or construct fresh execution values;
replacing a field through a shared nested pointer can otherwise mutate the
ConfigKit tree indirectly. Preserve exact IDs, references, and record-to-index
association while constructing this interpretation. Read presence and origins
from ConfigKit, not from guesses based on zero/nil interpreted values. Existing
provider-map and snapshot ownership rules remain in place.
Preserve current domain normalization/defaulting behavior, including endpoints,
credential names, diagnostic settings, positive-concurrency queue defaults,
profile controls, prompt metadata/input names, session templates, output schema
paths, roles, and cache control. Do not change trimming or explicit-null semantics
merely because the transformation moves. Validate normalized values without
mutating the configuration passed to `Validate`. Keep normalization failures and
domain errors at their existing public boundary with concrete list-field paths.
Moved checks may now produce validation-phase rather than resolution-phase
ConfigKit diagnostics; preserve meaningful public error identity and source
locations rather than an obsolete phase-specific expectation.
Configuration inspection, metadata, explanations, and diffs expose ConfigKit's
composed values/provenance. PromptKit's normalization/defaults appear in its
interpreted metadata and effective execution views, not as ConfigKit resolution
events. For example, inspection may retain a padded endpoint and an omitted or
null queue capacity, while the execution backend has the normalized endpoint
and the existing default capacity. Do not insert those defaults into
`Result.Config`, fabricate normalization history, or add a second public report.
Existing `InspectPrompt`, `InspectProfile`, preparation, and diagnostic results
continue exposing the interpreted information their contracts already own.
Resolve `content_file` using the unchanged ConfigKit field origin and
`SourceContext`; interpreted list positions remain associated with those paths.
Do not save a parallel history-based source resolver or record whole-list
normalization merely to pass the mutation audit. This is final-value domain
interpretation under ADR 0001, not raw-source validation or another composition
pass. Upstream field-granular mutation support remains a
[future reevaluation](future.md#field-level-normalization-with-preserved-list-provenance),
not a prerequisite for finishing this sprint on v1.0.0.
### Layering And Resource Context
Within one strict tier, duplicate IDs fail. Across tiers, registered sequences
@@ -176,6 +245,8 @@ Scope: `go.mod`, `go.sum`, imports, and the existing ConfigKit adapter/facade.
and resolution recording calls to `RecordNormalization`/`RecordDerivedDefault`
as used. Recorded mutations must still perform their assignments; recording
methods do not assign values. Typed `Secret` references remain unchanged.
This is API migration guidance where recording is still used; the revised
production interpretation does not require resource-list mutation records.
3. Audit public inspection wrappers and their tests against the upstream release
note's complete rename table: version evidence, empty import selections,
fallback destination flags, import defaults, layer names, and history-limit
@@ -251,25 +322,30 @@ validation, indexing, prompt materialization, and older fixtures still expect
maps; those migrations are assigned to the following stages. Formatting and
`git diff --check` passed; execution of the new fixture remains deferred.
## Stage 4: Preserve Field Presence And Resolution At List Paths
## Stage 4: Preserve Field Presence And Interpretation At List Paths
Scope: backend/profile field capture, normalization, and defaulting in
`internal/configuration/load.go` and their focused tests.
Revised target: the recorded implementation below used ConfigKit resolution
mutations; Stage 11 replaces that mechanism with execution-owned interpretation.
1. Iterate records by index, retaining the local ID for full-ID state-map keys.
Replace resource `.Key(id)` paths with `.Index(i)` for effective fields.
2. Adapt `captureFields` and related helpers to query `EntryInfo` before defaults
and normalization. Preserve absent, null, explicit zero/false/empty, inherited,
and backend-completed settings using the current semantics.
3. Adapt `resolveBackends` and `resolveProfiles` to update the actual slice
elements and record precise field mutations. Keep existing endpoint,
credential-name, diagnostic-setting, and queue-capacity rules.
3. Interpret backend/profile records on owned copies rather than mutating the
actual ConfigKit slice elements. Keep existing endpoint, credential-name,
diagnostic-setting, and queue-capacity rules; do not record these changes
against ConfigKit list fields or entire lists.
4. Convert the existing focused default/presence fixtures. Update a same-ID
layered fixture to whole-record upsert rather than adding a hidden merge to
keep its previous expectation.
Validation: owning tests demonstrate explicit zeros/nulls, backend completion,
and recorded normalization at the correct list entries. No new readiness rule.
Validation: owning tests demonstrate explicit zeros/nulls and backend completion
in execution values while composed values and source origins stay unchanged.
No new readiness rule or ConfigKit normalization-event expectation.
Completion: backend and profile presence capture and resolution now use list
indexes and mutate the effective slice elements while retaining full-ID state
@@ -278,6 +354,9 @@ same-ID replacement fixtures. Their execution remains deferred: the package
still does not compile until the subsequent indexing, validation, and prompt
list migrations. Formatting and `git diff --check` passed.
Recovery required: this completion predates the atomic-list audit finding.
The revised production target and test expectations are assigned to Stage 11.
## Stage 5: Validate Final Records And Build Execution Indexes
Scope: `validateEffective`, `indexedBackends`, `indexedProfiles`, and
@@ -287,9 +366,10 @@ Scope: `validateEffective`, `indexedBackends`, `indexedProfiles`, and
full backend IDs from final records for ordinary profile-reference checks.
Keep namespace/local-ID syntax, model strings, and deferred prompt/default
readiness semantics unchanged.
2. Build backend/profile indexes using each record's ID and namespace. Update
capacity-policy and execution-target assembly to use those indexes and the
Stage 4 presence state. Do not inspect history or add a second ConfigKit load.
2. Build backend/profile indexes from interpreted records using each record's
ID and namespace, leaving `result.Config` as the composed inspection tree.
Update capacity-policy and execution-target assembly to use those indexes and
the Stage 4 presence state. Do not inspect history or add a second ConfigKit load.
3. Keep final inventories sorted and collection membership independent of list
position. Do not conflate local IDs in separate namespaces or resource kinds.
4. Convert target-focused fixtures and retain runtime override, provider-map,
@@ -306,18 +386,22 @@ duplicate fixture to identified lists. The focused tests remain deferred because
prompt materialization and remaining configuration fixtures have not yet been
migrated. Formatting and `git diff --check` passed.
Recovery required: Stage 11 switches runtime construction from raw retained
records to their owned normalized interpretation.
## Stage 6: Materialize Prompts From Effective List Entries
Scope: prompt resolution/capture in `internal/configuration/prompts.go` and
Scope: prompt interpretation/capture in `internal/configuration/prompts.go` and
prompt-input presence capture in `load.go`.
1. Iterate final prompt records using their IDs for runtime keys and their list
indexes for metadata paths, message paths, and validation errors. Remove the
raw prompt-label parameter from materialization; remaining internal label
plumbing is removed in Stage 9.
2. Adapt input-description/content-type presence capture and prompt defaulting
to the new paths. Continue compiling captured message/session templates and
validating effective output contracts only.
2. Adapt input-description/content-type presence capture to the new paths.
Normalize/default owned prompt interpretations, not ConfigKit list fields.
Continue compiling captured message/session templates and validating
interpreted output contracts only.
3. Resolve file-backed fields from their contributing origin and SourceContext
after imports, inherited prompt definitions, upsert, and index movement.
Share the existing lazy metadata snapshot across all resources, and preserve
@@ -338,6 +422,9 @@ loader tests still index resource maps and reference removed prompt metadata;
their conversion is assigned to later work. Formatting and `git diff --check`
passed.
Recovery required: Stage 12 moves remaining prompt normalization off ConfigKit
state and verifies resource origins after that change.
## Stage 7: Preserve Inspection And Sensitive-Value Handling
Scope: `internal/configuration/inspection.go`, configuration inspection/diff
@@ -347,8 +434,8 @@ facade tests, and path-specific metadata expectations.
list indexes, retaining the existing sensitive key policy and nested values.
Use ConfigKit v1's `Sensitive` hook and schema tags where already applicable.
2. Convert inspection queries and fixtures from resource-key paths to concrete
index paths. Retained effective output stays in list shape; runtime IDs are
not synthetic inspection mapping keys.
index paths. Retained output stays in composed list shape without PromptKit
normalization/default writes; runtime IDs are not synthetic inspection keys.
3. Preserve redaction in effective output, explanations, failure diagnostics,
metadata, and diffs through existing owning coverage. Include a replaced or
inherited sensitive record at a different index where it adds protection.
@@ -367,6 +454,9 @@ passed: `go test . -run '^TestConfigurationInspection' -count=1` with Go 1.27.0,
formatting, and `git diff --check`. Internal package tests remain deferred until
the remaining map-indexed loader fixtures are converted.
Recovery required: Stage 12 reconciles inspection expectations with composed
configuration versus interpreted execution values. Preserve the redaction work.
## Stage 8: Convert Public Source Builders To Explicit-ID Slices
Scope: `profiles.go`, `backends.go`, source-builder GoDoc, and owning construction
@@ -445,7 +535,77 @@ asserting the removed field is absent from representative values. The isolated
JSON contract suite passed on Go 1.27.0, as did formatting and `git diff --check`.
Remaining callers and the maintained example are assigned to later work.
## Stage 11: Verify Identified Composition And Inheritance
## Stage 11: Recover Backend And Profile Interpretation Without List Mutation
Scope: the production definition/resolver/validator in
`internal/configuration/load.go`, target assembly in `targets.go`, and the
focused normalization/presence tests. This is the first resumption assignment.
1. Preserve the existing in-progress definition extraction and integration tests.
Remove production resolver calls that mutate resource lists, including the
prompt-list call that Stage 12 replaces. Retain the six identity registrations
and read-only presence capture; do not add covering whole-list records.
2. Build owned backend/profile interpretations from the final typed records at
the semantic validation boundary. Reuse the private typed structures and
domain normalization helpers. Keep each record's original index/path and
exact ID, and detach nested state that interpretation modifies. Report
normalization failures through the validation context using those paths.
3. Preserve backend endpoints, credential-name handling, diagnostic endpoint/kind
normalization, queue defaults, profile controls, and absent/null/explicit
values. Keep `EntryInfo` capture separate from the interpreted defaults.
Validate owned values without modifying the supplied ConfigKit configuration.
4. Retain the interpreted values for runtime backend/profile/capacity assembly;
stop those paths from assuming `result.Config` has been normalized. Do not
mutate `Result.Config` after success or rebuild definitions on ordinary runs.
5. Update the existing backend-normalization/null-default test to check two
outcomes: normalized/defaulted execution values and unchanged composed
values with original field provenance. Remove its expectation of a ConfigKit
`ChangeNormalization` event for PromptKit's transformation. Retain tests for
explicit zero/false/null and the existing public configuration-error boundary.
Validation: targeted real-loader cases with a padded endpoint and positive
concurrency plus omitted/null queue capacity load on the selected v1.0.0 without
an unrecorded-change error. Their execution values keep current behavior, while
inspection does not acquire synthesized whole-list origins/defaults. Record
unrelated old-fixture failures for their assigned stages rather than restoring
mutating resolution to satisfy them.
## Stage 12: Recover Prompt Interpretation And Preserve Inspection Origins
Scope: prompt interpretation/materialization in `load.go`/`prompts.go` and the
owning prompt/inspection tests, completing Stage 11's production recovery.
1. Move prompt description/session, input-name/content-type/description, and
output-schema-path normalization into owned interpreted records. Reuse the
Stage 11 ownership pattern and existing message role/cache-control handling.
Clone nested output/input structures that are modified; do not trim IDs or
stored resource references. Validate interpreted names/settings so normalization
cannot conceal a duplicate input name or invalid output contract.
2. Materialize prompts from interpreted records while using the unchanged
ConfigKit effective field paths, origins, and `SourceContext` for file reads.
Preserve one lazy metadata snapshot across root/collection resources, content
capture/closure, and existing prompt hash and requirement metadata behavior.
3. Extend an existing imported/inherited-content case with prompt metadata that
actually needs trimming, including a resource from another directory and a
replaced/moved record as appropriate. Verify the correct file is read and the
field retains its contributing source even when other fields normalize.
4. Reconcile inspection/diff tests with the agreed views: ConfigKit composed
values/provenance versus PromptKit-normalized metadata and execution settings.
Verify that normalizing the owned interpretation leaves the retained values
and origins unchanged, including nested structures. Keep redaction coverage
and upstream composition/inheritance history; do not manufacture records for
PromptKit transformations or duplicate the full test matrix.
5. Search production resource interpretation for leftover `Normalize`, `Default`,
or `RecordNormalization` calls writing ConfigKit list fields. Remove the
obsolete mutation-only helpers where unused. Deliberate recorded whole-list
mutations in upstream-registration tests are separate and remain legitimate.
Validation: the source-origin regression and focused normalized metadata,
inspection, and redaction tests pass without whole-list normalization. Complete
the backend/profile/prompt recovery before continuing the existing integration
work. No upstream release, extra public API, or provenance repair layer is needed.
## Stage 13: Verify Identified Composition And Inheritance
Scope: `internal/configuration/load_test.go`, `targets_test.go`, and focused
configuration fixtures not yet converted.
@@ -470,7 +630,7 @@ configuration fixtures not yet converted.
Validation: real-loader tests assert effective behavior and structured diagnostic
identity/paths as appropriate, not complete upstream error wording or ordering.
## Stage 12: Complete Header, Origin, And Adapter Fixture Coverage
## Stage 14: Complete Header, Origin, And Adapter Fixture Coverage
Scope: remaining `internal/configuration` prompt, inspection, listing, and
source-context tests and `internal/engine` configuration fixtures.
@@ -485,12 +645,13 @@ source-context tests and `internal/engine` configuration fixtures.
existing schema's allowed/rejected shapes; do not create a new application
field just to demonstrate upstream control extraction.
4. Close any missing source-origin or sensitive-path cases identified in
Stages 6–7. Reuse those owning tests instead of repeating their matrix here.
Stages 6–7 and their recovery in Stages 11–12. Reuse those owning tests instead
of repeating their matrix here.
Validation: run the configuration and internal-engine packages together when
they compile. Correct production defects before adjusting meaningful assertions.
## Stage 13: Migrate Public Configuration, Inventory, And Scope Tests
## Stage 15: Migrate Public Configuration, Inventory, And Scope Tests
Scope: root construction, sources, inspection/diff, inheritance, profile
inspection, listing, and namespace contract tests.
@@ -510,7 +671,7 @@ inspection, listing, and namespace contract tests.
Validation: run the affected external-package contract tests using real ConfigKit
composition and offline sources. Do not add index/list-position guarantees.
## Stage 14: Migrate Internal Execution And Rendering Fixtures
## Stage 16: Migrate Internal Execution And Rendering Fixtures
Scope: remaining `internal/usecase`, `internal/prompt`, `internal/domain`, and
internal observation fixtures affected by resource lists or removed labels.
@@ -529,7 +690,7 @@ internal observation fixtures affected by resource lists or removed labels.
Validation: run the affected internal packages with final values and synthetic
sources. Resolve remaining label-related compilation errors in these packages.
## Stage 15: Migrate Public Preparation And Execution Contracts
## Stage 17: Migrate Public Preparation And Execution Contracts
Scope: root ordinary/prepared execution, concrete-request validation,
requirements, and capacity contract fixtures.
@@ -548,7 +709,7 @@ requirements, and capacity contract fixtures.
Validation: run the focused root preparation/execution/requirements tests using
existing injected clients or controlled HTTP transports, with no live provider.
## Stage 16: Migrate Public Diagnostics And Observation Contracts
## Stage 18: Migrate Public Diagnostics And Observation Contracts
Scope: root smoke diagnostic, observation, prepared-observation, and adapter
boundary fixtures not completed by Stage 10's serialization changes.
@@ -565,7 +726,7 @@ boundary fixtures not completed by Stage 10's serialization changes.
Validation: run these public contract tests offline; diagnostic operations in
tests use controlled transports, not actual backend endpoints or API keys.
## Stage 17: Update Maintained Examples And Benchmarks
## Stage 19: Update Maintained Examples And Benchmarks
Scope: the three `examples/go-library` workflows, their assets, and configuration-
dependent benchmarks and shared test helpers still using the old representation.
@@ -587,7 +748,7 @@ Validation: run all three examples through the semantic checker once runnable.
Use a short focused construction benchmark if needed to investigate a suspected
repeated-scan regression, not to claim unmeasured performance improvements.
## Stage 18: Document Formats And Internal Handoff
## Stage 20: Document Formats And Internal Handoff
Scope: `docs/formats.md`, `docs/internal/sources.md`, and other current internal
documents whose descriptions changed.
@@ -600,14 +761,17 @@ documents whose descriptions changed.
ConfigKit v1 for generic import/control/collection semantics rather than
copying its full reference or imposing additional authoring restrictions.
3. Explain final index-based presence/resource-context interpretation, captured
runtime indexes, sensitivity, and operator-only inspection. Update current
upstream references and obsolete mapping examples without rewriting accepted
ADR decision content or historical release notes.
runtime indexes, sensitivity, and operator-only inspection. Explain that
ConfigKit's composed values retain provenance while owned interpretations
carry PromptKit normalization/defaults; no leaf-level ConfigKit mutation or
synthetic whole-list history is required. Update current upstream references
and obsolete mapping examples without rewriting accepted ADR decision content
or historical release notes.
Validation: compare every current format example with the actual implemented
schema and owning tests. Exact Go declarations remain the API contract owner.
## Stage 19: Document One Coherent Consumer Migration
## Stage 21: Document One Coherent Consumer Migration
Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README,
remaining exported GoDoc, and toolchain/release preparation guidance.
@@ -620,6 +784,9 @@ remaining exported GoDoc, and toolchain/release preparation guidance.
minimum, actual root controls, optional imports/`required: true`, header 2,
removed prompt labels/JSON fields, changed inspection paths, and opaque hash
changes. Include the standalone-item header-versus-former-label distinction.
Explain that configuration inspection/diffs now retain composed values rather
than PromptKit-normalized/defaulted ones; the existing interpreted views serve
execution-setting inspection, with no new combined report or equality promise.
3. Update the current consumer/README examples and links to maintained artifacts.
Align toolchain/build guidance with the new minimum and the existing selected-
toolchain release procedure; do not introduce a separate release-tool upgrade,
@@ -633,7 +800,7 @@ Validation: render/read affected GoDoc; check local document links and snippets
against implemented APIs. Keep current documentation free of obsolete contracts;
old syntax may remain explicitly labeled in migration explanations and history.
## Stage 20: Verify The Integrated Sprint And Record Completion
## Stage 22: Verify The Integrated Sprint And Record Completion
Scope: acceptance review and residual corrections, not another feature stage.
@@ -641,7 +808,9 @@ Scope: acceptance review and residual corrections, not another feature stage.
proportionate existing tests: new dependency/types, source controls/header,
all six identity rules, builder order/duplicates, inheritance/upsert, effective
field paths, file origins, sensitivity, removed labels, and preserved runtime
operations. Close actual gaps at their owning boundary.
operations. Include the recovery distinction: normalized execution values
are valid without mutating ConfigKit's composed tree or its provenance.
Close actual gaps at their owning boundary.
2. Search current production code, tests, examples, module metadata, and current
docs for stale old-path imports, genuine old controls, prompt labels, keyed
resource fixtures, and version-1 headers. Classify intended migration examples,
@@ -677,4 +846,6 @@ diff establish sprint completion; intermediate checks alone do not.
None required to begin the sprint. The accepted roadmap settles module identity,
resource representation, layering/inheritance, source-builder inputs, header
policy, removed labels, and the coordinated breaking upgrade. Implementation
details above serve those decisions without adding consumer guarantees.
details above serve those decisions without adding consumer guarantees. The
approved execution-owned interpretation accommodates ConfigKit v1.0.0's atomic
sequence audit; upstream field-granular normalization is not an open dependency.