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

Tasks: env-spec-conformance

1. Spec annotations

• 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)

• 2.1 CoercionError throws ENV.INVALID_FORMAT (not ENV.COERCE_ERROR); COERCE_ERROR removed from the registry. Tests + docs updated.
• 2.2 createEnv runs a fixpoint ${VAR} interpolation pass over the merged values map before coercion (cross-loader interpolation works).
• 2.3 Wire CreateEnvOptionsSchema, DotenvLoaderOptionsSchema, ObjectLoaderOptionsSchema at the public boundaries of createEnv, dotenvLoader, objectLoader. Invalid options throw EnvValidationError with code ENV.VALIDATION_FAILED.
• 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)

• 3.1 ENV-04 updated to spec the single-options objectLoader({source, sourceName}) form.
• 3.2 ENV-05 updated: parseDotenv silently skips malformed lines; DotenvLoaderOptions.override defaults to false.
• 3.3 ENV-07 updated: addRule() on BaseField; optional()/default() lifted to each subclass because their return type narrows.
• 3.4 ENV-09 updated: ValidationResult shape is { success, data, errors: ReadonlyArray<EnvError> }.
• 3.5 ENV-10 updated: maskSensitive(schema, values) argument order; mask glyph is '****'.

4. New tests

• 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.
• 4.2 tests/dep-graph.test.ts flipped to assert @opentelemetry/api IS a runtime dep (ENV-14 contract).
• 4.3 tests/tree-shake.test.ts updated to reference INVALID_FORMAT instead of the removed COERCE_ERROR.

5. Verify

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/env green.
• 5.2 bunx turbo test:coverage --filter=@suaveplan/env 100/100/100/100.
• 5.3 bun scripts/openspec-conformance.ts @suaveplan/env exits 0.