nexus/.planning/phases/23-brainstormer-flow/23-00-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
23-brainstormer-flow	00	execute	0		packages/db/src/schema/chat_messages.ts packages/db/src/migrations/0049_add_message_type.sql packages/db/src/migrations/meta/_journal.json packages/shared/src/types/chat.ts packages/shared/src/validators/chat.ts packages/shared/src/index.ts ui/src/components/ChatSpecCard.test.tsx ui/src/components/ChatHandoffIndicator.test.tsx ui/src/components/ChatTaskCreatedBadge.test.tsx ui/src/components/ChatStatusUpdateBadge.test.tsx ui/src/hooks/useBrainstormerDefault.test.ts	true	AGENT-01 AGENT-02 AGENT-03 AGENT-05 AGENT-06 AGENT-07 CHAT-09	truths artifacts key_links chat_messages table has a message_type text column ChatMessage shared type includes messageType field createMessageSchema accepts optional messageType handoffSchema validates spec content and targetRole Test stubs exist for all new Phase 23 components and hooks path provides contains packages/db/src/schema/chat_messages.ts messageType column definition messageType path provides contains packages/db/src/migrations/0049_add_message_type.sql SQL migration for message_type column ADD COLUMN path provides contains packages/shared/src/types/chat.ts ChatMessage.messageType field messageType path provides contains packages/shared/src/validators/chat.ts handoffSchema and messageType in createMessageSchema handoffSchema from to via pattern packages/db/src/schema/chat_messages.ts packages/shared/src/types/chat.ts messageType field must match messageType

Foundation: DB migration for message_type column, shared types/validators extension, and Wave 0 test stubs for all Phase 23 components.

Purpose: Every subsequent plan depends on the message_type column existing in the DB schema, the ChatMessage type having a messageType field, and test stubs being in place for TDD-style development. Output: Migration file, updated schema/types/validators, test stub files.

<execution_context> @.claude/get-shit-done/workflows/execute-plan.md @.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/23-brainstormer-flow/23-RESEARCH.md @.planning/phases/23-brainstormer-flow/23-UI-SPEC.md

From packages/shared/src/types/chat.ts:

export interface ChatMessage {
  id: string;
  conversationId: string;
  role: "user" | "assistant" | "system";
  content: string;
  agentId: string | null;
  createdAt: string;
  updatedAt: string | null;
}

From packages/shared/src/validators/chat.ts:

export const createMessageSchema = z.object({
  role: z.enum(["user", "assistant", "system"]),
  content: z.string().min(1).max(100_000),
  agentId: z.string().uuid().optional(),
});

From packages/db/src/schema/chat_messages.ts:

export const chatMessages = pgTable(
  "chat_messages",
  {
    id: uuid("id").primaryKey().defaultRandom(),
    conversationId: uuid("conversation_id").notNull()
      .references(() => chatConversations.id, { onDelete: "cascade" }),
    role: text("role").notNull(),
    content: text("content").notNull(),
    agentId: uuid("agent_id"),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow(),
  },
  (table) => ({
    conversationCreatedIdx: index("chat_messages_conversation_created_idx").on(table.conversationId, table.createdAt),
  }),
);

Migration journal: last entry is idx 46, tag "0046_smooth_sentinels". Files on disk go up to 0048. Next migration must be 0049.

Task 1: DB migration and shared types for message_type - packages/db/src/schema/chat_messages.ts - packages/db/src/migrations/meta/_journal.json - packages/shared/src/types/chat.ts - packages/shared/src/validators/chat.ts - packages/shared/src/index.ts packages/db/src/schema/chat_messages.ts, packages/db/src/migrations/0049_add_message_type.sql, packages/db/src/migrations/meta/_journal.json, packages/shared/src/types/chat.ts, packages/shared/src/validators/chat.ts, packages/shared/src/index.ts 1. Create migration file `packages/db/src/migrations/0049_add_message_type.sql`: ```sql ALTER TABLE "chat_messages" ADD COLUMN "message_type" text; ```

2. Update packages/db/src/migrations/meta/_journal.json: append a new entry after idx 46 with idx 49, version "7", tag "0049_add_message_type", breakpoints true. Use when: Date.now() (current epoch ms).

   IMPORTANT: The journal has entries up to idx 46 but disk has files 0047 and 0048 (added manually in Phases 21/22 without journal entries). Add ONLY the idx 49 entry. Do NOT add entries for 0047 or 0048 — those were applied outside the journal.

   Wait — re-read the journal. If _journal.json only goes to idx 46, but files go to 0048, we must add entries for 47, 48, AND 49 to keep the journal consistent. Read the actual SQL files 0047 and 0048 to determine their tags.

   Actually, looking at the research notes: "The migration numbering... The next migration must be named 0049_*.sql with idx 49 added to _journal.json." Follow this guidance — add idx 47 (tag "0047_nebulous_klaw"), idx 48 (tag "0048_add_chat_messages_updated_at"), and idx 49 (tag "0049_add_message_type") entries.

3. Update packages/db/src/schema/chat_messages.ts: add messageType: text("message_type"), after the agentId field. This is a nullable text column. Values: null (normal), "handoff", "spec_card", "task_created", "status_update".

4. Update packages/shared/src/types/chat.ts:

   • Add messageType: string | null; to the ChatMessage interface (after agentId).

5. Update packages/shared/src/validators/chat.ts:

   • Add messageType: z.string().optional(), to createMessageSchema.
   • Add new handoffSchema:

     export const handoffSchema = z.object({
       spec: z.object({
         what: z.string().min(1),
         why: z.string().min(1),
         constraints: z.string().optional().default(""),
         success: z.string().optional().default(""),
       }),
       targetRole: z.enum(["pm", "engineer", "general"]),
     });
     export type Handoff = z.infer<typeof handoffSchema>;
     

   • Add handoffSchema and Handoff to the file's exports.

6. Update packages/shared/src/index.ts: add re-exports for handoffSchema and Handoff type from validators/chat.ts. Follow the existing pattern of re-exporting from ./validators/chat.js. cd /opt/nexus && pnpm exec tsc --noEmit -p packages/shared/tsconfig.json 2>&1 | head -20 && pnpm exec tsc --noEmit -p packages/db/tsconfig.json 2>&1 | head -20 <acceptance_criteria>

   • grep -q "messageType" packages/db/src/schema/chat_messages.ts
   • grep -q "message_type" packages/db/src/migrations/0049_add_message_type.sql
   • grep -q "messageType" packages/shared/src/types/chat.ts
   • grep -q "handoffSchema" packages/shared/src/validators/chat.ts
   • grep -q "handoffSchema" packages/shared/src/index.ts
   • grep -q "0049_add_message_type" packages/db/src/migrations/meta/_journal.json </acceptance_criteria> message_type column defined in Drizzle schema and SQL migration; ChatMessage type and createMessageSchema include messageType; handoffSchema exported from shared package

Task 2: Wave 0 test stubs for Phase 23 components and hooks - ui/src/components/ChatMessage.test.tsx - ui/src/components/ChatMessageList.test.tsx ui/src/components/ChatSpecCard.test.tsx, ui/src/components/ChatHandoffIndicator.test.tsx, ui/src/components/ChatTaskCreatedBadge.test.tsx, ui/src/components/ChatStatusUpdateBadge.test.tsx, ui/src/hooks/useBrainstormerDefault.test.ts Create test stub files using it.todo() pattern (matching Phase 21 convention — NOT it.skip()):

1. ui/src/components/ChatSpecCard.test.tsx:

   // @vitest-environment jsdom
   import { describe, it } from "vitest";
   
   describe("ChatSpecCard", () => {
     it.todo("renders four spec sections: What, Why, Constraints, Success");
     it.todo("parses JSON content and displays field values");
     it.todo("shows error fallback on JSON parse failure");
     it.todo("Send to PM button calls onHandoff with spec content");
     it.todo("Edit button switches to textarea edit mode");
     it.todo("Save changes button disabled when all fields empty");
     it.todo("Discard button reverts to read-only mode");
     it.todo("Save as Draft button adds [Draft] badge");
     it.todo("renders with role=region and aria-label=Specification");
   });
   

2. ui/src/components/ChatHandoffIndicator.test.tsx:

   // @vitest-environment jsdom
   import { describe, it } from "vitest";
   
   describe("ChatHandoffIndicator", () => {
     it.todo("renders content text between two hr elements");
     it.todo("has aria-label for agent handoff");
     it.todo("hr elements have aria-hidden=true");
   });
   

3. ui/src/components/ChatTaskCreatedBadge.test.tsx:

   // @vitest-environment jsdom
   import { describe, it } from "vitest";
   
   describe("ChatTaskCreatedBadge", () => {
     it.todo("shows Creating task... when taskId is not provided");
     it.todo("renders taskId, taskTitle, and View task link when resolved");
     it.todo("View task link has correct aria-label");
     it.todo("has role=status on container");
   });
   

4. ui/src/components/ChatStatusUpdateBadge.test.tsx:

   // @vitest-environment jsdom
   import { describe, it } from "vitest";
   
   describe("ChatStatusUpdateBadge", () => {
     it.todo("renders CheckCircle2 icon, agent name, and task reference");
     it.todo("View task link navigates to issue detail");
     it.todo("has role=status on container");
   });
   

5. ui/src/hooks/useBrainstormerDefault.test.ts:

   // @vitest-environment jsdom
   import { describe, it } from "vitest";
   
   describe("useBrainstormerDefault", () => {
     it.todo("returns general role agent ID when available");
     it.todo("returns first by createdAt when multiple general agents exist");
     it.todo("returns null when no agents loaded");
     it.todo("returns null when no general agent exists");
   });
   

cd /opt/nexus && pnpm vitest run --project=ui -- ChatSpecCard ChatHandoffIndicator ChatTaskCreatedBadge ChatStatusUpdateBadge useBrainstormerDefault 2>&1 | tail -10 - test -f ui/src/components/ChatSpecCard.test.tsx - test -f ui/src/components/ChatHandoffIndicator.test.tsx - test -f ui/src/components/ChatTaskCreatedBadge.test.tsx - test -f ui/src/components/ChatStatusUpdateBadge.test.tsx - test -f ui/src/hooks/useBrainstormerDefault.test.ts - grep -q "it.todo" ui/src/components/ChatSpecCard.test.tsx - grep -q "it.todo" ui/src/hooks/useBrainstormerDefault.test.ts All 5 test stub files exist with it.todo() entries covering every Phase 23 behavior; vitest run finds them without errors - `pnpm exec tsc --noEmit` passes for shared and db packages - Migration file 0049 exists with correct SQL - Journal updated with idx 49 entry - All 5 test stub files parseable by vitest

<success_criteria>

• messageType column in Drizzle schema and SQL migration
• ChatMessage type has messageType field
• handoffSchema exported from shared
• createMessageSchema accepts optional messageType
• 5 test stub files with it.todo() entries </success_criteria>

After completion, create `.planning/phases/23-brainstormer-flow/23-00-SUMMARY.md`