Finalize the ConfigKit roadmap and implementation plan

docs/policy/architecture.md

@@ -61,7 +61,10 @@ remote acquisition, runtime initialization, and resource checks.
 
 Library code must not depend on consuming applications or initialize their
 runtime resources. It must not perform implicit network access, discover
-application-specific paths, or change process-global state to load configuration.
+application-specific paths, or change process-global state during ordinary `Load`.
+The explicit secrets-directory bootstrap is a narrow, opt-in exception: applications
+invoke it during startup, and it reports writes, skips and partial failures. It
+must never run implicitly as part of configuration loading.
 Remote data can enter through application-supplied input without introducing a
 network provider into the library.
 
@@ -90,10 +93,20 @@ parser defaults. Processing order and diagnostics must be deterministic for the
 same inputs and options. Invalid input must not produce a successful usable
 configuration. Do not run application hooks on invalid typed configuration.
 
-Preserve presence and source information through processing. Ordinary Go zero
+User-controlled precedence is application defaults, composed base, selected
+profile, then explicitly supplied CLI overrides. Applications own flag parsing;
+ConfigKit owns overlay semantics and provenance. Domain resolution follows these
+inputs and must remain recorded, not become a hidden override channel.
+
+Preserve node-based composition until the effective input is ready for typed
+decoding. Preserve presence and source information through processing. Ordinary Go zero
 values must not be used to infer whether input was absent. Final configuration,
 metadata, and effective inspection must agree, including application resolution
 changes; see [ADR 0003](../adr/0003-preserve-presence-and-resolution-history.md).
+Safe historical values and an explanation renderer belong to the initial target,
+including superseded/deleted paths and effective source attribution. Inspection
+must agree with the final typed snapshot and apply historical sensitivity rules.
+See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
 Detailed syntax and operation tables belong to the target roadmap until their
 current configuration contract is implemented.
 
@@ -104,6 +117,14 @@ ConfigKit must not mutate a result after returning it. Ordinary exported Go
 values are not language-enforced immutable objects; document caller ownership
 and the lifetime of captured metadata without promising otherwise.
 
+Secret values enter configuration through typed environment-name references;
+literal credentials are not a supported configuration convention. Only an explicit
+accessor exposes a resolved credential to application code. Credential bytes must
+never enter composition trees, history, or inspection. General environment-variable
+configuration overlays are an explicit non-goal. Bootstrap must preserve already
+set variables, including empty ones, and report blocked files without contents.
+See [ADR 0004](../adr/0004-secret-references-and-explicit-bootstrap.md).
+
 Secrets must be considered throughout error handling and inspection. Library
 renderers must apply secret classification, and parser errors must not be
 forwarded blindly when they can include raw input. Do not log configuration

docs/policy/documentation.md

@@ -29,8 +29,7 @@ semantics, defaults, paths, diagnostics, or compatibility guarantees.
 - Roadmaps own unimplemented targets, deferred work, and execution status.
 
 The initial target and implementation plan have separate owners. Do not put
-staged steps or progress in `docs/roadmap/initial.md`. The future
-`docs/roadmap/implementation.md` will own those details when it is created.
+staged steps or progress in `docs/roadmap/initial.md`. `docs/roadmap/implementation.md` owns those details.
 As behavior lands, move its normative definition into the current contract and
 replace the roadmap definition with a link. Retire completed roadmap material
 as part of release preparation; ADRs preserve significant decision history.
@@ -65,13 +64,13 @@ handling, not secret values.
 | Release rules | `docs/policy/release.md` | Compatibility, integrity, gates, immutability, and exceptions |
 | Release procedure | `docs/release.md`, when operational | Exact maintainer commands, prerequisites, supported targets, and verification |
 | Exported Go API | Go documentation beside declarations | Symbol contracts, errors, ownership, and lifecycle API behavior |
-| YAML and resolution semantics | `docs/config.md`, as behavior lands | Syntax, composition, precedence, conversion, and metadata semantics; Go reference docs link here for shared rules |
+| YAML and resolution semantics | `docs/config.md`, as behavior lands | Syntax, composition, precedence, conversion, secret references/bootstrap, and explanation semantics; Go reference docs link here for shared rules |
 | Consumer walkthroughs | `docs/consumers/`, when useful | Task-oriented usage and consumer responsibilities, not duplicate API reference |
 | Component inventory | `docs/internal/overview.md` | Implemented components and links to their owners |
 | Component mechanics | Other `docs/internal/` files, when needed | Detailed implementation behavior and change recipes |
 | Architectural decisions | `docs/adr/` | Context, decisions, alternatives, consequences, and supersession history |
 | Initial target | `docs/roadmap/initial.md` | Unimplemented end-state and deferred feature scope |
-| Implementation plan | Future `docs/roadmap/implementation.md` | Stages, dependencies, acceptance gates, and progress |
+| Implementation plan | `docs/roadmap/implementation.md` | Stages, dependencies, acceptance gates, and progress |
 | Release readiness gaps | `docs/roadmap/release-readiness.md` | Outstanding release prerequisites and closure evidence |
 | Historical release notes | `docs/releases/` | Version-specific historical summaries required by release policy |
 | Complete examples | `examples/` and executable Go examples | Maintained artifacts; prose links instead of duplicating full examples |

docs/policy/testing.md

@@ -29,6 +29,15 @@ Use focused fuzzing for parser boundaries and semantic/filesystem path handling;
 keep deterministic seed regressions in the ordinary suite. Extended fuzz runs
 need a documented bounded invocation when introduced.
 
+Secret bootstrap tests must cover existing variables including empty values,
+preflight without writes, partial apply failures, and safe blocked-file reporting.
+Use controlled environment names and restore state; process-mutating tests must
+not run in parallel. Keep real filesystem coverage and use narrow private seams
+for deterministic environment/write failures. Verify full input precedence and
+safe historical values, including removed and replaced secrets, at their owning
+boundaries. No credential bytes may appear in inspection or failure fixtures'
+expected output; use disposable canaries to prove non-disclosure.
+
 Baseline commands belong in the [development guide](../development.md). Release
 gates belong in the [release policy](release.md) and its eventual runbook. This
 policy does not imply that those tools or tests already exist.