Plan shared source version checks

docs/roadmap/source-version-checks.md

@@ -1,7 +1,9 @@
 # Shared Source Version Checks Roadmap
 
-Status: design decisions settled; implementation has not started. Execute the
-stages below in order. This roadmap develops the partially accepted source-version request in
+Status: design decisions settled; implementation has not started. The
+[implementation plan](implementation.md) owns execution order, concrete API and
+integration decisions, and completion evidence. This roadmap develops the
+partially accepted source-version request in
 [PromptKit's proposal](promptkit-feature-request.md#partially-accepted-addition-shared-source-specification-checks)
 using the consumer's single `Definition.Version` policy. The design direction
 below incorporates the maintainer's subsequent decisions on lookup, consumption,
@@ -17,8 +19,8 @@ Different accepted declarations may coexist: ConfigKit does not require exact
 equality with the main declaration, impose SemVer, or invent an expected value.
 
 The consumer selects a load-wide enum on ordinary and layered options. Its zero
-value retains current behavior; exact exported names remain implementation design
-work. The same `Definition.Version` can be reused across loads with different
+value retains current behavior; the implementation plan selects exported names.
+The same `Definition.Version` can be reused across loads with different
 strictness. The three modes are:
 
 | Mode | Missing non-main declaration | Present non-main declaration |
@@ -164,118 +166,45 @@ destinations are implemented; the
   dedicated checked-version evidence. Existing sensitivity and inspection are
   primarily organized around application paths and retained application trees.
 
-## Ordered implementation plan
+## Acceptance outcomes
 
-### 1. Finalize the contract and integration design
+The completed feature supports all three modes through ordinary and layered
+public loading, with these observable outcomes:
 
-Select exact public mode and evidence type names within the agreed load-wide
-API, participation, main-path, inspection, and edge-case decisions. Define header
-lookup for nested paths and distinguish a missing member from an obstructing
-non-container ancestor. Specify consumption without broadening it into a generic transformation
-API. Preserve authored ancestors when consuming nested mapping headers as agreed;
-apply the agreed sequence-element removal and structural-overlap rejection rules.
+- One checker can accept several distinct source declarations. Rejected acquired
+  declarations fail the load even when later tiers would replace their payload.
+- Absence, explicit null, strings, exact decimal integers, and malformed selected
+  values follow the shared version vocabulary and selected mode.
+- Main retains its own declaration and is checked once; mounted main uses the
+  enabled mode's source-local interpretation, while NoSource and default mode
+  retain their documented behavior.
+- Every participating document role and supported acquisition kind follows the
+  same selected policy. Synthetic field operations and absent sources add no
+  document-header requirement.
+- Accepted non-main headers are consumed exactly, preserving authored empty
+  containers and ordinary sequence-removal semantics. Remaining payload retains
+  strict composition, precedence, protected-path rules, and ordinary versions
+  outside the selected header path.
+- Source evidence is detached, physically attributed, available without reopening
+  files, and subject to the agreed sensitivity rules. Warnings survive successful
+  checks; generated failure messages remain safe.
+- Effective values, presence, provenance, history, inheritance, rendering, diffs,
+  and resource contexts agree with remaining application payload. Consumed
+  declarations remain separate source evidence; main history stays ordinary.
+- Maintained public examples demonstrate gradual and required adoption with one
+  policy. Current API/configuration documentation describes the delivered
+  contract, and existing default-mode behavior remains covered.
 
-Record the change to main-only version ownership in an ADR and review public API
-compatibility under repository policy. Do not rewrite accepted ADR decisions or
-describe the feature as implemented before it lands. Existing default behavior
-must remain covered; tests must not turn incidental acquisition ordering or
-allocation choices into new guarantees.
-
-Completion: the three modes and every participating source role have defined
-lookup, callback, consumption, failure, and inspection semantics.
-
-### 2. Share declaration checking and integrate source acquisition
-
-Separate reusable version-value interpretation and checker reporting from the
-current main-only invocation. Carry the selected mode through ordinary and
-layered root APIs into the engine. Resolve source-local locations before mounting
-and perform non-main checks before composition or precedence can mask them.
-
-Consume only accepted non-main headers, retain their evidence, and apply existing
-placement to the remaining body. Integrate direct inputs, recursive imports, and
-selected overlays according to the selected participation contract. Continue
-checking remaining payload for protected-path claims. Preserve source identity,
-resource contexts, and applicable load accounting; consumed input still counts
-as acquired input rather than bypassing source limits.
-
-Avoid duplicate main checks or a second load of any document. Preserve the main
-declaration's final value and typed conversion behavior. Ensure warnings do not
-become failures merely because acquisition helpers previously treated any returned
-diagnostic as fatal. Keep returned hook errors safe and callback contexts closed.
-
-Completion: optional and required checks work across participating sources,
-incompatible superseded input fails, and disabled-mode loads remain unchanged.
-
-### 3. Expose evidence and verify lifecycle agreement
-
-Add the selected root-owned inspection records and explicit conversions. Retain
-source-local declarations and physical locations without fabricating effective
-payload paths. Apply the agreed disclosure treatment to retained evidence,
-including declarations consumed before final sensitivity evaluation. Return
-detached records and preserve evidence when source files subsequently disappear.
-
-Check agreement among configuration, provenance, history, rendering, and diff:
-main remains represented normally; consumed headers remain source evidence;
-ordinary version payload remains ordinary. Verify diagnostics identify the
-actual source even when several documents use the same local header path.
-Follow existing load-error reporting rather than promising exhaustive evidence
-for documents never acquired after an earlier failure.
-
-Completion: consumers can inspect checked declarations without reopening files,
-and evidence does not leak sensitive values or alter effective-value semantics.
-
-### 4. Add public acceptance coverage and update documentation
-
-Use focused engine tests for vocabulary, extraction, and consumption; root tests
-for public options and detached evidence; and executable consumer examples for
-multi-file loading. Cover these distinct behaviors without duplicating all
-existing import and composition tests:
-
-- all modes, with absent, null, string, decimal-integer, and malformed values;
-- multiple versions accepted by one checker without equality enforcement;
-- required missing declarations and incompatible inputs hidden by later layers;
-- main preservation and no duplicate callback, including the chosen mounted-main
-  interpretation and `NoSource` behavior;
-- direct underlays, transitive/glob imports, overlays, and every document source
-  kind; no header requirement for synthetic field overrides;
-- source-local lookup before input and relative-import destination placement;
-- nested-header consumption and retained empty containers; sequence-element
-  removal with shifted payload indexes and original evidence coordinates;
-- structural-directive overlap rejection without rejecting unrelated header paths
-  or ordinary keys containing directive spellings; remaining payload protection;
-- ordinary release/prompt version fields outside the header path;
-- warning propagation, safe checker failures, real source locations, and absent
-  header location fallbacks;
-- inspectable detached evidence and disclosure using disposable canaries, including
-  classified header/ancestor paths, historical classification, and safe failures;
-- consumed-header exclusion from effective rendering/diffs, with retained main
-  history and unchanged resource-relative behavior;
-- default-mode compatibility, including existing fragment version rejection.
-
-Demonstrate gradual adoption with optional checks and full declaration coverage
-with required checks, using one policy. Do not include independent collection
-checkers in examples. Update Go declaration documentation, the configuration
-contract, consumer guidance, and internal overview as behavior lands; reconcile
-the source-header request's earlier remaining-design notes then.
-
-Follow the [development guide](../development.md) and
-[testing policy](../policy/testing.md): focused checks during implementation,
-the everyday check before handoff, ownership race checks where applicable, and
-documentation-link validation. No independent performance benchmarks are part of
-this roadmap. Release preparation and publication are separate work.
-
-Completion: the agreed source coverage and three modes work through supported
-public APIs, inspection and disclosure agree with the contract, and validation
-and documentation are complete. Independent specification policies are not
-required to complete this feature.
+Independent specification policies, release preparation, and publication are
+outside this feature's completion criteria.
 
 ## Agreed Edge-Case Decisions
 
 The maintainer has accepted all three decisions below. Together with the mode
 API location, source participation, main-path handling, source-record evidence,
 and nested mapping ancestor preservation above, these settle the discussed
-product decisions. Exact public names and internal mechanics remain implementation
-work; the feature is not yet implemented.
+product decisions. The [implementation plan](implementation.md) selects public
+names and integration mechanics; the feature is not yet implemented.
 
 ### Sensitivity of consumed declaration evidence