@taiga-ai/mcp-server 0.20.0-dev.454 → 0.21.0-dev.455

package/src/tools/autonomy.ts

@@ -22,12 +22,11 @@ export function registerAutonomyTools(server: McpServer, client: TaigaClient) {
       {
         title: "Set a product's autonomy defaults",
         description:
-          "Set the defaults a product's initiatives follow when they have not decided for themselves. autoBuild: " +
-          'false makes every landed plan wait for a person to approve or reject it; true builds it as soon as the ' +
-          'product has room. autoMerge: false makes pull requests wait for a person to merge them; null follows ' +
-          "the organization and factory above (autonomous merge needs the organization's switch on, and a factory " +
-          'can turn it off for everything under it; neither can be opened from here). Defaults, not rules: an ' +
-          'initiative can decide otherwise for itself. Changes how work proceeds.',
+          "Set the defaults a product's initiatives follow unless they decide for themselves. autoBuild: false " +
+          'makes every plan wait for a person to approve or reject it; true builds it as soon as the product has ' +
+          'room. autoMerge: false makes pull requests wait for a person to merge; null follows the organization ' +
+          'and factory (autonomous merge needs the organization switch on, a factory can turn it off, and neither ' +
+          'is changed here).',
         inputSchema: z.object({
           productId,
           autoBuild: z.boolean().optional().describe('Build landed plans without a review by default'),
@@ -64,11 +63,10 @@ export function registerAutonomyTools(server: McpServer, client: TaigaClient) {
       {
         title: "Set whether an initiative's pull request merges on its own",
         description:
-          "Set whether one initiative's pull request merges on its own: true lets its pull request merge itself once the " +
-          "repository's own rules pass (required checks, reviews, a code reviewer you made Taiga wait for); false " +
-          "makes it wait for a person; null follows the product's default. The final word within what the " +
-          'organization and factories allow: where either has turned autonomous merge off, true changes nothing. ' +
-          'Taiga merges through your rules, never around them.',
+          "Set whether one initiative's pull request merges itself once the repository's rules pass (required " +
+          'checks, reviews, a code reviewer Taiga waits for): true, false (a person merges), or null (product ' +
+          'default). Where the organization or factory has turned autonomous merge off, true changes nothing. ' +
+          "Taiga merges through the repository's rules, never around them.",
         inputSchema: z.object({
           initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it'),
           autoMerge: z

package/src/tools/backlogs.ts

@@ -5,6 +5,7 @@ import {
   type ActivityActor,
   type BacklogItem,
   BUILD_RUN_STATUSES,
+  INITIATIVE_STATES,
   PLAN_REJECTION_COMMENT_MAX_CHARS,
   PR_CLOSING_STATES,
   USER_DROP_STATES,
@@ -74,10 +75,9 @@ const ITEM_OUTCOME_FIELDS = [
  * leaves it null, and the lifecycle is what says why and what moves it on.
  */
 const LIFECYCLE_MEANING =
-  'situation says in one sentence where it stands, whose turn it is and the call that moves it on. The same ' +
-  'as fields: lifecycle says whose turn it is and what moves it on: cta start_plan is taiga_queue_initiative, ' +
-  'retry_plan taiga_plan_again (planFailureCause says why the plan stopped), start_build taiga_approve_plan, ' +
-  'resume_build taiga_resume_initiative, retry_build a fresh run (start over, in the web), review_pr and ' +
+  'situation says in a sentence where it stands and what moves it on. lifecycle.cta names the next call: ' +
+  'start_plan taiga_queue_initiative, retry_plan taiga_plan_again (planFailureCause says why), start_build ' +
+  'taiga_approve_plan, resume_build taiga_resume_initiative, retry_build a fresh run (web only), review_pr and ' +
   'view_pr the pull request. needsHumanCause is set only when the line stopped on it.';
 
 /** The move each call to action is, in the tools' words. */
@@ -304,13 +304,11 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     {
       title: 'List initiatives',
       description:
-        "List a product's initiatives (its backlog): titles, category, status, where each one is on the " +
-        'line (backlog, todo, queue, plan, build, done), situation (where it stands and what moves it on, in a ' +
-        'sentence) and criteria, how many of its acceptance criteria are met ' +
-        '(null before it is planned; met counts the criteria the agent confirmed with evidence or a person checked ' +
-        'off, so a done item can show fewer met than it has). Use this to find the item you are working on (query ' +
-        'finds one by title), then read its acceptance criteria and technical context with taiga_get_initiative. ' +
-        'Archived items are left out unless asked for.',
+        "List a product's initiatives: title, category, status, place on the line (backlog, todo, queue, plan, " +
+        'build, done), situation (where it stands and what moves it on) and criteria (acceptance criteria met, ' +
+        'confirmed with evidence or checked off by a person; null before planning, so a done initiative can show ' +
+        'fewer met than it has). query finds one by title; taiga_get_initiative reads it in full. Archived ones ' +
+        'are left out unless asked for.',
       inputSchema: z.object({
         productId,
         query: z
@@ -328,6 +326,12 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
           .enum(['unplanned', 'planning', 'planned', 'failed'])
           .optional()
           .describe('Only items whose plan is in this state'),
+        state: z
+          .enum(INITIATIVE_STATES)
+          .optional()
+          .describe(
+            'Only items in this column of the board: backlog, todo, queue, plan, build, done or canceled (status groups them coarser)'
+          ),
         category: z.enum(['feature', 'bug', 'tech_debt', 'improvement']).optional().describe('Only this category'),
         includeArchived: z.boolean().optional().describe('Include archived items (default false)'),
         ...pagination,
@@ -336,7 +340,29 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const { query, ...filters } = params;
+        const { query, state, ...filters } = params;
+        // The API filters by status only; a board column is read across pages here (PRO-2800).
+        if (state !== undefined) {
+          if (params.cursor !== undefined) {
+            return toolError(
+              'VALIDATION_ERROR',
+              'A board-column filter answers one page; narrow it with status or query.'
+            );
+          }
+          const found = await searchPages(
+            (cursor) => client.listBacklogItems(params.productId, { ...filters, limit: SEARCH_PAGE_SIZE, cursor }),
+            query ?? '',
+            (row) => [row.title],
+            params.limit ?? 25,
+            (row) => row.state === state
+          );
+          return toolResult({
+            ...page(situatedRows(found.rows), null),
+            ...(found.more
+              ? { more: 'More items may be in that column: narrow it with status or query, or raise the limit.' }
+              : {}),
+          });
+        }
         if (query === undefined) {
           const result = await client.listBacklogItems(params.productId, filters);
           return toolResult(page(situatedRows(result.data as Record<string, unknown>[]), result.nextCursor));
@@ -362,11 +388,9 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     {
       title: 'Get initiative',
       description:
-        'Get one initiative in full: description, acceptance criteria (and which are met), technical ' +
-        'context (patterns, constraints, and the assumptions to verify before starting), dependencies and source documents. Read this before ' +
-        'implementing an item, and read its runs with taiga_list_runs to see what the coding agent already did. ' +
-        'A failed plan carries planFailure: the cause, what it means, when, and by whom. ' +
-        LIFECYCLE_MEANING,
+        'Read one initiative in full: description, acceptance criteria (which are met), technical context, ' +
+        'dependencies and source documents. Read it before implementing. A failed plan carries planFailure ' +
+        `(cause, meaning, when, by whom). ${LIFECYCLE_MEANING}`,
       inputSchema: z.object({
         initiativeId,
       }),
@@ -390,12 +414,11 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     {
       title: 'Get the active plan',
       description:
-        "Get an initiative's active plan with its steps, in order: each step's title, layer, dependencies " +
-        '(the orderIndex of the steps it builds on), the files it writes and reads and the resources it creates. ' +
-        'That is enough to ' +
-        'approve or reject it (taiga_approve_plan, taiga_reject_plan) and to say what a run will do; pass ' +
-        "full: true for each step's complete instructions, several thousand tokens on a large plan. NOT_FOUND " +
-        'when the initiative has no active plan yet (planningStatus says whether one is being generated).',
+        "Read an initiative's active plan: its steps in order, each with title, layer, dependencies (the " +
+        'orderIndex of the steps it builds on), files written and read, and resources created. Enough to approve ' +
+        "or reject it (taiga_approve_plan, taiga_reject_plan); full: true adds each step's complete instructions " +
+        '(thousands of tokens). NOT_FOUND when there is no active plan yet; planningStatus says whether one is ' +
+        'being generated.',
       inputSchema: z.object({
         initiativeId,
         full: z.boolean().optional().describe("Carry each step's complete instructions (default false: a summary)"),
@@ -421,18 +444,11 @@ function registerRequest(server: McpServer, client: TaigaClient) {
     {
       title: 'Request new initiatives',
       description:
-        'Add work the way Taiga adds it: describe it, and an agent turns the request into initiatives in the ' +
-        "product's Backlog. The agent reads the product documents and its repository, expands the request into a " +
-        'full brief, and sizes it: one piece of work stays one initiative, a program of work comes back as an ordered ' +
-        'set with its dependencies linked. It can also add nothing, and says why: an existing initiative already ' +
-        'covers the request, the request is not readable as work, it is outside what the product builds, or one of ' +
-        "the organization's policies does not allow it as asked (named, with the line it runs into and the way to " +
-        'decide otherwise). Leave both title and description out and the agent suggests the one next initiative the ' +
-        'product most needs. It runs in the background, a few minutes: this returns the job, and taiga_wait_for_job ' +
-        'or taiga_get_job (both need products:read) say what came of it. One request per product at a time ' +
-        '(CONFLICT while one runs). Inline images in the description are left out; the web is where a request ' +
-        'carries images. It starts nothing on the line: new initiatives land in Backlog. Runs an agent; ask the ' +
-        'person first.',
+        "Ask an agent to turn described work into initiatives in the product's Backlog, and return the job. One " +
+        'piece of work becomes one initiative, a program an ordered set with dependencies. It may add none and ' +
+        'say why (already covered, not work, outside the product, or a named policy forbids it). Omit title and ' +
+        'description for the one next initiative the product most needs. taiga_wait_for_job gives the outcome. ' +
+        'One request per product at a time (CONFLICT). Nothing goes on the line.',
       inputSchema: z.object({
         productId,
         title: z.string().max(500).optional().describe('What the work is, in a line'),
@@ -466,17 +482,13 @@ function registerMove(server: McpServer, client: TaigaClient) {
     {
       title: 'Move initiative on the board',
       description:
-        'Move an initiative on the board, take it off the line, or order it within a column: backlog and todo are yours and the line ' +
-        'never moves an initiative out of them; queue puts it in the line (taiga_queue_initiative says more); ' +
-        'done and canceled finish it by hand. The queue is the only way to start work: there is no "plan this ' +
-        'now", and nothing is moved into Build by a person. Moving an initiative out of Build stops the plan ' +
-        'being written or the run in flight: that is how work is stopped, and it throws that work away. A move to ' +
-        `${PR_CLOSING_STATES.join(', ')} CLOSES a pull request the initiative is still waiting on (a move to queue ` +
-        'keeps it, and done leaves it to be merged); Taiga leaves a comment on the pull request saying why. The ' +
-        'state machine refuses a move that is not allowed (CONFLICT). A move into queue starts paid work and ' +
-        'needs products:write. Ask the person before a move that starts work, stops work or closes a pull request. ' +
-        'archived: true files the initiative where it stands (pass its current column as state; never from the Build station, plan or build) ' +
-        'and archived: false brings it back; archived work is left out of lists unless includeArchived asks for it.',
+        'Move an initiative between columns, take it off the line, or reorder it. The line never takes from ' +
+        'backlog or todo; queue puts it on the line (taiga_queue_initiative), the only way to start work; done ' +
+        'and canceled finish it by hand. Nothing moves into Build by hand; moving out of Build stops and ' +
+        `discards the plan or run in flight. A move to ${PR_CLOSING_STATES.join(', ')} CLOSES a pull request the ` +
+        'initiative waits on (with a comment on it); queue keeps it open, and done leaves it to merge. Refused (CONFLICT) if not allowed; queue needs products:write. Ask first before ' +
+        'starting or stopping work or closing a pull request. archived: true archives it in place (pass its ' +
+        'current column as state; never from the Build station); false restores it.',
       inputSchema: z.object({
         initiativeId,
         state: z.enum(USER_DROP_STATES).describe('The column to move into'),
@@ -517,14 +529,11 @@ function registerPlanAgain(server: McpServer, client: TaigaClient) {
     {
       title: 'Plan an initiative again',
       description:
-        'Supersede the plan of the initiative at the Build station and ask the planner for a new one: for a plan ' +
-        'that failed, a plan you do not want built, or a run whose direction was wrong once it has stopped. The ' +
-        'earlier plan is kept, and every run records which plan version it built; a pull request still open ' +
-        'stays open. Offered only when the turn is yours: refused (CONFLICT) while an agent holds it (planning, ' +
-        'building, reviewing). Also refused while a dependency is still in flight or a UI direction has no ' +
-        'chosen concept, unless force says to plan anyway, which only the person decides. Anywhere off the ' +
-        'Build station, put the initiative in the queue instead (taiga_queue_initiative): the queue is the ' +
-        'only way to start work. To send a plan back with direction, taiga_reject_plan. Starts a planner run.',
+        'Replace the plan of the initiative at the Build station with a new one: for a failed plan, one you do ' +
+        'not want built, or a stopped run that went wrong. The old plan is kept; an open pull request stays ' +
+        'open. Refused (CONFLICT) while an agent holds the turn, and while a dependency is in flight or a UI ' +
+        'direction has no chosen concept unless force is set (the person decides). Off the Build station, use ' +
+        'taiga_queue_initiative; to send a plan back with direction, taiga_reject_plan.',
       inputSchema: z.object({
         initiativeId,
         force: z
@@ -607,15 +616,12 @@ function registerQueue(server: McpServer, client: TaigaClient) {
     {
       title: 'Queue initiative',
       description:
-        'Add an initiative to the product queue, the line the coding agent works: queued initiatives are ' +
-        'planned and built one at a time, each advancing when the previous pull request merges. This starts ' +
-        'paid work: a planner run, then a coding run that pushes commits and opens a pull request in the product ' +
-        "repository. Whether the plan is built at once or waits for a person is the initiative's review gate: " +
-        "pass autoBuild: false to read the plan before anything is built (the product's default applies " +
-        'otherwise, and the outcome says which it is); the gate is set first and stays set if the move is then ' +
-        'refused. An initiative already ' +
-        'in the queue stays where it is unless afterId says where to go; one being planned or built cannot move ' +
-        '(CONFLICT). Returns the initiative with its new state, its review gate and its place in the queue.',
+        "Put an initiative on the product's line, where initiatives are planned and built one at a time, each " +
+        'advancing when the previous pull request merges. Starts a planner run, then a coding run that pushes ' +
+        'commits and opens a pull request. autoBuild: false makes the plan wait for a person before it is built ' +
+        '(otherwise the product default; the result says which); the gate is set first and stays set if the move ' +
+        'is refused. An initiative already queued stays put unless afterId says where; one being planned or ' +
+        'built cannot move (CONFLICT). Returns the initiative with its state, review gate and place on the line.',
       inputSchema: z.object({
         initiativeId,
         afterId: idInput('initiative', 'taiga_list_initiatives gives it')
@@ -661,10 +667,10 @@ function registerReviewGate(server: McpServer, client: TaigaClient) {
     {
       title: "Set an initiative's review gate",
       description:
-        "Set whether an initiative's plan is built as soon as it lands (true) or waits for a person to read it and " +
-        "approve or reject it (false); null follows the product's default. Standing: it applies to every plan the " +
-        'initiative gets, including one being written now. Opening the gate on a plan that is already waiting ' +
-        'starts its build at once. Returns the initiative with the gate that now applies.',
+        "Set an initiative's review gate: true builds each plan as soon as it lands, false makes it wait for a " +
+        'person to approve or reject it, null follows the product default. Applies to every plan the initiative ' +
+        'gets, including one being written now; opening the gate on a plan already waiting starts its run at ' +
+        'once. Returns the initiative with the gate now in force.',
       inputSchema: z.object({ initiativeId, autoBuild: autoBuildInput }),
       annotations: OPERATE_SETTING,
     },
@@ -687,13 +693,11 @@ function registerResume(server: McpServer, client: TaigaClient) {
     {
       title: 'Resume initiative',
       description:
-        'Carry on an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a ' +
-        'failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished ' +
-        'part (the steps already committed are kept), a refused build start is cleared and retried. This is the ' +
-        'way to carry work on: a run is the record of an attempt, and decisions about the work are made on the ' +
-        'initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume: a plan that failed ' +
-        'with needsHumanCause null (lifecycle.cta retry_plan, planFailureCause says why) is planned again with ' +
-        'taiga_plan_again. Starts paid work.',
+        'Carry on an initiative the line stopped on (needsHumanCause is set): a failed or cancelled plan is ' +
+        'planned again, a stopped or failed run resumes from its first unfinished step (committed steps are ' +
+        'kept), a refused run start is cleared and retried. Refused (CONFLICT) when nothing is flagged or the ' +
+        'cause has no resume; a failed plan with needsHumanCause null (lifecycle.cta retry_plan, ' +
+        'planFailureCause says why) needs taiga_plan_again.',
       inputSchema: z.object({ initiativeId }),
       annotations: OPERATE,
     },
@@ -707,10 +711,9 @@ function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
     {
       title: 'Approve a plan',
       description:
-        "Approve an initiative's plan: its build starts now, as the approver, the same start the Start run " +
-        'button makes. Read the plan first with taiga_get_plan and name its ID; an approval of a plan that ' +
-        'was replaced since is refused (CONFLICT), as is one while a new plan is being generated or a build is ' +
-        'already running. Starts a coding run that pushes commits and opens a pull request.',
+        "Approve an initiative's plan and start its run, as the Start run button does. Read the plan first with " +
+        'taiga_get_plan and pass its ID. Refused (CONFLICT) if the plan was replaced since, while a new plan is ' +
+        'being generated, or while a run is already going. The run pushes commits and opens a pull request.',
       inputSchema: z.object({ planId }),
       annotations: OPERATE,
     },
@@ -722,9 +725,9 @@ function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
     {
       title: 'Reject a plan',
       description:
-        "Send an initiative's plan back with direction: a new plan is generated with the comment as reviewer " +
-        'feedback and the rejected plan as its starting point, which supersedes it when the new one lands. ' +
-        'Read the plan first with taiga_get_plan and name its ID. Starts a planner run.',
+        "Send an initiative's plan back with a comment: the planner writes a new plan from it, with the comment " +
+        'as reviewer feedback, and the new plan replaces this one when it lands. Read the plan first with ' +
+        'taiga_get_plan and pass its ID. Starts a planner run.',
       inputSchema: z.object({
         planId,
         comment: z

package/src/tools/builds.ts

@@ -160,10 +160,10 @@ export function handbackSaid(escalation: unknown): string | null {
 /** What a person does about a handback, by its reason, as the web's handback detail says it. */
 export function handbackNextStep(escalation: unknown): string {
   const reason = escalation && typeof escalation === 'object' ? (escalation as { reason?: unknown }).reason : null;
-  if (reason === 'check_weakened') return 'review the loosened check before merging, or review it back to the agent';
+  if (reason === 'check_weakened') return 'review the loosened check on GitHub before merging';
   if (reason === 'ci_never_settled')
-    return 'look at what is still running or queued in CI, then review it back to the agent';
-  return 'fix it by hand or review it back to the agent';
+    return 'look at what is still running or queued in CI on GitHub, then review the pull request';
+  return 'fix it by hand, or review the pull request on GitHub, which hands it back to the agent';
 }
 
 /** The web's words for why Taiga keeps a pull request a draft. */
@@ -243,6 +243,72 @@ export function readableRun(run: Record<string, unknown>, opts: { row?: boolean
   };
 }
 
+/** Distinct initiatives a run list reads to say which moved on; past this a waiting row says it was not checked. */
+const INITIATIVE_CHECKS = 10;
+
+/**
+ * The status of the initiative behind each run still waiting on its pull
+ * request (PRO-2800). A reviewing agent read a run of a canceled initiative as
+ * "waiting for a person to review and merge" while Action Required called the
+ * same review stale. A 404 is 'deleted'. Best effort: an initiative past the
+ * cap, one whose read failed, and every one without backlog:read is
+ * 'unchecked', which withInitiativeState adds to the row's outcome.
+ */
+export async function initiativeStates(
+  client: TaigaClient,
+  rows: Record<string, unknown>[]
+): Promise<Map<string, string>> {
+  const states = new Map<string, string>();
+  // Only the runs that could still be waiting: a settled run's initiative changes nothing about it.
+  const waiting = rows.filter(
+    (row) => ['needs_review', 'completed'].includes(String(row['status'])) && row['prMerged'] !== true
+  );
+  const all = [
+    ...new Set(waiting.map((row) => row['backlogItemId']).filter((id): id is string => typeof id === 'string')),
+  ];
+  // Without backlog:read, or past the cap, a waiting run's initiative is not read: it is marked unchecked so
+  // the row does not claim a person is waiting when nobody may be.
+  const ids = client.hasCapability('backlog:read') ? all.slice(0, INITIATIVE_CHECKS) : [];
+  for (const id of all) if (!ids.includes(id)) states.set(id, 'unchecked');
+  await Promise.all(
+    ids.map(async (id) => {
+      try {
+        const item = (await client.getBacklogItem(id)).data as unknown as Record<string, unknown>;
+        states.set(id, String(item['status'] ?? item['state']));
+      } catch (error) {
+        if (error instanceof TaigaApiError && error.status === 404) return void states.set(id, 'deleted');
+        if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
+        states.set(id, 'unchecked');
+      }
+    })
+  );
+  return states;
+}
+
+/** A readable run row that also says when its initiative was canceled or deleted while its pull request waited. */
+export function withInitiativeState(
+  row: Record<string, unknown>,
+  states: Map<string, string>
+): Record<string, unknown> {
+  const state = states.get(String(row['backlogItemId']));
+  // A run still executing is left as it is: its initiative's cancel stops it, and one still going after that is
+  // what taiga_stop_run is for.
+  if (!['gated', 'unmerged'].includes(String(row['disposition']))) return row;
+  if (state === 'unchecked') {
+    return { ...row, outcome: `${String(row['outcome'])} Whether its initiative still wants it was not checked.` };
+  }
+  if (state !== 'canceled' && state !== 'deleted') return row;
+  const pr = typeof row['prNumber'] === 'number' ? `PR #${row['prNumber']}` : 'its pull request';
+  const open = row['prState'] === 'open' ? ` ${pr} is still open on the forge.` : '';
+  return {
+    ...row,
+    disposition: 'abandoned',
+    // Retry or start over cannot succeed once the initiative is gone.
+    actions: [],
+    outcome: `Its initiative was ${state}, so nobody is waiting on this run.${open}`,
+  };
+}
+
 /** readableRun for a list row. */
 export const readableRow = (run: Record<string, unknown>) => readableRun(run, { row: true });
 
@@ -304,8 +370,10 @@ async function activityRows(
   for (const product of products?.data ?? []) {
     nameById.set(product.id, { name: product.name, slug: product.slug });
   }
+  const states = await initiativeStates(client, runs.data as Record<string, unknown>[]);
   const rows = pickFields(runs.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS)
     .map(readableRow)
+    .map((row) => withInitiativeState(row, states))
     .map((row) => {
       const product = nameById.get(String(row['productId']));
       return product ? { ...row, product } : row;
@@ -332,14 +400,11 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     {
       title: 'List runs',
       description:
-        "List the coding agent's runs, newest first. A run is one attempt at building an initiative: its branch, " +
-        'pull request and step progress. Each row says how it stands in one sentence (outcome) and as a ' +
-        'disposition: in_flight (the agent is working), gated (a person owes a review and merge), succeeded ' +
-        '(merged), failed, stopped, rejected (the pull request was closed without merging) or unmerged. actions ' +
-        'name what a person may do with it. With productId, the runs of that product, optionally of one ' +
-        'initiative; without it, the runs of every product the key can see, each row naming its product, and ' +
-        'active: true narrows to the runs executing now. taiga_get_run reads one with its steps. Work is carried ' +
-        'on from the initiative (taiga_resume_initiative), not the run.',
+        'List coding agent runs, newest first: branch, pull request, step progress, outcome (one sentence), ' +
+        'actions and disposition: in_flight, gated (a person owes a review and merge), succeeded (merged), ' +
+        'failed, stopped, rejected (pull request closed unmerged), unmerged, or abandoned (initiative canceled ' +
+        "or deleted). Without productId, every product's runs; active: true keeps running ones. taiga_get_run " +
+        'reads one; carry work on from the initiative (taiga_resume_initiative).',
       inputSchema: z.object({
         productId: productId.optional(),
         initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it')
@@ -378,9 +443,13 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
             limit: params.limit,
             cursor: params.cursor,
           });
+          const raw = result.data as Record<string, unknown>[];
+          const states = await initiativeStates(client, raw);
           return toolResult(
             page(
-              pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS).map(readableRow),
+              pickFields(raw, BUILD_SUMMARY_FIELDS)
+                .map(readableRow)
+                .map((row) => withInitiativeState(row, states)),
               result.nextCursor
             )
           );
@@ -394,15 +463,13 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get run',
       description:
-        'Read one run with its steps: how it stands (outcome, disposition), its pull request and hardening, and ' +
-        "each step's title, status, commit, files changed, verification and headline, the first paragraph of " +
-        "what the agent reported. A step's verification is Taiga's own check after the step (tests, lint, build), " +
-        'independent of what the agent says it ran: a docs-only step can show tests failed because the ' +
-        "repository's tests fail. A run that failed or was stopped says where (stoppedIn) and when it last made " +
-        "progress (lastProgressAt). Pass full: true for each step's complete instructions and report, several " +
-        'thousand tokens on a long run. Its actions name what the initiative accepts: resume and ' +
-        'retry_from_failed_step are taiga_resume_initiative; start_over is in the web only; to stop it, move the ' +
-        'initiative out of Build. A maintenance run has no initiative and is retried from its finding.',
+        'Read one run with its steps: outcome, disposition, pull request, hardening, and per step its title, ' +
+        "status, commit, files changed, verification and headline (first paragraph of the agent's report). " +
+        "verification is Taiga's own check after the step (tests, lint, build), so a docs-only step can fail on " +
+        "the repository's failing tests. A failed or stopped run has stoppedIn and lastProgressAt. full: true " +
+        'adds complete instructions and reports. actions: resume and retry_from_failed_step are ' +
+        'taiga_resume_initiative; start_over is web only; to stop it, move the initiative out of Build. A ' +
+        'maintenance run has no initiative and is retried from its finding.',
       inputSchema: z.object({
         runId,
         full: z
@@ -424,9 +491,11 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         const rows = steps.data;
         const where = stoppedIn(runRow, rows);
         const stop = where ? { stoppedIn: where } : {};
-        if (params.full) return toolResult({ ...readableRun(runRow), ...stop, steps: steps.data });
+        const states = await initiativeStates(client, [runRow as unknown as Record<string, unknown>]);
+        const readable = withInitiativeState(readableRun(runRow), states);
+        if (params.full) return toolResult({ ...readable, ...stop, steps: steps.data });
         return toolResult({
-          ...readableRun(runRow),
+          ...readable,
           ...stop,
           steps: pickFields(rows, STEP_SUMMARY_FIELDS).map((step, index) => ({
             ...step,
@@ -443,11 +512,10 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Stop a run',
       description:
-        'The emergency brake: stop a run the coding agent is executing when its initiative cannot be moved. The ' +
-        'way to stop work is on the initiative: move it out of Build (taiga_move_initiative), which stops the ' +
-        'plan or run in flight. Use this only for a run whose initiative does not offer that (it is finished, ' +
-        'canceled or gone) yet the run is still going. The agent halts, its branch and any draft pull request ' +
-        'stay. Only a run whose actions include stop; the API refuses the rest with CONFLICT.',
+        'Emergency stop for a run whose initiative cannot be moved out of Build (finished, canceled or gone) but ' +
+        'is still going. Normally stop work by moving the initiative out of Build with taiga_move_initiative. ' +
+        'The agent halts; its branch and any draft pull request stay. Only a run whose actions include stop; ' +
+        'others are refused (CONFLICT).',
       inputSchema: z.object({ runId }),
       annotations: OPERATE,
     },

package/src/tools/catalogue.test.ts

@@ -145,13 +145,7 @@ describe('tool descriptions against the catalogue', () => {
     // Claude Code loads only tool names and the instructions until the model
     // searches, and cuts the instructions at 2,048 characters (PRO-2800).
     expect(SERVER_INSTRUCTIONS.length).toBeLessThanOrEqual(SERVER_INSTRUCTIONS_LIMIT);
-    for (const must of [
-      'taiga_get_product_context',
-      'Before you write',
-      'NOT_FOUND',
-      'initiative',
-      'Only in the web',
-    ]) {
+    for (const must of ['taiga_get_product_context', 'ask-first', 'NOT_FOUND', 'initiative', 'Only in the web']) {
       expect(SERVER_INSTRUCTIONS).toContain(must);
     }
   });
@@ -167,6 +161,9 @@ describe('writeNotice', () => {
   it('says nothing for a read, and what a write does otherwise', () => {
     expect(writeNotice('r', { readOnlyHint: true })).toBe('');
     expect(writeNotice('w', { readOnlyHint: false })).toBe('Writes. ');
-    expect(writeNotice('o', { readOnlyHint: false, destructiveHint: true })).toMatch(/^Ask first: paid or shared work/);
+    expect(writeNotice('o', { readOnlyHint: false, destructiveHint: true })).toBe('Ask first (others see it). ');
+    expect(writeNotice('taiga_queue_initiative', { readOnlyHint: false, destructiveHint: true })).toBe(
+      'Ask first (paid agent work). '
+    );
   });
 });

package/src/tools/catalogue.ts

@@ -66,13 +66,10 @@ export function named(types: readonly string[]): string {
  * tool and the instructions cannot explain them three different ways.
  */
 export const ORIGIN_MEANING: Record<ProductDocumentOrigin, string> = {
-  plan:
-    'plan: the discovery documents, authored intent. Every greenfield product has them; ' +
-    'they say what is meant to be built.',
+  plan: 'plan: the discovery documents, what is meant to be built.',
   reality:
-    'reality: derived from the code on the main branch, what is actually built. A brownfield product ' +
-    'has them from its import; a greenfield product gets them once its first initiative is done (a ' +
-    'merged pull request marks it done) or the repository is pushed to, and they refresh as code lands.',
+    'reality: derived from the code on the main branch, what is built; an imported product has them from ' +
+    'its import, any other once its first initiative is done (a merged pull request) or code is pushed.',
 };
 
 /**
@@ -222,5 +219,5 @@ export function setupNextStep(
 /** What discoveryStep says, for a description that shows it. */
 export const DISCOVERY_STEP_MEANING =
   'discoveryStep is where a product in setup is: context (not started), conversation or import (the ' +
-  'specification is being talked out, or derived from the code), documents (the rest being generated and ' +
-  'reviewed), checks (stamped in the web); null once it is active.';
+  'specification being written or derived from code), documents (generated and reviewed), checks (stamped in ' +
+  'the web); null once it is active.';