lib: idea schemas + status mappers + transition guards (M12 T-493)

- lib/schemas/idea.ts: ideaCreateSchema, ideaUpdateSchema, ideaPlanMdFrontmatterSchema
  (yaml-frontmatter contract for materialize-step parser)
- lib/idea-status.ts: bidirectional DB↔API mapping, canTransition state-machine
  guard, isIdeaEditable + isGrillMdEditable + isPlanMdEditable helpers
- includes auto-regen docs/erd.svg from prisma generate

Tests: 26 cases (status round-trip, transitions valid/invalid, schema validation
edge-cases, priority bounds, verify-enum).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

__tests__/lib/idea-schemas.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  ideaCreateSchema,
+  ideaUpdateSchema,
+  ideaPlanMdFrontmatterSchema,
+} from '@/lib/schemas/idea'
+
+describe('ideaCreateSchema', () => {
+  it('accepts minimal valid input', () => {
+    const r = ideaCreateSchema.safeParse({ title: 'Plant-watering reminder' })
+    expect(r.success).toBe(true)
+  })
+
+  it('trims and enforces non-empty title', () => {
+    const r = ideaCreateSchema.safeParse({ title: '   ' })
+    expect(r.success).toBe(false)
+  })
+
+  it('rejects oversized title and description', () => {
+    expect(ideaCreateSchema.safeParse({ title: 'x'.repeat(201) }).success).toBe(false)
+    expect(
+      ideaCreateSchema.safeParse({ title: 'ok', description: 'x'.repeat(4001) }).success,
+    ).toBe(false)
+  })
+
+  it('accepts cuid-like product_id', () => {
+    const r = ideaCreateSchema.safeParse({
+      title: 'Idee',
+      product_id: 'cmohrysyj0000rd17clnjy4tc',
+    })
+    expect(r.success).toBe(true)
+  })
+
+  it('rejects non-cuid product_id', () => {
+    const r = ideaCreateSchema.safeParse({ title: 'Idee', product_id: 'not-a-cuid' })
+    expect(r.success).toBe(false)
+  })
+})
+
+describe('ideaUpdateSchema', () => {
+  it('allows empty object (no-op update)', () => {
+    expect(ideaUpdateSchema.safeParse({}).success).toBe(true)
+  })
+
+  it('allows partial title update', () => {
+    expect(ideaUpdateSchema.safeParse({ title: 'Updated' }).success).toBe(true)
+  })
+})
+
+describe('ideaPlanMdFrontmatterSchema', () => {
+  const validPlan = {
+    pbi: { title: 'Test PBI', priority: 2 },
+    stories: [
+      {
+        title: 'Eerste flow',
+        priority: 2,
+        tasks: [
+          { title: 'Setup', priority: 2, implementation_plan: '1. Doe X' },
+        ],
+      },
+    ],
+  }
+
+  it('accepts a minimal valid plan', () => {
+    expect(ideaPlanMdFrontmatterSchema.safeParse(validPlan).success).toBe(true)
+  })
+
+  it('requires at least one story', () => {
+    const r = ideaPlanMdFrontmatterSchema.safeParse({ ...validPlan, stories: [] })
+    expect(r.success).toBe(false)
+  })
+
+  it('requires at least one task per story', () => {
+    const r = ideaPlanMdFrontmatterSchema.safeParse({
+      ...validPlan,
+      stories: [{ ...validPlan.stories[0], tasks: [] }],
+    })
+    expect(r.success).toBe(false)
+  })
+
+  it('validates priority bounds 1-4', () => {
+    expect(
+      ideaPlanMdFrontmatterSchema.safeParse({
+        ...validPlan,
+        pbi: { ...validPlan.pbi, priority: 5 },
+      }).success,
+    ).toBe(false)
+    expect(
+      ideaPlanMdFrontmatterSchema.safeParse({
+        ...validPlan,
+        pbi: { ...validPlan.pbi, priority: 0 },
+      }).success,
+    ).toBe(false)
+  })
+
+  it('accepts optional verify_required + verify_only', () => {
+    const r = ideaPlanMdFrontmatterSchema.safeParse({
+      ...validPlan,
+      stories: [
+        {
+          ...validPlan.stories[0],
+          tasks: [
+            {
+              title: 'Verify-only task',
+              priority: 2,
+              verify_required: 'ALIGNED_OR_PARTIAL',
+              verify_only: true,
+            },
+          ],
+        },
+      ],
+    })
+    expect(r.success).toBe(true)
+  })
+
+  it('rejects invalid verify_required enum', () => {
+    const r = ideaPlanMdFrontmatterSchema.safeParse({
+      ...validPlan,
+      stories: [
+        {
+          ...validPlan.stories[0],
+          tasks: [
+            { title: 't', priority: 2, verify_required: 'INVALID' },
+          ],
+        },
+      ],
+    })
+    expect(r.success).toBe(false)
+  })
+})

__tests__/lib/idea-status.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  ideaStatusToApi,
+  ideaStatusFromApi,
+  canTransition,
+  isIdeaEditable,
+  isGrillMdEditable,
+  isPlanMdEditable,
+  IDEA_STATUS_API_VALUES,
+} from '@/lib/idea-status'
+
+describe('idea-status mappers', () => {
+  it('round-trips every API value', () => {
+    for (const api of IDEA_STATUS_API_VALUES) {
+      const db = ideaStatusFromApi(api)
+      expect(db).not.toBeNull()
+      expect(ideaStatusToApi(db!)).toBe(api)
+    }
+  })
+
+  it('returns null for invalid input', () => {
+    expect(ideaStatusFromApi('NOT_A_STATUS')).toBeNull()
+  })
+
+  it('is case-insensitive on the API side', () => {
+    expect(ideaStatusFromApi('PLAN_READY')).toBe('PLAN_READY')
+    expect(ideaStatusFromApi('Plan_Ready')).toBe('PLAN_READY')
+  })
+})
+
+describe('canTransition', () => {
+  it('allows valid forward transitions', () => {
+    expect(canTransition('DRAFT', 'GRILLING')).toBe(true)
+    expect(canTransition('GRILLING', 'GRILLED')).toBe(true)
+    expect(canTransition('GRILLED', 'PLANNING')).toBe(true)
+    expect(canTransition('PLANNING', 'PLAN_READY')).toBe(true)
+    expect(canTransition('PLAN_READY', 'PLANNED')).toBe(true)
+  })
+
+  it('allows re-grill from GRILLED and PLAN_READY-ish states', () => {
+    expect(canTransition('GRILLED', 'GRILLING')).toBe(true)
+    expect(canTransition('PLAN_FAILED', 'PLANNING')).toBe(true)
+  })
+
+  it('allows fail-side transitions', () => {
+    expect(canTransition('GRILLING', 'GRILL_FAILED')).toBe(true)
+    expect(canTransition('PLANNING', 'PLAN_FAILED')).toBe(true)
+  })
+
+  it('allows recovery from failed states', () => {
+    expect(canTransition('GRILL_FAILED', 'GRILLING')).toBe(true)
+    expect(canTransition('PLAN_FAILED', 'GRILLED')).toBe(true)
+  })
+
+  it('only allows PLANNED → PLAN_READY (relink path)', () => {
+    expect(canTransition('PLANNED', 'PLAN_READY')).toBe(true)
+    expect(canTransition('PLANNED', 'GRILLING')).toBe(false)
+    expect(canTransition('PLANNED', 'DRAFT')).toBe(false)
+  })
+
+  it('rejects invalid jumps', () => {
+    expect(canTransition('DRAFT', 'PLANNED')).toBe(false)
+    expect(canTransition('DRAFT', 'PLAN_READY')).toBe(false)
+    expect(canTransition('GRILLING', 'PLANNED')).toBe(false)
+  })
+})
+
+describe('isIdeaEditable', () => {
+  it('allows edit in non-running, non-PLANNED states', () => {
+    expect(isIdeaEditable('DRAFT')).toBe(true)
+    expect(isIdeaEditable('GRILLED')).toBe(true)
+    expect(isIdeaEditable('GRILL_FAILED')).toBe(true)
+    expect(isIdeaEditable('PLAN_FAILED')).toBe(true)
+    expect(isIdeaEditable('PLAN_READY')).toBe(true)
+  })
+
+  it('blocks edit while a job is running or after PLANNED', () => {
+    expect(isIdeaEditable('GRILLING')).toBe(false)
+    expect(isIdeaEditable('PLANNING')).toBe(false)
+    expect(isIdeaEditable('PLANNED')).toBe(false)
+  })
+})
+
+describe('isGrillMdEditable / isPlanMdEditable', () => {
+  it('grill_md only editable in GRILLED or PLAN_READY', () => {
+    expect(isGrillMdEditable('GRILLED')).toBe(true)
+    expect(isGrillMdEditable('PLAN_READY')).toBe(true)
+    expect(isGrillMdEditable('DRAFT')).toBe(false)
+    expect(isGrillMdEditable('PLANNED')).toBe(false)
+  })
+
+  it('plan_md only editable in PLAN_READY', () => {
+    expect(isPlanMdEditable('PLAN_READY')).toBe(true)
+    expect(isPlanMdEditable('GRILLED')).toBe(false)
+    expect(isPlanMdEditable('PLAN_FAILED')).toBe(false)
+    expect(isPlanMdEditable('PLANNED')).toBe(false)
+  })
+})