Document and audit effective configuration diffs

docs/roadmap/deferred.md

@@ -23,12 +23,18 @@ The following remain deliberately excluded:
 - automatic schema migrations;
 - hot reload, runtime resource replacement, and remote resource validation;
 - a bundled CLI framework or application commands; and
-- configuration diffs and fingerprints.
+- configuration fingerprints.
 
 Applications may build their own validate, effective-value, source, bootstrap, and
 explanation commands around the library. Broadening these boundaries requires
 concrete consumer evidence, compatibility review, and an explicit design change.
 
+Effective configuration diffs are implemented over frozen successful-load
+inspections; their current comparison and disclosure contract is in the
+[configuration contract](../config.md#effective-configuration-diffs), with
+consumer workflows in the [adoption guide](../consumers/README.md#effective-configuration-diffs).
+Fingerprints remain deferred.
+
 Built-in sibling inheritance using `extends` is implemented as described in the
 [configuration contract](../config.md#sibling-inheritance). It is distinct from
 inheritance between selected overlay files, which remains excluded above.

docs/roadmap/diff.md

@@ -1,9 +1,9 @@
 # Effective Configuration Diff Roadmap
 
-Status: design agreed; implementation has not started. This document owns the
-targeted end state, selected contract, and work needed from the current baseline.
-The [implementation plan](implementation.md) owns execution order. No diff API
-is available yet.
+Status: implemented. This document preserves the selected contract and scope;
+the [configuration contract](../config.md#effective-configuration-diffs) owns
+current behavior, and the [implementation record](implementation.md) preserves
+the completed sequence and validation evidence.
 
 ## Targeted end state
 
@@ -158,11 +158,10 @@ renderer. A diff may describe removals that existing overlay semantics cannot
 express. These boundaries define this feature's selected scope, not intrinsic
 correctness restrictions on every possible future extension.
 
-## Current baseline
+## Implementation references
 
-- [Deferred scope](deferred.md) currently excludes configuration diffs and
-  fingerprints. This design reconsiders only the diff boundary; fingerprints
-  and unrelated exclusions remain deferred.
+- [Deferred scope](deferred.md) continues to exclude fingerprints and unrelated
+  items; effective configuration diffs are implemented.
 - The [configuration contract](../config.md#typed-projection-and-ownership)
   describes canonical typed projection and private structural comparison.
   [The existing comparator](../../internal/engine/document_compare.go) reports
@@ -181,69 +180,20 @@ correctness restrictions on every possible future extension.
 - The [public facade](../internal/overview.md) is root-owned and delegates to
   the engine. The new operation and records follow that same boundary.
 
-## Work needed from the baseline
+## Implementation outcome
 
-### Architecture and scope documentation
+The accepted inspection boundary is recorded in
+[ADR 0010](../adr/0010-effective-configuration-diff.md), and the deferred
+inventory retains fingerprints while recognizing implemented diffs. The engine
+owns canonical comparison and paired disclosure in
+[internal/engine/diff.go](../../internal/engine/diff.go); the root facade exposes
+detached records in [diff.go](../../diff.go). The configuration
+contract, consumer guidance, component overview, architecture policy, and
+development guide now link to their respective behavior and implementation
+owners.
 
-Record the inspection boundary extension in an ADR and reconcile the diff
-exclusion in `deferred.md`, retaining fingerprints and unrelated exclusions.
-Keep planned behavior here until implementation lands. The staged implementation
-plan should reference the selected contract above rather than reopen it.
-
-### Private comparison and disclosure
-
-Add an engine operation over two successful frozen inspections, reusing the
-existing comparator where its semantics match this contract. Sharing helpers
-must preserve resolution and validation auditing behavior.
-
-Implement cross-configuration masking, structural-replacement fallback, and
-`HiddenChanged`. Compare canonical values rather than serialized redacted
-output, caller-mutated configuration values, or historical replay. Construct
-the needed safe snapshots without replaying every path's full explanation
-history. Keep comparison and disclosure distinct so masking does not erase
-change detection.
-
-### Root API and consumer guidance
-
-Add root-owned records, the comparison entry point, and explicit conversion
-across the engine boundary. Document direction, equality, failures, ownership,
-secret behavior, and the credential limitation beside declarations.
-
-Add executable examples for loading both files and handling each load failure,
-and for comparing a base result with a base-plus-overlay result. Include
-resolution and sensitive nested values, demonstrating consumer-owned formatting
-and changed-secret indicators with disposable data.
-
-### Behavioral validation and completion
-
-Use engine tests for comparison and combined sensitivity, root tests for the
-facade and ownership, and consumer examples for the complete workflows. Cover
-meaningful risks without duplicating all existing loading tests:
-
-- equality despite mapping order, provenance, or explicit-input differences;
-  canonical equality after defaults and resolution;
-- addition/removal versus explicit null, empty containers, scalar and kind
-  replacements, atomic sequence changes, and escaped or numeric mapping keys;
-- deterministic ordering and reported subtree granularity;
-- changed and unchanged sensitive values, classification on only one side,
-  removed secrets, classified containers, and mixed public/sensitive changes;
-- cross-kind replacement of a classified descendant, incompatible key/index
-  shapes, and complete-region masking without changing absence semantics;
-- hidden changes with identical safe YAML, public-only changes alongside
-  unchanged masked values with `HiddenChanged=false`, and literal marker-like
-  input;
-- changed secret reference names and unchanged names with credential rotation,
-  using controlled environment state;
-- invalid left/right loads, unavailable results, caller mutation after loading,
-  and returned-record mutation isolation.
-
-Use disposable canaries to check non-disclosure, including failure paths. Follow
-the focused, everyday, ownership-race, and documentation checks in the
-[development guide](../development.md). New performance benchmarks are not
-required for this feature.
-
-Update the configuration contract, consumer guidance, and component overview
-when their behavior lands. Keep symbol details in Go declaration documentation.
-Review compatibility and release notes under the release policy; publication is
-separate from feature completion. Completion means the selected contract is
-implemented, checks pass, and maintained examples and documentation agree.
+Validation and coverage are recorded in the completed
+[implementation plan](implementation.md). The implementation compares frozen
+effective values, protects both sides with combined sensitivity, retains the
+selected credential boundary, and provides executable file and overlay
+workflows. Publication and release preparation remain separate.

docs/roadmap/implementation.md

@@ -1,8 +1,9 @@
 # Implement effective configuration diffs
 
-Status: planned. Audience: a Luna coding agent implementing one stage per prompt,
-in numerical order. The [diff roadmap](diff.md) owns the agreed target contract
-and scope. This document owns implementation steps and completion evidence.
+Status: complete. The [diff roadmap](diff.md) owns the agreed target contract and
+scope. This document preserves the implementation sequence and completion
+evidence; completed planning records retire during separately authorized release
+preparation.
 
 Planning baseline: `e82b1c90543a6ab92138ee8c0c2a4cd4daea8af0`.
 No diff API exists at this baseline. This plan adds comparison of successful
@@ -385,7 +386,7 @@ redaction marker; no full-context rendering supplements the diff records.
 
 ## Stage 10 — Reconcile documentation and audit the complete feature
 
-Status: planned. Scope: current-behavior documentation, integration audit, and
+Status: complete. Scope: current-behavior documentation, integration audit, and
 completion evidence; no release publication.
 
 1. Add an effective-diff section to `docs/config.md` for shared equality,
@@ -417,6 +418,20 @@ completion evidence; no release publication.
 Done: the agreed feature is implemented, validated, and documented without
 stronger unrelated guarantees or changes to the publication contract.
 
+Evidence: the planned feature baseline was `e82b1c90543a6ab92138ee8c0c2a4cd4daea8af0`;
+the reviewed implementation through consumer examples is commit `a37e689`,
+following the accepted decision at `3697a51` and public facade at `8ae542b`.
+The complete baseline-to-implementation diff was reviewed against this plan and
+the selected contract. `go test ./internal/engine -run 'Diff|Explain|History|Secret|Independent'`,
+`go test . -run 'Diff|FacadeInspection|PublicFacadeBoundary|DependencyImportBoundary'`,
+`go test ./examples/consumers`, `go test . -run '^ExampleDiff$'`, the local
+documentation-link test, and `./scripts/check.sh` passed on
+`go1.26.8 linux/amd64`. `GOTOOLCHAIN=local GOPROXY=off go test -race ./...` also passed.
+The feature does not compare resolved credential bytes or supply paired full-
+document rendering context; credential rotation behind the same reference is
+not reported. Fingerprints remain deferred, no performance claim is made, and
+release publication remains separate.
+
 ## Open Questions
 
 None required for this scope. The roadmap's four choices are approved; the