internaltool-mcp 1.5.2 → 1.5.3

package/index.js

@@ -541,7 +541,12 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         })),
         movedToInProgress: moved,
         suggestedBranch,
-        nextStep: `Use create_branch to create "${suggestedBranch}" on GitHub, then run:\n  git fetch origin\n  git checkout ${suggestedBranch}`,
+        preflightBeforeBranch: {
+          message: 'Before creating the branch, check your local git state first.',
+          commands: ['git status', 'git stash list'],
+          instruction: 'If you have uncommitted changes, stash or commit them before switching branches. Then call create_branch with your localState.',
+        },
+        nextStep: `Use create_branch to create "${suggestedBranch}" on GitHub — it will ask for your local git state first.`,
       })
     }
   )
@@ -847,7 +852,7 @@ Use this when returning to a task after a break, or when Claude needs the full p
 
       let coachingPrompt = null
       if (task.column === 'in_progress' && !task.github?.headBranch) {
-        coachingPrompt = 'No branch created yet. Use create_branch before writing code.'
+        coachingPrompt = 'No branch yet. Before create_branch: run "git status" in your terminal first — stash or commit any local changes, then call create_branch with your localState.'
       } else if (task.column === 'in_progress' && task.github?.headBranch) {
         coachingPrompt = `Branch: ${task.github.headBranch}. When commits are pushed, use raise_pr to open a PR.`
       } else if (task.column === 'in_review') {
@@ -885,19 +890,28 @@ Use this when returning to a task after a break, or when Claude needs the full p
   fix/TASK-XXX-short-description      (for bug fixes / patches)
 
 WHEN TO USE: Immediately after a task moves to in_progress.
-Claude will suggest this automatically after kickoff_task.
 
-Set confirmed=false first to preview the branch name, then confirmed=true to create it.
-After creation, run locally:
-  git fetch origin
-  git checkout <branchName>`,
+THREE-STEP FLOW — do not skip steps:
+  1. confirmed=false              → preview branch name + get pre-flight git commands to run locally
+  2. Run the pre-flight commands  → check local state, stash if needed, report back with localState
+  3. confirmed=true + localState  → branch is created on GitHub
+
+localState must be one of:
+  "clean"     — git status shows nothing to commit, working tree clean
+  "stashed"   — had changes, ran git stash, now clean
+  "committed" — had changes, did a WIP commit, now clean
+
+Never skip the localState check — switching branches with uncommitted changes
+can cause conflicts or silently carry changes onto the new branch.`,
     {
-      taskId:    z.string().describe("Task's MongoDB ObjectId"),
-      projectId: z.string().describe("Project's MongoDB ObjectId"),
-      fromRef:   z.string().optional().describe("Base ref to branch from (default: project's default branch)"),
-      confirmed: z.boolean().optional().default(false).describe('Set true to create the branch after reviewing the preview'),
+      taskId:     z.string().describe("Task's MongoDB ObjectId"),
+      projectId:  z.string().describe("Project's MongoDB ObjectId"),
+      fromRef:    z.string().optional().describe("Base ref to branch from (default: project's default branch)"),
+      confirmed:  z.boolean().optional().default(false).describe('Set true only after running pre-flight commands and setting localState'),
+      localState: z.enum(['clean', 'stashed', 'committed']).optional()
+                   .describe('Your local git state AFTER running git status. Required when confirmed=true.'),
     },
-    async ({ taskId, projectId, fromRef, confirmed = false }) => {
+    async ({ taskId, projectId, fromRef, confirmed = false, localState }) => {
       if (scopedProjectId && projectId !== scopedProjectId) {
         return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
       }
@@ -915,33 +929,64 @@ After creation, run locally:
         .slice(0, 35)
       const branchName = `${prefix}/${task.key.toLowerCase()}-${slug}`
 
-      // Preview
+      // Step 1 — preview + pre-flight commands
       if (!confirmed) {
         return text({
           preview: {
             action:     'create_branch',
             branchName,
-            fromRef:    fromRef || '(project default branch)',
-            repo:       '(resolved from project)',
+            basedOn:    fromRef || '(project default branch)',
             task:       { key: task.key, title: task.title },
           },
-          requiresConfirmation: true,
-          message: `Will create branch "${branchName}" on GitHub. Call create_branch again with confirmed=true to proceed.`,
+          preflightRequired: true,
+          preflightCommands: [
+            'git status',
+            'git stash list',
+            'git diff --stat',
+          ],
+          preflightInstructions: [
+            'Run the three commands above in your terminal right now.',
+            'If "git status" shows modified/untracked files: run "git stash push -m \\"wip: switching to ' + branchName + '\\"" then set localState="stashed"',
+            'If working tree is already clean: set localState="clean"',
+            'If you prefer a WIP commit: run "git add . && git commit -m \\"chore: wip\\"" then set localState="committed"',
+          ],
+          message: `Check your local git state first. Run the pre-flight commands above, handle any uncommitted changes, then call create_branch again with confirmed=true and localState=<clean|stashed|committed>.`,
         })
       }
 
+      // Step 2 — localState gate: block if developer skipped the check
+      if (!localState) {
+        return text({
+          blocked: true,
+          reason: 'localState is required when confirmed=true.',
+          message: 'You must run "git status" first and tell me your local state. Set localState to "clean", "stashed", or "committed" depending on what you found.',
+          preflightCommands: ['git status', 'git stash list'],
+        })
+      }
+
+      // Step 3 — create branch on GitHub
       try {
         const res = await api.post(`/api/projects/${projectId}/github/branches`, { branchName, fromRef })
         if (!res?.success) return errorText(res?.message || 'Could not create branch')
+
+        const checkoutSteps = [
+          'git fetch origin',
+          `git checkout ${branchName}`,
+        ]
+
+        // If stashed, remind to check stash still makes sense on the new branch
+        const stashReminder = localState === 'stashed'
+          ? 'You stashed changes before switching. After checkout, decide: does your stash belong on this branch? If yes: git stash pop. If it belongs to a different branch, leave it and pop it there.'
+          : null
+
         return text({
           branchName,
-          url:      res.data.url,
-          message:  'Branch created on GitHub.',
-          gitSteps: [
-            'git fetch origin',
-            `git checkout ${branchName}`,
-          ],
-          nextStep: 'Start coding! When your commits are ready to review, use raise_pr to open a pull request.',
+          url:           res.data.url,
+          localState,
+          message:       `Branch "${branchName}" created on GitHub.`,
+          gitSteps:      checkoutSteps,
+          stashReminder,
+          nextStep:      'Run the git steps above to switch locally, then start coding. When commits are pushed, use raise_pr.',
         })
       } catch (e) {
         return errorText(e.message)

package/package.json

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