Add typed environment secret references

docs/roadmap/implementation.md

@@ -1233,7 +1233,39 @@ Acceptance:
 
 ## Stage 17 — Add environment-backed typed secret references
 
-Status: pending.
+Status: complete.
+
+Completion evidence (2026-09-06):
+
+- Added the opaque `Secret` and `SecretEnv` API in
+  [`secret_reference.go`](../../secret_reference.go), with name/value/resolution
+  accessors, name-only JSON, and credential-free formatting for every `fmt` verb.
+  The zero value remains an absent reference and no public constructor can inject
+  resolved credential state.
+- Extended the shared descriptor, decode, projection, clone, comparison, resolution,
+  and validation paths with a first-class secret-reference descriptor. References
+  project only their public names, cloned defaults are rebuilt unresolved, dynamic
+  `any` values cannot introduce secret semantics, and existing tag/predicate
+  classification continues to hide additionally sensitive names or derived data.
+- Inserted deterministic per-load environment resolution after recorded application
+  resolution and before semantic validation. Only effective valid names are read,
+  each unique success/unset/empty outcome is cached for that load, required and
+  optional shapes receive path-specific `secret.*` diagnostics, and `Load` performs
+  no environment writes. Validation compares private reference state with the lookup
+  cache in addition to the ordinary projected mutation audit.
+- Added focused coverage in
+  [`secret_reference_test.go`](../../secret_reference_test.go) for structs, maps,
+  pointers and sequences; successful and failed lookup deduplication; absent/null/
+  empty/invalid/unset cases; resolver-selected names; resolved-value validation;
+  same-name unresolved validator replacement; later-load environment changes;
+  stale resolved defaults; dynamic values; bootstrap blocked-empty integration; and
+  non-disclosure through fmt, JSON, effective projection, history, and diagnostics.
+  Added executable `ExampleSecretEnv` and updated the
+  [current secret-reference contract](../config.md#typed-secret-references), component
+  inventory, developer guide, and README. Verified `go test ./...`,
+  `go test -race ./...`, `go vet ./...`, `go build ./...`, `go mod tidy -diff`, and
+  `git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
+  CLI overrides remain later work.
 
 Read: [secret reference contract](initial.md#secret-references-and-explicit-bootstrap),
 shared descriptor/projection rules and lifecycle, Stage 16 report boundary.