internaltool-mcp 1.6.22 → 1.6.25

package/index.js

@@ -391,11 +391,16 @@ Set confirmed=false first to preview, then confirmed=true to execute everything.
       // ── Save park note + server-side comment & notifications ──────────────
       await api.patch(`/api/tasks/${taskId}/park`, { summary, remaining, blockers })
 
-      // ── Delete cursor rules file ───────────────────────────────────────────
+      // ── Delete cursor rules file + task-scoped workspace files ───────────────
       let cursorRulesCleared = null
       if (task?.cursorRules?.trim()) {
         cursorRulesCleared = deleteCursorRulesFile(task.key, repoPath)
       }
+      deleteCursorWorkspace(task?.agentRole || null, repoPath)
+      // Mark workspace as cleared in DB so UI shows "not active"
+      api.patch(`/api/tasks/${taskId}`, {
+        agentWorkspace: { clearedAt: new Date().toISOString() }
+      }).catch(() => {/* non-fatal */})
 
       // ── #9 Capture last commit for handoff metadata ───────────────────────
       const lastCommit = getLastCommitMeta(repoRoot)
@@ -434,8 +439,11 @@ 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 }) => {
+      trackTaskActivity(taskId, 'unpark_task')
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       const task    = taskRes?.data?.task
       const branch  = task?.github?.headBranch || null
@@ -546,10 +554,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 +576,368 @@ 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 }) => {
+      trackTaskActivity(taskId, 'claim_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 }) => {
+      trackTaskActivity(taskId, 'decompose_task')
+      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 = '' }) => {
+      trackTaskActivity(taskId, 'scout_task')
+      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 }) => {
+      trackTaskActivity(taskId, 'get_agent_context')
+      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 +949,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 +1034,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 +1112,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 +1138,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 +1187,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 +1298,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 +1459,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 +1481,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}`
@@ -1047,6 +1510,33 @@ Flow:
       })
     }
   )
+
+  // ── log_session_event ─────────────────────────────────────────────────────────
+  server.tool(
+    'log_session_event',
+    `Log a skill invocation, subagent start, rule activation, or informational note to the task's session timeline.
+Call this whenever you:
+  - Invoke a skill (type="skill", name=skill file name e.g. "scout-codebase")
+  - Spawn a subagent (type="subagent", name=subagent name)
+  - Activate a rule (type="rule", name=rule name)
+  - Want to note a significant step (type="info", name=short label)
+The log is visible in InternalTool under the task's Session tab — gives the human full visibility into what the agent is doing.`,
+    {
+      taskId:  z.string().describe("Task's MongoDB ObjectId"),
+      type:    z.enum(['skill', 'subagent', 'rule', 'info']).describe('Event type'),
+      name:    z.string().describe('Name of the skill / subagent / rule / step'),
+      summary: z.string().optional().default('').describe('Optional one-line description of what this event does'),
+      role:    z.string().optional().describe('Active agent role at this point (builder, scout, reviewer, coordinator)'),
+    },
+    async ({ taskId, type, name, summary = '', role }) => {
+      trackTaskActivity(taskId, 'log_session_event', { role, summary: `[${type}] ${name}` })
+      // Also push a dedicated entry with the correct event type
+      api.post(`/api/tasks/${taskId}/session/log`, {
+        type, name, role: role || null, summary,
+      }).catch(() => {})
+      return text({ logged: true, type, name, summary })
+    }
+  )
 }
 
 // ── Standup activity formatter ────────────────────────────────────────────────
@@ -1541,8 +2031,11 @@ 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 }) => {
+      trackTaskActivity(taskId, 'kickoff_task')
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
@@ -1573,6 +2066,7 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       // ── Preview: show the full plan before touching anything ──
       const pendingApv = (task.approvals || []).find(a => a.state === 'pending') || null
       const hasApprovedApv = (task.approvals || []).some(a => a.state === 'approved')
+      const approvalState = pendingApv ? 'pending' : hasApprovedApv ? 'approved' : 'none'
       const approvalBlocks = ['backlog', 'todo'].includes(task.column) && !hasApprovedApv
 
       // Build the next-step roadmap so developer knows exactly what comes after reading the plan
@@ -1722,6 +2216,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.`
@@ -1757,11 +2266,18 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
 
       // ── Confirmed: move to in_progress and fetch recent commits ──
       let recentCommits = []
+      let projectAgentConfig = null
       try {
         const commitsRes = await api.get(`/api/projects/${task.project}/github/commits?per_page=10`)
         if (commitsRes?.success) recentCommits = commitsRes.data.commits || []
       } catch { /* GitHub may not be linked */ }
 
+      // Fetch project agentConfig for custom role generation
+      try {
+        const projRes = await api.get(`/api/projects/${task.project}`)
+        if (projRes?.success) projectAgentConfig = projRes.data.project?.agentConfig || null
+      } catch { /* non-fatal */ }
+
       // If the task already has a branch linked, it's safe to move to in_progress now.
       // If not, create_branch will do the move once the branch is created.
       const alreadyHasBranch = !!task.github?.headBranch
@@ -1773,12 +2289,31 @@ 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)
       }
 
+      // Dynamically generate .cursor/agents, .cursor/skills, .cursor/commands
+      // based on live task data — so every agent gets the right task ID, files, and role
+      const workspaceResult = writeCursorWorkspace(task, projectAgentConfig, repoPath || process.cwd())
+
+      // Persist agentRole + workspace status to server
+      const workspacePatch = {
+        ...(agentRole ? { agentRole } : {}),
+        agentWorkspace: {
+          kickedOffAt: new Date().toISOString(),
+          clearedAt:   null,
+          role:        agentRole || task.agentRole || null,
+          files:       workspaceResult?.written?.map(f => f.replace(workspaceResult.repoRoot, '').replace(/^\//, '')) || [],
+        },
+      }
+      api.patch(`/api/tasks/${taskId}`, workspacePatch).catch(() => {/* non-fatal */})
+
       return text({
         started: {
           key:      task.key,
@@ -1787,14 +2322,26 @@ 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,
+        cursorWorkspace: workspaceResult
+          ? { written: true, files: workspaceResult.written.map(f => f.replace(workspaceResult.repoRoot, '')), note: 'Agent, skill, and command files generated dynamically from task data. Reload Cursor Settings → Rules, Skills, Subagents to see them.' }
+          : { written: false, note: 'Could not generate workspace files — not inside a git repo.' },
         recentCommits: recentCommits.slice(0, 5).map(c => ({
           sha:     c.sha?.slice(0, 7),
           message: c.commit?.message?.split('\n')[0],
@@ -1803,7 +2350,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 +2765,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 {
@@ -2226,6 +2884,202 @@ function writeCursorRulesFile(taskKey, rulesMarkdown, startPath) {
   }
 }
 
+/**
+ * Dynamically generate .cursor/ workspace files from live InternalTool data.
+ *
+ * Sources (in priority order):
+ *  1. project.agentConfig.subagents[]  → .cursor/agents/<name>.md
+ *  2. project.agentConfig.skills[]     → .cursor/skills/<name>.md
+ *  3. project.agentConfig.rules[]      → .cursor/rules/<name>.mdc  (project-level, alwaysApply)
+ *  4. Built-in ROLE_RULES / default skill templates (fallback when DB arrays are empty)
+ *
+ * Task-specific agent file (.cursor/agents/active-agent.md) is always written
+ * from the task's role + claimed files + task ID so Cursor knows exactly what to do.
+ * It is deleted by deleteCursorWorkspace() when the task is parked or completed.
+ */
+function writeCursorWorkspace(task, projectAgentConfig, startPath) {
+  try {
+    const repoRoot = findRepoRoot(startPath)
+    if (!repoRoot) return null
+
+    const role         = task.agentRole || null
+    const taskId       = String(task._id)
+    const taskKey      = task.key || 'TASK-???'
+    const taskTitle    = task.title || ''
+    const claimedFiles = task.claimedFiles || []
+    const hasScout     = !!(task.scoutReport?.trim())
+    const hasDec       = !!(task.decomposition?.trim())
+    const cfg          = projectAgentConfig || {}
+
+    const agentsDir   = join(repoRoot, '.cursor', 'agents')
+    const skillsDir   = join(repoRoot, '.cursor', 'skills')
+    const commandsDir = join(repoRoot, '.cursor', 'commands')
+    const rulesDir    = join(repoRoot, '.cursor', 'rules')
+    mkdirSync(agentsDir,   { recursive: true })
+    mkdirSync(skillsDir,   { recursive: true })
+    mkdirSync(commandsDir, { recursive: true })
+    mkdirSync(rulesDir,    { recursive: true })
+
+    const written = []
+
+    // ── 1. Project-level rules from DB → .cursor/rules/<name>.mdc ─────────────
+    const projectRules = cfg.rules || []
+    for (const r of projectRules) {
+      if (!r.name || !r.body) continue
+      const content = `---\ndescription: ${r.description || r.name} — project rule managed in InternalTool. Do not edit manually.\nalwaysApply: ${r.alwaysApply ? 'true' : 'false'}\n---\n\n${r.body}\n`
+      const f = join(rulesDir, `${r.name}.mdc`)
+      writeFileSync(f, content, 'utf8')
+      written.push(f)
+    }
+
+    // ── 2. Subagents from DB → .cursor/agents/<name>.md ───────────────────────
+    //    If DB has subagents defined, write them verbatim (admin-authored markdown)
+    const dbSubagents = cfg.subagents || []
+    for (const s of dbSubagents) {
+      if (!s.name || !s.body) continue
+      const header = `---\nname: ${s.name}\ndescription: ${s.description || s.name}\n---\n\n`
+      const f = join(agentsDir, `${s.name}.md`)
+      writeFileSync(f, header + s.body, 'utf8')
+      written.push(f)
+    }
+
+    // ── 3. Task-specific active-agent.md — always written, deleted on done ────
+    //    Uses DB subagent body as template if one matches the role; falls back to
+    //    built-in ROLE_RULES template with task-specific data injected.
+    if (role) {
+      const dbMatch = dbSubagents.find(s => s.name === `${role}-agent` || s.name === role)
+      let agentBody
+      if (dbMatch?.body) {
+        // Admin wrote a custom body — inject task data into placeholder tokens
+        agentBody = dbMatch.body
+          .replace(/\{\{taskId\}\}/g, taskId)
+          .replace(/\{\{taskKey\}\}/g, taskKey)
+          .replace(/\{\{taskTitle\}\}/g, taskTitle)
+          .replace(/\{\{claimedFiles\}\}/g, claimedFiles.map(f => `- \`${f}\``).join('\n') || '(none)')
+      } else {
+        // Built-in fallback template
+        const fileLine = claimedFiles.length
+          ? claimedFiles.map(f => `- \`${f}\``).join('\n')
+          : '- (no files claimed yet — call claim_files first)'
+        const scoutLine = hasScout ? '✅ Scout report available — call `get_agent_context` to read it.' : '⚠️  No scout report yet.'
+        const decLine   = hasDec   ? '✅ Execution plan exists — follow the decomposition order.' : ''
+
+        const BUILT_IN = {
+          scout: `# Scout Agent — ${taskKey}\n\n**Task ID:** \`${taskId}\`\n**Task:** ${taskTitle}\n\n## Constraints\n- READ ONLY — do not write or modify any file\n- You CAN read files, run tests, and use MCP tools\n\n## Workflow\n1. Call \`get_agent_context\` with taskId \`${taskId}\`\n2. Read every source file systematically\n3. Call \`scout_task\` with confirmed=false, then confirmed=true + your report\n`,
+          builder: `# Builder Agent — ${taskKey}\n\n**Task ID:** \`${taskId}\`\n**Task:** ${taskTitle}\n\n**Claimed files:**\n${fileLine}\n\n${scoutLine}\n${decLine}\n\n## Constraints\n- Only modify your claimed files\n- Every change needs a test update\n- Run tests before marking done\n\n## Workflow\n1. Call \`get_agent_context\` with taskId \`${taskId}\`\n2. Implement the feature\n3. Use the \`run-tests\` skill to verify\n4. Call \`commit_helper\` then \`raise_pr\`\n`,
+          coordinator: `# Coordinator Agent — ${taskKey}\n\n**Task ID:** \`${taskId}\`\n**Task:** ${taskTitle}\n\n## Constraints\n- Do NOT write code — plan and delegate only\n- Each subtask must have exclusive file ownership\n\n## Workflow\n1. Call \`get_agent_context\` with taskId \`${taskId}\`\n2. Break work into subtasks with role + files + description\n3. Call \`decompose_task\` with taskId \`${taskId}\` to save the plan\n`,
+          reviewer: `# Reviewer Agent — ${taskKey}\n\n**Task ID:** \`${taskId}\`\n**Task:** ${taskTitle}\n\n## Constraints\n- Read the full diff before approving\n- Post specific, file-level comments\n\n## Workflow\n1. Call \`get_agent_context\` with taskId \`${taskId}\`\n2. Call \`review_pr\` to fetch the diff\n3. Call \`post_pr_review\` with your verdict\n`,
+        }
+        agentBody = BUILT_IN[role] || `# ${role} Agent — ${taskKey}\n\n**Task ID:** \`${taskId}\`\n**Task:** ${taskTitle}\n`
+      }
+
+      const activeAgentContent = `---\nname: active-agent\ndescription: ${role} agent for ${taskKey} — auto-generated by InternalTool MCP on kickoff. Deleted when task is parked or done.\n---\n\n${agentBody}`
+      writeFileSync(join(agentsDir, 'active-agent.md'), activeAgentContent, 'utf8')
+      written.push(join(agentsDir, 'active-agent.md'))
+    }
+
+    // ── 4. Custom role agents from project.agentConfig.roles (non-subagent) ───
+    for (const cr of (cfg.roles || [])) {
+      if (!cr.name || dbSubagents.some(s => s.name === `${cr.name}-agent`)) continue
+      const content = `---\nname: ${cr.name}-agent\ndescription: ${cr.label || cr.name}${cr.promptHint ? ' — ' + cr.promptHint.slice(0, 80) : ''}\n---\n\n# ${cr.label || cr.name} Agent\n\n**Role:** \`${cr.name}\`\n${cr.promptHint ? `\n## Instructions\n${cr.promptHint}\n` : ''}${cr.allowedTools?.length ? `\n## Allowed tools\n${cr.allowedTools.map(t => `- ${t}`).join('\n')}\n` : ''}`
+      const f = join(agentsDir, `${cr.name}-agent.md`)
+      writeFileSync(f, content, 'utf8')
+      written.push(f)
+    }
+
+    // ── 5. Skills from DB → .cursor/skills/<name>.md ──────────────────────────
+    //    If DB is empty, write built-in defaults so Cursor always has something useful.
+    const dbSkills = cfg.skills || []
+    if (dbSkills.length > 0) {
+      for (const s of dbSkills) {
+        if (!s.name || !s.body) continue
+        const header = `---\nname: ${s.name}\ndescription: ${s.description || s.name}\n---\n\n`
+        const f = join(skillsDir, `${s.name}.md`)
+        writeFileSync(f, header + s.body, 'utf8')
+        written.push(f)
+      }
+    } else {
+      // Built-in default skills
+      const defaults = [
+        {
+          name: 'scout-codebase',
+          description: 'Read every source file and save a scout report to InternalTool.',
+          body: `1. Read all source files: routes, models, middleware, utils, tests, README, .cursorrules\n2. Write a report: Auth Flow, Data Model, API Surface, Utilities, Test Coverage, Gaps & Risks\n3. Call \`scout_task\` with taskId \`${taskId}\` confirmed=false (preview), then confirmed=true + report\n\n**READ ONLY — do not modify any file.**`,
+        },
+        {
+          name: 'run-tests',
+          description: 'Run the test suite and fix any failures before marking done.',
+          body: `1. Run \`npm test\`\n2. Report: passed / failed / skipped\n3. For each failure: identify root cause, fix source (not the test)\n4. Re-run until 0 failures\n5. Do NOT mark done until tests are green`,
+        },
+      ]
+      for (const s of defaults) {
+        const content = `---\nname: ${s.name}\ndescription: ${s.description}\n---\n\n${s.body}\n`
+        const f = join(skillsDir, `${s.name}.md`)
+        writeFileSync(f, content, 'utf8')
+        written.push(f)
+      }
+    }
+
+    // ── 6. Command — start-task pre-filled with this task ─────────────────────
+    const startCmd = `---\nname: start-task\ndescription: Start a task from InternalTool — brief, role rules, moves to In Progress.\n---\n\nDefault task: \`${taskId}\` (${taskKey} — ${taskTitle})\n\n1. Ask the user to confirm the task ID or use the default above\n2. Call \`kickoff_task\` with confirmed=false to show the brief\n3. Present: role, description, claimedFiles, cursorRules\n4. Ask "Ready to confirm and move to In Progress?"\n5. If yes, call \`kickoff_task\` again with confirmed=true\n`
+    writeFileSync(join(commandsDir, 'start-task.md'), startCmd, 'utf8')
+    written.push(join(commandsDir, 'start-task.md'))
+
+    return { repoRoot, written }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Delete task-specific workspace files written at kickoff.
+ * Project-level rules (.cursor/rules/<project-rule>.mdc) and skills are kept.
+ * Only the active-agent and start-task command are removed (they are task-scoped).
+ */
+function deleteCursorWorkspace(role, startPath) {
+  const deleted = []
+  try {
+    const repoRoot = findRepoRoot(startPath)
+    if (!repoRoot) return deleted
+    const toDelete = [
+      join(repoRoot, '.cursor', 'agents', 'active-agent.md'),
+      join(repoRoot, '.cursor', 'commands', 'start-task.md'),
+    ]
+    for (const f of toDelete) {
+      try {
+        if (existsSync(f)) { unlinkSync(f); deleted.push(f) }
+      } catch { /* non-fatal */ }
+    }
+  } catch { /* non-fatal */ }
+  return deleted
+}
+
+/**
+ * Record that a specific MCP tool was called for a task.
+ * 1. Updates agentWorkspace.lastActivityAt + lastTool (fast summary for overview card)
+ * 2. Appends to agentSessionLog (the ordered call history shown in Session tab)
+ * Fire-and-forget: never blocks the tool response.
+ */
+function trackTaskActivity(taskId, toolName, opts = {}) {
+  if (!taskId) return
+  // Fast summary update
+  api.patch(`/api/tasks/${taskId}`, {
+    agentWorkspace: {
+      lastActivityAt: new Date().toISOString(),
+      lastTool:       toolName,
+      _incCallCount:  true,
+      ...(opts.role ? { role: opts.role } : {}),
+    },
+  }).catch(() => {})
+  // Ordered session log entry
+  api.post(`/api/tasks/${taskId}/session/log`, {
+    type:    'tool',
+    name:    toolName,
+    role:    opts.role    || null,
+    summary: opts.summary || '',
+  }).catch(() => {})
+}
+
 /** Delete the task-specific cursor rules file when work is complete. */
 function deleteCursorRulesFile(taskKey, startPath) {
   try {
@@ -2680,6 +3534,7 @@ 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 }) => {
+      trackTaskActivity(taskId, 'get_task_context')
       let taskRes, activityRes
       try {
         [taskRes, activityRes] = await Promise.all([
@@ -2816,7 +3671,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 pendingApv2 = (task.approvals || []).find(a => a.state === 'pending') || null
       const hasApprovedApv2 = (task.approvals || []).some(a => a.state === 'approved')
+      const approvalState = pendingApv2 ? 'pending' : hasApprovedApv2 ? 'approved' : 'none'
       const PLANNING_COLS = ['backlog', 'todo']
       const needsApproval = PLANNING_COLS.includes(task.column) && !hasApprovedApv2
       if (needsApproval && !confirmed) {

package/package.json

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