Initial Commit

openspec/archive/2026-05-02-bytes-spec-conformance/proposal.md

@@ -0,0 +1,45 @@
+# bytes-spec-conformance
+
+- **Change ID**: bytes-spec-conformance
+- **Package**: `@suaveplan/bytes`
+- **Status**: PROPOSED
+- **Type**: spec-conformance
+- **Date**: 2026-04-26
+
+## Why
+
+The folded `openspec/specs/bytes/spec.md` documented the public surface as
+`### encoding` / `### uint8` / `### uuid` Module sections plus a flat list of
+function signatures. The conformance parser accepts only `### Requirement: <name>`
+or `### CAP-NN — <name>` headings, so `bun scripts/openspec-conformance.ts
+@suaveplan/bytes` reported "0 requirements parsed" — a parsing gap, not a
+contract gap. The implementation already satisfies every clause; this change
+makes those clauses machine-checkable and pins each one to existing tests.
+
+## What changes
+
+- Rewrite `openspec/specs/bytes/spec.md` from prose-module headings to seven
+  `### Requirement: <name>` blocks with `#### Scenario:` subblocks and
+  `**Verified by:**` lines that name concrete `it(...)` titles in the
+  existing test suite.
+- No source changes; no public-surface changes; no new tests required —
+  every scenario is already pinned by `src/encoding/encoding.test.ts`,
+  `src/uint8/uint8.test.ts`, and `src/uuid/uuid.test.ts`.
+
+## Out of scope
+
+- New behaviour. This is heading rewrite + verification annotation only.
+- Source mapping table — `@suaveplan/bytes` is genesis-original; there is
+  no `../suaveplan/enterprise/bytes.md` to cite.
+
+## Verification approach
+
+Every requirement is pinned to `it(...)` titles in the existing tests:
+
+- `src/encoding/encoding.test.ts` — encoding round-trips, error paths.
+- `src/uint8/uint8.test.ts` — uint8 utilities, format detection, conversion façade.
+- `src/uuid/uuid.test.ts` — UUID round-trip and validation.
+
+## Migration impact
+
+None — additive metadata only. Public surface unchanged.