@taiga-ai/mcp-server 0.18.0-dev.450 → 0.19.0-dev.451

package/src/tools/maintenance.ts

@@ -73,6 +73,31 @@ const VIOLATION_FIELDS = [
   'assessedAt',
 ] as const;
 
+type Row = Record<string, unknown>;
+
+/**
+ * How bad a product's policy standing is, as counts: the controls something is
+ * recorded against, the open violations by severity, the resolved ones. The
+ * API's standing carries the lists only; this tool and the product context
+ * both count them here.
+ */
+export function standingSummary(standing: {
+  controls?: unknown;
+  divergences?: unknown;
+  resolvedDivergences?: unknown;
+}): { controls: number; violations: number; bySeverity: Record<string, number>; resolvedViolations: number } {
+  const controls = Array.isArray(standing.controls) ? (standing.controls as Row[]) : [];
+  const violations = Array.isArray(standing.divergences) ? (standing.divergences as Row[]) : [];
+  const resolved = Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences.length : 0;
+  const listed = controls.filter((c) => Number(c['divergenceCount'] ?? 0) > 0 || Number(c['findingCount'] ?? 0) > 0);
+  const bySeverity: Record<string, number> = {};
+  for (const violation of violations) {
+    const severity = String(violation['severity'] ?? 'unknown');
+    bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
+  }
+  return { controls: listed.length, violations: violations.length, bySeverity, resolvedViolations: resolved };
+}
+
 const findingId = idInput('finding', 'taiga_list_findings gives it');
 
 export function registerMaintenanceTools(server: McpServer, client: TaigaClient) {
@@ -86,8 +111,9 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         "Where a product's repository stands: open findings by severity and kind, the most pressing ones, and " +
         'the latest sweeps, so you can tell when the product was last checked and whether that check succeeded. A ' +
         'quiet list from a sweep that last ran long ago, or that failed, is not an all-clear; a product never swept ' +
-        'says so. Sweeps run on their own after a push and periodically; nothing here starts one. Read the ' +
-        'findings with taiga_list_findings and the policy standing with taiga_get_policy_standing.',
+        'says so. Sweeps run on their own after a push and periodically; nothing here starts one. This is the ' +
+        'overview of the scanners alone; taiga_list_findings lists each finding to act on, and ' +
+        'taiga_get_policy_standing judges the product against the policies (scanner findings and the documents).',
       inputSchema: z.object({ productId }),
       annotations: READ_ONLY,
     },
@@ -120,8 +146,9 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         'severity and its priority tier (act_now: known exploited; urgent: likely and serious; elevated: one of ' +
         'the two; routine), where it is, who can fix it (remediableBy: coding_agent, or upstream_only for a ' +
         'submodule or a dependency with no fixed version), the policy controls it breaches, and the initiative ' +
-        'already fixing it (backlogItemId). Omit status for the findings that need action; work from the top tier ' +
-        'down. Read one in full with taiga_get_finding.',
+        'already fixing it (initiativeId). Omit status for the findings that need action; work from the top tier ' +
+        'down. Read one in full with taiga_get_finding. taiga_get_maintenance has the counts and when the last ' +
+        'sweep ran, which says whether an empty list can be trusted.',
       inputSchema: z.object({
         productId,
         status: z
@@ -157,7 +184,13 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
       inputSchema: z.object({ findingId }),
       annotations: READ_ONLY,
     },
-    (params) => runTool(async () => toolResult((await client.getFinding(params.findingId)).data))
+    (params) =>
+      runTool(async () => {
+        // The finding's runId is the sweep that found it, not a coding run:
+        // in the product's words runId is what taiga_get_run takes (PRO-2800).
+        const { runId, ...finding } = (await client.getFinding(params.findingId)).data as Row;
+        return toolResult(runId === undefined ? finding : { sweepId: runId, ...finding });
+      })
   );
 
   server.registerTool(
@@ -169,7 +202,11 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         "each with its violations (critical and high only, each citing the policy's sentence and the document " +
         'passage that contradicts it), what is being done about each (an initiative raised, a fix in progress, ' +
         'awaiting verification), and when the documents were derived and assessed, led by a summary of the ' +
-        'counts. A control breached by scanner findings counts them by tier (findingsByTier): a breach of ' +
+        'counts. A control is breached when open scanner findings map to it, diverged when the assessment of the ' +
+        'product documents found them contradicting it (a control can be both; state names the stronger, ' +
+        "breached). A violation's work is the initiative raised for it; live: false means that initiative is " +
+        'done or canceled without the violation going away, so it needs a person or a new fix. A control ' +
+        'breached by scanner findings counts them by tier (findingsByTier): a breach of ' +
         'routine findings only, such as secrets in test fixtures, is not an urgent one. A control with no violation ' +
         'is not listed, and it is not "passing" either: there is no such state. Pass full: true for every ' +
         "violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
@@ -187,21 +224,10 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         const standing = (await client.getPolicyStanding(params.productId)).data;
         const controls = Array.isArray(standing.controls) ? standing.controls : [];
         const violations = Array.isArray(standing.divergences) ? standing.divergences : [];
-        const resolved = Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences.length : 0;
         const listed = controls.filter((c) => Number(c.divergenceCount ?? 0) > 0 || Number(c.findingCount ?? 0) > 0);
-        const bySeverity: Record<string, number> = {};
-        for (const violation of violations) {
-          const severity = String(violation.severity ?? 'unknown');
-          bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
-        }
         // The counts first, on both answers: the lists run to thousands of
         // tokens, and "how bad is it" is the first question.
-        const summary = {
-          controls: listed.length,
-          violations: violations.length,
-          bySeverity,
-          resolvedViolations: resolved,
-        };
+        const summary = standingSummary(standing);
         if (params.full) return toolResult({ summary, ...standing });
         return toolResult({
           summary,

package/src/tools/product-documents.ts

@@ -93,7 +93,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
         "Publish a product document's draft as its new version, the one agents work from. Documents generated " +
         'from it are not rewritten: each is marked outdated, and is regenerated when someone chooses to ' +
         '(taiga_regenerate_product_document, or taiga_generate_product_documents for every outdated and missing ' +
-        'one). Ask the person before publishing.',
+        'one).',
       inputSchema: z.object({ productId, type: documentType }),
       annotations: OPERATE,
     },

package/src/tools/products.ts

@@ -15,12 +15,12 @@ import {
   isImportedProduct,
   productDocumentName,
   type ProductDocumentOrigin,
-  setupNextStep,
   type ProductSettingsView,
 } from './catalogue.js';
 import { apiFailureCode, apiFailureText, isMissOrRefusal, runTool, toolError, toolResult } from './errors.js';
 import { parseRemote } from './remote.js';
 import { sectionReadResult, sectionsInput, stripProvenance } from './sections.js';
+import { setupReadiness } from './readiness.js';
 import { SEARCH_NOTE, SEARCH_PAGE_SIZE, SEARCH_WITH_CURSOR, page, pickFields, searchPages } from './summarize.js';
 
 type ProductRow = WithoutTenant<Product>;
@@ -377,8 +377,10 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           '(application, infrastructure, deployment) and its settings; the list and resolve tools carry ' +
           'summaries; taiga_get_product_context carries this summary with the rest a session starts from. Use ' +
           'taiga_list_product_documents for its specification and design, ' +
-          'taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did. A product ' +
-          'still in setup carries nextStep: what it waits for and the call that moves it on.',
+          'taiga_list_initiatives for its work and taiga_list_runs for what the coding agent did. A product ' +
+          'still in setup carries readiness: whether it can finish setup now, its repository and import, the ' +
+          'required documents not yet published, the checks not yet stamped, and nextStep, the one move that ' +
+          'gets it closer.',
         inputSchema: z.object({
           productId: productId.optional(),
           slug: slug.optional(),
@@ -389,8 +391,8 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
         runTool(async () => {
           const resolved = await resolveProductRef(client, params, ['productId', 'slug']);
           if ('refusal' in resolved) return toolError(resolved.refusal.code, resolved.refusal.message);
-          const nextStep = setupNextStep(resolved.product);
-          return toolResult(nextStep ? { ...resolved.product, nextStep } : resolved.product);
+          const readiness = await setupReadiness(client, resolved.product);
+          return toolResult(readiness ? { ...resolved.product, readiness } : resolved.product);
         })
     );
 

package/src/tools/prompts.ts

@@ -97,7 +97,7 @@ export function registerPrompts(server: McpServer, client: TaigaClient) {
             '',
             'Before writing code: follow the factory instructions; read the policy sections that touch what you are',
             'about to change with taiga_get_document (security, data, SDLC, architecture at least); read the backlog',
-            'item you are implementing with taiga_get_backlog_item. Parts listed under notGranted or unavailable',
+            'item you are implementing with taiga_get_initiative. Parts listed under notGranted or unavailable',
             'could not be read; say so rather than assuming they are empty.',
             '',
             fenced('json', bundle),
@@ -109,22 +109,22 @@ export function registerPrompts(server: McpServer, client: TaigaClient) {
 
   if (client.hasCapability('backlog:read') && client.hasCapability('products:read')) {
     server.registerPrompt(
-      'taiga_implement_backlog_item',
+      'taiga_implement_initiative',
       {
-        title: 'Implement a backlog item',
+        title: 'Implement an initiative',
         description:
           'Implement one initiative: its description and acceptance criteria, the architecture of the product ' +
           "from its own timeline, the factory's instructions and the policy sections to check against. " +
-          'taiga_list_backlog_items gives the item ID.',
+          'taiga_list_initiatives gives the item ID.',
         argsSchema: z.object({
-          itemId: idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it'),
+          initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it'),
         }),
       },
       async (args) => {
         const item = (
           await served(
-            client.getBacklogItem(args.itemId),
-            'No backlog item with that ID the key can see; taiga_list_backlog_items shows what exists'
+            client.getBacklogItem(args.initiativeId),
+            'No initiative with that ID the key can see; taiga_list_initiatives shows what exists'
           )
         ).data;
         const productId = String(item.productId);

package/src/tools/queue.ts

@@ -16,7 +16,7 @@ import { isNetworkFailure, runTool, toolResult } from './errors.js';
 import { productId } from './inputs.js';
 import { criteriaCounts } from './summarize.js';
 
-/** How many entries the read names; past this an entry keeps its backlogItemId only. */
+/** How many entries the read names; past this an entry keeps its initiativeId only. */
 const NAMED_ENTRIES = 25;
 
 /** One queue entry as the read reports it: where it sits, and its initiative when that could be named. */
@@ -30,13 +30,13 @@ interface QueueRow {
   needsHumanCause?: BacklogItem['needsHumanCause'];
   criteria?: { met: number; total: number } | null;
   lifecycle?: Pick<BacklogItemLifecycle, 'turn' | 'stage' | 'cta'> | null;
-  buildId?: string;
+  runId?: string;
   prUrl?: string | null;
   halt?: { cause: string | null; reason: string; nextStep: string };
 }
 
 const MOVE_ASIDE =
-  'or move it down (taiga_queue_backlog_item with afterId) or off the line (taiga_move_backlog_item) to let the rest pass.';
+  'or move it down (taiga_queue_initiative with afterId) or off the line (taiga_move_initiative) to let the rest pass.';
 
 /**
  * What lifts a halt, in the tools that do it. Read from the halt registry in
@@ -49,11 +49,11 @@ function haltNextStep(cause: string | null): string {
     return 'Read the plan with taiga_get_plan, then approve it (taiga_approve_plan) or send it back (taiga_reject_plan).';
   }
   const spec = cause ? (HALT_CAUSES as Record<string, { clearedWhen: string } | undefined>)[cause] : undefined;
-  if (!cause || !spec) return `Read the initiative with taiga_get_backlog_item to see why, ${MOVE_ASIDE}`;
+  if (!cause || !spec) return `Read the initiative with taiga_get_initiative to see why, ${MOVE_ASIDE}`;
   const known = cause as HaltCause;
-  if (canResumeHalt(known)) return `taiga_resume_backlog_item lifts it, ${MOVE_ASIDE}`;
+  if (canResumeHalt(known)) return `taiga_resume_initiative lifts it, ${MOVE_ASIDE}`;
   if (haltClearsItself(known)) return `It clears when ${spec.clearedWhen}; ${MOVE_ASIDE}`;
-  return `Only taking it off the line clears it (taiga_move_backlog_item): ${spec.clearedWhen}.`;
+  return `Only taking it off the line clears it (taiga_move_initiative): ${spec.clearedWhen}.`;
 }
 
 /**
@@ -143,7 +143,7 @@ export async function queueView(
         needsHumanCause: item.needsHumanCause,
         criteria: criteriaCounts(item),
         lifecycle: lifecycle ? { turn: lifecycle.turn, stage: lifecycle.stage, cta: lifecycle.cta } : null,
-        ...(latestBuild ? { buildId: latestBuild.id, prUrl: latestBuild.prUrl ?? null } : {}),
+        ...(latestBuild ? { runId: latestBuild.id, prUrl: latestBuild.prUrl ?? null } : {}),
       } satisfies Partial<QueueRow>);
     }
     if (entry.state === 'halted') {
@@ -163,10 +163,10 @@ export async function queueView(
     unnamed === 0
       ? null
       : !canName
-        ? 'Entries carry backlogItemId only: naming them needs backlog:read, which this key lacks.'
+        ? 'Entries carry initiativeId only: naming them needs backlog:read, which this key lacks.'
         : entries.length > NAMED_ENTRIES
-          ? `Only the first ${NAMED_ENTRIES} entries are named; the rest carry backlogItemId only.`
-          : 'An entry whose initiative could not be read carries backlogItemId only; taiga_get_backlog_item reads it.';
+          ? `Only the first ${NAMED_ENTRIES} entries are named; the rest carry initiativeId only.`
+          : 'An entry whose initiative could not be read carries initiativeId only; taiga_get_initiative reads it.';
   // A paused line answers before anything in it: nothing is planned or built until it is resumed.
   const line =
     typeof paused === 'string'
@@ -198,7 +198,7 @@ export function registerQueueTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
   server.registerTool(
-    'taiga_get_queue',
+    'taiga_get_line',
     {
       title: 'Get the product queue',
       description:
@@ -226,7 +226,7 @@ export function registerQueueTools(server: McpServer, client: TaigaClient) {
         'keep their places. Resuming plans the interrupted initiative again from scratch, carries the interrupted ' +
         'build on from its first incomplete step, and the line picks up where it was; a build you had stopped ' +
         'yourself before pausing stays stopped. Idempotent. Pausing interrupts work and resuming starts it: read ' +
-        'taiga_get_queue first to see what it would interrupt, and ask the person.',
+        'taiga_get_line first to see what it would interrupt, and ask the person.',
       inputSchema: z.object({
         productId,
         paused: z.boolean().describe('true pauses the line, false resumes it'),

package/src/tools/readiness.ts

@@ -0,0 +1,172 @@
+import { TaigaApiError, type TaigaClient } from '../client.js';
+import { PRODUCT_DOCUMENT_NAMES, isImportedProduct, setupNextStep, type ProductSettingsView } from './catalogue.js';
+import { isNetworkFailure } from './errors.js';
+
+type Row = Record<string, unknown>;
+
+/**
+ * What a product in setup still needs, read rather than learned from a
+ * refused write (PRO-2800). A reviewing agent linked a repository and picked
+ * a branch, and every read still said "link its repository": nextStep read
+ * the Discovery step alone, and the only way to see the missing documents was
+ * to call taiga_finish_discovery and read its refusal. This reads the same
+ * preconditions the API refuses on (GET /products/:id/setup), the linked
+ * repositories and the import, and says the one next move.
+ */
+export interface Readiness {
+  /** Whether taiga_finish_discovery would succeed now. Null when the API could not say. */
+  ready: boolean | null;
+  /** Null when the links could not be read: not the same as none linked. */
+  repository: { linked: false } | { linked: true; name: unknown; branch: unknown } | null;
+  /** An imported product's import: not started, running, complete, failed. */
+  import?: string;
+  discoveryStep?: unknown;
+  /** The required documents not yet published, by name; null when the API could not say. */
+  missingDocuments: string[] | null;
+  /** The required checks not yet stamped (stamped in the web); null when the API could not say. */
+  openChecks: string[] | null;
+  /** The one move that gets it closer; null when too little could be read to say. */
+  nextStep: string | null;
+}
+
+const IMPORT_STATE: Record<string, string> = {
+  pending: 'not started',
+  analyzing: 'running',
+  generating_docs: 'running',
+  complete: 'complete',
+  failed: 'failed',
+  cancelled: 'failed',
+};
+
+/** A failure that is the API's (refused, missing, unreachable), not a bug in this code. */
+function isApiSide(error: unknown): boolean {
+  return error instanceof TaigaApiError || isNetworkFailure(error);
+}
+
+/** The documents by the names the web uses. */
+function named(types: string[]): string {
+  return types.map((type) => PRODUCT_DOCUMENT_NAMES[type as keyof typeof PRODUCT_DOCUMENT_NAMES] ?? type).join(', ');
+}
+
+/** The product's setup readiness, or null once it has finished setup. */
+export async function setupReadiness(client: TaigaClient, product: Row): Promise<Readiness | null> {
+  if (product['status'] !== 'draft') return null;
+  const id = String(product['id']);
+  const imported = isImportedProduct(product as ProductSettingsView);
+  const [repos, blockers, full] = await Promise.all([
+    client.listProductRepositories(id).then(
+      (result) => result.data as Row[],
+      (error: unknown) => {
+        if (isApiSide(error)) return null;
+        throw error;
+      }
+    ),
+    // An API from before the read answers 404 to it: fall back to the step.
+    client.getProductSetupBlockers(id).then(
+      (result) => result.data,
+      (error: unknown) => {
+        if (isApiSide(error)) return null;
+        throw error;
+      }
+    ),
+    // A write's answer carries no discoveryStep; the read derives it.
+    'discoveryStep' in product || imported
+      ? Promise.resolve(product)
+      : client.getProduct(id).then(
+          (result) => result.data as Row,
+          (error: unknown) => {
+            if (isApiSide(error)) return product;
+            throw error;
+          }
+        ),
+  ]);
+
+  const link = repos?.[0];
+  const repository = !repos
+    ? null
+    : link
+      ? { linked: true as const, name: link['repositoryName'], branch: link['effectiveBranch'] }
+      : { linked: false as const };
+  const settings = (product['settings'] ?? {}) as { importStatus?: unknown };
+  const importState = imported ? (IMPORT_STATE[String(settings.importStatus)] ?? 'not started') : undefined;
+  const missing = blockers ? blockers.missingDocuments : null;
+  const openChecks = blockers ? blockers.openChecks.map((check) => check.criterion) : null;
+  // What the API refuses on, nothing else: a running import is in nextStep, not a blocker.
+  const ready = blockers ? missing!.length === 0 && openChecks!.length === 0 : null;
+
+  return {
+    ready,
+    repository,
+    ...(importState ? { import: importState } : {}),
+    ...(imported ? {} : { discoveryStep: full['discoveryStep'] ?? null }),
+    missingDocuments: missing ? missing.map((type) => named([type])) : null,
+    openChecks,
+    nextStep: nextStepFor({
+      imported,
+      importState,
+      linked: repository?.linked ?? null,
+      missing,
+      openChecks,
+      product: full,
+    }),
+  };
+}
+
+function nextStepFor(state: {
+  imported: boolean;
+  importState: string | undefined;
+  /** Null when the links could not be read. */
+  linked: boolean | null;
+  missing: string[] | null;
+  openChecks: string[] | null;
+  product: Row;
+}): string | null {
+  const finish =
+    'taiga_finish_discovery opens the product and locks its documents (ask the person: it is their decision ' +
+    'that the documents are right).';
+  if (state.imported) {
+    if (state.linked === false) {
+      return 'Link its repository (taiga_list_linkable_repositories, then taiga_link_repository), then taiga_start_import.';
+    }
+    if (state.linked === null && state.importState === 'not started')
+      return setupNextStep(state.product as ProductSettingsView);
+    switch (state.importState) {
+      case 'running':
+        return 'The import is running and derives the documents from the code; taiga_wait_for_job follows it.';
+      case 'failed':
+        return 'The last import did not finish: taiga_start_import runs it again.';
+      case 'complete':
+        if (state.missing && state.missing.length > 0) {
+          return (
+            `The import finished but ${named(state.missing)} ${state.missing.length === 1 ? 'is' : 'are'} not ` +
+            'published: taiga_list_product_documents shows them, taiga_publish_product_document publishes a draft.'
+          );
+        }
+        return `The import is done: review the reality documents (taiga_list_product_documents), then ${finish}`;
+      default:
+        return 'taiga_start_import derives the documents from the code and runs by itself (paid agent work: ask first).';
+    }
+  }
+  // Without the API's read, the Discovery step is all there is to go on, and
+  // without that, nothing: a guess would send a product at its documents back
+  // to the conversation.
+  if (!state.missing) return setupNextStep(state.product as ProductSettingsView);
+  if (state.missing.includes('specification')) {
+    return (
+      'The specification comes from the Discovery conversation, held in the web: the person describes the ' +
+      'product there. The other documents follow from it.' +
+      (state.linked === false
+        ? ' Linking a repository (taiga_link_repository) can wait until before the first build.'
+        : '')
+    );
+  }
+  if (state.missing.length > 0) {
+    return (
+      `Still to publish: ${named(state.missing)}. taiga_generate_product_documents generates the missing ones ` +
+      '(paid agent work: ask first); a draft is published with taiga_publish_product_document.'
+    );
+  }
+  if (state.openChecks && state.openChecks.length > 0)
+    return `The documents are published; the checks are stamped in the web, then ${finish}`;
+  return `Every required document is published: ${finish}`;
+}

package/src/tools/repositories.ts

@@ -46,6 +46,8 @@ const GITHUB_REPOSITORY_FIELDS = [
   'defaultBranch',
   'description',
   'language',
+  // A product already links it (PRO-2800); absent from an API that predates the field.
+  'linked',
 ] as const;
 
 const repositoryId = idInput(
@@ -114,7 +116,8 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           "The repositories the organization's GitHub connection can reach, to link one to a product " +
           '(taiga_link_repository takes its id). Searches by name with query. Name the GitHub account (account: ' +
           'its login, the owner in owner/repo, or installationId) to read only its repositories; without one it ' +
-          'reads every connected account and takes rows from each in turn, so one account cannot fill the page. No ' +
+          'reads every connected account and takes rows from each in turn, so one account cannot fill the page. ' +
+          'linked: true means a product already links it (taiga_resolve_product says which). No ' +
           'connection means GitHub is not connected yet: that is done once, in the web, by someone who can ' +
           'install the app.',
         inputSchema: z.object({

package/src/tools/resources.ts

@@ -194,20 +194,20 @@ export function registerResources(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('backlog:read')) {
     server.registerResource(
       'backlog-item',
-      new ResourceTemplate('taiga://backlog/{itemId}', { list: undefined }),
+      new ResourceTemplate('taiga://initiatives/{initiativeId}', { list: undefined }),
       {
-        title: 'Backlog item',
+        title: 'Initiative',
         description:
-          'An initiative in full: description, acceptance criteria, technical context. taiga_list_backlog_items ' +
+          'An initiative in full: description, acceptance criteria, technical context. taiga_list_initiatives ' +
           'gives the item ID.',
         mimeType: 'application/json',
       },
       async (uri, variables) => {
-        const itemId = requireId('Backlog item ID', String(variables['itemId']));
+        const initiativeId = requireId('Initiative ID', String(variables['initiativeId']));
         const item = (
           await served(
-            client.getBacklogItem(itemId),
-            'No backlog item with that ID the key can see; taiga_list_backlog_items shows what exists'
+            client.getBacklogItem(initiativeId),
+            'No initiative with that ID the key can see; taiga_list_initiatives shows what exists'
           )
         ).data;
         return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(item, null, 2) }] };

package/src/tools/sections.ts

@@ -168,7 +168,7 @@ export const sectionsInput = z
   .max(50)
   .optional()
   .describe(
-    'Only these sections, by id; [] for the outline (every section id and its size, no text); omit for the whole document'
+    'Only these sections, by id; [] for the outline (under outline: every section id and its size, no text); omit for the whole document'
   );
 
 /**
@@ -184,6 +184,18 @@ export function sectionReadResult(doc: StoredDocument, ids: readonly string[], l
   if (!cut) return toolError('VALIDATION_ERROR', `The ${label} is not made of sections; read it without sections.`);
   const all = Object.keys(sectionsOf(doc.data as DocumentData) ?? {});
   const unknownSections = ids.filter((id) => !all.includes(id));
+  const known = ids.filter((id) => all.includes(id));
+  if (known.length === 0) {
+    // The outline, or a read naming only ids the document lacks: no text to
+    // carry, so no empty data.sections beside the ids, which read as a
+    // document with no sections (PRO-2800).
+    const { data: _data, ...meta } = cut.doc;
+    return toolResult({
+      ...meta,
+      outline: cut.omittedSections,
+      ...(unknownSections.length > 0 ? { unknownSections } : {}),
+    });
+  }
   return toolResult({
     ...cut.doc,
     omittedSections: cut.omittedSections,

package/src/tools/setup.ts

@@ -4,8 +4,9 @@ import { z } from 'zod';
 import type { Product } from '@taiga/types';
 import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY, WRITE } from './annotations.js';
-import { isImportedProduct, setupNextStep } from './catalogue.js';
-import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
+import { isImportedProduct } from './catalogue.js';
+import { runTool, toolError, toolResult } from './errors.js';
+import { setupReadiness } from './readiness.js';
 import { withStop } from './hints.js';
 import { idInput, productId } from './inputs.js';
 import { pickFields } from './summarize.js';
@@ -64,36 +65,17 @@ const MISSING_DOCUMENTS_HOW =
 
 type ProductRow = WithoutTenant<Product>;
 
-/** A product row the model can act on, saying how it started as the other product tools say it. */
+/** A product row the model can act on: how it started, and while in setup what it still needs. */
 async function productRow(client: TaigaClient, product: ProductRow) {
   const { settings: _settings, ...rest } = pickFields([product], PRODUCT_FIELDS)[0]!;
-  const nextStep = setupNextStep(await withDiscoveryStep(client, product));
+  const readiness = await setupReadiness(client, product);
   return {
     ...rest,
     projectType: isImportedProduct(product) ? 'brownfield' : 'greenfield',
-    ...(nextStep ? { nextStep } : {}),
+    ...(readiness ? { readiness } : {}),
   };
 }
 
-/**
- * The product with its discoveryStep. The API derives it on reads only, not
- * on the answer to a write (products.ts), and a draft started from scratch
- * needs it to say what comes next; an imported one reads its import status
- * instead. Best effort: a failed read leaves the product without a nextStep
- * rather than failing the write that already happened.
- */
-async function withDiscoveryStep(client: TaigaClient, product: ProductRow): Promise<ProductRow> {
-  if (product.status !== 'draft' || 'discoveryStep' in product || isImportedProduct(product)) {
-    return product;
-  }
-  try {
-    return (await client.getProduct(String(product.id))).data;
-  } catch (error) {
-    if (error instanceof TaigaApiError || isNetworkFailure(error)) return product;
-    throw error;
-  }
-}
-
 /**
  * A half turned off with nothing said about how it is done today. Allowed (the
  * web asks for the sentence but does not insist), so a warning rather than a
@@ -191,8 +173,8 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
           'Move a product to another factory. Access follows the factory, so this changes who can reach the ' +
           "product (taiga_preview_product_move says who); the product's own knowledge files are re-filed onto " +
           'the new factory, and factory knowledge and instructions stay with the factory that owns them. Refused ' +
-          '(CONFLICT) while a plan or build is in flight: stopLine: true stops the line first and then moves, which ' +
-          'interrupts that work.',
+          '(WORK_IN_FLIGHT) while a plan or build is in flight. Then ask the person: stopLine: true stops the ' +
+          'line first and then moves, which interrupts that work.',
         inputSchema: z.object({
           productId,
           factoryId: factoryId.describe('The factory to move it to'),
@@ -205,10 +187,28 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       },
       (params) =>
         runTool(async () => {
-          const moved = await client.moveProduct(params.productId, {
-            factoryId: params.factoryId,
-            ...(params.stopLine ? { stopLine: true } : {}),
-          });
+          let moved;
+          try {
+            moved = await client.moveProduct(params.productId, {
+              factoryId: params.factoryId,
+              ...(params.stopLine ? { stopLine: true } : {}),
+            });
+          } catch (error) {
+            // The API's own words say "Stop the line, then move the product",
+            // which reads as an instruction to the agent; whether to interrupt
+            // the work is the person's call (PRO-2800).
+            if (error instanceof TaigaApiError && error.code === 'WORK_IN_FLIGHT') {
+              return toolError(
+                'WORK_IN_FLIGHT',
+                // The API's first sentence says what is in flight; its second ("Stop the line, then move the product")
+                // is the instruction this replaces.
+                `${withStop((error.apiMessage ?? 'Work is in flight on this product').split(/(?<=[.!?])\s/)[0]!)} Moving it now means stopping ` +
+                  'the line, which interrupts that work: ask the person, and pass stopLine: true only if they say so.',
+                error.details
+              );
+            }
+            throw error;
+          }
           return toolResult({
             product: await productRow(client, moved.data),
             changed: moved.changed,