internaltool-mcp 1.6.2 → 1.6.4

package/index.js

@@ -861,6 +861,39 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       const subtasksTotal = subtasks.length
 
       // ── Preview: show the full plan before touching anything ──
+      const approvalState = task.approval?.state || 'none'
+      const approvalBlocks = ['backlog', 'todo'].includes(task.column) && approvalState !== 'approved'
+
+      // Build the next-step roadmap so developer knows exactly what comes after reading the plan
+      let workflowRoadmap
+      if (!hasReadme) {
+        workflowRoadmap = [
+          `1. Write the implementation plan — click "Start writing" on the Plan tab`,
+          `2. Call submit_task_for_approval to send it for review`,
+          `3. After approval, call create_branch — the task moves to In progress automatically`,
+        ]
+      } else if (approvalState === 'none') {
+        workflowRoadmap = [
+          `1. ✅ Implementation plan is written — read it above`,
+          `2. Call submit_task_for_approval with taskId="${taskId}" to send it for review`,
+          `3. After approval, call create_branch — the task moves to In progress automatically`,
+        ]
+      } else if (approvalState === 'pending') {
+        workflowRoadmap = [
+          `1. ✅ Implementation plan written`,
+          `2. ⏳ Waiting for reviewer approval`,
+          `3. After approval, call create_branch — the task moves to In progress automatically`,
+        ]
+      } else {
+        // approved
+        workflowRoadmap = [
+          `1. ✅ Implementation plan written and approved`,
+          `2. Call create_branch with taskId="${taskId}" — moves task to In progress automatically`,
+          `3. Code → commit (use commit_helper) → push`,
+          `4. Call raise_pr — task moves to In review automatically`,
+        ]
+      }
+
       if (!confirmed) {
         return text({
           brief: {
@@ -868,24 +901,28 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
             title:       task.title,
             priority:    task.priority,
             description: task.description || '(no description)',
-            // The implementation plan — Claude must read and present this to the developer
             implementationPlan: hasReadme
               ? task.readmeMarkdown
-              : '⚠️  No implementation plan (README) found for this task. The developer should write one before starting work.',
+              : '⚠️  No implementation plan found. Write one in the Plan tab before starting work.',
             subtasks: subtasksTotal > 0
               ? { items: subtasks, progress: `${subtasksDone}/${subtasksTotal} done` }
               : null,
-            approvalState: task.approval?.state || 'none',
+            approvalState,
           },
           meta: {
             currentColumn:  task.column,
-            willMoveTo:     'in_progress',
             suggestedBranch,
           },
+          workflowRoadmap,
+          approvalWarning: approvalBlocks
+            ? approvalState === 'pending'
+              ? `⏳ Plan is submitted and awaiting approval — you cannot create a branch until it is approved.`
+              : `⚠️  Plan is not yet submitted for approval. Submit it first, then create the branch.`
+            : null,
           requiresConfirmation: true,
-          message: hasReadme
-            ? `Read the implementation plan above carefully, then call kickoff_task again with confirmed=true to start the task.`
-            : `⚠️ This task has no implementation plan. Consider writing one first (use update_task with readmeMarkdown), then confirm to start anyway.`,
+          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.`,
         })
       }
 
@@ -1443,6 +1480,34 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       if (!taskRes?.success) return errorText('Task not found')
       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.
+      const approvalState = task.approval?.state || 'none'
+      const PLANNING_COLS = ['backlog', 'todo']
+      const needsApproval = PLANNING_COLS.includes(task.column) && approvalState !== 'approved'
+      if (needsApproval && !confirmed) {
+        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}`
+        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.`,
+          approvalStatus: approvalState === 'pending'
+            ? `Plan is already 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}"`]
+            : [
+                `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`,
+              ],
+        })
+      }
+
       const isFix = /\b(fix|bug|hotfix|patch)\b/i.test(task.title + ' ' + (task.description || ''))
       const prefix = isFix ? 'fix' : 'feature'
       const slug = task.title
@@ -1527,18 +1592,31 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
         })
       }
 
-      // Step 3 — create branch on GitHub, then link it to the task
+      // Step 3 — create branch on GitHub (or confirm it already exists), then link + move
       const localState = gitState?.localState || 'unknown'
       try {
+        let branchUrl = null
+        let alreadyExisted = false
+
         const res = await api.post(`/api/projects/${projectId}/github/branches`, { branchName, fromRef })
-        if (!res?.success) return errorText(res?.message || 'Could not create branch')
+        if (!res?.success) {
+          // "Reference already exists" means the branch is already on GitHub — treat as success
+          const msg = (res?.message || '').toLowerCase()
+          if (msg.includes('already exists') || msg.includes('reference already exists')) {
+            alreadyExisted = true
+          } else {
+            return errorText(res?.message || 'Could not create branch')
+          }
+        } else {
+          branchUrl = res.data?.url || null
+        }
 
-        // Link the branch name back to the task so get_task_context / list_my_tasks reflect it immediately
+        // Link branch to task regardless of whether it was just created or already existed
         try {
           await api.patch(`/api/tasks/${taskId}/github/branch`, { headBranch: branchName })
-        } catch { /* non-fatal — branch was still created on GitHub */ }
+        } catch { /* non-fatal */ }
 
-        // Move task to in_progress now that the branch exists (server guard now allows it)
+        // Move task to in_progress now that branch is linked
         let movedToInProgress = false
         try {
           const freshTask = await api.get(`/api/tasks/${taskId}`)
@@ -1562,17 +1640,42 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
           unknown:   null,
         }[localState] || null
 
+        const statusMsg = alreadyExisted
+          ? `Branch "${branchName}" already existed on GitHub — linked to task.${movedToInProgress ? ' Task moved to In progress.' : ''}`
+          : `Branch "${branchName}" created on GitHub.${movedToInProgress ? ' Task moved to In progress.' : ''}`
+
         return text({
           branchName,
-          url:              res.data.url,
+          url:              branchUrl,
+          alreadyExisted,
           localState,
           movedToInProgress,
-          message:          `Branch "${branchName}" created on GitHub.${movedToInProgress ? ' Task moved to In progress.' : ''}`,
+          message:          statusMsg,
           gitSteps:         checkoutSteps,
           localStateNote,
           nextStep:         'Run the git steps above to switch locally, then start coding. When commits are pushed, use raise_pr.',
         })
       } catch (e) {
+        // Last-resort catch: if error message indicates branch already exists, still link + move
+        const msg = (e.message || '').toLowerCase()
+        if (msg.includes('already exists') || msg.includes('reference already exists')) {
+          try { await api.patch(`/api/tasks/${taskId}/github/branch`, { headBranch: branchName }) } catch { /* ok */ }
+          try {
+            const freshTask = await api.get(`/api/tasks/${taskId}`)
+            const col = freshTask?.data?.task?.column
+            if (col && ['todo', 'backlog'].includes(col)) {
+              await api.post(`/api/tasks/${taskId}/move`, { column: 'in_progress', toIndex: 0 })
+            }
+          } catch { /* ok */ }
+          return text({
+            branchName,
+            alreadyExisted:   true,
+            movedToInProgress: true,
+            message:          `Branch "${branchName}" already existed on GitHub — linked to task and moved to In progress.`,
+            gitSteps:         ['git fetch origin', `git checkout ${branchName}`],
+            nextStep:         'Run the git steps above to switch locally, then start coding.',
+          })
+        }
         return errorText(e.message)
       }
     }

package/package.json

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