internaltool-mcp 1.6.31 → 1.6.35

package/index.js

@@ -619,6 +619,8 @@ Roles: BUILDER agents MUST call this before editing. Coordinators call this as p
       files:  z.array(z.string()).min(1).describe('List of file paths this task will exclusively edit (e.g. ["server/routes/tasks.js", "client/src/App.jsx"])'),
     },
     async ({ taskId, files }) => {
+      const denied = await guardRoleTool(taskId, 'claim_files')
+      if (denied) return denied
       trackTaskActivity(taskId, 'claim_files')
       const res = await api.post(`/api/tasks/${taskId}/files/claim`, { files })
       if (!res?.success) {
@@ -663,6 +665,47 @@ Files are also released automatically when the task is parked.`,
     }
   )
 
+  // ── set_task_type ─────────────────────────────────────────────────────────────
+  server.tool(
+    'set_task_type',
+    `Override the auto-detected task type before confirming kickoff.
+
+Call this during the confirmed=false preview step when the detected type looks wrong.
+Once set, kickoff_task will use this type directly and skip auto-detection entirely.
+Set to null to clear the override and let detection run again.
+
+Valid types:
+- migration    → DB schema changes, always coordinator + sequential
+- integration  → third-party API/webhook, single builder, no hardcoded keys
+- bugfix       → targeted fix, scout first, failing test before fix
+- ui           → frontend/components, parallel if multiple components
+- backend      → routes/controllers/services, auto complexity routing
+- security     → auth/permissions, always scout first + reviewer required
+- refactor     → restructuring, scout first, no behaviour changes
+- feature      → general new feature, auto complexity routing (default fallback)`,
+    {
+      taskId:   z.string().describe("Task's MongoDB ObjectId"),
+      taskType: z.enum(['migration', 'integration', 'bugfix', 'ui', 'backend', 'security', 'refactor', 'feature']).nullable()
+                 .describe('The correct task type, or null to clear and re-enable auto-detection'),
+    },
+    async ({ taskId, taskType }) => {
+      const res = await api.patch(`/api/tasks/${taskId}`, { taskType })
+      if (!res?.success) return errorText(res?.message || 'Could not set task type')
+      const cfg = taskType ? TASK_TYPES[taskType] : null
+      return text({
+        set: true,
+        taskType,
+        label:       cfg?.label || null,
+        riskLevel:   cfg?.riskLevel || null,
+        flow:        cfg?.flow || null,
+        scoutFirst:  cfg?.scoutFirst || false,
+        message:     taskType
+          ? `Task type locked to "${cfg?.label || taskType}". Call kickoff_task confirmed=false again to see the updated routing before confirming.`
+          : `Task type cleared — auto-detection will run again on next kickoff_task call.`,
+      })
+    }
+  )
+
   // ── decompose_task ────────────────────────────────────────────────────────────
   server.tool(
     'decompose_task',
@@ -700,6 +743,8 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
       confirmed:     z.boolean().optional().default(false).describe('Set true to save the decomposition and create subtasks on the board'),
     },
     async ({ taskId, subtaskPlan, confirmed = false }) => {
+      const denied = await guardRoleTool(taskId, 'decompose_task')
+      if (denied) return denied
       trackTaskActivity(taskId, 'decompose_task')
       const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
       if (!taskRes?.success) return errorText('Task not found')
@@ -840,6 +885,8 @@ Scouts MUST NOT modify any source code files or create branches.`,
       report:    z.string().optional().default('').describe('Your structured scout findings in markdown (required when confirmed=true)'),
     },
     async ({ taskId, confirmed = false, report = '' }) => {
+      const denied = await guardRoleTool(taskId, 'scout_task')
+      if (denied) return denied
       trackTaskActivity(taskId, 'scout_task')
       const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
       if (!taskRes?.success) return errorText('Task not found')
@@ -893,6 +940,271 @@ Scouts MUST NOT modify any source code files or create branches.`,
     }
   )
 
+  // ── check_merge_conflicts ─────────────────────────────────────────────────────
+  server.tool(
+    'check_merge_conflicts',
+    `Check whether this task's PR has merge conflicts and get coordination instructions.
+
+Call this when:
+- You are about to push commits and want to verify the branch is clean
+- You see a conflict warning in kickoff_task output (rebaseWarning)
+- A teammate tells you there is a conflict on this task
+- Before opening a PR to catch conflicts early
+
+Returns:
+- hasConflict: whether GitHub reports the PR as unmergeable
+- behindBy: how many commits behind the base branch this branch is
+- conflictingFiles: which files are in conflict
+- conflictingTasks: other active tasks in this project that claimed the same files
+- resolution: exact git commands to run, and who to coordinate with`,
+    { taskId: z.string().describe("Task's MongoDB ObjectId") },
+    async ({ taskId }) => {
+      trackTaskActivity(taskId, 'check_merge_conflicts')
+      const res = await api.get(`/api/tasks/${taskId}/conflict-status`)
+      if (!res?.success) return errorText('Could not fetch conflict status')
+
+      const d = res.data
+
+      if (!d.hasPR) return text({
+        status:  'no_pr',
+        message: 'No PR linked to this task yet. Create a branch and open a PR first.',
+      })
+      if (!d.linked) return text({
+        status:  'no_github',
+        message: 'Project does not have a GitHub repo linked. Configure it in project settings.',
+      })
+      if (d.error) return text({
+        status:  'github_unavailable',
+        message: d.error,
+      })
+      if (d.mergeableState === 'unknown') return text({
+        status:  'computing',
+        message: 'GitHub is still computing mergeability. Wait a few seconds and call check_merge_conflicts again.',
+      })
+
+      if (!d.hasConflict && d.behindBy === 0) return text({
+        status:  'clean',
+        message: `PR is clean — no conflicts, not behind ${d.base}. Safe to merge.`,
+      })
+
+      return text({
+        status:         d.hasConflict ? 'conflict' : 'behind',
+        hasConflict:    d.hasConflict,
+        behindBy:       d.behindBy,
+        base:           d.base,
+        headBranch:     d.headBranch,
+        conflictingFiles:  d.conflictingFiles,
+        conflictingTasks:  d.conflictingTasks,
+        coordinationNote:  d.coordinationNote,
+        resolution: {
+          steps: d.resolution,
+          note: d.hasConflict && d.conflictingTasks?.length > 0
+            ? `⚠️  COORDINATE FIRST: Contact the assignees of the conflicting tasks before resolving. Resolving without coordination may overwrite their work.`
+            : `Rebase your branch on ${d.base} to resolve.`,
+        },
+      })
+    }
+  )
+
+  // ── resolve_conflict ──────────────────────────────────────────────────────────
+  server.tool(
+    'resolve_conflict',
+    `Fetch full context from BOTH tasks involved in a merge conflict so Claude Code can make an informed semantic merge decision.
+
+Call this for each conflicting file BEFORE editing it. It returns:
+- thisTask: your task's goal, README, scout report
+- otherTask: the conflicting task's goal, README, scout report, assignees
+- the exact conflict markers to look for in the file
+- the resolution strategy based on both tasks' intents
+
+This is the context layer. After calling this, use the Read tool to open the file,
+the Edit tool to resolve the conflict markers, then continue the rebase with Bash.`,
+    {
+      taskId:   z.string().describe("Your task's MongoDB ObjectId"),
+      filePath: z.string().describe('The conflicting file path, e.g. server/middleware/auth.js'),
+    },
+    async ({ taskId, filePath }) => {
+      trackTaskActivity(taskId, 'resolve_conflict')
+
+      // Get this task + conflict status in parallel
+      const [taskRes, conflictRes] = await Promise.all([
+        apiWithRetry(() => api.get(`/api/tasks/${taskId}`)),
+        api.get(`/api/tasks/${taskId}/conflict-status`).catch(() => null),
+      ])
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      // Find the specific conflicting task that touched this file
+      const conflictData    = conflictRes?.data || {}
+      const conflictingTask = (conflictData.conflictingTasks || [])
+        .find(t => (t.claimedFiles || []).includes(filePath))
+
+      // Fetch other task's full context if found
+      let otherTask = null
+      if (conflictingTask?.taskId) {
+        try {
+          const otherRes = await api.get(`/api/tasks/${conflictingTask.taskId}`)
+          if (otherRes?.success) {
+            const o = otherRes.data.task
+            otherTask = {
+              key:         o.key,
+              title:       o.title,
+              goal:        o.readmeMarkdown || o.description || '(no README on that task)',
+              scoutReport: o.scoutReport    || null,
+              assignees:   (o.assignees || []).map(a => a.name || a.email).join(', ') || 'unassigned',
+              prUrl:       o.github?.prUrl  || null,
+            }
+          }
+        } catch { /* non-fatal */ }
+      }
+
+      const base = conflictData.base || 'main'
+
+      return text({
+        filePath,
+        thisTask: {
+          key:         task.key,
+          title:       task.title,
+          goal:        task.readmeMarkdown || task.description || '(no README on this task)',
+          scoutReport: task.scoutReport    || null,
+        },
+        otherTask: otherTask || {
+          note: 'Could not identify the specific task that caused this conflict. The conflict was likely introduced by a recent merge to ' + base + '. Check: git log origin/' + base + ' -- ' + filePath,
+        },
+        conflictMarkers: {
+          ours:   '<<<<<<< HEAD  ← YOUR changes (this task)',
+          theirs: '>>>>>>> ...   ← THEIR changes (merged into ' + base + ')',
+          middle: '=======       ← separator',
+        },
+        resolutionProtocol: [
+          '1. Read ' + filePath + ' using the Read tool — find all <<<<<<< blocks',
+          '2. For each block: understand thisTask.goal vs otherTask.goal',
+          '3. Decide: combine both / keep better / adapt one to fit the other',
+          '4. Use the Edit tool to rewrite the block — NO conflict markers in final file',
+          '5. Bash: git add ' + filePath,
+          '6. Bash: git rebase --continue (or git rebase --skip if this commit is already covered)',
+          '7. Repeat for each conflicting file',
+          '8. Bash: git push --force-with-lease',
+          '9. Call check_merge_conflicts to verify clean state',
+          '10. Call log_session_event with summary of what you merged and WHY',
+        ],
+        warning: otherTask
+          ? `⚠️  Read otherTask.goal before editing. "${otherTask.key}: ${otherTask.title}" made this change intentionally. Understand it before deciding what to keep.`
+          : `⚠️  Unknown conflict source. Be conservative — do not delete any logic you don't understand.`,
+      })
+    }
+  )
+
+  // ── request_human_input ───────────────────────────────────────────────────────
+  server.tool(
+    'request_human_input',
+    `Ask the developer a question and PAUSE — they will answer directly in this Cursor chat.
+
+WHEN TO CALL THIS:
+- Conflict resolution is ambiguous: both sides implement the same feature differently and you can't safely pick one
+- You need explicit approval before a destructive operation (git push --force-with-lease on a shared branch)
+- The task README is missing and you cannot determine intended behavior
+- Two tasks have incompatible goals that cannot be automatically merged
+
+DO NOT call this for decisions you can make autonomously (trivial formatting conflicts, variable names, import ordering).
+
+This tool posts a comment on the task (for visibility in the app) and notifies assignees. It then returns the question here in Cursor. The developer reads it and replies directly in this chat — you use their reply as the answer. No polling needed.`,
+    {
+      taskId:   z.string().describe("Your task's MongoDB ObjectId"),
+      question: z.string().describe('The specific question. Be precise — include file names, conflict lines, and what decision you need.'),
+      context:  z.string().optional().describe('Extra context: what both conflict sides do, what you tried, why you are stuck.'),
+      type:     z.enum(['question', 'approval', 'ambiguity']).optional()
+        .describe('question = need info; approval = need yes/no before destructive action; ambiguity = two valid interpretations, pick one'),
+    },
+    async ({ taskId, question, context = '', type = 'question' }) => {
+      trackTaskActivity(taskId, 'request_human_input')
+      await api.post(`/api/tasks/${taskId}/ask-human`, { question, context, type }).catch(() => null)
+
+      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.',
+      })
+    }
+  )
+
+  // ── get_project_git_tree ──────────────────────────────────────────────────────
+  server.tool(
+    'get_project_git_tree',
+    `Get a snapshot of all active branches in the project: who is working on what, which branches share files (conflict risk), and the suggested merge order.
+
+Call this at the START of a session (or before raising a PR) to understand the team landscape.
+Use the mergeOrder to know when it is safe to merge your branch.
+Use conflictPairs to coordinate with teammates before touching shared files.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId (find it in get_task response as task.project)"),
+    },
+    async ({ projectId }) => {
+      const treeRes = await api.get(`/api/projects/${projectId}/github/git-tree`).catch(() => null)
+      if (!treeRes?.success) return errorText('Could not fetch git tree — GitHub may not be linked to this project')
+      const tree = treeRes.data
+
+      // Compute conflict pairs from claimedFiles overlap
+      const branches = tree.branches || []
+      const conflictPairs = []
+      for (let i = 0; i < branches.length; i++) {
+        for (let j = i + 1; j < branches.length; j++) {
+          const shared = (branches[i].claimedFiles || []).filter(f => (branches[j].claimedFiles || []).includes(f))
+          if (shared.length) conflictPairs.push({ a: branches[i].taskKey, b: branches[j].taskKey, sharedFiles: shared })
+        }
+      }
+
+      // Merge order: fewest conflicts → least behind → most ahead
+      const conflictCount = {}
+      branches.forEach(b => { conflictCount[b.taskKey] = 0 })
+      conflictPairs.forEach(({ a, b }) => { conflictCount[a]++; conflictCount[b]++ })
+      const mergeOrder = [...branches]
+        .filter(b => !b.branchError)
+        .sort((a, b) => {
+          const cDiff = (conflictCount[a.taskKey] || 0) - (conflictCount[b.taskKey] || 0)
+          if (cDiff !== 0) return cDiff
+          const behindDiff = (a.compare?.behindBy ?? 99) - (b.compare?.behindBy ?? 99)
+          if (behindDiff !== 0) return behindDiff
+          return (b.compare?.aheadBy ?? 0) - (a.compare?.aheadBy ?? 0)
+        })
+        .map((b, i) => ({
+          rank:        i + 1,
+          taskKey:     b.taskKey,
+          taskTitle:   b.taskTitle,
+          headBranch:  b.headBranch,
+          status:      b.statusColor,
+          behindBy:    b.compare?.behindBy ?? null,
+          aheadBy:     b.compare?.aheadBy  ?? null,
+          assignees:   b.assignees.map(a => a.name).join(', ') || 'unassigned',
+          conflicts:   conflictPairs.filter(p => p.a === b.taskKey || p.b === b.taskKey).map(p => p.a === b.taskKey ? p.b : p.a),
+          readyToMerge: b.compare?.behindBy === 0 && b.statusColor !== 'red',
+        }))
+
+      const staleBranches = branches
+        .filter(b => {
+          if (!b.tipCommit?.date) return false
+          const hrs = (Date.now() - new Date(b.tipCommit.date).getTime()) / 3600000
+          return hrs >= 48
+        })
+        .map(b => ({ taskKey: b.taskKey, lastCommitAge: Math.round((Date.now() - new Date(b.tipCommit.date).getTime()) / 3600000) + 'h ago' }))
+
+      return text({
+        repo:          tree.repo,
+        defaultBranch: tree.defaultBranch,
+        summary: `${branches.length} active branch(es). ${branches.filter(b => b.statusColor === 'red').length} diverged. ${conflictPairs.length} conflict pair(s).`,
+        conflictPairs,
+        mergeOrder,
+        staleBranches,
+        advice: conflictPairs.length > 0
+          ? `⚠️  File conflicts exist. Coordinate with the listed teammates BEFORE editing shared files. Check mergeOrder to know when your branch should merge.`
+          : mergeOrder.some(b => b.behindBy > 0)
+            ? `Some branches are behind. Rebase before merging. Follow the mergeOrder sequence.`
+            : `✅ No file conflicts detected. Follow mergeOrder for the safest merge sequence.`,
+      })
+    }
+  )
+
   // ── get_agent_context ─────────────────────────────────────────────────────────
   server.tool(
     'get_agent_context',
@@ -940,7 +1252,13 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
       }
 
       // Suggest relevant skills based on role and available project skills
-      const availableSkills = ctx.project?.agentConfig?.skills || []
+      // Respects project-level enabled + task-level agentKitOverrides
+      const allProjectSkills = ctx.project?.agentConfig?.skills || []
+      const taskSkillOverrides = ctx.task?.agentKitOverrides?.skills || {}
+      const availableSkills = allProjectSkills.filter(s => {
+        const taskOverride = taskSkillOverrides[s.name]
+        return taskOverride !== undefined ? taskOverride : s.enabled !== false
+      })
       const suggestedSkills = availableSkills.length > 0
         ? availableSkills.map(s => ({
             name: s.name,
@@ -2345,8 +2663,80 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         ? `${devSlug}/feature/${task.key?.toLowerCase()}-${titleSlug}`
         : `feature/${task.key?.toLowerCase()}-${titleSlug}`
 
-      const hasReadme     = typeof task.readmeMarkdown === 'string' && task.readmeMarkdown.trim().length > 0
+      const hasReadme      = typeof task.readmeMarkdown === 'string' && task.readmeMarkdown.trim().length > 0
       const hasCursorRules = typeof task.cursorRules === 'string' && task.cursorRules.trim().length > 0
+
+      // ── Task flow auto-routing ────────────────────────────────────────────────
+      // Fetch project agentFlow setting early (needed for preview too)
+      let projectAgentFlowEarly = 'direct'
+      try {
+        const projEarly = await apiWithRetry(() => api.get(`/api/projects/${task.project}`))
+        projectAgentFlowEarly = projEarly?.data?.project?.agentConfig?.agentFlow || 'direct'
+      } catch { /* non-fatal */ }
+
+      // Only auto-route when no role is already set and task hasn't started yet
+      const notCoordinatorOrScout = agentRole !== 'coordinator' && agentRole !== 'scout'
+      const noDecomposition = !task.decomposition?.trim()
+      const noFileClaims    = !(task.claimedFiles?.length > 0)
+      const shouldAutoRoute = notCoordinatorOrScout && noDecomposition && noFileClaims
+
+      // ── Detect task type ───────────────────────────────────────────────────────
+      // Explicit type set by user or agent via set_task_type → skip detection.
+      const explicitType  = task.taskType || null
+      const detection     = explicitType ? null : detectTaskType(task)
+      const detectedType  = explicitType || detection.type
+      const typeIsExplicit = !!explicitType
+      const typeConfidence = explicitType ? 'explicit' : detection.confidence
+      const typeAmbiguous  = !explicitType && detection.ambiguous
+      const taskTypeCfg    = TASK_TYPES[detectedType]
+
+      // ── Score complexity from README signals ──────────────────────────────────
+      let complexityScore = 0
+      const complexitySignals = []
+
+      if (hasReadme) {
+        const readme = task.readmeMarkdown.trim()
+        const readmeLen    = readme.length
+        const sections     = (readme.match(/^#{1,3}\s/gm) || []).length
+        const fileMentions = (readme.match(/`[^`]+\.[a-z]{2,6}`/g) || []).length
+        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)
+
+        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`) }
+        else if (sections > 1)     { complexityScore += 1; complexitySignals.push(`${sections} README sections`) }
+        if (fileMentions > 4)      { complexityScore += 2; complexitySignals.push(`${fileMentions} files mentioned`) }
+        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') }
+      }
+
+      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
+      complexityScore = Math.max(0, complexityScore)
+
+      // ── Determine recommended flow ────────────────────────────────────────────
+      // Priority: project override > type-based > complexity score
+      let recommendedFlow
+      if (projectAgentFlowEarly === 'coordinator_first') {
+        recommendedFlow = 'coordinator'
+      } else if (taskTypeCfg.flow === 'coordinator') {
+        recommendedFlow = 'coordinator'            // type always requires coordinator (e.g. migration)
+      } else if (taskTypeCfg.flow === 'direct') {
+        recommendedFlow = 'direct'                 // type always direct (e.g. bugfix)
+      } else {
+        // 'auto' or 'single_builder' — use complexity score
+        if (!hasReadme || complexityScore <= 1)    recommendedFlow = 'direct'
+        else if (complexityScore <= 3)             recommendedFlow = 'single_builder'
+        else                                       recommendedFlow = 'coordinator'
+      }
+
+      // Backward-compat alias used in confirmed response
+      const requiresCoordinatorFlow = shouldAutoRoute && recommendedFlow === 'coordinator'
       const subtasks    = (task.subtasks || []).map(s => ({
         title: s.title,
         done:  s.done,
@@ -2485,6 +2875,56 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
                 rules: task.cursorRules,
               }
             : { ACTIVE: false },
+          TASK_ANALYSIS: shouldAutoRoute ? {
+            detectedType:    taskTypeCfg.label,
+            typeKey:         detectedType,
+            riskLevel:       taskTypeCfg.riskLevel,
+            recommendedFlow,
+            complexityScore,
+            complexitySignals,
+            scoutFirst:      taskTypeCfg.scoutFirst,
+            suggestedSkills: taskTypeCfg.suggestedSkills,
+            decompositionHint: taskTypeCfg.decompositionHint,
+            projectOverride: projectAgentFlowEarly === 'coordinator_first' ? 'Project enforces coordinator_first — overrides auto-detection.' : null,
+            typeRules: taskTypeCfg.extraRules,
+
+            // ── Type verification block — agent must read this before confirming ──
+            TYPE_VERIFICATION: typeIsExplicit
+              ? `✅ Type locked: ${taskTypeCfg.label} (set explicitly — detection skipped)`
+              : typeAmbiguous
+              ? [
+                  `⚠️  AMBIGUOUS TYPE — auto-detection was not confident.`,
+                  `Best guess: ${taskTypeCfg.label} (score: ${detection?.score ?? 0}, confidence: LOW)`,
+                  `Other candidates: ${Object.entries(detection?.allScores || {}).filter(([k]) => k !== detectedType).map(([k, s]) => `${k}(${s})`).join(', ') || 'none'}`,
+                  ``,
+                  `BEFORE confirming: verify this is the right type.`,
+                  `If wrong, call set_task_type with taskId="${taskId}" and the correct type, then re-run kickoff_task confirmed=false to see updated routing.`,
+                  `Valid types: migration | integration | bugfix | ui | backend | security | refactor | feature`,
+                ].join('\n')
+              : [
+                  `🔍 Detected: ${taskTypeCfg.label} (score: ${detection?.score ?? 0}, confidence: ${typeConfidence.toUpperCase()})`,
+                  `If this looks wrong, call set_task_type with taskId="${taskId}" and the correct type before confirming.`,
+                  `Valid types: migration | integration | bugfix | ui | backend | security | refactor | feature`,
+                ].join('\n'),
+
+            instruction: recommendedFlow === 'direct'
+              ? [
+                  `✅ ${taskTypeCfg.label.toUpperCase()} — DIRECT FLOW (risk: ${taskTypeCfg.riskLevel}, score: ${complexityScore})`,
+                  taskTypeCfg.scoutFirst ? `Recommended: Call kickoff_task with agentRole "scout" first to understand the codebase/bug, then builder.` : null,
+                  `Next: Call kickoff_task with taskId="${taskId}", agentRole "builder", confirmed true → claim_files → implement → commit → raise_pr`,
+                ].filter(Boolean).join('\n')
+              : recommendedFlow === 'single_builder'
+              ? `🔧 ${taskTypeCfg.label.toUpperCase()} — SINGLE BUILDER (risk: ${taskTypeCfg.riskLevel}, score: ${complexityScore})\nNext: Call kickoff_task with taskId="${taskId}", agentRole "builder", confirmed true → claim_files → implement → commit → raise_pr`
+              : [
+                  `⚡ ${taskTypeCfg.label.toUpperCase()} — COORDINATOR FLOW (risk: ${taskTypeCfg.riskLevel}, score: ${complexityScore})`,
+                  taskTypeCfg.scoutFirst ? `Step 0: Call kickoff_task with agentRole "scout" first — mapping schema/codebase is REQUIRED for this task type` : null,
+                  `Step 1: Call kickoff_task with taskId="${taskId}", agentRole "coordinator", confirmed true`,
+                  `Step 2: Call decompose_task — use decompositionHint above as your guide`,
+                  `Step 3: Call get_parallel_kickoffs — writes builder agent files`,
+                  `Step 4: Open Background Agents panel (⌘⇧J) → start each builder`,
+                  `Step 5: Call wait_for_group — auto-proceeds between groups`,
+                ].filter(Boolean).join('\n'),
+          } : null,
           brief: {
             key:         task.key,
             title:       task.title,
@@ -2565,15 +3005,92 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       } catch { /* GitHub may not be linked */ }
 
       // Fetch project agentConfig for custom role generation
+      let kickoffProject = null
       try {
         const projRes = await api.get(`/api/projects/${task.project}`)
-        if (projRes?.success) projectAgentConfig = projRes.data.project?.agentConfig || null
+        if (projRes?.success) {
+          kickoffProject     = projRes.data.project || null
+          projectAgentConfig = kickoffProject?.agentConfig || null
+        }
+      } catch { /* non-fatal */ }
+
+      // ── Team context: file conflict warnings + merge position ──────────────────
+      let teamContext = null
+      try {
+        const treeRes = await api.get(`/api/projects/${task.project}/github/git-tree`).catch(() => null)
+        if (treeRes?.success) {
+          const treeBranches = treeRes.data?.branches || []
+          const myFiles = task.claimedFiles || []
+
+          // Other active branches sharing claimed files with this task
+          const fileConflicts = treeBranches
+            .filter(b => b.taskId !== String(task._id))
+            .map(b => {
+              const shared = (b.claimedFiles || []).filter(f => myFiles.includes(f))
+              return shared.length ? { taskKey: b.taskKey, assignees: b.assignees.map(a => a.name).join(', ') || 'unassigned', sharedFiles: shared } : null
+            })
+            .filter(Boolean)
+
+          // Merge order position for this task
+          const conflictCount = {}
+          const allPairs = []
+          for (let i = 0; i < treeBranches.length; i++) {
+            for (let j = i + 1; j < treeBranches.length; j++) {
+              const shared = (treeBranches[i].claimedFiles || []).filter(f => (treeBranches[j].claimedFiles || []).includes(f))
+              if (shared.length) allPairs.push({ a: treeBranches[i].taskKey, b: treeBranches[j].taskKey })
+            }
+          }
+          treeBranches.forEach(b => { conflictCount[b.taskKey] = 0 })
+          allPairs.forEach(({ a, b }) => { conflictCount[a]++; conflictCount[b]++ })
+
+          const ordered = [...treeBranches]
+            .filter(b => !b.branchError)
+            .sort((a, b) => {
+              const c = (conflictCount[a.taskKey] || 0) - (conflictCount[b.taskKey] || 0)
+              if (c !== 0) return c
+              return (a.compare?.behindBy ?? 99) - (b.compare?.behindBy ?? 99)
+            })
+          const myRank = ordered.findIndex(b => b.taskId === String(task._id)) + 1
+
+          if (fileConflicts.length > 0 || myRank > 1) {
+            teamContext = {
+              mergePosition:       myRank || null,
+              totalActiveBranches: treeBranches.length,
+              fileConflicts,
+              mergeOrder: ordered.map((b, i) => ({
+                rank: i + 1, taskKey: b.taskKey, behindBy: b.compare?.behindBy ?? null, readyToMerge: b.compare?.behindBy === 0,
+              })),
+              warning: fileConflicts.length > 0
+                ? `⚠️  Your claimedFiles overlap with ${fileConflicts.map(c => c.taskKey).join(', ')}. Coordinate before pushing.`
+                : myRank > 1
+                  ? `ℹ️  You are #${myRank} in the suggested merge order. ${ordered[0]?.taskKey} should merge before you.`
+                  : 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
       let moved = false
+
+      // Rebase check: warn if the task branch is behind the default branch
+      let rebaseWarning = null
+      if (alreadyHasBranch) {
+        try {
+          const branchStatus = await api.get(`/api/tasks/${taskId}/branch-status`)
+          if (branchStatus?.success && branchStatus.data?.behindBy > 0) {
+            rebaseWarning = {
+              behindBy: branchStatus.data.behindBy,
+              base:     branchStatus.data.base,
+              status:   branchStatus.data.status,
+              message:  `⚠️  Branch '${task.github.headBranch}' is ${branchStatus.data.behindBy} commit(s) behind '${branchStatus.data.base}'. ` +
+                        `Rebase before editing files to avoid merge conflicts: git fetch origin && git rebase origin/${branchStatus.data.base}`,
+            }
+          }
+        } catch { /* non-fatal — never block kickoff for a GitHub API failure */ }
+      }
       if (alreadyHasBranch) {
         try {
           const moveRes = await api.post(`/api/tasks/${taskId}/move`, { column: 'in_progress', toIndex: 0 })
@@ -2581,13 +3098,13 @@ 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 (with role injection if set)
+      // Write cursor rules file — merge task rules + task-type rules
       let cursorRulesFile = null
-      if (hasCursorRules) {
-        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)
+      const typeExtraRules = shouldAutoRoute && taskTypeCfg.extraRules ? taskTypeCfg.extraRules : ''
+      const baseRules = hasCursorRules ? task.cursorRules : ''
+      const mergedRules = [baseRules, typeExtraRules].filter(Boolean).join('\n\n') || '(Follow role constraints above.)'
+      if (hasCursorRules || agentRole || typeExtraRules) {
+        cursorRulesFile = writeCursorRulesFile(task.key, mergedRules, repoPath, agentRole || null)
       }
 
       // Dynamically generate .cursor/agents, .cursor/skills, .cursor/commands
@@ -2597,6 +3114,46 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       const taskForWorkspace = agentRole ? { ...task, agentRole } : task
       const workspaceResult = writeCursorWorkspace(taskForWorkspace, projectAgentConfig, repoPath || process.cwd())
 
+      // If branch is behind or conflicted, write a conflict-resolver rule into .cursor/rules/
+      // so the agent is constrained by it automatically on every prompt until resolved.
+      if (rebaseWarning) {
+        try {
+          const repoRootForRules = workspaceResult?.repoRoot || findRepoRoot(repoPath || process.cwd())
+          if (repoRootForRules) {
+            const rulesDir      = join(repoRootForRules, '.cursor', 'rules')
+            mkdirSync(rulesDir, { recursive: true })
+            const teamWarn = teamContext?.warning ? `\n${teamContext.warning}\n` : ''
+            const mergePos = teamContext?.mergePosition ? `\nYou are **#${teamContext.mergePosition}** in the suggested merge order. Do not rush to merge — wait for tasks ranked above you.\n` : ''
+            const conflictRule  = `---
+description: Conflict resolution constraints — active because this branch has conflicts
+alwaysApply: true
+---
+
+## ⚠️ BRANCH CONFLICT ACTIVE
+
+This branch is **${rebaseWarning.behindBy} commit(s) behind** \`${rebaseWarning.base}\`.
+${teamWarn}${mergePos}
+### Before editing ANY file:
+1. \`get_project_git_tree\` — see the full team landscape
+2. \`check_merge_conflicts\` — get the conflict file list
+3. For each conflicting file: \`resolve_conflict\` → read both tasks' goals → resolve
+
+### Hard rules:
+- \`git rebase\` only — never \`git merge\`
+- \`git push --force-with-lease\` only — never \`--force\`
+- Do NOT mark subtasks done until \`check_merge_conflicts\` returns \`status: 'clean'\`
+
+### Ask the human when:
+- Another active branch shares your files AND you cannot determine whose change wins → \`request_human_input(type="ambiguity")\`
+- Before force-pushing if another developer's branch overlaps → \`request_human_input(type="approval")\`
+
+After \`request_human_input\`: STOP, show the question in chat, wait for reply, then continue.
+`
+            writeFileSync(join(rulesDir, 'conflict-resolver.mdc'), conflictRule, 'utf8')
+          }
+        } catch { /* non-fatal */ }
+      }
+
       // Persist agentRole + workspace status to server
       const workspacePatch = {
         ...(agentRole ? { agentRole } : {}),
@@ -2609,6 +3166,11 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       }
       api.patch(`/api/tasks/${taskId}`, workspacePatch).catch(() => {/* non-fatal */})
 
+      // Auto-scan workspace so the Workspace tab in the UI is fresh immediately after kickoff.
+      if (kickoffProject) {
+        runWorkspaceScan(taskId, task, kickoffProject, repoPath).catch(() => {/* non-fatal */})
+      }
+
       return text({
         started: {
           key:      task.key,
@@ -2644,18 +3206,34 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
           date:    c.commit?.author?.date,
         })),
         movedToInProgress: moved,
+        rebaseWarning,
+        teamContext,
         suggestedBranch: alreadyHasBranch ? null : suggestedBranch,
+        taskAnalysis: shouldAutoRoute ? {
+          detectedType:      taskTypeCfg.label,
+          riskLevel:         taskTypeCfg.riskLevel,
+          recommendedFlow,
+          complexityScore,
+          suggestedSkills:   taskTypeCfg.suggestedSkills,
+          decompositionHint: taskTypeCfg.decompositionHint,
+          scoutFirst:        taskTypeCfg.scoutFirst,
+          typeRulesInjected: !!typeExtraRules,
+        } : null,
         nextStep: agentRole === 'scout'
-          ? `You are in SCOUT mode. Read the codebase, then save your findings with update_task(scoutReport=...). Do NOT modify any files.`
+          ? `SCOUT mode. Read the codebase, then save findings with update_task(scoutReport=...). Do NOT modify 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.`
+          ? `COORDINATOR mode. Read the README, then call decompose_task to split work into parallel/sequential subtasks with file ownership.`
           : agentRole === 'builder'
-          ? `You are in BUILDER mode. Call claim_files first, then start coding on "${alreadyHasBranch ? task.github.headBranch : suggestedBranch}".`
+          ? `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.`
+          ? `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
-          ? `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.`,
+          ? `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.`,
       })
     }
   )
@@ -3166,6 +3744,269 @@ You are a COORDINATOR agent. Your behavioral constraints for this session:
 - NEVER implement code yourself — your job ends after get_parallel_kickoffs writes the agent files`,
 }
 
+// ── Task type detection + per-type config ──────────────────────────────────────
+// Each type carries: detection signals, recommended flow, extra rules, suggested skills,
+// decomposition hints, and risk level.
+
+const TASK_TYPES = {
+  migration: {
+    label: 'DB Migration',
+    riskLevel: 'high',
+    titleSignals:  ['migrat', 'schema', 'db ', 'database', 'column ', 'table ', 'index ', 'seed', 'sequelize', 'mongoose.*schema', 'alter '],
+    readmeSignals: ['migration', 'schema', 'rollback', 'up()', 'down()', 'alter table', 'add column', 'drop column', 'mongoose.Schema'],
+    fileSignals:   ['migrations/', 'seeds/', 'migrate', '.migration.'],
+    flow:          'coordinator',  // always coordinator — sequential groups, high risk
+    parallel:      false,          // schema changes are sequential by nature
+    scoutFirst:    true,           // must understand current schema before touching it
+    extraRules: `## Task Type: DB MIGRATION — HIGH RISK
+
+**MANDATORY before writing any code:**
+1. Scout the existing schema first — call kickoff_task with agentRole "scout"
+2. Map every model/schema file that will be affected
+3. Decompose into sequential groups: schema change → model update → seed/test data → tests
+
+**MIGRATION RULES (non-negotiable):**
+- Every migration file MUST have a rollback (down() function)
+- NEVER modify an existing migration file that has already run
+- NEVER drop columns/tables without confirming data is backed up
+- ALWAYS test the rollback before marking done
+- Run migrations on a test database copy first
+- Commit migration files separately from model changes
+
+**DECOMPOSITION PATTERN for migrations:**
+Group 1 (sequential): Write migration file with up() + down()
+Group 2 (sequential): Update affected models/schemas
+Group 3 (sequential): Update seed files and test fixtures
+Group 4 (sequential): Write integration tests that run migration + rollback`,
+    suggestedSkills: ['run-migration', 'test-rollback', 'scout-codebase'],
+    decompositionHint: 'Split into sequential groups: migration file → model update → seeds → tests. Each group depends on the previous. No parallel execution — order matters for schema integrity.',
+  },
+
+  integration: {
+    label: 'Third-party Integration',
+    riskLevel: 'medium-high',
+    titleSignals:  ['integrat', 'webhook', 'oauth', 'payment', 'stripe', 'twilio', 'sendgrid', 'aws', 's3', 'firebase', 'api key', 'third.party', 'external'],
+    readmeSignals: ['api key', 'webhook', 'oauth', 'access token', 'client secret', 'base url', 'sdk', 'third-party', 'external service'],
+    fileSignals:   ['services/', 'integrations/', 'webhooks/', '.env'],
+    flow:          'single_builder',  // usually one workstream — one integration = one unit
+    parallel:      false,
+    scoutFirst:    false,
+    extraRules: `## Task Type: THIRD-PARTY INTEGRATION — MEDIUM-HIGH RISK
+
+**SECURITY RULES (non-negotiable):**
+- NEVER hardcode API keys, secrets, or tokens in source code
+- ALL credentials go in environment variables — reference as process.env.KEY_NAME
+- NEVER commit .env files with real credentials
+- Add .env to .gitignore if not already present
+
+**INTEGRATION RULES:**
+- Always wrap external calls in try/catch with meaningful error messages
+- All external API calls must be mocked in tests (no real API calls in test suite)
+- Add timeout handling — external services can be slow or unavailable
+- Log errors with enough context to debug (request ID, status code, endpoint)
+- Test both success AND failure paths — what happens when the API is down?
+
+**DECOMPOSITION PATTERN for integrations:**
+1. Service/client file (wraps the SDK/API)
+2. Business logic that calls the service
+3. Tests with mocked external calls
+4. Environment variable documentation`,
+    suggestedSkills: ['mock-external-calls', 'check-env-vars', 'run-tests'],
+    decompositionHint: 'Split into: service wrapper → business logic → mocked tests. Keep external SDK calls isolated in one service file so tests can mock it cleanly.',
+  },
+
+  bugfix: {
+    label: 'Bug Fix',
+    riskLevel: 'low-medium',
+    titleSignals:  ['fix', 'bug', 'issue', 'error', 'broken', 'failing', 'crash', 'regression', 'typo', 'incorrect', 'wrong', 'not working'],
+    readmeSignals: ['bug', 'reproduce', 'root cause', 'stack trace', 'error message', 'expected behavior', 'actual behavior'],
+    fileSignals:   [],
+    flow:          'direct',   // targeted fix — scout to understand, then fix directly
+    parallel:      false,
+    scoutFirst:    true,       // understand the bug before touching code
+    extraRules: `## Task Type: BUG FIX
+
+**REQUIRED WORKFLOW:**
+1. Scout first: reproduce the bug, read the stack trace, understand root cause
+2. Write a failing test that reproduces the bug BEFORE writing the fix
+3. Fix the root cause — not the symptom
+4. Verify the test now passes
+5. Run the full test suite to check for regressions
+
+**BUG FIX RULES:**
+- Fix the root cause, not the symptom (no defensive null checks to hide errors)
+- The fix should be minimal and targeted — no unrelated refactors
+- Every bug fix MUST include a regression test
+- If the bug reveals a broader design issue, file a separate task — don't fix it here`,
+    suggestedSkills: ['reproduce-bug', 'run-tests'],
+    decompositionHint: 'Bug fixes rarely need decomposition. Use direct flow: scout → reproduce → fix → regression test → commit.',
+  },
+
+  ui: {
+    label: 'UI / Frontend',
+    riskLevel: 'low',
+    titleSignals:  ['ui', 'component', 'page', 'screen', 'layout', 'design', 'style', 'form', 'modal', 'button', 'dashboard', 'frontend', 'view'],
+    readmeSignals: ['component', 'jsx', 'tsx', 'css', 'tailwind', 'responsive', 'mobile', 'desktop', 'user interface', 'render'],
+    fileSignals:   ['components/', 'pages/', 'views/', 'screens/', '.jsx', '.tsx', '.css', '.scss'],
+    flow:          'auto',   // parallel if multiple independent components, single if one flow
+    parallel:      true,     // UI components are often independent
+    scoutFirst:    false,
+    extraRules: `## Task Type: UI / FRONTEND
+
+**UI RULES:**
+- No business logic inside components — components render data, they don't fetch/transform it
+- Keep components small and focused (single responsibility)
+- Every interactive element must handle loading, error, and empty states
+- Test responsive behavior — check mobile + desktop breakpoints
+- No inline styles — use CSS classes / Tailwind utilities consistently with the design system
+- Accessibility: interactive elements need aria labels, buttons need type="button"
+
+**DECOMPOSITION PATTERN for multi-component features:**
+Each independent component can run in parallel as a separate builder subtask.
+Shared utilities/hooks should be built first (Group 1), then components that use them (Group 2).`,
+    suggestedSkills: ['run-tests', 'check-responsive'],
+    decompositionHint: 'UI tasks can often run in parallel: one builder per independent component. Group shared hooks/utils in Group 1, then components in Group 2 (parallel).',
+  },
+
+  backend: {
+    label: 'Backend / API',
+    riskLevel: 'medium',
+    titleSignals:  ['endpoint', 'route', 'api', 'controller', 'service', 'middleware', 'backend', 'server', 'handler'],
+    readmeSignals: ['route', 'endpoint', 'request', 'response', 'middleware', 'controller', 'service', 'http', 'rest', 'graphql'],
+    fileSignals:   ['routes/', 'controllers/', 'services/', 'middleware/', 'api/'],
+    flow:          'auto',   // single builder for one endpoint, coordinator for multi-endpoint features
+    parallel:      false,    // route → model → middleware → tests often sequential
+    scoutFirst:    false,
+    extraRules: `## Task Type: BACKEND / API
+
+**API RULES:**
+- All routes must have corresponding tests (minimum: success, 401, 404)
+- Validate all request inputs at the route level — never trust user input
+- Return consistent response shape: { success: true/false, data: {...}, message: '...' }
+- Authentication middleware must be applied to all protected routes
+- No raw database queries in route handlers — use model methods or service layer
+- HTTP status codes must be semantically correct (200/201/400/401/403/404/500)
+
+**DECOMPOSITION PATTERN for multi-endpoint features:**
+Each independent endpoint can be a parallel builder subtask (separate route + tests).
+Shared middleware or model changes should be in Group 1 (sequential first).`,
+    suggestedSkills: ['run-tests', 'add-express-route'],
+    decompositionHint: 'Group shared model/middleware changes first (Group 1, sequential). Then independent endpoint implementations in Group 2 (parallel if no shared files).',
+  },
+
+  security: {
+    label: 'Security / Auth',
+    riskLevel: 'high',
+    titleSignals:  ['security', 'auth', 'permission', 'access control', 'jwt', 'token', 'xss', 'csrf', 'injection', 'vulnerability', 'pentest', 'audit', 'rbac', 'oauth', 'rate limit', 'sanitiz'],
+    readmeSignals: ['security', 'authentication', 'authorization', 'privilege', 'exploit', 'attack surface', 'hardening', 'role-based', 'guard', 'middleware auth'],
+    fileSignals:   ['middleware/auth', 'auth/', 'guards/', 'policies/', 'permissions/'],
+    flow:          'direct',    // security fixes are targeted and must not be parallelised
+    parallel:      false,
+    scoutFirst:    true,        // always map attack surface before touching auth code
+    extraRules: `## Task Type: SECURITY / AUTH — HIGH RISK
+
+**MANDATORY before writing any code:**
+1. Scout the full auth flow: middleware chain, token validation, role checks
+2. Map all endpoints that would be affected by the change
+3. Check for privilege escalation vectors before and after the change
+
+**SECURITY RULES (non-negotiable):**
+- NEVER weaken an existing security check — only strengthen
+- NEVER log passwords, tokens, secrets, or PII
+- ALL credentials go in environment variables only
+- Every auth change must be reviewed by a second agent (reviewer role) before merge
+- Test BOTH the happy path AND the attack path (what happens if you bypass the check?)
+- No hardcoded secrets, API keys, or signing secrets anywhere in source
+
+**REVIEW REQUIREMENT:**
+After implementing, call kickoff_task with agentRole "reviewer" to do a security review before raising the PR.`,
+    suggestedSkills: ['bridge-guard-security-audit', 'run-tests'],
+    decompositionHint: 'Security changes should NOT be parallelised — one reviewer must be able to trace the full change. Scout → fix → security review → tests → PR.',
+  },
+
+  refactor: {
+    label: 'Refactor',
+    riskLevel: 'medium',
+    titleSignals:  ['refactor', 'restructure', 'reorganize', 'rewrite', 'cleanup', 'clean up', 'extract', 'rename', 'dedup', 'deduplicate', 'simplify', 'modernize'],
+    readmeSignals: ['refactor', 'restructure', 'extract', 'duplicate', 'technical debt', 'code smell', 'cohesion', 'coupling'],
+    fileSignals:   [],
+    flow:          'auto',
+    parallel:      false,   // refactors touch shared files — parallelism causes conflicts
+    scoutFirst:    true,    // must understand what currently exists before restructuring
+    extraRules: `## Task Type: REFACTOR
+
+**REFACTOR RULES:**
+- No behaviour changes — the public API and observable behaviour must be identical before and after
+- Run the full test suite before AND after every meaningful change — tests are your safety net
+- Do not add new features during a refactor — create a separate task
+- Rename in small atomic commits so git blame stays useful
+- If you discover a bug while refactoring, file a separate task — don't fix it here
+
+**DECOMPOSITION PATTERN for large refactors:**
+Group 1: Scout + map all call sites of the code being changed
+Group 2: Change the internals without touching the public interface
+Group 3: Update all call sites
+Group 4: Delete dead code + run full test suite`,
+    suggestedSkills: ['run-tests', 'bridge-recon'],
+    decompositionHint: 'Refactors must be sequential — parallel builders will conflict on shared files. Scout first to map all usages, then change in layers: internals → call sites → cleanup.',
+  },
+
+  feature: {
+    label: 'New Feature',
+    riskLevel: 'medium',
+    titleSignals:  ['add', 'implement', 'build', 'create', 'new', 'introduce', 'develop'],
+    readmeSignals: [],
+    fileSignals:   [],
+    flow:          'auto',   // complexity score decides
+    parallel:      true,
+    scoutFirst:    false,
+    extraRules: `## Task Type: NEW FEATURE
+
+**FEATURE RULES:**
+- Read and follow the implementation plan exactly — no scope creep
+- Every new function/endpoint needs tests
+- New files must follow the existing naming and folder conventions
+- No breaking changes to existing public APIs without explicit approval`,
+    suggestedSkills: ['run-tests'],
+    decompositionHint: 'Split by layer (model / route / tests) or by independent sub-features. Use parallel execution where files don\'t overlap.',
+  },
+}
+
+/**
+ * Detect task type from title + README + file patterns.
+ * Returns the best matching type key, or 'feature' as fallback.
+ */
+function detectTaskType(task) {
+  const text = [task.title || '', task.readmeMarkdown || '', task.description || ''].join(' ').toLowerCase()
+
+  const scores = {}
+  for (const [typeKey, cfg] of Object.entries(TASK_TYPES)) {
+    let score = 0
+    for (const sig of cfg.titleSignals)  { if (new RegExp(sig, 'i').test(task.title || ''))          score += 3 }
+    for (const sig of cfg.readmeSignals) { if (new RegExp(sig, 'i').test(task.readmeMarkdown || '')) score += 2 }
+    for (const sig of cfg.fileSignals)   { if (new RegExp(sig, 'i').test(text))                      score += 1 }
+    scores[typeKey] = score
+  }
+
+  const sorted = Object.entries(scores).sort((a, b) => b[1] - a[1])
+  const [first, second] = sorted
+
+  // Require min score of 1 AND a gap of at least 2 over the second-best type.
+  // If two types are within 2 points of each other the title is ambiguous — fall
+  // back to 'feature' so the agent is asked to verify rather than silently mis-routing.
+  const topScore   = first?.[1] ?? 0
+  const secondScore = second?.[1] ?? 0
+  const isAmbiguous = topScore < 1 || (topScore - secondScore) < 2
+
+  return {
+    type:       isAmbiguous ? 'feature' : first[0],
+    score:      topScore,
+    confidence: isAmbiguous ? 'low' : topScore >= 5 ? 'high' : 'medium',
+    ambiguous:  isAmbiguous,
+    allScores:  Object.fromEntries(sorted.filter(([, s]) => s > 0)),
+  }
+}
+
 /** 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) {
@@ -3236,9 +4077,14 @@ function writeCursorWorkspace(task, projectAgentConfig, startPath) {
 
     // ── 2. Subagents from DB → .cursor/agents/<name>.md ───────────────────────
     //    If DB has subagents defined, write them verbatim (admin-authored markdown)
+    //    Respects project-level enabled flag + task-level agentKitOverrides.
     const dbSubagents = cfg.subagents || []
+    const kitSubagentOverrides = task.agentKitOverrides?.subagents || {}
     for (const s of dbSubagents) {
       if (!s.name || !s.body) continue
+      const taskOverride = kitSubagentOverrides[s.name]
+      const isEnabled = taskOverride !== undefined ? taskOverride : s.enabled !== false
+      if (!isEnabled) 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')
@@ -3291,16 +4137,22 @@ function writeCursorWorkspace(task, projectAgentConfig, startPath) {
 
     // ── 5. Skills from DB → .cursor/skills/<name>.md ──────────────────────────
     //    If DB is empty, write built-in defaults so Cursor always has something useful.
+    //    Respects project-level enabled flag + task-level agentKitOverrides.
     const dbSkills = cfg.skills || []
-    if (dbSkills.length > 0) {
-      for (const s of dbSkills) {
-        if (!s.name || !s.body) continue
+    const kitSkillOverrides = task.agentKitOverrides?.skills || {}
+    const enabledSkills = dbSkills.filter(s => {
+      if (!s.name || !s.body) return false
+      const taskOverride = kitSkillOverrides[s.name]
+      return taskOverride !== undefined ? taskOverride : s.enabled !== false
+    })
+    if (enabledSkills.length > 0) {
+      for (const s of enabledSkills) {
         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 {
+    } else if (dbSkills.length === 0) {
       // Built-in default skills
       const defaults = [
         {
@@ -3322,6 +4174,147 @@ function writeCursorWorkspace(task, projectAgentConfig, startPath) {
       }
     }
 
+    // ── 5b. System skill: team-awareness — always written ─────────────────────────
+    const teamAwarenessSkill = `---
+name: team-awareness
+description: Understand the team's branch landscape before coding or merging. Prevents conflicts and wrong merge order.
+---
+
+## When to use
+Call this skill at the start of every builder/coordinator session, and before raising a PR.
+
+## Step 1 — Check the team landscape
+\`\`\`
+get_project_git_tree(projectId="${task.project?._id || task.project || '<projectId>'}")
+\`\`\`
+Read: \`conflictPairs\`, \`mergeOrder\`, \`staleBranches\`.
+
+## Step 2 — Act on what you see
+
+**If \`conflictPairs\` includes your task:**
+- Contact the other task's assignee BEFORE touching shared files
+- Use \`request_human_input\` to coordinate if the overlap is significant
+- Consider claiming different files or splitting the work
+
+**If you are NOT rank 1 in \`mergeOrder\`:**
+- Note which tasks should merge before you
+- Do not raise your PR as "ready to merge" until the tasks ranked above you are merged
+- You CAN keep coding — just don't block the pipeline
+
+**If your branch is behind (\`behindBy > 0\`):**
+- Run: \`git fetch origin && git rebase origin/${base || 'main'}\`
+- Then re-check with \`check_merge_conflicts\`
+
+**If \`staleBranches\` includes your task:**
+- Your last commit was 48h+ ago
+- Check if work is blocked, notify the team via \`add_task_comment\`
+`
+    writeFileSync(join(skillsDir, 'team-awareness.md'), teamAwarenessSkill, 'utf8')
+    written.push(join(skillsDir, 'team-awareness.md'))
+
+    // ── 5c. System skill: resolve-conflict — always written, regardless of DB skills ──
+    //    Every agent needs this available. It is not configurable — it is infrastructure.
+    const resolveConflictSkill = `---
+name: resolve-conflict
+description: Autonomously resolve git merge conflicts using context from both tasks. Asks human only when genuinely ambiguous or before destructive operations.
+---
+
+## When to use
+Call this skill when \`kickoff_task\` returns a \`rebaseWarning\`, or when \`check_merge_conflicts\` returns \`status: 'conflict'\` or \`status: 'behind'\`.
+
+## Decision tree — autonomous vs. ask human
+
+Resolve autonomously when:
+- One side adds new functionality the other doesn't touch → keep both
+- One side fixes a bug in shared code → prefer the fix, adapt for your task's additions
+- Pure formatting / import ordering conflict → pick the cleaner version
+- One side deletes something the other modifies → keep the modification (deletion was likely superseded)
+
+Call \`request_human_input(type="ambiguity")\` when:
+- Both sides implement the SAME feature but differently (two valid architectures)
+- You cannot determine which task's intent takes priority
+- The task README is missing and the code intent is unclear
+- Two tasks have genuinely incompatible API contracts (different signatures for same function)
+
+Call \`request_human_input(type="approval")\` before:
+- \`git push --force-with-lease\` on a branch shared with another active developer
+- Any operation that could permanently overwrite a teammate's committed work
+
+## Protocol
+
+### Step 1 — Get the full picture
+\`\`\`
+check_merge_conflicts(taskId="${taskId}")
+\`\`\`
+Read: \`conflictingFiles\`, \`conflictingTasks\`, \`behindBy\`.
+
+### Step 2 — For each conflicting file, fetch both contexts
+\`\`\`
+resolve_conflict(taskId="${taskId}", filePath="<file>")
+\`\`\`
+This returns \`thisTask.goal\` and \`otherTask.goal\` — read both before touching the file.
+
+### Step 3 — Decide: autonomous or ask?
+Apply the decision tree above. If autonomous, continue to Step 4.
+If ambiguous:
+\`\`\`
+request_human_input(
+  taskId="${taskId}",
+  question="I found two conflicting implementations of <X> in <file>. Your version does <A>. The other task (KEY) does <B>. Which approach should I keep, or should I combine them?",
+  context="thisTask goal: <goal>. otherTask goal: <other goal>. Conflict block: <paste the <<<<<<< block>",
+  type="ambiguity"
+)
+\`\`\`
+The question appears in Cursor chat. STOP and wait for the developer to reply here. Use their reply as the answer and continue from Step 4.
+
+### Step 4 — Start the rebase
+\`\`\`bash
+git fetch origin
+git rebase origin/${base || 'main'}
+\`\`\`
+Git will stop at each conflict. Do NOT abort.
+
+### Step 5 — Resolve each conflict block
+Open the file with the Read tool. Find \`<<<<<<< HEAD\` blocks.
+
+Rules:
+- \`<<<<<<< HEAD\` = YOUR code (this task)
+- \`>>>>>>> ...\` = THEIR code (merged into ${base || 'main'})
+- NEVER blindly pick one side — read both task goals first
+- If both changes are needed, combine them
+- If they solve the same problem differently, keep the better implementation
+
+Use the Edit tool to resolve. The final file must have ZERO conflict markers.
+
+### Step 6 — Request approval before force-push (if shared branch)
+If \`conflictingTasks\` is non-empty (another developer's branch overlaps):
+\`\`\`
+request_human_input(
+  taskId="${taskId}",
+  question="I've resolved all conflict markers. Ready to run: git push --force-with-lease. This will overwrite the remote branch. Approve?",
+  context="Conflicts were with: <other task keys>. Files changed: <list>",
+  type="approval"
+)
+\`\`\`
+The question appears in Cursor chat. STOP and wait for the developer to reply "yes"/"approved" before pushing.
+If no overlapping active tasks, push directly (low risk — only your branch).
+
+### Step 7 — Push and verify
+\`\`\`bash
+git add <resolved-files>
+git rebase --continue
+# Repeat Step 5 for each conflict
+git push --force-with-lease
+\`\`\`
+\`\`\`
+check_merge_conflicts(taskId="${taskId}")  → must return status: 'clean'
+run-tests skill                            → must pass
+log_session_event(type="info", name="conflict-resolved", summary="<what you merged and why>")
+\`\`\`
+`
+    writeFileSync(join(skillsDir, 'resolve-conflict.md'), resolveConflictSkill, 'utf8')
+    written.push(join(skillsDir, 'resolve-conflict.md'))
+
     // ── 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')
@@ -3382,6 +4375,40 @@ function trackTaskActivity(taskId, toolName, opts = {}) {
   }).catch(() => {})
 }
 
+/**
+ * Role-based tool access guard.
+ * Checks the task's active agentRole against the project's agentConfig.roles[].allowedTools.
+ * Returns an errorText response if the tool is blocked, null if it is allowed.
+ * - No agentRole set on the task → allow (unrestricted session)
+ * - Role found but allowedTools is empty → allow (empty = no restrictions)
+ * - Tool name not in allowedTools → block with clear message
+ */
+async function guardRoleTool(taskId, toolName) {
+  if (!taskId) return null
+  try {
+    const taskRes = await api.get(`/api/tasks/${taskId}`)
+    if (!taskRes?.success) return null
+    const task = taskRes.data.task
+    if (!task.agentRole) return null
+
+    const projRes = await api.get(`/api/projects/${task.project}`)
+    if (!projRes?.success) return null
+    const roleConfig = (projRes.data.project?.agentConfig?.roles || [])
+      .find(r => r.name === task.agentRole)
+    if (!roleConfig || !roleConfig.allowedTools?.length) return null
+
+    if (!roleConfig.allowedTools.includes(toolName)) {
+      return errorText(
+        `Permission denied — role '${task.agentRole}' is not allowed to call '${toolName}'.\n` +
+        `Allowed tools for this role: ${roleConfig.allowedTools.join(', ')}`
+      )
+    }
+  } catch {
+    // guard failure is non-blocking — never crash the tool
+  }
+  return null
+}
+
 /** Delete the task-specific cursor rules file when work is complete. */
 function deleteCursorRulesFile(taskKey, startPath) {
   try {
@@ -4979,6 +6006,2134 @@ Use this when the developer says "clean up branches", "delete merged branches",
   )
 }
 
+// ── Merge Pipeline AI Tools ───────────────────────────────────────────────────
+// Tools that give AI agents a full understanding of the git merge pipeline
+// and guide developers + reviewers through shipping safely.
+function registerMergePipelineTools(server, { scopedProjectId } = {}) {
+
+  // ── get_branch_pipeline_status ────────────────────────────────────────────
+  server.tool(
+    'get_branch_pipeline_status',
+    `Get the full merge pipeline status for a project so an AI agent can understand every developer's branch state.
+
+Returns the suggested merge order, each branch's behind/ahead commit counts, conflict pairs (tasks touching the same files),
+and a plain-English summary of what each developer needs to do before they can merge.
+
+Use this tool FIRST when a developer asks "what do I need to do to merge?" or when a reviewer asks "which PRs are safe to merge?"
+Always call this before guide_my_merge or assess_review_readiness to orient yourself.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+    },
+    async ({ projectId }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      try {
+        const res = await api.get(`/api/projects/${projectId}/github/git-tree`)
+        if (!res?.success) return errorText('Could not fetch git tree data')
+
+        const { branches = [], defaultBranch = 'main', baseBranchCommits = [], fetchedAt } = res.data
+
+        // Compute conflict pairs
+        const conflictPairs = []
+        for (let i = 0; i < branches.length; i++) {
+          for (let j = i + 1; j < branches.length; j++) {
+            const shared = (branches[i].claimedFiles || []).filter(f => (branches[j].claimedFiles || []).includes(f))
+            if (shared.length) conflictPairs.push({ a: branches[i], b: branches[j], sharedFiles: shared })
+          }
+        }
+
+        // Compute conflict counts
+        const conflictCount = {}
+        branches.forEach(b => { conflictCount[b.taskId] = 0 })
+        conflictPairs.forEach(({ a, b }) => { conflictCount[a.taskId]++; conflictCount[b.taskId]++ })
+
+        // Merge order: fewest conflicts → least behind → most ahead
+        const ordered = [...branches]
+          .filter(b => !b.branchError)
+          .sort((a, b) => {
+            const c = (conflictCount[a.taskId] || 0) - (conflictCount[b.taskId] || 0)
+            if (c) return c
+            const bd = (a.compare?.behindBy ?? 99) - (b.compare?.behindBy ?? 99)
+            if (bd) return bd
+            return (b.compare?.aheadBy ?? 0) - (a.compare?.aheadBy ?? 0)
+          })
+
+        // Build per-branch guidance summary
+        const pipeline = ordered.map((b, idx) => {
+          const rank    = idx + 1
+          const behind  = b.compare?.behindBy || 0
+          const ahead   = b.compare?.aheadBy  || 0
+          const myConflicts = conflictPairs
+            .filter(p => p.a.taskId === b.taskId || p.b.taskId === b.taskId)
+            .map(p => ({
+              partnerKey:   p.a.taskId === b.taskId ? p.b.taskKey : p.a.taskKey,
+              sharedFiles:  p.sharedFiles,
+            }))
+          const blockedBy = myConflicts
+            .map(c => c.partnerKey)
+            .filter(key => ordered.slice(0, idx).some(ob => ob.taskKey === key))
+
+          let situation = ''
+          let nextAction = ''
+
+          if (blockedBy.length > 0) {
+            situation   = `BLOCKED — conflicts with ${blockedBy.join(', ')} which rank higher in merge order.`
+            nextAction  = `Wait for ${blockedBy.join(' and ')} to merge first. Coordinate via ping to agree on who refactors the shared files.`
+          } else if (behind > 0 && myConflicts.length > 0) {
+            situation   = `NEEDS REBASE + has ${myConflicts.length} file conflict(s).`
+            nextAction  = `Rebase onto ${defaultBranch} first (git fetch origin && git rebase origin/${defaultBranch}), resolve conflicts in shared files, then push.`
+          } else if (behind > 0) {
+            situation   = `BEHIND by ${behind} commit${behind !== 1 ? 's' : ''} — ${defaultBranch} has moved since this branch was created.`
+            nextAction  = `Run: git fetch origin && git rebase origin/${defaultBranch}. Fix any conflicts, then git push --force-with-lease.`
+          } else if (!b.prNumber) {
+            situation   = `UP TO DATE — ${ahead} commit${ahead !== 1 ? 's' : ''} ready to ship. No PR open yet.`
+            nextAction  = `Open a pull request targeting ${defaultBranch} to start the review process.`
+          } else if (rank === 1) {
+            situation   = `READY TO MERGE — ranked #1, no blockers, PR #${b.prNumber} open.`
+            nextAction  = `Get PR approved and merge when reviews are complete.`
+          } else {
+            situation   = `WAITING — rank #${rank}. PR open but waiting for higher-ranked tasks to merge first.`
+            nextAction  = `Monitor the pipeline. After tasks ranked #1–${rank - 1} merge, rebase if needed and get review.`
+          }
+
+          return {
+            rank,
+            taskKey:      b.taskKey,
+            taskTitle:    b.taskTitle,
+            taskId:       b.taskId,
+            branch:       b.headBranch,
+            assignees:    b.assignees.map(a => a.name).join(', ') || 'Unassigned',
+            status:       b.statusColor,
+            behind,
+            ahead,
+            prNumber:     b.prNumber || null,
+            prUrl:        b.prUrl    || null,
+            conflicts:    myConflicts,
+            blockedBy,
+            situation,
+            nextAction,
+          }
+        })
+
+        const readySummary   = pipeline.filter(b => b.blockedBy.length === 0 && b.behind === 0 && b.prNumber)
+        const behindSummary  = pipeline.filter(b => b.behind > 0)
+        const blockedSummary = pipeline.filter(b => b.blockedBy.length > 0)
+
+        return text({
+          defaultBranch,
+          fetchedAt,
+          totalBranches: branches.length,
+          mergeOrder:    pipeline,
+          summary: {
+            readyToMerge:   readySummary.map(b => `${b.taskKey} (#${b.rank})`).join(', ') || 'None',
+            needsRebase:    behindSummary.map(b => `${b.taskKey} (${b.behind} behind)`).join(', ') || 'None',
+            blocked:        blockedSummary.map(b => `${b.taskKey} blocked by ${b.blockedBy.join(', ')}`).join('; ') || 'None',
+            conflictPairs:  conflictPairs.map(p => `${p.a.taskKey} ↔ ${p.b.taskKey}: ${p.sharedFiles.join(', ')}`),
+          },
+          agentInstruction: 'To guide a specific developer, call guide_my_merge with their taskId. To review a PR, call assess_review_readiness with the taskId.',
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── guide_my_merge ────────────────────────────────────────────────────────
+  server.tool(
+    'guide_my_merge',
+    `Generate a complete, personalized step-by-step merge guide for a specific developer's branch.
+
+Call get_branch_pipeline_status first to find the taskId.
+Then call this tool to get the exact git commands the developer needs to run — in order — to rebase, resolve conflicts, and ship their work without losing any changes.
+
+The guide is safe to follow verbatim:
+- It checks local state before suggesting stash/commit
+- It never suggests force-push without --force-with-lease
+- It accounts for conflict files shared with other tasks
+- It ends with the exact next human action (open PR / request review / wait)
+
+Use this when a developer asks: "what do I do?", "how do I rebase?", "I have conflicts", "how do I ship this?", "I'm stuck"`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      taskId:    z.string().describe("Task's MongoDB ObjectId (get from get_branch_pipeline_status)"),
+      repoPath:  z.string().optional().describe('Absolute path to the developer\'s local git repo'),
+    },
+    async ({ projectId, taskId, repoPath }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      try {
+        // Fetch pipeline data + task detail in parallel
+        const [treeRes, taskRes] = await Promise.all([
+          api.get(`/api/projects/${projectId}/github/git-tree`),
+          api.get(`/api/tasks/${taskId}`),
+        ])
+        if (!treeRes?.success) return errorText('Could not fetch git tree')
+
+        const { branches = [], defaultBranch = 'main' } = treeRes.data
+        const branch = branches.find(b => b.taskId === taskId)
+        if (!branch) return errorText(`Task ${taskId} not found in active branches. Make sure it is In Progress or In Review with a branch set.`)
+
+        const task   = taskRes?.data?.task || {}
+        const behind = branch.compare?.behindBy || 0
+        const ahead  = branch.compare?.aheadBy  || 0
+
+        // Conflict pairs involving this branch
+        const conflictPairs = []
+        for (const ob of branches) {
+          if (ob.taskId === taskId) continue
+          const shared = (branch.claimedFiles || []).filter(f => (ob.claimedFiles || []).includes(f))
+          if (shared.length) conflictPairs.push({ partnerKey: ob.taskKey, partnerBranch: ob.headBranch, sharedFiles: shared })
+        }
+
+        // Check local git state if repoPath provided
+        let localState = null
+        const cwd = repoPath || process.cwd()
+        const repoRoot = findRepoRoot(cwd)
+        if (repoRoot) {
+          try {
+            const porcelain = runGit('status --porcelain=v1', repoRoot)
+            const currentBranch = runGit('branch --show-current', repoRoot)
+            const { localState: ls, modified, staged } = parseGitStatus(porcelain)
+            localState = { state: ls, currentBranch, modifiedCount: modified.length, stagedCount: staged.length }
+          } catch { /* git unavailable */ }
+        }
+
+        // Build the step-by-step guide
+        const steps = []
+        let stepNum = 1
+
+        // Step 0: Save work if needed
+        if (localState && localState.state !== 'clean') {
+          if (localState.state === 'modified' || localState.state === 'staged') {
+            steps.push({
+              step: stepNum++,
+              title: 'Save your current work',
+              why: `You have ${localState.modifiedCount + localState.stagedCount} unsaved change(s). You must stash or commit before rebasing, or git will refuse (or worse, silently mix changes).`,
+              commands: [
+                { label: 'Option A — stash (temporary, reversible)', cmd: `git stash push -m "wip: ${branch.taskKey} before rebase"` },
+                { label: 'Option B — commit (permanent, survives crashes)', cmd: `git add -A && git commit -m "chore: wip checkpoint before rebase [${branch.taskKey}]"` },
+              ],
+              note: 'If you stash, you will pop it back in step 4. Commit is safer if your machine might restart.',
+            })
+          }
+        }
+
+        // Step 1: Switch to task branch (if not already on it)
+        const targetBranch = branch.headBranch
+        steps.push({
+          step: stepNum++,
+          title: `Switch to your task branch`,
+          why: `All changes must be on branch "${targetBranch}" — not on ${defaultBranch} or another branch.`,
+          commands: [
+            { label: 'Check out your branch', cmd: `git checkout ${targetBranch}` },
+          ],
+        })
+
+        // Step 2: Fetch latest
+        steps.push({
+          step: stepNum++,
+          title: `Fetch the latest from GitHub`,
+          why: `Your local copy of origin/${defaultBranch} might be stale. This downloads new commits without changing your files yet.`,
+          commands: [
+            { label: 'Fetch all remotes', cmd: `git fetch origin` },
+          ],
+        })
+
+        if (behind > 0) {
+          // Step 3: Rebase
+          steps.push({
+            step: stepNum++,
+            title: `Rebase onto ${defaultBranch} (${behind} new commit${behind !== 1 ? 's' : ''} to include)`,
+            why: `${defaultBranch} has ${behind} commit${behind !== 1 ? 's' : ''} your branch does not have. Rebase replays your commits on top of the latest ${defaultBranch}, keeping history clean. This is safer than a merge for feature branches.`,
+            commands: [
+              { label: 'Rebase onto latest main', cmd: `git rebase origin/${defaultBranch}` },
+            ],
+            note: conflictPairs.length > 0
+              ? `⚠️  You share files with ${conflictPairs.map(c => c.partnerKey).join(', ')}. If rebase stops with conflicts, follow the next step.`
+              : 'If rebase completes with no conflicts, skip straight to step ' + (stepNum + 1) + '.',
+          })
+
+          // Step 4: Conflict resolution (if any)
+          if (conflictPairs.length > 0) {
+            const allConflictFiles = [...new Set(conflictPairs.flatMap(c => c.sharedFiles))]
+            steps.push({
+              step: stepNum++,
+              title: 'Resolve conflicts (if rebase stops)',
+              why: `Your branch touches the same files as ${conflictPairs.map(c => c.partnerKey).join(' and ')}. If those files were changed in ${defaultBranch}, git will pause and ask you to decide which changes to keep.`,
+              commands: [
+                { label: 'Open conflict file(s) and fix the markers', cmd: `# Edit these files and remove <<<<<<, =======, >>>>>>> markers:\n${allConflictFiles.map(f => `# ${f}`).join('\n')}` },
+                { label: 'Stage each resolved file', cmd: `git add ${allConflictFiles.join(' ')}` },
+                { label: 'Continue the rebase', cmd: `git rebase --continue` },
+                { label: 'If things go wrong, abort and start over', cmd: `git rebase --abort` },
+              ],
+              note: 'Keep YOUR changes for files you own. Merge carefully for shared files — check what your partner changed before discarding.',
+            })
+          }
+        }
+
+        // Step: Pop stash if stashed
+        if (localState && localState.state !== 'clean') {
+          steps.push({
+            step: stepNum++,
+            title: 'Restore your work in progress (if you stashed)',
+            why: 'Pop your stash to get your unsaved changes back on top of the rebased branch.',
+            commands: [
+              { label: 'Pop the stash', cmd: `git stash pop` },
+            ],
+            note: 'If stash pop causes conflicts (your wip vs the rebased code), resolve them the same way as above.',
+          })
+        }
+
+        // Step: Push
+        steps.push({
+          step: stepNum++,
+          title: 'Push to GitHub',
+          why: 'After a rebase, your local commit history has been rewritten. You must force-push — but use --force-with-lease which refuses to overwrite if someone else pushed in the meantime (safety net).',
+          commands: [
+            { label: 'Safe force push', cmd: `git push origin ${targetBranch} --force-with-lease` },
+          ],
+          note: 'NEVER use --force without --with-lease. --force-with-lease is safe because it aborts if another push happened.',
+        })
+
+        // Step: PR
+        if (!branch.prNumber) {
+          steps.push({
+            step: stepNum++,
+            title: `Open a pull request`,
+            why: `You have ${ahead} commit${ahead !== 1 ? 's' : ''} ready to ship but no PR open. A PR is how your code gets reviewed and merged into ${defaultBranch}.`,
+            commands: [
+              { label: 'Open a PR via GitHub CLI', cmd: `gh pr create --base ${defaultBranch} --head ${targetBranch} --title "${task.title || branch.taskKey}" --body "Closes #${branch.taskKey}"` },
+            ],
+            note: 'Or go to GitHub and click "Compare & pull request" — GitHub shows this banner automatically after a push.',
+          })
+        } 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.`,
+            commands: [
+              { label: 'Request review via GitHub CLI', cmd: `gh pr review ${branch.prNumber} --request-changes` },
+            ],
+            note: `PR URL: ${branch.prUrl || 'see GitHub'}`,
+          })
+        }
+
+        // Compile quick-copy block
+        const quickCommands = steps
+          .flatMap(s => s.commands.map(c => c.cmd))
+          .filter(cmd => !cmd.startsWith('#'))
+
+        return text({
+          taskKey:       branch.taskKey,
+          taskTitle:     branch.taskTitle,
+          branch:        targetBranch,
+          assignees:     branch.assignees.map(a => a.name).join(', '),
+          defaultBranch,
+          situation: {
+            behind,
+            ahead,
+            hasConflicts:  conflictPairs.length > 0,
+            conflictsWith: conflictPairs.map(c => c.partnerKey),
+            prNumber:      branch.prNumber || null,
+            localState:    localState?.state || 'unknown',
+          },
+          guide: steps,
+          quickCopy: {
+            description: 'Run these commands in order (skip lines starting with #)',
+            commands: quickCommands,
+            asOneLiner: quickCommands.join(' && '),
+          },
+          agentInstruction: `Walk the developer through each step in order. Paste the command for each step, explain what it does, and wait for them to confirm before moving to the next step. If they hit an error, diagnose it before continuing.`,
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── assess_review_readiness ───────────────────────────────────────────────
+  server.tool(
+    'assess_review_readiness',
+    `Assess whether a PR is ready for code review and safe to merge — for AI code reviewers and human reviewers.
+
+Returns a structured reviewer checklist covering:
+- Merge safety: is the branch up to date with the default branch? Will it cause conflicts?
+- Pipeline position: is this the right branch to merge next?
+- Code change context: what files changed, what the task was trying to accomplish
+- Risk indicators: stale branch, shared files with other tasks, no rebase done
+
+Call get_branch_pipeline_status first to find the taskId and check merge order.
+Then call get_review_bundle for the actual code diff.
+Use this tool between those two to understand the merge context.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+    },
+    async ({ projectId, taskId }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      try {
+        const [treeRes, taskRes] = await Promise.all([
+          api.get(`/api/projects/${projectId}/github/git-tree`),
+          api.get(`/api/tasks/${taskId}`),
+        ])
+        if (!treeRes?.success) return errorText('Could not fetch git tree')
+
+        const { branches = [], defaultBranch = 'main' } = treeRes.data
+        const branch = branches.find(b => b.taskId === taskId)
+        if (!branch) return errorText(`Task ${taskId} not found in active branches`)
+
+        const task = taskRes?.data?.task || {}
+        const behind = branch.compare?.behindBy || 0
+        const ahead  = branch.compare?.aheadBy  || 0
+
+        // Find merge order rank
+        const conflictCount = {}
+        branches.forEach(b => { conflictCount[b.taskId] = 0 })
+        const allConflictPairs = []
+        for (let i = 0; i < branches.length; i++) {
+          for (let j = i + 1; j < branches.length; j++) {
+            const shared = (branches[i].claimedFiles || []).filter(f => (branches[j].claimedFiles || []).includes(f))
+            if (shared.length) {
+              allConflictPairs.push({ a: branches[i], b: branches[j], sharedFiles: shared })
+              conflictCount[branches[i].taskId]++
+              conflictCount[branches[j].taskId]++
+            }
+          }
+        }
+        const ordered = [...branches]
+          .filter(b => !b.branchError)
+          .sort((a, b) => {
+            const c = (conflictCount[a.taskId] || 0) - (conflictCount[b.taskId] || 0)
+            if (c) return c
+            return (a.compare?.behindBy ?? 99) - (b.compare?.behindBy ?? 99)
+          })
+        const rank = ordered.findIndex(b => b.taskId === taskId) + 1
+
+        const myConflicts = allConflictPairs
+          .filter(p => p.a.taskId === taskId || p.b.taskId === taskId)
+          .map(p => ({
+            partnerKey: p.a.taskId === taskId ? p.b.taskKey : p.a.taskKey,
+            sharedFiles: p.sharedFiles,
+          }))
+
+        const blockedBy = myConflicts
+          .map(c => c.partnerKey)
+          .filter(key => ordered.slice(0, rank - 1).some(ob => ob.taskKey === key))
+
+        // Staleness check
+        const lastCommitDate = branch.tipCommit?.date ? new Date(branch.tipCommit.date) : null
+        const hoursSinceCommit = lastCommitDate
+          ? Math.round((Date.now() - lastCommitDate.getTime()) / 3600000)
+          : null
+        const isStale = hoursSinceCommit !== null && hoursSinceCommit >= 48
+
+        // Build checklist
+        const checklist = [
+          {
+            item:   'Branch is up to date with ' + defaultBranch,
+            passed: behind === 0,
+            detail: behind === 0
+              ? 'Branch is current — no rebase needed before merge'
+              : `Branch is ${behind} commit${behind !== 1 ? 's' : ''} behind ${defaultBranch}. Developer must rebase before this can be safely merged.`,
+            blocking: behind > 0,
+          },
+          {
+            item:   'No file conflicts with other active branches',
+            passed: myConflicts.length === 0,
+            detail: myConflicts.length === 0
+              ? 'No other branches touch the same files'
+              : `Shares files with: ${myConflicts.map(c => `${c.partnerKey} (${c.sharedFiles.join(', ')})`).join('; ')}`,
+            blocking: blockedBy.length > 0,
+          },
+          {
+            item:   'Correct merge order position',
+            passed: rank === 1 || blockedBy.length === 0,
+            detail: rank === 1
+              ? 'This is the #1 ranked branch — first in line to merge'
+              : blockedBy.length > 0
+                ? `This branch is BLOCKED — must wait for ${blockedBy.join(', ')} to merge first (rank #${rank})`
+                : `Ranked #${rank} — no blockers currently, but ${rank - 1} higher-ranked task${rank > 2 ? 's' : ''} should merge first`,
+            blocking: blockedBy.length > 0,
+          },
+          {
+            item:   'Branch has commits to merge',
+            passed: ahead > 0,
+            detail: ahead > 0
+              ? `${ahead} commit${ahead !== 1 ? 's' : ''} ready to merge into ${defaultBranch}`
+              : 'No commits ahead of main — nothing to merge',
+            blocking: ahead === 0,
+          },
+          {
+            item:   'Pull request is open',
+            passed: !!branch.prNumber,
+            detail: branch.prNumber
+              ? `PR #${branch.prNumber} is open: ${branch.prUrl}`
+              : 'No PR open — developer needs to create one before review can proceed',
+            blocking: !branch.prNumber,
+          },
+          {
+            item:   'Branch not stale',
+            passed: !isStale,
+            detail: isStale
+              ? `Last commit was ${hoursSinceCommit} hours ago — branch may be abandoned or developer is stuck. Check in with them.`
+              : lastCommitDate
+                ? `Last commit ${hoursSinceCommit} hours ago — active`
+                : 'No commit data available',
+            blocking: false,
+          },
+        ]
+
+        const blockingIssues = checklist.filter(c => !c.passed && c.blocking)
+        const warnings       = checklist.filter(c => !c.passed && !c.blocking)
+        const passed         = checklist.filter(c => c.passed)
+
+        const overallReady = blockingIssues.length === 0
+
+        return text({
+          taskKey:      branch.taskKey,
+          taskTitle:    branch.taskTitle,
+          branch:       branch.headBranch,
+          assignees:    branch.assignees.map(a => a.name).join(', '),
+          prNumber:     branch.prNumber || null,
+          prUrl:        branch.prUrl    || null,
+          defaultBranch,
+          mergeRank:    rank,
+          overallReady,
+          verdict:      overallReady
+            ? `✅ READY — ${branch.taskKey} can proceed to merge review. Check the code diff next with get_review_bundle.`
+            : `❌ NOT READY — ${blockingIssues.length} blocking issue${blockingIssues.length !== 1 ? 's' : ''} must be resolved first.`,
+          checklist: { blocking: blockingIssues, warnings, passed },
+          stats:     { behind, ahead, conflictCount: myConflicts.length, rank, isStale },
+          agentInstruction: overallReady
+            ? 'Call get_review_bundle next to get the full code diff and plan for review. Then call submit_ai_review with your findings.'
+            : `Tell the developer the blocking issues and call guide_my_merge to walk them through resolving them step by step.`,
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── get_pipeline_report ───────────────────────────────────────────────────
+  server.tool(
+    'get_pipeline_report',
+    `Generate a concise team pipeline status report for a standup, sprint review, or engineering lead briefing.
+
+Returns a plain-English summary: how many branches are active, which are ready to merge, which need rebase, which are blocked, and a per-developer one-liner with their current status.
+
+Use this when asked: "what is the current state of the pipeline?", "who is blocked?", "is anything ready to merge today?", "give me the standup report".
+
+Call this instead of get_branch_pipeline_status when you need a narrative summary rather than raw structured data.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+    },
+    async ({ projectId }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      try {
+        const res = await api.get(`/api/projects/${projectId}/github/git-tree`)
+        if (!res?.success) return errorText('Could not fetch git tree data')
+
+        const { branches = [], defaultBranch = 'main', fetchedAt } = res.data
+
+        const conflictPairs = []
+        for (let i = 0; i < branches.length; i++) {
+          for (let j = i + 1; j < branches.length; j++) {
+            const shared = (branches[i].claimedFiles || []).filter(f => (branches[j].claimedFiles || []).includes(f))
+            if (shared.length) conflictPairs.push({ a: branches[i], b: branches[j], sharedFiles: shared })
+          }
+        }
+        const conflictCount = {}
+        branches.forEach(b => { conflictCount[b.taskId] = 0 })
+        conflictPairs.forEach(({ a, b }) => { conflictCount[a.taskId]++; conflictCount[b.taskId]++ })
+
+        const ordered = [...branches].filter(b => !b.branchError).sort((a, b) => {
+          const c = (conflictCount[a.taskId] || 0) - (conflictCount[b.taskId] || 0)
+          if (c) return c
+          const bd = (a.compare?.behindBy ?? 99) - (b.compare?.behindBy ?? 99)
+          if (bd) return bd
+          return (b.compare?.aheadBy ?? 0) - (a.compare?.aheadBy ?? 0)
+        })
+
+        const readyToMerge = ordered.filter(b => (b.compare?.behindBy || 0) === 0 && b.prNumber && conflictCount[b.taskId] === 0)
+        const needsRebase  = ordered.filter(b => (b.compare?.behindBy || 0) > 0)
+        const hasConflicts = ordered.filter(b => conflictCount[b.taskId] > 0)
+        const noPR         = ordered.filter(b => !b.prNumber && (b.compare?.aheadBy || 0) > 0 && (b.compare?.behindBy || 0) === 0)
+        const noData       = branches.filter(b => b.branchError)
+
+        const devLines = ordered.map((b, idx) => {
+          const behind = b.compare?.behindBy || 0
+          const ahead  = b.compare?.aheadBy  || 0
+          const dev    = b.assignees.map(a => a.name).join('/') || 'Unassigned'
+          const cc     = conflictCount[b.taskId] || 0
+          let s = ''
+          if (behind > 0 && cc > 0) s = `⛔ Needs rebase (${behind} behind) + ${cc} conflict(s)`
+          else if (behind > 0)      s = `🟡 Needs rebase — ${behind} commit${behind !== 1 ? 's' : ''} behind ${defaultBranch}`
+          else if (cc > 0)          s = `🔴 File conflict with ${conflictPairs.filter(p => p.a.taskId === b.taskId || p.b.taskId === b.taskId).map(p => p.a.taskId === b.taskId ? p.b.taskKey : p.a.taskKey).join(', ')}`
+          else if (!b.prNumber)     s = `🔵 Up to date, ${ahead} commit${ahead !== 1 ? 's' : ''} — needs PR`
+          else                      s = `✅ Ready — PR #${b.prNumber} (rank #${idx + 1})`
+          return `  ${b.taskKey} [${dev}]: ${s}`
+        })
+
+        const lines = [
+          `# Pipeline Report — ${new Date(fetchedAt || Date.now()).toUTCString()}`,
+          `Default branch: ${defaultBranch} | Active branches: ${ordered.length}${noData.length ? ` (${noData.length} unavailable)` : ''}`,
+          '',
+          `## Summary`,
+          `- ✅ Ready to merge: ${readyToMerge.length} — ${readyToMerge.map(b => b.taskKey).join(', ') || 'none'}`,
+          `- 🟡 Needs rebase:   ${needsRebase.length} — ${needsRebase.map(b => `${b.taskKey}(↓${b.compare?.behindBy})`).join(', ') || 'none'}`,
+          `- 🔴 Has conflicts:  ${hasConflicts.length} — ${hasConflicts.map(b => b.taskKey).join(', ') || 'none'}`,
+          `- 🔵 Needs PR:       ${noPR.length} — ${noPR.map(b => b.taskKey).join(', ') || 'none'}`,
+          '',
+          `## Conflict pairs`,
+          ...(conflictPairs.length === 0
+            ? ['  None']
+            : conflictPairs.map(p => `  ${p.a.taskKey} ↔ ${p.b.taskKey}: ${p.sharedFiles.join(', ')}`)),
+          '',
+          `## Per-developer status (merge order)`,
+          ...devLines,
+          '',
+          `## Suggested next actions`,
+          ...[
+            readyToMerge.length > 0 ? `- Merge ${readyToMerge[0].taskKey} first (PR #${readyToMerge[0].prNumber}) — call assess_review_readiness then get_review_bundle` : '',
+            needsRebase.length > 0  ? `- Ask ${[...new Set(needsRebase.flatMap(b => b.assignees.map(a => a.name)))].filter(Boolean).join(', ')} to rebase — call guide_my_merge for each` : '',
+            hasConflicts.length > 0 ? `- Coordinate conflicts: ${conflictPairs.map(p => `${p.a.taskKey} ↔ ${p.b.taskKey}`).join('; ')} — call coordinate_conflict` : '',
+          ].filter(Boolean),
+        ].join('\n')
+
+        return text({
+          report: lines,
+          stats: { total: ordered.length, readyToMerge: readyToMerge.length, needsRebase: needsRebase.length, hasConflicts: hasConflicts.length, needsPR: noPR.length, unavailable: noData.length },
+          mergeOrder: ordered.map(b => b.taskKey),
+          agentInstruction: readyToMerge.length > 0
+            ? `Start with ${readyToMerge[0].taskKey} — call assess_review_readiness then get_review_bundle.`
+            : needsRebase.length > 0
+              ? `No branches ready yet. Call guide_my_merge for ${needsRebase[0].taskKey} to unblock first.`
+              : 'Pipeline is clear — monitor for new pushes.',
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── coordinate_conflict ───────────────────────────────────────────────────
+  server.tool(
+    'coordinate_conflict',
+    `Send a structured conflict resolution coordination message between two developers whose branches share files.
+
+The sender declares who will refactor the shared files — either "I will handle it" (resolver="me") or "Please handle it" (resolver="them").
+
+This posts a comment on the target task and sends a push notification with a clear, actionable message:
+- resolver="me": posts on the partner's task: "Dev A will refactor the shared files — wait for their merge"
+- resolver="them": posts on the partner's task: "Please refactor the shared files before merging"
+
+Call get_branch_pipeline_status first to identify the conflicting taskIds and sharedFiles.
+Use this when two branches have file conflicts and you need to establish who will resolve them before either can merge.`,
+    {
+      projectId:  z.string().describe("Project's MongoDB ObjectId"),
+      fromTaskId: z.string().describe('The task ID of the developer initiating the coordination'),
+      toTaskId:   z.string().describe('The task ID of the developer being coordinated with'),
+      resolver:   z.enum(['me', 'them']).describe('"me" = I will refactor the shared files; "them" = asking them to refactor'),
+      sharedFiles: z.array(z.string()).optional().describe('List of files both branches touch'),
+      note:        z.string().optional().describe('Optional message to include in the coordination comment'),
+    },
+    async ({ projectId, fromTaskId, toTaskId, resolver, sharedFiles = [], note = '' }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      try {
+        const res = await api.post(`/api/projects/${projectId}/git-tree/coordinate-conflict`, {
+          fromTaskId, toTaskId, resolver, sharedFiles, note,
+        })
+        if (!res?.success) return errorText(res?.message || 'Coordination failed')
+        const { fromTaskKey, toTaskKey } = res.data
+        return text({
+          coordinated: true,
+          resolver,
+          summary: resolver === 'me'
+            ? `${fromTaskKey} claimed responsibility — will refactor shared files. ${toTaskKey} should wait and rebase after ${fromTaskKey} merges.`
+            : `${toTaskKey} has been asked to refactor the shared files. They need to confirm and handle it before either branch merges.`,
+          nextStep: resolver === 'me'
+            ? `${fromTaskKey} should now refactor the shared files, push, and merge. ${toTaskKey} then rebases.`
+            : `Wait for ${toTaskKey} to confirm they will handle it. Follow up if no response within a day.`,
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+}
+
+// ── Memory Tools ──────────────────────────────────────────────────────────────
+function registerMemoryTools(server, ctx) {
+  const { scopedProjectId } = ctx
+
+  // ── remember ──────────────────────────────────────────────────────────────
+  server.tool(
+    'remember',
+    `Store a persistent key-value memory entry on a task. This memory survives across Cursor sessions and is recalled automatically at the start of every get_workspace_briefing call.
+
+Use this to remember decisions, constraints, context, and findings that should persist between working sessions:
+- Architecture decisions: remember(taskId, "arch_decision", "Using optimistic locking for inventory")
+- Constraints: remember(taskId, "constraint_auth", "Must not modify auth middleware — it's frozen")
+- Discoveries: remember(taskId, "discovered", "The cache invalidation happens in utils/cache.js:87")
+- Status: remember(taskId, "status", "Blocked on API design — waiting for review")
+
+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")'),
+      value:  z.string().describe('Value to store — plain text, any length'),
+    },
+    async ({ taskId, key, value }) => {
+      try {
+        const res = await api.put(`/api/tasks/${taskId}/agent-memory`, { key, value })
+        if (!res?.success) return errorText(res?.message || 'Failed to save memory')
+        return text({ remembered: true, key, value, hint: 'Saved. Call recall(taskId) to verify.' })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── recall ────────────────────────────────────────────────────────────────
+  server.tool(
+    'recall',
+    `Retrieve all persistent memory entries stored on a task via remember().
+
+Returns a key-value map of everything previously remembered. Call this at the start of a session to restore context — or use get_workspace_briefing which calls this automatically.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+    },
+    async ({ taskId }) => {
+      try {
+        const res = await api.get(`/api/tasks/${taskId}/agent-memory`)
+        if (!res?.success) return errorText(res?.message || 'Failed to retrieve memory')
+        const { memory } = res.data
+        const keys = Object.keys(memory)
+        if (keys.length === 0) return text({ memory: {}, hint: 'No memory stored yet. Use remember() to save context.' })
+        const formatted = keys.map(k => `  ${k}: ${memory[k]}`).join('\n')
+        return text({ memory, formatted: `Recalled ${keys.length} entr${keys.length === 1 ? 'y' : 'ies'}:\n${formatted}` })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── get_workspace_briefing ────────────────────────────────────────────────
+  server.tool(
+    'get_workspace_briefing',
+    `Comprehensive session-start briefing — the single tool to call at the beginning of every Cursor session on a task.
+
+Returns everything an agent needs to resume without re-reading the full codebase:
+1. Task details: title, description, readme plan, column, assignees
+2. Persistent memory recalled from previous sessions
+3. Active sub-agent sessions and their findings
+4. Files currently claimed by this task
+5. Branch status: behind/ahead counts, PR status
+6. Recent session log entries (last 10 tool calls)
+7. Teammate activity: which tasks share your files or are nearby in the pipeline
+
+Always call this first — it collapses context from the last 3 steps into one call.`,
+    {
+      taskId:   z.string().describe("Task's MongoDB ObjectId"),
+      repoPath: z.string().optional().describe('Absolute path to the local git repo — used to detect local branch state'),
+    },
+    async ({ taskId, repoPath }) => {
+      try {
+        // Task + project
+        const taskRes = await api.get(`/api/tasks/${taskId}`)
+        if (!taskRes?.success) return errorText(`Task not found: ${taskId}`)
+        const task    = taskRes.data.task
+        const projRes = await api.get(`/api/projects/${task.project}`)
+        const proj    = projRes?.data?.project || {}
+
+        // Memory
+        const memRes  = await api.get(`/api/tasks/${taskId}/agent-memory`)
+        const memory  = memRes?.data?.memory || {}
+
+        // Sessions
+        const sessRes = await api.get(`/api/tasks/${taskId}/agent-sessions`)
+        const sessions = (sessRes?.data?.sessions || []).slice(-5)
+
+        // Local branch state
+        let localState = null
+        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()
+            localState = { branch, dirty: status.length > 0, lastCommit: logLine }
+          } catch { localState = { error: 'Could not read local git state' } }
+        }
+
+        const memKeys = Object.keys(memory)
+        const memLines = memKeys.length > 0
+          ? memKeys.map(k => `  ${k}: ${memory[k]}`).join('\n')
+          : '  (none)'
+
+        const sessionLines = sessions.length > 0
+          ? sessions.map(s => `  [${s.status.toUpperCase()}] ${s.role}: ${s.mission}${s.summary ? ` → ${s.summary}` : ''}`).join('\n')
+          : '  (none)'
+
+        const recentLog = (task.agentSessionLog || []).slice(-10)
+          .map(e => `  ${new Date(e.calledAt).toISOString().slice(11, 19)} ${e.type}:${e.name}${e.summary ? ` — ${e.summary}` : ''}`)
+          .join('\n') || '  (none)'
+
+        const briefing = [
+          `# Workspace Briefing — ${task.key}: ${task.title}`,
+          `Project: ${proj.name || task.project} | Column: ${task.column} | Priority: ${task.priority}`,
+          `Branch: ${task.github?.headBranch || '(none)'} | PR: ${task.github?.prNumber ? `#${task.github.prNumber}` : '(none)'}`,
+          '',
+          '## Task',
+          `${task.description || '(no description)'}`,
+          '',
+          '## Persistent Memory',
+          memLines,
+          '',
+          '## Sub-agent Sessions',
+          sessionLines,
+          '',
+          '## Claimed Files',
+          (task.claimedFiles || []).length > 0
+            ? (task.claimedFiles || []).map(f => `  ${f}`).join('\n')
+            : '  (none)',
+          '',
+          '## Recent Session Log',
+          recentLog,
+          ...(localState ? ['', '## Local Git State', JSON.stringify(localState, null, 2)] : []),
+          '',
+          '## Next Steps',
+          `Call get_agent_context("${taskId}") for full task context, or start working directly.`,
+          `Use remember("${taskId}", key, value) to persist discoveries.`,
+          `Use spawn_agent_session("${taskId}", role, mission) to delegate to sub-agents.`,
+          `Use generate_cursor_workspace("${proj._id || task.project}", "${taskId}", repoPath) to write .mdc rule files.`,
+        ].join('\n')
+
+        return text({
+          briefing,
+          task:    { key: task.key, title: task.title, column: task.column, priority: task.priority },
+          memory,
+          sessions,
+          localState,
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+}
+
+// ── Cursor Workspace Tools ────────────────────────────────────────────────────
+function registerCursorTools(server, ctx) {
+  const { scopedProjectId } = ctx
+
+  // ── generate_cursor_workspace ─────────────────────────────────────────────
+  server.tool(
+    'generate_cursor_workspace',
+    `Write 4 context-rich .mdc rule files to .cursor/rules/ in the local repository.
+
+These files inject live task context directly into every Cursor AI response — no copy-paste needed:
+- devos-task.mdc      — task title, description, readme plan, constraints from memory
+- devos-pipeline.mdc  — branch status, merge rank, behind/ahead, conflicts
+- devos-teammates.mdc — who is working on what, files to avoid touching
+- devos-memory.mdc    — recalled persistent memory + recent session summaries
+
+Run this once at the start of a session (or after remember() to refresh devos-memory.mdc).
+All files use alwaysApply: true so Cursor includes them in every conversation automatically.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      repoPath:  z.string().describe('Absolute path to the local git repo root (where .cursor/ folder lives or should be created)'),
+    },
+    async ({ projectId, taskId, repoPath }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      try {
+        // Fetch data
+        const [taskRes, projRes, memRes, sessRes] = await Promise.all([
+          api.get(`/api/tasks/${taskId}`),
+          api.get(`/api/projects/${projectId}`),
+          api.get(`/api/tasks/${taskId}/agent-memory`),
+          api.get(`/api/tasks/${taskId}/agent-sessions`),
+        ])
+
+        if (!taskRes?.success) return errorText(`Task not found: ${taskId}`)
+        const task    = taskRes.data.task
+        const proj    = projRes?.data?.project || {}
+        const tasks   = projRes?.data?.tasks   || []
+        const memory  = memRes?.data?.memory   || {}
+        const sessions = (sessRes?.data?.sessions || []).slice(-5)
+
+        const rulesDir = join(repoPath, '.cursor', 'rules')
+        mkdirSync(rulesDir, { recursive: true })
+
+        // ── devos-task.mdc ────────────────────────────────────────────────
+        const assigneeNames = (task.assignees || []).map(a => a.name || a.email || 'unknown').join(', ')
+        const subtaskLines  = (task.subtasks || []).map(s => `  - [${s.done ? 'x' : ' '}] ${s.title}`).join('\n') || '  (none)'
+        const taskMdc = [
+          '---',
+          `description: DevOS Task Context — ${task.key}: ${task.title}`,
+          'alwaysApply: true',
+          '---',
+          '',
+          `# Active Task: ${task.key} — ${task.title}`,
+          '',
+          `**Project:** ${proj.name || projectId}`,
+          `**Column:** ${task.column} | **Priority:** ${task.priority}`,
+          `**Assigned to:** ${assigneeNames || '(unassigned)'}`,
+          `**Branch:** ${task.github?.headBranch || '(not set)'} | **PR:** ${task.github?.prNumber ? `#${task.github.prNumber} — ${task.github.prUrl}` : 'none'}`,
+          '',
+          '## Description',
+          task.description || '(no description)',
+          '',
+          '## Plan / Readme',
+          task.readmeMarkdown || '(no plan written)',
+          '',
+          '## Subtasks',
+          subtaskLines,
+          '',
+          '## Constraints (from Cursor Rules)',
+          task.cursorRules || '(no task-specific constraints)',
+          '',
+          `## Task IDs`,
+          `- Task ID: ${task._id}`,
+          `- Project ID: ${projectId}`,
+          `- MCP reminder: always call get_workspace_briefing("${task._id}") at session start`,
+        ].join('\n')
+
+        // ── devos-pipeline.mdc ────────────────────────────────────────────
+        const activeTasks = tasks.filter(t => ['in_progress', 'in_review'].includes(t.column) && t.github?.headBranch)
+        const pipelineLines = activeTasks.map(t => {
+          const isMine = String(t._id) === String(task._id)
+          return `  ${isMine ? '▶' : ' '} ${t.key} [${t.column}] — branch: ${t.github?.headBranch || '?'} ${isMine ? '← YOU' : ''}`
+        }).join('\n') || '  (no active branches)'
+
+        const pipelineMdc = [
+          '---',
+          `description: DevOS Pipeline Context — ${proj.name || projectId}`,
+          'alwaysApply: true',
+          '---',
+          '',
+          `# Merge Pipeline — ${proj.name || projectId}`,
+          '',
+          `**Default branch:** ${proj.githubDefaultBranch || 'main'}`,
+          `**Your branch:** ${task.github?.headBranch || '(not set)'}`,
+          `**Your PR:** ${task.github?.prNumber ? `#${task.github.prNumber}` : 'none yet'}`,
+          '',
+          '## Active Branches (all developers)',
+          pipelineLines,
+          '',
+          '## What to do',
+          '- Run `get_branch_pipeline_status` to see your current merge rank and behind/ahead counts',
+          '- Run `guide_my_merge` to get step-by-step rebase/merge commands for your branch',
+          '- Run `assess_review_readiness` before requesting a code review',
+          '- Run `coordinate_conflict` if you share files with another branch',
+          '',
+          '## Merge Safety Rules',
+          '- Always `git fetch origin && git rebase origin/main` before pushing',
+          '- Never force-push to a shared branch — use `--force-with-lease` only',
+          '- Confirm no conflicts with teammates before opening your PR',
+          '- Run `get_pipeline_report` to see the full team status at any time',
+        ].join('\n')
+
+        // ── devos-teammates.mdc ──────────────────────────────────────────
+        const otherTasks = activeTasks.filter(t => String(t._id) !== String(task._id))
+        const teammateLines = otherTasks.map(t => {
+          const devs = (t.assignees || []).map(a => a.name || 'unknown').join(', ')
+          const files = (t.claimedFiles || [])
+          return [
+            `  **${t.key}** [${devs || 'unassigned'}] — branch: ${t.github?.headBranch || '?'}`,
+            files.length > 0 ? `    Files owned: ${files.join(', ')}` : '',
+          ].filter(Boolean).join('\n')
+        }).join('\n\n') || '  (you are the only active developer)'
+
+        const myFiles = (task.claimedFiles || [])
+        const teammateMdc = [
+          '---',
+          `description: DevOS Teammate Context — who is working on what`,
+          'alwaysApply: true',
+          '---',
+          '',
+          '# Teammate Context',
+          '',
+          '## Your claimed files (do not touch in other branches)',
+          myFiles.length > 0 ? myFiles.map(f => `  - ${f}`).join('\n') : '  (none claimed yet — call claim_files to lock your scope)',
+          '',
+          '## Other active developers',
+          teammateLines,
+          '',
+          '## Coordination rules',
+          '- Do NOT modify files listed under another developer\'s "Files owned" without coordinating first',
+          '- Call coordinate_conflict(projectId, yourTaskId, theirTaskId, "me"|"them", sharedFiles) to establish who refactors shared files',
+          '- When in doubt, ask in the task comment before modifying a shared module',
+        ].join('\n')
+
+        // ── devos-memory.mdc ──────────────────────────────────────────────
+        const memKeys = Object.keys(memory)
+        const memLines = memKeys.length > 0
+          ? memKeys.map(k => `  **${k}:** ${memory[k]}`).join('\n')
+          : '  (no memory stored yet)'
+
+        const sessionLines = sessions.length > 0
+          ? sessions.map(s => `  [${s.status.toUpperCase()}] **${s.role}** — ${s.mission}${s.summary ? `\n    Result: ${s.summary}` : ''}`).join('\n\n')
+          : '  (no sub-agent sessions yet)'
+
+        const memoryMdc = [
+          '---',
+          `description: DevOS Agent Memory — ${task.key} persistent knowledge`,
+          'alwaysApply: true',
+          '---',
+          '',
+          `# Agent Memory — ${task.key}`,
+          '',
+          '## Persistent Memory (from previous sessions)',
+          memLines,
+          '',
+          '## Recent Sub-agent Sessions',
+          sessionLines,
+          '',
+          '## How to update memory',
+          `Call remember("${task._id}", "key", "value") to store a new fact.`,
+          `Call recall("${task._id}") to see all stored facts.`,
+          'Memory is permanent — it survives across Cursor restarts and session clears.',
+          '',
+          '## How to spawn sub-agents',
+          `Call spawn_agent_session("${task._id}", "role", "mission") to create a named session.`,
+          `Call report_agent_findings(sessionId, "${task._id}", findings) to store results.`,
+          `Call complete_agent_session(sessionId, "${task._id}", summary) when done.`,
+          `Call get_agent_sessions("${task._id}") to see all sessions and their status.`,
+        ].join('\n')
+
+        // Write all 4 files
+        const files = [
+          { name: 'devos-task.mdc',      content: taskMdc      },
+          { name: 'devos-pipeline.mdc',  content: pipelineMdc  },
+          { name: 'devos-teammates.mdc', content: teammateMdc  },
+          { name: 'devos-memory.mdc',    content: memoryMdc    },
+        ]
+        for (const f of files) {
+          writeFileSync(join(rulesDir, f.name), f.content, 'utf8')
+        }
+
+        // Auto-rescan workspace so the UI reflects the newly written files immediately.
+        runWorkspaceScan(taskId, task, proj, repoPath).catch(() => {/* non-fatal */})
+
+        return text({
+          written:     files.map(f => f.name),
+          rulesDir,
+          totalBytes:  files.reduce((n, f) => n + f.content.length, 0),
+          hint:        'All 4 .mdc files written. Cursor will pick them up automatically on next message. Re-run after calling remember() to refresh devos-memory.mdc.',
+          taskKey:     task.key,
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── install_zopkit_skills ─────────────────────────────────────────────────
+  server.tool(
+    'install_zopkit_skills',
+    `Write the complete ZopKit agent skills and methodology as Cursor rules (.mdc files) to .cursor/rules/.
+
+This installs all ZopKit skills and agent definitions so every Cursor session has them available automatically:
+- zopkit-merge-skill.mdc    — 8-phase Merge & Ship methodology with exact git commands
+- zopkit-review-skill.mdc   — 7-step Pipeline Code Review methodology (merge safety first)
+- zopkit-recon-skill.mdc    — 5-phase Codebase Recon delivering architecture intelligence report
+- zopkit-blueprint-skill.mdc — 5-step Feature Blueprint (data model → API → frontend → wiring)
+- zopkit-security-skill.mdc — 5-phase Security Audit skill
+- zopkit-agents.mdc         — All 6 agent personas (ZopShipper, ZopScout, ZopMerger, ZopReviewer, ZopGuard, ZopOrchestrator)
+
+How to use after installing:
+- Skills: reference with @zopkit-merge-skill or @zopkit-review-skill in Cursor chat
+- Agents: activate with "You are ZopMerger. [mission]" in Cursor chat
+- Prompts: use generate_cursor_workspace to also write task-specific context files
+
+Run once per repository. Re-run to update all files after a ZopKit version bump.`,
+    {
+      repoPath: z.string().describe('Absolute path to the local git repo root'),
+    },
+    async ({ repoPath }) => {
+      try {
+        const rulesDir = join(repoPath, '.cursor', 'rules')
+        mkdirSync(rulesDir, { recursive: true })
+
+        // ── zopkit-merge-skill.mdc ────────────────────────────────────────
+        const mergeSkillMdc = [
+          '---',
+          'description: ZopKit Merge & Ship Skill — 8-phase methodology for safely merging feature branches',
+          'alwaysApply: false',
+          '---',
+          '',
+          '# ZopKit Merge & Ship Skill',
+          '',
+          'Use this skill when a developer asks to merge, ship, rebase, or resolve conflicts.',
+          'Activate with: "@zop-merge-skill guide me to merge my branch"',
+          '',
+          '## Phase 1 — Assess current status',
+          '```',
+          'git fetch origin',
+          'git status',
+          'git log origin/main..HEAD --oneline  # your commits',
+          'git log HEAD..origin/main --oneline  # commits you are missing',
+          '```',
+          '',
+          '## Phase 2 — Stash any local changes',
+          '```',
+          'git stash push -m "pre-rebase stash $(date +%s)"',
+          '```',
+          '',
+          '## Phase 3 — Rebase onto the latest main',
+          '```',
+          'git rebase origin/main',
+          '# If conflicts:',
+          '#   git status                    → see conflicting files',
+          '#   git diff <file>               → inspect the conflict',
+          '#   # edit the file to resolve',
+          '#   git add <file>',
+          '#   git rebase --continue',
+          '```',
+          '',
+          '## Phase 4 — Verify the rebase result',
+          '```',
+          'git log --oneline -5',
+          'git diff origin/main --stat',
+          '```',
+          '',
+          '## Phase 5 — Pop stash (if any)',
+          '```',
+          'git stash pop',
+          '```',
+          '',
+          '## Phase 6 — Push (safely)',
+          '```',
+          'git push --force-with-lease origin <your-branch>',
+          '# NEVER use --force on a shared branch',
+          '```',
+          '',
+          '## Phase 7 — Check CI / PR status',
+          'Call assess_review_readiness(projectId, taskId) to get a structured readiness checklist.',
+          '',
+          '## Phase 8 — Coordinate if needed',
+          'If you share files with another branch, call coordinate_conflict() before merging.',
+          'Call get_pipeline_report(projectId) to see the full team status.',
+          '',
+          '## Safety rules',
+          '- Always fetch before rebase',
+          '- Always use --force-with-lease not --force',
+          '- Never rebase commits that have already been reviewed on a PR without notifying the reviewer',
+          '- Confirm the pipeline report shows you as #1 or #2 before merging',
+        ].join('\n')
+
+        // ── zopkit-review-skill.mdc ───────────────────────────────────────
+        const reviewSkillMdc = [
+          '---',
+          'description: ZopKit Pipeline Code Review Skill — 7-step methodology for reviewing PRs in the merge pipeline',
+          'alwaysApply: false',
+          '---',
+          '',
+          '# ZopKit Pipeline Code Review Skill',
+          '',
+          'Use this skill when asked to review a PR, assess readiness, or do a code review.',
+          'Activate with: "@zop-review-skill review this PR"',
+          '',
+          '## Step 1 — Fetch the diff',
+          'Call assess_review_readiness(projectId, taskId) for the structured 6-check readiness report.',
+          'Call get_review_bundle(taskId) for the raw diff + PR details.',
+          '',
+          '## Step 2 — Pipeline check',
+          'Confirm branch is not behind main. If behind → ask developer to rebase first.',
+          'Confirm no shared files with other active branches (call get_branch_pipeline_status).',
+          '',
+          '## Step 3 — Correctness review',
+          '- Does the code do what the task description says?',
+          '- Are there obvious bugs, null pointer risks, or off-by-one errors?',
+          '- Are all new code paths covered by existing tests or new ones?',
+          '',
+          '## Step 4 — Safety review',
+          '- No secrets, credentials, or API keys in the diff',
+          '- No SQL injection, XSS, or SSRF vectors introduced',
+          '- Input validation at system boundaries',
+          '',
+          '## Step 5 — Standards review',
+          '- Follows existing naming and file structure conventions',
+          '- No dead code or commented-out blocks left behind',
+          '- No unnecessary dependencies added',
+          '',
+          '## Step 6 — Verdict',
+          '- APPROVE: all checks pass, no blocking issues',
+          '- NEEDS WORK: one or more checks fail — list specific changes required',
+          '- REJECT: fundamental design issue — requires rework, not just fixes',
+          '',
+          '## Step 7 — Post findings',
+          'Post a comment on the task with your verdict and specific line-level feedback.',
+          'Call remember(taskId, "review_verdict", "APPROVE/NEEDS_WORK/REJECT — reason") to persist.',
+        ].join('\n')
+
+        // ── zopkit-agents.mdc ─────────────────────────────────────────────
+        const agentsMdc = [
+          '---',
+          'description: ZopKit Agent Definitions — ZopMerger and ZopReviewer agent personas',
+          'alwaysApply: false',
+          '---',
+          '',
+          '# ZopKit Agent Definitions',
+          '',
+          '## ZopMerger — Merge & Ship Guide',
+          '',
+          'Activate: "You are ZopMerger. Guide me to merge my branch safely."',
+          '',
+          'ZopMerger is a senior DevOps engineer specialising in git merge pipelines.',
+          'Personality: direct, methodical, safety-conscious. Never rushes a merge.',
+          '',
+          'Responsibilities:',
+          '- Runs the 8-phase Merge & Ship skill',
+          '- Calls get_branch_pipeline_status to assess current position',
+          '- Calls guide_my_merge for exact step-by-step commands',
+          '- Coordinates conflicts via coordinate_conflict',
+          '- Celebrates successful merges with confetti 🎉',
+          '',
+          'Trigger phrases:',
+          '- "help me merge", "guide my merge", "how do I ship this", "rebase help"',
+          '- "I have conflicts", "my branch is behind", "how do I push"',
+          '',
+          '## ZopReviewer — Pipeline Code Reviewer',
+          '',
+          'Activate: "You are ZopReviewer. Review this PR."',
+          '',
+          'ZopReviewer is a senior engineer and security-aware code reviewer.',
+          'Personality: thorough, precise, constructive. Always explains the "why".',
+          '',
+          'Responsibilities:',
+          '- Runs the 7-step Pipeline Code Review skill',
+          '- Calls assess_review_readiness for structured checklist',
+          '- Posts verdict as a task comment',
+          '- Remembers verdict via remember(taskId, "review_verdict", verdict)',
+          '',
+          'Trigger phrases:',
+          '- "review this PR", "is this ready to merge", "check my code", "review readiness"',
+          '- "am I ready", "can I merge", "what do you think of this diff"',
+          '',
+          '## ZopOrchestrator — Task Decomposer',
+          '',
+          'Activate: "You are ZopOrchestrator. Decompose this task."',
+          '',
+          'ZopOrchestrator is a technical lead who breaks complex tasks into parallel workstreams.',
+          'Personality: systems thinker, delegation-first, dependency-aware.',
+          '',
+          'Responsibilities:',
+          '- Calls decompose_task to create subtask groups',
+          '- Spawns named sub-agent sessions via spawn_agent_session',
+          '- Tracks session progress via get_agent_sessions',
+          '- Aggregates findings via report_agent_findings + complete_agent_session',
+          '- Generates the full workspace context via generate_cursor_workspace',
+        ].join('\n')
+
+        // ── zopkit-recon-skill.mdc ────────────────────────────────────────
+        const reconSkillMdc = [
+          '---',
+          'description: ZopKit Codebase Recon Skill — 5-phase architecture intelligence sweep',
+          'alwaysApply: false',
+          '---',
+          '',
+          '# ZopKit Codebase Recon Skill',
+          '',
+          'Reference with @zopkit-recon-skill, or paste as context before exploring a codebase.',
+          'Use at the start of any task on an unfamiliar module.',
+          '',
+          '## Phase 1: Surface Scan (< 2 minutes)',
+          '- Read package.json / go.mod — identify framework and key deps',
+          '- Read the entry point — understand bootstrap',
+          '- Check for CLAUDE.md, README, .cursorrules — existing docs',
+          '',
+          '## Phase 2: Architecture Map (< 5 minutes)',
+          '- Map directory structure to architectural boundaries',
+          '- Trace request lifecycle: entry → middleware → handler → response',
+          '- Map database layer: ORM, schema location, migration system',
+          '',
+          '## Phase 3: Data Flow Tracing',
+          'Pick a feature. Trace: user action → frontend → API call → backend → DB → response → UI update.',
+          '',
+          '## Phase 4: Risk Assessment',
+          '- Complexity concentration? God files, circular deps?',
+          '- Test coverage? Tech debt? TODO comments?',
+          '',
+          '## Phase 5: Intelligence Report',
+          '```',
+          'ARCHITECTURE: [monolith|modular|microservices|monorepo]',
+          'FRAMEWORK: [name + version]',
+          'DATABASE: [type + ORM]',
+          'AUTH: [strategy]',
+          'KEY MODULES: [list with one-line descriptions]',
+          'RISK AREAS: [list with severity]',
+          'ENTRY POINTS: [5 files to read first, in order]',
+          '```',
+        ].join('\n')
+
+        // ── zopkit-blueprint-skill.mdc ────────────────────────────────────
+        const blueprintSkillMdc = [
+          '---',
+          'description: ZopKit Feature Blueprint Skill — 5-step plan from intent to wired implementation',
+          'alwaysApply: false',
+          '---',
+          '',
+          '# ZopKit Feature Blueprint Skill',
+          '',
+          'Reference with @zopkit-blueprint-skill before planning or building a new feature.',
+          '',
+          '## Step 1: Parse Intent',
+          '- What are we building? (feature, fix, refactor, integration)',
+          '- Who uses it? What are the constraints?',
+          '',
+          '## Step 2: Design Data Model',
+          '- Entities, relationships, field types, indexes',
+          '',
+          '## Step 3: Plan API Layer',
+          '- Endpoints: method, path, request/response shape, auth requirements',
+          '- Error cases and status codes',
+          '',
+          '## Step 4: Build Frontend',
+          '- Components, state management, data fetching strategy',
+          '- UI states: loading, empty, error, success',
+          '',
+          '## Step 5: Wire It Together',
+          '- Module structure, route/guard registration, error boundaries',
+          '',
+          '## Output Format',
+          'For each file: [CREATE/MODIFY] path/to/file — Purpose — Dependencies',
+        ].join('\n')
+
+        // ── zopkit-security-skill.mdc ─────────────────────────────────────
+        const securitySkillMdc = [
+          '---',
+          'description: ZopKit Security Audit Skill — 5-phase review: auth, injection, data protection, infrastructure',
+          'alwaysApply: false',
+          '---',
+          '',
+          '# ZopKit Security Audit Skill',
+          '',
+          'Reference with @zopkit-security-skill before any PR that touches auth, APIs, or user data.',
+          '',
+          '## Phase 1: Attack Surface',
+          '- All API endpoints and their auth requirements',
+          '- User input entry points (forms, URL params, headers)',
+          '',
+          '## Phase 2: Auth & Authorization',
+          '- JWT: expiry, refresh, httpOnly cookies',
+          '- Every endpoint has appropriate guards',
+          '- Privilege escalation: can a user access another user\'s data?',
+          '',
+          '## Phase 3: Input Validation & Injection',
+          '- Input validated before use (no raw req.body in queries)',
+          '- SQL injection in raw queries? XSS in rendered content?',
+          '- Command injection in shell-executing code?',
+          '',
+          '## Phase 4: Data Protection',
+          '- Sensitive data never logged (passwords, tokens, PII)',
+          '- API responses don\'t leak internal IDs or stack traces',
+          '',
+          '## Phase 5: Infrastructure',
+          '- CORS: specific origins, not wildcard',
+          '- Rate limiting on auth endpoints',
+          '- Dependency vulnerabilities (npm audit)',
+          '',
+          '## Severity: CRITICAL → HIGH → MEDIUM → LOW → INFO',
+        ].join('\n')
+
+        // Update agents .mdc to include all 6 agents
+        const agentsMdcUpdated = agentsMdc
+          .replace('## ZopMerger — Merge & Ship Guide', '## ZopShipper — Builder Agent\n\nActivate: "You are ZopShipper. Ship this feature: [description]"\n\nBuilds features end-to-end. Scaffolds types, services, controllers, components, tests.\nUse for: implementing tasks, writing code from scratch, extending existing features.\n\n## ZopScout — Reconnaissance Agent\n\nActivate: "You are ZopScout. Map this codebase: [target]"\n\nMaps architecture, traces data flows, documents undocumented code.\nUse for: unfamiliar codebases, tracing bugs, understanding module boundaries.\n\n## ZopMerger — Merge & Ship Guide')
+
+        const files = [
+          { name: 'zopkit-merge-skill.mdc',     content: mergeSkillMdc    },
+          { name: 'zopkit-review-skill.mdc',    content: reviewSkillMdc   },
+          { name: 'zopkit-recon-skill.mdc',     content: reconSkillMdc    },
+          { name: 'zopkit-blueprint-skill.mdc', content: blueprintSkillMdc},
+          { name: 'zopkit-security-skill.mdc',  content: securitySkillMdc },
+          { name: 'zopkit-agents.mdc',          content: agentsMdcUpdated },
+        ]
+        for (const f of files) {
+          writeFileSync(join(rulesDir, f.name), f.content, 'utf8')
+        }
+
+        return text({
+          written:    files.map(f => f.name),
+          rulesDir,
+          totalBytes: files.reduce((n, f) => n + f.content.length, 0),
+          hint:       [
+            '6 skill files + agent definitions written.',
+            'Skills — reference in Cursor with: @zopkit-merge-skill | @zopkit-review-skill | @zopkit-recon-skill | @zopkit-blueprint-skill | @zopkit-security-skill',
+            'Agents — activate in Cursor with: "You are ZopShipper/ZopScout/ZopMerger/ZopReviewer/ZopGuard/ZopOrchestrator."',
+            'Next: call generate_cursor_workspace(projectId, taskId, repoPath) to write task-specific context files for this session.',
+          ].join('\n'),
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+}
+
+// ── Orchestration Tools ───────────────────────────────────────────────────────
+function registerOrchestrationTools(server, ctx) {
+
+  // ── spawn_agent_session ───────────────────────────────────────────────────
+  server.tool(
+    'spawn_agent_session',
+    `Register a named sub-agent session on a task. Use this when delegating work to a specialist sub-agent (Scout, Reviewer, Builder, Coordinator).
+
+Each session has:
+- sessionId: unique ID you assign (e.g. "scout-auth-module", "review-pass-1")
+- role: what this session does (scout, reviewer, builder, coordinator, custom)
+- mission: what the session is trying to accomplish
+
+After spawning, the sub-agent should call report_agent_findings() as it discovers things,
+and complete_agent_session() when done. The orchestrator calls get_agent_sessions() to monitor progress.
+
+Example flow:
+  1. spawn_agent_session(taskId, "scout-auth", "scout", "Map all auth middleware files and find injection points")
+  2. Sub-agent runs and calls report_agent_findings("scout-auth", taskId, "Found 3 middleware files...")
+  3. Sub-agent calls complete_agent_session("scout-auth", taskId, "Auth middleware mapped — see findings")
+  4. Orchestrator calls get_agent_sessions(taskId) to see the result`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      sessionId: z.string().describe('Unique session identifier — use short kebab-case (e.g. "scout-auth", "review-pass-1")'),
+      role:      z.string().describe('Session role — scout | reviewer | builder | coordinator | custom'),
+      mission:   z.string().describe('One-sentence description of what this session will accomplish'),
+    },
+    async ({ taskId, sessionId, role, mission }) => {
+      try {
+        const res = await api.post(`/api/tasks/${taskId}/agent-sessions`, { sessionId, role, mission })
+        if (!res?.success) return errorText(res?.message || 'Failed to spawn session')
+        return text({
+          spawned:    true,
+          session:    res.data.session,
+          nextSteps: [
+            `Sub-agent: call report_agent_findings("${sessionId}", "${taskId}", yourFindings) as you discover things`,
+            `Sub-agent: call complete_agent_session("${sessionId}", "${taskId}", summary) when done`,
+            `Orchestrator: call get_agent_sessions("${taskId}") to monitor all sessions`,
+          ],
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── report_agent_findings ─────────────────────────────────────────────────
+  server.tool(
+    'report_agent_findings',
+    `Store intermediate findings from a running sub-agent session. Call this as the sub-agent discovers information — before calling complete_agent_session.
+
+Findings are appended (replacing previous findings for this session) and visible to the orchestrator via get_agent_sessions.
+Use this to stream progress back so the orchestrator can act on partial results.`,
+    {
+      sessionId: z.string().describe('The session ID from spawn_agent_session'),
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      findings:  z.string().describe('Findings discovered so far — plain text or markdown, any length'),
+    },
+    async ({ sessionId, taskId, findings }) => {
+      try {
+        const res = await api.patch(`/api/tasks/${taskId}/agent-sessions/${sessionId}`, { findings })
+        if (!res?.success) return errorText(res?.message || 'Failed to report findings')
+        return text({ reported: true, sessionId, hint: `Findings stored. Call complete_agent_session("${sessionId}", "${taskId}", summary) when done.` })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── complete_agent_session ────────────────────────────────────────────────
+  server.tool(
+    'complete_agent_session',
+    `Mark a sub-agent session as complete and store the final summary.
+
+Call this when the sub-agent has finished its mission. Sets status to "done" and records endedAt.
+The orchestrator can then read all completed sessions via get_agent_sessions to aggregate results.`,
+    {
+      sessionId: z.string().describe('The session ID from spawn_agent_session'),
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      summary:   z.string().describe('One-paragraph summary of what was accomplished and key findings'),
+      status:    z.enum(['done', 'failed']).optional().describe('Final status — defaults to "done"'),
+    },
+    async ({ sessionId, taskId, summary, status = 'done' }) => {
+      try {
+        const res = await api.patch(`/api/tasks/${taskId}/agent-sessions/${sessionId}`, { summary, status })
+        if (!res?.success) return errorText(res?.message || 'Failed to complete session')
+        return text({
+          completed: true,
+          sessionId,
+          status,
+          summary,
+          hint: `Session marked ${status}. Orchestrator: call get_agent_sessions("${taskId}") to see all results. Call remember("${taskId}", "session_${sessionId}", summary) to persist the finding permanently.`,
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── get_agent_sessions ────────────────────────────────────────────────────
+  server.tool(
+    'get_agent_sessions',
+    `Retrieve all named sub-agent sessions for a task, with their status, mission, and findings.
+
+Use this as the orchestrator to monitor parallel sub-agents and aggregate their results.
+Sessions are returned ordered by startedAt. Status is active | done | failed.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+    },
+    async ({ taskId }) => {
+      try {
+        const res = await api.get(`/api/tasks/${taskId}/agent-sessions`)
+        if (!res?.success) return errorText(res?.message || 'Failed to retrieve sessions')
+        const { sessions } = res.data
+        if (sessions.length === 0) {
+          return text({ sessions: [], hint: `No sessions yet. Call spawn_agent_session("${taskId}", sessionId, role, mission) to create one.` })
+        }
+        const summary = sessions.map(s => {
+          const age = s.startedAt ? Math.round((Date.now() - new Date(s.startedAt).getTime()) / 60000) + 'm ago' : '?'
+          const end = s.endedAt   ? ` → ended ${Math.round((Date.now() - new Date(s.endedAt).getTime()) / 60000)}m ago` : ''
+          return `  [${s.status.toUpperCase().padEnd(6)}] ${s.sessionId} (${s.role}) — started ${age}${end}\n    Mission: ${s.mission}${s.summary ? `\n    Result:  ${s.summary}` : ''}${s.findings ? `\n    Findings: ${s.findings.slice(0, 200)}${s.findings.length > 200 ? '…' : ''}` : ''}`
+        }).join('\n\n')
+
+        const active  = sessions.filter(s => s.status === 'active').length
+        const done    = sessions.filter(s => s.status === 'done').length
+        const failed  = sessions.filter(s => s.status === 'failed').length
+
+        return text({ sessions, summary: `${sessions.length} sessions — ${active} active, ${done} done, ${failed} failed\n\n${summary}` })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+}
+
+// ── Monitoring Tools ──────────────────────────────────────────────────────────
+function registerMonitoringTools(server, ctx) {
+  const { scopedProjectId } = ctx
+
+  // ── poll_pipeline_events ──────────────────────────────────────────────────
+  server.tool(
+    'poll_pipeline_events',
+    `Poll for pipeline changes since a given timestamp — returns only tasks that changed, not the full pipeline.
+
+Use this for lightweight monitoring loops:
+1. Store the current timestamp: since = new Date().toISOString()
+2. Wait (sleep or user action)
+3. Call poll_pipeline_events(projectId, since) to see what changed
+4. Update since to fetchedAt from the response for the next poll
+
+Returns: changed tasks with their new column, branch info, and agent role.
+Much faster than calling get_branch_pipeline_status on every tick.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      since:     z.string().describe('ISO 8601 timestamp — only tasks updated after this time are returned. Use fetchedAt from the previous response.'),
+    },
+    async ({ projectId, since }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+      try {
+        const res = await api.get(`/api/projects/${projectId}/pipeline-events?since=${encodeURIComponent(since)}`)
+        if (!res?.success) return errorText(res?.message || 'Failed to poll pipeline events')
+        const { events, fetchedAt } = res.data
+        if (events.length === 0) {
+          return text({ events: [], fetchedAt, hint: `No changes since ${since}. Use fetchedAt (${fetchedAt}) as the next "since" value.` })
+        }
+        const lines = events.map(e => {
+          const branch = e.github?.headBranch || '—'
+          const pr     = e.github?.prNumber ? `PR #${e.github.prNumber}` : 'no PR'
+          return `  ${e.taskKey} [${e.column}] — branch: ${branch} | ${pr} | role: ${e.agentRole || 'none'}`
+        }).join('\n')
+        return text({
+          events,
+          fetchedAt,
+          summary: `${events.length} task${events.length !== 1 ? 's' : ''} changed since ${since}:\n${lines}`,
+          hint:    `Use fetchedAt (${fetchedAt}) as the next "since" value.`,
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+}
+
+// ── Shared workspace scan helper ─────────────────────────────────────────────
+// Called by scan_workspace tool AND automatically by kickoff_task /
+// generate_cursor_workspace so results are always fresh without the developer
+// needing to run a separate command.
+//
+// Returns { scanned, detectedRoot, repoVerification, cursorDirExists, sections, summary, allItems }
+// or { error, message } on failure.
+async function runWorkspaceScan(taskId, task, project, overrideRepoPath) {
+  const cfg = project.agentConfig || {}
+
+  // ── 1. Detect repo root ─────────────────────────────────────────────────────
+  // Cursor starts the MCP with cwd = the folder the developer has open.
+  // Walk up to find the .git root so we always scan the full repo, not a subfolder.
+  // Returns null if no .git found (avoids false positives from home-dir .git repos).
+  function findGitRoot(startDir) {
+    let dir = startDir
+    for (let i = 0; i < 10; i++) {
+      if (existsSync(join(dir, '.git'))) return dir
+      const parent = join(dir, '..')
+      if (parent === dir) break
+      dir = parent
+    }
+    return null  // no .git found — caller must handle
+  }
+  const detectedRoot = findGitRoot(overrideRepoPath || process.cwd())
+
+  if (!detectedRoot) {
+    const startedFrom = overrideRepoPath || process.cwd()
+    return {
+      error: true,
+      message: `No .git directory found in or above "${startedFrom}". Make sure Cursor is open inside your project folder, or pass repoPath explicitly.`,
+      hint: `scan_workspace repoPath="/absolute/path/to/your/repo"`,
+    }
+  }
+
+  // ── 2. Verify it's the right repo via git remote ────────────────────────────
+  // Compares local "origin" remote to project.githubRepoFullName.
+  // Case-insensitive — GitHub repo names are not case-sensitive.
+  // Prevents scanning the wrong repo when multiple projects are on the same machine.
+  const norm = url => url.replace(/^(https?:\/\/github\.com\/|git@github\.com:)/, '').replace(/\.git$/, '').trim().toLowerCase()
+  let repoVerification = { checked: false, matched: null, localRemote: null, projectRepo: project.githubRepoFullName || null }
+  try {
+    const remoteUrl = runGit('remote get-url origin', detectedRoot).trim()
+    const localRepo   = norm(remoteUrl)
+    const projectRepo = project.githubRepoFullName ? norm(project.githubRepoFullName) : null
+
+    if (projectRepo) {
+      // Project has a GitHub link — verify and block on mismatch
+      repoVerification = { checked: true, matched: localRepo === projectRepo, localRemote: localRepo, projectRepo }
+      if (!repoVerification.matched) {
+        return {
+          error: true,
+          message: `Wrong repo — Cursor is open in "${localRepo}" but this task belongs to "${projectRepo}". Open Cursor in the correct repo or pass repoPath explicitly.`,
+          fix: [
+            `Option 1: Run scan_workspace repoPath="/path/to/${projectRepo.split('/')[1]}"`,
+            `Option 2: Make sure git remote origin is set to the correct repo`,
+          ],
+        }
+      }
+    } else {
+      // No GitHub link — record the remote as a hint so user can tell if it looks right
+      repoVerification = { checked: false, matched: null, localRemote: localRepo, projectRepo: null, warning: `Project has no GitHub repo linked — could not verify identity. Detected remote: "${localRepo}". If this is the wrong repo, pass repoPath explicitly.` }
+    }
+  } catch {
+    // git unavailable or no remote — surface the detected root as a hint
+    repoVerification = { checked: false, matched: null, localRemote: null, projectRepo: project.githubRepoFullName || null, warning: `Could not read git remote — make sure git is installed and origin is configured. Scanned: "${detectedRoot}".` }
+  }
+
+  // ── 3. Read .cursor/ subdirectories ─────────────────────────────────────────
+  const cursorDir = join(detectedRoot, '.cursor')
+  const rulesDir  = join(cursorDir, 'rules')
+  const agentsDir = join(cursorDir, 'agents')
+  const skillsDir = join(cursorDir, 'skills')
+  const cursorDirExists = existsSync(cursorDir)
+
+  function listFilesSync(dir) {
+    if (!existsSync(dir)) return new Map()
+    try {
+      const map = new Map()
+      for (const filename of readdirSync(dir)) {
+        try {
+          const fp = join(dir, filename)
+          if (statSync(fp).isFile()) map.set(filename, { filename, size: statSync(fp).size })
+        } catch { /* skip */ }
+      }
+      return map
+    } catch { return new Map() }
+  }
+
+  const diskRules  = listFilesSync(rulesDir)
+  const diskAgents = listFilesSync(agentsDir)
+  const diskSkills = listFilesSync(skillsDir)
+
+  // ── 4. Compare config vs disk ────────────────────────────────────────────────
+  function compareSection(configItems, diskMap, ext) {
+    const results    = []
+    const seenOnDisk = new Set()
+    for (const item of (configItems || [])) {
+      if (!item.name) continue
+      const filename  = `${item.name}${ext}`
+      const disk      = diskMap.get(filename)
+      seenOnDisk.add(filename)
+      const isEnabled = item.enabled !== false
+      const diskStatus = !isEnabled
+        ? (disk ? 'present_but_disabled' : 'absent_disabled')
+        : (disk ? 'present'              : 'missing')
+      results.push({ name: item.name, description: item.description || '', enabled: isEnabled, filename, diskStatus, size: disk?.size ?? null })
+    }
+    for (const [filename, info] of diskMap) {
+      if (!seenOnDisk.has(filename)) {
+        results.push({ name: filename.replace(new RegExp(`\\${ext}$`), ''), description: '', enabled: null, filename, diskStatus: 'orphaned', size: info.size })
+      }
+    }
+    return results
+  }
+
+  const sections = {
+    rules:  compareSection(cfg.rules,     diskRules,  '.mdc'),
+    agents: compareSection(cfg.subagents, diskAgents, '.md'),
+    skills: compareSection(cfg.skills,    diskSkills, '.md'),
+  }
+
+  const allItems = [...sections.rules, ...sections.agents, ...sections.skills]
+  const summary  = {
+    present:  allItems.filter(i => i.diskStatus === 'present').length,
+    missing:  allItems.filter(i => i.diskStatus === 'missing').length,
+    orphaned: allItems.filter(i => i.diskStatus === 'orphaned').length,
+    disabled: allItems.filter(i => ['absent_disabled', 'present_but_disabled'].includes(i.diskStatus)).length,
+    total:    allItems.length,
+  }
+
+  // ── 5. Persist to task so the UI can display without server filesystem access
+  await api.patch(`/api/tasks/${taskId}`, {
+    lastWorkspaceScan: { repoPath: detectedRoot, cursorDirExists, sections, summary },
+  }).catch(() => {/* non-fatal — scan result returned regardless */})
+
+  return { scanned: true, detectedRoot, repoVerification, cursorDirExists, sections, summary, allItems }
+}
+
+// ── Workspace Scan Tool ───────────────────────────────────────────────────────
+function registerWorkspaceScanTool(server) {
+  server.tool(
+    'scan_workspace',
+    `Scan this repo's .cursor/ directory and compare it against the project config.
+
+ZERO ARGS NEEDED in most cases — the MCP already runs inside your Cursor workspace:
+  scan_workspace               ← auto-detects task (your in-progress work) + repo root
+  scan_workspace taskId="..."  ← explicit task, auto-detects repo root
+  scan_workspace repoPath="..."← explicit path override (e.g. Cursor opened in parent folder)
+
+HOW AUTO-DETECTION WORKS:
+- Task:     looks up your current in-progress task for this project
+- Repo root: walks up from process.cwd() (= the folder Cursor has open) to find .git/
+- Verified: reads git remote "origin" and checks it matches the project's linked GitHub repo
+
+WHAT IT CHECKS:
+  .cursor/rules/   — .mdc rule files vs project agentConfig.rules
+  .cursor/agents/  — .md agent files vs project agentConfig.subagents
+  .cursor/skills/  — .md skill files vs project agentConfig.skills
+
+Results are saved to the task and shown in InternalTool → Agent → Workspace tab.
+Also runs automatically inside kickoff_task and generate_cursor_workspace.`,
+    {
+      taskId:   z.string().optional().describe('Task ObjectId. Omit to auto-detect your current in-progress task for this project.'),
+      repoPath: z.string().optional().describe('Repo root override. Omit to use process.cwd() (where Cursor is open).'),
+    },
+    async ({ taskId, repoPath } = {}) => {
+      // ── Resolve task ─────────────────────────────────────────────────────────
+      let task, resolvedTaskId
+      if (taskId) {
+        const res = await api.get(`/api/tasks/${taskId}`)
+        if (!res?.success) return errorText('Task not found')
+        task = res.data.task
+        resolvedTaskId = taskId
+      } else {
+        // Auto-detect: find the developer's current in-progress task
+        const myTasksRes = await api.get('/api/users/me/tasks?column=in_progress')
+        const myTasks    = myTasksRes?.data?.tasks || []
+
+        // If scoped to a project, filter to that project
+        const candidates = cliProject
+          ? myTasks.filter(t => String(t.project?._id || t.project) === cliProject)
+          : myTasks
+
+        if (candidates.length === 0) {
+          return text({
+            error: true,
+            message: 'No in-progress task found for your account. Start a task first (kickoff_task), then re-run scan_workspace.',
+            hint: 'Or pass taskId explicitly: scan_workspace taskId="<id>"',
+          })
+        }
+        if (candidates.length > 1) {
+          return text({
+            error: true,
+            message: `${candidates.length} in-progress tasks found. Pass taskId to specify which one to scan.`,
+            tasks: candidates.map(t => ({ id: t._id, key: t.key, title: t.title })),
+          })
+        }
+        task = candidates[0]
+        resolvedTaskId = String(task._id)
+      }
+
+      // ── Resolve project ───────────────────────────────────────────────────────
+      const projectId = task.project?._id || task.project
+      const projRes   = await api.get(`/api/projects/${projectId}`)
+      if (!projRes?.success) return errorText('Project not found')
+      const project = projRes?.data?.project || {}
+
+      // ── Run the scan ──────────────────────────────────────────────────────────
+      const result = await runWorkspaceScan(resolvedTaskId, task, project, repoPath)
+      if (result.error) return text(result)
+
+      const { detectedRoot, repoVerification, cursorDirExists, summary, sections, allItems } = result
+      const missingItems  = allItems.filter(i => i.diskStatus === 'missing')
+      const orphanedItems = allItems.filter(i => i.diskStatus === 'orphaned')
+
+      return text({
+        scanned:          true,
+        task:             { key: task.key, title: task.title },
+        detectedRepoRoot: detectedRoot,
+        repoVerification,
+        cursorDirExists,
+        summary,
+        sections,
+        uiHint: 'Results saved → InternalTool task page → Agent → Workspace tab (auto-refreshes).',
+        actions: [
+          missingItems.length > 0
+            ? `⚠️  ${missingItems.length} item(s) missing from disk. Run: install_zopkit_skills repoPath="${detectedRoot}"`
+            : `✅ All configured items are present on disk.`,
+          orphanedItems.length > 0
+            ? `ℹ️  ${orphanedItems.length} orphaned file(s) not in project config: ${orphanedItems.map(i => i.filename).join(', ')}`
+            : null,
+        ].filter(Boolean),
+      })
+    }
+  )
+}
+
+// ── Kit Tools ─────────────────────────────────────────────────────────────────
+function registerKitTools(server) {
+
+  // ── Full catalog definition (mirrors client/src/lib/zopkit.js) ───────────────
+  const CATALOG_AGENTS = [
+    { name: 'zop-shipper',      description: 'Feature builder agent — implements code end-to-end',            when: 'builder tasks, new features, bug fixes' },
+    { name: 'zop-scout',        description: 'Codebase recon agent — read-only analysis and architecture map', when: 'exploring unfamiliar code, tracing flows' },
+    { name: 'zop-guard',        description: 'Security audit agent — auth, vulnerabilities, compliance',      when: 'security review, auth hardening' },
+    { name: 'zop-merger',       description: 'Merge & ship agent — rebase, conflict resolution, push to main', when: 'merging branches, resolving conflicts' },
+    { name: 'zop-reviewer',     description: 'Code review agent — PR review, diff quality, approval gate',   when: 'reviewing pull requests' },
+    { name: 'zop-orchestrator', description: 'Multi-agent coordinator — decomposes and orchestrates large tasks', when: 'large complex tasks needing parallel builders' },
+  ]
+  const CATALOG_SKILLS = [
+    { name: 'zop-blueprint',    description: 'Feature Blueprint — data model → API → frontend → wiring',     when: 'planning and building a new feature' },
+    { name: 'zop-recon',        description: 'Codebase Recon — 5-phase architecture intelligence sweep',      when: 'exploring a codebase or module' },
+    { name: 'zop-guard-skill',  description: 'Security Audit — 5-phase OWASP + auth + compliance sweep',     when: 'security review' },
+    { name: 'zop-merge-skill',  description: 'Merge & Ship — 8-phase safe merge + rebase methodology',       when: 'merging or rebasing branches' },
+    { name: 'zop-review-skill', description: 'Pipeline Code Review — 7-step review methodology',             when: 'reviewing PRs' },
+    { name: 'session-start',    description: 'Session Start — orients the agent at the start of every task', when: 'always include — activates on every session' },
+  ]
+  const CATALOG_PROMPTS = [
+    { name: 'ship-feature',     description: 'Ship Feature — blueprint + build + test + PR workflow',         when: 'building a feature end-to-end' },
+    { name: 'codebase-recon',   description: 'Codebase Recon — systematic exploration prompt',               when: 'exploring an unfamiliar codebase' },
+    { name: 'security-sweep',   description: 'Security Sweep — full OWASP security audit prompt',            when: 'security review or audit' },
+    { name: 'merge-guide',      description: 'Merge Guide — step-by-step merge + rebase instructions',       when: 'merging a branch safely' },
+    { name: 'review-pr',        description: 'Review PR — thorough code review prompt',                      when: 'reviewing a pull request' },
+  ]
+
+  // ── Keyword signals per category (same as recommendKit.js) ───────────────────
+  const KIT_SIGNALS = {
+    builder: {
+      title: 'Build / Implement', color: 'blue', role: 'builder',
+      keywords: ['build', 'implement', 'create', 'add feature', 'feature', 'endpoint', 'api', 'scaffold', 'fix bug', 'bugfix', 'refactor', 'write', 'function', 'component', 'page', 'route', 'module', 'service', 'integrate', 'develop', 'crud', 'migration', 'schema', 'model', 'frontend', 'backend', 'ui', 'form', 'test', 'unit test'],
+      agents: ['zop-shipper'], skills: ['zop-blueprint', 'session-start'], prompts: ['ship-feature'],
+    },
+    scout: {
+      title: 'Explore / Research', color: 'amber', role: 'scout',
+      keywords: ['explore', 'understand', 'map', 'architecture', 'trace', 'document', 'research', 'investigate', 'analyze', 'codebase', 'unfamiliar', 'how does', 'what is', 'find', 'locate', 'data flow', 'dependency', 'diagram', 'audit trail', 'recon', 'tech debt', 'dead code', 'legacy'],
+      agents: ['zop-scout'], skills: ['zop-recon', 'session-start'], prompts: ['codebase-recon'],
+    },
+    security: {
+      title: 'Security / Audit', color: 'red', role: 'builder',
+      keywords: ['security', 'auth', 'authentication', 'authorization', 'vulnerability', 'audit', 'sql injection', 'xss', 'csrf', 'token', 'jwt', 'password', 'encrypt', 'hash', 'permission', 'access control', 'rbac', 'pentest', 'exploit', 'secure', 'leak', 'breach', 'compliance', 'gdpr', 'cors', 'rate limit', 'sanitize', 'owasp'],
+      agents: ['zop-guard'], skills: ['zop-guard-skill', 'session-start'], prompts: ['security-sweep'],
+    },
+    merge: {
+      title: 'Merge / Ship', color: 'cyan', role: 'builder',
+      keywords: ['merge', 'rebase', 'conflict', 'behind main', 'push', 'ship', 'land', 'pr ready', 'close pr', 'squash', 'force push', 'origin'],
+      agents: ['zop-merger'], skills: ['zop-merge-skill', 'session-start'], prompts: ['merge-guide'],
+    },
+    review: {
+      title: 'Code Review', color: 'emerald', role: 'reviewer',
+      keywords: ['review', 'code review', 'pr review', 'approve', 'diff', 'feedback', 'check pr', 'pull request review', 'lgtm', 'request changes', 'reviewer', 'comment on pr'],
+      agents: ['zop-reviewer'], skills: ['zop-review-skill', 'session-start'], prompts: ['review-pr'],
+    },
+    coordinator: {
+      title: 'Coordination / Multi-agent', color: 'violet', role: 'coordinator',
+      keywords: ['large', 'complex', 'multiple', 'parallel', 'coordinate', 'orchestrate', 'decompose', 'breakdown', 'sub-task', 'subtask', 'multi-step', 'multi-agent'],
+      agents: ['zop-orchestrator'], skills: ['zop-blueprint', 'zop-recon', 'session-start'], prompts: ['ship-feature'],
+    },
+  }
+
+  function scoreCorpus(corpus) {
+    const results = []
+    for (const [cat, sig] of Object.entries(KIT_SIGNALS)) {
+      const matched = sig.keywords.filter(kw => corpus.includes(kw))
+      if (matched.length > 0) results.push({ cat, sig, matched, score: matched.length })
+    }
+    results.sort((a, b) => b.score - a.score)
+    return results
+  }
+
+  // ── inspect_kit_for_task ──────────────────────────────────────────────────────
+  server.tool(
+    'inspect_kit_for_task',
+    `Observe all available ZopKit agents, skills, and prompts for a task and get an optimal recommendation.
+
+Call this at the start of a session or when you need to decide which agents/skills/prompts to activate.
+
+Returns:
+- catalog: every available agent, skill, and prompt with status relative to the project config
+  - status: "active" (in project + enabled for task) | "in_project" (in project, not task-overridden) |
+            "project_disabled" (in project but disabled) | "catalog_only" (not yet added to project)
+- recommendation: auto-detected task type + optimal agent/skill/prompt set with matched keywords
+- current_overrides: what's currently set on this task
+- suggested_overrides: ready-to-apply override map — pass directly to apply_kit_to_task
+
+After reviewing, call apply_kit_to_task(taskId, confirmed=true) to apply the recommendation,
+or apply_kit_to_task(taskId, customOverrides={...}, confirmed=true) for a custom selection.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+    },
+    async ({ taskId }) => {
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const projectId = task.project?._id || task.project
+      const projRes   = await api.get(`/api/projects/${projectId}`)
+      const proj      = projRes?.data?.project || {}
+      const cfg       = proj.agentConfig || {}
+
+      const projAgents  = cfg.subagents || []
+      const projSkills  = cfg.skills    || []
+      const projPrompts = cfg.prompts   || []
+      const overrides   = task.agentKitOverrides || {}
+
+      // Build project lookup maps
+      const projAgentMap  = new Map(projAgents.map(i => [i.name, i]))
+      const projSkillMap  = new Map(projSkills.map(i => [i.name, i]))
+      const projPromptMap = new Map(projPrompts.map(i => [i.name, i]))
+
+      function itemStatus(type, name) {
+        const map = type === 'agent' ? projAgentMap : type === 'skill' ? projSkillMap : projPromptMap
+        const sec = type === 'agent' ? 'subagents' : type === 'skill' ? 'skills' : 'prompts'
+        const projItem = map.get(name)
+        if (!projItem) return 'catalog_only'
+        const projectEnabled = projItem.enabled !== false
+        const taskVal = overrides[sec]?.[name]
+        if (!projectEnabled) return 'project_disabled'
+        if (taskVal === false) return 'task_disabled'
+        if (taskVal === true || projectEnabled) return 'active'
+        return 'in_project'
+      }
+
+      // Build full catalog with status
+      const catalogView = {
+        agents:  CATALOG_AGENTS.map(a => ({ ...a, status: itemStatus('agent',  a.name) })),
+        skills:  CATALOG_SKILLS.map(s => ({ ...s, status: itemStatus('skill',  s.name) })),
+        prompts: CATALOG_PROMPTS.map(p => ({ ...p, status: itemStatus('prompt', p.name) })),
+      }
+
+      // Recommendation via keyword scoring
+      const corpus = [task.title || '', task.description || '', task.readmeMarkdown || ''].join(' ').toLowerCase()
+      const scored = scoreCorpus(corpus)
+
+      let primary = scored[0] || null
+      if (!primary && task.agentRole) {
+        const fallbackCat = { builder: 'builder', scout: 'scout', reviewer: 'review', coordinator: 'coordinator' }[task.agentRole]
+        if (fallbackCat && KIT_SIGNALS[fallbackCat]) {
+          primary = { cat: fallbackCat, sig: KIT_SIGNALS[fallbackCat], matched: [], score: 0, fromRole: true }
+        }
+      }
+      if (!primary) primary = { cat: 'builder', sig: KIT_SIGNALS.builder, matched: [], score: 0, fromRole: false }
+
+      const confidence = primary.score === 0 ? 'default' : primary.score >= 3 ? 'strong' : primary.score >= 2 ? 'good' : 'possible'
+
+      // Resolve suggested items against project config (only items in project can be task-overridden)
+      function resolveItems(type, names) {
+        const map = type === 'agent' ? projAgentMap : type === 'skill' ? projSkillMap : projPromptMap
+        return names.filter(n => map.has(n))
+      }
+
+      const rec = primary.sig
+      const suggestedAgents  = resolveItems('agent',  rec.agents)
+      const suggestedSkills  = resolveItems('skill',  rec.skills)
+      const suggestedPrompts = resolveItems('prompt', rec.prompts)
+
+      // Build the override map to pass to apply_kit_to_task
+      const suggestedOverrides = {
+        subagents: Object.fromEntries(projAgents.map(a => [a.name, rec.agents.includes(a.name)])),
+        skills:    Object.fromEntries(projSkills.map(s => [s.name, rec.skills.includes(s.name)])),
+        prompts:   Object.fromEntries(projPrompts.map(p => [p.name, rec.prompts.includes(p.name)])),
+      }
+
+      // Items in recommendation but NOT in project config (hint to add them)
+      const missingFromProject = {
+        agents:  rec.agents.filter(n => !projAgentMap.has(n)),
+        skills:  rec.skills.filter(n => !projSkillMap.has(n)),
+        prompts: rec.prompts.filter(n => !projPromptMap.has(n)),
+      }
+
+      return text({
+        task: { key: task.key, title: task.title, agentRole: task.agentRole || null },
+
+        // ── Full catalog with status ──
+        catalog: catalogView,
+
+        // ── Recommendation ──
+        recommendation: {
+          detected:    primary.cat,
+          title:       rec.title,
+          confidence,
+          role:        rec.role,
+          matchedKeywords: primary.matched,
+          agents:      rec.agents,
+          skills:      rec.skills,
+          prompts:     rec.prompts,
+          note: primary.fromRole
+            ? `No strong signals — defaulting to ${primary.cat} based on task role.`
+            : primary.score === 0
+            ? 'No signals detected — using builder defaults.'
+            : `Detected "${rec.title}" from ${primary.matched.length} keyword match(es).`,
+        },
+
+        // ── What's active right now ──
+        current: {
+          activeAgents:  catalogView.agents.filter(a => a.status === 'active').map(a => a.name),
+          activeSkills:  catalogView.skills.filter(s => s.status === 'active').map(s => s.name),
+          activePrompts: catalogView.prompts.filter(p => p.status === 'active').map(p => p.name),
+          overrides: overrides,
+        },
+
+        // ── What will change if you apply ──
+        suggested: {
+          agents:  suggestedAgents,
+          skills:  suggestedSkills,
+          prompts: suggestedPrompts,
+          role:    rec.role,
+        },
+
+        missingFromProject: (missingFromProject.agents.length + missingFromProject.skills.length + missingFromProject.prompts.length) > 0
+          ? { ...missingFromProject, hint: 'These items are in the ZopKit catalog but not in your project config. Add them via Agent Config (⚙ icon) to enable task-level toggling.' }
+          : null,
+
+        // ── Ready-to-use override payload ──
+        suggestedOverrides,
+
+        nextStep: `Review the recommendation above. Call apply_kit_to_task with taskId="${taskId}" and confirmed=true to apply the suggested kit, or pass customOverrides to set a custom selection.`,
+      })
+    }
+  )
+
+  // ── apply_kit_to_task ─────────────────────────────────────────────────────────
+  server.tool(
+    'apply_kit_to_task',
+    `Apply an agent/skill/prompt kit assignment to a task.
+
+Use after inspect_kit_for_task to assign the recommended or customised kit.
+
+Two modes:
+1. Apply the recommended kit:   call with taskId + confirmed=true (no customOverrides)
+2. Apply custom selections:     call with taskId + customOverrides + confirmed=true
+
+customOverrides format (all keys optional):
+  { subagents: { "zop-shipper": true, "zop-scout": false },
+    skills:    { "zop-blueprint": true, "session-start": true },
+    prompts:   { "ship-feature": true } }
+
+After applying, the kit is visible in the InternalTool UI under the task's Kit tab.
+The next generate_cursor_workspace call will include these active items in the .mdc workspace files.`,
+    {
+      taskId:         z.string().describe("Task's MongoDB ObjectId"),
+      confirmed:      z.boolean().optional().default(false).describe('Set true to apply. Set false (default) to preview what will change.'),
+      customOverrides: z.object({
+        subagents: z.record(z.boolean()).optional(),
+        skills:    z.record(z.boolean()).optional(),
+        prompts:   z.record(z.boolean()).optional(),
+      }).optional().describe('Custom override map. Omit to use the recommendation from inspect_kit_for_task.'),
+    },
+    async ({ taskId, confirmed = false, customOverrides }) => {
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const projectId = task.project?._id || task.project
+      const projRes   = await api.get(`/api/projects/${projectId}`)
+      const proj      = projRes?.data?.project || {}
+      const cfg       = proj.agentConfig || {}
+
+      const projAgents  = cfg.subagents || []
+      const projSkills  = cfg.skills    || []
+      const projPrompts = cfg.prompts   || []
+
+      let overridesToApply = customOverrides
+
+      // If no custom overrides, run the recommendation engine to get the suggested kit
+      if (!overridesToApply) {
+        const corpus = [task.title || '', task.description || '', task.readmeMarkdown || ''].join(' ').toLowerCase()
+        const scored = scoreCorpus(corpus)
+        let primary = scored[0]
+        if (!primary && task.agentRole) {
+          const fallback = { builder: 'builder', scout: 'scout', reviewer: 'review', coordinator: 'coordinator' }[task.agentRole]
+          if (fallback && KIT_SIGNALS[fallback]) primary = { cat: fallback, sig: KIT_SIGNALS[fallback], matched: [], score: 0 }
+        }
+        if (!primary) primary = { cat: 'builder', sig: KIT_SIGNALS.builder, matched: [], score: 0 }
+
+        const rec = primary.sig
+        overridesToApply = {
+          subagents: Object.fromEntries(projAgents.map(a => [a.name, rec.agents.includes(a.name)])),
+          skills:    Object.fromEntries(projSkills.map(s => [s.name, rec.skills.includes(s.name)])),
+          prompts:   Object.fromEntries(projPrompts.map(p => [p.name, rec.prompts.includes(p.name)])),
+        }
+      }
+
+      // Build a human-readable diff
+      const existing = task.agentKitOverrides || {}
+      const changes = []
+      for (const [sec, map] of Object.entries(overridesToApply)) {
+        for (const [name, val] of Object.entries(map || {})) {
+          const was = existing[sec]?.[name]
+          if (was !== val) changes.push({ section: sec, name, from: was !== undefined ? was : '(project default)', to: val })
+        }
+      }
+
+      if (!confirmed) {
+        return text({
+          preview: {
+            changes: changes.length > 0 ? changes : ['No changes — current overrides already match this selection.'],
+            activeAfter: {
+              subagents: projAgents.filter(a => overridesToApply.subagents?.[a.name] !== false && (overridesToApply.subagents?.[a.name] === true || a.enabled !== false)).map(a => a.name),
+              skills:    projSkills.filter(s => overridesToApply.skills?.[s.name]    !== false && (overridesToApply.skills?.[s.name]    === true || s.enabled !== false)).map(s => s.name),
+              prompts:   projPrompts.filter(p => overridesToApply.prompts?.[p.name]  !== false && (overridesToApply.prompts?.[p.name]   === true || p.enabled !== false)).map(p => p.name),
+            },
+          },
+          requiresConfirmation: true,
+          message: `Call apply_kit_to_task again with confirmed=true to apply ${changes.length} change(s).`,
+        })
+      }
+
+      // Apply
+      const res = await api.patch(`/api/tasks/${taskId}`, { agentKitOverrides: overridesToApply })
+      if (!res?.success) return errorText(res?.message || 'Failed to apply kit overrides')
+
+      const activeAgents  = projAgents.filter(a => overridesToApply.subagents?.[a.name] !== false && (overridesToApply.subagents?.[a.name] === true || a.enabled !== false)).map(a => a.name)
+      const activeSkills  = projSkills.filter(s => overridesToApply.skills?.[s.name]    !== false && (overridesToApply.skills?.[s.name]    === true || s.enabled !== false)).map(s => s.name)
+      const activePrompts = projPrompts.filter(p => overridesToApply.prompts?.[p.name]  !== false && (overridesToApply.prompts?.[p.name]   === true || p.enabled !== false)).map(p => p.name)
+
+      return text({
+        applied: true,
+        changes: changes.length,
+        activeKit: { agents: activeAgents, skills: activeSkills, prompts: activePrompts },
+        message:  `✅ Kit applied to task ${task.key}. ${activeAgents.length} agent(s), ${activeSkills.length} skill(s), ${activePrompts.length} prompt(s) now active.`,
+        nextStep: `Call generate_cursor_workspace(projectId="${projectId}", taskId="${taskId}", repoPath="...") to write the active kit items to .cursor/ files so Cursor injects them automatically.`,
+      })
+    }
+  )
+}
+
 function registerAdminTools(server) {
   server.tool(
     'admin_list_users',
@@ -5032,6 +8187,13 @@ async function main() {
   registerNotificationTools(server)
   registerGithubTools(server, ctx)
   registerGitWorkflowTools(server, ctx)
+  registerMergePipelineTools(server, ctx)
+  registerMemoryTools(server, ctx)
+  registerCursorTools(server, ctx)
+  registerOrchestrationTools(server, ctx)
+  registerMonitoringTools(server, ctx)
+  registerWorkspaceScanTool(server)
+  registerKitTools(server)
 
   if (isAdmin) {
     registerAdminTools(server)