suaveplan/openspec/archive/2026-05-24-enterprise-controller/tasks.md

Tasks — enterprise-controller

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree and worktree-isolation verified (pwd is .claude/worktrees/agent-…)
• 0.2 Worktree branch renamed to feat/controller
• 0.3 Confirm STATUS.md lists @suaveplan/controller as – (pending migration)

1. Spec authoring

• 1.1 Read upstream source at ../suaveplan/packages/universal/controller/src/
• 1.2 Draft proposal.md with Source mapping + deferred Out-of-scope section
• 1.3 Draft specs/controller/spec.md with 9 requirements + **Verified by:** lines
• 1.4 Confirm no openspec/specs/controller/ exists yet (forbidden until archive)

2. Implementation (Priority 1)

• 2.1 Scaffold packages/gaming/games/controller/ with package.json, vite.config.ts, vitest.config.ts, tsconfig.lib.json, README.md
• 2.2 src/types/controller.types.ts + .md — ControllerInput, Vector2D, callback aliases
• 2.3 src/schemas/options.schemas.ts + .md — Zod schemas for every options bundle
• 2.4 src/errors/controller-error.ts + .md — defineCodes + ControllerError
• 2.5 src/observability/otel.ts + .md — counter + attribute helpers
• 2.6 src/event-emitter/event-emitter.ts + .md + .test.ts
• 2.7 src/base/base-controller.ts + .md + .test.ts — Clock-injected, threshold/deadzone
• 2.8 src/keyboard/keyboard-controller.ts + .md + .test.ts
• 2.9 src/gamepad/gamepad-controller.ts + .md + .test.ts
• 2.10 src/controller-merger/controller-merger.ts + .md + .test.ts
• 2.11 src/index.ts — explicit named re-exports per CLAUDE.md rule 10

3. Tests

• 3.1 Every requirement's **Verified by:** test exists and passes
• 3.2 Errors test enumerates CONTROLLER_CODES and asserts each is thrown
• 3.3 OTel test uses real in-memory MeterProvider (no vi.mock)
• 3.4 Every it(...) has { timeout: 5000 } (30000 for async)
• 3.5 All test files import runner primitives from @suaveplan/testing/runner

4. Documentation

• 4.1 Sibling .md ≥200 words for every implementation .ts
• 4.2 README.md links every co-located .md under ## Modules
• 4.3 Update root CLAUDE.md to list @suaveplan/controller under ### Games (universal-tier)

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0/0/0 across monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/controller green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/controller 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/controller exit 0
• 5.5 bunx turbo build --filter=@suaveplan/controller green

6. Pre-archive 7-row checklist

• 6.1 Generics threaded; no any
• 6.2 Zod schemas wired at every constructor options boundary
• 6.3 Every CONTROLLER_CODES entry thrown by a real path
• 6.4 Strict-mode/destroyed-state behaviour tested both on and off
• 6.5 OTel asserted with in-memory MeterProvider
• 6.6 destroy() dedup tested
• 6.7 No retroactive ticks

7. Archive

• 7.1 Fold specs/controller/spec.md into openspec/specs/controller/spec.md
• 7.2 Move change folder to openspec/archive/2026-05-24-enterprise-controller/
• 7.3 Refresh MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts