internaltool-mcp 1.5.7 → 1.6.1

package/index.js

@@ -356,56 +356,433 @@ Set confirmed=false first to preview, then confirmed=true to actually save.`,
   )
 }
 
+// ── Standup activity formatter ────────────────────────────────────────────────
+// Converts raw activity {action, meta} into a human-readable sentence.
+function formatActivityLine(a) {
+  const m = a.meta || {}
+  switch (a.action) {
+    case 'task.created':    return 'Task created'
+    case 'task.updated':    return m.fields?.length ? `Updated: ${m.fields.join(', ')}` : 'Task updated'
+    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 '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)`
+    case 'task.pr_changes_requested':    return `PR #${m.prNumber} — changes requested by ${m.reviewerLogin || 'reviewer'}`
+    case 'task.pr_closed_without_merge': return `PR #${m.prNumber} closed without merging`
+    case 'issue.created':   return `Issue logged: "${m.title || '?'}"`
+    case 'issue.updated':   return `Issue updated`
+    default:                return a.action
+  }
+}
+
 function registerProductivityTools(server) {
   server.tool(
     'generate_standup',
-    `Generate a daily standup for the current user.
-Fetches all assigned tasks and their recent activity, then formats:
-- What was done yesterday (based on activity + park notes)
-- What is planned today (in_progress / todo tasks)
-- Any blockers
+    `Generate a full daily standup — covers both the current user's tasks AND the entire project board.
 
-Call this when the developer says "prepare my standup", "what did I do yesterday", or opens Cursor in the morning.`,
+Returns:
+- yesterday: readable activity lines for the last 24 h per task
+- today: all active tasks grouped by assignee, sorted by priority (critical first)
+- blockers: park notes + tasks without branches/PRs that are overdue
+- risks: critical/high tasks with no branch, tasks with PR changes requested
+- copy-paste: a ready-to-post standup snippet
+
+Call this when the developer says "generate standup", "what did I do yesterday", or "morning standup".`,
     {},
     async () => {
-      // Fetch all my tasks
-      const tasksRes = await api.get('/api/users/me/tasks')
-      if (!tasksRes?.success) return errorText('Could not fetch tasks')
+      const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000)
+      const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 }
+
+      // 1. Who am I?
+      const meRes = await api.get('/api/auth/me')
+      const me = meRes?.data?.user || {}
+
+      // 2. My tasks (all columns)
+      const myTasksRes = await api.get('/api/users/me/tasks')
+      const myTasks = myTasksRes?.data?.tasks || []
 
-      const tasks = tasksRes.data.tasks
-      if (!tasks.length) return text({ standup: 'No assigned tasks found.', tasks: [] })
+      // 3. All my projects (to get project-wide board)
+      const projectsRes = await api.get('/api/projects')
+      const projects = projectsRes?.data?.projects || []
 
-      // Fetch activity for each task (parallel)
+      // 4. For each project, fetch full board to get all tasks (not just mine)
+      const projectBoards = await Promise.all(
+        projects.map(async (p) => {
+          try {
+            const r = await api.get(`/api/projects/${p._id}`)
+            return r?.data?.project || null
+          } catch { return null }
+        })
+      )
+
+      // 5. Collect all unique tasks across all projects
+      const allTasksMap = new Map()
+      for (const board of projectBoards.filter(Boolean)) {
+        for (const t of (board.tasks || [])) {
+          allTasksMap.set(t._id, { ...t, projectName: board.name, projectId: board._id })
+        }
+      }
+      const allTasks = [...allTasksMap.values()]
+
+      // 6. Fetch recent activity for active tasks (parallel, capped at 20 tasks to avoid rate limits)
+      const activeTasks = allTasks.filter(t => ['in_progress', 'in_review', 'todo'].includes(t.column))
       const withActivity = await Promise.all(
-        tasks.map(async (t) => {
+        activeTasks.map(async (t) => {
           try {
-            const actRes = await api.get(`/api/tasks/${t._id}/activity`)
-            return { ...t, activity: actRes?.data?.activity || [] }
+            const r = await api.get(`/api/tasks/${t._id}/activity`)
+            const activity = r?.data?.activity || []
+            const recentLines = activity
+              .filter(a => new Date(a.createdAt) > yesterday)
+              .map(a => formatActivityLine(a))
+            return { ...t, recentActivityLines: recentLines, allActivity: activity }
           } catch {
-            return { ...t, activity: [] }
+            return { ...t, recentActivityLines: [], allActivity: [] }
           }
         })
       )
 
-      // Summarise for standup
-      const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000)
-      const standup = withActivity.map((t) => {
-        const recentActivity = t.activity.filter(
-          (a) => new Date(a.createdAt) > yesterday
-        )
-        return {
-          taskId:      t._id,
-          key:         t.key,
-          title:       t.title,
-          column:      t.column,
-          priority:    t.priority,
-          project:     t.project?.name,
-          parkNote:    t.parkNote,
-          recentActivity: recentActivity.map((a) => a.message || a.type),
+      // 7. Group by assignee
+      const byAssignee = {}
+      for (const t of withActivity) {
+        const assigneeList = (t.assignees || [])
+        if (!assigneeList.length) {
+          const key = 'Unassigned'
+          if (!byAssignee[key]) byAssignee[key] = []
+          byAssignee[key].push(t)
+        }
+        for (const a of assigneeList) {
+          const name = a.name || a.email || String(a)
+          if (!byAssignee[name]) byAssignee[name] = []
+          byAssignee[name].push(t)
+        }
+      }
+      // Sort each person's tasks by priority
+      for (const name of Object.keys(byAssignee)) {
+        byAssignee[name].sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99))
+      }
+
+      // 8. Build "yesterday" section — tasks with recent activity
+      const yesterdayItems = withActivity
+        .filter(t => t.recentActivityLines.length > 0)
+        .map(t => ({
+          key:      t.key,
+          title:    t.title,
+          project:  t.projectName,
+          assignee: (t.assignees || []).map(a => a.name || a.email).join(', ') || 'Unassigned',
+          activity: t.recentActivityLines,
+        }))
+
+      // 9. Risks + blockers
+      const risks = []
+      for (const t of withActivity) {
+        if (t.priority === 'critical' && t.column === 'todo') {
+          risks.push(`⚠️  ${t.key} (${t.projectName}) — CRITICAL but still in todo — needs kickoff now`)
+        }
+        if (t.priority === 'critical' && t.column === 'in_progress' && !t.github?.headBranch) {
+          risks.push(`⚠️  ${t.key} — CRITICAL, in_progress but no branch linked`)
         }
+        if (t.github?.changesRequestedAt) {
+          risks.push(`🔁 ${t.key} — PR has changes requested — developer needs to fix and re-push`)
+        }
+        if (t.column === 'in_review' && !t.github?.prUrl) {
+          risks.push(`❓ ${t.key} — in_review column but no PR URL recorded`)
+        }
+      }
+
+      const blockers = withActivity
+        .filter(t => t.parkNote?.blockers && t.parkNote.blockers.trim())
+        .map(t => `${t.key}: ${t.parkNote.blockers}`)
+
+      // 10. My personal section (my tasks with readable status)
+      const mySection = myTasks
+        .filter(t => ['in_progress', 'in_review', 'todo'].includes(t.column))
+        .map(t => {
+          const status = t.github?.headBranch
+            ? (t.github.prUrl ? `PR open → ${t.github.prUrl}` : `branch: ${t.github.headBranch}, no PR yet`)
+            : 'no branch yet'
+          return `${t.key} — ${t.title} [${t.column}, ${t.priority}] — ${status}`
+        })
+
+      // 11. Copy-paste snippet
+      const todayFocus = Object.entries(byAssignee)
+        .map(([person, tasks]) => `  ${person}: ${tasks.map(t => `${t.key} (${t.priority})`).join(', ')}`)
+        .join('\n')
+      const copyPaste = [
+        `**Yesterday:** ${yesterdayItems.length
+          ? yesterdayItems.map(i => `${i.key} — ${i.activity.slice(0,2).join('; ')}`).join('. ')
+          : 'No recorded activity in last 24 h.'}`,
+        `**Today:**\n${todayFocus || '  No active tasks.'}`,
+        blockers.length ? `**Blockers:** ${blockers.join(' | ')}` : '**Blockers:** None.',
+        risks.length    ? `**Risks:** ${risks.join(' | ')}` : null,
+      ].filter(Boolean).join('\n')
+
+      return text({
+        me:          { name: me.name, email: me.email, role: me.role },
+        yesterday:   yesterdayItems.length ? yesterdayItems : '(no activity logged in last 24 h)',
+        today: {
+          byAssignee: Object.fromEntries(
+            Object.entries(byAssignee).map(([person, tasks]) => [
+              person,
+              tasks.map(t => ({
+                key:        t.key,
+                title:      t.title,
+                column:     t.column,
+                priority:   t.priority,
+                project:    t.projectName,
+                branch:     t.github?.headBranch || null,
+                prUrl:      t.github?.prUrl || null,
+                parkNote:   t.parkNote?.summary || null,
+                needsFix:   !!t.github?.changesRequestedAt,
+              }))
+            ])
+          ),
+        },
+        myTasks:     mySection,
+        blockers:    blockers.length ? blockers : ['None recorded'],
+        risks:       risks.length    ? risks    : ['None'],
+        copyPaste,
+      })
+    }
+  )
+
+  // ── what_should_i_work_on ─────────────────────────────────────────────────────
+  server.tool(
+    'what_should_i_work_on',
+    `Recommend the single most important task to work on right now.
+
+Scores all assigned tasks by: priority, urgency (PR needs fix), column state, branch readiness.
+Returns the #1 pick with a clear reason and the exact next MCP call to make.
+
+Use this when the developer says "what should I do next", "I'm free", or "what's my priority".`,
+    {},
+    async () => {
+      const res = await api.get('/api/users/me/tasks')
+      if (!res?.success) return errorText('Could not fetch tasks')
+      const tasks = (res.data.tasks || []).filter(t => t.column !== 'done')
+
+      if (!tasks.length) return text({ recommendation: 'No open tasks assigned to you. Ask your project lead for work.' })
+
+      function scoreTask(t) {
+        const PRIORITY = { critical: 100, high: 60, medium: 30, low: 10 }
+        let score = PRIORITY[t.priority] ?? 0
+        if (t.github?.changesRequestedAt)  score += 80  // PR needs fix — most urgent
+        if (t.column === 'in_progress')    score += 25  // already in flight, keep momentum
+        if (t.column === 'in_review')      score += 10  // waiting on reviewer, low action needed
+        if (t.column === 'todo')           score += 15  // ready to start
+        if (t.column === 'backlog')        score -= 10  // not yet planned
+        if (t.parkNote?.parkedAt)          score -= 20  // intentionally paused
+        if (t.github?.headBranch)          score += 5   // branch already set up
+        return score
+      }
+
+      const scored = tasks
+        .map(t => ({ ...t, _score: scoreTask(t) }))
+        .sort((a, b) => b._score - a._score)
+
+      const top = scored[0]
+
+      // Build the reason and next step
+      let reason, nextStep
+      if (top.github?.changesRequestedAt) {
+        reason   = `PR has changes requested — this blocks the merge and the reviewer is waiting.`
+        nextStep = `Call fix_pr_feedback with taskAId="${top._id}" to get the full fix plan.`
+      } else if (top.column === 'in_progress' && top.github?.headBranch) {
+        reason   = `Already in progress on branch ${top.github.headBranch} — keep the momentum going.`
+        nextStep = `Continue coding on ${top.github.headBranch}. When commits are pushed, call raise_pr.`
+      } else if (top.column === 'in_progress' && !top.github?.headBranch) {
+        reason   = `In progress but no branch yet — needs a branch to start committing.`
+        nextStep = `Call create_branch with taskId="${top._id}" and projectId="${top.project?._id || top.project}".`
+      } else if (top.column === 'todo') {
+        reason   = `Highest priority unstarted task — ready to kick off.`
+        nextStep = `Call kickoff_task with taskId="${top._id}" to read the plan and move to in_progress.`
+      } else {
+        reason   = `Highest priority available task.`
+        nextStep = `Call get_task_context with taskId="${top._id}" for full details.`
+      }
+
+      // Show the queue (top 3)
+      const queue = scored.slice(0, 3).map((t, i) => ({
+        rank:     i + 1,
+        key:      t.key,
+        title:    t.title,
+        priority: t.priority,
+        column:   t.column,
+        score:    t._score,
+        branch:   t.github?.headBranch || null,
+        needsFix: !!t.github?.changesRequestedAt,
+      }))
+
+      return text({
+        recommendation: {
+          taskId:   top._id,
+          key:      top.key,
+          title:    top.title,
+          priority: top.priority,
+          column:   top.column,
+          project:  top.project?.name || top.project,
+          reason,
+          nextStep,
+        },
+        queue,
       })
+    }
+  )
+
+  // ── task_health_check ────────────────────────────────────────────────────────
+  server.tool(
+    'task_health_check',
+    `Scan the entire project board for health issues and surface them with severity levels.
+
+Detects:
+- Critical tasks sitting in todo without a branch (needs kickoff now)
+- Tasks in review for 3+ days (reviewer may be stuck)
+- Tasks in progress for 2+ days with no updates (possibly stale or blocked)
+- In-progress tasks with no branch linked
+- Active tasks with no README/implementation plan
+- PRs with changes requested that haven't been fixed
+
+Use this when the developer or team lead asks "how's the board?", "any blockers?", or for a weekly health review.`,
+    {},
+    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 r?.data?.project || null
+          } catch { return null }
+        })
+      )
+
+      const now = Date.now()
+      const MS_PER_DAY = 1000 * 60 * 60 * 24
+      const flags = []
+
+      for (const board of boards.filter(Boolean)) {
+        for (const t of (board.tasks || [])) {
+          if (t.column === 'done') continue
+          const ageDays = (now - new Date(t.updatedAt).getTime()) / MS_PER_DAY
+          const assignees = (t.assignees || []).map(a => a.name || a.email).join(', ') || 'Unassigned'
+
+          // PR changes requested — top priority
+          if (t.github?.changesRequestedAt) {
+            const daysSince = (now - new Date(t.github.changesRequestedAt).getTime()) / MS_PER_DAY
+            flags.push({
+              severity:   'critical',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `PR has had changes requested for ${Math.floor(daysSince)} day(s) — developer needs to fix and re-push`,
+              suggestion: `Use fix_pr_feedback with taskAId="${t._id}"`,
+            })
+          }
+
+          // Critical task stuck in todo
+          if (t.priority === 'critical' && t.column === 'todo') {
+            flags.push({
+              severity:   'critical',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `CRITICAL priority — stuck in todo for ${Math.floor(ageDays)} day(s)`,
+              suggestion: `Use kickoff_task with taskId="${t._id}" to start immediately`,
+            })
+          }
+
+          // High priority in todo for more than 1 day
+          if (t.priority === 'high' && t.column === 'todo' && ageDays > 1) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `HIGH priority — in todo for ${Math.floor(ageDays)} day(s) without being started`,
+              suggestion: `Use kickoff_task to start`,
+            })
+          }
+
+          // In review for 3+ days
+          if (t.column === 'in_review' && ageDays > 3) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `In review for ${Math.floor(ageDays)} days — reviewer may be stuck or PR is forgotten`,
+              suggestion: `Check PR status on GitHub or ping the reviewer`,
+            })
+          }
+
+          // In progress for 2+ days with no updates
+          if (t.column === 'in_progress' && ageDays > 2) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `In progress for ${Math.floor(ageDays)} day(s) with no board updates — possibly stale or silently blocked`,
+              suggestion: `Ask ${assignees} for a status update or check git log on ${t.github?.headBranch || 'their branch'}`,
+            })
+          }
 
-      return text({ standup })
+          // In progress but no branch linked
+          if (t.column === 'in_progress' && !t.github?.headBranch) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      'In progress but no branch linked — commits may be going to the wrong branch',
+              suggestion: `Use create_branch with taskId="${t._id}" to create and link a branch`,
+            })
+          }
+
+          // Active task with no README
+          if (['in_progress', 'in_review'].includes(t.column) && !t.readmeMarkdown?.trim()) {
+            flags.push({
+              severity:   'info',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      'No implementation plan (README) — harder to review and hard to resume if parked',
+              suggestion: `Use update_task to add a readmeMarkdown implementation plan`,
+            })
+          }
+        }
+      }
+
+      // Sort: critical → warning → info
+      const SEV = { critical: 0, warning: 1, info: 2 }
+      flags.sort((a, b) => (SEV[a.severity] ?? 9) - (SEV[b.severity] ?? 9))
+
+      const counts = {
+        critical: flags.filter(f => f.severity === 'critical').length,
+        warning:  flags.filter(f => f.severity === 'warning').length,
+        info:     flags.filter(f => f.severity === 'info').length,
+      }
+
+      return text({
+        summary: flags.length === 0
+          ? '✅ Board is healthy — no issues found.'
+          : `⚠️  ${flags.length} issue(s): ${counts.critical} critical, ${counts.warning} warnings, ${counts.info} info`,
+        counts,
+        flags,
+        healthy: flags.length === 0,
+      })
     }
   )
 
@@ -1470,6 +1847,363 @@ Set confirmed=false first to preview the full PR content, then confirmed=true to
       }
     }
   )
+
+  // ── commit_helper ─────────────────────────────────────────────────────────────
+  server.tool(
+    'commit_helper',
+    `Analyse local git changes and produce a ready-to-run conventional commit command.
+
+Auto-detects local branch, changed files, and — when taskId is given — the task's linked branch.
+If the current branch does not match the task's branch, presents three options before doing anything:
+  A) Switch to the task branch first, bring changes with you, then commit
+  B) Stash changes now and commit on the task branch later
+  C) Commit on the current branch (warns if that is main/master/dev)
+
+Commit message format: <type>(<scope>): <description>
+  type  = feat | fix | refactor | chore | docs | test | style (auto-inferred)
+  scope = task key (e.g. task-003) when taskId is provided
+
+Also flags unsafe patterns before generating any command:
+  - Untracked IDE/config dirs (.cursor/, .idea/, .vscode/, node_modules/)
+  - Committing directly to main / master / dev without a task branch
+
+TWO-STEP FLOW:
+  confirmed=false              → detect state, show branch mismatch options or commit preview
+  confirmed=true + branchAction → execute the chosen path
+
+branchAction values (only needed when current branch ≠ task branch):
+  "switch_then_commit"  — stash → checkout task branch → pop stash → commit + push
+  "stash_for_later"     — stash only; commit later when on the task branch
+  "commit_here"         — commit on current branch (use only when changes truly belong here)`,
+    {
+      taskId:       z.string().optional().describe("Task's MongoDB ObjectId"),
+      repoPath:     z.string().optional().describe('Absolute path to the local git repo'),
+      confirmed:    z.boolean().optional().default(false),
+      branchAction: z.enum(['switch_then_commit', 'stash_for_later', 'commit_here'])
+                     .optional()
+                     .describe('Required when confirmed=true and current branch ≠ task branch'),
+    },
+    async ({ taskId, repoPath, confirmed = false, branchAction }) => {
+      const cwd = repoPath || process.cwd()
+
+      // ── Read local git state ──────────────────────────────────────────────────
+      let porcelain = '', diffStat = '', currentBranch = ''
+      try {
+        porcelain     = runGit('status --porcelain=v1', cwd)
+        diffStat      = runGit('diff --stat HEAD', cwd)
+        currentBranch = runGit('branch --show-current', cwd)
+      } catch (e) {
+        return errorText(`Could not read git state: ${e.message.split('\n')[0]}`)
+      }
+
+      const { staged, unstaged, untracked, modified } = parseGitStatus(porcelain)
+
+      if (modified.length === 0 && untracked.length === 0) {
+        return text({ message: 'Nothing to commit — working tree is clean.', currentBranch })
+      }
+
+      // ── Fetch task ────────────────────────────────────────────────────────────
+      let task = null
+      if (taskId) {
+        try {
+          const r = await api.get(`/api/tasks/${taskId}`)
+          if (r?.success) task = r.data.task
+        } catch { /* non-fatal */ }
+      }
+
+      const taskBranch    = task?.github?.headBranch || null
+      const PROTECTED     = ['main', 'master', 'dev', 'develop', 'staging', 'production']
+      const onProtected   = PROTECTED.includes(currentBranch)
+      const branchMismatch = taskBranch && currentBranch !== taskBranch
+
+      // ── Detect unsafe untracked paths ─────────────────────────────────────────
+      const NOCOMMIT_PATTERNS = ['.cursor', '.idea', '.vscode', 'node_modules', '.env', 'dist', 'build', '.DS_Store']
+      const unsafeUntracked = untracked.filter(f =>
+        NOCOMMIT_PATTERNS.some(p => f === p || f.startsWith(p + '/'))
+      )
+      const safeUntracked = untracked.filter(f =>
+        !NOCOMMIT_PATTERNS.some(p => f === p || f.startsWith(p + '/'))
+      )
+
+      // ── Build commit message ──────────────────────────────────────────────────
+      // Use task branch name for type inference if available (more reliable than current branch)
+      const branchForType = taskBranch || currentBranch
+      const branchLower   = branchForType.toLowerCase()
+      const diffLower     = diffStat.toLowerCase()
+      let commitType = 'chore'
+      if (branchLower.startsWith('feature/') || branchLower.startsWith('feat/'))    commitType = 'feat'
+      else if (branchLower.startsWith('fix/') || branchLower.startsWith('hotfix/')) commitType = 'fix'
+      else if (branchLower.startsWith('refactor/'))                                 commitType = 'refactor'
+      else if (branchLower.startsWith('docs/'))                                     commitType = 'docs'
+      else if (branchLower.startsWith('test/'))                                     commitType = 'test'
+      else if (diffLower.includes('test') || diffLower.includes('spec'))            commitType = 'test'
+      else if (task) {
+        const t = (task.title || '').toLowerCase()
+        if (/\b(fix|bug|hotfix|patch)\b/.test(t))      commitType = 'fix'
+        else if (/\b(refactor|cleanup)\b/.test(t))     commitType = 'refactor'
+        else                                            commitType = 'feat'
+      }
+
+      const scope = task?.key?.toLowerCase() || ''
+      let description = task
+        ? task.title.toLowerCase().replace(/[^a-z0-9 ]+/g, '').replace(/\s+/g, ' ').trim().slice(0, 60)
+        : modified.length === 1
+          ? `update ${modified[0].split('/').pop()}`
+          : `update ${modified.length} file(s)`
+
+      const commitMsg = scope ? `${commitType}(${scope}): ${description}` : `${commitType}: ${description}`
+
+      // ── Build add command — exclude unsafe untracked ──────────────────────────
+      const trackedFiles = [...modified, ...safeUntracked]
+      const addCmd = unsafeUntracked.length > 0 && (unstaged.length > 0 || safeUntracked.length > 0)
+        ? trackedFiles.map(f => `git add "${f}"`).join('\n')   // explicit adds — skip unsafe
+        : unstaged.length > 0 || safeUntracked.length > 0
+          ? 'git add .'
+          : null  // everything already staged
+
+      const changedFilesList = [
+        ...staged.map(f => `staged:    ${f.file}`),
+        ...unstaged.map(f => `unstaged:  ${f.file}`),
+        ...safeUntracked.map(f => `untracked: ${f}`),
+        ...unsafeUntracked.map(f => `⚠️ SKIP:   ${f}  ← do not commit this`),
+      ]
+
+      // ── PREVIEW (confirmed=false) ─────────────────────────────────────────────
+      if (!confirmed) {
+        // Case 1: branch mismatch — must resolve before anything else
+        if (branchMismatch) {
+          const stashMsg = `wip: ${scope || currentBranch} — switching to ${taskBranch}`
+          return text({
+            situation: {
+              currentBranch,
+              taskBranch,
+              message: `You are on "${currentBranch}" but TASK-${task?.key} is linked to "${taskBranch}". Choose how to handle your local changes before committing.`,
+            },
+            changedFiles: changedFilesList,
+            unsafeUntrackedWarning: unsafeUntracked.length
+              ? `These paths should NOT be committed — add them to .gitignore: ${unsafeUntracked.join(', ')}`
+              : null,
+            options: {
+              A: {
+                branchAction: 'switch_then_commit',
+                description:  'Switch to the task branch now, bring your changes, then commit (recommended)',
+                commands: [
+                  `git stash push -m "${stashMsg}"`,
+                  `git fetch origin`,
+                  `git checkout ${taskBranch}`,
+                  `git stash pop`,
+                  addCmd,
+                  `git commit -m "${commitMsg}"`,
+                  `git push origin ${taskBranch}`,
+                ].filter(Boolean),
+              },
+              B: {
+                branchAction: 'stash_for_later',
+                description:  'Stash changes now and commit on the task branch later',
+                commands: [
+                  `git stash push -m "${stashMsg}"`,
+                  `# Later: git checkout ${taskBranch} && git stash pop`,
+                ],
+              },
+              C: {
+                branchAction: 'commit_here',
+                description:  `Commit on "${currentBranch}" as-is${onProtected ? ' ⚠️ THIS IS A PROTECTED BRANCH' : ''}`,
+                warning:      onProtected
+                  ? `"${currentBranch}" is a protected branch. Committing here directly bypasses the PR review process. Only do this for base repo changes (e.g. .gitignore, root README) that don't belong to any feature branch.`
+                  : null,
+                commands: [addCmd, `git commit -m "${commitMsg}"`, `git push origin ${currentBranch}`].filter(Boolean),
+              },
+            },
+            requiresConfirmation: true,
+            message: `Call commit_helper again with confirmed=true and branchAction set to "switch_then_commit", "stash_for_later", or "commit_here".`,
+          })
+        }
+
+        // Case 2: on correct branch — standard preview
+        const pushCmd = `git push origin ${currentBranch}`
+        return text({
+          preview: {
+            suggestedMessage: commitMsg,
+            type:             commitType,
+            scope,
+            currentBranch,
+            taskBranch:       taskBranch || '(none linked)',
+            onCorrectBranch:  !branchMismatch,
+            changedFiles:     changedFilesList,
+          },
+          unsafeUntrackedWarning: unsafeUntracked.length
+            ? `These paths should NOT be committed — add them to .gitignore first: ${unsafeUntracked.join(', ')}`
+            : null,
+          protectedBranchWarning: onProtected
+            ? `⚠️ You are on "${currentBranch}" — a protected branch. Consider committing on a feature branch instead.`
+            : null,
+          commands: [addCmd, `git commit -m "${commitMsg}"`, pushCmd].filter(Boolean),
+          requiresConfirmation: true,
+          message: `Suggested: "${commitMsg}". Call commit_helper again with confirmed=true to get the final commands.`,
+        })
+      }
+
+      // ── CONFIRMED (confirmed=true) ────────────────────────────────────────────
+      if (branchMismatch && !branchAction) {
+        return text({
+          blocked: true,
+          message: `Branch mismatch detected. You must set branchAction to one of: "switch_then_commit", "stash_for_later", "commit_here". Call commit_helper with confirmed=false first to see the options.`,
+        })
+      }
+
+      const stashMsg = `wip: ${scope || currentBranch} — switching to ${taskBranch}`
+
+      if (branchAction === 'switch_then_commit') {
+        return text({
+          plan:    'switch_then_commit',
+          commands: [
+            `git stash push -m "${stashMsg}"`,
+            `git fetch origin`,
+            `git checkout ${taskBranch}`,
+            `git stash pop`,
+            addCmd,
+            `git commit -m "${commitMsg}"`,
+            `git push origin ${taskBranch}`,
+          ].filter(Boolean),
+          commitMessage: commitMsg,
+          message: `Run these commands in order. Your changes will land on "${taskBranch}" where they belong.`,
+          nextStep: `After pushing, call raise_pr to open the pull request for ${task?.key}.`,
+          unsafeUntrackedWarning: unsafeUntracked.length
+            ? `These will be in your working tree after stash pop — do NOT git add them: ${unsafeUntracked.join(', ')}`
+            : null,
+        })
+      }
+
+      if (branchAction === 'stash_for_later') {
+        return text({
+          plan:    'stash_for_later',
+          commands: [
+            `git stash push -m "${stashMsg}"`,
+          ],
+          message: `Your changes are stashed. When you're ready to commit:`,
+          resumeCommands: [
+            `git checkout ${taskBranch}`,
+            `git stash pop`,
+            addCmd,
+            `git commit -m "${commitMsg}"`,
+            `git push origin ${taskBranch}`,
+          ].filter(Boolean),
+          commitMessage: commitMsg,
+        })
+      }
+
+      // commit_here (or no mismatch)
+      const targetBranch = currentBranch
+      const pushCmd = `git push origin ${targetBranch}`
+      return text({
+        commitMessage: commitMsg,
+        commands:      [addCmd, `git commit -m "${commitMsg}"`, pushCmd].filter(Boolean),
+        changedFiles:  changedFilesList,
+        protectedBranchWarning: onProtected
+          ? `⚠️ Committing directly to "${targetBranch}". Only appropriate for base repo changes that don't belong to a feature branch.`
+          : null,
+        unsafeUntrackedWarning: unsafeUntracked.length
+          ? `These were excluded from git add — add them to .gitignore: ${unsafeUntracked.join(', ')}`
+          : null,
+        message:  `Copy-paste these commands in order.`,
+        nextStep: taskBranch && !branchMismatch ? `After pushing, call raise_pr to open the pull request.` : null,
+      })
+    }
+  )
+
+  // ── branch_cleanup ────────────────────────────────────────────────────────────
+  server.tool(
+    'branch_cleanup',
+    `Find merged branches that are safe to delete — both on GitHub and locally.
+
+Checks GitHub branches against tasks that have been merged (github.mergedAt set).
+Also runs "git branch --merged origin/main" locally to find stale local branches.
+
+Set confirmed=false to preview the list, confirmed=true to get the exact delete commands.
+
+Use this when the developer says "clean up branches", "delete merged branches", or after a sprint ends.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      repoPath:  z.string().optional().describe('Absolute path to the local git repo'),
+      confirmed: z.boolean().optional().default(false).describe('Set true to get the delete commands'),
+    },
+    async ({ projectId, repoPath, confirmed = false }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+
+      // Fetch GitHub branches
+      const branchesRes = await api.get(`/api/projects/${projectId}/github/branches`)
+      if (!branchesRes?.success) return errorText('Could not fetch GitHub branches')
+      const remoteBranches = (branchesRes.data.branches || []).map(b => b.name || b)
+
+      // Fetch all tasks to find which branches are merged
+      const projectRes = await api.get(`/api/projects/${projectId}`)
+      const tasks = projectRes?.data?.project?.tasks || []
+      const defaultBranch = projectRes?.data?.project?.githubDefaultBranch || 'main'
+
+      // Branches linked to merged tasks
+      const mergedTaskBranches = new Set(
+        tasks
+          .filter(t => t.github?.mergedAt && t.github?.headBranch)
+          .map(t => t.github.headBranch)
+      )
+
+      // Remote branches safe to delete (merged task branch, not the default branch)
+      const remoteToDelete = remoteBranches.filter(b =>
+        mergedTaskBranches.has(b) && b !== defaultBranch && b !== 'main' && b !== 'master' && b !== 'dev'
+      )
+
+      // Local merged branches
+      const cwd = repoPath || process.cwd()
+      let localMerged = []
+      try {
+        const localRaw = runGit(`branch --merged origin/${defaultBranch}`, cwd)
+        localMerged = localRaw
+          .split('\n')
+          .map(b => b.replace(/^\*?\s+/, '').trim())
+          .filter(b => b && b !== defaultBranch && b !== 'main' && b !== 'master' && b !== 'dev')
+      } catch { /* git may not be available or no upstream */ }
+
+      if (!confirmed) {
+        return text({
+          preview: {
+            remoteBranchesToDelete: remoteToDelete,
+            localBranchesToDelete:  localMerged,
+            defaultBranch,
+            remoteCount: remoteToDelete.length,
+            localCount:  localMerged.length,
+          },
+          requiresConfirmation: true,
+          message: remoteToDelete.length === 0 && localMerged.length === 0
+            ? 'No merged branches found to clean up. Repository is already clean.'
+            : `Found ${remoteToDelete.length} remote and ${localMerged.length} local branch(es) to delete. Call branch_cleanup again with confirmed=true to get the delete commands.`,
+          safetyNote: 'Only branches linked to tasks with a merged PR are included. Default branch, main, master, and dev are always excluded.',
+        })
+      }
+
+      const remoteDeleteCmds = remoteToDelete.map(b => `git push origin --delete ${b}`)
+      const localDeleteCmds  = localMerged.map(b => `git branch -d ${b}`)
+      const allCmds = [
+        '# Fetch latest remote state first',
+        `git fetch origin --prune`,
+        '',
+        remoteDeleteCmds.length ? '# Delete merged remote branches' : null,
+        ...remoteDeleteCmds,
+        '',
+        localDeleteCmds.length ? '# Delete merged local branches' : null,
+        ...localDeleteCmds,
+      ].filter(v => v !== null)
+
+      return text({
+        commands:              allCmds,
+        remoteBranchesDeleted: remoteToDelete,
+        localBranchesDeleted:  localMerged,
+        message: `Run the commands above to clean up ${remoteToDelete.length} remote and ${localMerged.length} local branch(es).`,
+        tip: 'git fetch --prune also removes stale remote-tracking refs automatically.',
+      })
+    }
+  )
 }
 
 function registerAdminTools(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "internaltool-mcp",
-  "version": "1.5.7",
+  "version": "1.6.1",
   "description": "MCP server for InternalTool — connect AI assistants (Claude Code, Cursor) to your project and task management platform",
   "type": "module",
   "main": "index.js",