internaltool-mcp 1.6.45 → 1.6.52

package/index.js

@@ -963,7 +963,7 @@ WHAT THIS DOES AUTOMATICALLY (confirmed=true):
 1. Verifies all changes are committed and pushed — blocks if not
 2. Auto-pushes any unpushed commits to remote
 3. Saves your park note (summary, remaining, blockers) to the task
-4. Deletes the cursor rules file (.cursor/rules/<task>.mdc) so it doesn't bleed into other tasks
+4. Deletes all workspace files (.cursor/rules/, .cursor/skills/, .cursor/agents/) so they don't bleed into other tasks
 5. Posts a comment on the task with your handoff notes (visible to Dev B)
 6. Notifies all project members that this task is parked and ready for pickup
 
@@ -1023,8 +1023,10 @@ Set confirmed=false first to preview, then confirmed=true to execute everything.
       // ── Auto-commit if there are uncommitted changes ───────────────────────
       if (repoRoot && uncommitted) {
         try {
-          const commitMsg = `wip(${task?.key?.toLowerCase() || 'task'}): ${(summary || 'parking task').slice(0, 60)}`
-          runGit('add -A', repoRoot)
+          const rawMsg = `wip(${task?.key?.toLowerCase() || 'task'}): ${(summary || 'parking task').slice(0, 60)}`
+          // Sanitize to prevent shell injection — strip/replace special chars
+          const commitMsg = rawMsg.replace(/"/g, "'").replace(/[`$\\]/g, '')
+          runGit('add -u', repoRoot)  // only tracked files — avoids staging .env / build artifacts
           runGit(`commit -m "${commitMsg}"`, repoRoot)
           unpushedCount += 1   // just committed, so now there's something to push
         } catch (e) {
@@ -1087,10 +1089,12 @@ WHAT THIS DOES AUTOMATICALLY (confirmed=true):
 2. Shows the last 5 commits on the branch so you know the exact state of the code
 3. Shows recent task comments so you have full context
 4. Runs: git fetch origin + git checkout <branch> + git pull (switches your local repo)
-5. Restores the cursor rules file (.cursor/rules/<task>.mdc) so Cursor follows task rules
-6. Posts a comment that you picked up the task
-7. Notifies the previous developer that you have taken over
+5. Restores the FULL cursor workspace: rules, skills, session-protocol, active-agent.md
+6. Logs all restored skills/rules to the session activity timeline
+7. Posts a comment that you picked up the task
+8. Notifies the previous developer that you have taken over
 
+After unparking: READ all injected skills before touching any files. Then re-claim files.
 Set confirmed=false first to read everything, then confirmed=true to execute.`,
     {
       taskId:    z.string().describe("Task's MongoDB ObjectId"),
@@ -1140,6 +1144,8 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
             `git checkout ${branch}`,
             `git pull origin ${branch}`,
             task?.cursorRules?.trim() ? `Restore .cursor/rules/${task.key?.toLowerCase()}.mdc` : null,
+            `Restore full cursor workspace (skills, session-protocol, active-agent.md)`,
+            `Log restored workspace files to session timeline`,
             'Post "picked up" comment on task',
             'Notify previous developer',
           ].filter(Boolean) : ['No branch linked — create one with create_branch after unparking'],
@@ -1229,6 +1235,37 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
         api.patch(`/api/tasks/${taskId}`, { agentRole }).catch(() => {/* non-fatal */})
       }
 
+      // ── Re-write full cursor workspace (skills, session protocol, active-agent) ──
+      // park_task deletes everything; unpark_task must restore the complete workspace.
+      let workspaceResult = null
+      try {
+        let projectAgentConfig = null
+        try {
+          const projRes = await api.get(`/api/projects/${task.project}`)
+          if (projRes?.success) projectAgentConfig = projRes.data.project?.agentConfig || null
+        } catch { /* non-fatal */ }
+
+        const taskForWorkspace = agentRole ? { ...task, agentRole } : task
+        workspaceResult = writeCursorWorkspace(taskForWorkspace, projectAgentConfig, repoPath || process.cwd())
+
+        // Log injected skills/rules to session timeline
+        // Log each written file to session timeline
+        const writtenFiles = workspaceResult?.written || []
+        for (const filePath of writtenFiles) {
+          const fileName = filePath.split('/').pop().replace(/\.(md|mdc)$/, '')
+          const isSkill  = filePath.includes('/.cursor/skills/')
+          const isRule   = filePath.includes('/.cursor/rules/')
+          const isAgent  = filePath.includes('/.cursor/agents/')
+          const type = isSkill ? 'skill' : isRule ? 'rule' : isAgent ? 'subagent' : 'info'
+          api.post(`/api/tasks/${taskId}/session/log`, {
+            type,
+            name:    fileName,
+            role:    agentRole || null,
+            summary: `📖 Injected at unpark: ${filePath.replace(workspaceResult.repoRoot, '')}`,
+          }).catch(() => {})
+        }
+      } catch { /* non-fatal — workspace restore failure should not block the unpark */ }
+
       // ── #9 Last commit metadata for handoff context ───────────────────────
       const lastCommit = getLastCommitMeta(repoRoot)
 
@@ -1241,21 +1278,30 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
         cursorRules: cursorRulesFile
           ? { restored: true, path: cursorRulesFile, agentRole: agentRole || null }
           : { restored: false },
+        workspace: workspaceResult
+          ? { restored: true, filesCount: workspaceResult.written?.length || 0, files: workspaceResult.written || [] }
+          : { restored: false },
         commentPosted:       true,
         previousDevNotified: true,
         parkNote: task?.parkNote || null,
         message: gitResult?.switched
-          ? `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.`,
+          ? `You are now on branch "${branch}". Cursor workspace restored${agentRole ? ` (role: ${agentRole})` : ''}. Read all skills before editing.`
+          : `Branch switch failed — see git.manualSteps. Cursor workspace restored.`,
+        previouslyClaimed: task?.claimedFiles?.length ? task.claimedFiles : null,
         nextStep: agentRole === 'builder'
-          ? `BUILDER role active. Call claim_files to lock your files before editing.`
+          ? [
+              `BUILDER role active.`,
+              `1. ⚠️ READ all injected skills first (listed in workspace.files) — mandatory before any edits`,
+              `2. Re-claim your files: claim_files(taskId="${taskId}", files=${JSON.stringify(task?.claimedFiles || [])})`,
+              `3. Then continue implementation from where the previous developer left off`,
+            ].join('\n')
           : 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,
+          : `Read all injected skills in workspace.files before making any changes.`,
       })
     }
   )
@@ -1537,52 +1583,92 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
             templates: decompositionTemplates,
           } : null,
           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,
+            !executionPlan.scoutReportPresent
+              ? '⛔ SCOUT REPORT MISSING — Strongly recommended before decomposing. Builders without a scout map will guess at file ownership and produce overlapping work. Call kickoff_task(agentRole="scout", confirmed=true) first.'
+              : null,
+            !executionPlan.readmePresent
+              ? '⛔ NO IMPLEMENTATION PLAN — Builders cannot implement without a spec. Call update_task(readmeMarkdown=...) before decomposing.'
+              : null,
+            subtaskPlan.some(s => !s.files?.length)
+              ? `⚠️  ${subtaskPlan.filter(s => !s.files?.length).map(s => s.title).join(', ')} — no files declared. Every subtask MUST own at least one file to prevent two builders editing the same code.`
+              : null,
           ].filter(Boolean),
+          scoutFirstInstruction: !executionPlan.scoutReportPresent
+            ? `MANDATORY: call scout_task(taskId="${task._id}", confirmed=false) then scout_task(confirmed=true, report="<your findings>") before confirming this decomposition. Do NOT switch agentRole — run scout_task directly as coordinator.`
+            : null,
           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 JSON to parent task
-      const decompositionJson = JSON.stringify(executionPlan, null, 2)
-      try {
-        await api.patch(`/api/tasks/${taskId}`, { decomposition: decompositionJson })
-      } catch { /* non-fatal */ }
-
       // Create real child tasks for each subtask in the plan
+      // Do this BEFORE saving the decomposition JSON so we can embed child task IDs.
       const projectId = task.project?._id || task.project
       const createdTasks = []
+      // Build a map from subtask title → child task info for embedding into executionPlan
+      const childTaskByTitle = {}
+
       for (const s of subtaskPlan) {
         try {
+          // Role → generic role-appropriate skills that any project should have.
+          // We avoid hardcoding third-party skill names (e.g. zop-*) because projects
+          // may not have those configured — the agent would look for files that don't exist.
+          // The project-level agentConfig.skills drive what actually gets written to .cursor/skills/.
+          const ROLE_KIT = {
+            builder:     { skills: { 'run-tests': true, 'commit-conventions': true }, subagents: {}, prompts: {} },
+            scout:       { skills: { 'scout-codebase': true },                        subagents: {}, prompts: {} },
+            reviewer:    { skills: { 'review-checklist': true, 'run-tests': true },   subagents: {}, prompts: {} },
+            coordinator: { skills: { 'scout-codebase': true, 'run-tests': true },     subagents: {}, prompts: {} },
+          }
+          const childKit = ROLE_KIT[s.role] || ROLE_KIT.builder
+
           const childRes = await api.post(`/api/projects/${projectId}/tasks`, {
             title:          `[${s.role.toUpperCase()}] ${s.title}`,
             description:    s.description,
             readmeMarkdown: [
               `## Role: ${s.role}`,
+              `## Parent task: ${task.key} — ${task.title}`,
               `## Description\n${s.description}`,
               s.files?.length ? `## Files to claim at kickoff\n${s.files.map(f => `- \`${f}\``).join('\n')}` : '',
-              s.dependsOn?.length ? `## Depends on\n${s.dependsOn.map(d => `- ${d}`).join('\n')}` : '',
+              s.dependsOn?.length ? `## Depends on (must complete before this starts)\n${s.dependsOn.map(d => `- ${d}`).join('\n')}` : '',
+              `## Skills to read BEFORE editing\nRead every .md file in .cursor/skills/ that was written at kickoff.`,
+              `## After finishing\nCall park_task or raise_pr, then update the parent task (${task.key}) subtask checklist.`,
             ].filter(Boolean).join('\n\n'),
-            column:      'todo',
-            priority:    task.priority || 'medium',
-            taskType:    s.role === 'reviewer' ? 'feature' : (task.taskType || 'feature'),
-            parentTask:  taskId,
+            column:         'todo',
+            priority:       task.priority || 'medium',
+            taskType:       s.role === 'reviewer' ? 'feature' : (task.taskType || 'feature'),
+            parentTask:     taskId,
             suggestedFiles: s.files || [],
+            agentKitOverrides: childKit,
           })
           if (childRes?.success) {
-            createdTasks.push({
+            const childInfo = {
               taskId:  childRes.data?.task?._id,
               taskKey: childRes.data?.task?.key,
               title:   childRes.data?.task?.title,
               role:    s.role,
               files:   s.files,
-            })
+            }
+            createdTasks.push(childInfo)
+            childTaskByTitle[s.title] = childInfo
           }
         } catch { /* non-fatal — continue creating remaining tasks */ }
       }
 
+      // Embed child task IDs into the execution plan so get_parallel_kickoffs can route
+      // each builder to their own child task (not the parent task).
+      executionPlan.subtasks = executionPlan.subtasks.map(s => ({
+        ...s,
+        childTaskId:  childTaskByTitle[s.title]?.taskId  || null,
+        childTaskKey: childTaskByTitle[s.title]?.taskKey || null,
+      }))
+
+      // Save decomposition JSON to parent task — now includes child task IDs
+      const decompositionJson = JSON.stringify(executionPlan, null, 2)
+      try {
+        await api.patch(`/api/tasks/${taskId}`, { decomposition: decompositionJson })
+      } catch { /* non-fatal */ }
+
       return text({
         decomposed: true,
         taskKey:    task.key,
@@ -1603,16 +1689,17 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
     `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.
+Coordinators call this directly — do NOT switch agentRole to "scout" to call it.
+Agents with agentRole="scout" also call this as their primary work tool.
 
 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)
+- decompose_task (warns if missing, refuses to decompose without one)
+- get_agent_context (automatically included in builder system prompt)
+- kickoff_task (surfaced as part of the builder brief)
 
 Scouts MUST NOT modify any source code files or create branches.`,
     {
@@ -1929,11 +2016,24 @@ This tool posts a comment on the task (for visibility in the app) and notifies a
       trackTaskActivity(taskId, 'request_human_input')
       await api.post(`/api/tasks/${taskId}/ask-human`, { question, context, type }).catch(() => null)
 
+      // Detect whether we're likely running as a Cursor Background Agent (non-interactive).
+      // Background agents cannot receive chat replies — the human must check the InternalTool
+      // task comments to see the question, then the agent should use a safe default and move on.
+      // We surface this explicitly so the agent does not pause indefinitely.
+      const isBackgroundLikely = !process.stdin.isTTY
+
       const typeLabel = type === 'approval' ? '🔐 APPROVAL NEEDED' : type === 'ambiguity' ? '🤔 AMBIGUITY — YOUR DECISION' : '❓ QUESTION FOR YOU'
       return text({
         [typeLabel]: question,
         ...(context ? { context } : {}),
-        instruction: 'Please reply in this Cursor chat. I will use your answer to continue. Do NOT proceed until you reply.',
+        backgroundAgentWarning: isBackgroundLikely
+          ? 'You appear to be running as a Background Agent (no interactive TTY). The question has been posted as a task comment and the developer has been notified. Since there is no interactive chat channel, DO NOT wait indefinitely. Use the safest autonomous default and proceed, then note your decision in a log_session_event call.'
+          : null,
+        instruction: isBackgroundLikely
+          ? 'Background agent mode: proceed with the safest default decision. Log your choice with log_session_event(type="info", name="autonomous-decision", summary="<what you decided and why>").'
+          : 'Please reply in this Cursor chat. I will use your answer to continue. Do NOT proceed until you reply.',
+        taskCommentPosted: true,
+        developerNotified: true,
       })
     }
   )
@@ -2069,13 +2169,24 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
         return taskOverride !== undefined ? taskOverride : s.enabled !== false
       })
 
-      // Role-based relevance filter: each role only gets skills that match its job
+      // Role-based relevance filter: each role only gets skills that match its job.
+      // Keywords for each role are matched against skill name + description.
       const ROLE_SKILL_KEYWORDS = {
-        builder:     ['test', 'run', 'build', 'lint', 'commit', 'style', 'deploy', 'migration', 'seed'],
-        scout:       ['scout', 'codebase', 'explore', 'map', 'analyze', 'read'],
-        reviewer:    ['review', 'security', 'audit', 'test', 'quality'],
-        coordinator: ['decompose', 'plan', 'coordinate', 'parallel'],
-      }
+        builder:     ['test', 'run', 'build', 'lint', 'commit', 'style', 'deploy', 'migration', 'seed',
+                      'implement', 'feature', 'api', 'endpoint', 'component', 'service', 'hook',
+                      'util', 'helper', 'create', 'update', 'delete', 'fix', 'patch', 'convention'],
+        scout:       ['scout', 'codebase', 'explore', 'map', 'analyze', 'read', 'report',
+                      'find', 'locate', 'search', 'survey', 'inventory', 'document', 'recon'],
+        reviewer:    ['review', 'security', 'audit', 'test', 'quality', 'check', 'verify',
+                      'validate', 'pr', 'pull', 'lint', 'coverage', 'performance', 'checklist'],
+        coordinator: ['decompose', 'plan', 'coordinate', 'parallel', 'orchestrate', 'manage',
+                      'delegate', 'assign', 'breakdown', 'workflow', 'group', 'subtask'],
+      }
+      // Skills that don't match any role-specific keyword are treated as universal
+      // (e.g. 'session-start', 'workflow-guide') and given to all roles.
+      const ALL_ROLE_KEYWORDS = Object.values(ROLE_SKILL_KEYWORDS).flat()
+      const isRoleSpecific = (s) => ALL_ROLE_KEYWORDS.some(kw => `${s.name} ${s.description || ''}`.toLowerCase().includes(kw))
+
       const roleKeywords = effectiveRole ? (ROLE_SKILL_KEYWORDS[effectiveRole] || []) : []
 
       // Also use the task type's suggestedSkills list for relevance
@@ -2088,11 +2199,13 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
       })()
 
       const relevantSkills = enabledSkills.filter(s => {
-        // Always include explicitly overridden-true skills
+        // Always include explicitly overridden-true skills (task-level config)
         if (taskSkillOverrides[s.name] === true) return true
-        // Include if skill name matches task type's suggested list
+        // Always include task-type suggested skills
         if (taskTypeSkills.includes(s.name)) return true
-        // Include if skill name/description matches role keywords
+        // Include universal skills (don't match any role's keywords — generic helpers)
+        if (!isRoleSpecific(s)) return true
+        // Include if skill name/description matches this role's keywords
         const haystack = `${s.name} ${s.description || ''}`.toLowerCase()
         return roleKeywords.some(kw => haystack.includes(kw))
       })
@@ -2260,9 +2373,14 @@ Returns reviewId — save it and pass it to merge_pr to prove semantic review ha
       if (!prNumber) return errorText('No PR linked to this task. Call raise_pr first.')
 
       // Enforce that analysisPoints are specific — reject obviously generic ones
-      const genericPhrases = ['looks good', 'lgtm', 'code is fine', 'no issues', 'all good', 'seems correct']
+      const genericPhrases = [
+        'looks good', 'lgtm', 'code is fine', 'no issues', 'all good', 'seems correct',
+        'looks great', 'looks fine', 'all correct', 'perfect', 'seems fine', 'this is fine',
+        'this is correct', 'no problems', 'nothing wrong', 'good job', 'well done',
+        'approved', 'ship it', 'looks right', 'seems right', 'everything is fine',
+      ]
       const tooGeneric = analysisPoints.filter(p =>
-        p.trim().length < 20 || genericPhrases.some(g => p.toLowerCase().includes(g))
+        p.trim().length < 25 || genericPhrases.some(g => p.toLowerCase().includes(g))
       )
       if (tooGeneric.length > 0) {
         return text({
@@ -2406,8 +2524,15 @@ The task moves to Done automatically via the GitHub webhook.`,
         { check: `CI checks (${checks?.total ?? 0} runs)`,
           pass: skipChecks ? null : (checks?.allPassed ?? null),
           note: skipChecks ? 'Skipped by request' : checks?.anyFailed ? 'Some checks failed' : checks?.allPassed ? 'All passing' : 'No checks found' },
-        { check: 'Has at least one approval', pass: pr.approvals > 0,
-          note: pr.approvals === 0 ? 'No approvals yet — consider running post_pr_review first' : `${pr.approvals} approval(s)` },
+        // Hard block: PR must have at least one GitHub approval OR a sessionReview from this session.
+        // A sessionReview alone (reviewer = author) is not enough — someone independent must approve.
+        // Exception: if there's a sessionReview AND existing approvals, both gates are satisfied.
+        { check: 'Has at least one GitHub approval', pass: pr.approvals > 0,
+          note: pr.approvals === 0
+            ? hasSessionReview
+              ? '⚠️ Self-review only — no independent GitHub approval. Ask a teammate to approve on GitHub before merging.'
+              : 'No approvals. Call review_pr → post_pr_review, then ask a reviewer to approve on GitHub.'
+            : `${pr.approvals} GitHub approval(s)` },
       ]
 
       const hardBlocks = safetyChecks.filter(c => c.pass === false && c.check !== `CI checks (${checks?.total ?? 0} runs)`)
@@ -2456,14 +2581,17 @@ The task moves to Done automatically via the GitHub webhook.`,
         return text({ merged: true, message: 'PR was already merged.' })
       }
 
+      // Move task to done immediately — don't rely solely on the GitHub webhook
+      try { await api.post(`/api/tasks/${taskId}/move`, { column: 'done', toIndex: 0 }) } catch { /* webhook fallback */ }
+
       return text({
         merged:      true,
         sha:         mergeRes.data?.sha,
         prNumber,
         taskKey:     task.key,
         mergeMethod,
-        message:     `✅ PR #${prNumber} merged via ${mergeMethod}. Task "${task.key}" will move to Done automatically.`,
-        nextStep:    `The GitHub webhook will update the board. If the task doesn't move to Done within a minute, call update_task with column="done" manually.`,
+        message:     `✅ PR #${prNumber} merged via ${mergeMethod}. Task "${task.key}" moved to Done.`,
+        nextStep:    `Run deleteCursorWorkspace cleanup if any agent files remain, then pick up your next task.`,
       })
     }
   )
@@ -2664,6 +2792,34 @@ Flow:
         api.patch(`/api/tasks/${taskId}`, { agentRole }).catch(() => {/* non-fatal */})
       }
 
+      // Re-write full cursor workspace (skills, session protocol, active-agent)
+      // resume_task is equivalent to unpark_task for workspace purposes.
+      let workspaceResult = null
+      try {
+        let projectAgentConfig = null
+        try {
+          const projRes = await api.get(`/api/projects/${task.project}`)
+          if (projRes?.success) projectAgentConfig = projRes.data.project?.agentConfig || null
+        } catch { /* non-fatal */ }
+
+        const taskForWorkspace = agentRole ? { ...task, agentRole } : task
+        workspaceResult = writeCursorWorkspace(taskForWorkspace, projectAgentConfig, repoPath || process.cwd())
+
+        // Log injected files to session timeline
+        const writtenFiles = workspaceResult?.written || []
+        for (const filePath of writtenFiles) {
+          const fileName = filePath.split('/').pop().replace(/\.(md|mdc)$/, '')
+          const isSkill  = filePath.includes('/.cursor/skills/')
+          const isRule   = filePath.includes('/.cursor/rules/')
+          const isAgent  = filePath.includes('/.cursor/agents/')
+          const type = isSkill ? 'skill' : isRule ? 'rule' : isAgent ? 'subagent' : 'info'
+          api.post(`/api/tasks/${taskId}/session/log`, {
+            type, name: fileName, role: agentRole || null,
+            summary: `📖 Injected at resume: ${filePath.replace(workspaceResult.repoRoot, '')}`,
+          }).catch(() => {})
+        }
+      } catch { /* non-fatal */ }
+
       // Last commit metadata
       const lastCommit = getLastCommitMeta(repoRoot)
 
@@ -2679,11 +2835,20 @@ Flow:
         cursorRules: cursorRulesFile
           ? { restored: true, path: cursorRulesFile, agentRole: agentRole || null }
           : { restored: false },
+        workspace: workspaceResult
+          ? { restored: true, filesCount: workspaceResult.written?.length || 0, files: workspaceResult.written || [] }
+          : { restored: false },
+        previouslyClaimed: task?.claimedFiles?.length ? task.claimedFiles : null,
         message: gitResult?.switched || gitResult?.alreadyOnBranch
-          ? `You are on branch "${branch}". Ready to resume coding${agentRole ? ` as ${agentRole}` : ''}.`
+          ? `You are on branch "${branch}". Cursor workspace restored${agentRole ? ` as ${agentRole}` : ''}. Read all skills before editing.`
           : `Branch switch failed — see git.manualSteps.`,
         nextStep: agentRole === 'builder'
-          ? `BUILDER role active. Call claim_files to lock your files before editing.`
+          ? [
+              `BUILDER role active.`,
+              `1. ⚠️ READ all injected skills (workspace.files) — mandatory before any edits`,
+              `2. Re-claim files: claim_files(taskId="${taskId}", files=${JSON.stringify(task?.claimedFiles || [])})`,
+              `3. Continue implementation from where you left off`,
+            ].join('\n')
           : agentRole === 'scout'
           ? `SCOUT role active. Read-only mode — map the codebase and save findings with update_task(scoutReport=...).`
           : agentRole === 'coordinator'
@@ -2693,8 +2858,8 @@ Flow:
           : task.column === 'in_review'
           ? `Task is in review. Check if PR feedback needs addressing — call fix_pr_feedback if needed.`
           : task.parkNote?.remaining
-            ? `Remaining: ${task.parkNote.remaining}`
-            : `Continue coding on "${branch}".`,
+            ? `Remaining: ${task.parkNote.remaining}. Read workspace.files skills first.`
+            : `Continue coding on "${branch}". Read workspace.files skills first.`,
       })
     }
   )
@@ -2762,21 +2927,36 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
       const subtasks   = dec.subtasks || []
       const execOrder  = dec.executionOrder || []
 
-      // Determine which group to run next: first group that has at least one
-      // subtask not yet reflected in the board subtasks as done.
+      // Dual-signal completion check — mirrors wait_for_group logic.
+      // A subtask is "done" if EITHER the parent checklist ticks it OR its child task
+      // column is done/in_review. This prevents re-emitting builder prompts for subtasks
+      // that are already finished but whose builder skipped update_task on the parent.
       const boardSubtasks = task.subtasks || []
-      // Board subtask titles may carry a role prefix like "[BUILDER] Auth hardening..."
-      // Match on bare title OR prefixed title
-      const isDone = (title) => boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
+      const checklistDone = (title) => boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
+      const childColumnDoneCache = {}
+      const isSubtaskDone = async (title) => {
+        if (checklistDone(title)) return true
+        const entry = subtasks.find(s => s.title === title)
+        if (!entry?.childTaskId) return false
+        if (childColumnDoneCache[entry.childTaskId] !== undefined) return childColumnDoneCache[entry.childTaskId]
+        try {
+          const r = await api.get(`/api/tasks/${entry.childTaskId}`)
+          const col = r?.data?.task?.column
+          const done = col === 'done' || col === 'in_review'
+          childColumnDoneCache[entry.childTaskId] = done
+          return done
+        } catch { return false }
+      }
 
       let nextGroup = null
       let nextGroupIndex = -1
       for (let i = 0; i < execOrder.length; i++) {
         const group = execOrder[i]
-        const allDone = group.every(t => isDone(t))
+        const allDone = (await Promise.all(group.map(t => isSubtaskDone(t)))).every(Boolean)
         if (!allDone) {
           // Also check all prior groups are fully done (respects dependsOn)
-          const priorAllDone = execOrder.slice(0, i).every(g => g.every(t => isDone(t)))
+          const priorResults = await Promise.all(execOrder.slice(0, i).map(g => Promise.all(g.map(t => isSubtaskDone(t)))))
+          const priorAllDone = priorResults.every(g => g.every(Boolean))
           if (priorAllDone) {
             nextGroup = group
             nextGroupIndex = i + 1
@@ -2792,8 +2972,9 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
         })
       }
 
-      // Only kick off subtasks that aren't done yet
-      const pendingInGroup = nextGroup.filter(t => !isDone(t))
+      // Only kick off subtasks that aren't done yet (use cached dual-signal results)
+      const pendingInGroup = (await Promise.all(nextGroup.map(async t => ({ t, done: await isSubtaskDone(t) }))))
+        .filter(r => !r.done).map(r => r.t)
       const parallelCount  = pendingInGroup.length
       const isParallel     = parallelCount > 1
 
@@ -2811,35 +2992,42 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
       const kickoffs = pendingInGroup.map((subtaskTitle, i) => {
         const st = subtasks.find(s => s.title === subtaskTitle) || { title: subtaskTitle, role: 'builder', files: [], description: '' }
         const filesArg = (st.files || []).map(f => `"${f}"`).join(', ')
-        const fileList = (st.files || []).map(f => `  - \`${f}\``).join('\n')
-
-        // Prompt is a short, direct imperative Cursor immediately executes.
-        // Key: start with "Use the InternalTool MCP" so Cursor knows to call tools.
-        // Avoid pseudocode like fn(arg=val) — use plain English with quoted values.
         const fileListPlain = (st.files || []).join(', ')
+
+        // Use the child task ID if it was embedded at decompose time.
+        // Builders must work on their own child task, not the parent task.
+        // The parent task ID is only used to update the parent checklist when done.
+        const childTaskId  = st.childTaskId  || taskId   // fallback to parent if missing (old decompositions)
+        const childTaskKey = st.childTaskKey || task.key
+        const usingChildTask = !!(st.childTaskId)
+
         const prompt = [
-          `Use the InternalTool MCP tools to implement subtask "${st.title}" for task ${task.key}.`,
+          `Use the InternalTool MCP tools to implement subtask "${st.title}".`,
+          `Your task: ${childTaskKey} (child of ${task.key})`,
+          usingChildTask ? `Child task ID: "${childTaskId}" — use this for ALL MCP calls below.` : `⚠️ No child task ID found — using parent task ID "${taskId}" as fallback.`,
           ``,
           `Do these steps immediately in order — do not ask for confirmation, do not skip any step:`,
           ``,
-          `1. Call log_session_event with taskId "${taskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} started: ${st.title}"`,
-          `2. Call kickoff_task with taskId "${taskId}", agentRole "builder", confirmed true`,
-          `3. Call claim_files with taskId "${taskId}" and files [${filesArg}]`,
-          `4. Call get_agent_context with taskId "${taskId}" to read the full task plan and suggested skills`,
+          `1. Call log_session_event with taskId "${childTaskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} started: ${st.title}"`,
+          `2. Call kickoff_task with taskId "${childTaskId}", agentRole "builder", confirmed true`,
+          `   (This writes your cursor workspace. READ every file in .cursor/skills/ before editing anything.)`,
+          `3. Call claim_files with taskId "${childTaskId}" and files [${filesArg}]`,
+          `4. Call get_agent_context with taskId "${childTaskId}" and role "builder" — read the full plan and skills`,
           `5. Implement the subtask: ${st.description || st.title}`,
           `   - You may ONLY modify these files: ${fileListPlain}`,
-          `   - Do NOT touch any other file`,
-          `   - Follow any skills listed in get_agent_context suggestedSkills`,
-          `6. Run npm test — all tests must pass before continuing`,
-          `7. Call commit_helper with taskId "${taskId}"`,
-          `8. Call update_task with taskId "${taskId}" and mark the subtask "${st.title}" as done`,
-          `9. Call resume_task with taskId "${taskId}", agentRole "reviewer", confirmed true — transition to reviewer role`,
-          `10. Call log_session_event with taskId "${taskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} finished: ${st.title}"`,
+          `   - Do NOT touch any other file — other builders own those`,
+          `   - Follow skills listed in get_agent_context`,
+          `6. Run the project test suite — all tests must pass before continuing`,
+          `7. Call commit_helper with taskId "${childTaskId}"`,
+          `8. Call raise_pr with taskId "${childTaskId}" and projectId "${task.project?._id || task.project}"`,
+          `9. Call update_task with taskId "${taskId}" (parent) and mark the subtask "${st.title}" as done in the subtasks checklist`,
+          `10. Call log_session_event with taskId "${childTaskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} finished: ${st.title}"`,
           ``,
-          `You are builder ${i + 1} of ${parallelCount} running in parallel. Another builder is working on different files at the same time.`,
+          `You are builder ${i + 1} of ${parallelCount} running in parallel. Other builders are working on different files simultaneously — do NOT touch their files.`,
+          `If you finish early, call park_task on your child task and notify the coordinator.`,
         ].join('\n')
 
-        return { subtask: st.title, role: st.role || 'builder', files: st.files || [], prompt }
+        return { subtask: st.title, role: st.role || 'builder', files: st.files || [], childTaskId, childTaskKey, prompt }
       })
 
       // Write each builder prompt as a Cursor Background Agent file in .cursor/agents/
@@ -2856,14 +3044,14 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
 
         const agentFileContent = [
           `---`,
-          `description: Builder ${i + 1} of ${parallelCount} — ${k.subtask} (${task.key})`,
+          `description: Builder ${i + 1} of ${parallelCount} — ${k.subtask} (${k.childTaskKey || task.key})`,
           `---`,
           ``,
           k.prompt,
         ].join('\n')
 
         writeFileSync(filePath, agentFileContent, 'utf8')
-        writtenFiles.push({ index: i + 1, file: `.cursor/agents/${fileName}`, subtask: k.subtask })
+        writtenFiles.push({ index: i + 1, file: `.cursor/agents/${fileName}`, subtask: k.subtask, childTaskId: k.childTaskId, childTaskKey: k.childTaskKey })
       })
 
       // Build the human-facing instruction block
@@ -2875,13 +3063,11 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
         `  2. You'll see ${parallelCount} new builder agent(s) listed`,
         `  3. Click "Start" for each one — they run in parallel automatically`,
         ``,
-        ...writtenFiles.map(f => `  • Builder ${f.index}: "${f.subtask}"  →  ${f.file}`),
+        ...writtenFiles.map(f => `  • Builder ${f.index}: "${f.subtask}" [${f.childTaskKey || 'parent'}]  →  ${f.file}`),
         ``,
-        `Each builder calls kickoff_task → claim_files → implements → runs tests → commits.`,
+        `Each builder kicks off their own child task → claims files → implements → tests → commits → raises PR.`,
         `They work on different files simultaneously — no need to wait for one before starting the other.`,
-        ``,
-        `After all builders finish, come back here and call get_parallel_kickoffs again`,
-        `to get the next group's prompts.`,
+        `When all builders in this group are done, call get_parallel_kickoffs again for the next group.`,
       ].join('\n')
 
       return text({
@@ -2920,6 +3106,23 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
       const deadline = Date.now() + timeoutMs
       let attempts   = 0
 
+      // Helper: check if a subtask title is done via parent checklist
+      const isCheckedDone = (boardSubtasks, title) =>
+        boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
+
+      // Helper: check if a child task is done via its board column.
+      // A child task is considered done when it reaches 'done' or 'in_review'
+      // (builder finished + raised PR). This is the reliable signal — builders
+      // may skip calling update_task on the parent but they always raise_pr.
+      const isChildTaskDone = async (childTaskId) => {
+        if (!childTaskId) return false
+        try {
+          const res = await api.get(`/api/tasks/${childTaskId}`)
+          const col = res?.data?.task?.column
+          return col === 'done' || col === 'in_review'
+        } catch { return false }
+      }
+
       while (Date.now() < deadline) {
         attempts++
         const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
@@ -2932,27 +3135,43 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
           return errorText('Decomposition JSON is malformed.')
         }
 
-        const execOrder  = dec.executionOrder || []
+        const execOrder   = dec.executionOrder || []
+        const decSubtasks = dec.subtasks || []
         const targetGroup = execOrder[groupIndex - 1]
         if (!targetGroup) return errorText(`Group ${groupIndex} does not exist. Decomposition has ${execOrder.length} group(s).`)
 
         const boardSubtasks = task.subtasks || []
-        const isDone = (title) => boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
 
-        const doneTitles    = targetGroup.filter(t => isDone(t))
-        const pendingTitles = targetGroup.filter(t => !isDone(t))
+        // Dual-signal completion: parent checklist tick OR child task column (done/in_review).
+        // This prevents the coordinator from stalling when a builder skips update_task on the parent.
+        const statusPerTitle = await Promise.all(
+          targetGroup.map(async (title) => {
+            const checklist = isCheckedDone(boardSubtasks, title)
+            if (checklist) return { title, done: true, via: 'checklist' }
+            // Look up child task ID from the embedded decomposition
+            const decEntry = decSubtasks.find(s => s.title === title)
+            const childDone = decEntry?.childTaskId
+              ? await isChildTaskDone(decEntry.childTaskId)
+              : false
+            return { title, done: childDone, via: childDone ? 'child_task_column' : 'pending', childTaskId: decEntry?.childTaskId || null }
+          })
+        )
+
+        const doneTitles    = statusPerTitle.filter(s => s.done)
+        const pendingTitles = statusPerTitle.filter(s => !s.done)
 
         if (pendingTitles.length === 0) {
           return text({
-            done:     true,
-            group:    groupIndex,
-            subtasks: targetGroup,
+            done:       true,
+            group:      groupIndex,
+            subtasks:   targetGroup,
             done_count: doneTitles.length,
+            completion: doneTitles.map(s => ({ title: s.title, via: s.via })),
             attempts,
             message: `✅ All ${targetGroup.length} subtask(s) in Group ${groupIndex} are done after ${attempts} poll(s).`,
             nextStep: groupIndex < execOrder.length
               ? `Call get_parallel_kickoffs with taskId="${taskId}" to get Group ${groupIndex + 1}'s builder prompts.`
-              : 'All groups complete. Run final tests then call raise_pr.',
+              : 'All groups complete. Run final tests then call raise_pr on the parent task.',
           })
         }
 
@@ -2975,10 +3194,17 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
       const finalTask = finalRes?.data?.task
       let finalDec
       try { finalDec = JSON.parse(finalTask?.decomposition || '{}') } catch { finalDec = {} }
-      const finalGroup   = (finalDec.executionOrder || [])[groupIndex - 1] || []
-      const finalBoard   = finalTask?.subtasks || []
-      const finalIsDone  = (t) => finalBoard.some(s => s.done && (s.title === t || s.title.endsWith(t)))
-      const stillPending = finalGroup.filter(t => !finalIsDone(t))
+      const finalGroup     = (finalDec.executionOrder || [])[groupIndex - 1] || []
+      const finalDecSubs   = finalDec.subtasks || []
+      const finalBoard     = finalTask?.subtasks || []
+      const stillPending   = await Promise.all(
+        finalGroup.map(async (title) => {
+          if (isCheckedDone(finalBoard, title)) return null
+          const entry = finalDecSubs.find(s => s.title === title)
+          if (entry?.childTaskId && await isChildTaskDone(entry.childTaskId)) return null
+          return title
+        })
+      ).then(r => r.filter(Boolean))
 
       return text({
         timedOut:   true,
@@ -2986,7 +3212,7 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
         pending:    stillPending,
         attempts,
         message:    `⏱ Timed out after ${attempts} poll(s). ${stillPending.length} subtask(s) still pending: ${stillPending.join(', ')}`,
-        hint:       'Check the Background Agents panel — a builder may have crashed. Call wait_for_group again to resume waiting, or proceed manually.',
+        hint:       'Check the Background Agents panel — a builder may have crashed or skipped raise_pr. Call wait_for_group again to resume, or proceed manually if the work is done.',
       })
     }
   )
@@ -3808,6 +4034,18 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         const hasParallelLang   = /parallel|simultaneously|independent(ly)?|at the same time/i.test(readme)
         const hasSequentialLang = /step\s*\d|first[\s,].*then|depends\s+on|before.*after/i.test(readme)
 
+        // Count how many distinct codebase layers are touched: routes, models, components, services, tests, migrations, seeds, utils, middleware, hooks
+        const LAYER_PATTERNS = ['route', 'model', 'component', 'service', 'test', 'migration', 'seed', 'util', 'middleware', 'hook', 'schema', 'store', 'context', 'controller', 'resolver']
+        const layersHit = LAYER_PATTERNS.filter(l => new RegExp(l, 'i').test(readme)).length
+
+        // Count explicit numbered steps / subtasks in the plan (indicates decomposability)
+        const numberedSteps = (readme.match(/^\s*\d+\.\s/gm) || []).length
+
+        // Full-stack scope: touches both frontend and backend layers
+        const hasFrontend = /component|hook|store|context|jsx|tsx|vue|react|svelte|ui|page|view/i.test(readme)
+        const hasBackend  = /route|controller|model|schema|service|middleware|api|endpoint|database|migration/i.test(readme)
+        const isFullStack = hasFrontend && hasBackend
+
         if (readmeLen > 800)       { complexityScore += 2; complexitySignals.push(`long plan (${readmeLen} chars)`) }
         else if (readmeLen > 300)  { complexityScore += 1; complexitySignals.push(`medium plan (${readmeLen} chars)`) }
         if (sections > 3)          { complexityScore += 2; complexitySignals.push(`${sections} README sections`) }
@@ -3816,13 +4054,23 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         else if (fileMentions > 2) { complexityScore += 1; complexitySignals.push(`${fileMentions} files mentioned`) }
         if (hasParallelLang)       { complexityScore += 1; complexitySignals.push('parallel workstreams mentioned') }
         if (hasSequentialLang)     { complexityScore += 1; complexitySignals.push('sequential steps mentioned') }
+        if (layersHit >= 4)        { complexityScore += 2; complexitySignals.push(`${layersHit} codebase layers touched`) }
+        else if (layersHit >= 2)   { complexityScore += 1; complexitySignals.push(`${layersHit} codebase layers touched`) }
+        if (numberedSteps >= 5)    { complexityScore += 2; complexitySignals.push(`${numberedSteps} explicit steps in plan`) }
+        else if (numberedSteps >= 3) { complexityScore += 1; complexitySignals.push(`${numberedSteps} steps in plan`) }
+        if (isFullStack)           { complexityScore += 1; complexitySignals.push('full-stack scope (frontend + backend)') }
       }
 
+      // Score from task-level signals (subtask count from board)
+      const existingSubtaskCount = (task.subtasks || []).length
+      if (existingSubtaskCount >= 5)    { complexityScore += 2; complexitySignals.push(`${existingSubtaskCount} subtasks already defined`) }
+      else if (existingSubtaskCount >= 3) { complexityScore += 1; complexitySignals.push(`${existingSubtaskCount} subtasks defined`) }
+
       const titleLower = task.title.toLowerCase()
-      const complexTitleWords = ['implement', 'build', 'add', 'create', 'integrate', 'refactor', 'migrate', 'redesign']
-      const simpleTitleWords  = ['fix', 'patch', 'typo', 'bump', 'revert']
-      if (complexTitleWords.some(w => titleLower.includes(w))) complexityScore += 1
-      if (simpleTitleWords.some(w =>  titleLower.includes(w))) complexityScore -= 1
+      const complexTitleWords = ['implement', 'build', 'add', 'create', 'integrate', 'refactor', 'migrate', 'redesign', 'replace', 'overhaul', 'rearchitect']
+      const simpleTitleWords  = ['fix', 'patch', 'typo', 'bump', 'revert', 'update', 'rename', 'remove']
+      if (complexTitleWords.some(w => titleLower.includes(w))) { complexityScore += 1; complexitySignals.push('complex verb in title') }
+      if (simpleTitleWords.some(w =>  titleLower.includes(w))) { complexityScore -= 1 }
       complexityScore = Math.max(0, complexityScore)
 
       // ── Determine recommended flow ────────────────────────────────────────────
@@ -3888,6 +4136,27 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         }
       }
 
+      // ── Fetch team landscape for the preview so agent sees conflicts before committing ──
+      let previewTeamContext = null
+      try {
+        const previewTreeRes = await api.get(`/api/projects/${task.project}/github/git-tree`).catch(() => null)
+        if (previewTreeRes?.success) {
+          const branches = previewTreeRes.data?.branches || []
+          const otherActive = branches.filter(b => b.taskId !== String(task._id) && !b.branchError)
+          if (otherActive.length > 0) {
+            previewTeamContext = {
+              activeBranches: otherActive.map(b => ({
+                taskKey:   b.taskKey,
+                assignees: (b.assignees || []).map(a => a.name).join(', ') || 'unassigned',
+                files:     b.claimedFiles || [],
+                behindBy:  b.compare?.behindBy ?? null,
+              })),
+              warning: `⚠️  ${otherActive.length} other branch(es) active in this project. Check for file overlaps before claiming files.`,
+            }
+          }
+        }
+      } catch { /* non-fatal */ }
+
       // ── 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')
@@ -4120,6 +4389,7 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
               mainWarning: `⚠️  Your workspace is ${localGitState.mainBehindBy} commit(s) behind origin/${localGitState.defaultBranch}. Run: git pull origin ${localGitState.defaultBranch} before creating a branch.`,
             }),
           } : null,
+          teamLandscape: previewTeamContext,
           requiresConfirmation: true,
           message: approvalBlocks
             ? `Read the plan above, then follow workflowRoadmap — approval is required before you can branch and start coding.`
@@ -4471,21 +4741,85 @@ After \`request_human_input\`: STOP, show the question in chat, wait for reply,
           scoutFirst:        taskTypeCfg.scoutFirst,
           typeRulesInjected: !!typeExtraRules,
         } : null,
-        nextStep: agentRole === 'scout'
-          ? `SCOUT mode. Read the codebase, then save findings with update_task(scoutReport=...). Do NOT modify files.`
-          : agentRole === 'coordinator'
-          ? `COORDINATOR mode. Read the README, then call decompose_task to split work into parallel/sequential subtasks with file ownership.`
-          : agentRole === 'builder'
-          ? `BUILDER mode. Call claim_files first, then start coding on "${alreadyHasBranch ? task.github.headBranch : suggestedBranch}".`
-          : agentRole === 'reviewer'
-          ? `REVIEWER mode. Call review_pr to get the diff, then post_pr_review with your analysis.`
-          : recommendedFlow === 'coordinator' && shouldAutoRoute
-          ? `⚡ COMPLEX TASK (score ${complexityScore}): Call kickoff_task with agentRole "coordinator" confirmed true → decompose_task → get_parallel_kickoffs → start builders. DO NOT code directly.`
-          : recommendedFlow === 'single_builder' && shouldAutoRoute
-          ? `🔧 MEDIUM TASK (score ${complexityScore}): Call kickoff_task with agentRole "builder" confirmed true → claim_files → implement → commit → raise_pr.`
-          : alreadyHasBranch
-          ? `SIMPLE TASK (score ${complexityScore}). Branch "${task.github.headBranch}" exists — call claim_files and start coding.`
-          : `SIMPLE TASK (score ${complexityScore}). Call create_branch to create "${suggestedBranch}", then claim_files and code.`,
+        mandatoryWorkflow: (() => {
+          const flow = recommendedFlow  // 'direct' | 'single_builder' | 'coordinator'
+          const role = agentRole || 'builder'
+
+          // ── Coordinator flow ──────────────────────────────────────────────────
+          if (role === 'coordinator') {
+            return {
+              flow: 'coordinator',
+              WARNING: '⛔ COORDINATOR MODE — DO NOT WRITE ANY CODE. Your only job is to plan and delegate.',
+              mandatorySteps: [
+                '1. READ all files in .cursor/skills/ — log each with log_session_event(type="skill", name=<filename>)',
+                '2. Call recall(taskId) to restore memory from previous sessions',
+                '3. Call get_agent_context(taskId, role="coordinator") for the full context',
+                `4. If no scout report exists: call scout_task(taskId="${taskId}", confirmed=false) to get the analysis brief, then scout_task(confirmed=true, report="<findings>") to save it — do NOT switch agentRole to scout`,
+                '5. Call decompose_task(confirmed=false) — preview the subtask breakdown with file ownership',
+                '6. Fix any file overlap conflicts, then call decompose_task(confirmed=true)',
+                '7. Call get_parallel_kickoffs — it writes builder agent files automatically',
+                '8. Tell the user: open Background Agents panel (⌘⇧J) and start each builder',
+                '9. DO NOT start building. DO NOT claim files. DO NOT edit code.',
+              ],
+              blockedUntil: 'decompose_task confirmed=true is called and childTasks are created',
+            }
+          }
+
+          // ── Scout flow ────────────────────────────────────────────────────────
+          if (role === 'scout') {
+            return {
+              flow: 'scout',
+              WARNING: '⛔ SCOUT MODE — READ ONLY. DO NOT write or modify any source file.',
+              mandatorySteps: [
+                '1. READ all files in .cursor/skills/ — log each with log_session_event(type="skill", name=<filename>)',
+                '2. Call recall(taskId) to restore memory from previous sessions',
+                '3. Call scout_task(confirmed=false) to get your analysis brief',
+                '4. Read every relevant source file systematically (routes, models, utils, tests)',
+                '5. Call scout_task(confirmed=true, report="<your findings>") to save the report',
+                '6. DO NOT modify any file. DO NOT create branches. DO NOT commit.',
+              ],
+              blockedUntil: 'scout_task confirmed=true with a non-empty report',
+            }
+          }
+
+          // ── Reviewer flow ─────────────────────────────────────────────────────
+          if (role === 'reviewer') {
+            return {
+              flow: 'reviewer',
+              mandatorySteps: [
+                '1. READ all files in .cursor/skills/ — log each with log_session_event(type="skill", name=<filename>)',
+                '2. Call review_pr — read the FULL diff before forming any opinion',
+                '3. Check every changed file line by line against the implementation plan',
+                '4. Call post_pr_review with verdict, analysisPoints (min 2), and specific file+line comments',
+              ],
+              blockedUntil: 'post_pr_review called with verdict',
+            }
+          }
+
+          // ── Builder flow (direct / single_builder / decompose child) ──────────
+          const inDecomposeFlow = !!(task.decomposition?.trim())
+          return {
+            flow: inDecomposeFlow ? 'decompose_builder' : flow,
+            SKILLS_GATE: '⛔ DO NOT EDIT ANY FILE until all steps 1–3 are complete.',
+            mandatorySteps: [
+              '1. READ all files in .cursor/skills/ — log each: log_session_event(taskId, type="skill", name=<skill-name>, role="builder")',
+              '2. Call recall(taskId) to restore memory — check for prior session findings',
+              '3. Call get_agent_context(taskId, role="builder") — read implementation plan + claimed files',
+              alreadyHasBranch
+                ? `4. You are on branch "${task.github.headBranch}" — run: git pull origin ${task.github.headBranch}`
+                : `4. Call create_branch — creates "${suggestedBranch}" and moves task to in_progress`,
+              '5. Call claim_files with your exact file list — REQUIRED before editing',
+              '6. Implement the feature following the plan. Run tests after each logical unit.',
+              '7. Call commit_helper to stage and commit with a conventional message',
+              '8. Call raise_pr when all subtasks are done and tests pass',
+            ],
+            blockedUntil: 'Skills read (step 1), memory recalled (step 2), files claimed (step 5)',
+            inDecomposeFlow,
+            decomposeNote: inDecomposeFlow
+              ? '⚡ This is a PARALLEL BUILD. Only edit your claimed files. Do NOT touch files owned by other subtasks.'
+              : null,
+          }
+        })(),
       })
     }
   )
@@ -4744,15 +5078,54 @@ IMPORTANT — what to write in "summary":
 
   server.tool(
     'decide_task_approval',
-    'Approve or reject a specific approval request by approvalId. Only the designated reviewer can call this.',
+    `Approve or reject a specific approval request by approvalId. Only the designated reviewer can call this.
+
+BEFORE calling with a decision, review the plan:
+- Read the plan summary returned by this tool (confirmed=false)
+- Read the task comments for any context from the submitter
+- Check the implementation plan for completeness, correctness, and feasibility
+- Approve if the plan is clear and actionable; reject with a specific note explaining what needs to change
+
+Set confirmed=false first to read the plan, then call again with confirmed=true and your decision.`,
     {
       taskId:     z.string().describe("Task's MongoDB ObjectId"),
       approvalId: z.string().describe("Approval request's MongoDB ObjectId (from the task's approvals array)"),
-      decision:   z.enum(['approve', 'reject']),
-      note:       z.string().optional().describe('Reason for the decision'),
+      decision:   z.enum(['approve', 'reject']).optional().describe('Your decision — omit to just preview the plan'),
+      note:       z.string().optional().describe('Reason for the decision (required on reject, recommended on approve)'),
+      confirmed:  z.boolean().optional().default(false).describe('Set true to submit the decision after reviewing the plan'),
     },
-    async ({ taskId, approvalId, decision, note }) =>
-      call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/decide`, { decision, note }))
+    async ({ taskId, approvalId, decision, note, confirmed = false }) => {
+      // Always fetch task so reviewer can read the plan before deciding
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      const task = taskRes?.data?.task
+      if (!task) return errorText('Task not found')
+
+      const approval = (task.approvals || []).find(a => String(a._id) === String(approvalId))
+      if (!approval) return errorText('Approval request not found on this task')
+
+      if (!confirmed || !decision) {
+        // Preview mode — return plan so reviewer can read it first
+        const planLines = (approval.readme || '').split('\n')
+        const planPreview = planLines.slice(0, 80).join('\n') + (planLines.length > 80 ? '\n\n[…plan truncated, first 80 lines shown]' : '')
+        return text({
+          task:           { key: task.key, title: task.title, priority: task.priority },
+          approval:       { id: approval._id, title: approval.title, state: approval.state,
+                            submittedBy: approval.requestedBy?.name || approval.requestedBy?.email || 'unknown',
+                            submittedAt: approval.requestedAt },
+          planPreview,
+          reviewChecklist: [
+            'Is the plan clear and specific? (not vague high-level bullets)',
+            'Does it identify the correct files/modules to change?',
+            'Does it handle edge cases and error paths?',
+            'Is the scope reasonable for a single task?',
+            'Any security, data-loss, or regression risks?',
+          ],
+          message: `Review the plan above, then call decide_task_approval again with confirmed=true and decision="approve" or "reject".`,
+        })
+      }
+
+      return call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/decide`, { decision, note }))
+    }
   )
 }
 
@@ -5466,6 +5839,47 @@ function writeCursorWorkspace(task, projectAgentConfig, startPath) {
 
     const written = []
 
+    // ── 0. Session protocol rule — always-apply, enforces skill gate ──────────
+    // This is the first rule Cursor sees (filename 00- sorts before all others).
+    // It forces the agent to read skills before editing — the root cause of
+    // builders skipping the skill step was the lack of a hard runtime constraint.
+    const sessionProtocolRule = `---
+description: InternalTool session protocol — enforced for every agent session on this task.
+alwaysApply: true
+---
+
+# ⛔ MANDATORY SESSION PROTOCOL
+
+**You MUST follow these steps IN ORDER before editing any file.**
+Skipping any step is a protocol violation and will result in incorrect implementation.
+
+## Step 1 — Read all skills (REQUIRED before any Edit/Write)
+For each file in \`.cursor/skills/\`:
+1. Read the file completely
+2. Call \`log_session_event\` with type="skill", name=<filename without .md>, role=<your role>
+
+Do NOT call Edit or Write until every skill file has been read and logged.
+
+## Step 2 — Recall memory
+Call \`recall(taskId="${taskId}")\` to restore facts from previous sessions.
+If memory contains a \`status\` key, read it — the task may have known blockers.
+
+## Step 3 — Get full context
+Call \`get_agent_context(taskId="${taskId}", role=<your role>)\`.
+Read the implementation plan, claimed files, and scout report before proceeding.
+
+## Step 4 — Claim files (builders only)
+Call \`claim_files\` with every file you will edit BEFORE your first Edit call.
+Editing unclaimed files causes merge conflicts with other agents.
+
+---
+
+**Role-specific hard constraints are in \`.cursor/agents/active-agent.md\`.**
+**Project-level rules are in \`.cursor/rules/\` (other .mdc files).**
+`
+    writeFileSync(join(rulesDir, '00-session-protocol.mdc'), sessionProtocolRule, 'utf8')
+    written.push(join(rulesDir, '00-session-protocol.mdc'))
+
     // ── 1. Project-level rules from DB → .cursor/rules/<name>.mdc ─────────────
     const projectRules = cfg.rules || []
     for (const r of projectRules) {
@@ -5874,7 +6288,17 @@ async function apiWithRetry(fn, maxRetries = 2, initialDelay = 500) {
 }
 
 function wrapApiError(e) {
-  return { error: true, cause: e._cause || 'unknown', message: e.message?.split('\n')[0] }
+  const cause = e._cause || 'unknown'
+  const isAuth = cause === 'auth'
+  return {
+    error: true,
+    cause,
+    message: e.message?.split('\n')[0],
+    ...(isAuth ? {
+      authError: true,
+      fix: 'Your session token has expired or is invalid. Ask the developer to restart the MCP server (which re-reads the INTERNALTOOL_API_KEY env var) or re-run: npx internaltool-mcp to reconnect.',
+    } : {}),
+  }
 }
 
 // ── #9 Get last git commit metadata ──────────────────────────────────────────
@@ -6427,7 +6851,16 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       if (needsApproval) {
         const isFix2 = /\b(fix|bug|hotfix|patch)\b/i.test(task.title + ' ' + (task.description || ''))
         const slug2 = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 35)
-        const previewBranch = `${isFix2 ? 'fix' : 'feature'}/${task.key.toLowerCase()}-${slug2}`
+        // Fetch devSlug here too so the preview matches the actual branch name
+        let devSlug2 = ''
+        try {
+          const meRes2 = await api.get('/api/auth/me')
+          const devName2 = meRes2?.data?.user?.name || meRes2?.data?.name || ''
+          devSlug2 = devName2.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 15)
+        } catch { /* non-fatal */ }
+        const previewBranch = devSlug2
+          ? `${devSlug2}/${isFix2 ? 'fix' : 'feature'}/${task.key.toLowerCase()}-${slug2}`
+          : `${isFix2 ? 'fix' : 'feature'}/${task.key.toLowerCase()}-${slug2}`
         return text({
           blocked: true,
           reason: 'approval_required',
@@ -6833,7 +7266,7 @@ Set confirmed=false first to preview the full plan, then confirmed=true to save
         })
       }
 
-      // Park Task B if provided
+      // Park Task B if provided — and clean up its workspace so skills don't bleed into Task A
       if (taskB && taskBId) {
         try {
           await api.patch(`/api/tasks/${taskBId}/park`, {
@@ -6842,6 +7275,14 @@ Set confirmed=false first to preview the full plan, then confirmed=true to save
             blockers:  '',
           })
         } catch { /* non-fatal — developer can park manually */ }
+        // Delete Task B's cursor workspace — same cleanup that park_task does.
+        // Without this, Task B's skills and session-protocol stay on disk while
+        // working on Task A's branch, and the agent may read the wrong context.
+        try { deleteCursorWorkspace(taskB?.agentRole || null, process.cwd()) } catch { /* non-fatal */ }
+        try { unlinkSync(join(process.cwd(), '.internaltool-active-task')) } catch { /* non-fatal */ }
+        api.patch(`/api/tasks/${taskBId}`, {
+          agentWorkspace: { clearedAt: new Date().toISOString() }
+        }).catch(() => {})
       }
 
       return text({
@@ -7013,21 +7454,33 @@ Set confirmed=false first to preview the full PR content, then confirmed=true to
         })
         if (!res?.success) return errorText(res?.message || 'Could not create PR')
 
-        // Delete the task-specific cursor rules file — coding is done
+        // Delete the full cursor workspace (skills, rules, active-agent) — coding is done
         const deletedRulesFile = deleteCursorRulesFile(task.key, repoPath)
+        deleteCursorWorkspace(task?.agentRole || null, repoPath || process.cwd())
+
+        // Move task to in_review directly — don't rely solely on GitHub webhook
+        // (webhook may not be configured, or may be delayed)
+        try {
+          await api.post(`/api/tasks/${taskId}/move`, { column: 'in_review', toIndex: 0 })
+        } catch { /* non-fatal — webhook will do it if direct patch fails */ }
+
+        // Remove .internaltool-active-task marker
+        try { unlinkSync(join(process.cwd(), '.internaltool-active-task')) } catch { /* non-fatal */ }
 
         return text({
           prNumber: res.data.prNumber,
           prUrl:    res.data.prUrl,
           title:    prTitle,
           draft,
-          message:  `PR #${res.data.prNumber} created.`,
-          cursorRulesCleared: deletedRulesFile
-            ? { cleared: true, path: deletedRulesFile, note: 'Task-specific Cursor rules file deleted — coding is complete.' }
-            : { cleared: false },
+          message:  `PR #${res.data.prNumber} created. Task moved to In Review.`,
+          cursorWorkspaceCleared: {
+            cleared: true,
+            rulesFile: deletedRulesFile || null,
+            note: 'Cursor workspace (skills + rules + active-agent) deleted — coding session is complete.',
+          },
           nextStep: draft
             ? 'PR is a draft. Mark it ready for review on GitHub when you want reviewer notifications to fire.'
-            : 'PR is live. The GitHub webhook will move the task to in_review and notify the reviewer within seconds.',
+            : `PR is live at ${res.data.prUrl}. Task is now in_review — the reviewer can call kickoff_task with agentRole="reviewer".`,
         })
       } catch (e) {
         return errorText(e.message)
@@ -7762,12 +8215,13 @@ Use this when a developer asks: "what do I do?", "how do I rebase?", "I have con
         } else {
           steps.push({
             step: stepNum++,
-            title: `Request review on PR #${branch.prNumber}`,
-            why: `Your PR is already open. After pushing the rebase, request reviewers so they can approve and merge.`,
+            title: `Get your PR reviewed — PR #${branch.prNumber}`,
+            why: `Your PR is already open. After pushing the rebase, ask your reviewer to approve so it can be merged.`,
             commands: [
-              { label: 'Request review via GitHub CLI', cmd: `gh pr review ${branch.prNumber} --request-changes` },
+              { label: 'Open the PR in your browser to add reviewers', cmd: `gh pr view --web ${branch.prNumber}` },
+              { label: 'Or check PR status in the terminal', cmd: `gh pr status` },
             ],
-            note: `PR URL: ${branch.prUrl || 'see GitHub'}`,
+            note: `PR URL: ${branch.prUrl || 'see GitHub'}. Add reviewers on GitHub (top-right "Reviewers" panel) — do NOT use "gh pr review --request-changes" (that submits a rejection verdict, not a review request).`,
           })
         }
 
@@ -8170,7 +8624,7 @@ Use this to remember decisions, constraints, context, and findings that should p
 Call recall(taskId) to retrieve everything at any time.`,
     {
       taskId: z.string().describe("Task's MongoDB ObjectId"),
-      key:    z.string().describe('Memory key — short, descriptive, no spaces (e.g. "arch_decision", "constraint_auth")'),
+      key:    z.string().describe('Memory key — short, descriptive, no spaces (e.g. "arch_decision", "constraint_auth"). In parallel builds with multiple agents on the same task, prefix with your role/index to avoid collisions (e.g. "builder1_discovered", "builder2_constraint"). Last write to the same key wins.'),
       value:  z.string().describe('Value to store — plain text, any length'),
     },
     async ({ taskId, key, value }) => {
@@ -8249,8 +8703,8 @@ Always call this first — it collapses context from the last 3 steps into one c
         if (repoPath && task.github?.headBranch) {
           try {
             const branch = task.github.headBranch
-            const status = execSync(`git -C "${repoPath}" status --short 2>/dev/null`, { encoding: 'utf8' }).trim()
-            const logLine = execSync(`git -C "${repoPath}" log --oneline -1 2>/dev/null`, { encoding: 'utf8' }).trim()
+            const status  = runGit('status --short', repoPath)
+            const logLine = runGit('log --oneline -1', repoPath)
             localState = { branch, dirty: status.length > 0, lastCommit: logLine }
           } catch { localState = { error: 'Could not read local git state' } }
         }

package/package.json

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