From 0b026861a5e07b137f6f2a1c769b3ac580b83088 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 2 Nov 2026 12:20:44 +0000 Subject: [PATCH] Revise configuration plans to preserve source provenance --- docs/roadmap/configkit.md | 47 ++++++- docs/roadmap/implementation.md | 245 ++++++++++++++++++++++++++++----- 2 files changed, 250 insertions(+), 42 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index fcb4a8c..87d9af6 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index be53d9f..97f4fb4 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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.