internaltool-mcp 1.6.19 → 1.6.24

package/index.js

@@ -397,10 +397,16 @@ Set confirmed=false first to preview, then confirmed=true to execute everything.
         cursorRulesCleared = deleteCursorRulesFile(task.key, repoPath)
       }
 
+      // ── #9 Capture last commit for handoff metadata ───────────────────────
+      const lastCommit = getLastCommitMeta(repoRoot)
+
       return text({
         parked: true,
         task:   { key: task?.key, title: task?.title, branch: task?.github?.headBranch || null },
         autoPushed: pushed ? `${unpushedCount} commit(s) pushed to origin/${currentBranch}` : 'No push needed',
+        lastCommit: lastCommit
+          ? { sha: lastCommit.sha, subject: lastCommit.subject, author: lastCommit.author, date: lastCommit.date }
+          : null,
         cursorRulesCleared: cursorRulesCleared ? `Deleted ${cursorRulesCleared}` : null,
         commentPosted: true,
         teamNotified:  true,
@@ -427,8 +433,11 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
       taskId:    z.string().describe("Task's MongoDB ObjectId"),
       confirmed: z.boolean().optional().default(false).describe('Set true to execute after reviewing the park note'),
       repoPath:  z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory).'),
+      autoStash: z.boolean().optional().default(false).describe('Auto-stash dirty working tree before switching branches instead of blocking. Stash is labelled with the task key for easy recovery.'),
+      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.'),
     },
-    async ({ taskId, confirmed = false, repoPath }) => {
+    async ({ taskId, confirmed = false, repoPath, autoStash = false, agentRole }) => {
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       const task    = taskRes?.data?.task
       const branch  = task?.github?.headBranch || null
@@ -480,6 +489,35 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
       const repoRoot = findRepoRoot(cwd)
       let gitResult  = null
 
+      // ── #1/#2 Preflight: repo readiness guard + autoStash ─────────────────
+      if (repoRoot && branch) {
+        try {
+          const porcelain = runGit('status --porcelain=v1', repoRoot)
+          const { localState, modified } = parseGitStatus(porcelain)
+          const currentBranchNow = runGit('branch --show-current', repoRoot).trim()
+          if (localState === 'modified') {
+            if (autoStash) {
+              // Auto-stash with a clear label so it can be recovered later
+              const stashLabel = `auto-stash(${task?.key?.toLowerCase() || 'unpark'}): changes on ${currentBranchNow} before switching to ${branch}`
+              runGit(`stash push -m "${stashLabel}"`, repoRoot)
+            } else {
+              return text({
+                blocked:      true,
+                reason:       `Working tree has ${modified.length} modified file(s) on "${currentBranchNow}" — cannot switch branches safely.`,
+                modifiedFiles: modified,
+                choices: {
+                  stash:  `git stash push -m "wip: before unpark ${task?.key || ''} on ${currentBranchNow}"`,
+                  commit: `git add . && git commit -m "wip(${task?.key?.toLowerCase() || 'task'}): before unpark"`,
+                  autoStash: `Call unpark_task again with autoStash=true — MCP will stash automatically with a labelled entry`,
+                  cancel: 'Review and handle your changes, then retry',
+                },
+                message: 'Handle the working tree before switching branches. Tip: use autoStash=true to let MCP do it automatically.',
+              })
+            }
+          }
+        } catch { /* non-fatal — proceed with checkout anyway */ }
+      }
+
       if (repoRoot && branch) {
         try {
           runGit('fetch origin', repoRoot)
@@ -510,23 +548,955 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
       // ── Clear park note + server-side comment & notification ──────────────
       await api.patch(`/api/tasks/${taskId}/unpark`, {})
 
-      // ── Restore cursor rules file ──────────────────────────────────────────
+      // ── Restore cursor rules file (with role injection if set) ───────────────
       let cursorRulesFile = null
-      if (task?.cursorRules?.trim()) {
-        cursorRulesFile = writeCursorRulesFile(task.key, task.cursorRules, repoPath)
+      const hasCursorRulesUnpark = task?.cursorRules?.trim()
+      if (hasCursorRulesUnpark || agentRole) {
+        cursorRulesFile = writeCursorRulesFile(
+          task.key,
+          hasCursorRulesUnpark || '(No task-specific rules — follow role constraints above.)',
+          repoPath,
+          agentRole || null
+        )
+      }
+
+      // Persist agentRole to server if set
+      if (agentRole) {
+        api.patch(`/api/tasks/${taskId}`, { agentRole }).catch(() => {/* non-fatal */})
       }
 
+      // ── #9 Last commit metadata for handoff context ───────────────────────
+      const lastCommit = getLastCommitMeta(repoRoot)
+
       return text({
         unparked: true,
-        task:     { key: task?.key, title: task?.title },
+        task:     { key: task?.key, title: task?.title, agentRole: agentRole || null },
         git:      gitResult || { switched: false, reason: 'No branch linked or repo not found' },
-        cursorRules: cursorRulesFile ? { restored: true, path: cursorRulesFile } : { restored: false },
+        autoStashed: autoStash ? 'Changes were auto-stashed before branch switch. Run: git stash list to see them.' : null,
+        lastCommit: lastCommit || null,
+        cursorRules: cursorRulesFile
+          ? { restored: true, path: cursorRulesFile, agentRole: agentRole || null }
+          : { restored: false },
         commentPosted:       true,
         previousDevNotified: true,
         parkNote: task?.parkNote || null,
         message: gitResult?.switched
-          ? `You are now on branch "${branch}". Cursor rules restored. Start coding from where ${task?.parkNote?.parkedBy ? 'the previous developer' : 'you'} left off.`
+          ? `You are now on branch "${branch}". Cursor rules restored${agentRole ? ` (role: ${agentRole})` : ''}. Start coding from where ${task?.parkNote?.parkedBy ? 'the previous developer' : 'you'} left off.`
           : `Branch switch failed — see git.manualSteps. Cursor rules restored.`,
+        nextStep: agentRole === 'builder'
+          ? `BUILDER role active. Call claim_files to lock your files before editing.`
+          : agentRole === 'scout'
+          ? `SCOUT role active. Read-only mode — map the codebase and save findings with update_task(scoutReport=...).`
+          : agentRole === 'coordinator'
+          ? `COORDINATOR role active. Call decompose_task to plan parallel workstreams.`
+          : agentRole === 'reviewer'
+          ? `REVIEWER role active. Call review_pr to start the review chain.`
+          : null,
+      })
+    }
+  )
+
+  // ── claim_files ──────────────────────────────────────────────────────────────
+  server.tool(
+    'claim_files',
+    `Claim exclusive ownership of files for this task session.
+
+Prevents merge conflicts by ensuring no two in-progress tasks edit the same file.
+Call this at the start of a builder session before editing any files.
+
+Returns a conflict list if any claimed files are already owned by another in-progress task.
+Ownership is automatically released when the task is parked.
+
+Roles: BUILDER agents MUST call this before editing. Coordinators call this as part of decompose_task.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+      files:  z.array(z.string()).min(1).describe('List of file paths this task will exclusively edit (e.g. ["server/routes/tasks.js", "client/src/App.jsx"])'),
+    },
+    async ({ taskId, files }) => {
+      const res = await api.post(`/api/tasks/${taskId}/files/claim`, { files })
+      if (!res?.success) {
+        if (res?.conflicts) {
+          return text({
+            blocked: true,
+            reason: 'File ownership conflict — these files are already claimed by another in-progress task.',
+            conflicts: res.conflicts,
+            message: 'Wait for the conflicting task to release the files, or coordinate with the other developer to resolve the overlap.',
+          })
+        }
+        return errorText(res?.message || 'Could not claim files')
+      }
+      return text({
+        claimed: true,
+        files,
+        taskId,
+        message: `${files.length} file(s) claimed. No other in-progress task in this project may edit these files until you release or park.`,
+        nextStep: 'You may now safely edit the claimed files. Files are auto-released when you call park_task.',
+      })
+    }
+  )
+
+  // ── release_files ─────────────────────────────────────────────────────────────
+  server.tool(
+    'release_files',
+    `Release all file ownership claims for a task.
+
+Call this when a builder subtask is complete and another task needs to edit the same files.
+Files are also released automatically when the task is parked.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+    },
+    async ({ taskId }) => {
+      const res = await api.post(`/api/tasks/${taskId}/files/release`, {})
+      if (!res?.success) return errorText(res?.message || 'Could not release files')
+      return text({
+        released: true,
+        taskId,
+        message: 'All file claims released. Other tasks may now claim these files.',
+      })
+    }
+  )
+
+  // ── decompose_task ────────────────────────────────────────────────────────────
+  server.tool(
+    'decompose_task',
+    `Coordinator tool: decompose an implementation plan into parallel subtasks with file ownership and role assignments.
+
+Use this when you are acting as a COORDINATOR agent and need to break a large task into
+parallel workstreams that multiple builder agents can execute without stepping on each other.
+
+What this does:
+1. Reads the task's implementation plan (README)
+2. Analyzes the plan to identify independent work units
+3. Returns a structured execution plan with:
+   - Parallel subtask groups (tasks that can run simultaneously)
+   - File ownership per subtask (no overlaps — each file appears in exactly one subtask)
+   - Role assignment per subtask (builder/scout/reviewer)
+   - Dependency order (which subtasks must complete before others start)
+4. Saves the decomposition plan to the task (decomposition field)
+5. Optionally creates the subtasks on the board
+
+REQUIRED BEFORE BUILDERS START:
+- A scout report should exist (call kickoff_task with agentRole=scout first)
+- The README must describe what needs to be built
+
+Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
+    {
+      taskId:        z.string().describe("Task's MongoDB ObjectId"),
+      subtaskPlan:   z.array(z.object({
+        title:       z.string().describe('Subtask title'),
+        role:        z.enum(['builder', 'scout', 'reviewer']).describe('Agent role for this subtask'),
+        files:       z.array(z.string()).describe('Files this subtask exclusively owns (no overlap with other subtasks)'),
+        description: z.string().describe('What this subtask implements'),
+        dependsOn:   z.array(z.string()).optional().describe('Titles of subtasks that must complete before this one starts'),
+        parallel:    z.boolean().optional().default(true).describe('Can this subtask run in parallel with others at the same level?'),
+      })).min(1).describe('Decomposed subtask execution plan. File ownership must not overlap between subtasks.'),
+      confirmed:     z.boolean().optional().default(false).describe('Set true to save the decomposition and create subtasks on the board'),
+    },
+    async ({ taskId, subtaskPlan, confirmed = false }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      // Validate: no file overlap between subtasks
+      const fileOwnershipMap = {}
+      const conflicts = []
+      for (const subtask of subtaskPlan) {
+        for (const file of (subtask.files || [])) {
+          if (fileOwnershipMap[file]) {
+            conflicts.push({ file, claimedBy: [fileOwnershipMap[file], subtask.title] })
+          } else {
+            fileOwnershipMap[file] = subtask.title
+          }
+        }
+      }
+
+      if (conflicts.length > 0) {
+        return text({
+          blocked: true,
+          reason:  'File ownership overlap detected — each file must appear in exactly one subtask.',
+          conflicts,
+          message: 'Fix the overlapping file assignments before confirming the decomposition.',
+        })
+      }
+
+      // Group subtasks by dependency level for parallel execution visualization
+      const parallelGroups = []
+      const placed = new Set()
+      let safetyLimit = subtaskPlan.length + 1
+      while (placed.size < subtaskPlan.length && safetyLimit-- > 0) {
+        const batch = subtaskPlan.filter(s =>
+          !placed.has(s.title) &&
+          (s.dependsOn || []).every(dep => placed.has(dep))
+        )
+        if (!batch.length) break
+        parallelGroups.push(batch.map(s => s.title))
+        batch.forEach(s => placed.add(s.title))
+      }
+
+      const executionPlan = {
+        taskKey:      task.key,
+        taskTitle:    task.title,
+        totalSubtasks: subtaskPlan.length,
+        subtasks:     subtaskPlan.map(s => ({
+          title:      s.title,
+          role:       s.role,
+          files:      s.files,
+          description: s.description,
+          dependsOn:  s.dependsOn || [],
+          parallel:   s.parallel !== false,
+        })),
+        executionOrder: parallelGroups,
+        fileOwnershipMap,
+        scoutReportPresent: !!(task.scoutReport?.trim()),
+        readmePresent:      !!(task.readmeMarkdown?.trim()),
+      }
+
+      if (!confirmed) {
+        return text({
+          decomposition: executionPlan,
+          warnings: [
+            !executionPlan.scoutReportPresent ? '⚠️  No scout report on this task. Consider running a scout agent first to map the codebase before builders start.' : null,
+            !executionPlan.readmePresent ? '⚠️  No implementation plan (README). Builders need a spec to work from.' : null,
+          ].filter(Boolean),
+          requiresConfirmation: true,
+          message: 'Review the decomposition above. Call decompose_task again with confirmed=true to save it and create the subtasks on the board.',
+        })
+      }
+
+      // Save decomposition to 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 */ }
+
+      return text({
+        decomposed: true,
+        taskKey:    task.key,
+        executionPlan,
+        subtasksCreated: subtaskPlan.length,
+        message: `Decomposition saved. ${subtaskPlan.length} subtask(s) added to the board.`,
+        nextStep: parallelGroups.length > 0
+          ? `Start with parallel group 1: ${parallelGroups[0].join(', ')}. Each builder agent should call kickoff_task with agentRole="builder" and claim_files before coding.`
+          : 'Start the subtasks in order. Each builder should call kickoff_task with agentRole="builder" and claim_files.',
+      })
+    }
+  )
+
+  // ── scout_task ────────────────────────────────────────────────────────────────
+  server.tool(
+    'scout_task',
+    `Scout agent entry point: analyze the codebase for a task and save a structured scout report.
+
+Call this BEFORE builders start when the Coordinator needs a codebase map.
+Use agentRole="scout" in kickoff_task first, then call scout_task to get your briefing.
+
+Two-phase flow:
+  Phase 1 — confirmed=false: get the briefing (what to analyze, report format)
+  Phase 2 — confirmed=true + report: save your findings to the task
+
+The scout report is consumed by:
+- decompose_task (warns if missing)
+- get_agent_context (included in builder context)
+- kickoff_task (surfaced as part of builder brief)
+
+Scouts MUST NOT modify any source code files or create branches.`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      confirmed: z.boolean().optional().default(false).describe('Set true to save the report. Set false (default) to get the briefing on what to analyze.'),
+      report:    z.string().optional().default('').describe('Your structured scout findings in markdown (required when confirmed=true)'),
+    },
+    async ({ taskId, confirmed = false, report = '' }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      if (!confirmed) {
+        return text({
+          brief: {
+            key:   task.key,
+            title: task.title,
+            implementationPlan: task.readmeMarkdown || '(no README — ask coordinator to write one first)',
+          },
+          currentScoutReport: task.scoutReport?.trim() || null,
+          scoutInstructions: {
+            objective: 'Map the codebase as it relates to this task. Identify every file that will need to change.',
+            analyzeThese: [
+              'Entry points — where does execution start for this feature area?',
+              'File dependency graph — which files import from which?',
+              'Existing patterns — what conventions does this codebase use (naming, folder structure, abstractions)?',
+              'Conflict risks — are any in-progress tasks touching the same files?',
+              'Complexity estimate — lines of code, number of files, coupling, test coverage',
+            ],
+            reportFormat: {
+              summary: 'One paragraph overview of what this task touches in the codebase',
+              entryPoints: ['file/path/entry.ts', '...'],
+              keyFiles: [{ path: 'file/path.ts', role: 'what it does for this task' }],
+              risks: ['Potential gotchas, breaking changes, or hidden complexity'],
+              suggestedFileOwnership: { 'Subtask Name': ['file1.ts', 'file2.ts'] },
+              complexityEstimate: 'low | medium | high',
+            },
+          },
+          requiresConfirmation: true,
+          message: `Analyze the codebase for ${task.key}, then call scout_task again with confirmed=true and your report string.`,
+        })
+      }
+
+      if (!report.trim()) return errorText('report is required when confirmed=true. Pass your scout findings as a markdown string.')
+
+      try {
+        await api.patch(`/api/tasks/${taskId}`, { scoutReport: report })
+      } catch (e) {
+        return errorText(`Failed to save scout report: ${e?.message || 'unknown error'}`)
+      }
+
+      return text({
+        saved:   true,
+        taskKey: task.key,
+        message: `Scout report saved for ${task.key}.`,
+        nextStep: 'The coordinator can now call decompose_task — the scout report will be included in builder context automatically via get_agent_context.',
+      })
+    }
+  )
+
+  // ── get_agent_context ─────────────────────────────────────────────────────────
+  server.tool(
+    'get_agent_context',
+    `Get a complete context package for starting work on a task as a specific agent role.
+
+Call this instead of get_task when starting a session — it returns everything composed and
+ready to use: systemPrompt, role behavioral constraints, implementation plan, cursor rules,
+scout report, decomposition plan, claimed files, and project-level custom guidance.
+
+Use this as the single entry point for any agent picking up a task. Replaces the need to
+call get_task + kickoff_task preview separately.
+
+Returns systemPrompt ready to use as a Claude system prompt.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+      role:   z.enum(['builder', 'reviewer', 'scout', 'coordinator']).optional()
+        .describe('Agent role for this session. Falls back to task.agentRole if omitted.'),
+    },
+    async ({ taskId, role }) => {
+      const qs = role ? `?role=${role}` : ''
+      const res = await apiWithRetry(() => api.get(`/api/tasks/${taskId}/agent-context${qs}`))
+      if (!res?.success) return errorText(res?.message || 'Failed to get agent context')
+      const ctx = res.data
+
+      const effectiveRole = ctx.role
+      const roleRules     = effectiveRole && ROLE_RULES[effectiveRole] ? ROLE_RULES[effectiveRole] : null
+
+      // Compose the full system prompt
+      const parts = []
+      if (effectiveRole) {
+        const roleLabel = ctx.customRoleLabel || effectiveRole.toUpperCase()
+        parts.push(`You are a ${roleLabel} agent working on task ${ctx.taskKey}: "${ctx.taskTitle}".`)
+      }
+      if (roleRules)                         parts.push(roleRules)
+      if (ctx.customPromptHint)              parts.push(`\n## Project-Specific Guidance\n\n${ctx.customPromptHint}`)
+      if (ctx.task?.cursorRules?.trim())     parts.push(`\n## Task-Specific Cursor Rules\n\n${ctx.task.cursorRules}`)
+      if (ctx.task?.readmeMarkdown?.trim())  parts.push(`\n## Implementation Plan\n\n${ctx.task.readmeMarkdown}`)
+      if (ctx.task?.scoutReport?.trim())     parts.push(`\n## Scout Report (Codebase Analysis)\n\n${ctx.task.scoutReport}`)
+      if (ctx.task?.decomposition?.trim()) {
+        try {
+          const dec = JSON.parse(ctx.task.decomposition)
+          parts.push(`\n## Execution Plan\n\nExecution order: ${JSON.stringify(dec.executionOrder)}\nFile ownership: ${JSON.stringify(dec.fileOwnershipMap, null, 2)}`)
+        } catch { /* non-fatal */ }
+      }
+
+      return text({
+        role:           effectiveRole,
+        taskKey:        ctx.taskKey,
+        taskTitle:      ctx.taskTitle,
+        systemPrompt:   parts.join('\n\n'),
+        allowedTools:   ctx.customAllowedTools || null,
+        claimedFiles:   ctx.task?.claimedFiles || [],
+        warnings:       ctx.warnings || [],
+        task:           ctx.task,
+        project:        ctx.project,
+        usage: 'Use systemPrompt as your Claude system prompt. If allowedTools is set, restrict your MCP tool calls to that list.',
+      })
+    }
+  )
+
+  // ── review_pr ────────────────────────────────────────────────────────────────
+  server.tool(
+    'review_pr',
+    `Fetch everything needed to do a thorough PR review: PR details, full code diff, CI status, and the task's implementation plan.
+
+Returns the diff file-by-file (filename, additions, deletions, patch hunks), the task's README spec, acceptance criteria, and CI check results so you can verify code against the plan.
+
+MANDATORY: After calling this tool, you MUST:
+1. Read every file in diff.files — check the patch hunk line by line
+2. Compare each change against spec.implementationPlan — does the code implement what was planned?
+3. Identify what is present, what is missing, what is wrong
+4. Build analysisPoints (min 2) referencing specific filenames and function names
+5. Only THEN call post_pr_review with your verdict and analysisPoints
+
+Do NOT call post_pr_review immediately after this without analyzing the diff first.
+Do NOT approve a PR without reading the patch hunks.
+
+Use this when the developer asks "review PR", "check the PR for TASK-X", or "is this PR ready to merge".`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId (used to find the project + PR number)"),
+    },
+    async ({ taskId }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const prNumber = task.github?.prNumber
+      if (!prNumber) return errorText('No PR linked to this task. The developer must raise_pr first.')
+
+      const projectId = task.project?._id || task.project
+      const res = await apiWithRetry(() => api.get(`/api/projects/${projectId}/github/pull-requests/${prNumber}`))
+      if (!res?.success) return errorText(res?.message || 'Could not fetch PR from GitHub')
+
+      const { pr, files, checks, task: linkedTask } = res.data
+
+      // Build a reviewer checklist from the implementation plan
+      const hasReadme = linkedTask?.readmeMarkdown?.trim()
+      const checklist = [
+        '[ ] Code matches the implementation plan (README)',
+        '[ ] All subtasks/acceptance criteria covered',
+        '[ ] No obvious bugs or edge cases missed',
+        '[ ] No hardcoded secrets or credentials',
+        '[ ] Error handling is in place where needed',
+        '[ ] No console.log / debug code left in',
+        checks?.anyFailed  ? '[ ] ⚠️  CI checks are failing — investigate before approving' : '[ ] CI checks passing ✅',
+        pr.changesRequested > 0 ? `[ ] ⚠️  ${pr.changesRequested} reviewer(s) already requested changes` : null,
+      ].filter(Boolean)
+
+      return text({
+        pr: {
+          number:         pr.number,
+          title:          pr.title,
+          author:         pr.author,
+          headBranch:     pr.headBranch,
+          baseBranch:     pr.baseBranch,
+          state:          pr.state,
+          approvals:      pr.approvals,
+          changesRequested: pr.changesRequested,
+          mergeable:      pr.mergeable,
+          mergeableState: pr.mergeableState,
+          url:            pr.htmlUrl,
+        },
+        ci: checks || { runs: [], allPassed: null, note: 'Could not fetch CI checks' },
+        diff: {
+          totalFiles:     files.length,
+          totalAdditions: files.reduce((s, f) => s + f.additions, 0),
+          totalDeletions: files.reduce((s, f) => s + f.deletions, 0),
+          files: files.map(f => ({
+            filename:  f.filename,
+            status:    f.status,
+            additions: f.additions,
+            deletions: f.deletions,
+            patch:     f.patch || '(binary or no diff)',
+          })),
+        },
+        spec: {
+          taskKey:            linkedTask?.key,
+          taskTitle:          linkedTask?.title,
+          implementationPlan: hasReadme ? linkedTask.readmeMarkdown : '⚠️  No implementation plan — review code against description only.',
+          description:        linkedTask?.description || null,
+        },
+        reviewChecklist: checklist,
+        nextStep: pr.approvals > 0 && !pr.changesRequested
+          ? `PR has ${pr.approvals} approval(s) and no changes requested. Call merge_pr with taskId="${taskId}" when ready.`
+          : `Review the diff above against the spec, then call post_pr_review with taskId="${taskId}" to post your verdict.`,
+      })
+    }
+  )
+
+  // ── post_pr_review ────────────────────────────────────────────────────────────
+  server.tool(
+    'post_pr_review',
+    `Post a GitHub PR review after analyzing the code diff from review_pr.
+
+Supports three actions:
+- APPROVE         — Approves the PR. Notifies the developer they can merge.
+- REQUEST_CHANGES — Blocks merge. Developer gets notified. Task board updated.
+- COMMENT         — Leaves a comment without approving or blocking.
+
+REQUIRED WORKFLOW — you MUST call review_pr first and read the diff before calling this.
+You MUST populate analysisPoints with specific findings from the diff — what you checked,
+what matched the spec, what is missing or broken. Generic analysis like "code looks good"
+will be rejected. Be file-specific: reference filenames, function names, line numbers.
+
+Human approval gate: confirmed=false shows preview, confirmed=true posts to GitHub.
+
+Returns reviewId — save it and pass it to merge_pr to prove semantic review happened.`,
+    {
+      taskId:         z.string().describe("Task's MongoDB ObjectId"),
+      event:          z.enum(['APPROVE', 'REQUEST_CHANGES', 'COMMENT']).describe('Review action'),
+      body:           z.string().describe('Review summary posted to GitHub — be specific about files, functions, issues'),
+      analysisPoints: z.array(z.string()).min(2).describe(
+        'Structured findings from your diff analysis. Each entry must reference a specific file, function, or line. ' +
+        'Examples: ["calculator.js: add/subtract/multiply all present and correct", ' +
+        '"divide() function missing — spec requires divide-by-zero handling", ' +
+        '"No input validation on any function — null/string inputs silently coerce"]. ' +
+        'Minimum 2 points required. Generic entries like "code looks fine" are rejected.'
+      ),
+      confirmed:      z.boolean().optional().default(false).describe('Set true after the human has read and approved the review text'),
+    },
+    async ({ taskId, event, body: reviewBody, analysisPoints, confirmed = false }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const prNumber  = task.github?.prNumber
+      const projectId = task.project?._id || task.project
+      if (!prNumber) return errorText('No PR linked to this task. Call raise_pr first.')
+
+      // Enforce that analysisPoints are specific — reject obviously generic ones
+      const genericPhrases = ['looks good', 'lgtm', 'code is fine', 'no issues', 'all good', 'seems correct']
+      const tooGeneric = analysisPoints.filter(p =>
+        p.trim().length < 20 || genericPhrases.some(g => p.toLowerCase().includes(g))
+      )
+      if (tooGeneric.length > 0) {
+        return text({
+          blocked: true,
+          reason: 'analysisPoints must be file-specific and reference actual diff content.',
+          rejected: tooGeneric,
+          instruction: 'Call review_pr first to get the diff, then re-examine each file and describe specific findings.',
+        })
+      }
+
+      // Preview — human must confirm
+      if (!confirmed) {
+        return text({
+          preview: {
+            action:         event,
+            prNumber,
+            taskKey:        task.key,
+            taskTitle:      task.title,
+            reviewBody,
+            analysisPoints,
+          },
+          warning: event === 'APPROVE'
+            ? '✅ This will APPROVE the PR on GitHub and notify the developer they can merge.'
+            : event === 'REQUEST_CHANGES'
+            ? '⚠️  This will REQUEST CHANGES — the developer will be blocked from merging until they fix the issues.'
+            : 'ℹ️  This will post a comment on the PR without approving or blocking.',
+          requiresConfirmation: true,
+          message: 'Show the review body and analysis points to the user and ask them to confirm. Then call post_pr_review again with confirmed=true.',
+        })
+      }
+
+      const res = await api.post(
+        `/api/projects/${projectId}/github/pull-requests/${prNumber}/reviews`,
+        { event, body: reviewBody }
+      )
+      if (!res?.success) return errorText(res?.message || 'Could not post review')
+
+      const reviewId = res.data?.reviewId
+
+      return text({
+        posted:         true,
+        event,
+        prNumber,
+        reviewId,
+        taskKey:        task.key,
+        analysisPoints,
+        message: event === 'APPROVE'
+          ? `✅ PR #${prNumber} approved. Developer has been notified and can now merge.`
+          : event === 'REQUEST_CHANGES'
+          ? `⚠️  Changes requested on PR #${prNumber}. Developer has been notified. Task board updated.`
+          : `💬 Comment posted on PR #${prNumber}.`,
+        nextStep: event === 'APPROVE'
+          ? `Call merge_pr with taskId="${taskId}" and reviewId="${reviewId}" to merge.`
+          : event === 'REQUEST_CHANGES'
+          ? `Wait for the developer to push fixes. They'll call fix_pr_feedback, then re-push. You'll be notified.`
+          : null,
+      })
+    }
+  )
+
+  // ── merge_pr ─────────────────────────────────────────────────────────────────
+  server.tool(
+    'merge_pr',
+    `Merge a pull request after semantic review and human approval.
+
+REQUIRED WORKFLOW:
+1. Call review_pr        — read the diff and spec
+2. Call post_pr_review   — post your verdict with specific analysisPoints, get back reviewId
+3. Call merge_pr         — pass reviewId to prove semantic review happened
+
+If the PR already has GitHub approvals from before this session, reviewId is not required.
+
+Safety checks (pre-merge):
+- Semantic review: reviewId required if PR has no existing GitHub approvals
+- PR must be open and not already merged
+- No pending change requests
+- CI checks must be passing (pass skipChecks=true to override)
+
+Human approval gate:
+- confirmed=false (default): shows all checks and asks for confirmation
+- confirmed=true:            executes the merge
+
+The task moves to Done automatically via the GitHub webhook.`,
+    {
+      taskId:      z.string().describe("Task's MongoDB ObjectId"),
+      confirmed:   z.boolean().optional().default(false).describe('Set true only after the human has reviewed the safety checks and approved the merge'),
+      mergeMethod: z.enum(['squash', 'merge', 'rebase']).optional().default('squash').describe('Merge strategy (default: squash)'),
+      commitTitle: z.string().optional().describe('Override the merge commit title. Defaults to PR title (#number).'),
+      skipChecks:  z.boolean().optional().default(false).describe('Skip CI check gate — use only when checks are informational or flaky'),
+      reviewId:    z.number().optional().describe('GitHub review ID returned by post_pr_review. Required when PR has no existing approvals — proves semantic review happened in this session.'),
+    },
+    async ({ taskId, confirmed = false, mergeMethod = 'squash', commitTitle, skipChecks = false, reviewId }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const prNumber  = task.github?.prNumber
+      const projectId = task.project?._id || task.project
+      if (!prNumber) return errorText(`No PR linked to task ${task.key}. The developer must raise_pr first.`)
+
+      // Fetch current PR state + checks for the preview
+      const prContextRes = await api.get(`/api/projects/${projectId}/github/pull-requests/${prNumber}`)
+      if (!prContextRes?.success) return errorText('Could not fetch PR details from GitHub')
+      const { pr, checks } = prContextRes.data
+
+      if (pr.merged) {
+        return text({ alreadyMerged: true, message: `PR #${prNumber} is already merged. Task should be in Done.` })
+      }
+      if (pr.state !== 'open') {
+        return text({ blocked: true, reason: `PR #${prNumber} is ${pr.state} — cannot merge a closed PR.` })
+      }
+
+      // ── Semantic review gate ──────────────────────────────────────────────────
+      // If the PR has no GitHub approvals from any session, a reviewId from
+      // post_pr_review in this session is mandatory. This ensures code was
+      // actually read and analyzed before merge, not just rubber-stamped.
+      const hasExistingApproval = pr.approvals > 0
+      const hasSessionReview    = !!reviewId
+      if (!hasExistingApproval && !hasSessionReview) {
+        return text({
+          blocked: true,
+          reason:  'No semantic review has been performed on this PR.',
+          required: [
+            `1. Call review_pr with taskId="${taskId}" to read the diff and spec`,
+            `2. Analyze the diff — check every file against the implementation plan`,
+            `3. Call post_pr_review with taskId="${taskId}", your verdict, and specific analysisPoints`,
+            `4. Pass the returned reviewId here to prove the review happened`,
+          ],
+          note: 'If this PR was already approved by a reviewer on GitHub, merge_pr will allow it through automatically.',
+        })
+      }
+
+      // Build safety check summary
+      const safetyChecks = [
+        { check: 'Semantic review performed', pass: hasExistingApproval || hasSessionReview,
+          note: hasSessionReview ? `reviewId ${reviewId} from this session` : hasExistingApproval ? `${pr.approvals} existing GitHub approval(s)` : 'Missing — call review_pr then post_pr_review' },
+        { check: 'PR is open',             pass: pr.state === 'open' },
+        { check: 'Not already merged',     pass: !pr.merged },
+        { check: 'No change requests',     pass: pr.changesRequested === 0,
+          note: pr.changesRequested > 0 ? `${pr.changesRequested} reviewer(s) requested changes` : null },
+        { check: `CI checks (${checks?.total ?? 0} runs)`,
+          pass: skipChecks ? null : (checks?.allPassed ?? null),
+          note: skipChecks ? 'Skipped by request' : checks?.anyFailed ? 'Some checks failed' : checks?.allPassed ? 'All passing' : 'No checks found' },
+        { check: 'Has at least one approval', pass: pr.approvals > 0,
+          note: pr.approvals === 0 ? 'No approvals yet — consider running post_pr_review first' : `${pr.approvals} approval(s)` },
+      ]
+
+      const hardBlocks = safetyChecks.filter(c => c.pass === false && c.check !== `CI checks (${checks?.total ?? 0} runs)`)
+      const ciBlocked  = !skipChecks && checks?.anyFailed
+
+      if (!confirmed) {
+        return text({
+          pr: {
+            number:      pr.number,
+            title:       pr.title,
+            author:      pr.author,
+            headBranch:  pr.headBranch,
+            approvals:   pr.approvals,
+            url:         pr.htmlUrl,
+          },
+          safetyChecks,
+          mergeStrategy: mergeMethod,
+          blocked: hardBlocks.length > 0 || ciBlocked,
+          blockers: [
+            ...hardBlocks.map(c => c.note || c.check),
+            ciBlocked ? 'CI checks are failing (pass skipChecks=true to override)' : null,
+          ].filter(Boolean),
+          requiresConfirmation: hardBlocks.length === 0 && !ciBlocked,
+          message: hardBlocks.length > 0 || ciBlocked
+            ? `⚠️  Merge blocked. Resolve the issues above before merging.`
+            : `Show the safety checks above to the user and ask them to confirm the merge. Then call merge_pr again with confirmed=true.`,
+        })
+      }
+
+      // Hard-block even on confirmed=true if there are unresolved change requests
+      if (pr.changesRequested > 0) {
+        return text({
+          blocked: true,
+          reason:  `Cannot merge: ${pr.changesRequested} reviewer(s) have requested changes. They must approve before merging.`,
+        })
+      }
+
+      // Execute merge
+      const mergeRes = await api.put(
+        `/api/projects/${projectId}/github/pull-requests/${prNumber}/merge`,
+        { mergeMethod, commitTitle: commitTitle || undefined, skipChecks }
+      )
+      if (!mergeRes?.success) return errorText(mergeRes?.message || 'Merge failed')
+
+      if (mergeRes.data?.alreadyMerged) {
+        return text({ merged: true, message: 'PR was already merged.' })
+      }
+
+      return text({
+        merged:      true,
+        sha:         mergeRes.data?.sha,
+        prNumber,
+        taskKey:     task.key,
+        mergeMethod,
+        message:     `✅ PR #${prNumber} merged via ${mergeMethod}. Task "${task.key}" will move to Done automatically.`,
+        nextStep:    `The GitHub webhook will update the board. If the task doesn't move to Done within a minute, call update_task with column="done" manually.`,
+      })
+    }
+  )
+
+  // ── resume_task ───────────────────────────────────────────────────────────────
+  server.tool(
+    'resume_task',
+    `One-click safe resume for a task you previously worked on.
+
+Combines: context fetch + dirty-tree check + optional auto-stash + checkout + pull + readiness summary.
+
+Use this when the developer says "resume task", "get back to task X", "continue my work on", or
+"switch back to TASK-KEY". Prefer this over manually running git commands.
+
+Flow:
+1. confirmed=false (default) → shows full context: park note, last commits, working-tree state, what will happen
+2. confirmed=true            → executes: stash (if needed + autoStash=true), checkout, pull, restore cursor rules, return readiness summary`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      confirmed: z.boolean().optional().default(false).describe('Set true after reviewing the context to execute the resume'),
+      repoPath:  z.string().optional().describe('Absolute path to the local git repo. Defaults to MCP process working directory.'),
+      autoStash: z.boolean().optional().default(false).describe('If working tree is dirty, auto-stash before switching. Labelled with task key.'),
+      agentRole: z.enum(['builder', 'reviewer', 'scout', 'coordinator']).optional()
+        .describe('Set the agent role for this resumed session. Role-specific constraints are injected into cursor rules.'),
+    },
+    async ({ taskId, confirmed = false, repoPath, autoStash = false, agentRole }) => {
+      // ── Fetch task ────────────────────────────────────────────────────────
+      let taskRes
+      try { taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`)) }
+      catch (e) { return errorText(`Could not fetch task: ${e.message}`) }
+      if (!taskRes?.success) return errorText(taskRes?.message || 'Task not found')
+      const task   = taskRes.data.task
+      const branch = task?.github?.headBranch || null
+
+      // ── Fetch recent comments ─────────────────────────────────────────────
+      let recentComments = []
+      try {
+        const commentsRes = await api.get(`/api/tasks/${taskId}/comments`)
+        recentComments = (commentsRes?.data?.comments || []).slice(-5).map(c => ({
+          author: c.author?.name || c.author?.email || 'unknown',
+          body:   c.body?.slice(0, 300),
+          at:     c.createdAt,
+        }))
+      } catch { /* non-fatal */ }
+
+      // ── Fetch recent commits on branch ────────────────────────────────────
+      let recentCommits = []
+      if (branch) {
+        try {
+          const commitsRes = await api.get(`/api/projects/${task.project}/github/commits?per_page=5&branch=${branch}`)
+          recentCommits = (commitsRes?.data?.commits || []).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 */ }
+      }
+
+      // ── Inspect local repo state ──────────────────────────────────────────
+      const repoRoot = findRepoRoot(repoPath || process.cwd())
+      let localState = 'clean'
+      let modified   = []
+      let currentBranch = null
+      let alreadyOnBranch = false
+
+      if (repoRoot) {
+        try {
+          const porcelain = runGit('status --porcelain=v1', repoRoot)
+          const parsed    = parseGitStatus(porcelain)
+          localState      = parsed.localState
+          modified        = parsed.modified
+          currentBranch   = runGit('branch --show-current', repoRoot).trim()
+          alreadyOnBranch = branch && currentBranch === branch
+        } catch { /* non-fatal */ }
+      }
+
+      // ── Preview ───────────────────────────────────────────────────────────
+      if (!confirmed) {
+        const willStash   = localState === 'modified' && !alreadyOnBranch
+        const stashBlocks = willStash && !autoStash
+
+        return text({
+          task: {
+            key:      task.key,
+            title:    task.title,
+            column:   task.column,
+            priority: task.priority,
+            branch:   branch || '(no branch)',
+          },
+          parkNote:      task.parkNote || null,
+          recentCommits: recentCommits.length ? recentCommits : ['No remote commits found'],
+          recentComments,
+          localRepo: repoRoot ? {
+            root:          repoRoot,
+            currentBranch,
+            alreadyOnBranch,
+            workingTree:   localState,
+            modifiedFiles: modified.length ? modified : null,
+          } : { found: false, note: 'No git repo found at ' + (repoPath || process.cwd()) },
+          willDo: branch && !alreadyOnBranch ? [
+            willStash && autoStash ? `git stash push -m "auto-stash(${task.key?.toLowerCase()}): changes on ${currentBranch} before resuming"` : null,
+            `git fetch origin`,
+            `git checkout ${branch}`,
+            `git pull origin ${branch}`,
+            task?.cursorRules?.trim() ? `Restore .cursor/rules/${task.key?.toLowerCase()}.mdc` : null,
+          ].filter(Boolean) : alreadyOnBranch ? [`git pull origin ${branch} (already on branch)`] : ['No branch to switch to'],
+          blocked: stashBlocks ? {
+            reason:  `Working tree is dirty (${modified.length} file(s) modified) and you are not on the task branch.`,
+            choices: {
+              autoStash: `Call resume_task again with autoStash=true — MCP stashes automatically`,
+              manual:    `git stash push -m "wip: before resuming ${task.key}"`,
+              cancel:    `Commit or discard your current changes first`,
+            },
+          } : null,
+          requiresConfirmation: !stashBlocks,
+          message: stashBlocks
+            ? `Working tree is dirty — resolve or pass autoStash=true, then call resume_task with confirmed=true.`
+            : `Review the context above, then call resume_task again with confirmed=true to switch branches and resume.`,
+        })
+      }
+
+      // ── Execute ───────────────────────────────────────────────────────────
+      if (!branch) {
+        return text({
+          resumed: false,
+          reason:  'No branch linked to this task yet.',
+          nextStep: `Call create_branch with taskId="${taskId}" to create one.`,
+        })
+      }
+
+      // Handle dirty tree
+      if (localState === 'modified' && !alreadyOnBranch) {
+        if (autoStash) {
+          try {
+            const stashLabel = `auto-stash(${task.key?.toLowerCase()}): changes on ${currentBranch} before resuming ${branch}`
+            runGit(`stash push -m "${stashLabel}"`, repoRoot)
+          } catch (e) {
+            return text({
+              resumed:  false,
+              reason:   `Auto-stash failed: ${e.message.split('\n')[0]}`,
+              nextStep: `Manually run: git stash push -m "wip" then retry.`,
+            })
+          }
+        } else {
+          return text({
+            blocked:  true,
+            reason:   `Working tree has ${modified.length} modified file(s). Cannot switch branches safely.`,
+            choices: {
+              autoStash: `Call resume_task again with confirmed=true and autoStash=true`,
+              manual:    `git stash push -m "wip: before resuming ${task.key}"`,
+              cancel:    `Commit or discard your changes first`,
+            },
+          })
+        }
+      }
+
+      // Switch branch + pull
+      let gitResult = null
+      if (repoRoot) {
+        if (alreadyOnBranch) {
+          try {
+            const pullOut = runGit(`pull origin ${branch}`, repoRoot)
+            gitResult = { switched: false, alreadyOnBranch: true, pulled: true, pullOutput: pullOut.slice(0, 200) }
+          } catch (e) {
+            gitResult = { switched: false, alreadyOnBranch: true, pulled: false, error: e.message.split('\n')[0] }
+          }
+        } else {
+          try {
+            runGit('fetch origin', repoRoot)
+            runGit(`checkout ${branch}`, repoRoot)
+            const pullOut = runGit(`pull origin ${branch}`, repoRoot)
+            gitResult = { switched: true, branch, pulled: true, pullOutput: pullOut.slice(0, 200) }
+          } catch (e) {
+            gitResult = {
+              switched: false,
+              error:    e.message.split('\n')[0],
+              manualSteps: [`git fetch origin`, `git checkout ${branch}`, `git pull origin ${branch}`],
+            }
+          }
+        }
+      }
+
+      // Restore cursor rules (with role injection if set)
+      let cursorRulesFile = null
+      const hasCursorRulesResume = task?.cursorRules?.trim()
+      if ((hasCursorRulesResume || agentRole) && repoRoot) {
+        cursorRulesFile = writeCursorRulesFile(
+          task.key,
+          hasCursorRulesResume || '(No task-specific rules — follow role constraints above.)',
+          repoPath,
+          agentRole || null
+        )
+      }
+
+      // Persist agentRole to server if set
+      if (agentRole) {
+        api.patch(`/api/tasks/${taskId}`, { agentRole }).catch(() => {/* non-fatal */})
+      }
+
+      // Last commit metadata
+      const lastCommit = getLastCommitMeta(repoRoot)
+
+      return text({
+        resumed:     true,
+        task:        { key: task.key, title: task.title, column: task.column, agentRole: agentRole || null },
+        git:         gitResult || { switched: false, reason: 'No repo found' },
+        autoStashed: autoStash && localState === 'modified' && !alreadyOnBranch
+          ? `Changes stashed before switch. Run: git stash list to see them.`
+          : null,
+        lastCommit:  lastCommit || null,
+        parkNote:    task.parkNote || null,
+        cursorRules: cursorRulesFile
+          ? { restored: true, path: cursorRulesFile, agentRole: agentRole || null }
+          : { restored: false },
+        message: gitResult?.switched || gitResult?.alreadyOnBranch
+          ? `You are on branch "${branch}". Ready to resume coding${agentRole ? ` as ${agentRole}` : ''}.`
+          : `Branch switch failed — see git.manualSteps.`,
+        nextStep: agentRole === 'builder'
+          ? `BUILDER role active. Call claim_files to lock your files before editing.`
+          : agentRole === 'scout'
+          ? `SCOUT role active. Read-only mode — map the codebase and save findings with update_task(scoutReport=...).`
+          : agentRole === 'coordinator'
+          ? `COORDINATOR role active. Call decompose_task to plan parallel workstreams.`
+          : agentRole === 'reviewer'
+          ? `REVIEWER role active. Call review_pr to start the review chain.`
+          : task.column === 'in_review'
+          ? `Task is in review. Check if PR feedback needs addressing — call fix_pr_feedback if needed.`
+          : task.parkNote?.remaining
+            ? `Remaining: ${task.parkNote.remaining}`
+            : `Continue coding on "${branch}".`,
       })
     }
   )
@@ -542,9 +1512,10 @@ function formatActivityLine(a) {
     case 'task.moved':      return `Moved from ${m.from} → ${m.to}`
     case 'task.branch_linked': return `Branch linked: ${m.headBranch}`
     case 'comment.created': return 'Comment posted'
-    case 'approval.submitted': return `Sent for approval → ${m.reviewerName || 'reviewer'}`
-    case 'approval.approved':  return `Plan approved${m.note ? ': ' + m.note : ''}`
-    case 'approval.rejected':  return `Plan rejected${m.note ? ': ' + m.note : ''}`
+    case 'approval.submitted':   return `Sent for approval → ${m.reviewerName || 'reviewer'}`
+    case 'approval.approved':    return `Plan approved${m.note ? ': ' + m.note : ''}`
+    case 'approval.rejected':    return `Plan rejected${m.note ? ': ' + m.note : ''}`
+    case 'approval.ai_reviewed': return `AI review submitted by ${m.agentName || 'AI'} — ${m.recommendation || 'needs_work'}`
     case 'task.merged_from_github':      return `PR #${m.prNumber} merged → done`
     case 'task.pr_opened_to_review':     return `PR #${m.prNumber} opened — moved to in_review`
     case 'task.pr_linked_in_review':     return `PR #${m.prNumber} linked (already in review)`
@@ -1023,8 +1994,10 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       taskId:    z.string().describe("Task's MongoDB ObjectId"),
       confirmed: z.boolean().optional().default(false).describe('Set true after reading the plan to move the task to in_progress'),
       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.'),
     },
-    async ({ taskId, confirmed = false, repoPath }) => {
+    async ({ taskId, confirmed = false, repoPath, agentRole }) => {
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
@@ -1053,8 +2026,9 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       const subtasksTotal = subtasks.length
 
       // ── Preview: show the full plan before touching anything ──
-      const approvalState = task.approval?.state || 'none'
-      const approvalBlocks = ['backlog', 'todo'].includes(task.column) && approvalState !== 'approved'
+      const pendingApv = (task.approvals || []).find(a => a.state === 'pending') || null
+      const hasApprovedApv = (task.approvals || []).some(a => a.state === 'approved')
+      const approvalBlocks = ['backlog', 'todo'].includes(task.column) && !hasApprovedApv
 
       // Build the next-step roadmap so developer knows exactly what comes after reading the plan
       let workflowRoadmap
@@ -1087,35 +2061,87 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       }
 
       // ── Simultaneous work lock ──────────────────────────────────────────────────
-      // If the task is already in_progress with a branch, warn before proceeding.
-      // This prevents two developers from unknowingly working on the same task.
       const alreadyActive = task.column === 'in_progress' && !!task.github?.headBranch
-      const activeAssignees = (task.assignees || []).map(a => a.name || a.email || a.toString())
 
       if (!confirmed && alreadyActive) {
+        // Determine the active owner precisely:
+        // currentOwner = whoever last unparked (actively working now)
+        // parkedBy     = whoever parked (task is idle, waiting for pickup)
+        // fallback     = assignees list
+        const currentOwner = task.parkNote?.currentOwner
+        const parkedBy     = task.parkNote?.parkedBy
+        const isParked     = !!task.parkNote?.parkedAt
+
+        const activeOwnerName = currentOwner
+          ? (currentOwner.name || currentOwner.email || currentOwner.toString())
+          : null
+        const parkedByName = parkedBy
+          ? (parkedBy.name || parkedBy.email || parkedBy.toString())
+          : null
+        const assigneeNames = (task.assignees || []).map(a => a.name || a.email || a.toString())
+
+        // Who is actively coding right now?
+        let activeWorker, situation, advice
+        if (isParked) {
+          activeWorker = null
+          situation = `Task is parked by ${parkedByName || 'a developer'} — no one is actively coding. Safe to pick up via unpark_task.`
+          advice = `Call unpark_task with taskId="${taskId}" to take ownership and continue from where ${parkedByName || 'they'} left off.`
+        } else if (activeOwnerName) {
+          activeWorker = activeOwnerName
+          situation = `${activeOwnerName} is actively working on this task right now.`
+          advice = `Contact ${activeOwnerName} directly before taking over. Do NOT push to branch "${task.github.headBranch}" — it will cause a conflict.`
+        } else if (assigneeNames.length) {
+          activeWorker = assigneeNames.join(', ')
+          situation = `${assigneeNames.join(' and ')} ${assigneeNames.length > 1 ? 'are' : 'is'} assigned to this task and it is in progress.`
+          advice = `Check with ${assigneeNames.join(', ')} before taking over.`
+        } else {
+          activeWorker = null
+          situation = `Task is in progress with no clear owner.`
+          advice = `Check the branch "${task.github.headBranch}" before starting fresh.`
+        }
+
+        // Notify all project members that someone attempted to take an active task
+        try {
+          const projectRes = await api.get(`/api/projects/${task.project}`)
+          const members = projectRes?.data?.project?.members || []
+          const meRes = await api.get('/api/auth/me')
+          const meName = meRes?.data?.user?.name || meRes?.data?.name || 'Someone'
+          const meId   = meRes?.data?.user?._id  || meRes?.data?._id  || ''
+          for (const memberId of members) {
+            const id = memberId._id || memberId.toString()
+            if (id !== meId) {
+              await api.post('/api/notifications/task-event', {
+                recipient: id,
+                type:      'task_assigned',
+                title:     `👀 ${meName} tried to start ${task.key}`,
+                body:      `${meName} attempted to kick off "${task.title}" which is already active${activeOwnerName ? ` (owned by ${activeOwnerName})` : ''}.`,
+                link:      `/projects/${task.project}/tasks/${taskId}`,
+                taskId,
+              }).catch(() => {/* non-fatal */})
+            }
+          }
+        } catch { /* non-fatal — don't block the warning */ }
+
         return text({
           warning: {
-            type:       'simultaneous_work_detected',
-            message:    `⚠️ This task is already in progress on branch "${task.github.headBranch}".`,
-            assignees:  activeAssignees.length ? activeAssignees : ['(unassigned)'],
-            branch:     task.github.headBranch,
-            parkNote:   task.parkNote || null,
-            advice:     activeAssignees.length
-              ? `Check with ${activeAssignees.join(', ')} before taking over. If they have parked this task their changes are pushed — checkout their branch instead of starting fresh.`
-              : `Someone may have been working on this. Check the branch before starting fresh.`,
+            type:        'simultaneous_work_detected',
+            situation,
+            activeWorker: activeWorker || '(unknown)',
+            isParked,
+            branch:      task.github.headBranch,
+            parkNote:    isParked ? task.parkNote : null,
+            advice,
             checkoutSteps: [
               'git fetch origin',
               `git checkout ${task.github.headBranch}`,
               `git pull origin ${task.github.headBranch}`,
             ],
           },
-          brief: {
-            key:         task.key,
-            title:       task.title,
-            priority:    task.priority,
-          },
+          brief: { key: task.key, title: task.title, priority: task.priority },
           requiresConfirmation: true,
-          message: `Task is already in progress. Read the warning above. If you still want to take over, call kickoff_task again with confirmed=true.`,
+          message: isParked
+            ? `Task is parked. Use unpark_task instead of kickoff_task to continue safely.`
+            : `⚠️ ${activeWorker || 'Someone'} is actively working on this. Do not take over without coordinating first. Call kickoff_task with confirmed=true only if you have confirmed with them.`,
         })
       }
 
@@ -1151,6 +2177,21 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
               ? `⏳ Plan is submitted and awaiting approval — you cannot create a branch until it is approved.`
               : `⚠️  Plan is not yet submitted for approval. Submit it first, then create the branch.`
             : null,
+          decompositionWarning: (() => {
+            if (!task.decomposition?.trim()) return null
+            try {
+              const dec = JSON.parse(task.decomposition)
+              if (!dec.scoutReportPresent && !task.scoutReport?.trim())
+                return `⚠️  This task has a decomposition plan but no scout report. Consider running scout_task before builders start.`
+              return `Decomposition exists: ${dec.totalSubtasks} subtask(s), ${dec.executionOrder?.length || 0} execution group(s).`
+            } catch { return null }
+          })(),
+          agentContext: {
+            hasScoutReport:   !!(task.scoutReport?.trim()),
+            hasDecomposition: !!(task.decomposition?.trim()),
+            claimedFiles:     task.claimedFiles || [],
+            agentRole:        task.agentRole || null,
+          },
           requiresConfirmation: true,
           message: approvalBlocks
             ? `Read the plan above, then follow workflowRoadmap — approval is required before you can branch and start coding.`
@@ -1158,6 +2199,32 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         })
       }
 
+      // ── #1 Preflight: check dirty tree before writing cursor rules / moving task ──
+      {
+        const pCwd  = repoPath || process.cwd()
+        const pRoot = findRepoRoot(pCwd)
+        if (pRoot) {
+          try {
+            const porcelain = runGit('status --porcelain=v1', pRoot)
+            const { localState, modified } = parseGitStatus(porcelain)
+            const currentBranchNow = runGit('branch --show-current', pRoot).trim()
+            if (localState === 'modified' && task.github?.headBranch && currentBranchNow !== task.github.headBranch) {
+              return text({
+                blocked:      true,
+                reason:       `You are on "${currentBranchNow}" with ${modified.length} modified file(s), but this task's branch is "${task.github.headBranch}".`,
+                modifiedFiles: modified,
+                choices: {
+                  stash:   `git stash push -m "wip: before kickoff ${task.key} on ${currentBranchNow}"`,
+                  autoSwitch: `Switch to ${task.github.headBranch}: git stash && git checkout ${task.github.headBranch} && git stash pop`,
+                  cancel:  'Review your changes first, then retry kickoff_task',
+                },
+                message: 'Resolve the working tree before kicking off this task to avoid cross-task pollution.',
+              })
+            }
+          } catch { /* non-fatal */ }
+        }
+      }
+
       // ── Confirmed: move to in_progress and fetch recent commits ──
       let recentCommits = []
       try {
@@ -1176,10 +2243,18 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         } catch { /* might already be in_progress */ }
       }
 
-      // Write cursor rules file to local repo immediately on kickoff
+      // Write cursor rules file to local repo immediately on kickoff (with role injection if set)
       let cursorRulesFile = null
       if (hasCursorRules) {
-        cursorRulesFile = writeCursorRulesFile(task.key, task.cursorRules, repoPath)
+        cursorRulesFile = writeCursorRulesFile(task.key, task.cursorRules, repoPath, agentRole || null)
+      } else if (agentRole) {
+        // Even if no task-specific cursor rules, write role rules alone
+        cursorRulesFile = writeCursorRulesFile(task.key, '(No task-specific rules — follow role constraints above.)', repoPath, agentRole)
+      }
+
+      // Persist agentRole to server so board shows the active role
+      if (agentRole) {
+        api.patch(`/api/tasks/${taskId}`, { agentRole }).catch(() => {/* non-fatal */})
       }
 
       return text({
@@ -1190,14 +2265,23 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
           column:   moved ? 'in_progress' : task.column,
           branch:   task.github?.headBranch || null,
           subtasks,
+          agentRole: agentRole || null,
         },
         implementationPlan: hasReadme ? task.readmeMarkdown : null,
-        cursorRules: hasCursorRules
-          ? { active: true, rules: task.cursorRules, instruction: '⚠️  CURSOR RULES ACTIVE — You MUST follow every rule in the "rules" field for the entire duration of this task.' }
+        cursorRules: hasCursorRules || agentRole
+          ? {
+              active: true,
+              agentRole: agentRole || null,
+              rules: task.cursorRules || null,
+              roleRules: agentRole ? ROLE_RULES[agentRole] : 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.',
+            }
           : { active: false },
         cursorRulesFile: cursorRulesFile
           ? { written: true, path: cursorRulesFile, note: 'Rules file written to your repo. Cursor enforces it automatically on every prompt.' }
-          : hasCursorRules ? { written: false, note: 'Could not write rules file — not inside a git repo.' } : null,
+          : (hasCursorRules || agentRole) ? { written: false, note: 'Could not write rules file — not inside a git repo.' } : null,
         recentCommits: recentCommits.slice(0, 5).map(c => ({
           sha:     c.sha?.slice(0, 7),
           message: c.commit?.message?.split('\n')[0],
@@ -1206,7 +2290,15 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         })),
         movedToInProgress: moved,
         suggestedBranch: alreadyHasBranch ? null : suggestedBranch,
-        nextStep: alreadyHasBranch
+        nextStep: agentRole === 'scout'
+          ? `You are in SCOUT mode. Read the codebase, then save your findings with update_task(scoutReport=...). Do NOT modify any files.`
+          : agentRole === 'coordinator'
+          ? `You are in COORDINATOR mode. Read the README, then call decompose_task to break the work into parallel subtasks with file ownership.`
+          : agentRole === 'builder'
+          ? `You are in BUILDER mode. Call claim_files first, then start coding on "${alreadyHasBranch ? task.github.headBranch : suggestedBranch}".`
+          : agentRole === 'reviewer'
+          ? `You are in REVIEWER mode. Call review_pr to get the diff, then post_pr_review with your analysis.`
+          : alreadyHasBranch
           ? `Branch "${task.github.headBranch}" already exists. Task is now In progress — start coding.`
           : `Call create_branch to create "${suggestedBranch}" — it will check your local git state and move the task to In progress automatically.`,
       })
@@ -1340,25 +2432,162 @@ function registerIssueTools(server) {
 function registerApprovalTools(server) {
   server.tool(
     'submit_task_for_approval',
-    'Submit a task implementation plan for review. README must be at least 80 characters.',
+    '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.',
     {
       taskId:     z.string().describe("Task's MongoDB ObjectId"),
+      title:      z.string().describe('Short title for this approval request, e.g. "Experiment: Add caching layer"'),
+      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, reviewerId }) =>
-      call(() => api.post(`/api/tasks/${taskId}/approval/submit`, { reviewerId }))
+    async ({ taskId, title, readme, reviewerId }) =>
+      call(() => api.post(`/api/tasks/${taskId}/approvals`, { title, readme, reviewerId }))
   )
 
   server.tool(
     'decide_task_approval',
-    'Approve or reject a task plan. Only the designated reviewer can call this.',
+    'Approve or reject a specific approval request by approvalId. Only the designated reviewer can call this.',
     {
-      taskId:   z.string().describe("Task's MongoDB ObjectId"),
-      decision: z.enum(['approve', 'reject']),
-      note:     z.string().optional().describe('Reason for the decision'),
+      taskId:     z.string().describe("Task's MongoDB ObjectId"),
+      approvalId: z.string().describe("Approval request's MongoDB ObjectId (from the task's approvals array)"),
+      decision:   z.enum(['approve', 'reject']),
+      note:       z.string().optional().describe('Reason for the decision'),
     },
-    async ({ taskId, decision, note }) =>
-      call(() => api.post(`/api/tasks/${taskId}/approval/decide`, { decision, note }))
+    async ({ taskId, approvalId, decision, note }) =>
+      call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/decide`, { decision, note }))
+  )
+}
+
+function registerAIReviewTools(server) {
+  server.tool(
+    'list_pending_reviews',
+    `List all tasks currently pending your review across all your projects.
+
+Returns task key, title, plan length, who submitted, how long it has been waiting, and whether a PR is linked.
+Call this when you want to know "what needs reviewing?" or to start a review session.`,
+    {},
+    async () => {
+      const projectsRes = await api.get('/api/projects')
+      const projects = projectsRes?.data?.projects || []
+
+      const boards = await Promise.all(
+        projects.map(async p => {
+          try {
+            const r = await api.get(`/api/projects/${p._id}`)
+            return { project: r?.data?.project, tasks: r?.data?.tasks || [] }
+          } catch { return null }
+        })
+      )
+
+      const meRes = await api.get('/api/auth/me')
+      const meId = meRes?.data?.user?._id || ''
+
+      const pending = []
+      const now = Date.now()
+      for (const board of boards.filter(Boolean)) {
+        for (const t of board.tasks) {
+          const pendingApv = (t.approvals || []).find(a => a.state === 'pending')
+          if (!pendingApv) continue
+          const reviewerId = pendingApv?.reviewer?._id || pendingApv?.reviewer
+          if (meId && reviewerId && String(reviewerId) !== String(meId)) continue
+          const waitingMs = pendingApv?.requestedAt ? now - new Date(pendingApv.requestedAt).getTime() : 0
+          const waitingHours = Math.round(waitingMs / (1000 * 60 * 60) * 10) / 10
+          pending.push({
+            taskId:         t._id,
+            approvalId:     pendingApv._id,
+            approvalTitle:  pendingApv.title || '',
+            key:            t.key,
+            title:          t.title,
+            project:        board.project?.name || '',
+            priority:       t.priority,
+            submittedBy:    pendingApv?.requestedBy?.name || pendingApv?.requestedBy?.email || 'unknown',
+            waitingHours,
+            planChars:      (pendingApv.readme || '').length,
+            hasPR:          !!(t.github?.prNumber),
+            prUrl:          t.github?.prUrl || null,
+            hasAIReview:    !!pendingApv?.aiReview,
+            aiRecommendation: pendingApv?.aiReview?.recommendation || null,
+          })
+        }
+      }
+
+      pending.sort((a, b) => b.waitingHours - a.waitingHours)
+
+      return text({
+        count: pending.length,
+        pendingReviews: pending,
+        message: pending.length === 0
+          ? 'No tasks pending your review.'
+          : `${pending.length} task(s) awaiting review. Call get_review_bundle with a taskId to start reviewing.`,
+      })
+    }
+  )
+
+  server.tool(
+    'get_review_bundle',
+    `Get everything needed to review a task as an AI code reviewer.
+
+Returns:
+- plan: full implementation README (what the developer planned to build)
+- prFiles: list of changed files in the PR with unified diffs (the actual code written)
+- recentCommits: last 20 commits on the task branch
+- comments: recent discussion on the task
+- openIssues: any open bugs logged on the task
+- approval: current approval state and any prior AI review
+
+After calling this, analyze the plan vs the code diff and call submit_ai_review with your findings.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+    },
+    async ({ taskId }) => call(() => api.get(`/api/tasks/${taskId}/review-bundle`))
+  )
+
+  server.tool(
+    'submit_ai_review',
+    `Submit a structured AI code review opinion on a specific approval request pending review.
+
+This does NOT override the human reviewer's decision — it attaches your analysis so the
+human reviewer can approve/reject faster with full AI context.
+
+Your review should cover:
+1. Does the experiment plan make sense and is it safe to implement?
+2. Are there security concerns, performance issues, or bugs in linked PR code?
+3. Is the plan clear and actionable?
+4. Are edge cases covered?
+
+Workflow:
+1. Call list_pending_reviews to find tasks awaiting review (returns taskId + approvalId)
+2. Call get_review_bundle to get the full context (plan + PR diff + commits)
+3. Analyze everything thoroughly
+4. Call submit_ai_review with your structured findings`,
+    {
+      taskId:     z.string().describe("Task's MongoDB ObjectId"),
+      approvalId: z.string().describe("Approval request's MongoDB ObjectId (from list_pending_reviews)"),
+      agentName:  z.string().optional().default('Claude Code').describe('Name of the AI agent doing the review'),
+      summary:    z.string().describe(
+        'Overall review narrative (2-5 paragraphs). Cover: plan quality, code quality, security, correctness.'
+      ),
+      recommendation: z.enum(['approve', 'reject', 'needs_work']).describe(
+        '"approve" = plan is solid; "needs_work" = minor issues; "reject" = significant problems'
+      ),
+      confidence: z.number().min(0).max(100).describe(
+        'How confident are you in this recommendation? 0 = very uncertain, 100 = very certain'
+      ),
+      checklist: z.array(z.object({
+        item:   z.string().describe('What was checked (e.g. "Error handling in API calls")'),
+        passed: z.boolean().describe('Did it pass?'),
+        note:   z.string().optional().describe('Brief explanation'),
+      })).describe('Structured checklist of what was reviewed'),
+      issues: z.array(z.object({
+        severity:    z.enum(['low', 'medium', 'high', 'critical']),
+        description: z.string().describe('What the issue is'),
+        suggestion:  z.string().optional().describe('How to fix it'),
+      })).optional().describe('Specific issues found in the code'),
+    },
+    async ({ taskId, approvalId, agentName, summary, recommendation, confidence, checklist, issues }) =>
+      call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/ai-review`, {
+        agentName, summary, recommendation, confidence, checklist,
+        issues: issues || [],
+      }))
   )
 }
 
@@ -1476,15 +2705,118 @@ function findRepoRoot(startPath) {
   return null
 }
 
-/** Write task-specific cursor rules to .cursor/rules/<taskKey>.mdc in the local repo root. */
-function writeCursorRulesFile(taskKey, rulesMarkdown, startPath) {
+// ── Agent role behavioral rule templates ─────────────────────────────────────
+// 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
+
+You are a BUILDER agent. Your behavioral constraints for this session:
+
+**ALLOWED:**
+- Write, modify, and delete code files within the task scope
+- Create new files required by the implementation plan
+- 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)
+- 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
+- Follow the spec precisely — don't add unrequested features
+- Commit atomically with conventional commit format (feat/fix/refactor)`,
+
+  scout: `## Agent Role: SCOUT
+
+You are a SCOUT agent. Your behavioral constraints for this session:
+
+**ALLOWED:**
+- Read and analyze any file in the codebase
+- Search for patterns, dependencies, and potential conflicts
+- Write a structured scout report (update_task with scoutReport field)
+- Identify which files the implementation will need to touch
+- Surface risks, gotchas, and architectural considerations
+
+**NOT ALLOWED:**
+- Modify any source code files
+- Create branches or commits
+- Move tasks or create PRs
+- Make changes that would require a PR
+
+**WORK STYLE:**
+- Your output is a scout report for the builder agents
+- Map file dependencies before builders start
+- Identify conflict risks with other in-progress tasks
+- Estimate complexity and flag potential blockers
+- Save your report with update_task(scoutReport=...)`,
+
+  reviewer: `## Agent Role: REVIEWER
+
+You are a REVIEWER agent. Your behavioral constraints for this session:
+
+**ALLOWED:**
+- Read all code changes and diffs (use review_pr)
+- Post structured reviews with specific analysis points (use post_pr_review)
+- Request changes or approve the PR
+- Reference specific files, functions, and line numbers in your review
+
+**NOT ALLOWED:**
+- Approve a PR without reading every file in the diff
+- Write "looks good" or generic analysis — be specific and file-based
+- Merge the PR without completing the review chain (review_pr → post_pr_review → merge_pr)
+- Modify source code directly
+
+**WORK STYLE:**
+- Always call review_pr first to get the full diff and spec
+- Check each file against the implementation plan
+- Build analysisPoints with file-specific findings (minimum 2)
+- Reference function names and line numbers
+- Only call merge_pr after post_pr_review returns a reviewId`,
+
+  coordinator: `## Agent Role: COORDINATOR
+
+You are a COORDINATOR agent. Your behavioral constraints for this session:
+
+**ALLOWED:**
+- Read the task implementation plan and codebase structure
+- Decompose the plan into parallel subtasks (use decompose_task)
+- Assign file ownership to each subtask with no overlaps
+- Assign roles to each subtask (builder, scout, reviewer)
+- Create subtasks on the board (use update_task with subtasks)
+- Monitor progress and resolve file conflicts
+
+**NOT ALLOWED:**
+- Write implementation code directly
+- Claim file ownership for yourself
+- Bypass the decomposition step — always decompose before builders start
+- Start coding without a scout report when the codebase is unfamiliar
+
+**WORK STYLE:**
+- Start with decompose_task to get the structured execution plan
+- Ensure no two builder subtasks claim the same file
+- Scout report must exist before builders begin
+- Each builder subtask must have explicit file ownership and a clear scope`,
+}
+
+/** 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) {
   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 content = `---\ndescription: Task-specific rules for ${taskKey} — auto-generated by InternalTool MCP. Do not edit manually.\nalwaysApply: true\n---\n\n${rulesMarkdown}\n`
+    const roleSection = role && ROLE_RULES[role]
+      ? `${ROLE_RULES[role]}\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')
     return filePath
   } catch {
@@ -1508,6 +2840,49 @@ function deleteCursorRulesFile(taskKey, startPath) {
   }
 }
 
+// ── #3 Better failure recovery: API call with auto-retry + structured cause ───
+async function apiWithRetry(fn, maxRetries = 2, initialDelay = 500) {
+  let lastErr
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (e) {
+      lastErr = e
+      const msg = (e.message || '').toLowerCase()
+      // Never retry auth / client errors
+      if (msg.includes('401') || msg.includes('403') || msg.includes('unauthorized') || msg.includes('forbidden')) {
+        throw Object.assign(e, { _cause: 'auth' })
+      }
+      if (msg.includes('404') || msg.includes('400') || msg.includes('422') || msg.includes('409')) {
+        throw Object.assign(e, { _cause: 'client' })
+      }
+      if (attempt < maxRetries) {
+        await new Promise(r => setTimeout(r, initialDelay * (attempt + 1)))
+      }
+    }
+  }
+  const msg = (lastErr?.message || '').toLowerCase()
+  const cause = (msg.includes('econnref') || msg.includes('network') || msg.includes('fetch failed') || msg.includes('enotfound'))
+    ? 'network'
+    : msg.includes('timeout') ? 'timeout' : 'server'
+  lastErr._cause = cause
+  throw lastErr
+}
+
+function wrapApiError(e) {
+  return { error: true, cause: e._cause || 'unknown', message: e.message?.split('\n')[0] }
+}
+
+// ── #9 Get last git commit metadata ──────────────────────────────────────────
+function getLastCommitMeta(repoRoot) {
+  if (!repoRoot) return null
+  try {
+    const raw = runGit('log -1 --format=%H%x09%s%x09%an%x09%ae%x09%ad --date=short', repoRoot)
+    const [sha, subject, authorName, authorEmail, date] = raw.split('\t')
+    return { sha: sha?.slice(0, 7), subject: subject?.trim(), author: authorName || authorEmail, date }
+  } catch { return null }
+}
+
 function parseGitStatus(porcelain) {
   const lines = porcelain.split('\n').filter(Boolean)
   const staged     = lines.filter(l => !' ?!'.includes(l[0])).map(l => ({ xy: l.slice(0, 2), file: l.slice(3) }))
@@ -1623,18 +2998,24 @@ The developer does not need to run any commands manually — this tool reads loc
   server.tool(
     'list_my_tasks',
     `List your assigned tasks sorted by priority (critical → high → medium → low).
-Each task includes a suggested next git action so Claude can guide you step by step.
+Each task includes a suggested next git action, ownership status (who currently owns / parked it),
+and branch consistency warnings so Claude can guide you step by step.
 Use this at the start of a session or when switching tasks.`,
     {
       includeColumns: z.array(
         z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done'])
       ).optional().default(['todo', 'in_progress', 'in_review'])
        .describe('Which columns to include. Default excludes backlog and done.'),
+      repoPath: z.string().optional().describe('Absolute path to local repo — used for branch consistency checks'),
     },
-    async ({ includeColumns = ['todo', 'in_progress', 'in_review'] } = {}) => {
+    async ({ includeColumns = ['todo', 'in_progress', 'in_review'], repoPath } = {}) => {
       const res = await api.get('/api/users/me/tasks')
       if (!res?.success) return errorText('Could not fetch tasks')
 
+      // #4 Local repo for branch consistency checks
+      const cwd      = repoPath || process.cwd()
+      const repoRoot = findRepoRoot(cwd)
+
       // Server already sorts by priority (critical → low) then updatedAt — just filter and annotate
       const tasks = (res.data.tasks || [])
         .filter(t => includeColumns.includes(t.column))
@@ -1649,6 +3030,44 @@ Use this at the start of a session or when switching tasks.`,
           } else if (t.column === 'in_review') {
             suggestedAction = `PR #${t.github?.prNumber || '?'} is open — waiting for reviewer feedback`
           }
+
+          // ── #6 Ownership visibility ───────────────────────────────────────
+          const currentOwner = t.parkNote?.currentOwner
+          const parkedBy     = t.parkNote?.parkedBy
+          const ownership = {
+            currentOwner: currentOwner
+              ? (currentOwner.name || currentOwner.email || String(currentOwner))
+              : null,
+            parkedBy: parkedBy
+              ? (parkedBy.name || parkedBy.email || String(parkedBy))
+              : null,
+            parkedAt:      t.parkNote?.parkedAt || null,
+            parkedSummary: t.parkNote?.summary  || null,
+          }
+
+          // ── #4 Branch consistency check ───────────────────────────────────
+          let branchConsistency = null
+          if (t.column === 'in_progress' && t.github?.headBranch && repoRoot) {
+            try {
+              let localExists = false, remoteExists = false
+              try { runGit(`rev-parse --verify ${t.github.headBranch}`, repoRoot); localExists = true } catch { /* not local */ }
+              try { runGit(`rev-parse --verify origin/${t.github.headBranch}`, repoRoot); remoteExists = true } catch { /* not remote */ }
+              if (!localExists && !remoteExists) {
+                branchConsistency = {
+                  warning: 'branch_not_found',
+                  message: `Branch "${t.github.headBranch}" does not exist locally or remotely.`,
+                  fixAction: `git fetch origin && git checkout ${t.github.headBranch}  — or use create_branch if it was never pushed`,
+                }
+              } else if (!localExists && remoteExists) {
+                branchConsistency = {
+                  warning: 'branch_remote_only',
+                  message: `Branch "${t.github.headBranch}" exists on remote but not locally.`,
+                  fixAction: `git fetch origin && git checkout ${t.github.headBranch}`,
+                }
+              }
+            } catch { /* non-fatal */ }
+          }
+
           return {
             id:             t._id,
             key:            t.key,
@@ -1658,11 +3077,193 @@ Use this at the start of a session or when switching tasks.`,
             project:        t.project?.name || t.project,
             github:         t.github ? { headBranch: t.github.headBranch, prNumber: t.github.prNumber, mergedAt: t.github.mergedAt } : null,
             parked:         !!t.parkNote?.parkedAt,
+            ownership,
+            branchConsistency,
             suggestedAction,
           }
         })
 
-      return text({ tasks, count: tasks.length })
+      const consistencyIssues = tasks.filter(t => t.branchConsistency).map(t => ({ key: t.key, ...t.branchConsistency }))
+
+      return text({
+        tasks,
+        count: tasks.length,
+        consistencyIssues: consistencyIssues.length ? consistencyIssues : null,
+      })
+    }
+  )
+
+  // ── #7 find_repo ─────────────────────────────────────────────────────────────
+  server.tool(
+    'find_repo',
+    `Scan the file system to find git repositories near a given path.
+
+Use this when the user says "I can't find my repo", points to a parent folder,
+or when create_branch / unpark_task fail because repoPath is wrong.
+
+Returns all git repos found within 2 directory levels, along with their current branch
+and whether they contain a .cursor/mcp.json (indicating InternalTool is configured there).`,
+    {
+      searchPath: z.string().optional().describe('Directory to scan from. Defaults to the MCP process working directory.'),
+    },
+    async ({ searchPath } = {}) => {
+      const base = searchPath || process.cwd()
+      const candidates = []
+
+      function tryRepo(dir) {
+        try {
+          const root = runGit('rev-parse --show-toplevel', dir)
+          if (candidates.some(c => c.repoRoot === root)) return  // already found
+          let currentBranch = null, hasMcpConfig = false
+          try { currentBranch = runGit('branch --show-current', root).trim() } catch { /* ok */ }
+          try { hasMcpConfig = existsSync(join(root, '.cursor', 'mcp.json')) } catch { /* ok */ }
+          candidates.push({ repoRoot: root, currentBranch, hasMcpConfig })
+        } catch { /* not a git repo */ }
+      }
+
+      // Level 0: the path itself
+      tryRepo(base)
+
+      // Level 1: immediate subdirectories
+      try {
+        const entries = readdirSync(base, { withFileTypes: true })
+        for (const e of entries) {
+          if (!e.isDirectory() || e.name.startsWith('.')) continue
+          const sub = join(base, e.name)
+          tryRepo(sub)
+          // Level 2: one more level deep
+          try {
+            const sub2Entries = readdirSync(sub, { withFileTypes: true })
+            for (const e2 of sub2Entries) {
+              if (!e2.isDirectory() || e2.name.startsWith('.')) continue
+              tryRepo(join(sub, e2.name))
+            }
+          } catch { /* ok */ }
+        }
+      } catch { /* ok */ }
+
+      if (!candidates.length) {
+        return text({
+          found: false,
+          searchedFrom: base,
+          message: `No git repositories found within 2 levels of "${base}". Try passing a searchPath closer to your project.`,
+        })
+      }
+
+      return text({
+        found:        true,
+        searchedFrom: base,
+        repos:        candidates,
+        count:        candidates.length,
+        tip: candidates.length === 1
+          ? `Use repoPath="${candidates[0].repoRoot}" in create_branch / unpark_task / park_task.`
+          : `Multiple repos found. Pass the correct one as repoPath to git workflow tools.`,
+      })
+    }
+  )
+
+  // ── #8 validate_mcp_config ───────────────────────────────────────────────────
+  server.tool(
+    'validate_mcp_config',
+    `Validate the .cursor/mcp.json configuration for InternalTool.
+
+Checks for common issues:
+- File not found or not valid JSON
+- Missing required fields (command, args, env.INTERNALTOOL_TOKEN)
+- Trailing spaces or wrong separators in the --url value
+- Token not starting with "ilt_"
+- Mismatched project URL vs server URL
+
+Use this when the MCP connection seems wrong or tools return unexpected auth errors.`,
+    {
+      repoPath: z.string().optional().describe('Path to search for .cursor/mcp.json (defaults to MCP working directory)'),
+    },
+    async ({ repoPath } = {}) => {
+      const cwd  = repoPath || process.cwd()
+      const root = findRepoRoot(cwd) || cwd
+
+      const configPath = join(root, '.cursor', 'mcp.json')
+      const issues = []
+      const fixes  = []
+
+      if (!existsSync(configPath)) {
+        return text({
+          valid: false,
+          configPath,
+          issues: ['File not found: .cursor/mcp.json does not exist in this repo'],
+          fixes: [
+            `Create it at: ${configPath}`,
+            `Minimal content:\n{\n  "mcpServers": {\n    "internaltool": {\n      "command": "npx",\n      "args": ["-y", "internaltool-mcp", "--url", "http://localhost:5001"],\n      "env": { "INTERNALTOOL_TOKEN": "ilt_your_token_here" }\n    }\n  }\n}`,
+          ],
+        })
+      }
+
+      let parsed = null
+      try {
+        const { readFileSync: rfs } = await import('fs')
+        const raw = rfs(configPath, 'utf8')
+        // Check for trailing space in path (a common copy-paste mistake on macOS)
+        if (configPath.includes(' ')) {
+          issues.push(`Path contains a space: "${configPath}" — rename the folder to remove it`)
+          fixes.push(`mv "${root}" "${root.replace(/ /g, '_')}"`)
+        }
+        parsed = JSON.parse(raw)
+      } catch (e) {
+        return text({
+          valid: false,
+          configPath,
+          issues: [`Invalid JSON: ${e.message}`],
+          fixes:  ['Open .cursor/mcp.json and fix the JSON syntax. Use jsonlint.com to validate.'],
+        })
+      }
+
+      const servers = parsed?.mcpServers || {}
+      const serverNames = Object.keys(servers)
+      if (!serverNames.length) {
+        issues.push('mcpServers object is empty — no server configured')
+        fixes.push('Add an "internaltool" entry under mcpServers')
+      }
+
+      for (const name of serverNames) {
+        const cfg = servers[name]
+        if (!cfg.command) { issues.push(`"${name}": missing "command" field`); fixes.push(`Set "command": "npx"`) }
+        const args = cfg.args || []
+        if (!args.includes('internaltool-mcp') && !args.some(a => a.includes('internaltool-mcp'))) {
+          issues.push(`"${name}": args do not include "internaltool-mcp"`)
+          fixes.push(`args should be: ["-y", "internaltool-mcp", "--url", "<your-server-url>"]`)
+        }
+        const urlIdx = args.indexOf('--url')
+        if (urlIdx === -1) {
+          issues.push(`"${name}": --url flag missing from args`)
+          fixes.push(`Add "--url", "http://localhost:5001" to args`)
+        } else {
+          const urlVal = args[urlIdx + 1] || ''
+          if (urlVal.endsWith(' ') || urlVal.startsWith(' ')) {
+            issues.push(`"${name}": --url value has leading/trailing space: "${urlVal}"`)
+            fixes.push(`Remove spaces: "${urlVal.trim()}"`)
+          }
+          if (!urlVal.startsWith('http://') && !urlVal.startsWith('https://')) {
+            issues.push(`"${name}": --url value looks invalid: "${urlVal}"`)
+            fixes.push(`Should start with http:// or https://`)
+          }
+        }
+        const token = cfg.env?.INTERNALTOOL_TOKEN
+        if (!token) {
+          issues.push(`"${name}": INTERNALTOOL_TOKEN not set in env`)
+          fixes.push(`Add: "env": { "INTERNALTOOL_TOKEN": "ilt_your_token" }`)
+        } else if (!token.startsWith('ilt_')) {
+          issues.push(`"${name}": INTERNALTOOL_TOKEN does not start with "ilt_" — may be wrong`)
+          fixes.push(`Regenerate your token in InternalTool → Settings → API Keys`)
+        }
+      }
+
+      return text({
+        valid:      issues.length === 0,
+        configPath,
+        serverNames,
+        issues:     issues.length ? issues : ['None — config looks correct'],
+        fixes:      fixes.length  ? fixes  : ['No fixes needed'],
+      })
     }
   )
 
@@ -1677,10 +3278,15 @@ Use this when returning to a task after a break, or when Claude needs the full p
       repoPath: z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory)'),
     },
     async ({ taskId, repoPath }) => {
-      const [taskRes, activityRes] = await Promise.all([
-        api.get(`/api/tasks/${taskId}`),
-        api.get(`/api/tasks/${taskId}/activity`).catch(() => null),
-      ])
+      let taskRes, activityRes
+      try {
+        [taskRes, activityRes] = await Promise.all([
+          apiWithRetry(() => api.get(`/api/tasks/${taskId}`)),
+          apiWithRetry(() => api.get(`/api/tasks/${taskId}/activity`)).catch(() => null),
+        ])
+      } catch (e) {
+        return text({ error: true, ...wrapApiError(e), message: `Could not fetch task context — ${wrapApiError(e).cause} error. Retry in a moment.` })
+      }
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
       const recentActivity = (activityRes?.data?.activity || []).slice(-10)
@@ -1794,8 +3400,9 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       fromRef:   z.string().optional().describe("Base ref to branch from (default: project's default branch)"),
       confirmed: z.boolean().optional().default(false).describe('Set true after reviewing the preview to create the branch'),
       repoPath:  z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory)'),
+      autoStash: z.boolean().optional().default(false).describe('Auto-stash modified files before creating the branch instead of blocking. Stash is labelled for easy recovery.'),
     },
-    async ({ taskId, projectId, fromRef, confirmed = false, repoPath }) => {
+    async ({ taskId, projectId, fromRef, confirmed = false, repoPath, autoStash = false }) => {
       if (scopedProjectId && projectId !== scopedProjectId) {
         return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
       }
@@ -1807,9 +3414,9 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       // ── Approval gate check ───────────────────────────────────────────────────
       // The server blocks non-admins from moving todo → in_progress without approval.
       // Detect this early and guide the developer instead of failing silently after branch creation.
-      const approvalState = task.approval?.state || 'none'
+      const hasApprovedApv2 = (task.approvals || []).some(a => a.state === 'approved')
       const PLANNING_COLS = ['backlog', 'todo']
-      const needsApproval = PLANNING_COLS.includes(task.column) && approvalState !== 'approved'
+      const needsApproval = PLANNING_COLS.includes(task.column) && !hasApprovedApv2
       if (needsApproval && !confirmed) {
         const isFix2 = /\b(fix|bug|hotfix|patch)\b/i.test(task.title + ' ' + (task.description || ''))
         const slug2 = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 35)
@@ -1913,18 +3520,32 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
         })
       }
 
-      // Step 2 — block automatically if there are tracked changes
+      // Step 2 — block or auto-stash if there are tracked changes
       if (gitState?.localState === 'modified') {
-        return text({
-          blocked: true,
-          reason: `You have ${gitState.modified.length} modified tracked file(s). Creating a branch while tracked changes are present can carry them onto the new branch.`,
-          modifiedFiles: gitState.modified,
-          fixOptions: {
-            stash:  `git stash push -m "wip: switching to ${branchName}"`,
-            commit: 'git add . && git commit -m "chore: wip"',
-          },
-          message: 'Stash or commit your changes, then call create_branch again with confirmed=true.',
-        })
+        if (autoStash) {
+          try {
+            const stashLabel = `auto-stash(${task.key?.toLowerCase()}): before create_branch ${branchName}`
+            runGit(`stash push -m "${stashLabel}"`, cwd)
+          } catch (stashErr) {
+            return text({
+              blocked: true,
+              reason: `autoStash failed: ${stashErr.message.split('\n')[0]}`,
+              message: 'Stash your changes manually and retry.',
+            })
+          }
+        } else {
+          return text({
+            blocked: true,
+            reason: `You have ${gitState.modified.length} modified tracked file(s). Creating a branch while tracked changes are present can carry them onto the new branch.`,
+            modifiedFiles: gitState.modified,
+            fixOptions: {
+              stash:     `git stash push -m "wip: switching to ${branchName}"`,
+              commit:    'git add . && git commit -m "chore: wip"',
+              autoStash: `Call create_branch again with autoStash=true — MCP will stash automatically`,
+            },
+            message: 'Stash or commit your changes, then call create_branch again with confirmed=true.',
+          })
+        }
       }
 
       // Step 3 — create branch on GitHub (or confirm it already exists), then link + move
@@ -2261,10 +3882,27 @@ Set confirmed=false first to preview the full PR content, then confirmed=true to
         return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
       }
 
-      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      let taskRes
+      try { taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`)) }
+      catch (e) { return text({ error: true, ...wrapApiError(e), message: `Could not fetch task — ${wrapApiError(e).cause} error. Retry raise_pr in a moment.` }) }
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
 
+      // ── #5 Idempotent: return existing PR instead of trying to recreate ─────
+      if (task.github?.prUrl && task.github?.prNumber) {
+        const msg = confirmed
+          ? `PR #${task.github.prNumber} already exists for ${task.key} — no duplicate created.`
+          : `PR #${task.github.prNumber} already exists for this branch. No action needed.`
+        return text({
+          prAlreadyExists: true,
+          prNumber:  task.github.prNumber,
+          prUrl:     task.github.prUrl,
+          headBranch: task.github.headBranch || headBranch,
+          message: msg,
+          nextStep: `PR is live at ${task.github.prUrl}. The GitHub webhook tracks review status automatically.`,
+        })
+      }
+
       const prTitle = `[${task.key}] ${task.title}`
       const bodyParts = [
         `## ${task.key}: ${task.title}`,
@@ -2799,6 +4437,7 @@ async function main() {
   registerProductivityTools(server)
   registerIssueTools(server)
   registerApprovalTools(server)
+  registerAIReviewTools(server)
   registerCommentTools(server)
   registerNotificationTools(server)
   registerGithubTools(server, ctx)