suaveplan/openspec/archive/2026-05-23-enterprise-control-surface-schema/tasks.md

Tasks — enterprise-control-surface-schema

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 Account for every .claude/worktrees/* entry; prune stale ones via bun scripts/worktree-prune.ts --remove.
• 0.3 Confirm MANIFEST.md matches find packages -maxdepth 3 -name package.json | wc -l.

1. Spec authoring

• 1.1 Draft proposal.md, tasks.md, specs/control-surface-schema/spec.md

2. Implementation

• 2.1 src/error-codes.ts — CONTROL_SURFACE_SCHEMA.* via defineCodes
• 2.2 src/types/transform.types.ts — Transform, Vec3, Vec2
• 2.3 src/types/binding.types.ts — Binding discriminated union (6 variants)
• 2.4 src/types/range.types.ts, behaviour.types.ts, appearance.types.ts, action.types.ts
• 2.5 src/types/control-kind.types.ts — 18-variant ControlKind enum
• 2.6 src/types/control-node.types.ts — ControlNode = Group | Control discriminated union
• 2.7 src/types/group-layout.types.ts — 4-variant GroupLayout
• 2.8 src/types/control-surface.types.ts — ControlSurface root
• 2.9 src/schemas/control-surface-schema.ts — Zod schemas mirroring every type
• 2.10 src/validate/validate.ts — validateSurface(unknown) returning typed result union
• 2.11 src/upgrade/upgrade.ts + migrations/ — upgradeSurface(unknown), chained migrations, registry pattern
• 2.12 src/walk/walk.ts — DFS visitor with parent-stack
• 2.13 src/identity/identity.ts — uuid generation, duplicate-id detection, binding-reference cross-check
• 2.14 src/constants.ts — CURRENT_SCHEMA_VERSION

3. Tests

• 3.1 Per-feature .test.ts covering every scenario in spec.md
• 3.2 tests/round-trip.test.ts — JSON serialise → validate → walk → re-serialise; deep-equal
• 3.3 tests/property.test.ts — fast-check generators for every node type; validator accepts only well-formed documents
• 3.4 tests/upgrade.test.ts — registered migrations apply in order; unknown version surfaces typed error
• 3.5 Every it(...) has { timeout: 5000 }

4. Documentation

• 4.1 Sibling .md per .ts (≥200 words, basic + advanced examples)
• 4.2 README with ## Surface document shape reference + 4 worked examples (4-pad drum machine, 8-channel mixer, piano keyboard, Traktor-style DJ surface)

5. Pre-archive verification

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/control-surface-schema — green
• 5.2 bunx turbo test:coverage --filter=@suaveplan/control-surface-schema — 100/100/100/100
• 5.3 bunx turbo build --filter=@suaveplan/control-surface-schema — green

6. Archive

• 6.1 Fold spec delta → openspec/specs/control-surface-schema/spec.md
• 6.2 Move folder → openspec/archive/<yyyy-mm-dd>-enterprise-control-surface-schema/
• 6.3 Refresh MANIFEST.md
• 6.4 Prune worktree