internaltool-mcp 1.6.42 → 1.6.52

package/index.js

@@ -520,73 +520,69 @@ After approval, the skill/rule is injected at every future kickoff_task.`,
   // ── plan_task_from_codebase ───────────────────────────────────────────────────
   server.tool(
     'plan_task_from_codebase',
-    `Specialized task-creation agent — analyzes the codebase and creates a fully structured, kickoff-ready task.
-
-Use this instead of create_task when you need to implement something and want the task to
-contain a real implementation plan based on the actual codebase, not a generic description.
+    `Specialized task-creation agent — scouts the codebase, sets up the agent config, and creates a fully-planned, kickoff-ready task.
 
 ## MANDATORY protocol — follow every step in order
 
-### Step 1 — Duplicate check (always first)
+### Step 1 — Duplicate check
 Call search_tasks(projectId, query="<keywords from the request>").
-If a similar open task already exists → return it with kickoff instructions instead of creating a duplicate.
+If a similar open task exists → return it with kickoff instructions. Do NOT create a duplicate.
 
-### Step 2 — Codebase analysis (READ the code, do not guess)
+### Step 2 — Codebase scout (READ the code — do not guess)
 Using your native Read / Grep / Glob tools:
 
 a) **Stack detection** — read package.json / go.mod / requirements.txt / Cargo.toml.
-   Identify: language, framework, major libraries, test runner.
-
-b) **Entry point mapping** — find where the relevant feature area lives:
-   - For backend: grep for existing route patterns (router.post, app.get, @Controller, etc.)
-   - For frontend: grep for existing component patterns, hooks, state management
-   - For DB: find schema/model files
-
-c) **Pattern extraction** — read 2-3 existing files similar to what you'll build.
-   Note: naming conventions, folder structure, how services/routes/components are wired.
-
-d) **Impact analysis** — identify every file that needs to change:
-   - Files to CREATE (new route, new component, new model, new test)
-   - Files to MODIFY (existing router index, existing schema, existing types)
-
-e) **Dependency order** — which files must be built first (schema before service, service before route, etc.)
-
-### Step 3 — Write the implementation plan
-Using what you found in Step 2, build:
+b) **Entry point mapping** — grep for route/component/schema patterns relevant to the feature.
+c) **Pattern extraction** — read 2–3 files similar to what you'll build. Note naming conventions, folder structure, wiring patterns.
+d) **Impact analysis** — list every file to CREATE and every file to MODIFY.
+e) **Dependency order** — schema → model → service → route → test → UI.
+
+### Step 3 — Agent config analysis (use agentConfigAnalysis returned by this tool)
+The tool returns agentConfigAnalysis showing what the project already has and what it needs.
+Act on it BEFORE creating the task:
+
+**a) suggest_skill for each item in agentConfigAnalysis.suggestForProject:**
+   Call suggest_skill(projectId, type, name, description, body, rationale, sourceTaskKey)
+   — one call per missing skill/rule. Use the body template from agentConfigAnalysis.suggestBodyTemplate.
+   These go to the admin approval queue and will be injected at every future kickoff.
+
+**b) Set task-level kit via agentKitOverrides in create_task:**
+   Pass agentKitOverrides = agentConfigAnalysis.taskKitOverrides
+   — this pre-selects the right agents/skills/prompts for THIS task without touching project-level config.
+
+**c) Use remember() for facts that cannot be expressed as a skill or rule:**
+   After create_task, call remember(taskId, key, value) for each fact in agentConfigAnalysis.rememberFacts.
+   Examples: "auth_module = server/middleware/auth.js", "test_runner = jest --runInBand"
+
+### Step 4 — Write the implementation plan
+Using findings from Step 2:
 - ## Goal — one sentence
-- ## Stack — language/framework detected
-- ## Technical approach — how it fits into the existing code (name actual files and functions)
-- ## Files to create — path + what it does
-- ## Files to modify — path + what changes
-- ## Subtasks — ordered implementation steps (schema → service → route → test → UI)
-- ## Acceptance criteria — what done looks like
-
-### Step 4 — Determine task metadata
-- taskType: feature / bugfix / migration / integration / ui / backend / security / refactor
-- priority: low / medium / high / critical (use "high" if the request sounds important)
-- suggestedFiles: the exact file paths from your Step 2d impact analysis
+- ## Stack — detected stack
+- ## Technical approach — real file names and functions
+- ## Files to create
+- ## Files to modify
+- ## Subtasks — ordered steps
+- ## Acceptance criteria
 
 ### Step 5 — Create the task
 Call create_task with:
-- projectId (from this call)
-- title: action-oriented, concise (verb + noun, e.g. "Add rate limiting to /api/auth/login")
-- description: one paragraph summary
-- readmeMarkdown: the full plan from Step 3
-- taskType, priority, column="todo"
-- subtasks: the ordered list from Step 3 (each step = one subtask)
-- suggestedFiles: from Step 2d
-
-After create_task succeeds, immediately call:
-kickoff_task(taskId=<returned id>, confirmed=true, agentRole="builder", files=<suggestedFiles>)
-
-## What makes a high-quality task
-- readmeMarkdown references REAL file paths found by grepping the codebase
-- subtasks are ordered (schema first, then service, then route, then test, then UI)
-- suggestedFiles lists every file that will be touched — no omissions
-- title is specific ("Add email verification to /api/auth/register") not generic ("Add email feature")
-
-Do NOT skip the codebase analysis. Do NOT create the task before reading the code.
-Do NOT ask the developer to describe the codebase — read it yourself.`,
+- projectId, title (verb+noun), description, readmeMarkdown, taskType, priority, column="todo"
+- subtasks (ordered), suggestedFiles (from Step 2d)
+- agentKitOverrides from Step 3b
+
+### Step 6 — Post-creation setup
+1. For each fact in agentConfigAnalysis.rememberFacts: call remember(taskId, key, value)
+2. Log to session: call log_session_event(taskId, type="info", name="task-created", summary="Scouted codebase, configured kit, created task")
+3. Present the approval summary to the developer and wait for submit_task_for_approval confirmation
+
+## Quality checklist
+- readmeMarkdown references REAL file paths
+- subtasks are ordered (schema → model → service → route → test → UI)
+- agentKitOverrides is set based on task type
+- suggest_skill was called for any missing project-level skills
+- remember() was called for codebase-specific facts
+
+Do NOT skip the scout phase. Do NOT ask the developer to describe the codebase.`,
     {
       projectId: z.string().describe("InternalTool project's MongoDB ObjectId — from the project's task board URL or CLAUDE.md"),
       request:   z.string().describe('What the developer wants to build — the raw natural language request (e.g. "add rate limiting to the login endpoint", "fix the pagination bug on users list")'),
@@ -604,8 +600,9 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
       const dirTree     = getDirTree(cwd, 2)
       const entryPoints = findEntryPoints(cwd, stack)
 
-      // ── 2. Fetch project context ──────────────────────────────────────────────
+      // ── 2. Fetch project context + existing agentConfig ─────────────────────
       let projectContext = null
+      let existingAgentConfig = { skills: [], rules: [], subagents: [], prompts: [] }
       try {
         const projRes = await api.get(`/api/projects/${projectId}`)
         if (projRes?.success) {
@@ -615,6 +612,13 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
             taskCount:  (projRes.data.tasks || []).length,
             githubRepo: p.github?.repoUrl || null,
           }
+          const cfg = p.agentConfig || {}
+          existingAgentConfig = {
+            skills:    (cfg.skills    || []).map(s => s.name),
+            rules:     (cfg.rules     || []).map(r => r.name),
+            subagents: (cfg.subagents || []).map(a => a.name),
+            prompts:   (cfg.prompts   || []).map(p => p.name),
+          }
         }
       } catch { /* non-fatal */ }
 
@@ -632,7 +636,102 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
         }
       } catch { /* non-fatal */ }
 
-      // ── 4. Return codebase intelligence + tight instructions ──────────────────
+      // ── 4. Agent config gap analysis ─────────────────────────────────────────
+      // Determine what kit the task needs based on stack + request keywords
+      const requestCorpus = `${request} ${stack.language || ''} ${stack.framework || ''} ${(stack.extra || []).join(' ')}`.toLowerCase()
+
+      // Map task type keywords → what kit category is relevant
+      const KIT_CATEGORY_HINTS = {
+        security:    ['auth', 'security', 'jwt', 'password', 'permission', 'rbac', 'owasp', 'token', 'encrypt', 'rate limit', 'sanitize'],
+        scout:       ['explore', 'understand', 'architecture', 'trace', 'how does', 'what is', 'map', 'audit', 'recon', 'investigate'],
+        merge:       ['merge', 'rebase', 'conflict', 'ship', 'push', 'pr', 'branch'],
+        review:      ['review', 'code review', 'diff', 'approve', 'feedback', 'pull request'],
+        coordinator: ['large', 'complex', 'parallel', 'coordinate', 'orchestrate', 'decompose', 'multi-step'],
+        builder:     ['build', 'implement', 'create', 'add', 'fix', 'feature', 'endpoint', 'route', 'component', 'model', 'service', 'crud'],
+      }
+      let detectedKitCategory = 'builder'
+      let maxKitScore = 0
+      for (const [cat, keywords] of Object.entries(KIT_CATEGORY_HINTS)) {
+        const score = keywords.filter(kw => requestCorpus.includes(kw)).length
+        if (score > maxKitScore) { maxKitScore = score; detectedKitCategory = cat }
+      }
+
+      // Kit catalog — what skills/agents/prompts exist in ZopKit
+      const ZOPKIT_SKILLS_CATALOG  = ['zop-blueprint', 'zop-recon', 'zop-guard-skill', 'zop-merge-skill', 'zop-review-skill', 'session-start']
+      const ZOPKIT_AGENTS_CATALOG  = ['zop-shipper', 'zop-scout', 'zop-guard', 'zop-merger', 'zop-reviewer', 'zop-orchestrator']
+      const ZOPKIT_PROMPTS_CATALOG = ['ship-feature', 'codebase-recon', 'security-sweep', 'merge-guide', 'review-pr']
+
+      // Recommended kit for detected category
+      const KIT_RECOMMENDATIONS = {
+        builder:     { skills: ['zop-blueprint', 'session-start'], agents: ['zop-shipper'],      prompts: ['ship-feature'] },
+        scout:       { skills: ['zop-recon', 'session-start'],     agents: ['zop-scout'],        prompts: ['codebase-recon'] },
+        security:    { skills: ['zop-guard-skill', 'session-start'], agents: ['zop-guard'],      prompts: ['security-sweep'] },
+        merge:       { skills: ['zop-merge-skill', 'session-start'], agents: ['zop-merger'],     prompts: ['merge-guide'] },
+        review:      { skills: ['zop-review-skill', 'session-start'], agents: ['zop-reviewer'],  prompts: ['review-pr'] },
+        coordinator: { skills: ['zop-blueprint', 'zop-recon', 'session-start'], agents: ['zop-orchestrator'], prompts: ['ship-feature'] },
+      }
+      const recommendedKit = KIT_RECOMMENDATIONS[detectedKitCategory] || KIT_RECOMMENDATIONS.builder
+
+      // What's already in the project vs what's missing
+      const missingSkills  = recommendedKit.skills.filter(s => !existingAgentConfig.skills.includes(s))
+      const missingAgents  = recommendedKit.agents.filter(a => !existingAgentConfig.subagents.includes(a))
+      const missingPrompts = recommendedKit.prompts.filter(p => !existingAgentConfig.prompts.includes(p))
+
+      // Task-level overrides: enable recommended, disable irrelevant
+      const taskKitOverrides = {
+        skills:    Object.fromEntries([
+          ...existingAgentConfig.skills.map(s => [s, recommendedKit.skills.includes(s)]),
+          ...recommendedKit.skills.filter(s => !existingAgentConfig.skills.includes(s)).map(s => [s, false]), // not in project yet — pending suggest_skill
+        ]),
+        subagents: Object.fromEntries(existingAgentConfig.subagents.map(a => [a, recommendedKit.agents.includes(a)])),
+        prompts:   Object.fromEntries(existingAgentConfig.prompts.map(p => [p, recommendedKit.prompts.includes(p)])),
+      }
+
+      // Stack-derived codebase facts that should be persisted via remember()
+      const rememberFacts = [
+        stack.language    && { key: 'stack_language',    value: stack.language },
+        stack.framework   && { key: 'stack_framework',   value: stack.framework },
+        stack.testRunner  && { key: 'stack_test_runner', value: stack.testRunner },
+        stack.packageManager && { key: 'stack_pkg_manager', value: stack.packageManager },
+        entryPoints.routes?.[0]     && { key: 'entry_routes',  value: entryPoints.routes[0] },
+        entryPoints.models?.[0]     && { key: 'entry_models',  value: entryPoints.models[0] },
+        entryPoints.components?.[0] && { key: 'entry_components', value: entryPoints.components[0] },
+      ].filter(Boolean)
+
+      // Skill suggestion templates for each missing item
+      const SKILL_BODY_TEMPLATES = {
+        'zop-blueprint':    `## Feature Blueprint\n1. Define the data model / schema changes\n2. Build the API layer (route → service → model)\n3. Build the frontend (component → hook → API call)\n4. Wire everything together\n5. Write tests (unit + integration)\n6. Update README / docs`,
+        'zop-recon':        `## Codebase Recon\n1. Read entry points: routes, models, middleware, utils\n2. Map the data flow end-to-end\n3. Identify patterns: naming conventions, error handling, auth\n4. Find gaps: missing tests, dead code, undocumented APIs\n5. Write findings to scout_task`,
+        'zop-guard-skill':  `## Security Audit\n1. Check authentication (JWT expiry, refresh, revocation)\n2. Check authorization (role checks on every sensitive route)\n3. Check input validation (Zod/Joi on all user inputs)\n4. Check for injection (SQL, NoSQL, command)\n5. Check error messages (no stack traces exposed)\n6. Run OWASP Top 10 checklist`,
+        'zop-merge-skill':  `## Merge & Ship\n1. git fetch origin && git rebase origin/main\n2. Resolve any conflicts using resolve_conflict tool\n3. Run full test suite — must be green\n4. Push with --force-with-lease\n5. Verify PR CI passes\n6. Request final review`,
+        'zop-review-skill': `## Code Review\n1. Read the task README to understand intent\n2. Review each changed file: correctness, edge cases, security\n3. Check test coverage: are new paths tested?\n4. Check for breaking changes\n5. Post review with specific file+line comments\n6. Approve or request changes`,
+        'session-start':    `## Session Start\n1. Call recall(taskId) to restore memory from previous sessions\n2. Call get_agent_context(taskId) for the full implementation plan\n3. Check local git state: \`git status\`\n4. Check branch: \`git branch --show-current\`\n5. Read any changed files since last session\n6. Resume work from where you left off`,
+      }
+      const AGENT_BODY_TEMPLATES = {
+        'zop-shipper':      `You are a builder agent. Your job is to implement code end-to-end.\nConstraints:\n- Only modify files listed in claimedFiles\n- Every change needs a test\n- Run tests before marking done\n- Never modify auth middleware without explicit approval`,
+        'zop-scout':        `You are a scout agent. Your job is to map the codebase — READ ONLY.\nConstraints:\n- Never write or modify any file\n- Read every source file systematically\n- Write findings via scout_task tool\n- Focus on: data flow, auth, API surface, test coverage, gaps`,
+        'zop-guard':        `You are a security audit agent.\nConstraints:\n- Check auth, authorization, input validation, and OWASP Top 10\n- Report findings as structured issues, not inline comments\n- Never modify security-critical code without explicit admin approval`,
+        'zop-orchestrator': `You are a coordinator agent. Your job is to decompose and delegate — NO CODE.\nConstraints:\n- Call decompose_task to break work into parallel subtasks\n- Call get_parallel_kickoffs to generate builder prompts\n- Never implement anything yourself\n- Each subtask must have exclusive file ownership`,
+      }
+
+      const suggestForProject = [
+        ...missingSkills.map(name => ({
+          type: 'skill',
+          name,
+          description: `${name} — ${ZOPKIT_SKILLS_CATALOG.includes(name) ? 'ZopKit standard skill' : 'custom skill'}`,
+          body: SKILL_BODY_TEMPLATES[name] || `## ${name}\n[Add instructions here]`,
+          rationale: `Detected task type: ${detectedKitCategory}. This skill guides the builder through the ${name.replace('zop-', '').replace('-skill', '')} process in this codebase.`,
+        })),
+        ...missingAgents.map(name => ({
+          type: 'subagent',
+          name,
+          description: `${name} — ${ZOPKIT_AGENTS_CATALOG.includes(name) ? 'ZopKit standard agent' : 'custom agent'}`,
+          body: AGENT_BODY_TEMPLATES[name] || `## ${name} Agent\n[Add role instructions here]`,
+          rationale: `Detected task type: ${detectedKitCategory}. This agent persona enforces the right constraints for ${name.replace('zop-', '')} sessions.`,
+        })),
+      ]
+
+      // ── 5. Return codebase intelligence + tight instructions ──────────────────
       const hasEntryPoints = Object.keys(entryPoints).length > 0
       const stackSummary = [
         stack.language, stack.framework, stack.testRunner, ...(stack.extra || [])
@@ -649,6 +748,26 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
             : { note: 'No entry points found at cwd — check that MCP server is running from the project root' },
         },
 
+        // Agent config analysis — act on this BEFORE calling create_task
+        agentConfigAnalysis: {
+          detectedKitCategory,
+          recommendedKit,
+          existingProjectConfig: existingAgentConfig,
+          missingFromProject: { skills: missingSkills, agents: missingAgents, prompts: missingPrompts },
+          suggestForProject,   // call suggest_skill for each item here
+          taskKitOverrides,    // pass as agentKitOverrides to create_task
+          rememberFacts,       // call remember(taskId, key, value) for each after create_task
+          instruction: [
+            suggestForProject.length > 0
+              ? `⚠️  ${suggestForProject.length} item(s) are missing from project config — call suggest_skill for each before creating the task.`
+              : `✅ Project config already has the recommended kit for ${detectedKitCategory} tasks.`,
+            `Pass taskKitOverrides as agentKitOverrides in create_task to pre-configure this task.`,
+            rememberFacts.length > 0
+              ? `After create_task, call remember(taskId, key, value) for ${rememberFacts.length} codebase fact(s) so future sessions don't need to re-scout.`
+              : null,
+          ].filter(Boolean).join('\n'),
+        },
+
         // Duplicate guard
         ...(similarTasks?.length > 0 && {
           duplicateWarning: true,
@@ -656,16 +775,21 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
           duplicateInstruction: 'Check the list above. If one matches → call kickoff_task on it. If none match → proceed.',
         }),
 
-        // What to do now — use codebaseIntelligence above to skip re-reading the filesystem
+        // What to do now
         nextSteps: [
-          'Use dirTree + entryPoints above to identify which files need changing — you already have the map.',
-          `Read 2-3 files from entryPoints.routes / entryPoints.models / entryPoints.components to extract naming conventions and wiring patterns.`,
-          'Draft readmeMarkdown with: ## Goal, ## Stack, ## Technical approach (name real files), ## Files to create, ## Files to modify, ## Subtasks (ordered), ## Acceptance criteria.',
-          `Call create_task(projectId="${projectId}", title="<verb + noun>", readmeMarkdown="<plan>", taskType="<feature|bugfix|...>", priority="${priority}", column="todo", subtasks=[...], suggestedFiles=[...])`,
-          'Immediately after: call kickoff_task(taskId=<returned id>, confirmed=true, agentRole="builder", files=[...suggestedFiles])',
-        ],
+          suggestForProject.length > 0
+            ? `FIRST: call suggest_skill for each item in agentConfigAnalysis.suggestForProject (${suggestForProject.length} item(s)). Use the body and rationale from the array.`
+            : null,
+          'Read 2-3 files from entryPoints.routes / entryPoints.models / entryPoints.components to extract naming conventions.',
+          'Draft readmeMarkdown: ## Goal, ## Stack, ## Technical approach, ## Files to create, ## Files to modify, ## Subtasks, ## Acceptance criteria.',
+          `Call create_task(projectId="${projectId}", title="<verb+noun>", readmeMarkdown="<plan>", taskType="<type>", priority="${priority}", column="todo", subtasks=[...], suggestedFiles=[...], agentKitOverrides=agentConfigAnalysis.taskKitOverrides)`,
+          'After create_task: call remember(taskId, key, value) for each fact in agentConfigAnalysis.rememberFacts.',
+          'Then: call log_session_event(taskId, type="info", name="task-created", summary="Codebase scouted, kit configured, task created").',
+          'Then: call kickoff_task(taskId, confirmed=false) to preview the plan and check git state.',
+          'Then: call submit_task_for_approval(taskId, summary="<3-8 sentence summary>", reviewerId="<admin id>").',
+          'After approval: call kickoff_task(taskId, confirmed=true, agentRole="builder", files=[...suggestedFiles]).',
+        ].filter(Boolean),
 
-        // Context
         request,
         projectId,
         priority,
@@ -715,8 +839,13 @@ Always prefer column="todo" so the task is visibly ready to start.`,
         .describe('Ordered implementation checklist — shown in the task UI and read by agents at kickoff. Order matters: schema → model → service → route → test → frontend.'),
       suggestedFiles: z.array(z.string()).optional()
         .describe('Files the builder will claim at kickoff (e.g. ["server/routes/tasks.js", "server/models/Task.js"]). Included in the task README automatically so the builder knows what to pass to kickoff_task files=[...].'),
+      agentKitOverrides: z.object({
+        skills:    z.record(z.boolean()).optional(),
+        subagents: z.record(z.boolean()).optional(),
+        prompts:   z.record(z.boolean()).optional(),
+      }).optional().describe('Task-level skill/agent/prompt overrides — pass agentConfigAnalysis.taskKitOverrides from plan_task_from_codebase to pre-configure the right kit for this task.'),
     },
-    async ({ projectId, suggestedFiles, ...taskData }) => {
+    async ({ projectId, suggestedFiles, agentKitOverrides, ...taskData }) => {
       try { assertProjectScope(projectId) } catch (e) { return errorText(e.message) }
 
       // Append suggested files section to the README so the builder sees them at kickoff
@@ -736,18 +865,37 @@ Always prefer column="todo" so the task is visibly ready to start.`,
       if (!res?.success) return errorText(res?.message || 'Failed to create task')
 
       const task = res.data?.task
+
+      // Apply agentKitOverrides immediately if provided
+      let kitApplied = null
+      if (task?._id && agentKitOverrides && Object.keys(agentKitOverrides).length > 0) {
+        try {
+          const kitRes = await api.patch(`/api/tasks/${task._id}`, { agentKitOverrides })
+          kitApplied = kitRes?.success
+            ? { applied: true, overrides: agentKitOverrides }
+            : { applied: false, reason: kitRes?.message }
+        } catch { kitApplied = { applied: false, reason: 'patch failed' } }
+      }
+
       return text({
-        created:   true,
-        taskId:    task?._id,
-        taskKey:   task?.key,
-        title:     task?.title,
-        column:    task?.column,
-        taskType:  task?.taskType || null,
-        subtasks:  (task?.subtasks || []).length,
-        kickoff:   task?._id
-          ? `kickoff_task(taskId="${task._id}", confirmed=false)  ← read plan first\nkickoff_task(taskId="${task._id}", confirmed=true, agentRole="builder", files=[...])  ← start building`
+        created:    true,
+        taskId:     task?._id,
+        taskKey:    task?.key,
+        title:      task?.title,
+        column:     task?.column,
+        taskType:   task?.taskType || null,
+        subtasks:   (task?.subtasks || []).length,
+        kitApplied,
+        nextStep: task?._id
+          ? [
+              `1. Call remember(taskId="${task._id}", key, value) for each fact in agentConfigAnalysis.rememberFacts.`,
+              `2. Call log_session_event(taskId="${task._id}", type="info", name="task-created", summary="Codebase scouted, kit configured").`,
+              `3. Call kickoff_task(taskId="${task._id}", confirmed=false) — read the plan and check local git state.`,
+              `4. Call submit_task_for_approval(taskId="${task._id}", summary="<3-8 sentences>", reviewerId="<admin id>").`,
+              `5. After approval: call kickoff_task(taskId="${task._id}", confirmed=true, agentRole="builder", files=[...]).`,
+            ].join('\n')
           : null,
-        message: `Task ${task?.key} created and ready to kick off.`,
+        message: `Task ${task?.key} created${kitApplied?.applied ? ' with kit overrides applied' : ''}. Follow nextStep — do NOT branch until the plan is approved.`,
       })
     }
   )
@@ -815,7 +963,7 @@ WHAT THIS DOES AUTOMATICALLY (confirmed=true):
 1. Verifies all changes are committed and pushed — blocks if not
 2. Auto-pushes any unpushed commits to remote
 3. Saves your park note (summary, remaining, blockers) to the task
-4. Deletes the cursor rules file (.cursor/rules/<task>.mdc) so it doesn't bleed into other tasks
+4. Deletes all workspace files (.cursor/rules/, .cursor/skills/, .cursor/agents/) so they don't bleed into other tasks
 5. Posts a comment on the task with your handoff notes (visible to Dev B)
 6. Notifies all project members that this task is parked and ready for pickup
 
@@ -875,8 +1023,10 @@ Set confirmed=false first to preview, then confirmed=true to execute everything.
       // ── Auto-commit if there are uncommitted changes ───────────────────────
       if (repoRoot && uncommitted) {
         try {
-          const commitMsg = `wip(${task?.key?.toLowerCase() || 'task'}): ${(summary || 'parking task').slice(0, 60)}`
-          runGit('add -A', repoRoot)
+          const rawMsg = `wip(${task?.key?.toLowerCase() || 'task'}): ${(summary || 'parking task').slice(0, 60)}`
+          // Sanitize to prevent shell injection — strip/replace special chars
+          const commitMsg = rawMsg.replace(/"/g, "'").replace(/[`$\\]/g, '')
+          runGit('add -u', repoRoot)  // only tracked files — avoids staging .env / build artifacts
           runGit(`commit -m "${commitMsg}"`, repoRoot)
           unpushedCount += 1   // just committed, so now there's something to push
         } catch (e) {
@@ -939,10 +1089,12 @@ WHAT THIS DOES AUTOMATICALLY (confirmed=true):
 2. Shows the last 5 commits on the branch so you know the exact state of the code
 3. Shows recent task comments so you have full context
 4. Runs: git fetch origin + git checkout <branch> + git pull (switches your local repo)
-5. Restores the cursor rules file (.cursor/rules/<task>.mdc) so Cursor follows task rules
-6. Posts a comment that you picked up the task
-7. Notifies the previous developer that you have taken over
+5. Restores the FULL cursor workspace: rules, skills, session-protocol, active-agent.md
+6. Logs all restored skills/rules to the session activity timeline
+7. Posts a comment that you picked up the task
+8. Notifies the previous developer that you have taken over
 
+After unparking: READ all injected skills before touching any files. Then re-claim files.
 Set confirmed=false first to read everything, then confirmed=true to execute.`,
     {
       taskId:    z.string().describe("Task's MongoDB ObjectId"),
@@ -992,6 +1144,8 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
             `git checkout ${branch}`,
             `git pull origin ${branch}`,
             task?.cursorRules?.trim() ? `Restore .cursor/rules/${task.key?.toLowerCase()}.mdc` : null,
+            `Restore full cursor workspace (skills, session-protocol, active-agent.md)`,
+            `Log restored workspace files to session timeline`,
             'Post "picked up" comment on task',
             'Notify previous developer',
           ].filter(Boolean) : ['No branch linked — create one with create_branch after unparking'],
@@ -1081,6 +1235,37 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
         api.patch(`/api/tasks/${taskId}`, { agentRole }).catch(() => {/* non-fatal */})
       }
 
+      // ── Re-write full cursor workspace (skills, session protocol, active-agent) ──
+      // park_task deletes everything; unpark_task must restore the complete workspace.
+      let workspaceResult = null
+      try {
+        let projectAgentConfig = null
+        try {
+          const projRes = await api.get(`/api/projects/${task.project}`)
+          if (projRes?.success) projectAgentConfig = projRes.data.project?.agentConfig || null
+        } catch { /* non-fatal */ }
+
+        const taskForWorkspace = agentRole ? { ...task, agentRole } : task
+        workspaceResult = writeCursorWorkspace(taskForWorkspace, projectAgentConfig, repoPath || process.cwd())
+
+        // Log injected skills/rules to session timeline
+        // Log each written file to session timeline
+        const writtenFiles = workspaceResult?.written || []
+        for (const filePath of writtenFiles) {
+          const fileName = filePath.split('/').pop().replace(/\.(md|mdc)$/, '')
+          const isSkill  = filePath.includes('/.cursor/skills/')
+          const isRule   = filePath.includes('/.cursor/rules/')
+          const isAgent  = filePath.includes('/.cursor/agents/')
+          const type = isSkill ? 'skill' : isRule ? 'rule' : isAgent ? 'subagent' : 'info'
+          api.post(`/api/tasks/${taskId}/session/log`, {
+            type,
+            name:    fileName,
+            role:    agentRole || null,
+            summary: `📖 Injected at unpark: ${filePath.replace(workspaceResult.repoRoot, '')}`,
+          }).catch(() => {})
+        }
+      } catch { /* non-fatal — workspace restore failure should not block the unpark */ }
+
       // ── #9 Last commit metadata for handoff context ───────────────────────
       const lastCommit = getLastCommitMeta(repoRoot)
 
@@ -1093,21 +1278,30 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
         cursorRules: cursorRulesFile
           ? { restored: true, path: cursorRulesFile, agentRole: agentRole || null }
           : { restored: false },
+        workspace: workspaceResult
+          ? { restored: true, filesCount: workspaceResult.written?.length || 0, files: workspaceResult.written || [] }
+          : { restored: false },
         commentPosted:       true,
         previousDevNotified: true,
         parkNote: task?.parkNote || null,
         message: gitResult?.switched
-          ? `You are now on branch "${branch}". Cursor rules restored${agentRole ? ` (role: ${agentRole})` : ''}. Start coding from where ${task?.parkNote?.parkedBy ? 'the previous developer' : 'you'} left off.`
-          : `Branch switch failed — see git.manualSteps. Cursor rules restored.`,
+          ? `You are now on branch "${branch}". Cursor workspace restored${agentRole ? ` (role: ${agentRole})` : ''}. Read all skills before editing.`
+          : `Branch switch failed — see git.manualSteps. Cursor workspace restored.`,
+        previouslyClaimed: task?.claimedFiles?.length ? task.claimedFiles : null,
         nextStep: agentRole === 'builder'
-          ? `BUILDER role active. Call claim_files to lock your files before editing.`
+          ? [
+              `BUILDER role active.`,
+              `1. ⚠️ READ all injected skills first (listed in workspace.files) — mandatory before any edits`,
+              `2. Re-claim your files: claim_files(taskId="${taskId}", files=${JSON.stringify(task?.claimedFiles || [])})`,
+              `3. Then continue implementation from where the previous developer left off`,
+            ].join('\n')
           : agentRole === 'scout'
           ? `SCOUT role active. Read-only mode — map the codebase and save findings with update_task(scoutReport=...).`
           : agentRole === 'coordinator'
           ? `COORDINATOR role active. Call decompose_task to plan parallel workstreams.`
           : agentRole === 'reviewer'
           ? `REVIEWER role active. Call review_pr to start the review chain.`
-          : null,
+          : `Read all injected skills in workspace.files before making any changes.`,
       })
     }
   )
@@ -1389,52 +1583,92 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
             templates: decompositionTemplates,
           } : null,
           warnings: [
-            !executionPlan.scoutReportPresent ? '⚠️  No scout report on this task. Consider running a scout agent first to map the codebase before builders start.' : null,
-            !executionPlan.readmePresent ? '⚠️  No implementation plan (README). Builders need a spec to work from.' : null,
+            !executionPlan.scoutReportPresent
+              ? '⛔ SCOUT REPORT MISSING — Strongly recommended before decomposing. Builders without a scout map will guess at file ownership and produce overlapping work. Call kickoff_task(agentRole="scout", confirmed=true) first.'
+              : null,
+            !executionPlan.readmePresent
+              ? '⛔ NO IMPLEMENTATION PLAN — Builders cannot implement without a spec. Call update_task(readmeMarkdown=...) before decomposing.'
+              : null,
+            subtaskPlan.some(s => !s.files?.length)
+              ? `⚠️  ${subtaskPlan.filter(s => !s.files?.length).map(s => s.title).join(', ')} — no files declared. Every subtask MUST own at least one file to prevent two builders editing the same code.`
+              : null,
           ].filter(Boolean),
+          scoutFirstInstruction: !executionPlan.scoutReportPresent
+            ? `MANDATORY: call scout_task(taskId="${task._id}", confirmed=false) then scout_task(confirmed=true, report="<your findings>") before confirming this decomposition. Do NOT switch agentRole — run scout_task directly as coordinator.`
+            : null,
           requiresConfirmation: true,
           message: 'Review the decomposition above. Call decompose_task again with confirmed=true to save it and create the subtasks on the board.',
         })
       }
 
-      // Save decomposition JSON to parent task
-      const decompositionJson = JSON.stringify(executionPlan, null, 2)
-      try {
-        await api.patch(`/api/tasks/${taskId}`, { decomposition: decompositionJson })
-      } catch { /* non-fatal */ }
-
       // Create real child tasks for each subtask in the plan
+      // Do this BEFORE saving the decomposition JSON so we can embed child task IDs.
       const projectId = task.project?._id || task.project
       const createdTasks = []
+      // Build a map from subtask title → child task info for embedding into executionPlan
+      const childTaskByTitle = {}
+
       for (const s of subtaskPlan) {
         try {
+          // Role → generic role-appropriate skills that any project should have.
+          // We avoid hardcoding third-party skill names (e.g. zop-*) because projects
+          // may not have those configured — the agent would look for files that don't exist.
+          // The project-level agentConfig.skills drive what actually gets written to .cursor/skills/.
+          const ROLE_KIT = {
+            builder:     { skills: { 'run-tests': true, 'commit-conventions': true }, subagents: {}, prompts: {} },
+            scout:       { skills: { 'scout-codebase': true },                        subagents: {}, prompts: {} },
+            reviewer:    { skills: { 'review-checklist': true, 'run-tests': true },   subagents: {}, prompts: {} },
+            coordinator: { skills: { 'scout-codebase': true, 'run-tests': true },     subagents: {}, prompts: {} },
+          }
+          const childKit = ROLE_KIT[s.role] || ROLE_KIT.builder
+
           const childRes = await api.post(`/api/projects/${projectId}/tasks`, {
             title:          `[${s.role.toUpperCase()}] ${s.title}`,
             description:    s.description,
             readmeMarkdown: [
               `## Role: ${s.role}`,
+              `## Parent task: ${task.key} — ${task.title}`,
               `## Description\n${s.description}`,
               s.files?.length ? `## Files to claim at kickoff\n${s.files.map(f => `- \`${f}\``).join('\n')}` : '',
-              s.dependsOn?.length ? `## Depends on\n${s.dependsOn.map(d => `- ${d}`).join('\n')}` : '',
+              s.dependsOn?.length ? `## Depends on (must complete before this starts)\n${s.dependsOn.map(d => `- ${d}`).join('\n')}` : '',
+              `## Skills to read BEFORE editing\nRead every .md file in .cursor/skills/ that was written at kickoff.`,
+              `## After finishing\nCall park_task or raise_pr, then update the parent task (${task.key}) subtask checklist.`,
             ].filter(Boolean).join('\n\n'),
-            column:      'todo',
-            priority:    task.priority || 'medium',
-            taskType:    s.role === 'reviewer' ? 'feature' : (task.taskType || 'feature'),
-            parentTask:  taskId,
+            column:         'todo',
+            priority:       task.priority || 'medium',
+            taskType:       s.role === 'reviewer' ? 'feature' : (task.taskType || 'feature'),
+            parentTask:     taskId,
             suggestedFiles: s.files || [],
+            agentKitOverrides: childKit,
           })
           if (childRes?.success) {
-            createdTasks.push({
+            const childInfo = {
               taskId:  childRes.data?.task?._id,
               taskKey: childRes.data?.task?.key,
               title:   childRes.data?.task?.title,
               role:    s.role,
               files:   s.files,
-            })
+            }
+            createdTasks.push(childInfo)
+            childTaskByTitle[s.title] = childInfo
           }
         } catch { /* non-fatal — continue creating remaining tasks */ }
       }
 
+      // Embed child task IDs into the execution plan so get_parallel_kickoffs can route
+      // each builder to their own child task (not the parent task).
+      executionPlan.subtasks = executionPlan.subtasks.map(s => ({
+        ...s,
+        childTaskId:  childTaskByTitle[s.title]?.taskId  || null,
+        childTaskKey: childTaskByTitle[s.title]?.taskKey || null,
+      }))
+
+      // Save decomposition JSON to parent task — now includes child task IDs
+      const decompositionJson = JSON.stringify(executionPlan, null, 2)
+      try {
+        await api.patch(`/api/tasks/${taskId}`, { decomposition: decompositionJson })
+      } catch { /* non-fatal */ }
+
       return text({
         decomposed: true,
         taskKey:    task.key,
@@ -1455,16 +1689,17 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
     `Scout agent entry point: analyze the codebase for a task and save a structured scout report.
 
 Call this BEFORE builders start when the Coordinator needs a codebase map.
-Use agentRole="scout" in kickoff_task first, then call scout_task to get your briefing.
+Coordinators call this directly — do NOT switch agentRole to "scout" to call it.
+Agents with agentRole="scout" also call this as their primary work tool.
 
 Two-phase flow:
   Phase 1 — confirmed=false: get the briefing (what to analyze, report format)
   Phase 2 — confirmed=true + report: save your findings to the task
 
 The scout report is consumed by:
-- decompose_task (warns if missing)
-- get_agent_context (included in builder context)
-- kickoff_task (surfaced as part of builder brief)
+- decompose_task (warns if missing, refuses to decompose without one)
+- get_agent_context (automatically included in builder system prompt)
+- kickoff_task (surfaced as part of the builder brief)
 
 Scouts MUST NOT modify any source code files or create branches.`,
     {
@@ -1781,11 +2016,24 @@ This tool posts a comment on the task (for visibility in the app) and notifies a
       trackTaskActivity(taskId, 'request_human_input')
       await api.post(`/api/tasks/${taskId}/ask-human`, { question, context, type }).catch(() => null)
 
+      // Detect whether we're likely running as a Cursor Background Agent (non-interactive).
+      // Background agents cannot receive chat replies — the human must check the InternalTool
+      // task comments to see the question, then the agent should use a safe default and move on.
+      // We surface this explicitly so the agent does not pause indefinitely.
+      const isBackgroundLikely = !process.stdin.isTTY
+
       const typeLabel = type === 'approval' ? '🔐 APPROVAL NEEDED' : type === 'ambiguity' ? '🤔 AMBIGUITY — YOUR DECISION' : '❓ QUESTION FOR YOU'
       return text({
         [typeLabel]: question,
         ...(context ? { context } : {}),
-        instruction: 'Please reply in this Cursor chat. I will use your answer to continue. Do NOT proceed until you reply.',
+        backgroundAgentWarning: isBackgroundLikely
+          ? 'You appear to be running as a Background Agent (no interactive TTY). The question has been posted as a task comment and the developer has been notified. Since there is no interactive chat channel, DO NOT wait indefinitely. Use the safest autonomous default and proceed, then note your decision in a log_session_event call.'
+          : null,
+        instruction: isBackgroundLikely
+          ? 'Background agent mode: proceed with the safest default decision. Log your choice with log_session_event(type="info", name="autonomous-decision", summary="<what you decided and why>").'
+          : 'Please reply in this Cursor chat. I will use your answer to continue. Do NOT proceed until you reply.',
+        taskCommentPosted: true,
+        developerNotified: true,
       })
     }
   )
@@ -1912,16 +2160,58 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
         } catch { /* non-fatal */ }
       }
 
-      // Suggest relevant skills based on role and available project skills
-      // Respects project-level enabled + task-level agentKitOverrides
+      // Filter skills to only those relevant to this role and task type.
+      // An agent should NOT load every project skill — only what it needs for this specific task.
       const allProjectSkills = ctx.project?.agentConfig?.skills || []
       const taskSkillOverrides = ctx.task?.agentKitOverrides?.skills || {}
-      const availableSkills = allProjectSkills.filter(s => {
+      const enabledSkills = allProjectSkills.filter(s => {
         const taskOverride = taskSkillOverrides[s.name]
         return taskOverride !== undefined ? taskOverride : s.enabled !== false
       })
-      const suggestedSkills = availableSkills.length > 0
-        ? availableSkills.map(s => ({
+
+      // Role-based relevance filter: each role only gets skills that match its job.
+      // Keywords for each role are matched against skill name + description.
+      const ROLE_SKILL_KEYWORDS = {
+        builder:     ['test', 'run', 'build', 'lint', 'commit', 'style', 'deploy', 'migration', 'seed',
+                      'implement', 'feature', 'api', 'endpoint', 'component', 'service', 'hook',
+                      'util', 'helper', 'create', 'update', 'delete', 'fix', 'patch', 'convention'],
+        scout:       ['scout', 'codebase', 'explore', 'map', 'analyze', 'read', 'report',
+                      'find', 'locate', 'search', 'survey', 'inventory', 'document', 'recon'],
+        reviewer:    ['review', 'security', 'audit', 'test', 'quality', 'check', 'verify',
+                      'validate', 'pr', 'pull', 'lint', 'coverage', 'performance', 'checklist'],
+        coordinator: ['decompose', 'plan', 'coordinate', 'parallel', 'orchestrate', 'manage',
+                      'delegate', 'assign', 'breakdown', 'workflow', 'group', 'subtask'],
+      }
+      // Skills that don't match any role-specific keyword are treated as universal
+      // (e.g. 'session-start', 'workflow-guide') and given to all roles.
+      const ALL_ROLE_KEYWORDS = Object.values(ROLE_SKILL_KEYWORDS).flat()
+      const isRoleSpecific = (s) => ALL_ROLE_KEYWORDS.some(kw => `${s.name} ${s.description || ''}`.toLowerCase().includes(kw))
+
+      const roleKeywords = effectiveRole ? (ROLE_SKILL_KEYWORDS[effectiveRole] || []) : []
+
+      // Also use the task type's suggestedSkills list for relevance
+      const taskTypeSkills = (() => {
+        try {
+          const taskType = ctx.task?.taskType || 'feature'
+          const cfg = TASK_TYPES?.[taskType]
+          return cfg?.suggestedSkills || []
+        } catch { return [] }
+      })()
+
+      const relevantSkills = enabledSkills.filter(s => {
+        // Always include explicitly overridden-true skills (task-level config)
+        if (taskSkillOverrides[s.name] === true) return true
+        // Always include task-type suggested skills
+        if (taskTypeSkills.includes(s.name)) return true
+        // Include universal skills (don't match any role's keywords — generic helpers)
+        if (!isRoleSpecific(s)) return true
+        // Include if skill name/description matches this role's keywords
+        const haystack = `${s.name} ${s.description || ''}`.toLowerCase()
+        return roleKeywords.some(kw => haystack.includes(kw))
+      })
+
+      const suggestedSkills = relevantSkills.length > 0
+        ? relevantSkills.map(s => ({
             name: s.name,
             description: s.description,
             path: `.cursor/skills/${s.name}.md`,
@@ -1943,7 +2233,12 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
         suggestedSkills,
         task:            ctx.task,
         project:         ctx.project,
-        usage: 'Use systemPrompt as your Claude system prompt. If allowedTools is set, restrict your MCP tool calls to that list. Read and follow each skill in suggestedSkills before starting work.',
+        usage: [
+          'Use systemPrompt as your Claude system prompt.',
+          'If allowedTools is set, restrict your MCP tool calls to that list.',
+          'Read ONLY the skills listed in suggestedSkills — they are filtered for your role and task type.',
+          'After the task is done (park_task or raise_pr), the skill files are automatically deleted from .cursor/skills/.',
+        ].join(' '),
       })
     }
   )
@@ -2078,9 +2373,14 @@ Returns reviewId — save it and pass it to merge_pr to prove semantic review ha
       if (!prNumber) return errorText('No PR linked to this task. Call raise_pr first.')
 
       // Enforce that analysisPoints are specific — reject obviously generic ones
-      const genericPhrases = ['looks good', 'lgtm', 'code is fine', 'no issues', 'all good', 'seems correct']
+      const genericPhrases = [
+        'looks good', 'lgtm', 'code is fine', 'no issues', 'all good', 'seems correct',
+        'looks great', 'looks fine', 'all correct', 'perfect', 'seems fine', 'this is fine',
+        'this is correct', 'no problems', 'nothing wrong', 'good job', 'well done',
+        'approved', 'ship it', 'looks right', 'seems right', 'everything is fine',
+      ]
       const tooGeneric = analysisPoints.filter(p =>
-        p.trim().length < 20 || genericPhrases.some(g => p.toLowerCase().includes(g))
+        p.trim().length < 25 || genericPhrases.some(g => p.toLowerCase().includes(g))
       )
       if (tooGeneric.length > 0) {
         return text({
@@ -2224,8 +2524,15 @@ The task moves to Done automatically via the GitHub webhook.`,
         { check: `CI checks (${checks?.total ?? 0} runs)`,
           pass: skipChecks ? null : (checks?.allPassed ?? null),
           note: skipChecks ? 'Skipped by request' : checks?.anyFailed ? 'Some checks failed' : checks?.allPassed ? 'All passing' : 'No checks found' },
-        { check: 'Has at least one approval', pass: pr.approvals > 0,
-          note: pr.approvals === 0 ? 'No approvals yet — consider running post_pr_review first' : `${pr.approvals} approval(s)` },
+        // Hard block: PR must have at least one GitHub approval OR a sessionReview from this session.
+        // A sessionReview alone (reviewer = author) is not enough — someone independent must approve.
+        // Exception: if there's a sessionReview AND existing approvals, both gates are satisfied.
+        { check: 'Has at least one GitHub approval', pass: pr.approvals > 0,
+          note: pr.approvals === 0
+            ? hasSessionReview
+              ? '⚠️ Self-review only — no independent GitHub approval. Ask a teammate to approve on GitHub before merging.'
+              : 'No approvals. Call review_pr → post_pr_review, then ask a reviewer to approve on GitHub.'
+            : `${pr.approvals} GitHub approval(s)` },
       ]
 
       const hardBlocks = safetyChecks.filter(c => c.pass === false && c.check !== `CI checks (${checks?.total ?? 0} runs)`)
@@ -2274,14 +2581,17 @@ The task moves to Done automatically via the GitHub webhook.`,
         return text({ merged: true, message: 'PR was already merged.' })
       }
 
+      // Move task to done immediately — don't rely solely on the GitHub webhook
+      try { await api.post(`/api/tasks/${taskId}/move`, { column: 'done', toIndex: 0 }) } catch { /* webhook fallback */ }
+
       return text({
         merged:      true,
         sha:         mergeRes.data?.sha,
         prNumber,
         taskKey:     task.key,
         mergeMethod,
-        message:     `✅ PR #${prNumber} merged via ${mergeMethod}. Task "${task.key}" will move to Done automatically.`,
-        nextStep:    `The GitHub webhook will update the board. If the task doesn't move to Done within a minute, call update_task with column="done" manually.`,
+        message:     `✅ PR #${prNumber} merged via ${mergeMethod}. Task "${task.key}" moved to Done.`,
+        nextStep:    `Run deleteCursorWorkspace cleanup if any agent files remain, then pick up your next task.`,
       })
     }
   )
@@ -2482,6 +2792,34 @@ Flow:
         api.patch(`/api/tasks/${taskId}`, { agentRole }).catch(() => {/* non-fatal */})
       }
 
+      // Re-write full cursor workspace (skills, session protocol, active-agent)
+      // resume_task is equivalent to unpark_task for workspace purposes.
+      let workspaceResult = null
+      try {
+        let projectAgentConfig = null
+        try {
+          const projRes = await api.get(`/api/projects/${task.project}`)
+          if (projRes?.success) projectAgentConfig = projRes.data.project?.agentConfig || null
+        } catch { /* non-fatal */ }
+
+        const taskForWorkspace = agentRole ? { ...task, agentRole } : task
+        workspaceResult = writeCursorWorkspace(taskForWorkspace, projectAgentConfig, repoPath || process.cwd())
+
+        // Log injected files to session timeline
+        const writtenFiles = workspaceResult?.written || []
+        for (const filePath of writtenFiles) {
+          const fileName = filePath.split('/').pop().replace(/\.(md|mdc)$/, '')
+          const isSkill  = filePath.includes('/.cursor/skills/')
+          const isRule   = filePath.includes('/.cursor/rules/')
+          const isAgent  = filePath.includes('/.cursor/agents/')
+          const type = isSkill ? 'skill' : isRule ? 'rule' : isAgent ? 'subagent' : 'info'
+          api.post(`/api/tasks/${taskId}/session/log`, {
+            type, name: fileName, role: agentRole || null,
+            summary: `📖 Injected at resume: ${filePath.replace(workspaceResult.repoRoot, '')}`,
+          }).catch(() => {})
+        }
+      } catch { /* non-fatal */ }
+
       // Last commit metadata
       const lastCommit = getLastCommitMeta(repoRoot)
 
@@ -2497,11 +2835,20 @@ Flow:
         cursorRules: cursorRulesFile
           ? { restored: true, path: cursorRulesFile, agentRole: agentRole || null }
           : { restored: false },
+        workspace: workspaceResult
+          ? { restored: true, filesCount: workspaceResult.written?.length || 0, files: workspaceResult.written || [] }
+          : { restored: false },
+        previouslyClaimed: task?.claimedFiles?.length ? task.claimedFiles : null,
         message: gitResult?.switched || gitResult?.alreadyOnBranch
-          ? `You are on branch "${branch}". Ready to resume coding${agentRole ? ` as ${agentRole}` : ''}.`
+          ? `You are on branch "${branch}". Cursor workspace restored${agentRole ? ` as ${agentRole}` : ''}. Read all skills before editing.`
           : `Branch switch failed — see git.manualSteps.`,
         nextStep: agentRole === 'builder'
-          ? `BUILDER role active. Call claim_files to lock your files before editing.`
+          ? [
+              `BUILDER role active.`,
+              `1. ⚠️ READ all injected skills (workspace.files) — mandatory before any edits`,
+              `2. Re-claim files: claim_files(taskId="${taskId}", files=${JSON.stringify(task?.claimedFiles || [])})`,
+              `3. Continue implementation from where you left off`,
+            ].join('\n')
           : agentRole === 'scout'
           ? `SCOUT role active. Read-only mode — map the codebase and save findings with update_task(scoutReport=...).`
           : agentRole === 'coordinator'
@@ -2511,8 +2858,8 @@ Flow:
           : task.column === 'in_review'
           ? `Task is in review. Check if PR feedback needs addressing — call fix_pr_feedback if needed.`
           : task.parkNote?.remaining
-            ? `Remaining: ${task.parkNote.remaining}`
-            : `Continue coding on "${branch}".`,
+            ? `Remaining: ${task.parkNote.remaining}. Read workspace.files skills first.`
+            : `Continue coding on "${branch}". Read workspace.files skills first.`,
       })
     }
   )
@@ -2580,21 +2927,36 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
       const subtasks   = dec.subtasks || []
       const execOrder  = dec.executionOrder || []
 
-      // Determine which group to run next: first group that has at least one
-      // subtask not yet reflected in the board subtasks as done.
+      // Dual-signal completion check — mirrors wait_for_group logic.
+      // A subtask is "done" if EITHER the parent checklist ticks it OR its child task
+      // column is done/in_review. This prevents re-emitting builder prompts for subtasks
+      // that are already finished but whose builder skipped update_task on the parent.
       const boardSubtasks = task.subtasks || []
-      // Board subtask titles may carry a role prefix like "[BUILDER] Auth hardening..."
-      // Match on bare title OR prefixed title
-      const isDone = (title) => boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
+      const checklistDone = (title) => boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
+      const childColumnDoneCache = {}
+      const isSubtaskDone = async (title) => {
+        if (checklistDone(title)) return true
+        const entry = subtasks.find(s => s.title === title)
+        if (!entry?.childTaskId) return false
+        if (childColumnDoneCache[entry.childTaskId] !== undefined) return childColumnDoneCache[entry.childTaskId]
+        try {
+          const r = await api.get(`/api/tasks/${entry.childTaskId}`)
+          const col = r?.data?.task?.column
+          const done = col === 'done' || col === 'in_review'
+          childColumnDoneCache[entry.childTaskId] = done
+          return done
+        } catch { return false }
+      }
 
       let nextGroup = null
       let nextGroupIndex = -1
       for (let i = 0; i < execOrder.length; i++) {
         const group = execOrder[i]
-        const allDone = group.every(t => isDone(t))
+        const allDone = (await Promise.all(group.map(t => isSubtaskDone(t)))).every(Boolean)
         if (!allDone) {
           // Also check all prior groups are fully done (respects dependsOn)
-          const priorAllDone = execOrder.slice(0, i).every(g => g.every(t => isDone(t)))
+          const priorResults = await Promise.all(execOrder.slice(0, i).map(g => Promise.all(g.map(t => isSubtaskDone(t)))))
+          const priorAllDone = priorResults.every(g => g.every(Boolean))
           if (priorAllDone) {
             nextGroup = group
             nextGroupIndex = i + 1
@@ -2610,8 +2972,9 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
         })
       }
 
-      // Only kick off subtasks that aren't done yet
-      const pendingInGroup = nextGroup.filter(t => !isDone(t))
+      // Only kick off subtasks that aren't done yet (use cached dual-signal results)
+      const pendingInGroup = (await Promise.all(nextGroup.map(async t => ({ t, done: await isSubtaskDone(t) }))))
+        .filter(r => !r.done).map(r => r.t)
       const parallelCount  = pendingInGroup.length
       const isParallel     = parallelCount > 1
 
@@ -2629,35 +2992,42 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
       const kickoffs = pendingInGroup.map((subtaskTitle, i) => {
         const st = subtasks.find(s => s.title === subtaskTitle) || { title: subtaskTitle, role: 'builder', files: [], description: '' }
         const filesArg = (st.files || []).map(f => `"${f}"`).join(', ')
-        const fileList = (st.files || []).map(f => `  - \`${f}\``).join('\n')
-
-        // Prompt is a short, direct imperative Cursor immediately executes.
-        // Key: start with "Use the InternalTool MCP" so Cursor knows to call tools.
-        // Avoid pseudocode like fn(arg=val) — use plain English with quoted values.
         const fileListPlain = (st.files || []).join(', ')
+
+        // Use the child task ID if it was embedded at decompose time.
+        // Builders must work on their own child task, not the parent task.
+        // The parent task ID is only used to update the parent checklist when done.
+        const childTaskId  = st.childTaskId  || taskId   // fallback to parent if missing (old decompositions)
+        const childTaskKey = st.childTaskKey || task.key
+        const usingChildTask = !!(st.childTaskId)
+
         const prompt = [
-          `Use the InternalTool MCP tools to implement subtask "${st.title}" for task ${task.key}.`,
+          `Use the InternalTool MCP tools to implement subtask "${st.title}".`,
+          `Your task: ${childTaskKey} (child of ${task.key})`,
+          usingChildTask ? `Child task ID: "${childTaskId}" — use this for ALL MCP calls below.` : `⚠️ No child task ID found — using parent task ID "${taskId}" as fallback.`,
           ``,
           `Do these steps immediately in order — do not ask for confirmation, do not skip any step:`,
           ``,
-          `1. Call log_session_event with taskId "${taskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} started: ${st.title}"`,
-          `2. Call kickoff_task with taskId "${taskId}", agentRole "builder", confirmed true`,
-          `3. Call claim_files with taskId "${taskId}" and files [${filesArg}]`,
-          `4. Call get_agent_context with taskId "${taskId}" to read the full task plan and suggested skills`,
+          `1. Call log_session_event with taskId "${childTaskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} started: ${st.title}"`,
+          `2. Call kickoff_task with taskId "${childTaskId}", agentRole "builder", confirmed true`,
+          `   (This writes your cursor workspace. READ every file in .cursor/skills/ before editing anything.)`,
+          `3. Call claim_files with taskId "${childTaskId}" and files [${filesArg}]`,
+          `4. Call get_agent_context with taskId "${childTaskId}" and role "builder" — read the full plan and skills`,
           `5. Implement the subtask: ${st.description || st.title}`,
           `   - You may ONLY modify these files: ${fileListPlain}`,
-          `   - Do NOT touch any other file`,
-          `   - Follow any skills listed in get_agent_context suggestedSkills`,
-          `6. Run npm test — all tests must pass before continuing`,
-          `7. Call commit_helper with taskId "${taskId}"`,
-          `8. Call update_task with taskId "${taskId}" and mark the subtask "${st.title}" as done`,
-          `9. Call resume_task with taskId "${taskId}", agentRole "reviewer", confirmed true — transition to reviewer role`,
-          `10. Call log_session_event with taskId "${taskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} finished: ${st.title}"`,
+          `   - Do NOT touch any other file — other builders own those`,
+          `   - Follow skills listed in get_agent_context`,
+          `6. Run the project test suite — all tests must pass before continuing`,
+          `7. Call commit_helper with taskId "${childTaskId}"`,
+          `8. Call raise_pr with taskId "${childTaskId}" and projectId "${task.project?._id || task.project}"`,
+          `9. Call update_task with taskId "${taskId}" (parent) and mark the subtask "${st.title}" as done in the subtasks checklist`,
+          `10. Call log_session_event with taskId "${childTaskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} finished: ${st.title}"`,
           ``,
-          `You are builder ${i + 1} of ${parallelCount} running in parallel. Another builder is working on different files at the same time.`,
+          `You are builder ${i + 1} of ${parallelCount} running in parallel. Other builders are working on different files simultaneously — do NOT touch their files.`,
+          `If you finish early, call park_task on your child task and notify the coordinator.`,
         ].join('\n')
 
-        return { subtask: st.title, role: st.role || 'builder', files: st.files || [], prompt }
+        return { subtask: st.title, role: st.role || 'builder', files: st.files || [], childTaskId, childTaskKey, prompt }
       })
 
       // Write each builder prompt as a Cursor Background Agent file in .cursor/agents/
@@ -2674,14 +3044,14 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
 
         const agentFileContent = [
           `---`,
-          `description: Builder ${i + 1} of ${parallelCount} — ${k.subtask} (${task.key})`,
+          `description: Builder ${i + 1} of ${parallelCount} — ${k.subtask} (${k.childTaskKey || task.key})`,
           `---`,
           ``,
           k.prompt,
         ].join('\n')
 
         writeFileSync(filePath, agentFileContent, 'utf8')
-        writtenFiles.push({ index: i + 1, file: `.cursor/agents/${fileName}`, subtask: k.subtask })
+        writtenFiles.push({ index: i + 1, file: `.cursor/agents/${fileName}`, subtask: k.subtask, childTaskId: k.childTaskId, childTaskKey: k.childTaskKey })
       })
 
       // Build the human-facing instruction block
@@ -2693,13 +3063,11 @@ The agent files are fully self-contained: each builder knows exactly what MCP to
         `  2. You'll see ${parallelCount} new builder agent(s) listed`,
         `  3. Click "Start" for each one — they run in parallel automatically`,
         ``,
-        ...writtenFiles.map(f => `  • Builder ${f.index}: "${f.subtask}"  →  ${f.file}`),
+        ...writtenFiles.map(f => `  • Builder ${f.index}: "${f.subtask}" [${f.childTaskKey || 'parent'}]  →  ${f.file}`),
         ``,
-        `Each builder calls kickoff_task → claim_files → implements → runs tests → commits.`,
+        `Each builder kicks off their own child task → claims files → implements → tests → commits → raises PR.`,
         `They work on different files simultaneously — no need to wait for one before starting the other.`,
-        ``,
-        `After all builders finish, come back here and call get_parallel_kickoffs again`,
-        `to get the next group's prompts.`,
+        `When all builders in this group are done, call get_parallel_kickoffs again for the next group.`,
       ].join('\n')
 
       return text({
@@ -2738,6 +3106,23 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
       const deadline = Date.now() + timeoutMs
       let attempts   = 0
 
+      // Helper: check if a subtask title is done via parent checklist
+      const isCheckedDone = (boardSubtasks, title) =>
+        boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
+
+      // Helper: check if a child task is done via its board column.
+      // A child task is considered done when it reaches 'done' or 'in_review'
+      // (builder finished + raised PR). This is the reliable signal — builders
+      // may skip calling update_task on the parent but they always raise_pr.
+      const isChildTaskDone = async (childTaskId) => {
+        if (!childTaskId) return false
+        try {
+          const res = await api.get(`/api/tasks/${childTaskId}`)
+          const col = res?.data?.task?.column
+          return col === 'done' || col === 'in_review'
+        } catch { return false }
+      }
+
       while (Date.now() < deadline) {
         attempts++
         const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
@@ -2750,27 +3135,43 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
           return errorText('Decomposition JSON is malformed.')
         }
 
-        const execOrder  = dec.executionOrder || []
+        const execOrder   = dec.executionOrder || []
+        const decSubtasks = dec.subtasks || []
         const targetGroup = execOrder[groupIndex - 1]
         if (!targetGroup) return errorText(`Group ${groupIndex} does not exist. Decomposition has ${execOrder.length} group(s).`)
 
         const boardSubtasks = task.subtasks || []
-        const isDone = (title) => boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
 
-        const doneTitles    = targetGroup.filter(t => isDone(t))
-        const pendingTitles = targetGroup.filter(t => !isDone(t))
+        // Dual-signal completion: parent checklist tick OR child task column (done/in_review).
+        // This prevents the coordinator from stalling when a builder skips update_task on the parent.
+        const statusPerTitle = await Promise.all(
+          targetGroup.map(async (title) => {
+            const checklist = isCheckedDone(boardSubtasks, title)
+            if (checklist) return { title, done: true, via: 'checklist' }
+            // Look up child task ID from the embedded decomposition
+            const decEntry = decSubtasks.find(s => s.title === title)
+            const childDone = decEntry?.childTaskId
+              ? await isChildTaskDone(decEntry.childTaskId)
+              : false
+            return { title, done: childDone, via: childDone ? 'child_task_column' : 'pending', childTaskId: decEntry?.childTaskId || null }
+          })
+        )
+
+        const doneTitles    = statusPerTitle.filter(s => s.done)
+        const pendingTitles = statusPerTitle.filter(s => !s.done)
 
         if (pendingTitles.length === 0) {
           return text({
-            done:     true,
-            group:    groupIndex,
-            subtasks: targetGroup,
+            done:       true,
+            group:      groupIndex,
+            subtasks:   targetGroup,
             done_count: doneTitles.length,
+            completion: doneTitles.map(s => ({ title: s.title, via: s.via })),
             attempts,
             message: `✅ All ${targetGroup.length} subtask(s) in Group ${groupIndex} are done after ${attempts} poll(s).`,
             nextStep: groupIndex < execOrder.length
               ? `Call get_parallel_kickoffs with taskId="${taskId}" to get Group ${groupIndex + 1}'s builder prompts.`
-              : 'All groups complete. Run final tests then call raise_pr.',
+              : 'All groups complete. Run final tests then call raise_pr on the parent task.',
           })
         }
 
@@ -2793,10 +3194,17 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
       const finalTask = finalRes?.data?.task
       let finalDec
       try { finalDec = JSON.parse(finalTask?.decomposition || '{}') } catch { finalDec = {} }
-      const finalGroup   = (finalDec.executionOrder || [])[groupIndex - 1] || []
-      const finalBoard   = finalTask?.subtasks || []
-      const finalIsDone  = (t) => finalBoard.some(s => s.done && (s.title === t || s.title.endsWith(t)))
-      const stillPending = finalGroup.filter(t => !finalIsDone(t))
+      const finalGroup     = (finalDec.executionOrder || [])[groupIndex - 1] || []
+      const finalDecSubs   = finalDec.subtasks || []
+      const finalBoard     = finalTask?.subtasks || []
+      const stillPending   = await Promise.all(
+        finalGroup.map(async (title) => {
+          if (isCheckedDone(finalBoard, title)) return null
+          const entry = finalDecSubs.find(s => s.title === title)
+          if (entry?.childTaskId && await isChildTaskDone(entry.childTaskId)) return null
+          return title
+        })
+      ).then(r => r.filter(Boolean))
 
       return text({
         timedOut:   true,
@@ -2804,7 +3212,7 @@ Polls every 10 s, times out after 30 min by default. Returns immediately if alre
         pending:    stillPending,
         attempts,
         message:    `⏱ Timed out after ${attempts} poll(s). ${stillPending.length} subtask(s) still pending: ${stillPending.join(', ')}`,
-        hint:       'Check the Background Agents panel — a builder may have crashed. Call wait_for_group again to resume waiting, or proceed manually.',
+        hint:       'Check the Background Agents panel — a builder may have crashed or skipped raise_pr. Call wait_for_group again to resume, or proceed manually if the work is done.',
       })
     }
   )
@@ -3626,6 +4034,18 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         const hasParallelLang   = /parallel|simultaneously|independent(ly)?|at the same time/i.test(readme)
         const hasSequentialLang = /step\s*\d|first[\s,].*then|depends\s+on|before.*after/i.test(readme)
 
+        // Count how many distinct codebase layers are touched: routes, models, components, services, tests, migrations, seeds, utils, middleware, hooks
+        const LAYER_PATTERNS = ['route', 'model', 'component', 'service', 'test', 'migration', 'seed', 'util', 'middleware', 'hook', 'schema', 'store', 'context', 'controller', 'resolver']
+        const layersHit = LAYER_PATTERNS.filter(l => new RegExp(l, 'i').test(readme)).length
+
+        // Count explicit numbered steps / subtasks in the plan (indicates decomposability)
+        const numberedSteps = (readme.match(/^\s*\d+\.\s/gm) || []).length
+
+        // Full-stack scope: touches both frontend and backend layers
+        const hasFrontend = /component|hook|store|context|jsx|tsx|vue|react|svelte|ui|page|view/i.test(readme)
+        const hasBackend  = /route|controller|model|schema|service|middleware|api|endpoint|database|migration/i.test(readme)
+        const isFullStack = hasFrontend && hasBackend
+
         if (readmeLen > 800)       { complexityScore += 2; complexitySignals.push(`long plan (${readmeLen} chars)`) }
         else if (readmeLen > 300)  { complexityScore += 1; complexitySignals.push(`medium plan (${readmeLen} chars)`) }
         if (sections > 3)          { complexityScore += 2; complexitySignals.push(`${sections} README sections`) }
@@ -3634,13 +4054,23 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         else if (fileMentions > 2) { complexityScore += 1; complexitySignals.push(`${fileMentions} files mentioned`) }
         if (hasParallelLang)       { complexityScore += 1; complexitySignals.push('parallel workstreams mentioned') }
         if (hasSequentialLang)     { complexityScore += 1; complexitySignals.push('sequential steps mentioned') }
+        if (layersHit >= 4)        { complexityScore += 2; complexitySignals.push(`${layersHit} codebase layers touched`) }
+        else if (layersHit >= 2)   { complexityScore += 1; complexitySignals.push(`${layersHit} codebase layers touched`) }
+        if (numberedSteps >= 5)    { complexityScore += 2; complexitySignals.push(`${numberedSteps} explicit steps in plan`) }
+        else if (numberedSteps >= 3) { complexityScore += 1; complexitySignals.push(`${numberedSteps} steps in plan`) }
+        if (isFullStack)           { complexityScore += 1; complexitySignals.push('full-stack scope (frontend + backend)') }
       }
 
+      // Score from task-level signals (subtask count from board)
+      const existingSubtaskCount = (task.subtasks || []).length
+      if (existingSubtaskCount >= 5)    { complexityScore += 2; complexitySignals.push(`${existingSubtaskCount} subtasks already defined`) }
+      else if (existingSubtaskCount >= 3) { complexityScore += 1; complexitySignals.push(`${existingSubtaskCount} subtasks defined`) }
+
       const titleLower = task.title.toLowerCase()
-      const complexTitleWords = ['implement', 'build', 'add', 'create', 'integrate', 'refactor', 'migrate', 'redesign']
-      const simpleTitleWords  = ['fix', 'patch', 'typo', 'bump', 'revert']
-      if (complexTitleWords.some(w => titleLower.includes(w))) complexityScore += 1
-      if (simpleTitleWords.some(w =>  titleLower.includes(w))) complexityScore -= 1
+      const complexTitleWords = ['implement', 'build', 'add', 'create', 'integrate', 'refactor', 'migrate', 'redesign', 'replace', 'overhaul', 'rearchitect']
+      const simpleTitleWords  = ['fix', 'patch', 'typo', 'bump', 'revert', 'update', 'rename', 'remove']
+      if (complexTitleWords.some(w => titleLower.includes(w))) { complexityScore += 1; complexitySignals.push('complex verb in title') }
+      if (simpleTitleWords.some(w =>  titleLower.includes(w))) { complexityScore -= 1 }
       complexityScore = Math.max(0, complexityScore)
 
       // ── Determine recommended flow ────────────────────────────────────────────
@@ -3669,6 +4099,64 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       const subtasksDone  = subtasks.filter(s => s.done).length
       const subtasksTotal = subtasks.length
 
+      // ── Gather local git state (used in both preview and confirmed path) ────────
+      let localGitState = null
+      {
+        const pCwd  = repoPath || process.cwd()
+        const pRoot = findRepoRoot(pCwd)
+        if (pRoot) {
+          try {
+            const porcelain    = runGit('status --porcelain=v1', pRoot)
+            const { localState, modified, staged, unstaged, untracked } = parseGitStatus(porcelain)
+            const currentBranch = runGit('branch --show-current', pRoot).trim()
+
+            // Detect default branch (main / master)
+            let defaultBranch = 'main'
+            try {
+              defaultBranch = runGit('symbolic-ref refs/remotes/origin/HEAD', pRoot).trim().replace('refs/remotes/origin/', '')
+            } catch { /* no remote HEAD — stay with 'main' */ }
+
+            // How far behind is the current branch from origin/<default>?
+            let mainBehindBy = 0
+            try {
+              runGit('fetch origin --quiet', pRoot)
+              mainBehindBy = parseInt(runGit(`rev-list HEAD..origin/${defaultBranch} --count`, pRoot).trim(), 10) || 0
+            } catch { /* no remote or network — non-fatal */ }
+
+            localGitState = {
+              repoRoot:     pRoot,
+              currentBranch,
+              defaultBranch,
+              localState,   // 'clean' | 'modified' | 'untracked'
+              modifiedFiles: modified,
+              untrackedFiles: untracked,
+              mainBehindBy,
+            }
+          } catch { /* git not available or not a git repo — non-fatal */ }
+        }
+      }
+
+      // ── Fetch team landscape for the preview so agent sees conflicts before committing ──
+      let previewTeamContext = null
+      try {
+        const previewTreeRes = await api.get(`/api/projects/${task.project}/github/git-tree`).catch(() => null)
+        if (previewTreeRes?.success) {
+          const branches = previewTreeRes.data?.branches || []
+          const otherActive = branches.filter(b => b.taskId !== String(task._id) && !b.branchError)
+          if (otherActive.length > 0) {
+            previewTeamContext = {
+              activeBranches: otherActive.map(b => ({
+                taskKey:   b.taskKey,
+                assignees: (b.assignees || []).map(a => a.name).join(', ') || 'unassigned',
+                files:     b.claimedFiles || [],
+                behindBy:  b.compare?.behindBy ?? null,
+              })),
+              warning: `⚠️  ${otherActive.length} other branch(es) active in this project. Check for file overlaps before claiming files.`,
+            }
+          }
+        }
+      } catch { /* non-fatal */ }
+
       // ── Preview: show the full plan before touching anything ──
       const pendingApv = (task.approvals || []).find(a => a.state === 'pending') || null
       const hasApprovedApv = (task.approvals || []).some(a => a.state === 'approved')
@@ -3887,10 +4375,25 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
             claimedFiles:     task.claimedFiles || [],
             agentRole:        task.agentRole || null,
           },
+          localGitState: localGitState ? {
+            currentBranch:  localGitState.currentBranch,
+            status:         localGitState.localState,
+            modifiedFiles:  localGitState.modifiedFiles,
+            untrackedFiles: localGitState.untrackedFiles,
+            mainBehindBy:   localGitState.mainBehindBy,
+            ...(localGitState.localState === 'modified' && {
+              warning: `⚠️  You have ${localGitState.modifiedFiles.length} uncommitted change(s) on "${localGitState.currentBranch}". Commit or stash before starting a new task to avoid cross-task pollution.`,
+              suggestedFix: `git stash push -m "wip: before starting ${task.key}"`,
+            }),
+            ...(localGitState.mainBehindBy > 0 && {
+              mainWarning: `⚠️  Your workspace is ${localGitState.mainBehindBy} commit(s) behind origin/${localGitState.defaultBranch}. Run: git pull origin ${localGitState.defaultBranch} before creating a branch.`,
+            }),
+          } : null,
+          teamLandscape: previewTeamContext,
           requiresConfirmation: true,
           message: approvalBlocks
             ? `Read the plan above, then follow workflowRoadmap — approval is required before you can branch and start coding.`
-            : `Read the implementation plan above carefully, then call kickoff_task again with confirmed=true.`,
+            : `Read the implementation plan above carefully, resolve any localGitState warnings, then call kickoff_task again with confirmed=true.`,
         })
       }
 
@@ -3948,28 +4451,39 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       }
 
       // ── #1 Preflight: check dirty tree before writing cursor rules / moving task ──
-      {
-        const pCwd  = repoPath || process.cwd()
-        const pRoot = findRepoRoot(pCwd)
-        if (pRoot) {
-          try {
-            const porcelain = runGit('status --porcelain=v1', pRoot)
-            const { localState, modified } = parseGitStatus(porcelain)
-            const currentBranchNow = runGit('branch --show-current', pRoot).trim()
-            if (localState === 'modified' && task.github?.headBranch && currentBranchNow !== task.github.headBranch) {
-              return text({
-                blocked:      true,
-                reason:       `You are on "${currentBranchNow}" with ${modified.length} modified file(s), but this task's branch is "${task.github.headBranch}".`,
-                modifiedFiles: modified,
-                choices: {
-                  stash:   `git stash push -m "wip: before kickoff ${task.key} on ${currentBranchNow}"`,
-                  autoSwitch: `Switch to ${task.github.headBranch}: git stash && git checkout ${task.github.headBranch} && git stash pop`,
-                  cancel:  'Review your changes first, then retry kickoff_task',
-                },
-                message: 'Resolve the working tree before kicking off this task to avoid cross-task pollution.',
-              })
-            }
-          } catch { /* non-fatal */ }
+      // Use the git state we already gathered above; re-check if not available.
+      if (localGitState?.localState === 'modified') {
+        const { currentBranch, modifiedFiles } = localGitState
+        const taskBranch = task.github?.headBranch
+
+        if (taskBranch && currentBranch !== taskBranch) {
+          // On the wrong branch — stash and switch, or cancel
+          return text({
+            blocked:       true,
+            reason:        `You are on "${currentBranch}" with ${modifiedFiles.length} uncommitted change(s), but this task's branch is "${taskBranch}".`,
+            modifiedFiles,
+            choices: {
+              stash:      `git stash push -m "wip: before kickoff ${task.key} on ${currentBranch}"`,
+              autoSwitch: `git stash && git checkout ${taskBranch} && git stash pop`,
+              cancel:     'Review your changes first, then retry kickoff_task',
+            },
+            message: '⛔ Resolve the working tree before kicking off this task to avoid cross-task pollution.',
+          })
+        }
+
+        if (!taskBranch) {
+          // First-time kickoff — uncommitted changes risk bleeding into the new branch
+          return text({
+            blocked:       true,
+            reason:        `You have ${modifiedFiles.length} uncommitted change(s) on "${currentBranch}". Starting a new task from a dirty tree would carry these changes into the new branch.`,
+            modifiedFiles,
+            choices: {
+              stash:  `git stash push -m "wip: before starting ${task.key}"`,
+              commit: 'git add -p && git commit -m "wip: save changes before new task"',
+              cancel: 'Review your changes, then retry kickoff_task',
+            },
+            message: '⛔ Commit or stash your changes before creating a new task branch.',
+          })
         }
       }
 
@@ -4145,6 +4659,26 @@ After \`request_human_input\`: STOP, show the question in chat, wait for reply,
       }
       api.patch(`/api/tasks/${taskId}`, workspacePatch).catch(() => {/* non-fatal */})
 
+      // Auto-log every skill / rule / agent written to the session timeline
+      // so the Session tab always shows what got injected at kickoff.
+      if (workspaceResult?.written?.length) {
+        const repoRoot = workspaceResult.repoRoot || ''
+        for (const filePath of workspaceResult.written) {
+          const rel  = filePath.replace(repoRoot, '').replace(/^\//, '')
+          const name = rel.replace(/^\.cursor\/(skills|rules|agents|commands)\//, '').replace(/\.(md|mdc)$/, '')
+          const type = rel.includes('/skills/')   ? 'skill'
+                     : rel.includes('/rules/')    ? 'rule'
+                     : rel.includes('/agents/')   ? 'subagent'
+                     : 'info'
+          api.post(`/api/tasks/${taskId}/session/log`, {
+            type,
+            name,
+            role:    agentRole || null,
+            summary: `${type === 'skill' ? '📖' : type === 'rule' ? '📏' : type === 'subagent' ? '🤖' : 'ℹ️'} Injected at kickoff: ${rel}`,
+          }).catch(() => {/* non-fatal */})
+        }
+      }
+
       // Write .internaltool-active-task so the Claude Code hook knows a task is active
       try {
         writeFileSync(
@@ -4207,21 +4741,85 @@ After \`request_human_input\`: STOP, show the question in chat, wait for reply,
           scoutFirst:        taskTypeCfg.scoutFirst,
           typeRulesInjected: !!typeExtraRules,
         } : null,
-        nextStep: agentRole === 'scout'
-          ? `SCOUT mode. Read the codebase, then save findings with update_task(scoutReport=...). Do NOT modify files.`
-          : agentRole === 'coordinator'
-          ? `COORDINATOR mode. Read the README, then call decompose_task to split work into parallel/sequential subtasks with file ownership.`
-          : agentRole === 'builder'
-          ? `BUILDER mode. Call claim_files first, then start coding on "${alreadyHasBranch ? task.github.headBranch : suggestedBranch}".`
-          : agentRole === 'reviewer'
-          ? `REVIEWER mode. Call review_pr to get the diff, then post_pr_review with your analysis.`
-          : recommendedFlow === 'coordinator' && shouldAutoRoute
-          ? `⚡ COMPLEX TASK (score ${complexityScore}): Call kickoff_task with agentRole "coordinator" confirmed true → decompose_task → get_parallel_kickoffs → start builders. DO NOT code directly.`
-          : recommendedFlow === 'single_builder' && shouldAutoRoute
-          ? `🔧 MEDIUM TASK (score ${complexityScore}): Call kickoff_task with agentRole "builder" confirmed true → claim_files → implement → commit → raise_pr.`
-          : alreadyHasBranch
-          ? `SIMPLE TASK (score ${complexityScore}). Branch "${task.github.headBranch}" exists — call claim_files and start coding.`
-          : `SIMPLE TASK (score ${complexityScore}). Call create_branch to create "${suggestedBranch}", then claim_files and code.`,
+        mandatoryWorkflow: (() => {
+          const flow = recommendedFlow  // 'direct' | 'single_builder' | 'coordinator'
+          const role = agentRole || 'builder'
+
+          // ── Coordinator flow ──────────────────────────────────────────────────
+          if (role === 'coordinator') {
+            return {
+              flow: 'coordinator',
+              WARNING: '⛔ COORDINATOR MODE — DO NOT WRITE ANY CODE. Your only job is to plan and delegate.',
+              mandatorySteps: [
+                '1. READ all files in .cursor/skills/ — log each with log_session_event(type="skill", name=<filename>)',
+                '2. Call recall(taskId) to restore memory from previous sessions',
+                '3. Call get_agent_context(taskId, role="coordinator") for the full context',
+                `4. If no scout report exists: call scout_task(taskId="${taskId}", confirmed=false) to get the analysis brief, then scout_task(confirmed=true, report="<findings>") to save it — do NOT switch agentRole to scout`,
+                '5. Call decompose_task(confirmed=false) — preview the subtask breakdown with file ownership',
+                '6. Fix any file overlap conflicts, then call decompose_task(confirmed=true)',
+                '7. Call get_parallel_kickoffs — it writes builder agent files automatically',
+                '8. Tell the user: open Background Agents panel (⌘⇧J) and start each builder',
+                '9. DO NOT start building. DO NOT claim files. DO NOT edit code.',
+              ],
+              blockedUntil: 'decompose_task confirmed=true is called and childTasks are created',
+            }
+          }
+
+          // ── Scout flow ────────────────────────────────────────────────────────
+          if (role === 'scout') {
+            return {
+              flow: 'scout',
+              WARNING: '⛔ SCOUT MODE — READ ONLY. DO NOT write or modify any source file.',
+              mandatorySteps: [
+                '1. READ all files in .cursor/skills/ — log each with log_session_event(type="skill", name=<filename>)',
+                '2. Call recall(taskId) to restore memory from previous sessions',
+                '3. Call scout_task(confirmed=false) to get your analysis brief',
+                '4. Read every relevant source file systematically (routes, models, utils, tests)',
+                '5. Call scout_task(confirmed=true, report="<your findings>") to save the report',
+                '6. DO NOT modify any file. DO NOT create branches. DO NOT commit.',
+              ],
+              blockedUntil: 'scout_task confirmed=true with a non-empty report',
+            }
+          }
+
+          // ── Reviewer flow ─────────────────────────────────────────────────────
+          if (role === 'reviewer') {
+            return {
+              flow: 'reviewer',
+              mandatorySteps: [
+                '1. READ all files in .cursor/skills/ — log each with log_session_event(type="skill", name=<filename>)',
+                '2. Call review_pr — read the FULL diff before forming any opinion',
+                '3. Check every changed file line by line against the implementation plan',
+                '4. Call post_pr_review with verdict, analysisPoints (min 2), and specific file+line comments',
+              ],
+              blockedUntil: 'post_pr_review called with verdict',
+            }
+          }
+
+          // ── Builder flow (direct / single_builder / decompose child) ──────────
+          const inDecomposeFlow = !!(task.decomposition?.trim())
+          return {
+            flow: inDecomposeFlow ? 'decompose_builder' : flow,
+            SKILLS_GATE: '⛔ DO NOT EDIT ANY FILE until all steps 1–3 are complete.',
+            mandatorySteps: [
+              '1. READ all files in .cursor/skills/ — log each: log_session_event(taskId, type="skill", name=<skill-name>, role="builder")',
+              '2. Call recall(taskId) to restore memory — check for prior session findings',
+              '3. Call get_agent_context(taskId, role="builder") — read implementation plan + claimed files',
+              alreadyHasBranch
+                ? `4. You are on branch "${task.github.headBranch}" — run: git pull origin ${task.github.headBranch}`
+                : `4. Call create_branch — creates "${suggestedBranch}" and moves task to in_progress`,
+              '5. Call claim_files with your exact file list — REQUIRED before editing',
+              '6. Implement the feature following the plan. Run tests after each logical unit.',
+              '7. Call commit_helper to stage and commit with a conventional message',
+              '8. Call raise_pr when all subtasks are done and tests pass',
+            ],
+            blockedUntil: 'Skills read (step 1), memory recalled (step 2), files claimed (step 5)',
+            inDecomposeFlow,
+            decomposeNote: inDecomposeFlow
+              ? '⚡ This is a PARALLEL BUILD. Only edit your claimed files. Do NOT touch files owned by other subtasks.'
+              : null,
+          }
+        })(),
       })
     }
   )
@@ -4399,18 +4997,40 @@ How to determine status:
 
   server.tool(
     'submit_task_for_approval',
-    'Create and submit a new approval request on a task. Each request has its own title, plan/readme, and reviewer. Only one request can be pending at a time.',
+    `Create and immediately submit an approval request so a human reviewer can approve the plan before any branch or code is created.
+
+This is a single atomic operation — it creates the approval draft and submits it in one step.
+Only one approval can be pending at a time. Returns blocked=true if another is already pending.
+
+IMPORTANT — what to write in "summary":
+- Write a SHORT, new approval request (3–8 sentences). Do NOT copy the task readmeMarkdown verbatim.
+- The reviewer already has access to the full plan. Your job is to write a concise summary: what will change, why, and what the key risks are.
+- Example: "This adds Redis caching to the product list endpoint. It will reduce DB load by ~60% during peak hours. Key risk: cache invalidation on product updates — handled by clearing the cache key on every product.save()."`,
     {
       taskId:     z.string().describe("Task's MongoDB ObjectId"),
-      title:      z.string().describe('Short title for this approval request, e.g. "Experiment: Add caching layer"'),
-      readme:     z.string().describe('The plan/markdown describing what you want to do and why (min 80 chars)'),
-      reviewerId: z.string().describe('User ID of the reviewer'),
+      title:      z.string().describe('Short title for this approval request, e.g. "Plan: Add Redis caching to product list"'),
+      summary:    z.string().describe('A 3–8 sentence approval summary (NOT the full README). Describe: what changes, why, and key risks. The reviewer will read the full plan separately.'),
+      reviewerId: z.string().describe('User ID of the reviewer (admin or project lead)'),
     },
-    async ({ taskId, title, readme, reviewerId }) => {
-      // Gate: block if latest test run is failing
+    async ({ taskId, title, summary, reviewerId }) => {
+      // Gate: block if another approval is already pending
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       if (taskRes?.success) {
-        const latestRun = taskRes.data?.task?.testRuns?.[0]
+        const task = taskRes.data?.task
+        const alreadyPending = (task?.approvals || []).find(a => a.state === 'pending')
+        if (alreadyPending) {
+          return text({
+            blocked: true,
+            reason:  'An approval is already pending review.',
+            pendingApproval: {
+              title: alreadyPending.title,
+              requestedAt: alreadyPending.requestedAt,
+            },
+            message: 'Wait for the reviewer to decide on the existing request, or ask them to reject it first.',
+          })
+        }
+        // Gate: block if latest test run is failing
+        const latestRun = task?.testRuns?.[0]
         if (latestRun && latestRun.status === 'failing') {
           return text({
             blocked: true,
@@ -4426,21 +5046,86 @@ How to determine status:
           })
         }
       }
-      return call(() => api.post(`/api/tasks/${taskId}/approvals`, { title, readme, reviewerId }))
+
+      // Step 1: create draft
+      const createRes = await api.post(`/api/tasks/${taskId}/approvals`, { title, readme: summary })
+      if (!createRes?.success) return errorText(createRes?.message || 'Could not create approval draft')
+      const freshTask = createRes.data?.task
+      const newApproval = (freshTask?.approvals || []).find(a => a.state === 'none' && a.title === title)
+      if (!newApproval?._id) return errorText('Approval created but could not find its ID — check the task approvals tab')
+
+      // Step 2: immediately submit for review
+      const submitRes = await api.post(`/api/tasks/${taskId}/approvals/${newApproval._id}/submit`, { reviewerId })
+      if (!submitRes?.success) {
+        return text({
+          draftCreated: true,
+          approvalId:   newApproval._id,
+          submitFailed: true,
+          reason:       submitRes?.message || 'Draft created but submit step failed',
+          message:      'The approval draft was created but could not be submitted automatically. Open the task → Approval tab → click "Submit for review" manually.',
+        })
+      }
+      return text({
+        submitted:  true,
+        approvalId: newApproval._id,
+        title,
+        state:      'pending',
+        message:    `Approval request submitted. The reviewer will be notified. Do NOT start coding or create a branch until they approve.`,
+        nextStep:   `Wait for decide_task_approval to return decision="approve". Then call create_branch.`,
+      })
     }
   )
 
   server.tool(
     'decide_task_approval',
-    'Approve or reject a specific approval request by approvalId. Only the designated reviewer can call this.',
+    `Approve or reject a specific approval request by approvalId. Only the designated reviewer can call this.
+
+BEFORE calling with a decision, review the plan:
+- Read the plan summary returned by this tool (confirmed=false)
+- Read the task comments for any context from the submitter
+- Check the implementation plan for completeness, correctness, and feasibility
+- Approve if the plan is clear and actionable; reject with a specific note explaining what needs to change
+
+Set confirmed=false first to read the plan, then call again with confirmed=true and your decision.`,
     {
       taskId:     z.string().describe("Task's MongoDB ObjectId"),
       approvalId: z.string().describe("Approval request's MongoDB ObjectId (from the task's approvals array)"),
-      decision:   z.enum(['approve', 'reject']),
-      note:       z.string().optional().describe('Reason for the decision'),
+      decision:   z.enum(['approve', 'reject']).optional().describe('Your decision — omit to just preview the plan'),
+      note:       z.string().optional().describe('Reason for the decision (required on reject, recommended on approve)'),
+      confirmed:  z.boolean().optional().default(false).describe('Set true to submit the decision after reviewing the plan'),
     },
-    async ({ taskId, approvalId, decision, note }) =>
-      call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/decide`, { decision, note }))
+    async ({ taskId, approvalId, decision, note, confirmed = false }) => {
+      // Always fetch task so reviewer can read the plan before deciding
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      const task = taskRes?.data?.task
+      if (!task) return errorText('Task not found')
+
+      const approval = (task.approvals || []).find(a => String(a._id) === String(approvalId))
+      if (!approval) return errorText('Approval request not found on this task')
+
+      if (!confirmed || !decision) {
+        // Preview mode — return plan so reviewer can read it first
+        const planLines = (approval.readme || '').split('\n')
+        const planPreview = planLines.slice(0, 80).join('\n') + (planLines.length > 80 ? '\n\n[…plan truncated, first 80 lines shown]' : '')
+        return text({
+          task:           { key: task.key, title: task.title, priority: task.priority },
+          approval:       { id: approval._id, title: approval.title, state: approval.state,
+                            submittedBy: approval.requestedBy?.name || approval.requestedBy?.email || 'unknown',
+                            submittedAt: approval.requestedAt },
+          planPreview,
+          reviewChecklist: [
+            'Is the plan clear and specific? (not vague high-level bullets)',
+            'Does it identify the correct files/modules to change?',
+            'Does it handle edge cases and error paths?',
+            'Is the scope reasonable for a single task?',
+            'Any security, data-loss, or regression risks?',
+          ],
+          message: `Review the plan above, then call decide_task_approval again with confirmed=true and decision="approve" or "reject".`,
+        })
+      }
+
+      return call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/decide`, { decision, note }))
+    }
   )
 }
 
@@ -5129,8 +5814,72 @@ function writeCursorWorkspace(task, projectAgentConfig, startPath) {
     mkdirSync(commandsDir, { recursive: true })
     mkdirSync(rulesDir,    { recursive: true })
 
+    // ── Ensure generated AI files are NOT committed by the developer ────────────
+    // These are runtime files — they change per task and per agent session.
+    // They belong in the developer's local env, not in git history.
+    const gitignorePath = join(repoRoot, '.gitignore')
+    const AI_GITIGNORE_ENTRIES = [
+      '# InternalTool AI workspace — auto-generated, do not commit',
+      '.cursor/agents/',
+      '.cursor/skills/',
+      '.cursor/commands/',
+      '.cursor/rules/',
+      '.claude/',
+      '.internaltool-active-task',
+    ]
+    try {
+      let existing = ''
+      if (existsSync(gitignorePath)) existing = readFileSync(gitignorePath, 'utf8')
+      const missing = AI_GITIGNORE_ENTRIES.filter(e => e.startsWith('#') ? false : !existing.includes(e))
+      if (missing.length > 0) {
+        const toAppend = '\n' + AI_GITIGNORE_ENTRIES[0] + '\n' + missing.join('\n') + '\n'
+        writeFileSync(gitignorePath, existing + toAppend, 'utf8')
+      }
+    } catch { /* non-fatal — gitignore update is best-effort */ }
+
     const written = []
 
+    // ── 0. Session protocol rule — always-apply, enforces skill gate ──────────
+    // This is the first rule Cursor sees (filename 00- sorts before all others).
+    // It forces the agent to read skills before editing — the root cause of
+    // builders skipping the skill step was the lack of a hard runtime constraint.
+    const sessionProtocolRule = `---
+description: InternalTool session protocol — enforced for every agent session on this task.
+alwaysApply: true
+---
+
+# ⛔ MANDATORY SESSION PROTOCOL
+
+**You MUST follow these steps IN ORDER before editing any file.**
+Skipping any step is a protocol violation and will result in incorrect implementation.
+
+## Step 1 — Read all skills (REQUIRED before any Edit/Write)
+For each file in \`.cursor/skills/\`:
+1. Read the file completely
+2. Call \`log_session_event\` with type="skill", name=<filename without .md>, role=<your role>
+
+Do NOT call Edit or Write until every skill file has been read and logged.
+
+## Step 2 — Recall memory
+Call \`recall(taskId="${taskId}")\` to restore facts from previous sessions.
+If memory contains a \`status\` key, read it — the task may have known blockers.
+
+## Step 3 — Get full context
+Call \`get_agent_context(taskId="${taskId}", role=<your role>)\`.
+Read the implementation plan, claimed files, and scout report before proceeding.
+
+## Step 4 — Claim files (builders only)
+Call \`claim_files\` with every file you will edit BEFORE your first Edit call.
+Editing unclaimed files causes merge conflicts with other agents.
+
+---
+
+**Role-specific hard constraints are in \`.cursor/agents/active-agent.md\`.**
+**Project-level rules are in \`.cursor/rules/\` (other .mdc files).**
+`
+    writeFileSync(join(rulesDir, '00-session-protocol.mdc'), sessionProtocolRule, 'utf8')
+    written.push(join(rulesDir, '00-session-protocol.mdc'))
+
     // ── 1. Project-level rules from DB → .cursor/rules/<name>.mdc ─────────────
     const projectRules = cfg.rules || []
     for (const r of projectRules) {
@@ -5394,23 +6143,41 @@ log_session_event(type="info", name="conflict-resolved", summary="<what you merg
 
 /**
  * Delete task-specific workspace files written at kickoff.
- * Project-level rules (.cursor/rules/<project-rule>.mdc) and skills are kept.
- * Only the active-agent and start-task command are removed (they are task-scoped).
+ * Removes: active-agent.md, start-task.md command, and ALL skill files in .cursor/skills/.
+ * Project-level rules (.cursor/rules/*.mdc) are kept — they are curated by the admin, not generated per task.
  */
 function deleteCursorWorkspace(role, startPath) {
   const deleted = []
   try {
     const repoRoot = findRepoRoot(startPath)
     if (!repoRoot) return deleted
-    const toDelete = [
+
+    // Always-delete: task-scoped agent and command files
+    const alwaysDelete = [
       join(repoRoot, '.cursor', 'agents', 'active-agent.md'),
       join(repoRoot, '.cursor', 'commands', 'start-task.md'),
     ]
-    for (const f of toDelete) {
+    for (const f of alwaysDelete) {
       try {
         if (existsSync(f)) { unlinkSync(f); deleted.push(f) }
       } catch { /* non-fatal */ }
     }
+
+    // Delete all skill files — they are fetched fresh on every kickoff
+    // based on role and task type. Keeping stale skills causes context bloat.
+    const skillsDir = join(repoRoot, '.cursor', 'skills')
+    if (existsSync(skillsDir)) {
+      try {
+        const skillFiles = readdirSync(skillsDir).filter(f => f.endsWith('.md'))
+        for (const f of skillFiles) {
+          try {
+            const fullPath = join(skillsDir, f)
+            unlinkSync(fullPath)
+            deleted.push(fullPath)
+          } catch { /* non-fatal */ }
+        }
+      } catch { /* non-fatal */ }
+    }
   } catch { /* non-fatal */ }
   return deleted
 }
@@ -5521,7 +6288,17 @@ async function apiWithRetry(fn, maxRetries = 2, initialDelay = 500) {
 }
 
 function wrapApiError(e) {
-  return { error: true, cause: e._cause || 'unknown', message: e.message?.split('\n')[0] }
+  const cause = e._cause || 'unknown'
+  const isAuth = cause === 'auth'
+  return {
+    error: true,
+    cause,
+    message: e.message?.split('\n')[0],
+    ...(isAuth ? {
+      authError: true,
+      fix: 'Your session token has expired or is invalid. Ask the developer to restart the MCP server (which re-reads the INTERNALTOOL_API_KEY env var) or re-run: npx internaltool-mcp to reconnect.',
+    } : {}),
+  }
 }
 
 // ── #9 Get last git commit metadata ──────────────────────────────────────────
@@ -6065,31 +6842,39 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       const task = taskRes.data.task
 
       // ── Approval gate check ───────────────────────────────────────────────────
-      // The server blocks non-admins from moving todo → in_progress without approval.
-      // Detect this early and guide the developer instead of failing silently after branch creation.
+      // Block branch creation (at both confirmed=false AND confirmed=true) until the plan is approved.
       const pendingApv2 = (task.approvals || []).find(a => a.state === 'pending') || null
       const hasApprovedApv2 = (task.approvals || []).some(a => a.state === 'approved')
       const approvalState = pendingApv2 ? 'pending' : hasApprovedApv2 ? 'approved' : 'none'
       const PLANNING_COLS = ['backlog', 'todo']
       const needsApproval = PLANNING_COLS.includes(task.column) && !hasApprovedApv2
-      if (needsApproval && !confirmed) {
+      if (needsApproval) {
         const isFix2 = /\b(fix|bug|hotfix|patch)\b/i.test(task.title + ' ' + (task.description || ''))
         const slug2 = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 35)
-        const previewBranch = `${isFix2 ? 'fix' : 'feature'}/${task.key.toLowerCase()}-${slug2}`
+        // Fetch devSlug here too so the preview matches the actual branch name
+        let devSlug2 = ''
+        try {
+          const meRes2 = await api.get('/api/auth/me')
+          const devName2 = meRes2?.data?.user?.name || meRes2?.data?.name || ''
+          devSlug2 = devName2.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 15)
+        } catch { /* non-fatal */ }
+        const previewBranch = devSlug2
+          ? `${devSlug2}/${isFix2 ? 'fix' : 'feature'}/${task.key.toLowerCase()}-${slug2}`
+          : `${isFix2 ? 'fix' : 'feature'}/${task.key.toLowerCase()}-${slug2}`
         return text({
           blocked: true,
           reason: 'approval_required',
           task:   { key: task.key, title: task.title, column: task.column, approvalState },
-          message: `The task's implementation plan (README) must be approved before creating a branch and moving to In progress.`,
+          message: `⛔ The plan must be approved before creating a branch. Do NOT code until the reviewer approves.`,
           approvalStatus: approvalState === 'pending'
-            ? `Plan is already submitted and waiting for reviewer approval. Once approved, call create_branch again.`
+            ? `Plan is submitted and waiting for reviewer approval. Once approved, call create_branch again.`
             : `Plan has not been submitted for review yet.`,
           nextSteps: approvalState === 'pending'
-            ? [`Wait for the reviewer to approve, then call create_branch with taskId="${taskId}"`]
+            ? [`Wait for decide_task_approval to return decision="approve", then call create_branch with taskId="${taskId}"`]
             : [
-                `1. Make sure the README / implementation plan is written on the task (use update_task with readmeMarkdown if needed)`,
-                `2. Call submit_task_for_approval with taskId="${taskId}" and the reviewerId of your project lead`,
-                `3. Once approved, call create_branch again — it will create "${previewBranch}" and move the task to In progress automatically`,
+                `1. Write the implementation plan: call update_task with readmeMarkdown if not already written`,
+                `2. Call submit_task_for_approval with taskId="${taskId}", summary="<3-8 sentence summary>", reviewerId="<admin user id>"`,
+                `3. Once approved: call create_branch — it will create "${previewBranch}" and move the task to In progress`,
               ],
         })
       }
@@ -6481,7 +7266,7 @@ Set confirmed=false first to preview the full plan, then confirmed=true to save
         })
       }
 
-      // Park Task B if provided
+      // Park Task B if provided — and clean up its workspace so skills don't bleed into Task A
       if (taskB && taskBId) {
         try {
           await api.patch(`/api/tasks/${taskBId}/park`, {
@@ -6490,6 +7275,14 @@ Set confirmed=false first to preview the full plan, then confirmed=true to save
             blockers:  '',
           })
         } catch { /* non-fatal — developer can park manually */ }
+        // Delete Task B's cursor workspace — same cleanup that park_task does.
+        // Without this, Task B's skills and session-protocol stay on disk while
+        // working on Task A's branch, and the agent may read the wrong context.
+        try { deleteCursorWorkspace(taskB?.agentRole || null, process.cwd()) } catch { /* non-fatal */ }
+        try { unlinkSync(join(process.cwd(), '.internaltool-active-task')) } catch { /* non-fatal */ }
+        api.patch(`/api/tasks/${taskBId}`, {
+          agentWorkspace: { clearedAt: new Date().toISOString() }
+        }).catch(() => {})
       }
 
       return text({
@@ -6661,21 +7454,33 @@ Set confirmed=false first to preview the full PR content, then confirmed=true to
         })
         if (!res?.success) return errorText(res?.message || 'Could not create PR')
 
-        // Delete the task-specific cursor rules file — coding is done
+        // Delete the full cursor workspace (skills, rules, active-agent) — coding is done
         const deletedRulesFile = deleteCursorRulesFile(task.key, repoPath)
+        deleteCursorWorkspace(task?.agentRole || null, repoPath || process.cwd())
+
+        // Move task to in_review directly — don't rely solely on GitHub webhook
+        // (webhook may not be configured, or may be delayed)
+        try {
+          await api.post(`/api/tasks/${taskId}/move`, { column: 'in_review', toIndex: 0 })
+        } catch { /* non-fatal — webhook will do it if direct patch fails */ }
+
+        // Remove .internaltool-active-task marker
+        try { unlinkSync(join(process.cwd(), '.internaltool-active-task')) } catch { /* non-fatal */ }
 
         return text({
           prNumber: res.data.prNumber,
           prUrl:    res.data.prUrl,
           title:    prTitle,
           draft,
-          message:  `PR #${res.data.prNumber} created.`,
-          cursorRulesCleared: deletedRulesFile
-            ? { cleared: true, path: deletedRulesFile, note: 'Task-specific Cursor rules file deleted — coding is complete.' }
-            : { cleared: false },
+          message:  `PR #${res.data.prNumber} created. Task moved to In Review.`,
+          cursorWorkspaceCleared: {
+            cleared: true,
+            rulesFile: deletedRulesFile || null,
+            note: 'Cursor workspace (skills + rules + active-agent) deleted — coding session is complete.',
+          },
           nextStep: draft
             ? 'PR is a draft. Mark it ready for review on GitHub when you want reviewer notifications to fire.'
-            : 'PR is live. The GitHub webhook will move the task to in_review and notify the reviewer within seconds.',
+            : `PR is live at ${res.data.prUrl}. Task is now in_review — the reviewer can call kickoff_task with agentRole="reviewer".`,
         })
       } catch (e) {
         return errorText(e.message)
@@ -7410,12 +8215,13 @@ Use this when a developer asks: "what do I do?", "how do I rebase?", "I have con
         } else {
           steps.push({
             step: stepNum++,
-            title: `Request review on PR #${branch.prNumber}`,
-            why: `Your PR is already open. After pushing the rebase, request reviewers so they can approve and merge.`,
+            title: `Get your PR reviewed — PR #${branch.prNumber}`,
+            why: `Your PR is already open. After pushing the rebase, ask your reviewer to approve so it can be merged.`,
             commands: [
-              { label: 'Request review via GitHub CLI', cmd: `gh pr review ${branch.prNumber} --request-changes` },
+              { label: 'Open the PR in your browser to add reviewers', cmd: `gh pr view --web ${branch.prNumber}` },
+              { label: 'Or check PR status in the terminal', cmd: `gh pr status` },
             ],
-            note: `PR URL: ${branch.prUrl || 'see GitHub'}`,
+            note: `PR URL: ${branch.prUrl || 'see GitHub'}. Add reviewers on GitHub (top-right "Reviewers" panel) — do NOT use "gh pr review --request-changes" (that submits a rejection verdict, not a review request).`,
           })
         }
 
@@ -7818,7 +8624,7 @@ Use this to remember decisions, constraints, context, and findings that should p
 Call recall(taskId) to retrieve everything at any time.`,
     {
       taskId: z.string().describe("Task's MongoDB ObjectId"),
-      key:    z.string().describe('Memory key — short, descriptive, no spaces (e.g. "arch_decision", "constraint_auth")'),
+      key:    z.string().describe('Memory key — short, descriptive, no spaces (e.g. "arch_decision", "constraint_auth"). In parallel builds with multiple agents on the same task, prefix with your role/index to avoid collisions (e.g. "builder1_discovered", "builder2_constraint"). Last write to the same key wins.'),
       value:  z.string().describe('Value to store — plain text, any length'),
     },
     async ({ taskId, key, value }) => {
@@ -7897,8 +8703,8 @@ Always call this first — it collapses context from the last 3 steps into one c
         if (repoPath && task.github?.headBranch) {
           try {
             const branch = task.github.headBranch
-            const status = execSync(`git -C "${repoPath}" status --short 2>/dev/null`, { encoding: 'utf8' }).trim()
-            const logLine = execSync(`git -C "${repoPath}" log --oneline -1 2>/dev/null`, { encoding: 'utf8' }).trim()
+            const status  = runGit('status --short', repoPath)
+            const logLine = runGit('log --oneline -1', repoPath)
             localState = { branch, dirty: status.length > 0, lastCommit: logLine }
           } catch { localState = { error: 'Could not read local git state' } }
         }