diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index eb3df2b..6606792 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -94,3 +94,39 @@ or cross-path parent references are requested. Keep the feature deferred until its consumer value and full lifecycle design justify reconsidering the sequence-merging exclusion. A correct final sequence alone would not establish correct inspection or disclosure behavior. + +## 2. Required version declarations for selected sources + +Status: deferred. PromptKit requested a way to require version declarations on +a selected subset of source files while permitting other fragments to omit them. + +### Motivation and proposed behavior + +PromptKit could require each collection's root file (for example, +`collection.yml` or `meta.yml`, with naming still undecided) to declare an +accepted specification version. Other files would use the existing +[check-when-present behavior](../config.md#shared-source-version-checks). +This would enforce a rule that otherwise remains a documentation convention. + +All declarations would use the same application-owned `Definition.Version` +path and acceptance policy. The proposal concerns where declarations are +required; it does not introduce independently versioned collections or subtrees. +A root declaration would not prove that headerless descendants declare a +compatible version or replace final configuration validation. + +### Questions to resolve before implementation + +- **Selection API:** should callers mark explicit inputs, select sources by + path or predicate, or annotate imports? An input-level requirement is simpler, + but cannot by itself select a root reached only through an import. +- **Scope:** does a requirement apply only to the selected document or also to + its imports? Applying it only to that document best fits PromptKit's request; + imported fragments could still declare versions checked by the shared policy. +- **Mode interaction:** how should selection interact with disabled source + checks? Require an enabled mode, or activate checking for selected sources? + Selection would strengthen check-when-present behavior and add no requirement + beyond the load-wide required mode. +- **Source handling and evidence:** how should selection work across file, + reader, byte, and mapping inputs, glob matches, and repeated imports? Define + behavior for absent optional inputs and preserve source-local diagnostics, + inspection evidence, and existing sensitivity handling.