Initial Commit

openspec/archive/2026-04-29-utils-spec-conformance/proposal.md

@@ -0,0 +1,66 @@
+# utils-spec-conformance
+
+- **Change ID**: utils-spec-conformance
+- **Package**: `@suaveplan/utils`
+- **Status**: PROPOSED
+- **Type**: spec-conformance
+- **Date**: 2026-04-26
+
+## Why
+
+The folded `openspec/specs/utils/spec.md` documented the public surface as
+`### ./errors`, `### ./debug`, `### ./object`, … module sections with bullet
+lists of function signatures. The conformance parser only sees `###
+Requirement: <name>` or `### CAP-NN —` headings, so the audit reported "0
+requirements parsed". The implementation already satisfies every clause;
+this change makes them machine-checkable and pins each scenario to existing
+tests.
+
+## What changes
+
+- Rewrite `openspec/specs/utils/spec.md` from `./<module>` section headings
+  to ten `### Requirement: <name>` blocks, one per module:
+  - debug logger with bounded dedup buffer
+  - object utilities (type guards, deepMerge, pick/omit, flattenObject,
+    getNestedValue, deepClone)
+  - platform detection with injectable adapter
+  - IEEE 754 float packing and range constants
+  - pseudorandom array selection
+  - provider-aware email normalization
+  - sound-sprite parsing and variation selection
+  - string utilities (id generation, link extraction)
+  - hex string validation
+  - byte-size enforcement and parsing
+
+- Add `**Verified by:**` lines under every requirement naming concrete
+  `it(...)` titles in the corresponding `*.test.ts` files (10 test files,
+  169 cases pre-dating this change).
+- No source changes; no public-surface changes.
+
+## Out of scope
+
+- New behaviour. Heading rewrite + verification annotation only.
+- `errors` is not a separate requirement block — error semantics are
+  asserted via the codes raised in each module's requirement (object
+  prototype-pollution, random empty/oob, validation size/parse, platform
+  unavailable, sound no-variations).
+- Source mapping table — `@suaveplan/utils` is genesis-original.
+
+## Verification approach
+
+Every requirement is pinned to existing `it(...)` titles in:
+
+- `src/debug/debug.test.ts`
+- `src/object/object.test.ts`
+- `src/platform/platform.test.ts`
+- `src/number/number.test.ts`
+- `src/random/pseudo.test.ts`
+- `src/email/email.test.ts`
+- `src/sound/sound.test.ts`
+- `src/string/string.test.ts`
+- `src/validate/validate.test.ts`
+- `src/validation/size.test.ts`
+
+## Migration impact
+
+None — additive metadata only. Public surface unchanged.