internaltool-mcp 1.6.22 → 1.6.24

package/index.js

@@ -434,8 +434,10 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
       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, autoStash = false }) => {
+    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
@@ -546,10 +548,21 @@ 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 ───────────────────────
@@ -557,17 +570,364 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
 
       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' },
         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 } : { restored: false },
+        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.',
       })
     }
   )
@@ -579,7 +939,17 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
 
 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.
 
-Call this FIRST before post_pr_review. Use it when the developer asks "review PR", "check the PR for TASK-X", or "is this PR ready to merge".`,
+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)"),
     },
@@ -654,48 +1024,75 @@ Call this FIRST before post_pr_review. Use it when the developer asks "review PR
   // ── post_pr_review ────────────────────────────────────────────────────────────
   server.tool(
     'post_pr_review',
-    `Post a GitHub PR review after analyzing the code diff.
+    `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.
 
-Always call review_pr first to get the diff and spec context. Then call this with your verdict and reasoning.
+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.
 
-IMPORTANT: This posts a real GitHub review and updates the InternalTool board. The human must confirm before this runs — always show the review body to the user and ask for approval before calling with confirmed=true.`,
+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 — be specific: what was good, what needs fixing, which files/lines'),
-      confirmed: z.boolean().optional().default(false).describe('Set true only after the human has read and approved the review text'),
+      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, confirmed = false }) => {
+    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.')
+      if (!prNumber) return errorText('No PR linked to this task. Call raise_pr first.')
 
-      // Always preview first — human must confirm
+      // 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,
+            action:         event,
             prNumber,
-            taskKey:   task.key,
-            taskTitle: task.title,
+            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 and you re-approve.'
+            ? '⚠️  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 above to the user and ask them to confirm. Then call post_pr_review again with confirmed=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.',
         })
       }
 
@@ -705,20 +1102,24 @@ IMPORTANT: This posts a real GitHub review and updates the InternalTool board. T
       )
       if (!res?.success) return errorText(res?.message || 'Could not post review')
 
+      const reviewId = res.data?.reviewId
+
       return text({
-        posted:    true,
+        posted:         true,
         event,
         prNumber,
-        taskKey:   task.key,
-        message:   event === 'APPROVE'
+        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}" to merge, or wait for the developer to merge.`
+          ? `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 get notified.`
+          ? `Wait for the developer to push fixes. They'll call fix_pr_feedback, then re-push. You'll be notified.`
           : null,
       })
     }
@@ -727,28 +1128,35 @@ IMPORTANT: This posts a real GitHub review and updates the InternalTool board. T
   // ── merge_pr ─────────────────────────────────────────────────────────────────
   server.tool(
     'merge_pr',
-    `Merge a pull request after human approval. Runs safety checks before executing.
+    `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 safety check results and asks for confirmation
+- confirmed=false (default): shows all checks and asks for confirmation
 - confirmed=true:            executes the merge
 
-The task moves to Done automatically via the existing GitHub webhook. A final comment is posted on the task.
-
-Use this when the reviewer says "merge it", "looks good, ship it", or "merge the PR for TASK-X".`,
+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 }) => {
+    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
@@ -769,8 +1177,30 @@ Use this when the reviewer says "merge it", "looks good, ship it", or "merge the
         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,
@@ -858,8 +1288,10 @@ Flow:
       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 }) => {
+    async ({ taskId, confirmed = false, repoPath, autoStash = false, agentRole }) => {
       // ── Fetch task ────────────────────────────────────────────────────────
       let taskRes
       try { taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`)) }
@@ -1017,10 +1449,21 @@ Flow:
         }
       }
 
-      // Restore cursor rules
+      // Restore cursor rules (with role injection if set)
       let cursorRulesFile = null
-      if (task?.cursorRules?.trim() && repoRoot) {
-        cursorRulesFile = writeCursorRulesFile(task.key, task.cursorRules, repoPath)
+      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
@@ -1028,18 +1471,28 @@ Flow:
 
       return text({
         resumed:     true,
-        task:        { key: task.key, title: task.title, column: task.column },
+        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 } : { restored: false },
+        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.`
+          ? `You are on branch "${branch}". Ready to resume coding${agentRole ? ` as ${agentRole}` : ''}.`
           : `Branch switch failed — see git.manualSteps.`,
-        nextStep: task.column === 'in_review'
+        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}`
@@ -1541,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
@@ -1722,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.`
@@ -1773,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({
@@ -1787,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],
@@ -1803,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.`,
       })
@@ -2210,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 {

package/package.json

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