Initial Commit

openspec/archive/2026-05-02-env-spec-conformance/tasks.md

@@ -0,0 +1,32 @@
+# Tasks: env-spec-conformance
+
+## 1. Spec annotations
+
+- [x] 1.1 Add a real `**Verified by:**` line under every `### ENV-NN —` block in `openspec/specs/env/spec.md` for ENV-01 through ENV-17. No `deferred` / `follow-up` markers remain.
+
+## 2. Spec → impl alignment (spec is the contract)
+
+- [x] 2.1 `CoercionError` throws `ENV.INVALID_FORMAT` (not `ENV.COERCE_ERROR`); `COERCE_ERROR` removed from the registry. Tests + docs updated.
+- [x] 2.2 `createEnv` runs a fixpoint `${VAR}` interpolation pass over the merged values map before coercion (cross-loader interpolation works).
+- [x] 2.3 Wire `CreateEnvOptionsSchema`, `DotenvLoaderOptionsSchema`, `ObjectLoaderOptionsSchema` at the public boundaries of `createEnv`, `dotenvLoader`, `objectLoader`. Invalid options throw `EnvValidationError` with code `ENV.VALIDATION_FAILED`.
+- [x] 2.4 Wire OTel instruments in `createEnv` via `metrics.getMeter('suaveplan.env')`: `env.validation.total` counter, `env.validation.errors` counter, `env.load.duration_ms` histogram. Add `@opentelemetry/api` as a runtime dep.
+
+## 3. Impl → spec alignment (impl is the intended design)
+
+- [x] 3.1 `ENV-04` updated to spec the single-options `objectLoader({source, sourceName})` form.
+- [x] 3.2 `ENV-05` updated: `parseDotenv` silently skips malformed lines; `DotenvLoaderOptions.override` defaults to `false`.
+- [x] 3.3 `ENV-07` updated: `addRule()` on `BaseField`; `optional()`/`default()` lifted to each subclass because their return type narrows.
+- [x] 3.4 `ENV-09` updated: `ValidationResult` shape is `{ success, data, errors: ReadonlyArray<EnvError> }`.
+- [x] 3.5 `ENV-10` updated: `maskSensitive(schema, values)` argument order; mask glyph is `'****'`.
+
+## 4. New tests
+
+- [x] 4.1 `src/core/create-env/create-env.spec-conformance.test.ts` covers literal-type narrowing, loader-chain merge order, `parseDotenv` purity + interpolation chain, `dotenvLoader` missing-file fallback, `maskSensitive` non-mutation, `EnvValidationError.code === ENV.VALIDATION_FAILED`, `ENV_CODES.*` literal typing, cross-loader `${VAR}` interpolation, unresolved-token default, Zod boundary failures (createEnv / dotenvLoader / objectLoader), and OTel non-throwing instrumentation.
+- [x] 4.2 `tests/dep-graph.test.ts` flipped to assert `@opentelemetry/api` IS a runtime dep (ENV-14 contract).
+- [x] 4.3 `tests/tree-shake.test.ts` updated to reference `INVALID_FORMAT` instead of the removed `COERCE_ERROR`.
+
+## 5. Verify
+
+- [x] 5.1 `bunx turbo lint typecheck test --filter=@suaveplan/env` green.
+- [x] 5.2 `bunx turbo test:coverage --filter=@suaveplan/env` 100/100/100/100.
+- [x] 5.3 `bun scripts/openspec-conformance.ts @suaveplan/env` exits 0.