popilot 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "popilot",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Multi-agent PO/PM system scaffold for Claude Code",
   "type": "module",
   "bin": {

package/scaffold/mcp-notification-server/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "mcp-notification-server",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/scaffold/mcp-notification-server/src/index.ts

@@ -0,0 +1,275 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { query, execute } from './turso-client.js'
+
+const server = new McpServer({
+  name: 'spec-notifications',
+  version: '1.0.0',
+})
+
+// Tool 1: Check unread notifications
+server.tool(
+  'check_notifications',
+  'Check unread notifications for a user (max 20)',
+  { user_name: z.string().describe('User name to check notifications for') },
+  async ({ user_name }) => {
+    const result = await query<{
+      id: number; type: string; title: string; body: string | null
+      source_type: string; source_id: number; page_id: string
+      actor: string; is_read: number; created_at: string
+    }>(
+      `SELECT id, type, title, body, source_type, source_id, page_id, actor, is_read, created_at
+       FROM notifications
+       WHERE user_name = ? AND is_read = 0
+       ORDER BY created_at DESC
+       LIMIT 20`,
+      [user_name],
+    )
+
+    if (result.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${result.error}` }] }
+    }
+
+    if (result.rows.length === 0) {
+      return { content: [{ type: 'text' as const, text: `No unread notifications for ${user_name}.` }] }
+    }
+
+    const lines = result.rows.map((n, i) => {
+      const icon = n.type === 'memo_assigned' ? '📩' : n.type === 'reply_received' ? '💬' : '📢'
+      return `${i + 1}. ${icon} [ID:${n.id}] ${n.title}\n   ${n.body ?? ''}\n   Page: ${n.page_id} | ${n.created_at}`
+    })
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Unread notifications for ${user_name} (${result.rows.length}):\n\n${lines.join('\n\n')}`,
+      }],
+    }
+  },
+)
+
+// Tool 2: Mark notification as read
+server.tool(
+  'mark_notification_read',
+  'Mark a notification as read by ID',
+  { notification_id: z.number().describe('Notification ID to mark as read') },
+  async ({ notification_id }) => {
+    const result = await execute(
+      'UPDATE notifications SET is_read = 1 WHERE id = ?',
+      [notification_id],
+    )
+
+    if (result.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${result.error}` }] }
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.rowsAffected > 0
+          ? `Notification #${notification_id} marked as read.`
+          : `Notification #${notification_id} not found.`,
+      }],
+    }
+  },
+)
+
+// Tool 3: Check open memos assigned to user
+server.tool(
+  'check_open_memos',
+  'Check all open memos assigned to a user',
+  { user_name: z.string().describe('User name to check memos for') },
+  async ({ user_name }) => {
+    const result = await query<{
+      id: number; page_id: string; content: string; memo_type: string
+      created_by: string; assigned_to: string | null; created_at: string
+    }>(
+      `SELECT id, page_id, content, memo_type, created_by, assigned_to, created_at
+       FROM memos_v2
+       WHERE assigned_to = ? AND status = 'open'
+       ORDER BY created_at DESC`,
+      [user_name],
+    )
+
+    if (result.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${result.error}` }] }
+    }
+
+    if (result.rows.length === 0) {
+      return { content: [{ type: 'text' as const, text: `No open memos assigned to ${user_name}.` }] }
+    }
+
+    const typeIcons: Record<string, string> = {
+      memo: '📝', decision: '⚡', request: '📋', backlog: '💡',
+    }
+
+    const lines = result.rows.map((m, i) => {
+      const icon = typeIcons[m.memo_type] ?? '📝'
+      const preview = m.content.length > 80 ? m.content.slice(0, 80) + '…' : m.content
+      return `${i + 1}. ${icon} [ID:${m.id}] ${m.created_by} → ${m.assigned_to}\n   ${preview}\n   Page: ${m.page_id} | ${m.created_at}`
+    })
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Open memos for ${user_name} (${result.rows.length}):\n\n${lines.join('\n\n')}`,
+      }],
+    }
+  },
+)
+
+// Tool 4: Create notification
+server.tool(
+  'create_notification',
+  'Create a notification for a user (memo events: assignment, reply, resolve, reopen)',
+  {
+    user_name: z.string().describe('Notification recipient'),
+    type: z.enum(['memo_assigned', 'memo_mention_all', 'reply_received', 'memo_resolved', 'memo_reopened'])
+      .describe('Notification type'),
+    title: z.string().describe('Notification title'),
+    body: z.string().optional().describe('Preview body (60 chars max)'),
+    source_id: z.number().describe('Related memo ID'),
+    page_id: z.string().describe('Page ID the memo belongs to'),
+    actor: z.string().describe('Name of the person who performed the action'),
+  },
+  async ({ user_name, type, title, body, source_id, page_id, actor }) => {
+    const result = await execute(
+      `INSERT INTO notifications (user_name, type, title, body, source_type, source_id, page_id, actor)
+       VALUES (?, ?, ?, ?, 'memo', ?, ?, ?)`,
+      [user_name, type, title, body ?? null, source_id, page_id, actor],
+    )
+
+    if (result.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${result.error}` }] }
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Notification created: [${type}] "${title}" for ${user_name}`,
+      }],
+    }
+  },
+)
+
+// Tool 5: Reply to memo
+server.tool(
+  'reply_memo',
+  'Reply to a memo and notify the memo author',
+  {
+    memo_id: z.number().describe('Memo ID to reply to'),
+    content: z.string().describe('Reply content'),
+    created_by: z.string().describe('Reply author name'),
+  },
+  async ({ memo_id, content, created_by }) => {
+    const memo = await query<{
+      id: number; page_id: string; created_by: string; assigned_to: string | null; status: string
+    }>(
+      'SELECT id, page_id, created_by, assigned_to, status FROM memos_v2 WHERE id = ?',
+      [memo_id],
+    )
+
+    if (memo.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${memo.error}` }] }
+    }
+    if (memo.rows.length === 0) {
+      return { content: [{ type: 'text' as const, text: `Memo #${memo_id} not found.` }] }
+    }
+
+    const m = memo.rows[0]
+
+    const insertResult = await execute(
+      'INSERT INTO memo_replies (memo_id, content, created_by) VALUES (?, ?, ?)',
+      [memo_id, content, created_by],
+    )
+
+    if (insertResult.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${insertResult.error}` }] }
+    }
+
+    // Notify memo author (skip self-notification)
+    if (m.created_by !== created_by) {
+      await execute(
+        `INSERT INTO notifications (user_name, type, title, body, source_type, source_id, page_id, actor)
+         VALUES (?, 'reply_received', ?, ?, 'memo', ?, ?, ?)`,
+        [
+          m.created_by,
+          `${created_by} replied to your memo`,
+          content.length > 60 ? content.slice(0, 57) + '…' : content,
+          memo_id,
+          m.page_id,
+          created_by,
+        ],
+      )
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Reply posted on memo #${memo_id} by ${created_by}.\nContent: ${content}`,
+      }],
+    }
+  },
+)
+
+// Tool 6: Resolve memo
+server.tool(
+  'resolve_memo',
+  'Mark a memo as resolved and notify related users',
+  {
+    memo_id: z.number().describe('Memo ID to resolve'),
+    resolved_by: z.string().describe('Name of resolver'),
+  },
+  async ({ memo_id, resolved_by }) => {
+    const memo = await query<{
+      id: number; page_id: string; created_by: string; assigned_to: string | null; status: string
+    }>(
+      'SELECT id, page_id, created_by, assigned_to, status FROM memos_v2 WHERE id = ?',
+      [memo_id],
+    )
+
+    if (memo.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${memo.error}` }] }
+    }
+    if (memo.rows.length === 0) {
+      return { content: [{ type: 'text' as const, text: `Memo #${memo_id} not found.` }] }
+    }
+
+    const m = memo.rows[0]
+    if (m.status === 'resolved') {
+      return { content: [{ type: 'text' as const, text: `Memo #${memo_id} is already resolved.` }] }
+    }
+
+    const updateResult = await execute(
+      "UPDATE memos_v2 SET status = 'resolved' WHERE id = ?",
+      [memo_id],
+    )
+
+    if (updateResult.error) {
+      return { content: [{ type: 'text' as const, text: `Error: ${updateResult.error}` }] }
+    }
+
+    if (m.created_by !== resolved_by) {
+      await execute(
+        `INSERT INTO notifications (user_name, type, title, body, source_type, source_id, page_id, actor)
+         VALUES (?, 'memo_resolved', ?, NULL, 'memo', ?, ?, ?)`,
+        [m.created_by, `${resolved_by} resolved the memo`, memo_id, m.page_id, resolved_by],
+      )
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Memo #${memo_id} resolved by ${resolved_by}.`,
+      }],
+    }
+  },
+)
+
+async function main() {
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+main().catch(console.error)

package/scaffold/mcp-notification-server/src/turso-client.ts

@@ -0,0 +1,142 @@
+/**
+ * Database HTTP API client (Turso Hrana v2 protocol)
+ * Reads DB_URL and DB_AUTH_TOKEN from environment.
+ */
+
+const DB_URL = process.env.DB_URL ?? ''
+const DB_AUTH_TOKEN = process.env.DB_AUTH_TOKEN ?? ''
+
+type ArgValue = string | number | null
+
+interface HranaValue {
+  type: 'text' | 'integer' | 'float' | 'null'
+  value?: string
+}
+
+function toHranaArg(v: ArgValue): HranaValue {
+  if (v === null) return { type: 'null' }
+  if (typeof v === 'number') {
+    return Number.isInteger(v)
+      ? { type: 'integer', value: String(v) }
+      : { type: 'float', value: String(v) }
+  }
+  return { type: 'text', value: String(v) }
+}
+
+interface PipelineResult {
+  results: Array<{
+    type: 'ok' | 'error'
+    response?: {
+      type: string
+      result?: {
+        cols: Array<{ name: string }>
+        rows: Array<Array<HranaValue>>
+        affected_row_count: number
+        last_insert_rowid: string | null
+      }
+    }
+    error?: { message: string }
+  }>
+}
+
+export async function query<T = Record<string, unknown>>(
+  sql: string,
+  args: ArgValue[] = [],
+): Promise<{ rows: T[]; error?: string }> {
+  if (!DB_URL || !DB_AUTH_TOKEN) {
+    return { rows: [], error: 'Missing DB_URL or DB_AUTH_TOKEN' }
+  }
+
+  try {
+    const resp = await fetch(DB_URL + '/v2/pipeline', {
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer ' + DB_AUTH_TOKEN,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        requests: [
+          { type: 'execute', stmt: { sql, args: args.map(toHranaArg) } },
+          { type: 'close' },
+        ],
+      }),
+      signal: AbortSignal.timeout(10000),
+    })
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '')
+      return { rows: [], error: `HTTP ${resp.status}: ${text}` }
+    }
+
+    const data: PipelineResult = await resp.json()
+    const first = data.results[0]
+
+    if (first.type === 'error') {
+      return { rows: [], error: first.error?.message ?? 'Unknown error' }
+    }
+
+    const result = first.response?.result
+    if (!result) return { rows: [] }
+
+    const colNames = result.cols.map(c => c.name)
+    const rows = result.rows.map(row => {
+      const obj: Record<string, unknown> = {}
+      colNames.forEach((col, i) => {
+        const cell = row[i]
+        if (cell.type === 'null') obj[col] = null
+        else if (cell.type === 'integer') obj[col] = Number(cell.value)
+        else if (cell.type === 'float') obj[col] = Number(cell.value)
+        else obj[col] = cell.value
+      })
+      return obj as T
+    })
+
+    return { rows }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Unknown error'
+    return { rows: [], error: message }
+  }
+}
+
+export async function execute(
+  sql: string,
+  args: ArgValue[] = [],
+): Promise<{ rowsAffected: number; error?: string }> {
+  if (!DB_URL || !DB_AUTH_TOKEN) {
+    return { rowsAffected: 0, error: 'Missing DB_URL or DB_AUTH_TOKEN' }
+  }
+
+  try {
+    const resp = await fetch(DB_URL + '/v2/pipeline', {
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer ' + DB_AUTH_TOKEN,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        requests: [
+          { type: 'execute', stmt: { sql, args: args.map(toHranaArg) } },
+          { type: 'close' },
+        ],
+      }),
+      signal: AbortSignal.timeout(10000),
+    })
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '')
+      return { rowsAffected: 0, error: `HTTP ${resp.status}: ${text}` }
+    }
+
+    const data: PipelineResult = await resp.json()
+    const first = data.results[0]
+
+    if (first.type === 'error') {
+      return { rowsAffected: 0, error: first.error?.message ?? 'Unknown error' }
+    }
+
+    return { rowsAffected: first.response?.result?.affected_row_count ?? 0 }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Unknown error'
+    return { rowsAffected: 0, error: message }
+  }
+}

package/scaffold/mcp-notification-server/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}

package/scaffold/pm-api/sql/001-memo-v2.sql

@@ -0,0 +1,49 @@
+-- Memo v2 migration — authentication, user activity, memos, replies
+
+-- 1. Auth tokens
+CREATE TABLE IF NOT EXISTS auth_tokens (
+  token      TEXT PRIMARY KEY,
+  user_name  TEXT NOT NULL,
+  user_email TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  expires_at TIMESTAMP,
+  is_active  INTEGER DEFAULT 1
+);
+
+-- 2. User activity tracking
+CREATE TABLE IF NOT EXISTS user_activity (
+  user_name      TEXT PRIMARY KEY,
+  last_seen_at   TIMESTAMP,
+  last_memo_seen TIMESTAMP,
+  updated_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 3. Memos v2
+CREATE TABLE IF NOT EXISTS memos_v2 (
+  id          INTEGER PRIMARY KEY,
+  page_id     TEXT NOT NULL,
+  content     TEXT NOT NULL,
+  memo_type   TEXT DEFAULT 'memo',
+  status      TEXT DEFAULT 'open',
+  created_by  TEXT NOT NULL,
+  assigned_to TEXT,
+  resolved_by TEXT,
+  resolved_at TIMESTAMP,
+  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_memos_v2_page ON memos_v2(page_id);
+CREATE INDEX IF NOT EXISTS idx_memos_v2_assigned ON memos_v2(assigned_to, status);
+CREATE INDEX IF NOT EXISTS idx_memos_v2_type ON memos_v2(memo_type, status);
+
+-- 4. Memo replies
+CREATE TABLE IF NOT EXISTS memo_replies (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  memo_id    INTEGER NOT NULL,
+  content    TEXT NOT NULL,
+  created_by TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_memo_replies_memo ON memo_replies(memo_id);

package/scaffold/pm-api/sql/002-notifications.sql

@@ -0,0 +1,18 @@
+-- Notifications table for per-user alert management
+
+CREATE TABLE IF NOT EXISTS notifications (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_name   TEXT NOT NULL,
+  type        TEXT NOT NULL DEFAULT 'memo_assigned',
+  title       TEXT NOT NULL,
+  body        TEXT,
+  source_type TEXT NOT NULL DEFAULT 'memo',
+  source_id   INTEGER NOT NULL,
+  page_id     TEXT NOT NULL,
+  actor       TEXT NOT NULL,
+  is_read     INTEGER DEFAULT 0,
+  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_notifications_user_unread ON notifications(user_name, is_read, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_notifications_source ON notifications(source_type, source_id);

package/scaffold/pm-api/sql/003-content.sql

@@ -0,0 +1,66 @@
+-- Spec-site content schema — rules, scenarios, areas, versions, wireframe meta
+
+-- 1. Rules (flat, individually queryable)
+CREATE TABLE IF NOT EXISTS spec_rules (
+  id           TEXT NOT NULL,
+  page_id      TEXT NOT NULL,
+  rule_group   TEXT NOT NULL,
+  category     TEXT NOT NULL,
+  name         TEXT NOT NULL,
+  condition    TEXT NOT NULL,
+  severity     TEXT NOT NULL,
+  home_message TEXT NOT NULL DEFAULT '',
+  action       TEXT NOT NULL DEFAULT '',
+  data_source  TEXT NOT NULL DEFAULT '',
+  impl_status  TEXT NOT NULL DEFAULT 'logic-needed',
+  impl_note    TEXT,
+  action_route TEXT,
+  sort_order   INTEGER NOT NULL DEFAULT 0,
+  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (page_id, id)
+);
+CREATE INDEX IF NOT EXISTS idx_spec_rules_page ON spec_rules(page_id);
+
+-- 2. Scenarios
+CREATE TABLE IF NOT EXISTS spec_scenarios (
+  page_id      TEXT NOT NULL,
+  scenario_id  TEXT NOT NULL,
+  label        TEXT NOT NULL,
+  data_json    TEXT NOT NULL,
+  is_default   INTEGER DEFAULT 0,
+  sort_order   INTEGER NOT NULL DEFAULT 0,
+  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (page_id, scenario_id)
+);
+
+-- 3. Spec areas
+CREATE TABLE IF NOT EXISTS spec_areas (
+  page_id     TEXT NOT NULL,
+  area_id     TEXT NOT NULL,
+  label       TEXT NOT NULL,
+  short_label TEXT NOT NULL,
+  rule_count  INTEGER NOT NULL DEFAULT 0,
+  sort_order  INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (page_id, area_id)
+);
+
+-- 4. Page versions
+CREATE TABLE IF NOT EXISTS spec_versions (
+  page_id      TEXT PRIMARY KEY,
+  version      TEXT NOT NULL,
+  last_updated TEXT NOT NULL,
+  sprint       TEXT NOT NULL,
+  status       TEXT NOT NULL DEFAULT 'draft',
+  changelog    TEXT NOT NULL DEFAULT '[]',
+  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 5. Wireframe metadata
+CREATE TABLE IF NOT EXISTS spec_wireframe_meta (
+  page_id             TEXT NOT NULL,
+  sprint              TEXT NOT NULL,
+  default_scenario_id TEXT NOT NULL,
+  spec_title          TEXT NOT NULL,
+  route_title         TEXT NOT NULL,
+  PRIMARY KEY (page_id, sprint)
+);

package/scaffold/pm-api/sql/004-agent-events.sql

@@ -0,0 +1,21 @@
+-- Agent events table for push-based inter-agent communication
+
+CREATE TABLE IF NOT EXISTS agent_events (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_type   TEXT NOT NULL,
+  source_agent TEXT NOT NULL,
+  target_agent TEXT NOT NULL,
+  target_user  TEXT NOT NULL,
+  payload      TEXT NOT NULL,
+  status       TEXT DEFAULT 'pending',
+  delivered_at TIMESTAMP,
+  acked_at     TIMESTAMP,
+  expires_at   TIMESTAMP,
+  created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_target
+  ON agent_events(target_user, status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_events_type
+  ON agent_events(event_type, status);

package/scaffold/pm-api/sql/005-epic-sprint-decoupling.sql

@@ -0,0 +1,6 @@
+-- Epic-Sprint decoupling migration
+-- Purpose: Make pm_epics the SSOT, remove nav_epics dependency
+-- Epics are global; stories move between sprints.
+
+ALTER TABLE pm_epics ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE pm_epics ADD COLUMN origin_sprint TEXT;

package/scaffold/pm-api/src/utils/retro-link.ts

@@ -0,0 +1,32 @@
+/**
+ * Retro → Kickoff Link — pure domain logic
+ */
+
+export interface RetroAction {
+  id: number
+  content: string
+  assignee: string | null
+  status: string
+}
+
+export interface BacklogStory {
+  title: string
+  description: string
+  assignee: string | null
+  source: string
+}
+
+/** Convert action item → backlog story */
+export function actionToStory(action: RetroAction, sprintId: string): BacklogStory {
+  return {
+    title: `[Retro] ${action.content.slice(0, 60)}`,
+    description: `Created from retro (${sprintId}) action item.\n\nOriginal: ${action.content}`,
+    assignee: action.assignee,
+    source: `retro:${sprintId}`,
+  }
+}
+
+/** Filter incomplete action items */
+export function getPendingActions(actions: RetroAction[]): RetroAction[] {
+  return actions.filter(a => a.status !== 'done')
+}