internaltool-mcp 1.5.2 → 1.5.4

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', 'untracked', 'stashed', 'committed']).optional()
+                   .describe('Your local git state after running git status. Required when confirmed=true. Use "untracked" if git status shows only untracked files with no modified tracked files.'),
     },
-    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,69 @@ 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.',
+            'Read your git status output and pick the matching localState:',
+            '  "clean"     — "nothing to commit, working tree clean"',
+            '  "untracked" — only untracked files listed, no modified tracked files. Safe to proceed — untracked files stay in place when you switch branches, they do NOT follow you.',
+            '  "stashed"   — you had modified tracked files; run: git stash push -m "wip: switching to ' + branchName + '" — then set this.',
+            '  "committed" — you had changes; run: git add . && git commit -m "chore: wip" — then set this.',
+          ],
+          message: `Run the pre-flight commands above, read the output, then call create_branch again with confirmed=true and localState set to one of: clean | untracked | 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}`,
+        ]
+
+        // State-specific notes
+        const localStateNote = {
+          clean:     null,
+          untracked: 'Your untracked files (.cursor/, docs, etc.) will stay in your working directory after checkout — they are not tracked by git so they do not follow branches. They will not appear in commits on the new branch unless you explicitly git add them.',
+          stashed:   'You stashed changes before switching. After checkout, decide: does your stash belong on this new branch? If yes: git stash pop. If it belongs to a different branch, leave it and pop it there later.',
+          committed: 'You made a WIP commit before switching. That commit stays on the branch you were on — it will not appear on the new branch.',
+        }[localState] || 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,
+          localStateNote,
+          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.4",
   "description": "MCP server for InternalTool — connect AI assistants (Claude Code, Cursor) to your project and task management platform",
   "type": "module",
   "main": "index.js",