internaltool-mcp 1.6.35 → 1.6.41

package/index.js

@@ -18,7 +18,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { execSync } from 'child_process'
-import { mkdirSync, writeFileSync, unlinkSync, existsSync, readdirSync, statSync } from 'fs'
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync, statSync } from 'fs'
 import { join } from 'path'
 import { z } from 'zod'
 import { api, login, configure } from './api-client.js'
@@ -83,6 +83,180 @@ async function assertAdmin() {
   }
 }
 
+// ── Codebase analysis helpers (used by plan_task_from_codebase) ───────────────
+
+/**
+ * Reads manifest files in cwd and returns detected stack info.
+ * Works for any language — JS/TS, Python, Go, Ruby, Java, Rust, PHP.
+ */
+function detectStack(cwd) {
+  const stack = { language: null, framework: null, testRunner: null, packageManager: null, extra: [] }
+  try {
+    // Node.js / JS / TS
+    const pkgPath = join(cwd, 'package.json')
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+      stack.language = pkg.scripts?.build?.includes('tsc') || existsSync(join(cwd, 'tsconfig.json')) ? 'typescript' : 'javascript'
+      stack.packageManager = existsSync(join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(cwd, 'yarn.lock')) ? 'yarn' : 'npm'
+      // Framework detection
+      if (deps.next)        stack.framework = 'nextjs'
+      else if (deps.nuxt)   stack.framework = 'nuxt'
+      else if (deps.react)  stack.framework = 'react'
+      else if (deps.vue)    stack.framework = 'vue'
+      else if (deps.svelte) stack.framework = 'svelte'
+      else if (deps.express)  stack.framework = 'express'
+      else if (deps.fastify)  stack.framework = 'fastify'
+      else if (deps.nestjs || deps['@nestjs/core']) stack.framework = 'nestjs'
+      else if (deps.hono)     stack.framework = 'hono'
+      // Test runner
+      if (deps.jest || deps['@jest/core'])   stack.testRunner = 'jest'
+      else if (deps.vitest)                  stack.testRunner = 'vitest'
+      else if (deps.mocha)                   stack.testRunner = 'mocha'
+      else if (deps.playwright || deps['@playwright/test']) stack.testRunner = 'playwright'
+      // ORM / DB
+      if (deps.mongoose)       stack.extra.push('mongoose')
+      if (deps.prisma)         stack.extra.push('prisma')
+      if (deps.drizzle)        stack.extra.push('drizzle')
+      if (deps.typeorm)        stack.extra.push('typeorm')
+      if (deps.sequelize)      stack.extra.push('sequelize')
+      if (deps['@supabase/supabase-js']) stack.extra.push('supabase')
+      if (deps.trpc || deps['@trpc/server']) stack.extra.push('trpc')
+      return stack
+    }
+    // Python
+    const reqPath  = join(cwd, 'requirements.txt')
+    const pyprojPath = join(cwd, 'pyproject.toml')
+    if (existsSync(reqPath) || existsSync(pyprojPath)) {
+      stack.language = 'python'
+      const content = existsSync(reqPath) ? readFileSync(reqPath, 'utf8') : readFileSync(pyprojPath, 'utf8')
+      if (content.includes('django'))  stack.framework = 'django'
+      else if (content.includes('fastapi')) stack.framework = 'fastapi'
+      else if (content.includes('flask'))   stack.framework = 'flask'
+      else if (content.includes('starlette')) stack.framework = 'starlette'
+      if (content.includes('pytest'))  stack.testRunner = 'pytest'
+      if (content.includes('sqlalchemy')) stack.extra.push('sqlalchemy')
+      if (content.includes('alembic'))    stack.extra.push('alembic')
+      return stack
+    }
+    // Go
+    if (existsSync(join(cwd, 'go.mod'))) {
+      stack.language = 'go'
+      const gomod = readFileSync(join(cwd, 'go.mod'), 'utf8')
+      if (gomod.includes('gin-gonic/gin'))  stack.framework = 'gin'
+      else if (gomod.includes('go-chi/chi')) stack.framework = 'chi'
+      else if (gomod.includes('labstack/echo')) stack.framework = 'echo'
+      else if (gomod.includes('gofiber/fiber')) stack.framework = 'fiber'
+      stack.testRunner = 'go test'
+      return stack
+    }
+    // Ruby
+    if (existsSync(join(cwd, 'Gemfile'))) {
+      stack.language = 'ruby'
+      const gemfile = readFileSync(join(cwd, 'Gemfile'), 'utf8')
+      if (gemfile.includes('rails'))  stack.framework = 'rails'
+      else if (gemfile.includes('sinatra')) stack.framework = 'sinatra'
+      if (gemfile.includes('rspec'))  stack.testRunner = 'rspec'
+      return stack
+    }
+    // Rust
+    if (existsSync(join(cwd, 'Cargo.toml'))) {
+      stack.language = 'rust'
+      const cargo = readFileSync(join(cwd, 'Cargo.toml'), 'utf8')
+      if (cargo.includes('actix-web')) stack.framework = 'actix-web'
+      else if (cargo.includes('axum')) stack.framework = 'axum'
+      else if (cargo.includes('warp')) stack.framework = 'warp'
+      stack.testRunner = 'cargo test'
+      return stack
+    }
+    // Java / Kotlin
+    if (existsSync(join(cwd, 'pom.xml')) || existsSync(join(cwd, 'build.gradle'))) {
+      stack.language = existsSync(join(cwd, 'build.gradle.kts')) ? 'kotlin' : 'java'
+      stack.framework = 'spring-boot'
+      stack.testRunner = 'junit'
+      return stack
+    }
+    // PHP
+    if (existsSync(join(cwd, 'composer.json'))) {
+      stack.language = 'php'
+      const composer = JSON.parse(readFileSync(join(cwd, 'composer.json'), 'utf8'))
+      const req = { ...composer.require, ...composer['require-dev'] }
+      if (req['laravel/framework']) stack.framework = 'laravel'
+      else if (req['symfony/symfony'] || req['symfony/framework-bundle']) stack.framework = 'symfony'
+      return stack
+    }
+  } catch { /* non-fatal */ }
+  return stack
+}
+
+/**
+ * Returns a shallow directory tree (depth 2) so the agent knows the folder layout.
+ * Ignores node_modules, .git, vendor, __pycache__, dist, build, .next
+ */
+function getDirTree(cwd, maxDepth = 2) {
+  const IGNORE = new Set(['node_modules', '.git', 'vendor', '__pycache__', 'dist', 'build', '.next', '.turbo', 'coverage', '.cache', 'target', 'venv', '.venv'])
+  function walk(dir, depth) {
+    if (depth > maxDepth) return []
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return [] }
+    return entries
+      .filter(e => !IGNORE.has(e.name) && !e.name.startsWith('.'))
+      .map(e => {
+        if (e.isDirectory()) {
+          const children = walk(join(dir, e.name), depth + 1)
+          return { name: e.name + '/', children: children.length ? children : undefined }
+        }
+        return { name: e.name }
+      })
+  }
+  return walk(cwd, 0)
+}
+
+/**
+ * Based on detected stack, grep for the most likely entry-point files.
+ * Returns a list of { pattern, matches } — actual file paths found locally.
+ */
+function findEntryPoints(cwd, stack) {
+  const results = {}
+  const greps = {
+    javascript: { typescript: true,
+      routes:     ['router\\.', 'app\\.get\\|app\\.post\\|app\\.put\\|fastify\\.', 'Route path='],
+      models:     ['mongoose\\.Schema\\|new Schema\\|@Entity\\|@Table'],
+      components: ['export default function\\|export const.*=.*=>\\|React\\.FC'],
+    },
+    python: {
+      routes:  ['@app\\.route\\|@router\\.\\|path(\\|urlpatterns\\|@api_view'],
+      models:  ['class.*Model\\|db\\.Model\\|Base\\)\\|models\\.Model'],
+      schemas: ['class.*Schema\\|serializers\\.\\|Pydantic\\|BaseModel'],
+    },
+    go: {
+      routes:  ['router\\.\\.\\|http\\.HandleFunc\\|r\\.GET\\|r\\.POST\\|e\\.GET'],
+      models:  ['type.*struct\\|gorm\\.Model'],
+    },
+    ruby: {
+      routes:  ['resources \\|get \'\\|post \'\\|Rails\\.application\\.routes'],
+      models:  ['ApplicationRecord\\|ActiveRecord::Base\\|belongs_to\\|has_many'],
+    },
+  }
+
+  const lang = stack.language === 'typescript' ? 'javascript' : stack.language
+  const patterns = greps[lang] || {}
+
+  for (const [type, patternList] of Object.entries(patterns)) {
+    if (type === 'typescript') continue
+    try {
+      const pat = Array.isArray(patternList) ? patternList.join('\\|') : patternList
+      const out = execSync(
+        `grep -rl "${pat}" . --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" --include="*.py" --include="*.go" --include="*.rb" --include="*.java" --include="*.kt" --include="*.rs" --include="*.php" 2>/dev/null | grep -v node_modules | grep -v ".git" | head -8`,
+        { cwd, encoding: 'utf8', timeout: 4000 }
+      )
+      const files = out.trim().split('\n').filter(Boolean)
+      if (files.length) results[type] = files
+    } catch { /* non-fatal */ }
+  }
+  return results
+}
+
 // ── Tool registration functions ───────────────────────────────────────────────
 
 function registerAuthTools(server) {
@@ -227,21 +401,300 @@ function registerTaskTools(server, { isAdmin, scopedProjectId }) {
     async ({ taskId }) => call(() => api.get(`/api/tasks/${taskId}`))
   )
 
+  // ── search_tasks ──────────────────────────────────────────────────────────────
+  server.tool(
+    'search_tasks',
+    `Search and filter tasks within a project.
+
+Use this to find tasks by keyword, type, status, or assignee. Much faster than listing all tasks.
+
+Examples:
+- Find all bugfix tasks:         search_tasks(projectId, taskType="bugfix")
+- Find tasks about "auth":       search_tasks(projectId, query="auth")
+- Find your in-progress tasks:   search_tasks(projectId, column="in_progress", assignee=myUserId)
+- Find high priority todo items: search_tasks(projectId, column="todo", priority="high,critical")
+- Find tasks in review:          search_tasks(projectId, column="in_review")
+
+Returns tasks with key, title, column, assignees, priority, taskType, and branch info.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      query:     z.string().optional().describe('Free-text search across title, description, README, and key (e.g. "auth", "TASK-042", "payment webhook")'),
+      column:    z.string().optional().describe('Filter by column — comma-separated: "todo,in_progress" or single "done"'),
+      taskType:  z.string().optional().describe('Filter by task type — comma-separated: "bugfix,feature" or single "migration"'),
+      priority:  z.string().optional().describe('Filter by priority — comma-separated: "high,critical"'),
+      assignee:  z.string().optional().describe('Filter by assignee user ID — returns only tasks assigned to this user'),
+      limit:     z.number().optional().default(20).describe('Max results to return (default 20, max 100)'),
+    },
+    async ({ projectId, query, column, taskType, priority, assignee, limit = 20 }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      const params = new URLSearchParams()
+      if (query)    params.set('q', query)
+      if (column)   params.set('column', column)
+      if (taskType) params.set('taskType', taskType)
+      if (priority) params.set('priority', priority)
+      if (assignee) params.set('assignee', assignee)
+      if (limit)    params.set('limit', String(limit))
+
+      const res = await api.get(`/api/projects/${projectId}/tasks/search?${params.toString()}`)
+      if (!res?.success) return errorText(res?.message || 'Search failed')
+
+      const tasks = res.data.tasks || []
+      if (!tasks.length) return text({ found: 0, message: 'No tasks match your search criteria.' })
+
+      return text({
+        found: tasks.length,
+        tasks: tasks.map(t => ({
+          taskId:    t._id,
+          key:       t.key,
+          title:     t.title,
+          column:    t.column,
+          priority:  t.priority,
+          taskType:  t.taskType || null,
+          assignees: (t.assignees || []).map(a => ({ id: a._id, name: a.name || a.email })),
+          branch:    t.github?.headBranch || null,
+          prNumber:  t.github?.prNumber || null,
+          hasPR:     !!(t.github?.prNumber),
+          updatedAt: t.updatedAt,
+        })),
+        tip: tasks.length === limit ? `Results capped at ${limit}. Use more specific filters or increase limit to see more.` : null,
+      })
+    }
+  )
+
+  // ── plan_task_from_codebase ───────────────────────────────────────────────────
+  server.tool(
+    'plan_task_from_codebase',
+    `Specialized task-creation agent — analyzes the codebase and creates a fully structured, kickoff-ready task.
+
+Use this instead of create_task when you need to implement something and want the task to
+contain a real implementation plan based on the actual codebase, not a generic description.
+
+## MANDATORY protocol — follow every step in order
+
+### Step 1 — Duplicate check (always first)
+Call search_tasks(projectId, query="<keywords from the request>").
+If a similar open task already exists → return it with kickoff instructions instead of creating a duplicate.
+
+### Step 2 — Codebase analysis (READ the code, do not guess)
+Using your native Read / Grep / Glob tools:
+
+a) **Stack detection** — read package.json / go.mod / requirements.txt / Cargo.toml.
+   Identify: language, framework, major libraries, test runner.
+
+b) **Entry point mapping** — find where the relevant feature area lives:
+   - For backend: grep for existing route patterns (router.post, app.get, @Controller, etc.)
+   - For frontend: grep for existing component patterns, hooks, state management
+   - For DB: find schema/model files
+
+c) **Pattern extraction** — read 2-3 existing files similar to what you'll build.
+   Note: naming conventions, folder structure, how services/routes/components are wired.
+
+d) **Impact analysis** — identify every file that needs to change:
+   - Files to CREATE (new route, new component, new model, new test)
+   - Files to MODIFY (existing router index, existing schema, existing types)
+
+e) **Dependency order** — which files must be built first (schema before service, service before route, etc.)
+
+### Step 3 — Write the implementation plan
+Using what you found in Step 2, build:
+- ## Goal — one sentence
+- ## Stack — language/framework detected
+- ## Technical approach — how it fits into the existing code (name actual files and functions)
+- ## Files to create — path + what it does
+- ## Files to modify — path + what changes
+- ## Subtasks — ordered implementation steps (schema → service → route → test → UI)
+- ## Acceptance criteria — what done looks like
+
+### Step 4 — Determine task metadata
+- taskType: feature / bugfix / migration / integration / ui / backend / security / refactor
+- priority: low / medium / high / critical (use "high" if the request sounds important)
+- suggestedFiles: the exact file paths from your Step 2d impact analysis
+
+### Step 5 — Create the task
+Call create_task with:
+- projectId (from this call)
+- title: action-oriented, concise (verb + noun, e.g. "Add rate limiting to /api/auth/login")
+- description: one paragraph summary
+- readmeMarkdown: the full plan from Step 3
+- taskType, priority, column="todo"
+- subtasks: the ordered list from Step 3 (each step = one subtask)
+- suggestedFiles: from Step 2d
+
+After create_task succeeds, immediately call:
+kickoff_task(taskId=<returned id>, confirmed=true, agentRole="builder", files=<suggestedFiles>)
+
+## What makes a high-quality task
+- readmeMarkdown references REAL file paths found by grepping the codebase
+- subtasks are ordered (schema first, then service, then route, then test, then UI)
+- suggestedFiles lists every file that will be touched — no omissions
+- title is specific ("Add email verification to /api/auth/register") not generic ("Add email feature")
+
+Do NOT skip the codebase analysis. Do NOT create the task before reading the code.
+Do NOT ask the developer to describe the codebase — read it yourself.`,
+    {
+      projectId: z.string().describe("InternalTool project's MongoDB ObjectId — from the project's task board URL or CLAUDE.md"),
+      request:   z.string().describe('What the developer wants to build — the raw natural language request (e.g. "add rate limiting to the login endpoint", "fix the pagination bug on users list")'),
+      priority:  z.enum(['low', 'medium', 'high', 'critical']).optional().default('medium')
+        .describe('Task priority — default medium, use high/critical for urgent work'),
+    },
+    async ({ projectId, request, priority = 'medium' }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+
+      // ── 1. Run codebase analysis using local filesystem access ────────────────
+      const cwd = process.cwd()
+      const stack       = detectStack(cwd)
+      const dirTree     = getDirTree(cwd, 2)
+      const entryPoints = findEntryPoints(cwd, stack)
+
+      // ── 2. Fetch project context ──────────────────────────────────────────────
+      let projectContext = null
+      try {
+        const projRes = await api.get(`/api/projects/${projectId}`)
+        if (projRes?.success) {
+          const p = projRes.data.project
+          projectContext = {
+            name:       p.name,
+            taskCount:  (projRes.data.tasks || []).length,
+            githubRepo: p.github?.repoUrl || null,
+          }
+        }
+      } catch { /* non-fatal */ }
+
+      // ── 3. Duplicate check ────────────────────────────────────────────────────
+      let similarTasks = null
+      try {
+        const keywords = request.split(' ').filter(w => w.length > 4).slice(0, 3).join(' ')
+        const searchRes = await api.get(
+          `/api/projects/${projectId}/tasks/search?q=${encodeURIComponent(keywords)}&limit=3`
+        )
+        if (searchRes?.success && searchRes.data?.tasks?.length > 0) {
+          similarTasks = searchRes.data.tasks.map(t => ({
+            taskId: t._id, key: t.key, title: t.title, column: t.column, taskType: t.taskType,
+          }))
+        }
+      } catch { /* non-fatal */ }
+
+      // ── 4. Return codebase intelligence + tight instructions ──────────────────
+      const hasEntryPoints = Object.keys(entryPoints).length > 0
+      const stackSummary = [
+        stack.language, stack.framework, stack.testRunner, ...(stack.extra || [])
+      ].filter(Boolean).join(', ') || 'unknown (no manifest found at cwd)'
+
+      return text({
+        // Real codebase data — use these directly, do NOT re-read what's already here
+        codebaseIntelligence: {
+          cwd,
+          stack: { ...stack, summary: stackSummary },
+          dirTree,
+          entryPoints: hasEntryPoints
+            ? entryPoints
+            : { note: 'No entry points found at cwd — check that MCP server is running from the project root' },
+        },
+
+        // Duplicate guard
+        ...(similarTasks?.length > 0 && {
+          duplicateWarning: true,
+          similarTasks,
+          duplicateInstruction: 'Check the list above. If one matches → call kickoff_task on it. If none match → proceed.',
+        }),
+
+        // What to do now — use codebaseIntelligence above to skip re-reading the filesystem
+        nextSteps: [
+          'Use dirTree + entryPoints above to identify which files need changing — you already have the map.',
+          `Read 2-3 files from entryPoints.routes / entryPoints.models / entryPoints.components to extract naming conventions and wiring patterns.`,
+          'Draft readmeMarkdown with: ## Goal, ## Stack, ## Technical approach (name real files), ## Files to create, ## Files to modify, ## Subtasks (ordered), ## Acceptance criteria.',
+          `Call create_task(projectId="${projectId}", title="<verb + noun>", readmeMarkdown="<plan>", taskType="<feature|bugfix|...>", priority="${priority}", column="todo", subtasks=[...], suggestedFiles=[...])`,
+          'Immediately after: call kickoff_task(taskId=<returned id>, confirmed=true, agentRole="builder", files=[...suggestedFiles])',
+        ],
+
+        // Context
+        request,
+        projectId,
+        priority,
+        projectContext,
+      })
+    }
+  )
+
   server.tool(
     'create_task',
-    'Create a new task in a project. Project owner or admin only.',
+    `Create a new task in a project — use this as the final step after analysing the codebase.
+
+## Optimal flow when a developer asks to implement a feature:
+
+1. **Read the codebase first** (use your native Read/Grep/Glob tools — do NOT ask the developer to describe the code):
+   - Find the entry point: package.json / go.mod / requirements.txt → detect stack
+   - Find existing patterns relevant to the feature (e.g. grep for "router.post" to see how routes work)
+   - Identify which files will need to be created or modified
+
+2. **Write the implementation plan** in readmeMarkdown:
+   - ## Goal — one sentence of what this builds
+   - ## Technical approach — how it fits into the existing code (name actual files and functions)
+   - ## Files to create — list each new file and what it does
+   - ## Files to modify — list each existing file and what changes
+   - ## Subtasks — ordered implementation steps (these become the task checklist)
+
+3. **Call create_task** with the completed plan — the task is immediately kickoff-ready.
+
+## What makes a good task
+- readmeMarkdown has enough detail that an agent can implement without asking questions
+- subtasks are ordered (schema first → service → route → test → frontend)
+- taskType is set so kickoff_task routes correctly (feature/bugfix/migration/etc.)
+- suggestedFiles tells the builder exactly which files to claim at kickoff
+
+Always prefer column="todo" so the task is visibly ready to start.`,
     {
       projectId:      z.string().describe("Project's MongoDB ObjectId"),
-      title:          z.string().describe('Task title'),
-      description:    z.string().optional().describe('Short description'),
-      readmeMarkdown: z.string().optional().describe('Markdown implementation plan'),
+      title:          z.string().describe('Task title — concise, action-oriented (e.g. "Add email channel to sendNotification")'),
+      description:    z.string().optional().describe('One-sentence summary of what this task does and why'),
+      readmeMarkdown: z.string().optional().describe('Full markdown implementation plan — see tool description for the recommended structure'),
       priority:       z.enum(['low', 'medium', 'high', 'critical']).optional(),
-      column:         z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']).optional(),
+      column:         z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']).optional().describe('Use "todo" for features ready to start'),
       assignees:      z.array(z.string()).optional().describe('User IDs to assign'),
+      taskType:       z.enum(['migration', 'integration', 'bugfix', 'ui', 'backend', 'security', 'refactor', 'feature']).optional()
+        .describe('Task type — drives agent routing at kickoff (scout-first, coordinator vs single builder, etc.)'),
+      subtasks:       z.array(z.object({ title: z.string() })).optional()
+        .describe('Ordered implementation checklist — shown in the task UI and read by agents at kickoff. Order matters: schema → model → service → route → test → frontend.'),
+      suggestedFiles: z.array(z.string()).optional()
+        .describe('Files the builder will claim at kickoff (e.g. ["server/routes/tasks.js", "server/models/Task.js"]). Included in the task README automatically so the builder knows what to pass to kickoff_task files=[...].'),
     },
-    async ({ projectId, ...taskData }) => {
+    async ({ projectId, suggestedFiles, ...taskData }) => {
       try { assertProjectScope(projectId) } catch (e) { return errorText(e.message) }
-      return call(() => api.post(`/api/projects/${projectId}/tasks`, taskData))
+
+      // Append suggested files section to the README so the builder sees them at kickoff
+      if (suggestedFiles?.length > 0 && taskData.readmeMarkdown) {
+        taskData.readmeMarkdown = [
+          taskData.readmeMarkdown.trimEnd(),
+          '',
+          '## Files to claim at kickoff',
+          '```',
+          ...suggestedFiles.map(f => f),
+          '```',
+          `Call \`kickoff_task(confirmed=true, agentRole="builder", files=[${suggestedFiles.map(f => `"${f}"`).join(', ')}])\` to atomically claim ownership and start.`,
+        ].join('\n')
+      }
+
+      const res = await api.post(`/api/projects/${projectId}/tasks`, taskData)
+      if (!res?.success) return errorText(res?.message || 'Failed to create task')
+
+      const task = res.data?.task
+      return text({
+        created:   true,
+        taskId:    task?._id,
+        taskKey:   task?.key,
+        title:     task?.title,
+        column:    task?.column,
+        taskType:  task?.taskType || null,
+        subtasks:  (task?.subtasks || []).length,
+        kickoff:   task?._id
+          ? `kickoff_task(taskId="${task._id}", confirmed=false)  ← read plan first\nkickoff_task(taskId="${task._id}", confirmed=true, agentRole="builder", files=[...])  ← start building`
+          : null,
+        message: `Task ${task?.key} created and ready to kick off.`,
+      })
     }
   )
 
@@ -402,6 +855,9 @@ Set confirmed=false first to preview, then confirmed=true to execute everything.
         agentWorkspace: { clearedAt: new Date().toISOString() }
       }).catch(() => {/* non-fatal */})
 
+      // Remove .internaltool-active-task so the Claude Code hook blocks edits until next kickoff
+      try { unlinkSync(join(process.cwd(), '.internaltool-active-task')) } catch { /* non-fatal */ }
+
       // ── #9 Capture last commit for handoff metadata ───────────────────────
       const lastCommit = getLastCommitMeta(repoRoot)
 
@@ -602,6 +1058,65 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
     }
   )
 
+  // ── add_blocker ───────────────────────────────────────────────────────────────
+  server.tool(
+    'add_blocker',
+    `Mark a task as blocked by another task that must complete first.
+
+Use this when you discover that TASK-A cannot start or cannot be merged until TASK-B is done.
+Examples: auth middleware must ship before the protected routes task starts;
+DB schema migration must merge before the service layer task.
+
+The blocked task will show a warning in kickoff_task and be deprioritized in what_should_i_work_on.`,
+    {
+      taskId:        z.string().describe("Task that is blocked — the one that cannot start yet"),
+      blockerTaskId: z.string().describe("Task that must complete first — the blocker"),
+      reason:        z.string().optional().describe('Why this dependency exists — shown to developers'),
+    },
+    async ({ taskId, blockerTaskId, reason }) => {
+      const res = await api.post(`/api/tasks/${taskId}/blockers`, { blockerTaskId })
+      if (!res?.success) return errorText(res?.message || 'Could not add blocker')
+      // Optionally add a comment explaining the dependency
+      if (reason) {
+        await api.post(`/api/tasks/${taskId}/comments`, {
+          body: `🔒 **Blocked by task \`${blockerTaskId}\`**: ${reason}`,
+        }).catch(() => {})
+      }
+      return text({
+        blocked: true,
+        taskId,
+        blockerTaskId,
+        reason: reason || null,
+        message: `Task is now blocked. It will not be recommended until the blocker is resolved.`,
+        nextStep: `When the blocker task is done, call remove_blocker with taskId="${taskId}" and blockerTaskId="${blockerTaskId}".`,
+      })
+    }
+  )
+
+  // ── remove_blocker ────────────────────────────────────────────────────────────
+  server.tool(
+    'remove_blocker',
+    `Remove a blocker from a task, marking it as unblocked and ready to start.
+
+Call this when the blocking task has been merged or completed.
+After removing the blocker, the task will appear in what_should_i_work_on recommendations again.`,
+    {
+      taskId:        z.string().describe("Task that was blocked"),
+      blockerTaskId: z.string().describe("The blocker task that is now resolved"),
+    },
+    async ({ taskId, blockerTaskId }) => {
+      const res = await api.delete(`/api/tasks/${taskId}/blockers/${blockerTaskId}`)
+      if (!res?.success) return errorText(res?.message || 'Could not remove blocker')
+      return text({
+        unblocked: true,
+        taskId,
+        blockerTaskId,
+        message: `Blocker removed. Task is now unblocked.`,
+        nextStep: `Call kickoff_task with taskId="${taskId}" to start this task.`,
+      })
+    }
+  )
+
   // ── claim_files ──────────────────────────────────────────────────────────────
   server.tool(
     'claim_files',
@@ -828,32 +1343,51 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
         })
       }
 
-      // Save decomposition to task
+      // Save decomposition JSON to parent task
       const decompositionJson = JSON.stringify(executionPlan, null, 2)
       try {
         await api.patch(`/api/tasks/${taskId}`, { decomposition: decompositionJson })
-      } catch { /* non-fatal — decomposition is returned regardless */ }
-
-      // Create subtasks on the board
-      const currentSubtasks = task.subtasks || []
-      const newSubtasks = [
-        ...currentSubtasks,
-        ...subtaskPlan.map((s, i) => ({
-          title: `[${s.role.toUpperCase()}] ${s.title}`,
-          done:  false,
-          order: currentSubtasks.length + i,
-        })),
-      ]
-      try {
-        await api.patch(`/api/tasks/${taskId}`, { subtasks: newSubtasks })
       } catch { /* non-fatal */ }
 
+      // Create real child tasks for each subtask in the plan
+      const projectId = task.project?._id || task.project
+      const createdTasks = []
+      for (const s of subtaskPlan) {
+        try {
+          const childRes = await api.post(`/api/projects/${projectId}/tasks`, {
+            title:          `[${s.role.toUpperCase()}] ${s.title}`,
+            description:    s.description,
+            readmeMarkdown: [
+              `## Role: ${s.role}`,
+              `## Description\n${s.description}`,
+              s.files?.length ? `## Files to claim at kickoff\n${s.files.map(f => `- \`${f}\``).join('\n')}` : '',
+              s.dependsOn?.length ? `## Depends on\n${s.dependsOn.map(d => `- ${d}`).join('\n')}` : '',
+            ].filter(Boolean).join('\n\n'),
+            column:      'todo',
+            priority:    task.priority || 'medium',
+            taskType:    s.role === 'reviewer' ? 'feature' : (task.taskType || 'feature'),
+            parentTask:  taskId,
+            suggestedFiles: s.files || [],
+          })
+          if (childRes?.success) {
+            createdTasks.push({
+              taskId:  childRes.data?.task?._id,
+              taskKey: childRes.data?.task?.key,
+              title:   childRes.data?.task?.title,
+              role:    s.role,
+              files:   s.files,
+            })
+          }
+        } catch { /* non-fatal — continue creating remaining tasks */ }
+      }
+
       return text({
         decomposed: true,
         taskKey:    task.key,
         executionPlan,
-        subtasksCreated: subtaskPlan.length,
-        message: `Decomposition saved. ${subtaskPlan.length} subtask(s) added to the board.`,
+        childTasksCreated: createdTasks.length,
+        childTasks: createdTasks,
+        message: `Decomposition saved. ${createdTasks.length} child task(s) created on the board (${subtaskPlan.length - createdTasks.length} failed).`,
         nextStep: parallelGroups.length > 0
           ? `⚡ COORDINATOR: Call get_parallel_kickoffs with taskId="${taskId}" NOW. It writes Cursor Background Agent files for each parallel builder automatically. Then tell the user to open Background Agents panel (⌘⇧J) and click Start. DO NOT implement code yourself.`
           : `Call get_parallel_kickoffs with taskId="${taskId}". It writes a Cursor Background Agent file for the builder. Tell the user to open Background Agents panel (⌘⇧J) and start it.`,
@@ -982,10 +1516,57 @@ Returns:
         message: 'GitHub is still computing mergeability. Wait a few seconds and call check_merge_conflicts again.',
       })
 
-      if (!d.hasConflict && d.behindBy === 0) return text({
-        status:  'clean',
-        message: `PR is clean — no conflicts, not behind ${d.base}. Safe to merge.`,
-      })
+      if (!d.hasConflict && d.behindBy === 0) {
+        // Branch is clean — remove conflict-resolver.mdc if it was written during a previous kickoff.
+        // Leaving it on disk keeps injecting "BRANCH CONFLICT ACTIVE" into every Cursor prompt forever.
+        let cleanedRuleFile = false
+        try {
+          const root = findRepoRoot(process.cwd())
+          if (root) {
+            const ruleFile = join(root, '.cursor', 'rules', 'conflict-resolver.mdc')
+            if (existsSync(ruleFile)) {
+              unlinkSync(ruleFile)
+              cleanedRuleFile = true
+            }
+          }
+        } catch { /* non-fatal — never block on cleanup */ }
+        return text({
+          status:  'clean',
+          message: `PR is clean — no conflicts, not behind ${d.base}. Safe to merge.`,
+          ...(cleanedRuleFile ? { cleaned: 'conflict-resolver.mdc removed from .cursor/rules/ — Cursor will no longer inject conflict warnings.' } : {}),
+        })
+      }
+
+      // Diff-based fallback: when conflicting files exist but no task owns them via claimedFiles,
+      // scan the git tree to find branches that touch the same files without having claimed them.
+      // This catches real overlaps when developers skip claim_files or edit files directly.
+      let uncoveredConflicts = []
+      if (d.hasConflict && d.conflictingFiles?.length > 0) {
+        try {
+          const taskRes = await api.get(`/api/tasks/${taskId}`)
+          const projectId = taskRes?.data?.task?.project
+          if (projectId) {
+            const treeRes = await api.get(`/api/projects/${projectId}/github/git-tree`).catch(() => null)
+            if (treeRes?.success) {
+              const coveredFiles = new Set((d.conflictingTasks || []).flatMap(t => t.claimedFiles || []))
+              const branches = treeRes.data.branches || []
+              for (const file of d.conflictingFiles) {
+                if (coveredFiles.has(file)) continue  // already identified via claimedFiles
+                const matches = branches
+                  .filter(b => String(b.taskId) !== taskId && (b.claimedFiles || []).includes(file))
+                  .map(b => ({ taskKey: b.taskKey, branch: b.headBranch, assignees: (b.assignees || []).map(a => a.name).join(', ') }))
+                uncoveredConflicts.push({
+                  file,
+                  likelyCausedBy: matches.length > 0 ? matches : null,
+                  hint: matches.length === 0
+                    ? `No task claims this file. Check: git log origin/${d.base} -- ${file} --oneline -5`
+                    : null,
+                })
+              }
+            }
+          }
+        } catch { /* non-fatal */ }
+      }
 
       return text({
         status:         d.hasConflict ? 'conflict' : 'behind',
@@ -995,10 +1576,11 @@ Returns:
         headBranch:     d.headBranch,
         conflictingFiles:  d.conflictingFiles,
         conflictingTasks:  d.conflictingTasks,
+        ...(uncoveredConflicts.length > 0 ? { uncoveredConflicts } : {}),
         coordinationNote:  d.coordinationNote,
         resolution: {
           steps: d.resolution,
-          note: d.hasConflict && d.conflictingTasks?.length > 0
+          note: d.hasConflict && (d.conflictingTasks?.length > 0 || uncoveredConflicts.length > 0)
             ? `⚠️  COORDINATE FIRST: Contact the assignees of the conflicting tasks before resolving. Resolving without coordination may overwrite their work.`
             : `Rebase your branch on ${d.base} to resolve.`,
         },
@@ -1058,6 +1640,27 @@ the Edit tool to resolve the conflict markers, then continue the rebase with Bas
         } catch { /* non-fatal */ }
       }
 
+      // Fallback: no task owns this file via claimedFiles — conflict came from a direct commit to the
+      // base branch. Fetch the 5 most recent commits touching this file so the agent can read
+      // what changed and why, instead of getting a generic "check git log" message.
+      let recentMainCommits = null
+      if (!otherTask && task.project) {
+        try {
+          const base = conflictData.base || 'main'
+          const commitsRes = await api.get(
+            `/api/projects/${task.project}/github/commits?sha=${base}&per_page=5&path=${encodeURIComponent(filePath)}`
+          )
+          if (commitsRes?.success && commitsRes.data?.commits?.length > 0) {
+            recentMainCommits = commitsRes.data.commits.slice(0, 5).map(c => ({
+              sha:     c.sha?.slice(0, 7),
+              message: c.commit?.message?.split('\n')[0],
+              author:  c.commit?.author?.name,
+              date:    c.commit?.author?.date,
+            }))
+          }
+        } catch { /* non-fatal */ }
+      }
+
       const base = conflictData.base || 'main'
 
       return text({
@@ -1069,7 +1672,11 @@ the Edit tool to resolve the conflict markers, then continue the rebase with Bas
           scoutReport: task.scoutReport    || null,
         },
         otherTask: otherTask || {
-          note: 'Could not identify the specific task that caused this conflict. The conflict was likely introduced by a recent merge to ' + base + '. Check: git log origin/' + base + ' -- ' + filePath,
+          note: 'No task claims this file — conflict came from a direct commit to ' + base + '.',
+          ...(recentMainCommits
+            ? { recentCommits: recentMainCommits, hint: 'Read recentCommits above to understand what changed in ' + base + ' before deciding what to keep.' }
+            : { hint: 'Run: git log origin/' + base + ' -- ' + filePath + ' --oneline -5' }
+          ),
         },
         conflictMarkers: {
           ours:   '<<<<<<< HEAD  ← YOUR changes (this task)',
@@ -1231,7 +1838,7 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
       const ctx = res.data
 
       const effectiveRole = ctx.role
-      const roleRules     = effectiveRole && ROLE_RULES[effectiveRole] ? ROLE_RULES[effectiveRole] : null
+      const roleRules     = getRoleRules(effectiveRole, ctx.claimedFiles || [])
 
       // Compose the full system prompt
       const parts = []
@@ -2192,6 +2799,24 @@ Call this when the developer says "generate standup", "what did I do yesterday",
       const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000)
       const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 }
 
+      // 0. Real git commits since midnight (local repo)
+      let gitCommitsToday = []
+      try {
+        const midnight = new Date()
+        midnight.setHours(0, 0, 0, 0)
+        const out = execSync(
+          `git log --since="${midnight.toISOString()}" --format="%h|||%s|||%an|||%D" --all 2>/dev/null`,
+          { cwd: process.cwd(), encoding: 'utf8', timeout: 3000 }
+        )
+        gitCommitsToday = out.trim().split('\n').filter(Boolean).map(line => {
+          const [sha, msg, author, refs] = line.split('|||')
+          return { sha: sha?.slice(0, 7), message: msg?.trim(), author: author?.trim(), refs: refs?.trim() || null }
+        })
+      } catch { /* non-fatal — local git not available */ }
+
+      // 0b. PRs opened or merged today (across my tasks)
+      // We'll collect these from task activity below
+
       // 1. Who am I?
       const meRes = await api.get('/api/auth/me')
       const me = meRes?.data?.user || {}
@@ -2306,10 +2931,14 @@ Call this when the developer says "generate standup", "what did I do yesterday",
       const todayFocus = Object.entries(byAssignee)
         .map(([person, tasks]) => `  ${person}: ${tasks.map(t => `${t.key} (${t.priority})`).join(', ')}`)
         .join('\n')
+      const gitCommitsSummary = gitCommitsToday.length > 0
+        ? gitCommitsToday.slice(0, 5).map(c => `  \`${c.sha}\` ${c.message}`).join('\n')
+        : null
       const copyPaste = [
         `**Yesterday:** ${yesterdayItems.length
           ? yesterdayItems.map(i => `${i.key} — ${i.activity.slice(0,2).join('; ')}`).join('. ')
           : 'No recorded activity in last 24 h.'}`,
+        gitCommitsSummary ? `**Commits today:**\n${gitCommitsSummary}` : null,
         `**Today:**\n${todayFocus || '  No active tasks.'}`,
         blockers.length ? `**Blockers:** ${blockers.join(' | ')}` : '**Blockers:** None.',
         risks.length    ? `**Risks:** ${risks.join(' | ')}` : null,
@@ -2317,6 +2946,7 @@ Call this when the developer says "generate standup", "what did I do yesterday",
 
       return text({
         me:          { name: me.name, email: me.email, role: me.role },
+        gitCommitsToday: gitCommitsToday.length ? gitCommitsToday : '(no local git commits found since midnight)',
         yesterday:   yesterdayItems.length ? yesterdayItems : '(no activity logged in last 24 h)',
         today: {
           byAssignee: Object.fromEntries(
@@ -2349,80 +2979,150 @@ Call this when the developer says "generate standup", "what did I do yesterday",
     'what_should_i_work_on',
     `Recommend the single most important task to work on right now.
 
-Scores all assigned tasks by: priority, urgency (PR needs fix), column state, branch readiness.
-Returns the #1 pick with a clear reason and the exact next MCP call to make.
+Scores all assigned tasks by: priority, urgency (PR needs fix), column state, branch readiness,
+files you recently edited (git log), and PRs waiting for your review.
+
+Also surfaces:
+- Pending approval reviews assigned to you
+- Tasks you can unblock (blockers that are now done)
 
 Use this when the developer says "what should I do next", "I'm free", or "what's my priority".`,
     {},
     async () => {
-      const res = await api.get('/api/users/me/tasks')
-      if (!res?.success) return errorText('Could not fetch tasks')
-      const tasks = (res.data.tasks || []).filter(t => t.column !== 'done')
+      // Fetch my tasks + identity in parallel
+      const [tasksRes, meRes] = await Promise.all([
+        api.get('/api/users/me/tasks'),
+        api.get('/api/auth/me'),
+      ])
+      if (!tasksRes?.success) return errorText('Could not fetch tasks')
+      const tasks = (tasksRes.data.tasks || []).filter(t => t.column !== 'done')
+      const meId  = meRes?.data?.user?._id || ''
 
-      if (!tasks.length) return text({ recommendation: 'No open tasks assigned to you. Ask your project lead for work.' })
+      // Recently edited files from local git (last 2 days) — boosts tasks claiming those files
+      let recentFiles = new Set()
+      try {
+        const out = execSync(
+          'git log --since=2.days.ago --name-only --format="" --diff-filter=ACM 2>/dev/null',
+          { cwd: process.cwd(), encoding: 'utf8', timeout: 3000 }
+        )
+        out.split('\n').map(s => s.trim()).filter(Boolean).forEach(f => recentFiles.add(f))
+      } catch { /* non-fatal — local git may not be available */ }
+
+      // Pending approval reviews assigned to me (across all projects)
+      let pendingReviews = []
+      try {
+        const projectsRes = await api.get('/api/projects')
+        const projects = projectsRes?.data?.projects || []
+        const boards = await Promise.all(
+          projects.map(p => api.get(`/api/projects/${p._id}`).catch(() => null))
+        )
+        for (const r of boards.filter(Boolean)) {
+          for (const t of (r?.data?.project?.tasks || [])) {
+            const apv = (t.approvals || []).find(a => a.state === 'pending')
+            if (!apv) continue
+            const rid = apv?.reviewer?._id || apv?.reviewer
+            if (!meId || !rid || String(rid) !== String(meId)) continue
+            const waitMs = apv.requestedAt ? Date.now() - new Date(apv.requestedAt).getTime() : 0
+            pendingReviews.push({
+              taskId:       t._id,
+              key:          t.key,
+              title:        t.title,
+              waitingHours: Math.round(waitMs / 3600000 * 10) / 10,
+              submittedBy:  apv?.requestedBy?.name || apv?.requestedBy?.email || 'unknown',
+            })
+          }
+        }
+        pendingReviews.sort((a, b) => b.waitingHours - a.waitingHours)
+      } catch { /* non-fatal */ }
+
+      if (!tasks.length && !pendingReviews.length) {
+        return text({ recommendation: 'No open tasks or pending reviews. Ask your project lead for work.' })
+      }
 
       function scoreTask(t) {
         const PRIORITY = { critical: 100, high: 60, medium: 30, low: 10 }
         let score = PRIORITY[t.priority] ?? 0
         if (t.github?.changesRequestedAt)  score += 80  // PR needs fix — most urgent
-        if (t.column === 'in_progress')    score += 25  // already in flight, keep momentum
-        if (t.column === 'in_review')      score += 10  // waiting on reviewer, low action needed
+        if (t.column === 'in_progress')    score += 25  // already in flight
+        if (t.column === 'in_review')      score += 10  // waiting on reviewer
         if (t.column === 'todo')           score += 15  // ready to start
         if (t.column === 'backlog')        score -= 10  // not yet planned
         if (t.parkNote?.parkedAt)          score -= 20  // intentionally paused
-        if (t.github?.headBranch)          score += 5   // branch already set up
+        if (t.blockedBy?.some(b => typeof b === 'object' ? b.column !== 'done' : false)) score -= 50
+        if (t.github?.headBranch)          score += 5
+        // Boost tasks overlapping files you've been editing recently
+        if (recentFiles.size > 0 && (t.claimedFiles || []).some(f => recentFiles.has(f))) score += 20
         return score
       }
 
-      const scored = tasks
-        .map(t => ({ ...t, _score: scoreTask(t) }))
-        .sort((a, b) => b._score - a._score)
-
-      const top = scored[0]
-
-      // Build the reason and next step
-      let reason, nextStep
-      if (top.github?.changesRequestedAt) {
-        reason   = `PR has changes requested — this blocks the merge and the reviewer is waiting.`
-        nextStep = `Call fix_pr_feedback with taskAId="${top._id}" to get the full fix plan.`
-      } else if (top.column === 'in_progress' && top.github?.headBranch) {
-        reason   = `Already in progress on branch ${top.github.headBranch} — keep the momentum going.`
-        nextStep = `Continue coding on ${top.github.headBranch}. When commits are pushed, call raise_pr.`
-      } else if (top.column === 'in_progress' && !top.github?.headBranch) {
-        reason   = `In progress but no branch yet — needs a branch to start committing.`
-        nextStep = `Call create_branch with taskId="${top._id}" and projectId="${top.project?._id || top.project}".`
-      } else if (top.column === 'todo') {
-        reason   = `Highest priority unstarted task — ready to kick off.`
-        nextStep = `Call kickoff_task with taskId="${top._id}" to read the plan and move to in_progress.`
-      } else {
-        reason   = `Highest priority available task.`
-        nextStep = `Call get_task_context with taskId="${top._id}" for full details.`
-      }
-
-      // Show the queue (top 3)
-      const queue = scored.slice(0, 3).map((t, i) => ({
-        rank:     i + 1,
-        key:      t.key,
-        title:    t.title,
-        priority: t.priority,
-        column:   t.column,
-        score:    t._score,
-        branch:   t.github?.headBranch || null,
-        needsFix: !!t.github?.changesRequestedAt,
-      }))
-
-      return text({
-        recommendation: {
-          taskId:   top._id,
-          key:      top.key,
-          title:    top.title,
-          priority: top.priority,
-          column:   top.column,
-          project:  top.project?.name || top.project,
+      const scored = tasks.length
+        ? tasks.map(t => ({ ...t, _score: scoreTask(t) })).sort((a, b) => b._score - a._score)
+        : []
+
+      // If pending reviews are waiting and outrank the top task, surface review first
+      const longestWaitingReview = pendingReviews[0]
+      const topTask = scored[0]
+
+      let recommendation, isReview = false
+      if (longestWaitingReview && (!topTask || longestWaitingReview.waitingHours > 4)) {
+        isReview = true
+        recommendation = {
+          type:     'review',
+          taskId:   longestWaitingReview.taskId,
+          key:      longestWaitingReview.key,
+          title:    longestWaitingReview.title,
+          reason:   `Approval review waiting ${longestWaitingReview.waitingHours}h — ${longestWaitingReview.submittedBy} is blocked on you.`,
+          nextStep: `Call get_review_bundle with taskId="${longestWaitingReview.taskId}" to start the review.`,
+        }
+      } else if (topTask) {
+        let reason, nextStep
+        if (topTask.github?.changesRequestedAt) {
+          reason   = `PR has changes requested — this blocks the merge and the reviewer is waiting.`
+          nextStep = `Call fix_pr_feedback with taskAId="${topTask._id}" to get the full fix plan.`
+        } else if (topTask.column === 'in_progress' && topTask.github?.headBranch) {
+          const fileHint = recentFiles.size > 0 && (topTask.claimedFiles || []).some(f => recentFiles.has(f))
+            ? ' (matches your recent git activity)'
+            : ''
+          reason   = `Already in progress on branch ${topTask.github.headBranch} — keep the momentum going.${fileHint}`
+          nextStep = `Continue coding on ${topTask.github.headBranch}. When commits are pushed, call raise_pr.`
+        } else if (topTask.column === 'in_progress' && !topTask.github?.headBranch) {
+          reason   = `In progress but no branch yet — needs a branch to start committing.`
+          nextStep = `Call create_branch with taskId="${topTask._id}" and projectId="${topTask.project?._id || topTask.project}".`
+        } else if (topTask.column === 'todo') {
+          reason   = `Highest priority unstarted task — ready to kick off.`
+          nextStep = `Call kickoff_task with taskId="${topTask._id}" to read the plan and move to in_progress.`
+        } else {
+          reason   = `Highest priority available task.`
+          nextStep = `Call get_task_context with taskId="${topTask._id}" for full details.`
+        }
+        recommendation = {
+          type:     'task',
+          taskId:   topTask._id,
+          key:      topTask.key,
+          title:    topTask.title,
+          priority: topTask.priority,
+          column:   topTask.column,
+          project:  topTask.project?.name || topTask.project,
           reason,
           nextStep,
-        },
-        queue,
+        }
+      }
+
+      return text({
+        recommendation,
+        queue: scored.slice(0, 3).map((t, i) => ({
+          rank:     i + 1,
+          key:      t.key,
+          title:    t.title,
+          priority: t.priority,
+          column:   t.column,
+          score:    t._score,
+          branch:   t.github?.headBranch || null,
+          needsFix: !!t.github?.changesRequestedAt,
+          recentFileMatch: recentFiles.size > 0 && (t.claimedFiles || []).some(f => recentFiles.has(f)),
+        })),
+        pendingReviews: pendingReviews.length > 0 ? pendingReviews : null,
+        recentFilesDetected: recentFiles.size,
       })
     }
   )
@@ -2556,6 +3256,28 @@ Use this when the developer or team lead asks "how's the board?", "any blockers?
               suggestion: `Use update_task to add a readmeMarkdown implementation plan`,
             })
           }
+
+          // Stale PR — open 5+ days with no approval or changes-requested (forgotten in review queue)
+          if (
+            t.column === 'in_review' &&
+            t.github?.prNumber &&
+            ageDays > 5 &&
+            !t.github?.changesRequestedAt  // already flagged above if changes were requested
+          ) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `PR #${t.github.prNumber} has been open ${Math.floor(ageDays)} days with no reviewer action — likely forgotten`,
+              suggestion: t.github?.prUrl
+                ? `Check PR at ${t.github.prUrl} — ping the reviewer or close if abandoned`
+                : `Check GitHub for PR #${t.github.prNumber} — ping the reviewer`,
+              prNumber:   t.github.prNumber,
+              prUrl:      t.github.prUrl || null,
+            })
+          }
         }
       }
 
@@ -2582,21 +3304,138 @@ Use this when the developer or team lead asks "how's the board?", "any blockers?
 
   server.tool(
     'end_of_day',
-    `End-of-day wrap-up. For every task currently in_progress:
-1. Parks it with the provided notes (run "git diff HEAD" first to fill these accurately)
-2. Returns a summary of what was wrapped
+    `End-of-day wrap-up — call with confirmed=false first to get a checklist, then confirmed=true to park tasks.
+
+Phase 1 (confirmed=false — default):
+- Scans local git for uncommitted changes and unpushed commits
+- Fetches your in_progress tasks
+- Detects stale PRs (open 5+ days)
+- Returns a full action checklist so nothing is left behind
+
+Phase 2 (confirmed=true):
+- Parks each in_progress task with your notes
+- Releases file claims on parked tasks
 
-After this tool runs, post a short comment on each parked task via add_task_comment summarising the day.
 Use this when the developer says "wrap up", "end of day", or "I'm done for today".`,
     {
+      confirmed: z.boolean().optional().default(false).describe('Set true to actually park the tasks after reviewing the checklist'),
       taskNotes: z.array(z.object({
         taskId:    z.string().describe("Task's MongoDB ObjectId"),
         summary:   z.string().describe('What was done today — be specific, include file names'),
         remaining: z.string().describe('What is left to do next session'),
-        blockers:  z.string().optional().describe('Anything blocking'),
-      })).describe('Park notes for each in_progress task. Call get_my_tasks(column="in_progress") first to get the list.'),
+        blockers:  z.string().optional().describe('Anything blocking progress'),
+      })).optional().describe('Park notes for each in_progress task. Required when confirmed=true.'),
     },
-    async ({ taskNotes }) => {
+    async ({ confirmed = false, taskNotes = [] }) => {
+      // Always fetch in-progress tasks and git state
+      const myTasksRes = await api.get('/api/users/me/tasks')
+      const inProgress = (myTasksRes?.data?.tasks || []).filter(t => t.column === 'in_progress')
+
+      // Local git state
+      let gitState = { uncommitted: [], unpushedBranches: [], currentBranch: null }
+      try {
+        const cwd = process.cwd()
+        const repoRoot = findRepoRoot(cwd)
+        if (repoRoot) {
+          // Uncommitted changes
+          const statusOut = execSync('git status --short 2>/dev/null', { cwd: repoRoot, encoding: 'utf8', timeout: 3000 })
+          gitState.uncommitted = statusOut.trim().split('\n').filter(Boolean)
+          // Current branch
+          try {
+            gitState.currentBranch = execSync('git rev-parse --abbrev-ref HEAD 2>/dev/null', { cwd: repoRoot, encoding: 'utf8', timeout: 2000 }).trim()
+          } catch { /* non-fatal */ }
+          // Unpushed commits on current branch
+          if (gitState.currentBranch && gitState.currentBranch !== 'HEAD') {
+            try {
+              const unpushed = execSync(
+                `git log origin/${gitState.currentBranch}..HEAD --format="%h %s" 2>/dev/null || git log HEAD -3 --format="%h %s"`,
+                { cwd: repoRoot, encoding: 'utf8', timeout: 3000 }
+              )
+              gitState.unpushedBranch = unpushed.trim().split('\n').filter(Boolean)
+            } catch { /* non-fatal */ }
+          }
+        }
+      } catch { /* non-fatal */ }
+
+      // Stale PRs (in_review 5+ days)
+      const now = Date.now()
+      const stalePRs = inProgress
+        .concat((myTasksRes?.data?.tasks || []).filter(t => t.column === 'in_review'))
+        .filter(t => {
+          if (!t.github?.prNumber) return false
+          const ageDays = (now - new Date(t.updatedAt).getTime()) / (1000 * 60 * 60 * 24)
+          return ageDays > 5
+        })
+        .map(t => ({ key: t.key, title: t.title, prNumber: t.github.prNumber, prUrl: t.github.prUrl || null }))
+
+      if (!confirmed) {
+        // Phase 1: checklist
+        const checklist = []
+        if (gitState.uncommitted.length > 0) {
+          checklist.push({
+            urgent: true,
+            action: 'Commit uncommitted changes',
+            detail: `${gitState.uncommitted.length} file(s) modified but not committed`,
+            files:  gitState.uncommitted.slice(0, 10),
+            cmd:    `git add -p && git commit -m "wip: end of day checkpoint"`,
+          })
+        }
+        if (gitState.unpushedBranch?.length > 0) {
+          checklist.push({
+            urgent: true,
+            action: 'Push unpushed commits',
+            detail: `${gitState.unpushedBranch.length} commit(s) not pushed to remote`,
+            commits: gitState.unpushedBranch,
+            cmd:    `git push origin ${gitState.currentBranch}`,
+          })
+        }
+        if (inProgress.length > 0) {
+          checklist.push({
+            urgent: false,
+            action: 'Park in-progress tasks with notes',
+            detail: `${inProgress.length} task(s) need a park note so work can resume cleanly`,
+            tasks:  inProgress.map(t => ({ taskId: t._id, key: t.key, title: t.title, branch: t.github?.headBranch || null })),
+            nextStep: `Fill taskNotes for each task above, then call end_of_day with confirmed=true`,
+          })
+        }
+        if (stalePRs.length > 0) {
+          checklist.push({
+            urgent: false,
+            action: 'Follow up on stale PRs',
+            detail: `${stalePRs.length} PR(s) open 5+ days with no reviewer action`,
+            prs:    stalePRs,
+          })
+        }
+
+        return text({
+          checklist,
+          gitState: {
+            currentBranch:   gitState.currentBranch,
+            uncommitted:     gitState.uncommitted.length,
+            unpushedCommits: gitState.unpushedBranch?.length || 0,
+          },
+          inProgressTasks: inProgress.map(t => ({ taskId: t._id, key: t.key, title: t.title })),
+          stalePRs:        stalePRs.length ? stalePRs : null,
+          message: checklist.length === 0
+            ? '✅ All clear — no uncommitted work, no unpushed commits, no in-progress tasks. Good day!'
+            : `${checklist.filter(c => c.urgent).length} urgent item(s) need attention before logging off.`,
+          nextStep: inProgress.length > 0
+            ? `Fill taskNotes for your in-progress tasks then call end_of_day with confirmed=true and taskNotes=[...].`
+            : checklist.some(c => c.urgent)
+            ? `Handle the urgent items above (commit/push), then you are done.`
+            : `Nothing to park. You are good to go.`,
+        })
+      }
+
+      // Phase 2: park tasks
+      if (!taskNotes.length && inProgress.length > 0) {
+        return text({
+          blocked: true,
+          message: `confirmed=true requires taskNotes for each in-progress task. Call end_of_day with confirmed=false first to get the task list.`,
+          inProgressTasks: inProgress.map(t => ({ taskId: t._id, key: t.key, title: t.title })),
+        })
+      }
+
       const results = []
       for (const note of taskNotes) {
         try {
@@ -2614,7 +3453,15 @@ Use this when the developer says "wrap up", "end of day", or "I'm done for today
           results.push({ taskId: note.taskId, success: false, message: e.message })
         }
       }
-      return text({ wrapped: results })
+
+      return text({
+        wrapped: results,
+        stalePRs: stalePRs.length ? stalePRs : null,
+        gitReminder: gitState.uncommitted.length > 0 || gitState.unpushedBranch?.length > 0
+          ? `⚠️  You still have ${gitState.uncommitted.length} uncommitted file(s) and ${gitState.unpushedBranch?.length || 0} unpushed commit(s). Push before logging off!`
+          : null,
+        message: `${results.filter(r => r.success).length}/${results.length} task(s) parked successfully.`,
+      })
     }
   )
 
@@ -2643,13 +3490,36 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       repoPath:  z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory). Used to write cursor rules file.'),
       agentRole: z.enum(['builder', 'reviewer', 'scout', 'coordinator']).optional()
         .describe('Set the agent role for this task session. Role-specific behavioral constraints are injected into cursor rules. builder=implements code, scout=reads/analyzes only, reviewer=reviews PRs only, coordinator=decomposes work.'),
+      files: z.array(z.string()).optional()
+        .describe('REQUIRED for agentRole=builder. Files this builder will exclusively edit (e.g. ["server/routes/tasks.js", "client/src/App.jsx"]). Ownership is claimed atomically during kickoff — kickoff is blocked until files are provided. Read the implementation plan first (confirmed=false), identify your files, then call confirmed=true with this list.'),
     },
-    async ({ taskId, confirmed = false, repoPath, agentRole }) => {
+    async ({ taskId, confirmed = false, repoPath, agentRole, files }) => {
       trackTaskActivity(taskId, 'kickoff_task')
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
 
+      // Warn if task has unresolved blockers
+      const activeBlockers = (task.blockedBy || []).filter(b => {
+        if (typeof b === 'object' && b !== null && b.column !== undefined) return b.column !== 'done'
+        return false  // if not populated, can't check — don't block
+      })
+      if (activeBlockers.length > 0) {
+        return text({
+          blocked: true,
+          reason: 'This task has unresolved dependencies that must complete first.',
+          blockers: activeBlockers.map(b => ({
+            taskKey: b.key || b._id,
+            title:   b.title || '(unknown)',
+            column:  b.column || 'unknown',
+          })),
+          message: `⛔ Cannot kick off ${task.key} — ${activeBlockers.length} blocker(s) must complete first.`,
+          nextStep: activeBlockers.length === 1
+            ? `Work on ${activeBlockers[0].key || 'the blocker task'} first. Call remove_blocker when it's done.`
+            : `Complete the blockers listed above. Call remove_blocker for each one when done.`,
+        })
+      }
+
       // Include developer name in branch so it's clear who created it
       let devSlug = ''
       try {
@@ -2970,6 +3840,59 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         })
       }
 
+      // ── Builder file ownership gate ───────────────────────────────────────────
+      // Structural equivalent of BridgeSwarm's file-lock: a builder cannot complete
+      // kickoff without declaring which files it owns. This prevents two agents editing
+      // the same file because both kickoffs either succeed (different files) or one is
+      // blocked (conflict detected before a single line of code is written).
+      if (agentRole === 'builder') {
+        if (!files?.length) {
+          // Hard block — return plan context so agent can identify files, then retry
+          return text({
+            requiresFileClaim: true,
+            taskKey:   task.key,
+            title:     task.title,
+            implementationPlan: task.readmeMarkdown || '(no plan — write one in the Plan tab first)',
+            scoutReport:        task.scoutReport    || null,
+            subtasks:  (task.subtasks || []).map(s => ({ title: s.title, done: s.done })),
+            message: [
+              `⛔ Builder kickoff blocked — file ownership required.`,
+              ``,
+              `Read the implementation plan above and identify EVERY file you will create or modify.`,
+              `Then call kickoff_task again with confirmed=true, agentRole="builder", and files=[...].`,
+              ``,
+              `This is enforced structurally: kickoff cannot complete until files are declared.`,
+              `It prevents two agents from editing the same file simultaneously.`,
+            ].join('\n'),
+            nextStep: `kickoff_task(taskId="${taskId}", confirmed=true, agentRole="builder", files=["path/to/file1", "path/to/file2"])`,
+          })
+        }
+
+        // Files provided — attempt atomic claim before proceeding with kickoff
+        const claimRes = await api.post(`/api/tasks/${taskId}/files/claim`, { files }).catch(() => null)
+        if (!claimRes?.success) {
+          if (claimRes?.conflicts) {
+            return text({
+              blocked: true,
+              reason:  `File ownership conflict — another in-progress task already owns one or more of your files.`,
+              conflicts: claimRes.conflicts,
+              message: [
+                `⛔ Builder kickoff blocked — file conflict detected.`,
+                ``,
+                `The files listed in conflicts[] are already claimed by another task.`,
+                `Options:`,
+                `1. Coordinate with the other task's assignee and wait for them to release the files.`,
+                `2. Remove the conflicting files from your list if you don't actually need them.`,
+                `3. Call release_files on the other task if it is no longer active (coordinator only).`,
+              ].join('\n'),
+              nextStep: `Resolve the conflict, then retry: kickoff_task(taskId="${taskId}", confirmed=true, agentRole="builder", files=[...updated list...])`,
+            })
+          }
+          return errorText(claimRes?.message || 'Could not claim files — retry kickoff_task with confirmed=true and files=[...]')
+        }
+        // Files claimed successfully — kickoff continues below with ownership established
+      }
+
       // ── #1 Preflight: check dirty tree before writing cursor rules / moving task ──
       {
         const pCwd  = repoPath || process.cwd()
@@ -3104,7 +4027,9 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       const baseRules = hasCursorRules ? task.cursorRules : ''
       const mergedRules = [baseRules, typeExtraRules].filter(Boolean).join('\n\n') || '(Follow role constraints above.)'
       if (hasCursorRules || agentRole || typeExtraRules) {
-        cursorRulesFile = writeCursorRulesFile(task.key, mergedRules, repoPath, agentRole || null)
+        // Pass claimedFiles so the builder cursor rule lists exactly which files are owned
+        const effectiveClaimedFiles = files?.length ? files : (task.claimedFiles || [])
+        cursorRulesFile = writeCursorRulesFile(task.key, mergedRules, repoPath, agentRole || null, effectiveClaimedFiles)
       }
 
       // Dynamically generate .cursor/agents, .cursor/skills, .cursor/commands
@@ -3166,6 +4091,15 @@ After \`request_human_input\`: STOP, show the question in chat, wait for reply,
       }
       api.patch(`/api/tasks/${taskId}`, workspacePatch).catch(() => {/* non-fatal */})
 
+      // Write .internaltool-active-task so the Claude Code hook knows a task is active
+      try {
+        writeFileSync(
+          join(process.cwd(), '.internaltool-active-task'),
+          JSON.stringify({ taskId, taskKey: task.key, title: task.title, agentRole: agentRole || null, kickedOffAt: new Date().toISOString() }, null, 2),
+          'utf8'
+        )
+      } catch { /* non-fatal — hook gracefully degrades if file can't be written */ }
+
       // Auto-scan workspace so the Workspace tab in the UI is fresh immediately after kickoff.
       if (kickoffProject) {
         runWorkspaceScan(taskId, task, kickoffProject, repoPath).catch(() => {/* non-fatal */})
@@ -3187,7 +4121,7 @@ After \`request_human_input\`: STOP, show the question in chat, wait for reply,
               active: true,
               agentRole: agentRole || null,
               rules: task.cursorRules || null,
-              roleRules: agentRole ? ROLE_RULES[agentRole] : null,
+              roleRules: agentRole ? getRoleRules(agentRole, task.claimedFiles || []) : null,
               instruction: agentRole
                 ? `⚠️  AGENT ROLE: ${agentRole.toUpperCase()} — Follow the role behavioral constraints injected into the cursor rules file. These override default behavior.`
                 : '⚠️  CURSOR RULES ACTIVE — You MUST follow every rule in the "rules" field for the entire duration of this task.',
@@ -3363,6 +4297,52 @@ function registerIssueTools(server) {
 }
 
 function registerApprovalTools(server) {
+  // ── report_test_results ───────────────────────────────────────────────────────
+  server.tool(
+    'report_test_results',
+    `Save a test run result to the task — call this after running the test suite.
+
+REQUIRED WORKFLOW:
+1. Run tests using your shell or the run-tests skill
+2. Parse the output to extract pass/fail counts
+3. Call this tool to attach the results to the task
+
+The latest test run is visible in the UI and blocks submit_task_for_approval if failing.
+Calling this with status="passing" is required before submitting for approval.
+
+How to determine status:
+- "passing"  → all tests pass (failed === 0)
+- "partial"  → some pass, some fail — needs investigation
+- "failing"  → no tests pass or test runner itself crashed`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      status:    z.enum(['passing', 'failing', 'partial']).describe('Overall test run outcome'),
+      total:     z.number().optional().default(0).describe('Total number of tests run'),
+      passed:    z.number().optional().default(0).describe('Tests that passed'),
+      failed:    z.number().optional().default(0).describe('Tests that failed'),
+      skipped:   z.number().optional().default(0).describe('Tests that were skipped'),
+      summary:   z.string().describe('One-line summary, e.g. "42 passed, 2 failed in 3.4s"'),
+      rawOutput: z.string().optional().default('').describe('Raw test output (truncated to 3000 chars) for reviewer context'),
+    },
+    async ({ taskId, status, total = 0, passed = 0, failed = 0, skipped = 0, summary, rawOutput = '' }) => {
+      trackTaskActivity(taskId, 'report_test_results', { summary: `Tests: ${status} (${passed}/${total})` })
+      const res = await api.post(`/api/tasks/${taskId}/test-runs`, {
+        status, total, passed, failed, skipped,
+        summary,
+        raw: rawOutput.slice(0, 3000),
+      })
+      if (!res?.success) return errorText(res?.message || 'Could not save test results')
+      const icon = status === 'passing' ? '✅' : status === 'partial' ? '⚠️' : '❌'
+      return text({
+        saved: true, status, summary, passed, failed, total, skipped,
+        message: `${icon} Test results saved to task.`,
+        nextStep: status === 'passing'
+          ? `Tests passing. You can now call submit_task_for_approval or raise_pr.`
+          : `${failed} test(s) failing. Fix them and call report_test_results again before submitting for approval.`,
+      })
+    }
+  )
+
   server.tool(
     'submit_task_for_approval',
     'Create and submit a new approval request on a task. Each request has its own title, plan/readme, and reviewer. Only one request can be pending at a time.',
@@ -3372,8 +4352,28 @@ function registerApprovalTools(server) {
       readme:     z.string().describe('The plan/markdown describing what you want to do and why (min 80 chars)'),
       reviewerId: z.string().describe('User ID of the reviewer'),
     },
-    async ({ taskId, title, readme, reviewerId }) =>
-      call(() => api.post(`/api/tasks/${taskId}/approvals`, { title, readme, reviewerId }))
+    async ({ taskId, title, readme, reviewerId }) => {
+      // Gate: block if latest test run is failing
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      if (taskRes?.success) {
+        const latestRun = taskRes.data?.task?.testRuns?.[0]
+        if (latestRun && latestRun.status === 'failing') {
+          return text({
+            blocked: true,
+            reason:  'Latest test run is failing — fix tests before submitting for approval.',
+            testRun: {
+              status:  latestRun.status,
+              summary: latestRun.summary,
+              failed:  latestRun.failed,
+              total:   latestRun.total,
+              runAt:   latestRun.runAt,
+            },
+            nextStep: `Fix the failing tests, then call report_test_results with status="passing" before retrying submit_task_for_approval.`,
+          })
+        }
+      }
+      return call(() => api.post(`/api/tasks/${taskId}/approvals`, { title, readme, reviewerId }))
+    }
   )
 
   server.tool(
@@ -3642,26 +4642,30 @@ function findRepoRoot(startPath) {
 // Prepended to cursor rules when an agentRole is set. Defines what the agent
 // CAN and CANNOT do for the duration of the task session.
 const ROLE_RULES = {
-  builder: `## Agent Role: BUILDER
+  builder: (claimedFiles = []) => `## Agent Role: BUILDER
 
 You are a BUILDER agent. Your behavioral constraints for this session:
 
+**YOUR CLAIMED FILES (exclusive ownership — enforced at kickoff):**
+${claimedFiles.length > 0
+  ? claimedFiles.map(f => `- ${f}`).join('\n')
+  : '- (no files claimed yet — call claim_files before editing anything)'}
+
 **ALLOWED:**
-- Write, modify, and delete code files within the task scope
-- Create new files required by the implementation plan
+- Write, modify, and delete code files listed above under YOUR CLAIMED FILES
+- Create new files required by the implementation plan (call claim_files to add them first)
 - Commit and push changes on the task branch
 - Run tests and fix failures
-- Claim file ownership before editing (use claim_files MCP tool)
 
 **NOT ALLOWED:**
-- Modify files owned by another in-progress task (check claimedFiles conflicts)
+- Edit ANY file not listed in YOUR CLAIMED FILES above without first calling claim_files
+- Modify files owned by another in-progress task
 - Make architectural decisions not in the implementation plan — flag them instead
-- Edit files outside the task scope without explicit approval
 - Merge to main/master/dev directly
 
 **WORK STYLE:**
-- Read the implementation plan fully before writing any code
-- Claim your files at the start with claim_files
+- YOUR CLAIMED FILES list is your contract — stay within it
+- If you discover you need an additional file mid-session, call claim_files first, then edit
 - Follow the spec precisely — don't add unrequested features
 - Commit atomically with conventional commit format (feat/fix/refactor)`,
 
@@ -4008,16 +5012,24 @@ function detectTaskType(task) {
 }
 
 /** Write task-specific cursor rules to .cursor/rules/<taskKey>.mdc in the local repo root.
- *  When role is provided, role-specific behavioral constraints are prepended. */
-function writeCursorRulesFile(taskKey, rulesMarkdown, startPath, role = null) {
+ *  When role is provided, role-specific behavioral constraints are prepended.
+ *  claimedFiles is passed through to the builder role template so Cursor injects
+ *  the exact file ownership list into every prompt. */
+function getRoleRules(role, claimedFiles = []) {
+  if (!role || !ROLE_RULES[role]) return null
+  const entry = ROLE_RULES[role]
+  return typeof entry === 'function' ? entry(claimedFiles) : entry
+}
+
+function writeCursorRulesFile(taskKey, rulesMarkdown, startPath, role = null, claimedFiles = []) {
   try {
     const repoRoot = findRepoRoot(startPath)
     if (!repoRoot) return null
     const rulesDir = join(repoRoot, '.cursor', 'rules')
     mkdirSync(rulesDir, { recursive: true })
     const filePath = join(rulesDir, `${taskKey.toLowerCase()}.mdc`)
-    const roleSection = role && ROLE_RULES[role]
-      ? `${ROLE_RULES[role]}\n\n---\n\n## Task-Specific Rules\n\n`
+    const roleSection = getRoleRules(role, claimedFiles)
+      ? `${getRoleRules(role, claimedFiles)}\n\n---\n\n## Task-Specific Rules\n\n`
       : ''
     const content = `---\ndescription: Task-specific rules for ${taskKey}${role ? ` (role: ${role})` : ''} — auto-generated by InternalTool MCP. Do not edit manually.\nalwaysApply: true\n---\n\n${roleSection}${rulesMarkdown}\n`
     writeFileSync(filePath, content, 'utf8')
@@ -5498,13 +6510,46 @@ Set confirmed=false first to preview the full PR content, then confirmed=true to
       }
 
       const prTitle = `[${task.key}] ${task.title}`
+
+      // Subtask checklist with completion state
+      const subtaskLines = (task.subtasks || []).map(s =>
+        `- [${s.done ? 'x' : ' '}] ${s.title}`
+      )
+
+      // Recent commits for this branch
+      let commitLines = []
+      try {
+        const commitsRes = await api.get(
+          `/api/projects/${projectId}/github/commits?sha=${encodeURIComponent(headBranch)}&per_page=10`
+        )
+        if (commitsRes?.success && commitsRes.data?.commits?.length) {
+          commitLines = commitsRes.data.commits.slice(0, 10).map(c => {
+            const msg = c.commit?.message?.split('\n')[0] || ''
+            const sha = c.sha?.slice(0, 7) || ''
+            return `- \`${sha}\` ${msg}`
+          })
+        }
+      } catch { /* non-fatal */ }
+
+      // Latest test run
+      const latestTest = task.testRuns?.[0]
+      const testLine = latestTest
+        ? latestTest.status === 'passing'
+          ? `✅ Tests passing — ${latestTest.summary}`
+          : latestTest.status === 'partial'
+            ? `⚠️ Tests partial — ${latestTest.summary}`
+            : `❌ Tests failing — ${latestTest.summary}`
+        : null
+
       const bodyParts = [
         `## ${task.key}: ${task.title}`,
         '',
-        task.description ? `### Description\n${task.description}` : null,
-        task.readmeMarkdown ? `### Implementation Notes\n${task.readmeMarkdown.slice(0, 600)}` : null,
+        task.description?.trim() ? `### What & Why\n${task.description.trim()}` : null,
+        task.readmeMarkdown?.trim() ? `### Implementation Plan\n${task.readmeMarkdown.trim()}` : null,
+        subtaskLines.length > 0 ? `### Checklist\n${subtaskLines.join('\n')}` : null,
+        commitLines.length > 0 ? `### Commits\n${commitLines.join('\n')}` : null,
+        testLine ? `### Test Results\n${testLine}` : null,
         task.parkNote?.summary ? `### Work Summary\n${task.parkNote.summary}` : null,
-        task.parkNote?.remaining ? `### What Remains\n${task.parkNote.remaining}` : null,
         additionalNotes ? `### Additional Notes\n${additionalNotes}` : null,
         '',
         '---',
@@ -6431,6 +7476,27 @@ Use this tool between those two to understand the merge context.`,
           : null
         const isStale = hoursSinceCommit !== null && hoursSinceCommit >= 48
 
+        // CI status — fetch check runs for the PR if one exists
+        let ciCheck = null
+        if (branch.prNumber) {
+          try {
+            const prRes = await api.get(`/api/projects/${projectId}/github/pull-requests/${branch.prNumber}`)
+            if (prRes?.success && prRes.data?.checks) {
+              const runs = Array.isArray(prRes.data.checks.check_runs) ? prRes.data.checks.check_runs
+                         : Array.isArray(prRes.data.checks)            ? prRes.data.checks
+                         : []
+              const total   = runs.length
+              const failed  = runs.filter(r => r.conclusion === 'failure' || r.conclusion === 'timed_out').length
+              const pending = runs.filter(r => !r.conclusion).length
+              const ciStatus = total === 0 ? 'no_checks'
+                             : failed  > 0 ? 'failing'
+                             : pending > 0 ? 'pending'
+                             : 'passing'
+              ciCheck = { status: ciStatus, total, failed, pending, passed: total - failed - pending }
+            }
+          } catch { /* non-fatal — CI is optional */ }
+        }
+
         // Build checklist
         const checklist = [
           {
@@ -6485,6 +7551,16 @@ Use this tool between those two to understand the merge context.`,
                 : 'No commit data available',
             blocking: false,
           },
+          ...(ciCheck && ciCheck.status !== 'no_checks' ? [{
+            item:   'CI checks passing',
+            passed: ciCheck.status === 'passing',
+            detail: ciCheck.status === 'passing'
+              ? `All ${ciCheck.total} CI check${ciCheck.total !== 1 ? 's' : ''} passing`
+              : ciCheck.status === 'failing'
+                ? `${ciCheck.failed} of ${ciCheck.total} CI check${ciCheck.total !== 1 ? 's' : ''} failing — fix before requesting review`
+                : `${ciCheck.pending} CI check${ciCheck.pending !== 1 ? 's' : ''} still running — wait before reviewing`,
+            blocking: ciCheck.status === 'failing',
+          }] : []),
         ]
 
         const blockingIssues = checklist.filter(c => !c.passed && c.blocking)