promptkit/docs/roadmap/implementation.md

# ConfigKit v1 And Identified Resources Implementation Plan

Status: ready for implementation.

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.

## Baseline And Working Rules

The 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
`c88aac990b23f48a31f9046b830d4d0954f57f53`; its release note and configuration
contract were reviewed for the decisions below.

Upstream references are the [v1 migration note](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c88aac990b23f48a31f9046b830d4d0954f57f53/docs/releases/v1.0.0.md)
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c88aac990b23f48a31f9046b830d4d0954f57f53/docs/config.md).
The local `../ConfigKit` checkout can supply the same tagged documentation for
development; it is not a committed dependency replacement or a test prerequisite.

Before each assignment, use [development orientation](../development.md) and
read the applicable [agent](../policy/agents.md),
[architecture](../policy/architecture.md), [testing](../policy/testing.md),
[documentation](../policy/documentation.md), [OSS](../policy/oss.md), or
[release](../policy/release.md) policy. Preserve the accepted
[configuration-boundary ADR](../adr/0001-configuration-boundary.md).

- Complete stages in order. Intermediate stages may fail compilation or tests
  belonging to later stages. Record those known dependencies and continue;
  do not add compatibility shims, duplicate fixtures, or temporary architectures
  merely to make each checkpoint green. The completed sprint must be coherent.
- Dependency/API migration precedes the list migration to isolate the kinds of
  changes, not to require a separate release or a fully migrated intermediate
  test suite. Convert each substantive fixture to its final form once where
  practical.
- Use focused validation when the affected package can run. When it cannot,
  review the changed code and defer execution to the identified later stage.
  Do not report deferred checks as passing. There are no intermediate human
  approval, downstream release, catalog publication, or live-provider gates.
- After a completed nonempty unit, record its completion and checks beneath its
  stage and commit under the agent policy. Do not create empty commits. Update
  exact GoDoc as declarations change; final documentation stages reconcile the
  wider narrative.
- Keep scope to the roadmap. PromptKit's module path, generation behavior,
  capacity policy, runtime overrides, and application ownership remain intact.
  This sprint does not authorize tagging, pushing, or changes in other projects.

## Delivery Decisions

### Dependency, Controls, And Headers

Select `go.maximumdirect.net/configkit v1.0.0` directly and declare
`go 1.27.0`. Use a locally available Go 1.27-or-newer toolchain that meets the
consumer minimum, with the same selected toolchain for maintainer tooling and
checks. Do not pin the consumer minimum to its incidental patch release.
Keep the existing ReleaseKit selection and publication workflow unless a
concrete build incompatibility requires attention; ConfigKit's upstream tool
dependency alone is not a reason to migrate PromptKit's release machinery.

Rename actual source-root `configkit:` controls to `config:`; leave nested
application data and `configkit:"secret"` tags alone. Replace removed import
`optional` fields with `required` values. Use `required: true` where a maintained
example or fixture needs a file to exist; do not set a global required-import
default. A test of missing optional imports must keep that intended behavior.

Keep `SourceVersionModeIfPresent`. The existing `VersionRule` checks exact text
`2` rather than `1`; upstream parsing permits string `"2"` or strict decimal
integer `2` and rejects unsupported types. Headerless documents remain valid.
Source-local headers, collection `release_version`, and ConfigKit software
versions are separate concepts. A standalone prompt item's root `version` is
only a source header; there is no remaining prompt-version label.

### Typed Resources, Paths, And Identity

Use slices of resource structs for root and collection `Backends`, `Profiles`,
and `Prompts`, with `ID string` bound as `yaml:"id"` on each internal record.
Keep `Collections` as `map[string]collectionConfig`. Preserve the other field
types and allowed domain values except for removal of the prompt label.
ConfigKit consumes `extends`; internal resource structs need no parallel
inheritance field or relationship interpreter.

Register these six destination rules on the one loader definition:

| Destination | Registration | Identity |
| --- | --- | --- |
| Root `backends`, `profiles`, `prompts` | One `SequenceIdentityAt(configkit.Keys(kind), "id")` per kind | Direct `id` |
| `collections/<any-key>/backends`, `profiles`, `prompts` | One `SequenceIdentityMatching` per kind using literal `collections`, `SequenceAnyMappingKey()`, and literal kind | Direct `id` |

Use `configkit.SequenceSelector` with `SequenceLiteralKey` segments for each
dynamic selector. A literal `"*"` namespace is not the wildcard selector.
Register once without discovering source documents or enumerating namespaces.
Missing destinations need no artificial empty value or declaration.

Separate three things throughout the adapter:

- effective path: resource-list base plus `.Index(i)`, then the actual field;
- 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.
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.

ConfigKit owns duplicate-identity checks, composition, final registered-identity
checks, and sibling inheritance. PromptKit owns accepted shapes, string-ID
syntax, domain settings, final references, and prompt materialization. Do not
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.

### Layering And Resource Context

Within one strict tier, duplicate IDs fail. Across tiers, registered sequences
default to upsert, replacing a matching record in full. Explicit append/replace
remain upstream operations; an empty append/upsert adds nothing, while explicit
replacement with `[]` clears the list. Do not recreate the old fieldwise merge
between same-ID records. Mapping overlay within inherited records is still
ConfigKit behavior, and backend-to-profile setting completion stays PromptKit
behavior; neither is removed by whole-record upsert.

All three resource kinds can use `extends: {id: parent}` within the same list.
Parents are ordinary validated resources, children retain their own identities,
and only surviving records supply parents. Self-extension cannot recover a
displaced lower-tier record. Keep partial profiles valid until request
completion; do not introduce abstract records or prompt-specific inheritance
restrictions.

Resolve each effective `content_file` through its final index-based field origin
and contributing `SourceContext`, including inherited fields and moved/replaced
records. Keep the existing construction-wide lazy metadata snapshot, synchronous
content capture, handle closure, and captured runtime lookups. Origins are
resource-resolution information from the handoff, not a source-history audit.

### Public Builders And Removed Labels

The final builder signatures are:

```go
func ProfileSource(label string, profiles []ProfileConfig) configkit.Source
func BackendSource(label string, backends []BackendConfig) configkit.Source
```

Add `ID string` to both public config structs. Preserve existing optional field
types, including `ProfileConfig.Extends *string`; when non-nil, encode it as
`extends: {id: *config.Extends}` rather than a scalar reference. Omission remains
omission. Both builders emit explicit-ID record lists in supplied order, retain
duplicates for ConfigKit to reject on loading, preserve existing ownership of
provider maps/diagnostic values, and do not independently validate definitions.
No map overload, new backend inheritance convenience, or public prompt builder
is required. Backend/prompt inheritance is available through configuration.

Remove prompt-version fields, parameters, copying, formatting, and JSON
`prompt_version` members throughout domain, application, and facade values.
Keep `PromptIdentity` as an ID-only struct and retain the existing listing return
type rather than redesigning it as a string slice. Preserve prompt hashes as
opaque equality values; removing a hashed field can change them. Keep collection
release labels, ConfigKit version evidence, session IDs, and unrelated version
identifiers. No replacement label or consumer compatibility alias is needed.

## Stage 1: Adopt The Module, Toolchain, And Renamed APIs

Scope: `go.mod`, `go.sum`, imports, and the existing ConfigKit adapter/facade.

1. Select Go 1.27 or newer locally, set the consumer minimum to 1.27.0, and
   replace the old ConfigKit requirement with the new module at v1.0.0. Prepare
   dependency sums through ordinary Go tooling. Do not commit workspace files or
   filesystem replacements.
2. Update imports in production, tests, and examples. Migrate `Definition.Secret`
   to `Definition.Sensitive`, `Resolution.InputInfo` to `Resolution.EntryInfo`,
   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.
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
   diagnostics. Change symbols/expectations actually used here, not unrelated
   identifiers by global text substitution.
4. Update the ConfigKit attribution entry to the selected commit above, the new
   source repository, and its verified COPYRIGHT/LICENSE notices. Review resolved
   module changes, including any additional tooling dependency, proportionately.

Validation: check the module diff and imports; attempt focused adapter builds
when source controls permit. Record any toolchain/dependency-access failure
accurately. Do not use local substitution as the delivered dependency state.

Completion: selected Go 1.27.0 and ConfigKit v1.0.0 at the specified commit,
updated imports, adapter API names and attribution, and audited the upstream
rename table against the facade and tests. The existing ReleaseKit selection
remains unchanged; ConfigKit's separate tool dependency appears in the resolved
module graph. Validation passed: focused adapter and facade compilation, the
configuration header-check test, module/import review, formatting, and
`git diff --check`. Source controls and resource-shape fixtures remain for the
subsequent assignments.

## Stage 2: Migrate Source Controls And Import Expectations

Scope: actual configuration controls in fixtures, programmatic sources, and
maintained example assets; application resource shape can still be transitional.

1. Rename source-root controls to `config` in main documents, imported files,
   collection entries, test strings, and programmatic maps. Inspect context for
   each change rather than replacing every occurrence of `configkit`.
2. Convert removed `optional` fields and make intended required imports explicit.
   Preserve tests whose purpose is optional selection. Keep directory patterns,
   recursion, destinations, import opt-in, and filesystem roots as selected by
   the caller; do not invent glob `**` semantics or directory discovery rules.
3. Update source-evidence assertions for ConfigKit v1 names and `main` layer
   spelling. Test meaningful source attribution rather than preserving historical
   source order, complete rendering, or incidental history-event counts.

Validation: use the existing source-helper/import tests when runnable; otherwise
record remaining resource-shape dependencies. Leave source headers for Stage 3.

Completion: source-root import controls now use `config`, with the selected
file imports explicitly required. Reviewed source-evidence assertions and found
no obsolete API or main-layer spellings in use. Validation passed: the native
and embedded collection input tests, directory/filesystem source-helper tests,
and inherited imported-content test on Go 1.27.0; `git diff --check` passed.
Resource formats and headers remain for the following assignments.

## Stage 3: Introduce Identified Record Shapes And Header Version 2

Scope: schema types and loader definition in `internal/configuration/load.go`.

1. Convert the six root/collection resource fields to slices and add record IDs.
   Remove `promptConfig.Version`; retain document `Version` and collection
   `ReleaseVersion`. Do not decode both mapping and list formats.
2. Add all six identity registrations exactly as described above. Advance the
   optional checker to exact specification version 2 without changing its mode.
3. Adapt `resourceSet`/`resourceSets` to expose slices and their existing base
   paths. Preserve root and arbitrary collection traversal without pre-scanning
   inputs. Keep namespace syntax validation at the effective configuration.
4. Update one small adapter fixture to the final shape to exercise registered
   root and dynamic destinations; do not migrate the entire suite in this stage.

Validation: inspect the registration selectors and schema; when runnable, load
one headerless root list and one version-2 collection. Resolution/validation
callers are completed in the following stages.

Completion: the typed document now uses identified resource slices, registers
all six root and collection identity rules, and checks specification version 2.
Added a focused root/collection list fixture and reviewed the selectors and
schema. The focused test cannot yet compile because field capture, resolution,
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

Scope: backend/profile field capture, normalization, and defaulting in
`internal/configuration/load.go` and their focused tests.

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.
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.

Completion: backend and profile presence capture and resolution now use list
indexes and mutate the effective slice elements while retaining full-ID state
keys. Converted focused normalization, null/default, profile-presence, and
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.

## Stage 5: Validate Final Records And Build Execution Indexes

Scope: `validateEffective`, `indexedBackends`, `indexedProfiles`, and
`internal/configuration/targets.go`.

1. Validate local IDs and settings at final index-based paths. Build the set of
   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.
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,
   credential omission, concurrency, and queue-policy behavior.

Validation: target tests cover a root resource, namespaced resources sharing a
local ID, and partial-profile completion. Upstream duplicates must fail before
an execution map can silently overwrite a record.

Completion: final backend, profile, and prompt IDs and references are validated
at list-entry paths; backend and profile runtime indexes use full identities.
Added root and independent namespace target coverage and converted the strict
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.

## Stage 6: Materialize Prompts From Effective List Entries

Scope: prompt resolution/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.
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
   content-handle closure and post-construction capture.
4. Convert/extend the existing native and in-memory filesystem tests with
   inherited prompt content and a replaced record from another directory. Use
   distinctive synthetic file contents to prove which source contributed it.

Validation: owning prompt tests prove correct content and input metadata after
inheritance/replacement, including file edits not changing a constructed engine.
Do not normalize a whole list solely to update a field and lose its origins.

Completion: prompt capture, normalization, input presence, and materialization
now use effective list indexes and full runtime IDs, preserving the shared lazy
origin snapshot. Converted native, explicit-context, inherited-import, and
replacement content fixtures. Focused execution is deferred because older
loader tests still index resource maps and reference removed prompt metadata;
their conversion is assigned to later work. Formatting and `git diff --check`
passed.

## Stage 7: Preserve Inspection And Sensitive-Value Handling

Scope: `internal/configuration/inspection.go`, configuration inspection/diff
facade tests, and path-specific metadata expectations.

1. Adapt provider-extra sensitivity matching for root and collection resource
   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.
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.
4. Retain the existing thin ConfigKit wrappers. Do not add inspection methods
   merely because upstream v1 offers them, or invoke inspection during a run.

Validation: converted inspection/diff tests find the expected values/origins and
do not disclose synthetic credentials. Relax only assertions tied to deliberate
upstream history/diagnostic changes, not meaningful redaction expectations.

Completion: sensitivity matching and inspection paths now recognize resource
list indexes. Public inspection and diff fixtures use identified lists and
ConfigKit's atomic sequence comparison, including replaced and inherited
sensitive values, metadata, failure diagnostics, and detached reports. Validation
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.

## Stage 8: Convert Public Source Builders To Explicit-ID Slices

Scope: `profiles.go`, `backends.go`, source-builder GoDoc, and owning construction
tests. Other callers are migrated in later stages.

1. Implement the exact public signatures and fields in Delivery Decisions.
   Emit slice records with explicit `id`; preserve caller order and duplicates.
2. Encode non-nil profile `Extends` as an identity mapping. Preserve omitted
   options, explicit false/zero values, provider-map copying, and diagnostic
   configuration ownership. Leave value validation to loading.
3. Convert owning builder tests to slices. Check ordered output and that duplicate
   records reach loading and are rejected rather than silently deduplicated.
   Retain a public profile-variant test through real ConfigKit inheritance.

Validation: the public construction/source-builder tests demonstrate the new
input shape and ownership. Do not add map compatibility or builder-only ID rules.

Completion: profile and backend builders now accept ordered explicit-ID slices,
preserve duplicates and owned values, and encode profile inheritance by sibling
identity. Migrated their owning construction callers and added focused tests
for order, copying, duplicate rejection, and real profile inheritance. Validation
passed: the isolated source-builder contract tests and `go build .` on Go 1.27.0,
formatting, and `git diff --check`. The full root test package remains deferred
until later callers are converted to the new signatures.

## Stage 9: Remove Internal Prompt-Version Propagation

Scope: domain values, prompt requirement snapshots, hashes, use cases, and
observation recording; facade cleanup follows in Stage 10.

1. Remove prompt `Version`/`PromptVersion` from domain definitions, identities,
   prepared/run/inspection/requirement/smoke values and internal snapshot types.
   Remove corresponding parameters, assignments, and label-only clone helpers.
   Preserve helpers still needed for collection labels or other optional values.
2. Update prompt hashing, render/requirement snapshots, runner preparation,
   prepared-execution cloning, profile-independent inspection, smoke selection,
   and observation recording to use prompt identity without a label.
3. Remove internal tests exclusively about absent/empty/inherited prompt labels.
   Keep their independent snapshot-ownership and hash/metadata protections by
   exercising retained fields, not by deleting the wider regression coverage.

Validation: focused domain/use-case tests when runnable and symbol searches for
remaining label plumbing. Do not promise old hash values or remove source-version
checks, collection release labels, or session metadata.

## Stage 10: Remove Public Prompt Labels And Serialized Fields

Scope: `types.go`, `listing.go`, `requirements.go`, `observations.go`,
`smoke_diagnostics.go`, `convert.go`, formatting, and owning JSON tests.

1. Remove public prompt-version fields and their conversions, including
   `PromptIdentity.Version`; preserve the ID-only struct and listing method shape.
2. Remove `prompt_version` JSON fields from prepared/results, observation, and
   diagnostic values wherever present. Update redacted formatting and exact
   GoDoc to avoid referring to removed metadata.
3. Adapt existing JSON contract tests to verify the field is absent from the
   affected representative public values. Retain the existing unrelated
   serialization, ownership, and sensitive-data checks.

Validation: compile the facade when remaining fixtures permit and run JSON
contract tests. Search production code for stale prompt labels, separating
unrelated version fields from the removed feature.

## Stage 11: Verify Identified Composition And Inheritance

Scope: `internal/configuration/load_test.go`, `targets_test.go`, and focused
configuration fixtures not yet converted.

1. Convert remaining loader fixtures to explicit-ID lists and identity-reference
   `extends`. Keep malformed-shape cases malformed for their intended reason.
2. Cover all six identity registrations without duplicating the generic upstream
   matrix: root kinds plus dynamic collection kinds, duplicate strict peers,
   arbitrary namespaces including a literal `*` or numeric-looking namespace,
   and equal local IDs in different kinds/namespaces.
3. Through the real PromptKit loader definition, test final registered-identity
   enforcement using a package-local test seam for supported application
   resolution if needed. Reuse/extract the loader definition rather than writing
   a parallel test-only registration list or adding a public resolver API.
4. Cover surviving parent/child inheritance for profiles, backends, and prompts;
   child identity; missing/cyclic/self parents via upstream error propagation;
   valid ordinary parents; and partial profiles completed by requests.
5. Cover whole-record layered upsert, explicit append/replace, empty upsert versus
   clearing replacement, and replaced lower-tier invalid domain values not being
   separately validated. Preserve failure on upstream syntax/structural errors.

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

Scope: remaining `internal/configuration` prompt, inspection, listing, and
source-context tests and `internal/engine` configuration fixtures.

1. Finish fixture conversion without recreating label-specific tests. Preserve
   local import roots, explicit-null cases, input metadata, static syntax,
   snapshot ownership, and sorted inventory behavior.
2. Cover headers `2` and `"2"`, headerless entry/fragments/items, rejected
   declared version 1 and malformed declared types, and rejection of the old
   resource mapping shape. Do not require every document to declare a header.
3. Keep nested application `config` data distinct from source controls. Use the
   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.

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

Scope: root construction, sources, inspection/diff, inheritance, profile
inspection, listing, and namespace contract tests.

1. Convert YAML, programmatic mappings, and builder callers to final lists and
   explicit IDs. Remove prompt labels without changing the purpose of each test.
2. Change same-ID customization fixtures deliberately: use distinct inherited
   variants for field customization, or retain same-ID records when whole-record
   replacement is the behavior under test. Do not silently change replacement
   into inheritance in tests intended to protect precedence.
3. Preserve full-ID listings/filtering, global namespace/collection inventories,
   metadata-only collections, independent namespaces, shared scoped-engine
   ownership, and unchanged exact stored references.
4. Confirm the public facade accepts new-module ConfigKit inputs and exposes
   new-module inspection values; old-path type aliases/adapters are not needed.

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

Scope: remaining `internal/usecase`, `internal/prompt`, `internal/domain`, and
internal observation fixtures affected by resource lists or removed labels.

1. Convert source-backed fixtures and builder callers. Remove direct internal
   struct labels and assertions only about the removed metadata; retain prompt
   ID, body/output, session, usage, and substantive observation assertions.
2. Reuse current runner, requirements, prepared-execution, and smoke-selection
   tests to confirm captured full identities remain their selection input.
   Keep tests using direct execution-owned values independent of YAML where
   they already protect that separate boundary.
3. Preserve renderer behavior, structural repairs, transient retries,
   cancellation, and resource snapshots through their existing owning tests.
   Do not redesign those mechanisms or introduce runner-time list searches.

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

Scope: root ordinary/prepared execution, concrete-request validation,
requirements, and capacity contract fixtures.

1. Convert remaining YAML, programmatic definitions, and builder callers for
   Run, Prepare, PrepareExecution/RunPrepared, ValidateRequest, and
   InspectRequirements. Retain their established substantive outcomes.
2. Keep runtime overrides, artifact/schema ownership, appended messages,
   cancellation, prepared-handle isolation, and shared capacity coverage at the
   boundaries that already own it. Update frozen-rendering/source fixtures
   without reintroducing prompt-label metadata.
3. Distinguish intentional whole-record replacement from inherited variants in
   request-level fixture layering; do not weaken test expectations to accommodate
   a broken adapter or add new upstream-availability requirements.

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

Scope: root smoke diagnostic, observation, prepared-observation, and adapter
boundary fixtures not completed by Stage 10's serialization changes.

1. Convert diagnostic backend/profile/prompt sources and observation fixtures to
   the final shape. Keep exact configured references, selection precedence,
   tri-state findings, timing/usage, partial cancellation, and disclosure checks.
2. Preserve observation event order and metadata that remain contractual while
   removing only the prompt label. Reuse existing retry/repair and injected-client
   evidence tests rather than repeating their transport matrices.
3. Confirm scoped smoke diagnostics and ordinary runs resolve from the same
   captured indexes and retain their existing client/capacity ownership.

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

Scope: the three `examples/go-library` workflows, their assets, and configuration-
dependent benchmarks and shared test helpers still using the old representation.

1. Convert preparation collections/fragments, run prompt assets, and observation
   prompt assets to identified lists. Include the item-import workflow using
   `placement: sequence-item` and a headerless resource file under an explicit
   collection input. Keep synthetic IDs/models and source-relative content.
2. Update Go builder callers to ordered explicit-ID slices and imports to the
   new module. Keep the examples' distinct purposes and expected execution
   outcomes; only update `scripts/check-examples.py` if an intentionally changed
   output shape requires it.
3. Migrate benchmark fixture generators and remaining common test helpers.
   Preserve the construction-wide origin-metadata optimization and the existing
   benchmark's usefulness; do not add allocation/time pass thresholds or a new
   benchmarking release gate.

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

Scope: `docs/formats.md`, `docs/internal/sources.md`, and other current internal
documents whose descriptions changed.

1. Document specification 2, optional per-source headers, collection mappings
   containing identified resource lists, exact ID rules, and preserved provider
   model strings. Remove prompt-label fields; retain collection release labels.
2. Describe sibling identity inheritance across the three kinds, ordinary parent
   validation, partial profiles, and same-ID whole-record replacement. Link to
   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.

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

Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README,
remaining exported GoDoc, and toolchain/release preparation guidance.

1. Add the v0.16-era mapping-to-list upgrade to the migration guide while retaining
   useful older identity/deployment guidance. Show explicit IDs, sibling identity
   references, same-ID whole-record replacement, and source-builder map-to-slice
   conversion with a distinct variant where customization is intended.
2. Explain the new import path and incompatible Go type identities, Go 1.27.0
   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.
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,
   CI wait, consumer publication check, or new platform support promise.
4. Identify this as one breaking pre-v1 minor migration. Actual version selection,
   release-note creation, tagging, and publication remain normal separately
   authorized release preparation. Do not make Scriptorium publication a sprint
   gate or modify Scriptorium in this task.

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

Scope: acceptance review and residual corrections, not another feature stage.

1. Trace every target section of the feature roadmap to implementation and
   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.
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,
   historical release notes, unchanged tags, and unrelated version fields rather
   than demanding zero textual matches.
3. With the selected Go toolchain and prepared dependencies, run:

   ```sh
   GOTOOLCHAIN=local GOWORK=off go test -race ./...
   GOTOOLCHAIN=local GOWORK=off go vet ./...
   GOTOOLCHAIN=local GOWORK=off python3 scripts/check-examples.py
   git diff --check
   ```

   Format changed Go files and validate affected local Markdown links. Review
   the final module graph/sums and absence of committed workspace/local
   replacements. These are sprint checks, not an extra publication command or
   new permanent release gates. Reuse successful checks for unchanged content.
4. Verify the only intended API breaks are those selected by the roadmap and
   upstream type migration. In particular, do not add ID normalization, required
   headers/imports, profile readiness, abstract parents, source auditing, or
   execution-order semantics. Review final status/diff for unrelated material.
5. Record completion and validation in this plan and mark the feature roadmap
   complete. Commit the final nonempty unit; leave retirement and publication to
   normal release preparation. Report remaining failures honestly if the full
   target has not been reached.

Validation: the acceptance trace, integrated checks above, and reviewed final
diff establish sprint completion; intermediate checks alone do not.

## Open Questions

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.