@taiga-ai/mcp-server 0.19.0-dev.451 → 0.20.0-dev.454

package/src/tools/index.ts

@@ -19,6 +19,8 @@ import { registerRepositoryTools } from './repositories.js';
 import { registerResources } from './resources.js';
 import { registerSetupTools } from './setup.js';
 import { notFoundHint, notFoundHints } from './hints.js';
+import { runTool, toolResult } from './errors.js';
+import { READ_ONLY } from './annotations.js';
 import { DEFAULT_WAIT_OPTIONS, registerWaitTools, type WaitOptions } from './wait.js';
 
 /**
@@ -30,13 +32,14 @@ import { DEFAULT_WAIT_OPTIONS, registerWaitTools, type WaitOptions } from './wai
  * model learns the tool's real shape. Applied here, once, so no tool can be
  * registered without it.
  */
-function withStrictInputs(server: McpServer): McpServer {
+function withStrictInputs(server: McpServer, registered: Map<string, ToolAnnotations | undefined>): McpServer {
   const register = server.registerTool.bind(server) as (...args: unknown[]) => unknown;
   server.registerTool = ((
     name: string,
     config: { inputSchema?: unknown; description?: string; annotations?: ToolAnnotations },
     callback: unknown
   ) => {
+    registered.set(name, config.annotations);
     const schema = config.inputSchema;
     if (schema !== undefined && !(schema instanceof z.ZodObject)) {
       throw new Error(`Tool ${name}: inputSchema must be a z.object() so unknown arguments can be refused`);
@@ -56,7 +59,7 @@ function withStrictInputs(server: McpServer): McpServer {
   return server;
 }
 
-type ToolAnnotations = { readOnlyHint?: boolean; destructiveHint?: boolean };
+type ToolAnnotations = { readOnlyHint?: boolean; destructiveHint?: boolean; openWorldHint?: boolean };
 
 /**
  * The entry points, loaded with their descriptions at session start
@@ -79,7 +82,7 @@ export function writeNotice(name: string, annotations: ToolAnnotations | undefin
     throw new Error(`Tool ${name}: annotations must say whether it is read-only`);
   }
   if (annotations.readOnlyHint) return '';
-  return annotations.destructiveHint ? 'Acts on paid or shared work: ask the person first. ' : 'Writes. ';
+  return annotations.destructiveHint ? 'Ask first: paid or shared work. ' : 'Writes. ';
 }
 
 /**
@@ -88,7 +91,8 @@ export function writeNotice(name: string, annotations: ToolAnnotations | undefin
  * never sees tools it can't use.
  */
 export function registerAllTools(server: McpServer, client: TaigaClient, options: { wait?: WaitOptions } = {}): void {
-  withStrictInputs(server);
+  const registered = new Map<string, ToolAnnotations | undefined>();
+  withStrictInputs(server, registered);
   registerProductTools(server, client);
   registerDocumentTools(server, client);
   registerBacklogTools(server, client);
@@ -105,6 +109,52 @@ export function registerAllTools(server: McpServer, client: TaigaClient, options
   registerRepositoryTools(server, client);
   registerWaitTools(server, client, options.wait ?? DEFAULT_WAIT_OPTIONS);
   registerContextTools(server, client);
+  // Only beside other tools: a key with no capabilities gets no tools at all.
+  if (registered.size > 0) registerWhoami(server, client, registered);
   registerResources(server, client);
   registerPrompts(server, client);
 }
+
+/**
+ * Who this key is and what it may do (PRO-2800): reviewing agents read tool
+ * descriptions saying "owners and admins link repositories" with no way to
+ * learn their own role until a write was refused. Registered last, so it can
+ * name every tool the key was given.
+ */
+function registerWhoami(
+  server: McpServer,
+  client: TaigaClient,
+  registered: Map<string, ToolAnnotations | undefined>
+): void {
+  server.registerTool(
+    'taiga_whoami',
+    {
+      title: 'Who am I',
+      description:
+        "Who this API key acts as and what it may do: the person's email and organization role, the key's scopes " +
+        '(null means every capability the person has), its capabilities, and the tools it was given, split into ' +
+        "reads, writes, and the ask-first writes (paid agent work or changes others see). A tool the key's " +
+        'capabilities do not cover is not offered at all, rather than refused when called.',
+      inputSchema: z.object({}),
+      annotations: READ_ONLY,
+    },
+    () =>
+      runTool(async () => {
+        const me = client.getIntrospection();
+        const tools = [...registered.entries()].filter(([name]) => name !== 'taiga_whoami');
+        const named = (pick: (notes: ToolAnnotations | undefined) => boolean) =>
+          tools.filter(([, notes]) => pick(notes)).map(([name]) => name);
+        return toolResult({
+          email: me?.email ?? null,
+          role: me?.role ?? null,
+          scopes: me?.scopes ?? null,
+          capabilities: me?.capabilities ?? [],
+          tools: {
+            reads: named((notes) => notes?.readOnlyHint === true),
+            writes: named((notes) => notes?.readOnlyHint === false && notes.destructiveHint !== true),
+            askFirst: named((notes) => notes?.readOnlyHint === false && notes.destructiveHint === true),
+          },
+        });
+      })
+  );
+}

package/src/tools/instructions.ts

@@ -13,20 +13,25 @@ export const SERVER_INSTRUCTIONS = [
   "Taiga is a policy-aware software delivery platform: an organization's policies and knowledge, its factories",
   "and products, each product's initiatives (its backlog), the line that plans and builds them one at a time, the",
   "coding agent's runs and pull requests, maintenance findings, and Action Required, where work waits on a person.",
-  'Search these tools whenever the person asks about a Taiga product, an initiative, a run or pull request, policy',
-  'or compliance, findings, deployments or monitoring, or setting a product up.',
+  'Use these tools (names start with taiga_) whenever the person asks about a Taiga product, an initiative, a run',
+  'or pull request, policy or compliance, findings, deployments, or setting a product up.',
   '',
-  '**Start here.** taiga_get_product_context (the product by git remote URL, slug or ID) gives its state in one',
-  'call: what it still needs while in setup, its documents as outlines, policies as section ids, open initiatives,',
-  'recent runs with their outcome, and what waits on a person. Then read only what you need. Across products,',
-  'taiga_list_products and taiga_list_action_required.',
+  '**Start here.** taiga_get_product_context (a product by git remote URL, slug or ID) says where it stands in one',
+  'call: what it still needs while in setup, documents as outlines, policies as section ids, open initiatives,',
+  'recent runs with their outcome, what waits on a person, findings and policy violations. Then read only what you',
+  'need. Across products: taiga_list_products, taiga_list_action_required. taiga_whoami says what this key may do.',
   '',
   '**Words.** An initiative is a unit of work in the backlog; a run is one attempt by the coding agent to build it;',
   "the line is the product's queue; a factory owns a set of products. IDs are UUIDs, never names; a NOT_FOUND names",
-  'the tool that lists the right ones. A refusal carries the reason: say it as it is.',
+  'the tool that lists the right ones. A GitHub repository id is not a repository link id. Say a refusal as it is.',
   '',
-  '**Before you write.** A tool that writes says so first: "Writes." or "Acts on paid or shared work: ask the',
-  'person first." Ask before the second kind: it starts paid agent work, interrupts it, or changes what others see.',
+  '**Reading.** Lists page with nextCursor (Action Required, setup tasks, findings: totalCount). A document has two',
+  'timelines: plan (what was meant) and reality (derived from the code). outcome, situation and nextStep are',
+  'one-sentence summaries of the record they sit on; read the record for the detail.',
+  '',
+  '**Before you write.** A tool that writes opens with "Writes." or "Ask first:". Before an "Ask first" tool, tell',
+  'the person what you are about to do and wait for their yes: it starts paid agent work, interrupts it, or changes',
+  'what others see.',
   '',
   '**Only in the web:** connecting GitHub, members and roles, the Discovery conversation of a product started from',
   'scratch, stamping checks, starting a run over, and deleting anything.',

package/src/tools/knowledge.ts

@@ -173,7 +173,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Add knowledge',
       description:
-        'File a Markdown or plain-text reference document as knowledge, at the level it is relevant: a product ' +
+        'File a reference document as knowledge for agents to search: Markdown or plain text, at the level it is relevant: a product ' +
         '(productId), a factory (factoryId), or the organization (neither; that takes an owner or admin, ' +
         'because every factory and product inherits it). Good candidates are what a new engineer would be ' +
         'handed to read: specifications and contracts to conform to, glossaries and code lists, third-party ' +

package/src/tools/maintenance.ts

@@ -85,7 +85,14 @@ export function standingSummary(standing: {
   controls?: unknown;
   divergences?: unknown;
   resolvedDivergences?: unknown;
-}): { controls: number; violations: number; bySeverity: Record<string, number>; resolvedViolations: number } {
+}): {
+  controls: number;
+  controlsInPolicies: number;
+  controlsWithNothingRecorded: 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;
@@ -95,7 +102,16 @@ export function standingSummary(standing: {
     const severity = String(violation['severity'] ?? 'unknown');
     bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
   }
-  return { controls: listed.length, violations: violations.length, bySeverity, resolvedViolations: resolved };
+  return {
+    controls: listed.length,
+    // Every control the product's policies hold, and those nothing is recorded against: the positive side of
+    // "how do we stand", which is no evidence against them, not proof they are met.
+    controlsInPolicies: controls.length,
+    controlsWithNothingRecorded: controls.length - listed.length,
+    violations: violations.length,
+    bySeverity,
+    resolvedViolations: resolved,
+  };
 }
 
 const findingId = idInput('finding', 'taiga_list_findings gives it');
@@ -177,7 +193,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Get a maintenance finding',
       description:
-        'Read one finding in full: what it is, how likely it is to be exploited (EPSS, the known-exploited list), ' +
+        'Read one maintenance finding in full: what it is, how likely it is to be exploited (EPSS, the known-exploited list), ' +
         'the advisory and the fixed version, the place in the code, the policy controls it breaches, why it is ' +
         'ranked where it is, its history (reintroduced, previously resolved) and the remediation under way. A ' +
         "secret's value is never stored; the finding names the rule and the location only.",
@@ -198,7 +214,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: "Get a product's policy standing",
       description:
-        "Where a product stands against the organization's own published policies: the controls it violates, " +
+        "How a product stands against the organization's own published policies: the controls it violates, " +
         "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 ' +
@@ -208,7 +224,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         '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 ' +
+        'is not listed, and it is not "passing" either: there is no such state; summary.controlsWithNothingRecorded counts them. Pass full: true for every ' +
         "violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
       inputSchema: z.object({
         productId,
@@ -228,9 +244,18 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         // The counts first, on both answers: the lists run to thousands of
         // tokens, and "how bad is it" is the first question.
         const summary = standingSummary(standing);
-        if (params.full) return toolResult({ summary, ...standing });
+        // Never assessed reads like a clean bill otherwise (PRO-2800).
+        const assessment = standing.assessment as { state?: unknown } | null | undefined;
+        const note =
+          assessment?.state === 'never'
+            ? 'Never assessed: the documents have not been checked against the policies yet, so nothing here is an ' +
+              'all-clear. An assessment runs when the reality documents are derived or refreshed ' +
+              '(taiga_refresh_reality_documents, paid work: ask first).'
+            : null;
+        if (params.full) return toolResult({ summary, ...(note ? { note } : {}), ...standing });
         return toolResult({
           summary,
+          ...(note ? { note } : {}),
           productId: standing.productId,
           hasPolicies: standing.hasPolicies,
           assessment: standing.assessment,
@@ -259,7 +284,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Ignore or reopen a finding',
       description:
-        'Ignore a finding that does not apply or whose risk is accepted, with the reason (false_positive, ' +
+        'Ignore a maintenance finding, with a reason, or reopen it. Ignore one that does not apply or whose risk is accepted, with the reason (false_positive, ' +
         'not_reachable, accepted_risk, wont_fix), an optional note and an optional expiry after which it resurfaces ' +
         'if it still exists; or reopen an ignored one (ignored: false). Ignored findings are kept and reviewable. ' +
         'There is no "mark fixed": a finding resolves when the next sweep no longer detects it. For a secret that ' +
@@ -302,7 +327,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Fix a finding',
       description:
-        "Ask for a finding's fix: Taiga raises an initiative and adds it to the end of the product's queue, where " +
+        "Ask Taiga to fix a maintenance finding: it raises an initiative and adds it to the end of the product's queue, where " +
         "the line plans it in turn; whether the build then waits for a person is the initiative's review gate, " +
         'as for any initiative. The fix is a normal run that ends in a pull request you review and merge. With ' +
         "wholeGroup: true it fixes the finding's whole group in one initiative, as the page does: for a " +
@@ -353,7 +378,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Fix policy violations',
       description:
-        "Ask for the fix of a product's policy violations: name a control to cover every violation recorded " +
+        "Ask Taiga to fix a product's policy violations (it raises initiatives): name a control to cover every violation recorded " +
         'against it that has no initiative yet, or a single violation (violationId) when the control has more ' +
         "than one. Taiga raises one initiative and adds it to the end of the product's queue, exactly as a " +
         'finding fix does. The violation stays listed while the work is under way: only the next assessment ' +

package/src/tools/observe.ts

@@ -100,7 +100,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get what runs where',
       description:
-        "What is running in each of a product's environments now, anything deploying to them, and the recent " +
+        "What runs in each of a product's environments, and recent deployments: what is running now, anything deploying, and the recent " +
         'history, newest first: each deployment with its commit, pull request, status, who deployed it and, ' +
         'for a failure, the error the provider reported. What runs is the most recent deployment that actually ' +
         'succeeded, so a newer failed attempt shows beside the version still running, not in its place. The ' +
@@ -174,7 +174,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get delivery metrics',
       description:
-        "DORA's five software delivery metrics for one environment (the one marked production, as the page " +
+        "DORA's five delivery metrics for one environment (the one marked production, as the page " +
         'reports them), computed from its deployment history over the last 30, 60 or 90 days: deployment ' +
         'frequency, lead time and failed deployment recovery time (throughput), change-failure rate and rework ' +
         'rate (instability), each with its trend against the window before, and a performance band for all but ' +
@@ -196,7 +196,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: "Get a product's monitoring",
       description:
-        "How a product's environments are doing: each environment's current health from Taiga's availability " +
+        "How a product's environments are doing (health, uptime): each environment's current health from Taiga's availability " +
         'checks of its App URL, with its uptime and when it was last checked; a status Taiga cannot verify now ' +
         'reads as not checked rather than the last thing it knew, and a new environment as baseline learning. ' +
         "With environmentId, that environment's uptime over a 30, 60 or 90-day window, and the experience " +

package/src/tools/product-documents.ts

@@ -105,7 +105,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
     {
       title: 'Mark a product document reviewed',
       description:
-        "Record that a person reviewed a product document's latest published version, as the Documents page " +
+        'Record that a person reviewed a product document: its latest published version, as the Documents page ' +
         "shows it beside each version; once every published document is reviewed, the product's review item in " +
         'Action Required resolves. The mark says a human read it, so make it only when the person tells you they ' +
         'have: reading it yourself is not a review.',

package/src/tools/products.ts

@@ -17,7 +17,15 @@ import {
   type ProductDocumentOrigin,
   type ProductSettingsView,
 } from './catalogue.js';
-import { apiFailureCode, apiFailureText, isMissOrRefusal, runTool, toolError, toolResult } from './errors.js';
+import {
+  apiFailureCode,
+  apiFailureText,
+  isMissOrRefusal,
+  isNetworkFailure,
+  runTool,
+  toolError,
+  toolResult,
+} from './errors.js';
 import { parseRemote } from './remote.js';
 import { sectionReadResult, sectionsInput, stripProvenance } from './sections.js';
 import { setupReadiness } from './readiness.js';
@@ -30,6 +38,38 @@ type DocumentRow = WithoutTenant<ProductDocumentListItem>;
 // Not `kind`: it is parked behind a flag that is on nowhere, so every row said null.
 export const PRODUCT_SUMMARY_FIELDS = ['id', 'name', 'slug', 'status', 'factoryId', 'discoveryStep'] as const;
 
+/**
+ * Product rows with their factory's name beside its id (PRO-2800): "what
+ * products does the organization have" needed a second list to name the
+ * factories. One factories read; without factories:read, or when it fails,
+ * the rows keep the id alone.
+ */
+async function withFactoryNames<T extends { factoryId?: unknown }>(client: TaigaClient, rows: T[]) {
+  if (!client.hasCapability('factories:read') || rows.length === 0) return rows;
+  try {
+    // Every page until the rows' factories are named, up to a bound.
+    const wanted = new Set(rows.map((row) => String(row.factoryId)));
+    const names = new Map<string, string>();
+    let cursor: string | undefined;
+    for (let pageIndex = 0; pageIndex < FACTORY_PAGES; pageIndex += 1) {
+      const result = await client.listFactories({ limit: 100, cursor });
+      for (const factory of result.data) names.set(factory.id, factory.name);
+      if (!result.nextCursor || [...wanted].every((id) => names.has(id))) break;
+      cursor = result.nextCursor;
+    }
+    return rows.map((row) => {
+      const name = names.get(String(row.factoryId));
+      return name === undefined ? row : { ...row, factoryName: name };
+    });
+  } catch (error) {
+    if (error instanceof TaigaApiError || isNetworkFailure(error)) return rows;
+    throw error;
+  }
+}
+
+/** Factory pages read to name products' factories. */
+const FACTORY_PAGES = 10;
+
 /** A list's name search: part of a name, any case. */
 const query = (what: string) =>
   z.string().trim().min(1).max(200).optional().describe(`Part of the ${what}, any case: only the rows that contain it`);
@@ -322,7 +362,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'List products',
         description:
-          'List products in the organization, as summaries (id, name, slug, status, factory, discoveryStep). ' +
+          'List products in the organization, as summaries (id, name, slug, status, factoryId and factoryName, discoveryStep). ' +
           'Use this to find a product by name (query); inside a git checkout, taiga_resolve_product finds it ' +
           `from the remote URL instead. taiga_get_product reads one in full. ${DISCOVERY_STEP_MEANING}`,
         inputSchema: z.object({
@@ -346,7 +386,9 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           const { query: text, ...filters } = params;
           if (text === undefined) {
             const result = await client.listProducts(filters);
-            return toolResult(page(pickFields(result.data, PRODUCT_SUMMARY_FIELDS), result.nextCursor));
+            return toolResult(
+              page(await withFactoryNames(client, pickFields(result.data, PRODUCT_SUMMARY_FIELDS)), result.nextCursor)
+            );
           }
           if (params.cursor !== undefined) return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
           const found = await searchPages(
@@ -362,7 +404,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
             params.limit ?? 25
           );
           return toolResult({
-            ...page(pickFields(found.rows, PRODUCT_SUMMARY_FIELDS), null),
+            ...page(await withFactoryNames(client, pickFields(found.rows, PRODUCT_SUMMARY_FIELDS)), null),
             ...(found.more ? { more: SEARCH_NOTE } : {}),
           });
         })
@@ -373,7 +415,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
       {
         title: 'Get product',
         description:
-          'Get one product in full, by ID or by slug: name, slug, factory, what Taiga owns for it ' +
+          'Read one product record and its settings, by ID or by slug: name, slug, factory, what Taiga owns for it ' +
           '(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, ' +

package/src/tools/queue.ts

@@ -15,6 +15,7 @@ import { OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { isNetworkFailure, runTool, toolResult } from './errors.js';
 import { productId } from './inputs.js';
 import { criteriaCounts } from './summarize.js';
+import { handbackSaid } from './builds.js';
 
 /** How many entries the read names; past this an entry keeps its initiativeId only. */
 const NAMED_ENTRIES = 25;
@@ -32,6 +33,8 @@ interface QueueRow {
   lifecycle?: Pick<BacklogItemLifecycle, 'turn' | 'stage' | 'cta'> | null;
   runId?: string;
   prUrl?: string | null;
+  /** Why the agent handed the latest run back to a person, when it did. */
+  handedBack?: string;
   halt?: { cause: string | null; reason: string; nextStep: string };
 }
 
@@ -89,6 +92,7 @@ function waitingOn(rows: QueueRow[]): string | null {
   // An active entry with a landed plan is past its review gate (a closed
   // gate halts it instead): it waits for the Build slot, not for anyone.
   if (lifecycle.cta === 'start_build') return `${name} has its plan and waits for the Build slot; ${held}`;
+  if (head.handedBack) return `${name} was handed back to a person: ${head.handedBack}${pr}; ${held}`;
   if (lifecycle.turn === 'you') {
     return `${name} is waiting on a person (${String(lifecycle.cta ?? lifecycle.stage)})${pr}; ${held}`;
   }
@@ -145,6 +149,8 @@ export async function queueView(
         lifecycle: lifecycle ? { turn: lifecycle.turn, stage: lifecycle.stage, cta: lifecycle.cta } : null,
         ...(latestBuild ? { runId: latestBuild.id, prUrl: latestBuild.prUrl ?? null } : {}),
       } satisfies Partial<QueueRow>);
+      const handback = handbackSaid(latestBuild?.reviewEscalation);
+      if (handback) row.handedBack = handback;
     }
     if (entry.state === 'halted') {
       const cause = typeof entry.haltCause === 'string' ? entry.haltCause : null;
@@ -202,7 +208,7 @@ export function registerQueueTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get the product queue',
       description:
-        "Read a product's queue, the line the coding agent works one initiative at a time: each entry in order " +
+        "Read a product's line, the queue the coding agent works one initiative at a time, and what it waits on: each entry in order " +
         'with its title, where it is (planning, building, in review) and whose turn it is, a halted entry with why ' +
         'it stopped and what lifts it, linePaused (null when the product could not be read), and waitingOn, one ' +
         'sentence saying what the line is waiting for. The ' +

package/src/tools/readiness.ts

@@ -18,10 +18,10 @@ export interface Readiness {
   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. */
+  /** An imported product's import, as its settings.importStatus says it: pending (not started), analyzing or generating_docs (running), complete, failed, cancelled. */
   import?: string;
   discoveryStep?: unknown;
-  /** The required documents not yet published, by name; null when the API could not say. */
+  /** The required documents not yet published, as the type taiga_get_product_document takes; 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;
@@ -49,12 +49,17 @@ function named(types: string[]): string {
 }
 
 /** The product's setup readiness, or null once it has finished setup. */
-export async function setupReadiness(client: TaigaClient, product: Row): Promise<Readiness | null> {
+export async function setupReadiness(
+  client: TaigaClient,
+  product: Row,
+  /** The product's repository links when the caller is reading them anyway (the context), so one read serves both. */
+  links?: () => Promise<{ data: unknown[] }>
+): 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(
+    (links ? links() : client.listProductRepositories(id)).then(
       (result) => result.data as Row[],
       (error: unknown) => {
         if (isApiSide(error)) return null;
@@ -97,9 +102,9 @@ export async function setupReadiness(client: TaigaClient, product: Row): Promise
   return {
     ready,
     repository,
-    ...(importState ? { import: importState } : {}),
+    ...(imported ? { import: typeof settings.importStatus === 'string' ? settings.importStatus : 'pending' } : {}),
     ...(imported ? {} : { discoveryStep: full['discoveryStep'] ?? null }),
-    missingDocuments: missing ? missing.map((type) => named([type])) : null,
+    missingDocuments: missing,
     openChecks,
     nextStep: nextStepFor({
       imported,

package/src/tools/repositories.ts

@@ -211,8 +211,8 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
     {
       title: 'Link a repository to a product',
       description:
-        'Link a repository the GitHub connection can reach (taiga_list_linkable_repositories gives its id) to a ' +
-        'product, or with replacesRepositoryId swap the one linked now for it in one step (naming the same ' +
+        'Link a GitHub repository to a product: one the GitHub connection can reach (taiga_list_linkable_repositories gives its id), ' +
+        'or with replacesRepositoryId swap the one linked now for it in one step (naming the same ' +
         'repository there changes nothing; linking one already linked without it is refused). A link Taiga ' +
         'manages (isManaged) cannot be replaced or unlinked. Once linked, planning reads its code, runs open pull requests in it, ' +
         'sweeps scan it, and its deployment history is imported in the background.',

package/src/tools/sections.ts

@@ -168,9 +168,33 @@ export const sectionsInput = z
   .max(50)
   .optional()
   .describe(
-    'Only these sections, by id; [] for the outline (under outline: every section id and its size, no text); omit for the whole document'
+    'Only these sections, by id, or a policy control id (SEC-5.1) for the sections that state it; [] for the outline (under outline: every section id and its size, no text); omit for the whole document'
   );
 
+/** A policy control id as the standing cites it: SEC-5.1, SDLC-3.1, GDPR-2.3. */
+const CONTROL_ID = /^[A-Z][A-Z0-9]*-\d+(\.\d+)*$/;
+
+/**
+ * The sections that state each control id asked for (PRO-2800): policy
+ * standing cites SEC-5.1, and the section holding it has an id of its own
+ * (secretsManagement) an agent could only guess. A control id is found in
+ * the sections' text, matched as a whole id so SEC-5.1 is not SEC-5.10.
+ */
+function controlSections(sections: Sections, ids: readonly string[]): Record<string, string[]> {
+  const found: Record<string, string[]> = {};
+  for (const id of ids) {
+    if (!CONTROL_ID.test(id) || Object.hasOwn(sections, id)) continue;
+    // Whole id only: not SEC-5.10, SEC-5.1.2, SEC-5.1A or SEC-5.1-appendix; a sentence's full stop is fine.
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`(^|[^A-Za-z0-9.-])${escaped}(?![A-Za-z0-9-]|\\.[A-Za-z0-9])`);
+    const holders = Object.keys(sections).filter((sectionId) =>
+      pattern.test(sectionContent(sections, sectionId) ?? '')
+    );
+    if (holders.length > 0) found[id] = holders;
+  }
+  return found;
+}
+
 /**
  * The answer to a read that names sections: the ones the document has, the
  * rest listed with their sizes, and the asked-for ids it lacks under
@@ -179,12 +203,17 @@ export const sectionsInput = z
  * real id with its size, so the retry needs nothing else. No ids is the
  * outline.
  */
-export function sectionReadResult(doc: StoredDocument, ids: readonly string[], label: string): CallToolResult {
+export function sectionReadResult(doc: StoredDocument, asked: readonly string[], label: string): CallToolResult {
+  const before = sectionsOf(doc.data as DocumentData);
+  const controls = before ? controlSections(before, asked) : {};
+  // A control id reads the sections that state it; the id is then not unknown.
+  const ids = [...new Set([...asked.filter((id) => !Object.hasOwn(controls, id)), ...Object.values(controls).flat()])];
   const cut = pickSections(doc, new Set(ids));
   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));
+  const found = Object.keys(controls).length > 0 ? { controls } : {};
   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
@@ -198,6 +227,7 @@ export function sectionReadResult(doc: StoredDocument, ids: readonly string[], l
   }
   return toolResult({
     ...cut.doc,
+    ...found,
     omittedSections: cut.omittedSections,
     ...(unknownSections.length > 0 ? { unknownSections } : {}),
   });

package/src/tools/setup.ts

@@ -268,7 +268,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     {
       title: "Change a product's settings",
       description:
-        "Change a product's name (its slug follows the name, so links to the product change) or what Taiga " +
+        "Change a product's name or what Taiga builds for it. A new name changes the slug, so links to the product change. What Taiga " +
         'builds for it: its infrastructure code and CI/CD pipelines (null ' +
         'returns one to the organization default), the sentence on how a half Taiga does not build is done today, ' +
         "and whether it inherits the organization's design standards (null follows the default for how the " +
@@ -306,7 +306,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     {
       title: "Refresh a product's documents from its code",
       description:
-        "Derive the reality documents again from the code on the branch Taiga works on (the link's effectiveBranch: " +
+        "Derive the reality documents again from the code, on the branch Taiga works on (the link's effectiveBranch: " +
         "the chosen branch, or the repository's default): all of them, or the ones named (with " +
         'what they are derived from). For a document the import misread, refresh it rather than importing ' +
         'again; unchanged sections are not republished. Runs an agent in the background and returns the job; ' +

package/src/tools/wait.ts

@@ -9,7 +9,7 @@ import { isNetworkFailure, runTool, toolResult } from './errors.js';
 import { SETTLED_JOB_STATUSES, jobReport } from './jobs.js';
 import { criteriaCounts, pickFields } from './summarize.js';
 import { situationOf } from './backlogs.js';
-import { readableRun } from './builds.js';
+import { readableRow } from './builds.js';
 
 /**
  * Waiting without a timer. A model in an editor has no clock: to learn that
@@ -324,6 +324,8 @@ const RUN_REPORT_FIELDS = [
   'prState',
   'prDraft',
   'prMerged',
+  'reviewEscalation',
+  'error',
   'prNumber',
   'baseBranch',
   'actions',
@@ -358,7 +360,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
       {
         title: 'Wait for an initiative',
         description:
-          'Wait until an initiative reaches a point, instead of reading it again and again: changed (anything ' +
+          'Wait for an initiative to reach a point (planned, building, a pull request, done), instead of reading it again and again: changed (anything ' +
           'about where it is or its latest run), planned (its plan landed), your_turn (it waits on a person: a ' +
           'plan to review, a pull request, a flag), pr_open (a pull request open now; a merged or closed one does ' +
           'not count), run_settled (its latest run stopped moving) or done (finished; a canceled one stops the wait). ' +
@@ -423,7 +425,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
       {
         title: 'Wait for a run',
         description:
-          "Wait until a coding agent's run reaches a point: changed (status, steps or pull request), step_done " +
+          'Wait for a run to reach a point (a step, a pull request, settled): changed (status, steps or pull request), step_done ' +
           '(one more step finished), pr_open (open now, not merged or closed) or settled (it stopped moving: in ' +
           'review, completed, failed, stopped). ' +
           'Returns as soon as that holds (reached: true), early when the run settled without it (stoppedBecause; ' +
@@ -454,7 +456,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
           return toolResult({
             until: params.until,
             ...outcome,
-            run: now ? readableRun(pickFields([now], RUN_REPORT_FIELDS)[0]!) : null,
+            run: now ? readableRow(pickFields([now], RUN_REPORT_FIELDS)[0]!) : null,
           });
         })
     );