tspl-cli 0.0.0-stage → 0.1.1

package/src/mcp/server.js

@@ -0,0 +1,708 @@
+'use strict'
+
+const Crypto = require('crypto')
+const { bindApproach } = require('../shared')
+const { proposeApproaches, selectApproach, renderApproaches } = require('../task/approaches')
+const Path = require('path')
+const z = require('zod')
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js')
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js')
+
+const { version } = require('../../package.json')
+const { request } = require('../api-client')
+const { findProject } = require('../workspace')
+const { refreshIndex } = require('../analysis/analyzer')
+const { readIndex, readTask, writeTask, readFeedback, writeFeedback } = require('../config-store')
+const { createGraph } = require('../find/graph')
+const { createSearch } = require('../find/search')
+const { checkTask, taskText } = require('../task/check')
+const { projectInstructionsText } = require('../project-config')
+const { briefFrom, buildBrief, renderFiles, renderBrief } = require('../task/brief')
+const { reviewPlan, renderChecklist, changesSince, withSnapshot } = require('../task/plan')
+const { prepareBuild, describeProposal, blockers, runBuild, reviewBuild, describeReport, finishBuild, runPlanTests, runStyleChecks, mergeTests, renderBuildBrief, planRepos } = require('../task/build')
+const { conventionsFor } = require('../task/conventions')
+const { fetchDue, syncInBackground } = require('../commands/sync.command')
+
+const PROJECT_TTL = 5 * 60 * 1000
+const FEEDBACK_PER_FILE = 20
+
+const INSTRUCTIONS = `tspl knows the code of every repo in this project (it read them without AI).
+Tasks are prepared outside the AI with "tspl task new" (questions, done-when checks, files found; 0 tokens) and get a task id.
+With a task id: call get_brief, read the files it lists, compare two or three approaches with propose_approaches, show one recommendation, wait for an explicit user selection and record it with select_approach, then submit_plan for the checklist the user approves (approve_plan) before any code changes.
+Without a task id (free text only): check_task is the fallback that asks the questions here.`
+
+const createContext = cwd => {
+  let found = null
+  let foundAt = 0
+  let state = null
+
+  const load = async () => {
+    if (!found || Date.now() - foundAt > PROJECT_TTL) {
+      found = await findProject(cwd)
+      foundAt = Date.now()
+    }
+    const { project, repos, offline } = found
+    const failed = []
+    const saved = state ? state.index : readIndex(project._id)
+    let changed = false
+    const index = offline
+      ? saved
+      : await refreshIndex(project, repos, (repo, repoIndex, err, isNew) => {
+        if (err) failed.push(`${repo.name}: ${err.message}`)
+        changed = changed || Boolean(isNew)
+      }, saved)
+    if (!offline && (changed || fetchDue(project._id))) syncInBackground(cwd)
+    if (!Object.keys(index.repos || {}).length) {
+      throw new Error('tspl has not read this project yet. Ask the user to run: tspl analyze')
+    }
+    const signature = Object.values(index.repos).map(repo => repo.commitSha).join()
+    if (!state || state.signature !== signature || state.feedbackChanged) {
+      const graph = createGraph(index, readFeedback(project._id))
+      state = { index, signature, graph, search: createSearch(graph), feedbackChanged: false }
+    }
+    const paths = new Map(repos.map(repo => [repo.name, repo.path]))
+    return { ...state, project, paths, offline, failed }
+  }
+
+  return {
+    load,
+    feedbackChanged() {
+      if (state) state.feedbackChanged = true
+    },
+  }
+}
+
+const shareTask = (projectId, task) =>
+  request('PUT', `/api/v1/projects/${projectId}/tasks/${task.id}`, {
+    card: task.card,
+    assumptions: task.assumptions || [],
+    found: task.found || [],
+    used: task.used || [],
+    plan: task.plan || null,
+    ...(task.brief ? { brief: task.brief } : {}),
+  })
+
+const saveTask = async (projectId, task, wait = false) => {
+  writeTask(task)
+  const shared = shareTask(projectId, task).then(() => null, err => err)
+  return wait ? shared : null
+}
+
+/** The task on this computer, fetched from the server the first time (tasks created in the console). */
+const localTask = async (loaded, taskId) => {
+  const saved = readTask(taskId)
+  if (saved.id && loaded.offline) return saved
+  if (loaded.offline) throw new Error(`task ${taskId} is not on this computer and the server cannot be reached`)
+  let remote
+  try {
+    remote = await request('GET', `/api/v1/projects/${loaded.project._id}/tasks/${encodeURIComponent(taskId)}`)
+  } catch (err) {
+    if (err.statusCode === 404) throw new Error(`task ${taskId} was not found in ${loaded.project.name} (it may have been deleted). Check the id in the console.`)
+    throw err
+  }
+  const card = { apps: [], doneWhen: [], ...(remote.card || {}) }
+  const task = {
+    ...saved,
+    id: remote.key,
+    card,
+    summary: taskText(card),
+    assumptions: remote.assumptions || [],
+    found: remote.found || [],
+    used: remote.used || [],
+    plan: remote.plan || null,
+    status: remote.status,
+    scope: remote.scope || null,
+    approaches: remote.approaches || null,
+  }
+  writeTask(task)
+  return task
+}
+
+const NEXT_STEP = {
+  'pm-review': taskId =>
+    `Approved by the developer. The project needs PM approval before any code changes: the PM approves it in the tspl web console (Plans), or with "tspl plan approve ${taskId}" in their own terminal. Do not change any code yet; when the user says it is approved, call plan_status to check.`,
+  approved: taskId =>
+    `Approved. Call start_build to begin here, or, for a smaller context, the user runs "tspl build start ${taskId} --open" in a terminal to open a fresh AI session with only the checklist. Build exactly the checklist, follow how the code around it is written, run the tests and check every "done when" item. If you need to change files that are not on the checklist, stop and tell the user first.`,
+  'changes-requested': () => 'Changes were asked for. Change the plan as asked and call submit_plan again.',
+  'plan-review': taskId => `Waiting for the developer to approve the plan: "tspl plan approve ${taskId}" in their own terminal, or the tspl console. When they say it is done, call plan_status.`,
+  draft: () => 'Read the relevant code, propose approaches, wait for the user to choose, then submit_plan.',
+  building: () => 'Building. When the checklist is done, the tests ran and every "done when" item was checked, call finish_build.',
+  done: () => 'Done: the build was reported and passed.',
+}
+
+const text = value => ({ content: [{ type: 'text', text: value }] })
+
+const failure = err => ({ content: [{ type: 'text', text: `tspl could not do this: ${err.message}` }], isError: true })
+
+const describeQuestion = (question, i) => {
+  const lines = [`${i + 1}. [${question.header}] ${question.question}${question.multiSelect ? ' (choose one or more)' : ''} → card.${question.target || question.field}`]
+  question.options.forEach(option => lines.push(`   - ${option.label}${option.description ? `: ${option.description}` : ''}`))
+  if (question.suggestOptions) lines.push(`   ${question.suggestOptions}`)
+  if (!question.options.length && !question.suggestOptions) lines.push('   Free text: offer 2-3 likely answers if you can infer them, otherwise ask in plain text.')
+  return lines.join('\n')
+}
+
+const formatCheck = (result, taskId) => {
+  if (result.status === 'ready') {
+    return [
+      `Status: ready. Task id: ${taskId}`,
+      'Show this summary to the user and ask them to confirm or correct it:',
+      '',
+      result.summary,
+      '',
+      result.suggestChecks ? 'Suggest 2-4 short, testable "done when" checks under it for the user to tick or edit.' : null,
+      `If they confirm unchanged, call find_code with taskId "${taskId}". If they change the checks or correct something, call check_task once more with the card and taskId "${taskId}" first.`,
+    ]
+      .filter(line => line !== null)
+      .join('\n')
+  }
+  return [
+    `Status: needs answers (round ${result.card.round} of 2).`,
+    'Ask the user these questions in one go, with your multiple-choice question tool if you have one:',
+    '',
+    ...result.questions.map(describeQuestion),
+    '',
+    result.assumptions.length ? `Assumed so far: ${result.assumptions.join('; ')}` : null,
+    'Put each answer in the card field shown after the arrow, then call check_task again with this card:',
+    JSON.stringify(result.card),
+  ]
+    .filter(line => line !== null)
+    .join('\n')
+}
+
+const TRUST = {
+  high: 'Start with these files, at the "look at" places. Then confirm with one quick search of your own (the names below and the task\'s words) for places tspl may have missed, such as copies in other repos.',
+  medium: 'Good starting point, likely not complete. Read these files first, then search for the names below and the task\'s words to find the other places before you plan.',
+}
+
+const searchFolders = result =>
+  [...new Set(result.files.slice(0, 6).map(file => `${file.repo}/${Path.dirname(Path.dirname(file.path))}`))].slice(0, 4)
+
+const placeOptions = (result, areas) => {
+  const seen = new Set()
+  return [...(result.choices || []), ...areas]
+    .filter(option => option.files.length && !seen.has(option.files[0]) && seen.add(option.files[0]))
+    .slice(0, 4)
+}
+
+const lowConfidence = (result, areas, keywords) => {
+  if (!keywords.length) {
+    return [
+      'tspl is not sure yet.',
+      'First think how this code is probably named: function and variable names, labels on the screen, API paths, and other words for the user\'s words.',
+      'Then call find_code again with the same taskId and those as keywords (5-15 short words or names).',
+    ]
+  }
+  const options = placeOptions(result, areas)
+  if (options.length > 1) {
+    return [
+      'tspl found more than one place this could be.',
+      'If the task does not make clear which one, ask the user, in one question with these as options (plus "Something else"):',
+      ...options.map((area, i) => `  ${String.fromCharCode(65 + i)}) ${area.name} (${area.repo}): ${area.files.slice(0, 2).join(', ')}`),
+      'Then search the code yourself in that place, starting with the files below.',
+    ]
+  }
+  return [
+    'tspl is still not sure: search the code yourself, starting in these folders and with these words:',
+    `  - folders: ${searchFolders(result).join(', ')}`,
+    `  - words: ${[...new Set([...result.searchSteps.map(step => step.pattern), ...keywords])].slice(0, 10).join(', ')}`,
+  ]
+}
+
+const recordUsed = (loaded, saved, words, files) => {
+  const known = new Set(loaded.graph.files.map(file => `${file.repo}/${file.path}`))
+  const keys = files.map(file => file.trim().replace(/^([^:/\s]+):\s*/, '$1/'))
+  const accepted = keys.filter(key => known.has(key))
+  const feedback = readFeedback(loaded.project._id)
+  accepted.forEach(key => {
+    const list = (feedback[key] || []).filter(item => item !== words)
+    feedback[key] = [words, ...list].slice(0, FEEDBACK_PER_FILE)
+  })
+  writeFeedback(loaded.project._id, feedback)
+  return { accepted, unknown: keys.filter(key => !known.has(key)) }
+}
+
+const formatFind = (result, context, scope, keywords = []) => {
+  const lines = []
+  const commits = Object.values(context.index.repos).map(repo => `${repo.name}@${repo.branch}`).join(', ')
+  const level = result.confidence.level
+  const areas = result.areas.filter(area => area.score >= result.areas[0].score * 0.5)
+  lines.push(`tspl searched ${context.graph.files.length} files in ${context.graph.repos.length} repos (0 AI tokens).`)
+  lines.push(`Confidence: ${level.toUpperCase()} (${result.confidence.reasons.join('; ')})`)
+  if (scope.length) lines.push(`Apps: ${scope.join(', ')} (plus code they connect to)`)
+  if (keywords.length) lines.push(`Keywords: ${keywords.join(', ')}`)
+  lines.push(...(level === 'low' ? lowConfidence(result, areas, keywords) : [TRUST[level]]))
+  lines.push('')
+  lines.push(level === 'low' ? 'Closest files so far (hints only):' : 'Files, most relevant first:')
+  lines.push(...renderFiles(result.files))
+  if (level === 'medium' && placeOptions(result, areas).length > 1) {
+    lines.push('')
+    lines.push('Two or more places match; if the files do not make clear which one, ask the user:')
+    placeOptions(result, areas).forEach((area, i) => lines.push(`  ${String.fromCharCode(65 + i)}) ${area.name} (${area.repo}): ${area.files.slice(0, 2).join(', ')}`))
+  }
+  if (level !== 'low' && result.searchSteps.length) {
+    lines.push('')
+    lines.push('Names to search for:')
+    result.searchSteps.forEach(step => lines.push(`  ${step.pattern}   (${step.why})`))
+  }
+  if (result.chains.length) {
+    lines.push('')
+    lines.push('How they connect:')
+    result.chains.forEach(chain => {
+      lines.push(`  ${chain.map((step, i) => `${i ? ` → ${step.detail ? `${step.detail} → ` : ''}` : ''}${step.repo}: ${step.path}`).join('')}`)
+    })
+  }
+  if (result.placement.length) {
+    lines.push('')
+    lines.push('New files, if needed, usually go:')
+    result.placement.forEach(place => lines.push(`  ${place.repo}: ${place.pattern} (${place.count} like this)`))
+  }
+  lines.push('')
+  lines.push(`Based on the last fetched commit of: ${commits}. Local, uncommitted changes are not included.`)
+  if (context.failed.length) lines.push(`Not refreshed: ${context.failed.join('; ')}`)
+  lines.push('')
+  lines.push('When you know which files change, call report_files with them (repo: path), including any tspl missed.')
+  return lines.join('\n')
+}
+
+const formatBrief = (task, loaded, cwd) => {
+  const level = task.brief.confidence.level
+  const next = []
+  if (task.scope && !task.scope.confirmed) {
+    next.push(`The PM sent the scope back: "${task.scope.note || 'no note'}". Tell the user; they can change the task with: tspl task edit ${task.id}. Do not plan until the scope is confirmed.`)
+  } else if (task.plan && NEXT_STEP[task.status]) {
+    next.push(`A plan v${task.plan.version} exists already. ${NEXT_STEP[task.status](task.id)}`)
+  } else {
+    next.push(
+      `Read the files above at the "look at" places. ${level === 'high' ? 'Confirm with one quick search for the names above.' : 'Also do one short, targeted search for the names above and the task\'s words (grep, not whole repos).'}`,
+      `Compare approaches and ask the user to choose before calling submit_plan with taskId "${task.id}": files to edit, create and remove (with why), screen changes, and tests with the numbers of the "done when" checks they prove.`,
+    )
+  }
+  return [renderApproaches(task.approaches), '', renderBrief(task, { files: loaded.graph.files.length, repos: loaded.graph.repos.length }, projectInstructionsText(cwd)), '', ...next].join('\n')
+}
+
+const cardShape = {
+  ticket: z.string().optional().describe('Ticket id or link, if the user gave one'),
+  type: z.string().optional().describe('feature, change or bug'),
+  what: z.string().optional().describe('What should change, in the user\'s words'),
+  where: z.string().optional().describe('Where it is, as the user said it (app, screen, menu)'),
+  apps: z.array(z.string()).optional().describe('App/repo names chosen by the user'),
+  screen: z.string().optional().describe('Screen chosen by the user'),
+  who: z.string().optional().describe('Who uses it (role), if the user said'),
+  how: z.string().optional().describe('Features and changes: how it should work (steps or rules)'),
+  steps: z.string().optional().describe('Bugs: steps to make it happen'),
+  now: z.string().optional().describe('Bugs: what happens now. Changes: how it works today'),
+  expected: z.string().optional().describe('Bugs: what should happen'),
+  doneWhen: z.array(z.string()).optional().describe('Checks that must pass when done'),
+  details: z.string().optional().describe('Ticket description and acceptance criteria, text from screenshots or PDFs, and anything else the user said'),
+  skip: z.boolean().optional().describe('true if the user wants to skip further questions'),
+  round: z.number().optional().describe('Copy from the previous check_task answer'),
+  asked: z.record(z.string(), z.number()).optional().describe('Copy from the previous check_task answer'),
+  taskId: z.string().optional().describe('When correcting or confirming a task that is already ready, its task id'),
+}
+
+const PLAN_ITEM = z.union([z.string(), z.object({ file: z.string(), why: z.string().optional() })])
+
+const createServer = (cwd, context = createContext(cwd)) => {
+  const server = new McpServer({ name: 'tspl', version }, { instructions: INSTRUCTIONS })
+
+  server.registerTool(
+    'check_task',
+    {
+      title: 'Check a task is clear (fallback when there is no task id)',
+      description:
+        'Only when the user gave free text and no task id. Fill the card ONLY with what the user said or showed; leave the rest empty. ' +
+        'Returns either a few questions to ask the user (with options taken from the code) or "ready" with a task id and a summary to confirm. ' +
+        'Tasks prepared with "tspl task new" already have an id: use get_brief instead.',
+      inputSchema: cardShape,
+    },
+    async ({ taskId: existing, ...card }) => {
+      try {
+        const loaded = await context.load()
+        const result = checkTask(card, loaded)
+        let taskId = null
+        if (result.status === 'ready') {
+          const saved = existing ? readTask(existing) : {}
+          taskId = saved.id || `t-${Date.now().toString(36)}-${Crypto.randomBytes(2).toString('hex')}`
+          await saveTask(loaded.project._id, {
+            ...saved,
+            id: taskId,
+            status: saved.status && saved.status !== 'stopped' ? saved.status : 'draft',
+            projectId: loaded.project._id,
+            card: result.card,
+            assumptions: result.assumptions,
+            summary: result.summary,
+            createdAt: saved.createdAt || new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          })
+        }
+        return text(formatCheck(result, taskId))
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  server.registerTool(
+    'find_code',
+    {
+      title: 'Find the code for a task',
+      description:
+        'Find the files a task is about across all repos of the project, with reasons, how they connect (screen → API → service → model), ' +
+        'where new files usually go and a confidence level. Uses no AI tokens. Pass taskId from check_task, or a task text.',
+      inputSchema: {
+        taskId: z.string().optional(),
+        task: z.string().optional().describe('Task text, if there is no taskId'),
+        apps: z.array(z.string()).optional().describe('Limit to these apps/repos (and code they connect to)'),
+        limit: z.number().optional().describe('How many files (default 10)'),
+        keywords: z.array(z.string()).optional().describe('Words you expect in the code for this task: function or variable names, screen labels, API paths, and other words for the user\'s words'),
+      },
+    },
+    async ({ taskId, task, apps, limit, keywords }) => {
+      try {
+        const loaded = await context.load()
+        const saved = taskId ? await localTask(loaded, taskId) : null
+        const words = (keywords && keywords.length ? keywords : (saved && saved.keywords) || []).map(word => String(word).trim()).filter(Boolean).slice(0, 20)
+        const base = saved ? taskText(saved.card) : task
+        if (!base) throw new Error('pass taskId or task')
+        const query = [base, ...words].join(' ')
+        const known = new Set(loaded.graph.repos.map(repo => repo.name))
+        const scope = (apps || (saved && saved.card.apps) || []).filter(name => known.has(name))
+        const result = loaded.search.find(query, { limit: limit || 10, repos: scope, title: [saved ? saved.card.what : base, ...words].join(' ') })
+        if (saved) {
+          const basis = Object.fromEntries(Object.values(loaded.index.repos).map(repo => [repo.name, { branch: repo.branch, commit: repo.commitSha }]))
+          const brief = briefFrom(result, { keywords: words, basis, source: 'ai', refined: saved.brief ? saved.brief.refined : null })
+          await saveTask(loaded.project._id, { ...saved, keywords: words, basis, brief, found: result.files.map(file => `${file.repo}/${file.path}`), confidence: result.confidence.level })
+        }
+        return text(formatFind(result, loaded, scope, words))
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  server.registerTool(
+    'get_brief',
+    {
+      title: 'Get the brief of a prepared task',
+      description:
+        'Call first when the user gives a tspl task id (t-…). Returns the task card, the "done when" checks, whether the PM confirmed the scope, ' +
+        'and the files tspl found for it (no AI tokens) with where to look and how they connect. Read those files, then propose approaches and wait for the explicit selection before submit_plan.',
+      inputSchema: { taskId: z.string() },
+    },
+    async ({ taskId }) => {
+      try {
+        const loaded = await context.load()
+        const saved = await localTask(loaded, taskId)
+        const { brief } = buildBrief(loaded, saved, { keywords: saved.keywords || [], source: saved.brief ? saved.brief.source : 'wizard', refined: saved.brief ? saved.brief.refined : null })
+        const task = {
+          ...saved,
+          brief,
+          found: brief.files.map(file => `${file.repo}/${file.path}`),
+          confidence: brief.confidence.level,
+          basis: brief.basis,
+        }
+        writeTask(task)
+        return text(formatBrief(task, loaded, cwd))
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  server.registerTool(
+    'report_files',
+    {
+      title: 'Report the files you will change',
+      description:
+        'After you have looked at the code, report the files you will change, including files tspl did not list. ' +
+        'tspl learns from this so the next similar task finds them first.',
+      inputSchema: {
+        taskId: z.string().optional(),
+        task: z.string().optional().describe('Task text, if there is no taskId'),
+        files: z.array(z.string()).describe('Files you will change, as "repo: path" or "repo/path"'),
+        note: z.string().optional().describe('Anything tspl got wrong or missed'),
+      },
+    },
+    async ({ taskId, task, files, note }) => {
+      try {
+        const loaded = await context.load()
+        const saved = taskId ? readTask(taskId) : null
+        const words = saved && saved.card ? taskText(saved.card) : task
+        if (!words) throw new Error('pass taskId or task')
+        const { accepted, unknown } = recordUsed(loaded, saved, words, files)
+        context.feedbackChanged()
+        if (saved && saved.id) {
+          const found = new Set(saved.found || [])
+          await saveTask(loaded.project._id, { ...saved, used: accepted, missed: accepted.filter(key => !found.has(key)), note: note || null })
+        }
+        return text(
+          `Saved ${accepted.length} file(s); tspl will rank them higher for similar tasks.` +
+            (unknown.length ? ` Not in tspl's copy of the code (new or uncommitted files are fine): ${unknown.join(', ')}` : ''),
+        )
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  const APPROACH_OPTION = z.object({
+    id: z.string().min(1).max(60), title: z.string().min(1).max(200), summary: z.string().min(1).max(2000),
+    benefits: z.array(z.string().min(1).max(1000)).min(1).max(10), drawbacks: z.array(z.string().min(1).max(1000)).min(1).max(10),
+    files: z.array(z.string().min(1).max(1000)).max(100).optional(),
+  })
+  server.registerTool('propose_approaches', {
+    title: 'Offer implementation approaches',
+    description: 'After reading relevant code, save two or three meaningful options and one recommendation. Show them to the user and wait for an explicit selection before planning.',
+    inputSchema: { taskId: z.string(), expectedVersion: z.number().int().min(0), options: z.array(APPROACH_OPTION).min(2).max(3), recommendedId: z.string(), reason: z.string().min(1).max(2000) },
+  }, async ({ taskId, ...proposal }) => {
+    try {
+      const loaded = await context.load()
+      if (loaded.offline) throw new Error('Connect to the server before saving approaches')
+      const task = await proposeApproaches(loaded.project._id, taskId, proposal)
+      return text(renderApproaches(task.approaches))
+    } catch (err) { return failure(err) }
+  })
+  server.registerTool('select_approach', {
+    title: "Record the user's approach selection",
+    description: 'Only after the user explicitly answers the options question, record their chosen option ID and approach version. Never choose the recommendation automatically. This does not approve a plan.',
+    inputSchema: { taskId: z.string(), version: z.number().int().min(1), optionId: z.string() },
+  }, async ({ taskId, ...selection }) => {
+    try {
+      const loaded = await context.load()
+      if (loaded.offline) throw new Error('Connect to the server before saving the selection')
+      const task = await selectApproach(loaded.project._id, taskId, { ...selection, via: 'mcp' })
+      return text(renderApproaches(task.approaches))
+    } catch (err) { return failure(err) }
+  })
+
+  server.registerTool(
+    'submit_plan',
+    {
+      title: 'Submit the plan checklist',
+      description:
+        'After reading the code and recording the explicit approach selection, submit the plan: files to edit, create and remove (with what changes in each), ' +
+        'screen changes, and tests (with the numbers of the "done when" checks each test covers). tspl checks it against the code ' +
+        'and returns the checklist to show the user for approval. Do not change any code before the user approves.',
+      inputSchema: {
+        taskId: z.string(),
+        approach: z.object({ version: z.number().int().min(1), optionId: z.string() }).optional().describe('The saved approach selection; required for plan submission'),
+        edit: z.array(PLAN_ITEM).optional().describe('Files to edit, as "repo/path" with why'),
+        create: z.array(PLAN_ITEM).optional().describe('New files, as "repo/path" with why'),
+        remove: z.array(PLAN_ITEM).optional().describe('Files to delete, as "repo/path" with why'),
+        screens: z.array(z.string()).optional().describe('What the user will see change on screen'),
+        tests: z.array(z.union([z.string(), z.object({ name: z.string(), file: z.string().optional(), checks: z.array(z.number()).optional(), command: z.string().optional() })])).optional()
+          .describe('Tests to add or run: name, file as "repo/path" (the test file to add or change), checks = numbers of the "done when" items the test proves, command = the shell command that runs it from the repo folder (tspl runs it at finish_build)'),
+        notes: z.string().optional().describe('Risks, open questions, things left out'),
+        testCases: z.array(z.object({ title: z.string(), steps: z.array(z.string()).optional(), expected: z.string().optional() })).optional()
+          .describe('Only when the task has no "done when" items: propose 2-6 test cases (title = what must be true, steps a person or test follows, expected result). They become TC1..TCn and your tests\' "checks" refer to their numbers; people approve them with the plan.'),
+      },
+    },
+    async ({ taskId, ...plan }) => {
+      try {
+        const loaded = await context.load()
+        const saved = await localTask(loaded, taskId)
+        if (loaded.offline) throw new Error('Connect to the server before planning')
+        const chosen = bindApproach(saved.approaches, saved.card, plan.approach)
+        plan.approach = chosen
+        const review = reviewPlan(plan, saved.card, loaded.graph)
+        if (review.testCases) {
+          saved.card = { ...saved.card, doneWhen: review.testCases.map(item => item.title), testCases: review.testCases.map(item => ({ steps: item.steps, expected: item.expected || item.title })) }
+        }
+        const version = ((saved.plan && saved.plan.version) || 0) + 1
+        const changes = changesSince(saved.plan, review)
+        const planned = ['edit', 'remove'].flatMap(kind => review[kind].map(item => item.file))
+        const { accepted } = recordUsed(loaded, saved, taskText(saved.card), planned)
+        context.feedbackChanged()
+        const found = new Set(saved.found || [])
+        const plannedTask = {
+          ...saved,
+          used: accepted,
+          missed: accepted.filter(key => !found.has(key)),
+          status: 'plan-review',
+          plans: saved.plan ? [...(saved.plans || []), saved.plan] : saved.plans || [],
+          plan: { ...withSnapshot(review, saved.card, cwd), approach: plan.approach, version, basis: saved.basis || null, submittedAt: new Date().toISOString() },
+        }
+        const shared = await shareTask(loaded.project._id, plannedTask)
+        writeTask({ ...plannedTask, status: shared.status, plan: shared.plan, approaches: shared.approaches })
+        return text([
+          `Selected approach: ${chosen.option.title} [${chosen.optionId}] (v${chosen.version})`,
+          renderChecklist(review, saved.card, `${taskId} v${version}`),
+          changes.length ? `\nCHANGES SINCE v${version - 1}\n${changes.map(line => `  ${line}`).join('\n')}` : null,
+          '',
+          review.warnings.length || review.companions.length
+            ? 'Fix only the tspl checks that are real problems and call submit_plan again; mention the others to the user.'
+            : null,
+          'Show the whole checklist above to the user. A person approves it, not this chat: the user runs',
+          `  tspl plan approve ${taskId}      (or: tspl plan reject ${taskId} --note "…")`,
+          'in their own terminal, or decides in the tspl console. Do not change any code before plan_status says approved. When the user says they have decided, call plan_status.',
+        ].filter(line => line !== null).join('\n'))
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  server.registerTool(
+    'plan_status',
+    {
+      title: 'Check if a plan is approved',
+      description: 'Call after the user says they decided on the plan, before building, and whenever the user asks where a task stands: returns who approved the plan, how, and whether building may start.',
+      inputSchema: { taskId: z.string() },
+    },
+    async ({ taskId }) => {
+      try {
+        const loaded = await context.load()
+        const task = await request('GET', `/api/v1/projects/${loaded.project._id}/tasks/${taskId}`)
+        const saved = readTask(taskId)
+        if (saved.id) writeTask({ ...saved, status: task.status, decisions: task.decisions })
+        const decisions = (task.decisions || []).map(decision =>
+          `${decision.stage} ${decision.approved ? 'approved' : 'asked for changes'} v${decision.planVersion || '-'}${decision.userName ? ` (${decision.userName}${decision.via ? `, ${decision.via === 'web' ? 'console' : 'terminal'}` : ''})` : ''}${decision.note ? `: ${decision.note}` : ''}`)
+        return text([
+          `Task ${taskId} · plan v${task.plan ? task.plan.version : '-'} · status: ${task.status}`,
+          ...decisions.map(line => `  - ${line}`),
+          NEXT_STEP[task.status] ? NEXT_STEP[task.status](taskId) : '',
+        ].join('\n'))
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  server.registerTool(
+    'start_build',
+    {
+      title: 'Start building an approved plan',
+      description:
+        'Call when the plan is approved. First call without confirm: tspl proposes the branch name and the branch each repo starts from, ' +
+        'and shows uncommitted changes; ask the user to confirm or change them. Then call again with confirm true (and branch, bases or ' +
+        'fromCurrent if they changed anything): tspl creates the branch in every repo on the plan and turns on the edit lock.',
+      inputSchema: {
+        taskId: z.string(),
+        confirm: z.boolean().optional(),
+        branch: z.string().optional().describe('Branch name, if the user changed it'),
+        bases: z.record(z.string(), z.string()).optional().describe('Branch each repo starts from, if the user changed it: { repo: branch }'),
+        fromCurrent: z.boolean().optional().describe('true to start from the branch each repo has checked out now'),
+      },
+    },
+    async ({ taskId, confirm, branch, bases, fromCurrent }) => {
+      try {
+        const loaded = await context.load()
+        const task = await request('GET', `/api/v1/projects/${loaded.project._id}/tasks/${taskId}`)
+        if (!['approved', 'building'].includes(task.status)) {
+          return text(`Not approved yet (status: ${task.status}). ${NEXT_STEP[task.status] ? NEXT_STEP[task.status](taskId) : ''}`)
+        }
+        const proposal = prepareBuild({ taskKey: taskId, task, project: loaded.project, paths: loaded.paths, branch, bases, fromCurrent })
+        const problems = blockers(proposal)
+        if (!confirm) {
+          return text([
+            describeProposal(proposal),
+            ...problems.map(problem => `Problem: ${problem}`),
+            '',
+            problems.length
+              ? 'Tell the user these must be fixed before building starts (for example commit or stash their changes), then call start_build again.'
+              : 'Ask the user to confirm this branch and where each repo starts from (or change them), then call start_build with confirm: true.',
+          ].join('\n'))
+        }
+        const result = await runBuild({ projectId: loaded.project._id, taskKey: taskId, task, proposal })
+        if (!result.started) {
+          return text(`Not started:\n${result.problems.map(problem => `  - ${problem}`).join('\n')}\nTell the user and ask how to go on.`)
+        }
+        return text([
+          ...result.repos.map(repo => `${repo.name}: on ${proposal.branch} from ${repo.base}@${repo.baseSha.slice(0, 7)}${repo.notes.length ? ` (${repo.notes.join('; ')})` : ''}`),
+          '',
+          renderBuildBrief({ ...task, key: taskId, build: { branch: proposal.branch, repos: result.repos } }, result.repos, conventionsFor(loaded.graph, loaded.index, { focus: planRepos(task.plan) }), projectInstructionsText(cwd)),
+          '',
+          'The edit lock is on: in these repos only the files on the approved checklist can be changed, and only on this branch; git refuses commits and pushes with other files.',
+          'Now build the checklist item by item, run the tests and check every "done when" item.',
+          'When everything is done, do NOT commit or push: call finish_build with the result of each "done when" item and each test. tspl runs the test commands from the plan itself on the files as they are now; the developer commits and pushes later if they want.',
+        ].join('\n'))
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  server.registerTool(
+    'finish_build',
+    {
+      title: 'Report a finished build',
+      description:
+        'Call when the approved checklist is built, the tests ran and every "done when" item was checked. tspl runs the test commands from the plan itself, plus lint and format on the changed files when the repo has them, ' +
+        'compares the changes in git with the approved checklist, saves the report for the team, and the server marks the task done only when everything passed. ' +
+        'Report honestly: a check or test that did not pass must be reported as passed: false.',
+      inputSchema: {
+        taskId: z.string(),
+        checks: z.array(z.object({
+          n: z.number().describe('Number of the "done when" item'),
+          passed: z.boolean(),
+          how: z.string().optional().describe('How you checked it, or what went wrong'),
+        })).describe('One entry per "done when" item'),
+        tests: z.array(z.object({
+          name: z.string(),
+          passed: z.boolean(),
+          how: z.string().optional().describe('Command you ran, or the failure'),
+        })).describe('Tests you ran and their result'),
+        summary: z.string().optional().describe('What changed, in two or three plain sentences'),
+      },
+    },
+    async ({ taskId, checks, tests, summary }) => {
+      try {
+        const loaded = await context.load()
+        const task = await request('GET', `/api/v1/projects/${loaded.project._id}/tasks/${taskId}`)
+        if (task.plan && task.plan.workflow) {
+          // Workflow tasks are finished by the same controller as `tspl task run`: the AI's own report counts for nothing.
+          const { runTask } = require('../workflow/controller')
+          const { controllerDeps, renderOutcome } = require('../workflow/runtime')
+          const result = await runTask({ cwd, taskId, options: { external: true } }, controllerDeps(cwd, { interactive: false }))
+          return text([
+            'tspl does not take this report as proof. It checked the committed work itself:',
+            '',
+            renderOutcome(result),
+            '',
+            result.stage === 'ready'
+              ? 'The pull requests are ready for human review.'
+              : 'Tell the user exactly this state and the next step above. Do not say the task is done.',
+          ].join('\n'))
+        }
+        if (!['building', 'done'].includes(task.status) || !task.build) {
+          return text(`This task has no started build (status: ${task.status}). ${NEXT_STEP[task.status] ? NEXT_STEP[task.status](taskId) : ''}`)
+        }
+        const executed = [...runPlanTests({ task, paths: loaded.paths }), ...runStyleChecks({ task, paths: loaded.paths })]
+        const report = reviewBuild({ task, paths: loaded.paths, checks, tests: mergeTests(executed, tests) })
+        const saved = await finishBuild({ projectId: loaded.project._id, taskKey: taskId, task, report, summary })
+        const next = report.passed
+          ? [
+              'Saved: the tests passed and the task is done. Nothing was committed or pushed.',
+              'Show this report to the user. Committing, pushing and opening a pull request are their choice; if they want it:',
+              ...report.repos.filter(repo => !repo.missing).flatMap(repo => [
+                `  ${repo.name}: commit, then ${repo.pushed ? 'already pushed' : repo.push}`,
+                repo.pullRequest ? `    pull request: ${repo.pullRequest}` : '    open the pull request in your git host',
+              ]),
+            ]
+          : [
+              `Saved, but the task is not done (status: ${saved.status}); the edit lock stays on.`,
+              'Show the problems to the user. Fix them (or, for files off the checklist, submit a new plan version for approval), then call finish_build again. Do not commit to make it pass.',
+            ]
+        return text([describeReport(report), '', ...next].join('\n'))
+      } catch (err) {
+        return failure(err)
+      }
+    },
+  )
+
+  return server
+}
+
+const startServer = async cwd => {
+  const server = createServer(cwd)
+  await server.connect(new StdioServerTransport())
+}
+
+module.exports = {
+  localTaskForTest: localTask,
+  createContext,
+  saveTask,
+  createServer,
+  startServer,
+}