suaveplan/openspec/archive/2026-05-09-i18n-shared/tasks.md

Tasks — @suaveplan/i18n-shared (runtime atoms for the i18n family)

Reconciled retroactively after Wave 1 shipped under commit 0e5b225a. Package is built, tested, and validated; this pass folds the spec delta into openspec/specs/i18n-shared/spec.md and archives the change folder.

1. Spec authoring

• 1.1 Cross-cutting design + AGENTS sections read
• 1.2 Source-mapping table populated against the monolith
• 1.3 proposal.md authored
• 1.4 specs/i18n-shared/spec.md delta drafted with 8 requirements
• 1.5 Every requirement carries a **Verified by:** line naming concrete it(...) titles
• 1.6 openspec change validate i18n-shared clean

2. Package scaffold

• 2.1 packages/i18n/i18n-shared/src/{constants,errors}/ structure
• 2.2 package.json — @suaveplan/i18n-shared@0.0.0, type: module, sideEffects: false, deps @suaveplan/error/@suaveplan/types/tslib, full exports map with subpaths
• 2.3 tsconfig.lib.json extends shared library config
• 2.4 vite.config.ts + vitest.config.ts for build + test
• 2.5 README.md with Modules table

3. Implementation — constants

• 3.1 src/constants/locale-bcp47-map.ts — LOCALE_BCP47_MAP (22 entries)
• 3.2 src/constants/rtl-locales.ts — RTL_LOCALES (Set) + RTL_LOCALE_LIST (tuple)
• 3.3 src/constants/locale-descriptors.ts — LOCALE_DESCRIPTORS, DEFAULT_LOCALES, DefaultLocale
• 3.4 src/constants/interpolation-defaults.ts — DEFAULT_INTERPOLATION (frozen as const)
• 3.5 src/constants/index.ts — explicit named re-exports

4. Implementation — error codes and class

• 4.1 src/errors/error-codes.ts — 18-code I18N_CODES registry + I18nErrorCode discriminant union
• 4.2 src/errors/i18n-error.ts — I18nError extends SuaveplanError<I18nErrorCode>, no biome suppressions
• 4.3 src/errors/index.ts — explicit named re-exports

5. Root barrel

• 5.1 src/index.ts — explicit named re-exports of constants + errors
• 5.2 Build emits all expected named exports

6. Documentation

• 6.1 src/constants/locale-bcp47-map.md
• 6.2 src/constants/rtl-locales.md
• 6.3 src/constants/locale-descriptors.md
• 6.4 src/constants/interpolation-defaults.md
• 6.5 src/errors/error-codes.md
• 6.6 src/errors/i18n-error.md
• 6.7 README links every .md

7. Tests (runner-neutral imports)

• 7.1 locale-bcp47-map.test.ts — short/mixed-case/canonical mapping cases
• 7.2 rtl-locales.test.ts — set membership + list parity
• 7.3 locale-descriptors.test.ts — descriptor coverage + RTL alignment
• 7.4 interpolation-defaults.test.ts — default values + as const narrowing
• 7.5 error-codes.test.ts — every code present, namespacing, cardinality
• 7.6 i18n-error.test.ts — construction, instanceof, cause chain, no biome suppressions
• 7.7 index.test.ts — every documented subpath resolves
• 7.8 byte-size.test.ts — bundle budget + sideEffects: false
• 7.9 Every it(...) carries { timeout: 5000 }
• 7.10 Runner-neutral imports (@suaveplan/testing/runner); CLAUDE.md §11 grep returns zero hits

8. Pre-archive verification

• 8.1 Biome clean
• 8.2 bunx turbo lint typecheck test --filter=@suaveplan/i18n-shared green at commit time
• 8.3 bunx turbo test:coverage --filter=@suaveplan/i18n-shared 100/100/100/100 at commit time
• 8.4 Conformance script clean
• 8.5 Build green

9. Pre-archive 7-row checklist

• 9.1 Generics — I18nError extends SuaveplanError<I18nErrorCode>
• 9.2 Zod schemas — N/A (constants/error class only)
• 9.3 Every error code constructable in i18n-error.test.ts
• 9.4 Strict-mode tested — expectTypeOf as const preservation
• 9.5 OTel — N/A (atoms, no spans)
• 9.6 Lifecycle dedup — N/A (no lifecycle)
• 9.7 No retroactive tick — boxes ticked during reconciliation pass after honest audit

10. Archive

• 10.1 Spec delta folded into openspec/specs/i18n-shared/spec.md (canonical, status ACTIVE, 8 requirements)
• 10.2 Folder moved to openspec/archive/2026-05-09-i18n-shared/
• 10.3 MANIFEST.md already lists the package (added during initial scaffold)