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

package/src/tools/maintenance.ts

@@ -20,8 +20,6 @@ import { page, pickFields } from './summarize.js';
  * next sweep no longer detects it, so there is no tool for either.
  */
 
-type Row = Record<string, unknown>;
-
 /** A finding as a list row: enough to decide whether to open, fix or ignore it. */
 const FINDING_ROW_FIELDS = [
   'id',
@@ -75,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) {
@@ -88,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,
     },
@@ -99,11 +123,11 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
           client.getMaintenanceSummary(params.productId),
           client.listMaintenanceSweeps(params.productId, { limit: 3 }),
         ]);
-        const latest = pickFields(sweeps.data as Row[], SWEEP_FIELDS);
+        const latest = pickFields(sweeps.data, SWEEP_FIELDS);
         // The sweeps are reported as `latestSweeps`, narrowed to SWEEP_FIELDS;
         // the summary's own run rows (PRO-2527: one per repository) would
         // repeat them with every column.
-        const { lastRun: _lastRun, lastRuns: _lastRuns, ...standing } = summary.data as Row;
+        const { lastRun: _lastRun, lastRuns: _lastRuns, ...standing } = summary.data;
         return toolResult({
           ...standing,
           latestSweeps: latest,
@@ -122,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
@@ -141,7 +166,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         const { productId: id, ...filters } = params;
         const result = await client.listFindings(id, filters);
         return toolResult({
-          ...page(pickFields(result.data as Row[], FINDING_ROW_FIELDS), result.nextCursor),
+          ...page(pickFields(result.data, FINDING_ROW_FIELDS), result.nextCursor),
           ...(typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {}),
         });
       })
@@ -159,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(
@@ -171,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.",
@@ -186,24 +221,13 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     },
     (params) =>
       runTool(async () => {
-        const standing = (await client.getPolicyStanding(params.productId)).data as Row;
-        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 standing = (await client.getPolicyStanding(params.productId)).data;
+        const controls = Array.isArray(standing.controls) ? standing.controls : [];
+        const violations = Array.isArray(standing.divergences) ? standing.divergences : [];
         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,
@@ -268,7 +292,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
               ...(params.expiresAt !== undefined ? { ignoreExpiresAt: params.expiresAt } : {}),
             }
           : { status: 'open' as const };
-        const finding = (await client.updateFinding(params.findingId, body)).data as Row;
+        const finding = (await client.updateFinding(params.findingId, body)).data;
         return toolResult(pickFields([finding], [...FINDING_ROW_FIELDS, 'ignoreNote'])[0]);
       })
   );
@@ -299,10 +323,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     (params) =>
       runTool(async () => {
         if (!params.wholeGroup) {
-          const fixed = (await client.remediateFinding(params.productId, params.findingId)).data as {
-            finding?: Row;
-            backlogItemId?: unknown;
-          };
+          const fixed = (await client.remediateFinding(params.productId, params.findingId)).data;
           return toolResult({
             backlogItemId: fixed.backlogItemId,
             finding: fixed.finding ? pickFields([fixed.finding], FINDING_ROW_FIELDS)[0] : null,
@@ -311,7 +332,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         // The group is the finding's own: the route matches the package (or
         // rule), the installed version and the repository exactly, so they are
         // taken from the finding rather than asked of the caller.
-        const finding = (await client.getFinding(params.findingId)).data as Row;
+        const finding = (await client.getFinding(params.findingId)).data;
         // The finding is read by its own id, so it is held to the product the
         // group fix is sent to, as the single-finding route holds it.
         if (finding.productId !== params.productId) {

package/src/tools/markdown.ts

@@ -1,7 +1,13 @@
 import { fromMarkdown } from 'mdast-util-from-markdown';
 import { toMarkdown } from 'mdast-util-to-markdown';
 import type { Heading, Node, Parent, PhrasingContent } from 'mdast';
-import { isRecord, sectionContent, sectionsOf } from './sections.js';
+import { isRecord, isSectionObject, sectionContent, sectionsOf, type StoredDocument } from './sections.js';
+
+/** A document as rendered: its data, and the facts its title and header line name. */
+interface RenderedDocument extends StoredDocument {
+  name?: unknown;
+  type?: unknown;
+}
 
 /**
  * A document as text an IDE can attach: the name as the title, one line of
@@ -11,7 +17,7 @@ import { isRecord, sectionContent, sectionsOf } from './sections.js';
  * described, and a document that is no section map at all is handed over as
  * JSON.
  */
-export function renderDocument(doc: Record<string, unknown>): { mimeType: string; text: string } {
+export function renderDocument(doc: RenderedDocument): { mimeType: string; text: string } {
   const data = isRecord(doc.data) ? doc.data : null;
   const sections = data ? sectionsOf(data) : null;
   if (!data || !sections) return { mimeType: 'application/json', text: JSON.stringify(doc, null, 2) };
@@ -25,7 +31,7 @@ export function renderDocument(doc: Record<string, unknown>): { mimeType: string
   // the headings: a heading is text a section could forge, this line is not.
   const core = Object.keys(sections).filter((id) => {
     const section = sections[id];
-    return isRecord(section) && section.priority === 'core';
+    return isSectionObject(section) && section.priority === 'core';
   });
   if (core.length > 0) facts.push(`core sections: ${core.join(', ')}`);
   if (facts.length > 0) lines.push('', facts.join(' | '));
@@ -120,11 +126,13 @@ function atxOf(depth: Heading['depth'], children: PhrasingContent[]): string {
 
 /** The section's title when it carries one, else its id. */
 function sectionTitle(section: unknown, id: string): string {
-  return isRecord(section) && typeof section.title === 'string' && section.title.trim() ? section.title.trim() : id;
+  return isSectionObject(section) && typeof section.title === 'string' && section.title.trim()
+    ? section.title.trim()
+    : id;
 }
 
 /** The mime type a read will answer with, for a list entry that must not disagree with it. */
-export function mimeTypeOf(doc: Record<string, unknown>): string {
+export function mimeTypeOf(doc: StoredDocument): string {
   const data = isRecord(doc.data) ? doc.data : null;
   return data && sectionsOf(data) ? 'text/markdown' : 'application/json';
 }

package/src/tools/observe.ts

@@ -1,7 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { ENVIRONMENT_TYPES } from '@taiga/types';
 import { z } from 'zod';
-import { TaigaApiError, type TaigaClient } from '../client.js';
+import type { Deployment, Environment } from '@taiga/types';
+import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { withNotFoundHint } from './hints.js';
@@ -16,8 +17,6 @@ import { page, pickFields } from './summarize.js';
  * provider and is an administrator's action in the web.
  */
 
-type Row = Record<string, unknown>;
-
 /** A deployment as a line of history: what shipped where, how it ended, and who shipped it. */
 const DEPLOYMENT_FIELDS = [
   'id',
@@ -39,6 +38,22 @@ const DEPLOYMENT_FIELDS = [
 
 const ENVIRONMENT_FIELDS = ['id', 'name', 'slug', 'type', 'ordinal', 'status', 'isProtected', 'url'] as const;
 
+/**
+ * Deployments as lines, each naming the repository that deployed it: every
+ * repository runs its own deployment in an environment, so two running in
+ * production are two repositories, not a contradiction (PRO-2528).
+ */
+function deploymentLines(rows: WithoutTenant<Deployment>[]) {
+  return rows.map((row) => {
+    // `metadata` is an untyped jsonb column until PRO-2515 types it.
+    const repository = row.metadata?.['repositoryFullName'];
+    return {
+      ...pickFields([row], DEPLOYMENT_FIELDS)[0],
+      repository: typeof repository === 'string' ? repository : null,
+    };
+  });
+}
+
 const environmentId = idInput('environment', 'taiga_list_environments lists them; a product ID is not one');
 /** The windows the pages offer, as the schema's own values rather than a number checked afterwards. */
 const windowDays = z.literal([30, 60, 90]).optional().describe('Days to look back: 30, 60 or 90 (default 30)');
@@ -62,12 +77,15 @@ async function part<T>(read: () => Promise<T>): Promise<{ value: T } | { unavail
 const ENVIRONMENT_PAGES = 5;
 
 /** Every environment of a product, page by page, and whether any were left past the guard. */
-async function allEnvironments(client: TaigaClient, product: string): Promise<{ rows: Row[]; more: boolean }> {
-  const rows: Row[] = [];
+async function allEnvironments(
+  client: TaigaClient,
+  product: string
+): Promise<{ rows: WithoutTenant<Environment>[]; more: boolean }> {
+  const rows: WithoutTenant<Environment>[] = [];
   let cursor: string | undefined;
   for (let pageNo = 0; pageNo < ENVIRONMENT_PAGES; pageNo++) {
     const result = await client.listEnvironments(product, { limit: 100, cursor });
-    rows.push(...(result.data as Row[]));
+    rows.push(...result.data);
     if (!result.nextCursor) return { rows, more: false };
     cursor = result.nextCursor;
   }
@@ -104,23 +122,23 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
           }),
           part(() => client.getDeploymentSyncStatus(params.productId)),
         ]);
-        const now = current.data as { current?: Row[]; deploying?: Row[] };
+        const now = current.data;
         // An empty answer says why, as the maintenance read does: no
         // environment, or none deployed to yet, is not "nothing is wrong".
         const note =
           environments.rows.length === 0
             ? 'This product has no environments yet: an environment is defined with taiga_define_environment, ' +
               'and its deployments are mirrored from the provider once it is.'
-            : (history.data as Row[]).length === 0 && !params.cursor
+            : history.data.length === 0 && !params.cursor
               ? 'No deployments recorded yet: none was mirrored from the provider (syncStatus says when it last ' +
                 'synced), or nothing has been deployed.'
               : null;
         return toolResult({
           environments: pickFields(environments.rows, ENVIRONMENT_FIELDS),
           ...(environments.more ? { moreEnvironments: true } : {}),
-          running: pickFields(now.current ?? [], DEPLOYMENT_FIELDS),
-          deploying: pickFields(now.deploying ?? [], DEPLOYMENT_FIELDS),
-          history: page(pickFields(history.data as Row[], DEPLOYMENT_FIELDS), history.nextCursor),
+          running: deploymentLines(now.current ?? []),
+          deploying: deploymentLines(now.deploying ?? []),
+          history: page(deploymentLines(history.data), history.nextCursor),
           ...('value' in sync
             ? { syncStatus: sync.value.data }
             : { syncStatus: null, syncUnavailable: sync.unavailable }),
@@ -226,7 +244,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
         }
         const value = (p: { value: { data: unknown } } | { unavailable: string }) =>
           'value' in p ? p.value.data : { unavailable: p.unavailable };
-        const envHealth = (health.data as Row[]).filter((row) => row.environmentId === env);
+        const envHealth = health.data.filter((row) => row.environmentId === env);
         return toolResult({
           health: envHealth,
           ...(envHealth.length === 0
@@ -267,7 +285,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const created = (await client.createEnvironment(params.productId, { name: params.name, type: params.type }))
-          .data as Row;
+          .data;
         return toolResult(pickFields([created], ENVIRONMENT_FIELDS)[0]);
       })
   );
@@ -295,7 +313,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
         if (Object.values(changes).every((value) => value === undefined)) {
           return toolError('VALIDATION_ERROR', 'Change at least one of name, type or url.');
         }
-        const updated = (await client.updateEnvironment(id, changes)).data as Row;
+        const updated = (await client.updateEnvironment(id, changes)).data;
         return toolResult(pickFields([updated], ENVIRONMENT_FIELDS)[0]);
       })
   );

package/src/tools/product-documents.ts

@@ -8,7 +8,7 @@ import {
   SETUP_REQUIRED_DOCUMENT_TYPES,
 } from '@taiga/types';
 import { z } from 'zod';
-import type { TaigaClient, TaigaDocument } from '../client.js';
+import type { TaigaClient } from '../client.js';
 import { OPERATE, WRITE } from './annotations.js';
 import { type DocumentScope, publishDraft, sectionContentInput, sectionIdFrom, updateSection } from './documents.js';
 import { runTool, toolError, toolResult } from './errors.js';
@@ -25,8 +25,6 @@ import { jobReport } from './jobs.js';
  * code and is not edited.
  */
 
-type Row = Record<string, unknown>;
-
 /** The plan-side documents people edit; the codebase snapshot is derived from the code, never written. */
 type EditableType = Exclude<ProductDocumentType, 'codebase_snapshot'>;
 const EDITABLE_TYPES = PRODUCT_DOCUMENT_TYPES.filter((type): type is EditableType => type !== 'codebase_snapshot') as [
@@ -56,7 +54,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
 
   const productScope = (product: string, type: string): DocumentScope => ({
     getDraft: () => client.getProductDocumentDraft(product, type),
-    getPublished: async () => (await client.getProductDocument(product, type, 'plan')) as { data: TaigaDocument },
+    getPublished: () => client.getProductDocument(product, type, 'plan'),
     saveDraft: (data) => client.saveProductDocumentDraft(product, type, { data }),
     publish: () => client.publishProductDocument(product, type),
   });
@@ -95,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,
     },
@@ -155,7 +153,7 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
               targetId: params.productId,
               documentType: params.type,
             })
-          ).data as Row;
+          ).data;
           return toolResult(jobReport(job));
         })
     );

package/src/tools/products.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { TaigaApiError, type TaigaClient } from '../client.js';
+import type { Product, ProductDocumentListItem } from '@taiga/types';
+import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { READ_ONLY } from './annotations.js';
 import { idInput, pagination, productId, remoteUrl, slug } from './inputs.js';
 import {
@@ -14,14 +15,17 @@ 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>;
+type DocumentRow = WithoutTenant<ProductDocumentListItem>;
+
 /** What a product row needs to say for the model to pick one and read it in full. */
 // 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;
@@ -72,11 +76,11 @@ const originInput = z
  * than being folded into a truncated list that would read as a complete one.
  */
 async function linkedProducts(client: TaigaClient, repository: string, repositoryHost: string) {
-  const products: Record<string, unknown>[] = [];
+  const products: ProductRow[] = [];
   let cursor: string | undefined;
   for (let page = 0; page < RESOLVE_PAGE_LIMIT; page += 1) {
     const result = await client.listProducts({ repository, repositoryHost, limit: PAGE_SIZE, cursor });
-    products.push(...(result.data as Record<string, unknown>[]));
+    products.push(...result.data);
     if (!result.nextCursor) return { products, truncated: false };
     cursor = result.nextCursor;
   }
@@ -84,15 +88,14 @@ async function linkedProducts(client: TaigaClient, repository: string, repositor
 }
 
 /** A document list row as the model sees it: the summary fields plus a display name and the staleness fact. */
-function documentSummaries(rows: unknown[]): Record<string, unknown>[] {
-  const typed = rows as Record<string, unknown>[];
-  return pickFields(typed, DOCUMENT_SUMMARY_FIELDS).map((picked, index) => {
+function documentSummaries(rows: DocumentRow[]) {
+  return pickFields(rows, DOCUMENT_SUMMARY_FIELDS).map((picked, index) => {
     // `outdated` on the wire is the list of sources that moved on; the model
     // needs the fact, not the tree. Published plan rows carry it: null when
     // current, a source list when not. A draft has nothing published to be
     // outdated (the API stamps it null too) and reality rows carry no such
     // field: no fact for either.
-    const outdated = typed[index]!.outdated as { sources?: unknown[] } | null | undefined;
+    const outdated = rows[index]!.outdated;
     const fact =
       picked.isDraft !== false
         ? undefined
@@ -110,12 +113,14 @@ function documentSummaries(rows: unknown[]): Record<string, unknown>[] {
   });
 }
 
+type DocumentSummary = ReturnType<typeof documentSummaries>[number];
+
 interface Timelines {
   projectType: 'greenfield' | 'brownfield';
   defaultOrigin: ProductDocumentOrigin;
   /** The side's summaries, or null when the API could not list it (see `unlistable`). */
-  plan: Record<string, unknown>[] | null;
-  reality: Record<string, unknown>[] | null;
+  plan: DocumentSummary[] | null;
+  reality: DocumentSummary[] | null;
   /** Why a null side is null, in the words the notes and a miss message use. */
   unlistable: Partial<Record<ProductDocumentOrigin, string>>;
   notes: string[];
@@ -134,7 +139,7 @@ function unlistableNote(origin: ProductDocumentOrigin, reason: unknown): string
  * so a caller that already holds it passes it in.
  */
 async function documentTimelines(client: TaigaClient, id: string, product?: ProductSettingsView): Promise<Timelines> {
-  const loaded = product ?? ((await client.getProduct(id)).data as ProductSettingsView);
+  const loaded = product ?? (await client.getProduct(id)).data;
   // Each side on its own: one side the API cannot list is reported as
   // unreadable, not as empty, and never hides the side that did answer.
   // Both failing is the API failing, and that is an error like any other.
@@ -142,7 +147,7 @@ async function documentTimelines(client: TaigaClient, id: string, product?: Prod
     PRODUCT_DOCUMENT_ORIGINS.map((o) => client.listProductDocuments(id, { origin: o, limit: PAGE_SIZE }))
   );
   if (settled.every((result) => result.status === 'rejected')) throw settled[0]!.reason;
-  const sides: Partial<Record<ProductDocumentOrigin, Record<string, unknown>[] | null>> = {};
+  const sides: Partial<Record<ProductDocumentOrigin, DocumentSummary[] | null>> = {};
   const unlistable: Partial<Record<ProductDocumentOrigin, string>> = {};
   PRODUCT_DOCUMENT_ORIGINS.forEach((o, index) => {
     const result = settled[index]!;
@@ -167,10 +172,10 @@ async function documentTimelines(client: TaigaClient, id: string, product?: Prod
   };
 }
 
-const isPublished = (row: Record<string, unknown>) => row.isDraft === false;
+const isPublished = (row: { isDraft?: boolean }) => row.isDraft === false;
 
 /** `specification (v2), architecture (draft)` for one side. */
-function sideList(rows: Record<string, unknown>[]): string {
+function sideList(rows: DocumentSummary[]): string {
   return rows
     .map((row) => `${String(row.type)} (${isPublished(row) ? `v${String(row.version)}` : 'draft'})`)
     .join(', ');
@@ -218,7 +223,7 @@ export async function resolveProductRef(
   accepted: readonly string[],
   /** How the caller's arguments are passed, for the message when none was given (a slash command's usage). */
   usage?: string
-): Promise<{ product: Record<string, unknown> } | { refusal: { code: string; message: string } }> {
+): Promise<{ product: ProductRow } | { refusal: { code: string; message: string } }> {
   const refusal = (code: string, message: string) => ({ refusal: { code, message } });
   const given = [ref.productId, ref.slug, ref.remoteUrl].filter((v) => v !== undefined).length;
   if (given !== 1) {
@@ -228,7 +233,7 @@ export async function resolveProductRef(
   }
   if (ref.productId) {
     try {
-      return { product: (await client.getProduct(ref.productId)).data as Record<string, unknown> };
+      return { product: (await client.getProduct(ref.productId)).data };
     } catch (error) {
       if (!isMissOrRefusal(error)) throw error;
       return refusal(
@@ -238,7 +243,7 @@ export async function resolveProductRef(
     }
   }
   if (ref.slug) {
-    const [product] = (await client.listProducts({ slug: ref.slug, limit: 1 })).data as Record<string, unknown>[];
+    const [product] = (await client.listProducts({ slug: ref.slug, limit: 1 })).data;
     if (!product) {
       return refusal(
         'NOT_FOUND',
@@ -341,9 +346,7 @@ 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 as Record<string, unknown>[], PRODUCT_SUMMARY_FIELDS), result.nextCursor)
-            );
+            return toolResult(page(pickFields(result.data, PRODUCT_SUMMARY_FIELDS), result.nextCursor));
           }
           if (params.cursor !== undefined) return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
           const found = await searchPages(
@@ -374,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(),
@@ -386,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);
         })
     );
 
@@ -483,11 +488,11 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
           // The product's own timeline when none is asked for; the API's
           // default is plan, which is the wrong side of an imported product.
           let product: ProductSettingsView | undefined;
-          if (!params.origin) product = (await client.getProduct(params.productId)).data as ProductSettingsView;
+          if (!params.origin) product = (await client.getProduct(params.productId)).data;
           const origin = params.origin ?? defaultOriginFor(product, params.type);
           try {
             const result = await client.getProductDocument(params.productId, params.type, origin);
-            const doc = stripProvenance(result.data as Record<string, unknown>);
+            const doc = stripProvenance(result.data);
             if (!params.sections) return toolResult(doc);
             return sectionReadResult(doc, params.sections, `${origin} ${params.type}`);
           } catch (error) {
@@ -496,7 +501,7 @@ export function registerProductTools(server: McpServer, client: TaigaClient) {
             // miss, so the product read propagates. The lists after it are
             // best effort per side (documentTimelines); only both failing
             // propagates, as the API failing.
-            product ??= (await client.getProduct(params.productId)).data as ProductSettingsView;
+            product ??= (await client.getProduct(params.productId)).data;
             const timelines = await documentTimelines(client, params.productId, product);
             return toolError('NOT_FOUND', describeMiss(params.type, origin, timelines, product));
           }