Document sequence composition for consumers

docs/roadmap/future.md

@@ -15,11 +15,12 @@ PromptKit repository at
 PromptKit selected mounted mappings instead; this feature is not a dependency
 of that design or a request to restore multiple installed prompt versions.
 
-A narrower [sequence placement and composition roadmap](sequence-composition.md)
-now covers placing source mappings as sequence items, single-field identities,
-duplicate rejection during strict composition, and whole-sequence replacement
-between precedence layers. The additional capabilities below remain deferred
-and are not requirements of that roadmap.
+A narrower [sequence placement and composition feature](../config.md#strict-document-composition)
+is implemented: consumers can place imported mappings as sequence items and
+register a single literal string identity field for duplicate-rejecting strict
+composition. Precedence still replaces sequences as whole values. This entry
+tracks broader identified-record behavior that remains deferred and is not part
+of that implemented contract.
 
 ### Motivation and proposed behavior
 
@@ -27,13 +28,16 @@ Allow applications to declare that selected sequences contain records identified
 by explicit fields, while retaining sequence-shaped output for slice decoding
 and effective YAML. This could make composite identities and independently
 authored catalogs more convenient than encoding identity in nested mapping keys.
-Current [composition](../config.md#strict-document-composition) and
-[overlay](../config.md#selected-overlays) treat sequences atomically.
+Current [composition](../config.md#strict-document-composition) appends distinct
+records only at explicitly registered paths; other sequences remain atomic.
+Selected [overlays](../config.md#selected-overlays) always treat sequences
+atomically.
 
-The proposed opt-in registration belongs in the reusable application definition:
-an exact effective sequence path after input/import placement, plus an ordered,
-nonempty set of distinct direct string-field names. For example, records at
-`profiles` could be identified by `(namespace, id)`. Records `(provider, brief)`
+The proposed broader opt-in registration would extend the current reusable
+application definition from one identity field to a composite identity made of
+an ordered, nonempty set of distinct direct string-field names. For example,
+records at `profiles` could be identified by `(namespace, id)`. Records
+`(provider, brief)`
 and `(application, brief)` would coexist, and a later layer could update the
 provider record's temperature while retaining its backend and model.
 

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Sequence Placement and Composition
 
-Status: implementation in progress; stages 1–12 completed.
+Status: implementation in progress; stages 1–13 completed.
 
 ## Purpose and authority
 
@@ -756,6 +756,24 @@ Validation: executable example/consumer tests, local documentation-link tests,
 whitespace review, and `./scripts/check.sh`.
 Completion: current docs and tested public examples describe what actually lands.
 
+Completion evidence: the canonical configuration contract and architecture
+policy now describe placement, registered strict composition, version/header
+boundaries, source containers, history, and unchanged precedence. README,
+consumer, development, and internal guides link to those contracts and the
+maintained prompt-catalog example. The example uses disposable in-repository
+fixtures to demonstrate path/glob item imports, a helper-supplied identity,
+strict composition, whole-sequence replacement of defaults, and consumer-owned
+validation. The feature roadmap and ADR status point to the implemented contract
+and delivery record; broader composite-identity behavior remains deferred.
+These checks passed with Go `go1.26.9 linux/amd64`:
+
+- `GOTOOLCHAIN=local GOPROXY=off go test ./examples/consumers`
+- `GOTOOLCHAIN=local GOPROXY=off go test -race ./...`
+- `GOTOOLCHAIN=local GOPROXY=off ./scripts/check.sh`
+- `git diff --check`
+
+No environmental limitation affected validation; checks ran on Linux/amd64.
+
 ## Stage 14 — Review the completed unit and hand off
 
 - Read the complete implementation diff against `2051177` and the feature

docs/roadmap/sequence-composition.md

@@ -1,8 +1,9 @@
 # Sequence-Item Placement and Identity-Based Composition
 
-Status: design decisions settled; not implemented. This roadmap owns the target
-state and accepted behavior. The [implementation plan](implementation.md) owns
-concrete API/syntax choices, execution order, validation, and progress.
+Status: implemented. This roadmap records the target state and accepted behavior.
+The [configuration contract](../config.md#strict-document-composition) defines
+the current behavior, and the [implementation plan](implementation.md) records
+delivery sequencing and validation.
 
 ## Goal and current baseline
 
@@ -11,13 +12,12 @@ files. Placement makes a source mapping one sequence item; identity-based strict
 composition combines distinct items and rejects repeated identities. These are
 complementary operations, with explicit consumer opt-in.
 
-Current [input destinations](../config.md#input-destinations) place source
-mappings beneath mapping-key paths. Imports support immediate-parent-relative
-destinations. Current [strict composition](../config.md#strict-document-composition)
-combines mappings recursively and rejects other overlaps, while
-[precedence assembly](../config.md#layered-loading) and
-[selected overlays](../config.md#selected-overlays) replace sequences wholesale.
-Neither sequence-item placement nor sequence-composition registration exists today.
+Sources can explicitly place mappings as sequence items at non-root destinations,
+and definitions can register literal sequence paths with one literal string
+identity field for duplicate-rejecting strict composition. Ordinary unregistered
+sequences retain strict conflict behavior. [Precedence assembly](../config.md#layered-loading)
+and [selected overlays](../config.md#selected-overlays) continue to replace
+sequences wholesale. The canonical contract documents the exact rules and limits.
 
 This roadmap covers a narrower feature than the
 [identified record sequences candidate](future.md#1-identified-record-sequences).