@taiga-ai/mcp-server 0.26.0-dev.487 → 0.26.0-dev.489

package/dist/index.js

@@ -124,6 +124,14 @@ function parseErrorBody(body) {
 */
 var TaigaClient = class {
 	baseUrl;
+	/** The API this client talks to, as its host: the environment a reader is in (PRO-2823). */
+	get apiHost() {
+		try {
+			return new URL(this.baseUrl).host;
+		} catch {
+			return this.baseUrl;
+		}
+	}
 	apiKey;
 	introspection = null;
 	constructor(opts) {
@@ -269,6 +277,9 @@ var TaigaClient = class {
 		if (opts?.status) params.set("status", opts.status);
 		if (opts?.planningStatus) params.set("planningStatus", opts.planningStatus);
 		if (opts?.category) params.set("category", opts.category);
+		if (opts?.state) params.set("state", opts.state);
+		if (opts?.open) params.set("open", "true");
+		if (opts?.order) params.set("order", opts.order);
 		if (opts?.includeArchived) params.set("includeArchived", "true");
 		if (opts?.limit) params.set("limit", String(opts.limit));
 		if (opts?.cursor) params.set("cursor", opts.cursor);
@@ -870,9 +881,6 @@ const PRODUCT_DOCUMENT_DISPLAY_NAMES = {
 const PRODUCT_DOCUMENT_ORIGINS = ["plan", "reality"];
 //#endregion
 //#region ../../packages/types/dist/backlog.js
-/** Dispositions that end an item's pipeline life: settled work neither blocks
-*  dependants nor counts toward completion denominators. */
-const SETTLED_BACKLOG_STATUSES = ["done", "canceled"];
 /**
 * The initiative's STORED state on the line board (PRO-1305, phase 1).
 *
@@ -922,11 +930,6 @@ const LINE_STATES = [
 	"plan",
 	"build"
 ];
-/** Finished work: settled by a person or a merge, or archived. The one
-*  predicate every "can this still move / plan / build" guard reads. */
-function isSettledOrArchived(item) {
-	return item.archivedAt != null || SETTLED_BACKLOG_STATUSES.includes(item.status);
-}
 /**
 * The columns a person can drop an initiative into by hand.
 *
@@ -2245,7 +2248,7 @@ const DOCUMENT_INPUTS = Object.freeze({
 * reads as deleted) and fields they explain would simply be missing. So it
 * refuses to start, and says what to do.
 */
-function apiLevelProblem(introspection, apiUrl, required = 1, version = SERVER_VERSION) {
+function apiLevelProblem(introspection, apiUrl, required = 2, version = SERVER_VERSION) {
 	const offered = introspection.mcpApiLevel ?? 0;
 	if (offered >= required) return null;
 	return `The Taiga API at ${apiUrl} is older than @taiga-ai/mcp-server ${version} needs (API level ${offered}, needs ${required}). Run the version published for it, or wait for that API to be updated; an earlier release of this package works against it.`;
@@ -2502,7 +2505,7 @@ const BY_ARGUMENT = {
 /** Where an argument means something else on one tool, or the tool's 404 needs its own word. */
 const BY_TOOL = {
 	taiga_resolve_action: () => "taiga_list_action_required lists the items with their IDs.",
-	taiga_get_plan: (said) => /\bplan\b/i.test(said) ? "taiga_get_initiative says whether one is being generated (planningStatus planning) or failed, and taiga_plan_again asks for a new one." : ITEM_ID_HINT
+	taiga_get_plan: (said) => /\bplan\b/i.test(said) ? "taiga_get_initiative's situation says whether one is being planned or failed, and taiga_plan_again asks for a new one." : ITEM_ID_HINT
 };
 /**
 * What the API calls the thing each ID names, as its 404 says it ("Environment
@@ -4033,7 +4036,7 @@ const FAILED_REASON_MEANS = {
 * text out: its first sentence is in the outcome, and taiga_get_run has it all.
 */
 function readableRun(run, opts = {}) {
-	const { prDraft, error, reviewEscalation, runtime: _runtime, ...rest } = run;
+	const { prDraft, error, reviewEscalation, runtime: _runtime, origin, ...rest } = run;
 	const said = runOutcome(run);
 	const means = FAILED_REASON_MEANS[String(run["failedReason"])];
 	const hardening = run["hardeningResult"];
@@ -4042,13 +4045,14 @@ function readableRun(run, opts = {}) {
 	const scan = scanSaid(hardening);
 	return {
 		...rest,
+		...origin === void 0 ? {} : { origin: origin === "backlog" ? "initiative" : origin },
 		...means ? { failedReasonMeans: means } : {},
 		...scan && scan.gaps + (scan.verdict === "not_scanned" ? 1 : 0) > 0 ? { scanCoverage: scan.said } : {},
 		...blocking > 0 ? { hardeningNote: hardeningSaid(blocking, named) } : {},
 		...opts.row || error === void 0 ? {} : { error },
 		...opts.row || reviewEscalation === void 0 ? {} : { reviewEscalation },
 		...typeof rest["prNumber"] === "number" || rest["prUrl"] ? { prDraft } : {},
-		...said ?? {}
+		...said ? { outcome: said.outcome } : {}
 	};
 }
 /** Distinct initiatives a run list reads to say which moved on; past this a waiting row says it was not checked. */
@@ -4100,7 +4104,8 @@ const INITIATIVE_ENDED = {
 /** A readable run row that also says when its initiative ended while its pull request waited. */
 function withInitiativeState(row, states) {
 	const state = states.get(String(row["backlogItemId"]));
-	if (!["gated", "unmerged"].includes(String(row["disposition"]))) return row;
+	const status = String(row["status"]);
+	if (!(BUILD_RUN_STATUSES.includes(status) && ["gated", "unmerged"].includes(landedDisposition(status, row["prMerged"] === true)))) return row;
 	if (state === "unchecked") return {
 		...row,
 		outcome: `${String(row["outcome"])} Whether its initiative still wants it was not checked.`
@@ -4111,7 +4116,6 @@ function withInitiativeState(row, states) {
 	const open = row["prState"] === "open" ? ` ${pr} is still open on the forge.` : "";
 	return {
 		...row,
-		disposition: "abandoned",
 		actions: [],
 		outcome: `Its initiative ${ended}, so nobody is waiting on this run.${open}`
 	};
@@ -4220,19 +4224,20 @@ function registerBuildTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_list_runs", {
 		title: "List runs",
-		description: "List coding agent runs, newest first: branch, pull request, step progress, outcome (one sentence), actions and disposition: in_flight, gated (a person owes a review and merge), succeeded (merged), failed, stopped, rejected (pull request closed unmerged), unmerged, or abandoned (its initiative ended: done, canceled, archived or deleted). Without productId, every product's runs; active: true keeps running ones. taiga_get_run reads one; carry work on from the initiative (taiga_resume_initiative).",
+		description: "List coding agent runs, newest first: status, branch, pull request, step progress, actions and outcome, one sentence saying how it stands: running, waiting for a person to review and merge, merged, failed, stopped, its pull request closed unmerged, or nobody waiting on it because its initiative ended. Without productId, every product's runs; active: true keeps running ones. taiga_get_run reads one; carry work on from the initiative (taiga_resume_initiative).",
 		inputSchema: z.object({
 			productId: productId.optional(),
-			initiativeId: idInput("initiative", "taiga_list_initiatives (query finds one by title) gives it").optional().describe("Only this initiative's runs -- get from taiga_list_initiatives; needs productId"),
+			initiativeId: idInput("initiative", "taiga_list_initiatives (query finds one by title) gives it").optional().describe("Only this initiative's runs -- get from taiga_list_initiatives"),
 			active: z.boolean().optional().describe("Only runs the agent is executing now (cloning through reviewing; a queued pending run is not yet executing and is left out); for the org-wide list"),
 			...pagination
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		if (!params.productId && params.initiativeId) return toolError("VALIDATION_ERROR", "initiativeId narrows the runs of one product: pass its productId as well (the initiative carries it).");
-		if (params.productId && params.active) return toolError("VALIDATION_ERROR", "active narrows the org-wide list only: omit productId, or read the product's runs and judge each by its status.");
-		if (params.productId) {
-			const result = await client.listBuildRuns(params.productId, {
+		if (params.active && (params.productId || params.initiativeId)) return toolError("VALIDATION_ERROR", "active narrows the org-wide list only: omit productId and initiativeId, or read the product's runs and judge each by its status.");
+		if (!params.productId && params.initiativeId && !client.hasCapability("backlog:read")) return toolError("VALIDATION_ERROR", "This key cannot read initiatives, so it cannot find the initiative's product: pass productId as well.");
+		const productIdOf = params.productId ?? (params.initiativeId ? (await client.getBacklogItem(params.initiativeId)).data.productId : void 0);
+		if (productIdOf) {
+			const result = await client.listBuildRuns(productIdOf, {
 				backlogItemId: params.initiativeId,
 				limit: params.limit,
 				cursor: params.cursor
@@ -4245,7 +4250,7 @@ function registerBuildTools(server, client) {
 	}));
 	server.registerTool("taiga_get_run", {
 		title: "Get run",
-		description: "Read one run with its steps: outcome, disposition, pull request, hardening (scanCoverage names the security scanners that did not run, and why; hardeningResult.verdict is passed only when every one ran), and per step its title, status, commit, files changed, verification and headline (first paragraph of the agent's report). verification is Taiga's own check after the step (tests, lint, build), so a docs-only step can fail on the repository's failing tests (verificationNote says when one failed throughout). A failed or stopped run has stoppedIn, lastProgressAt and failedReasonMeans (what its failedReason means). full: true adds complete instructions and reports. actions: resume and retry_from_failed_step are taiga_resume_initiative; webOnlyActions (start_over) are in the web; to stop it, move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
+		description: "Read one run with its steps: status, outcome, pull request, hardening (scanCoverage names the security scanners that did not run, and why; hardeningResult.verdict is passed only when every one ran), and per step its title, status, commit, files changed, verification and headline (first paragraph of the agent's report). verification is Taiga's own check after the step (tests, lint, build), so a docs-only step can fail on the repository's failing tests (verificationNote says when one failed throughout). A failed or stopped run has stoppedIn, lastProgressAt and failedReasonMeans (what its failedReason means). full: true adds complete instructions and reports. actions: resume and retry_from_failed_step are taiga_resume_initiative; webOnlyActions (start_over) are in the web; to stop it, move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
 		inputSchema: z.object({
 			runId,
 			full: z.boolean().optional().describe("Carry each step's complete instructions and report (default false: a summary)")
@@ -4372,9 +4377,7 @@ async function queueView(client, product, options = { name: "all" }) {
 		if (item) {
 			Object.assign(row, {
 				title: item.title,
-				state: item.state,
-				planningStatus: item.planningStatus,
-				needsHumanCause: item.needsHumanCause,
+				...standing(item),
 				criteria: criteriaCounts(item),
 				lifecycle: lifecycle ? {
 					turn: lifecycle.turn,
@@ -4406,7 +4409,7 @@ async function queueView(client, product, options = { name: "all" }) {
 	const line = typeof paused === "string" ? `The line is paused (since ${paused}): nothing is planned or built until a person resumes it.` : null;
 	return {
 		linePaused: paused === null ? null : typeof paused === "string",
-		entries: rows,
+		entries: rows.map(({ lifecycle: _lifecycle, runId: _runId, ...row }) => row),
 		waitingOn: line ?? waitingOn(rows),
 		...note ? { note } : {}
 	};
@@ -4452,18 +4455,21 @@ function registerQueueTools(server, client) {
 }
 //#endregion
 //#region src/tools/backlogs.ts
-/** What a list row needs to say for the model to pick an item to read in full. */
+/**
+* What a list row needs to say for the model to pick an item to read in full.
+* One vocabulary for where an initiative stands (PRO-2828): its board column,
+* whose turn it is and the situation sentence. The API's own fields for it
+* (status, planningStatus, needsHumanCause, lifecycle) said the same thing
+* four more ways, and a reviewing agent had to reconcile them; they are in
+* taiga_get_initiative with full: true.
+*/
 const BACKLOG_SUMMARY_FIELDS = [
 	"id",
 	"title",
 	"category",
-	"status",
-	"state",
-	"planningStatus",
 	"priority",
 	"estimate",
 	"origin",
-	"needsHumanCause",
 	"archivedAt",
 	"createdAt",
 	"updatedAt"
@@ -4477,21 +4483,44 @@ const ITEM_OUTCOME_FIELDS = [
 	"id",
 	"productId",
 	"title",
-	"status",
-	"state",
-	"planningStatus",
-	"needsHumanCause",
-	"needsHumanDetail",
 	"autoBuild",
-	"archivedAt",
-	"lifecycle"
+	"archivedAt"
+];
+/** The fields of an initiative's summary read: its row, plus what it is about. */
+const ITEM_SUMMARY_FIELDS = [
+	...BACKLOG_SUMMARY_FIELDS,
+	"productId",
+	"description",
+	"autoBuild",
+	"dependencies"
 ];
+/** How much of a description a summary read carries; full: true has the rest. */
+const DESCRIPTION_IN_SUMMARY = 600;
+/**
+* Where an initiative stands, in the one vocabulary every read uses
+* (PRO-2828): its board column, whose turn it is, the situation sentence, and
+* its latest run to open with taiga_get_run.
+*/
+function standing(item) {
+	const life = item["lifecycle"];
+	const run = life?.latestBuild;
+	const situation = situationOf(item);
+	return {
+		column: typeof item["state"] === "string" ? item["state"] : null,
+		turn: typeof life?.turn === "string" ? life.turn : null,
+		...situation ? { situation } : {},
+		latestRun: run && typeof run.id === "string" ? {
+			id: run.id,
+			...typeof run.prNumber === "number" ? { prNumber: run.prNumber } : {}
+		} : null
+	};
+}
 /**
 * What the lifecycle on an initiative says, and the call each next step is.
 * needsHumanCause is only the line's flag; a plan that failed outside the line
 * leaves it null, and the lifecycle is what says why and what moves it on.
 */
-const LIFECYCLE_MEANING = "situation says in a sentence where it stands and what moves it on. lifecycle.cta names the next call: start_plan taiga_queue_initiative, retry_plan taiga_plan_again (planFailureCause says why), start_build taiga_approve_plan, resume_build taiga_resume_initiative, retry_build a fresh run (web only; off the line, taiga_queue_initiative instead, as situation says), review_pr and view_pr the pull request. needsHumanCause is set only when the line stopped on it.";
+const LIFECYCLE_MEANING = "situation says in a sentence where it stands and names the next call; turn says whose move it is (you, agent, or idle: nobody owes one).";
 /** The move each call to action is, in the tools' words. */
 const CTA_MOVE = {
 	start_plan: "taiga_queue_initiative puts it on the line to be planned and built (paid work: ask first)",
@@ -4504,8 +4533,8 @@ const CTA_MOVE = {
 };
 /** The move for an initiative off the line whose last run did not land: there is no line to take it off (PRO-2840). */
 const OFF_THE_LINE_MOVE = "taiga_queue_initiative puts it back on the line (paid work: ask first)";
-/** What happens to a queued initiative whose last run did not land: the line plans it again (PRO-2840). */
-const REQUEUED_MOVE = "the line plans it again when its turn comes";
+/** What happens to a queued initiative: the line takes it up when its turn comes, replanning a run that did not land (PRO-2840). */
+const REQUEUED_MOVE = "the line takes it up when its turn comes";
 /** How a run stands, as the end of "its latest run ...", by disposition. */
 const RUN_STANDS = {
 	in_flight: "is running",
@@ -4542,7 +4571,10 @@ function situationOf(item) {
 	const column = typeof item["state"] === "string" ? item["state"] : null;
 	const offTheLine = column !== null && !LINE_STATES.includes(column);
 	const stalled = life.stage === "building" && life.turn !== "agent";
-	const requeued = stalled && column === "queue";
+	const requeued = column === "queue" && (stalled || life.turn === "idle" && life.cta == null);
+	const offTheLineStart = offTheLine && (life.cta === "start_build" || life.cta === "start_plan");
+	if (requeued && !stalled) stage = life.stage === "backlog" ? "Queued" : `Queued, ${stage.charAt(0).toLowerCase()}${stage.slice(1)}`;
+	else if (offTheLineStart && life.stage === "planned") stage = "Planned, off the line";
 	if (stalled) stage = requeued ? "Queued" : offTheLine ? "Off the line" : column === null ? "Its build stopped" : "On the line, but its build stopped";
 	const build = life.latestBuild;
 	if (build && typeof build.status === "string" && life.stage !== "done" && life.stage !== "canceled") {
@@ -4563,7 +4595,7 @@ function situationOf(item) {
 	}
 	const turn = life.turn === "you" ? "A person's turn" : life.turn === "agent" ? "The agent's turn" : null;
 	const handedBack = handbackSaid(build?.reviewEscalation);
-	const move = life.cta === "review_pr" && handedBack ? `a person should ${handbackNextStep(build.reviewEscalation)}` : stalled && offTheLine ? OFF_THE_LINE_MOVE : typeof life.cta === "string" ? CTA_MOVE[life.cta] : void 0;
+	const move = life.cta === "review_pr" && handedBack ? `a person should ${handbackNextStep(build.reviewEscalation)}` : stalled && offTheLine || offTheLineStart && life.stage !== "backlog" ? OFF_THE_LINE_MOVE : typeof life.cta === "string" ? CTA_MOVE[life.cta] : void 0;
 	if (requeued) parts.push(`Nothing to do: ${REQUEUED_MOVE}.`);
 	else if (life.cta === "view_pr") parts.push(`Nothing to do: ${move}.`);
 	else if (turn && move) parts.push(`${turn}: ${move}.`);
@@ -4591,15 +4623,14 @@ function endingSaid(item) {
 	if (next && typeof next.id === "string") said.push(`; superseded by "${String(next.title)}" (${next.id})`);
 	return said.join("");
 }
-/** A row or item with its situation added when it has a lifecycle. */
+/** A row or item with where it stands added (`standing`). */
 function withSituation(item, row = item) {
-	const situation = situationOf(item);
-	return situation ? {
+	return {
 		...row,
-		situation
-	} : row;
+		...standing(item)
+	};
 }
-/** List rows, each with its situation. */
+/** List rows, each with where it stands. */
 function situatedRows(items) {
 	return itemRows(items, BACKLOG_SUMMARY_FIELDS).map((row, index) => withSituation(items[index], row));
 }
@@ -4676,36 +4707,6 @@ const outcomeOf = (item) => withSituation(item, {
 	criteria: criteriaCounts(item)
 });
 const outcome = (item) => toolResult(outcomeOf(item));
-/** The statuses an initiative in each board column can have: the column decides it (statusForState, PRO-2828). */
-const COLUMN_STATUSES = {
-	backlog: [
-		"all",
-		"open",
-		"backlog"
-	],
-	todo: [
-		"all",
-		"open",
-		"backlog"
-	],
-	queue: [
-		"all",
-		"open",
-		"backlog"
-	],
-	plan: [
-		"all",
-		"open",
-		"backlog"
-	],
-	build: [
-		"all",
-		"open",
-		"in_progress"
-	],
-	done: ["all", "done"],
-	canceled: ["all", "canceled"]
-};
 /**
 * Each tool is registered under the capability its route requires, so a
 * key sees exactly what it may call: reads on backlog:read; the board move on
@@ -4738,25 +4739,15 @@ function registerBacklogTools(server, client) {
 function registerBacklogReads(server, client) {
 	server.registerTool("taiga_list_initiatives", {
 		title: "List initiatives",
-		description: "List a product's open initiatives (not done or canceled; status: 'all' for every one): title, category, status, place on the line (backlog, todo, queue, plan, build, done), situation (where it stands and what moves it on) and criteria (acceptance criteria met, confirmed with evidence or checked off by a person; null before planning, so a done initiative can show fewer met than it has). query finds one by title, state one board column; taiga_get_initiative reads it in full. Archived ones are left out unless asked for.",
+		description: "List a product's initiatives, newest first: open ones (not done or canceled) unless column says otherwise. Each row has its title, category, column (backlog, todo, queue, plan, build, done, canceled), turn (you, agent or idle), situation (where it stands and what moves it on, in a sentence), latestRun and criteria (acceptance criteria met; null before planning). query finds one by title; taiga_get_initiative reads one. Archived ones are left out unless asked for.",
 		inputSchema: z.object({
 			productId,
 			query: z.string().trim().min(1).max(200).optional().describe("Part of the title, any case: only the items that contain it"),
-			status: z.enum([
+			column: z.enum([
 				"open",
 				"all",
-				"backlog",
-				"in_progress",
-				"done",
-				"canceled"
-			]).optional().describe("open (default without state): not done or canceled; all: every one; in_progress is the Build column, backlog every other open one"),
-			planningStatus: z.enum([
-				"unplanned",
-				"planning",
-				"planned",
-				"failed"
-			]).optional().describe("Only items whose plan is in this state"),
-			state: z.enum(INITIATIVE_STATES).optional().describe("Only items in this column of the board: backlog, todo, queue, plan, build, done or canceled (status groups them coarser)"),
+				...INITIATIVE_STATES
+			]).optional().describe("open (default): not done or canceled; all: every one; or one column of the board"),
 			category: z.enum([
 				"feature",
 				"bug",
@@ -4768,56 +4759,66 @@ function registerBacklogReads(server, client) {
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		const { query, state, status = state === void 0 ? "open" : "all", ...filters } = params;
-		if (state !== void 0 && !COLUMN_STATUSES[state].includes(status)) return toolError("VALIDATION_ERROR", `No initiative is in the ${state} column with status ${status}: pass state alone, or a status it can have (${COLUMN_STATUSES[state].join(", ")}).`);
+		const { query, column = "open", productId: id, ...filters } = params;
 		const apiFilters = {
 			...filters,
-			status: status === "open" || status === "all" ? void 0 : status
+			order: "newest",
+			...column === "open" ? { open: true } : column === "all" ? {} : { state: column }
 		};
-		const open = status === "open";
-		if (query === void 0 && state === void 0 && !open) {
-			const result = await client.listBacklogItems(params.productId, apiFilters);
+		if (query === void 0) {
+			const result = await client.listBacklogItems(id, apiFilters);
 			return toolResult(page(situatedRows(result.data), result.nextCursor));
 		}
-		if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", "Open items, a board column or a title search answer one page; narrow them, or pass status: 'all' (or one status) to page through every item.");
+		if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", "A title search answers one page; narrow the title, or leave query out to page through a column.");
 		let closedSeen = 0;
-		const needle = (query ?? "").toLowerCase();
-		const found = await searchPages((cursor) => client.listBacklogItems(params.productId, {
+		const needle = query.toLowerCase();
+		const found = await searchPages((cursor) => client.listBacklogItems(id, {
 			...apiFilters,
+			...column === "open" ? { open: void 0 } : {},
 			limit: 100,
 			cursor
-		}), query ?? "", (row) => [row.title], params.limit ?? 25, (row) => {
-			if (state !== void 0 && row.state !== state) return false;
-			if (!open || !["done", "canceled"].includes(row.status)) return true;
-			if (query !== void 0 && String(row.title).toLowerCase().includes(needle)) closedSeen += 1;
+		}), query, (row) => [row.title], params.limit ?? 25, (row) => {
+			if (column !== "open" || !["done", "canceled"].includes(String(row.state))) return true;
+			if (String(row.title).toLowerCase().includes(needle)) closedSeen += 1;
 			return false;
 		});
-		const hidden = query !== void 0 && state === void 0 && !found.more ? closedSeen : 0;
+		const hidden = column === "open" && !found.more ? closedSeen : 0;
 		return toolResult({
 			...page(situatedRows(found.rows), null),
-			...hidden > 0 ? { closedMatches: `${hidden} done or canceled initiative${hidden === 1 ? " also matches" : "s also match"}; status: 'all' lists them.` } : {},
-			...found.more ? { more: "There may be more than the limit carries: narrow it with state or query, or list one status (backlog, in_progress, done or canceled) without them, which pages." } : {}
+			...hidden > 0 ? { closedMatches: `${hidden} done or canceled initiative${hidden === 1 ? " also matches" : "s also match"}; column: 'all' lists them.` } : {},
+			...found.more ? { more: "There may be more than the limit carries: narrow the title, or pick one column." } : {}
 		});
 	}));
 	server.registerTool("taiga_get_initiative", {
 		title: "Get initiative",
-		description: `Read one initiative in full: description, acceptance criteria (which are met), technical context, dependencies and source documents. Read it before implementing. A failed plan carries planFailure (cause, meaning, when, by whom). ${LIFECYCLE_MEANING}`,
-		inputSchema: z.object({ initiativeId }),
+		description: `Read one initiative: where it stands (column, turn, situation, latestRun), its acceptance criteria count and the start of its description. full: true reads it whole before implementing: the whole description, each acceptance criterion and whether it is met, technical context, source documents, and the API's own state fields. A failed plan carries planFailure (cause, meaning, when, by whom). ${LIFECYCLE_MEANING}`,
+		inputSchema: z.object({
+			initiativeId,
+			full: z.boolean().optional().describe("Read it whole: every criterion, technical context and the raw state fields (default false)")
+		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
 		const item = (await client.getBacklogItem(params.initiativeId)).data;
 		const row = item;
-		if (item.planningStatus !== "failed") return toolResult(withSituation(row));
-		const ownCause = item.lifecycle?.planFailureCause;
-		const planFailure = await planFailureOf(client, params.initiativeId, ownCause);
-		return toolResult(withSituation(row, planFailure ? {
-			...item,
-			planFailure
-		} : item));
+		const planFailure = item.planningStatus === "failed" ? await planFailureOf(client, params.initiativeId, item.lifecycle?.planFailureCause) : null;
+		const failure = planFailure ? { planFailure } : {};
+		if (params.full) return toolResult({
+			...withSituation(row),
+			...failure
+		});
+		const summary = itemRows([item], ITEM_SUMMARY_FIELDS)[0];
+		const description = String(summary["description"] ?? "");
+		return toolResult({
+			...withSituation(row, {
+				...summary,
+				description: description.length > DESCRIPTION_IN_SUMMARY ? `${description.slice(0, DESCRIPTION_IN_SUMMARY).trimEnd()}... (full: true has the rest)` : description
+			}),
+			...failure
+		});
 	}));
 	server.registerTool("taiga_get_plan", {
 		title: "Get the active plan",
-		description: "Read an initiative's active plan: its steps in order, each with title, layer, dependencies (the orderIndex of the steps it builds on), files written and read, and resources created. Enough to approve or reject it (taiga_approve_plan, taiga_reject_plan); full: true adds each step's complete instructions (thousands of tokens). NOT_FOUND when there is no active plan yet; planningStatus says whether one is being generated.",
+		description: "Read an initiative's active plan: its steps in order, each with title, layer, dependencies (the orderIndex of the steps it builds on), files written and read, and resources created. Enough to approve or reject it (taiga_approve_plan, taiga_reject_plan); full: true adds each step's complete instructions (thousands of tokens). NOT_FOUND when there is no active plan yet; taiga_get_initiative's situation says whether one is being generated.",
 		inputSchema: z.object({
 			initiativeId,
 			full: z.boolean().optional().describe("Carry each step's complete instructions (default false: a summary)")
@@ -4980,7 +4981,7 @@ function registerReviewGate(server, client) {
 function registerResume(server, client) {
 	server.registerTool("taiga_resume_initiative", {
 		title: "Resume initiative",
-		description: "Carry on an initiative the line stopped on (needsHumanCause is set): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished step (committed steps are kept), a refused run start is cleared and retried. Refused (CONFLICT) when nothing is flagged or the cause has no resume; a failed plan with needsHumanCause null (lifecycle.cta retry_plan, planFailureCause says why) needs taiga_plan_again.",
+		description: "Carry on an initiative the line stopped on (its situation says the line stopped on it): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished step (committed steps are kept), a refused run start is cleared and retried. Refused (CONFLICT) when nothing is flagged or the cause has no resume; a plan that failed off the line (its situation names taiga_plan_again, and planFailure says why) needs taiga_plan_again.",
 		inputSchema: z.object({ initiativeId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => outcome((await client.resumeInitiative(params.initiativeId)).data)));
@@ -5160,10 +5161,13 @@ function standingSummary(standing) {
 		const severity = String(violation["severity"] ?? "unknown");
 		bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
 	}
+	const stated = (state) => controls.filter((c) => c["state"] === state).length;
 	return {
 		controls: listed.length,
 		controlsInPolicies: controls.length,
-		controlsWithNothingRecorded: controls.length - listed.length,
+		controlsMet: stated("met"),
+		controlsNotApplicable: stated("not_applicable"),
+		controlsNotAssessed: stated("no_evidence"),
 		violations: violations.length,
 		bySeverity,
 		resolvedViolations: resolved
@@ -5231,11 +5235,12 @@ function registerMaintenanceTools(server, client) {
 	}));
 	server.registerTool("taiga_get_policy_standing", {
 		title: "Get a product's policy standing",
-		description: "How a product stands against the organization's published policies: summary counts, when the documents were assessed, and each violated control with its violations (critical and high only, citing the policy sentence and the contradicting passage) and the work on each. state: breached (open scanner findings map to it, by findingsByTier; routine-only is not urgent) or diverged (the documents contradict it). live: false means the violation's initiative ended without fixing it: it needs a person or a new fix. raisedFor: false means the link is the backlog planner's: it said an initiative a person asked it for would close the violation, which may be a dedicated fix or broader work; true means a fix was raised for it (taiga_fix_policy_violation or the sweep). An unlisted control is not \"passing\" (summary.controlsWithNothingRecorded counts them). full: true adds evidence and resolved ones. Fix with taiga_fix_policy_violation.",
+		description: "How a product stands against the organization's published policies: summary counts, when the documents were assessed, and each violated control with its violations (critical and high only, citing the policy sentence and the contradicting passage) and the work on each. state: breached (open scanner findings map to it, by findingsByTier; routine-only is not urgent) or diverged (the documents contradict it). live: false means the violation's initiative ended without fixing it: it needs a person or a new fix. raisedFor: false means the link is the backlog planner's: it said an initiative a person asked it for would close the violation, which may be a dedicated fix or broader work; true means a fix was raised for it (taiga_fix_policy_violation or the sweep). summary counts the other controls: met or not applicable as the documents show it, or not assessed (no evidence either way, which is no pass). controlId reads one control: its state, the passage behind a verdict, its document violations and how many scanner findings breach it. full: true adds evidence and resolved ones. Fix with taiga_fix_policy_violation.",
 		inputSchema: z.object({
 			productId,
 			full: z.boolean().optional().describe("Carry each violation's evidence and policy excerpt, cut to about 1,500 characters each, and up to 20 resolved violations (default false)"),
-			violationId: idInput("violation", "this tool lists them").optional().describe("Only this violation, in full and uncut: its evidence, policy excerpt and work")
+			violationId: idInput("violation", "this tool lists them").optional().describe("Only this violation, in full and uncut: its evidence, policy excerpt and work"),
+			controlId: z.string().trim().min(1).max(40).optional().describe("Only this control, such as SEC-5.1: whether it is met, not applicable, violated or not assessed, with the passage")
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
@@ -5247,6 +5252,20 @@ function registerMaintenanceTools(server, client) {
 		const note = standing.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;
 		const resolvedAny = Array.isArray(standing.resolvedDivergences) && standing.resolvedDivergences.length > 0;
 		const wording = violations.length > 0 || resolvedAny ? { wordingNote: "A violation's evidence is from its assessedAt; its title and summary may be from when it was first recorded. Where they disagree, the evidence is current." } : {};
+		if (params.controlId && params.violationId) return toolError("VALIDATION_ERROR", "Name either a control (controlId) or one violation (violationId), not both.");
+		if (params.controlId) {
+			const wanted = params.controlId.toUpperCase();
+			const control = controls.find((c) => String(c.controlId).toUpperCase() === wanted);
+			if (!control) return toolError("NOT_FOUND", "No control with that id in this product's policies; taiga_get_document (type, sections: []) lists a policy's controls.");
+			const own = violations.filter((violation) => String(violation["controlId"]).toUpperCase() === wanted);
+			return toolResult({
+				...control,
+				...control.state === "no_evidence" ? { meaning: "Not assessed: no finding or violation is recorded against it, and the documents were not found to show it met. That is no evidence either way, not a pass." } : {},
+				violations: pickFields(own, VIOLATION_FIELDS),
+				...Number(control.findingCount ?? 0) > 0 ? { findingsNote: `${String(control.findingCount)} open scanner finding${control.findingCount === 1 ? "" : "s"} breach it; taiga_list_findings (productId) lists them with the controls each breaches.` } : {},
+				...own.length > 0 ? wording : {}
+			});
+		}
 		if (params.violationId) {
 			const one = [...violations, ...Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences : []].find((violation) => violation["id"] === params.violationId);
 			if (!one) return toolError("NOT_FOUND", "No violation with that ID on this product; this tool without violationId lists them.");
@@ -5405,6 +5424,28 @@ function readWith(row, backlogRead) {
 		default: return;
 	}
 }
+/**
+* The glossary's words for what the API names after its tables (PRO-2823): a reviewer met kind review_backlog,
+* subjectType backlog_item and inbox_task beside a glossary that says initiative and run, and had to infer they
+* were the same things.
+*/
+const KIND_SAID = { review_backlog: "review_initiatives" };
+const SUBJECT_SAID = {
+	backlog_item: "initiative",
+	build_run: "run",
+	inbox_task: "setup_task"
+};
+const kindSaid = (kind) => KIND_SAID[String(kind)] ?? kind;
+/** A setup task row in the glossary's words: the Action Required item it is, by the name taiga_resolve_action takes. */
+function setupTaskRow(row) {
+	const { inboxItemId, inboxItemStatus, alsoFiledAs, ...rest } = row;
+	return {
+		...rest,
+		...inboxItemId !== void 0 ? { actionId: inboxItemId } : {},
+		...inboxItemStatus !== void 0 ? { actionStatus: inboxItemStatus } : {},
+		...Array.isArray(alsoFiledAs) ? { alsoFiledAs: alsoFiledAs.map(setupTaskRow) } : {}
+	};
+}
 /** A summary past its first sentence: review_doc rows quoted two documents, 800 to 1,200 characters each. */
 const SUMMARY_LIMIT = 200;
 function firstSentence(text) {
@@ -5422,9 +5463,12 @@ function itemRow(row, now, full, backlogRead) {
 	const created = typeof row["createdAt"] === "string" ? Date.parse(row["createdAt"]) : NaN;
 	const { summary, status, blocking, ...lean } = rest;
 	const read = readWith(row, backlogRead);
+	const saysNothing = row["kind"] === "setup_manual" && String(summary).trim().toLowerCase() === "manual config";
 	return {
 		...lean,
-		...full ? { summary } : row["kind"] === "review_pr" ? {} : { summary: firstSentence(summary) },
+		kind: kindSaid(lean["kind"]),
+		...typeof lean["subjectType"] === "string" ? { subjectType: SUBJECT_SAID[lean["subjectType"]] ?? lean["subjectType"] } : {},
+		...saysNothing ? {} : full ? { summary } : row["kind"] === "review_pr" ? {} : { summary: firstSentence(summary) },
 		...full || status !== "open" ? { status } : {},
 		...full || blocking === true ? { blocking } : {},
 		...read ? { readWith: read } : {},
@@ -5456,7 +5500,8 @@ function summaryOf(rows, stale) {
 		if (stale.has(String(row["id"]))) entry.stale = (entry.stale ?? 0) + 1;
 		else {
 			entry.open += 1;
-			entry.byKind[String(row["kind"])] = (entry.byKind[String(row["kind"])] ?? 0) + 1;
+			const kind = String(kindSaid(row["kind"]));
+			entry.byKind[kind] = (entry.byKind[kind] ?? 0) + 1;
 		}
 		byProduct.set(key, entry);
 	}
@@ -5512,15 +5557,10 @@ async function staleBacklogReviews(client, rows, out) {
 	const empty = /* @__PURE__ */ new Set();
 	await Promise.all(checked.map(async (productId) => {
 		try {
-			const pages = await Promise.all(["backlog", "in_progress"].map((status) => client.listBacklogItems(productId, {
-				status,
-				limit: 100
-			})));
-			if (pages.some((page) => page.data.some((item) => item.state === "backlog" || item.state === "todo"))) return;
-			if (pages.some((page) => page.nextCursor)) {
-				unchecked += asks.filter((row) => row["productId"] === productId).length;
-				return;
-			}
+			if ((await Promise.all(["backlog", "todo"].map((state) => client.listBacklogItems(productId, {
+				state,
+				limit: 1
+			})))).some((page) => page.data.length > 0)) return;
 			empty.add(productId);
 		} catch (error) {
 			if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
@@ -5603,6 +5643,7 @@ function sameKeyOnce(rows) {
 			id: from["id"],
 			category: from["category"],
 			title: from["title"],
+			inboxItemId: from["inboxItemId"],
 			inboxItemStatus: from["inboxItemStatus"]
 		});
 		if (!isOpen(kept) && isOpen(row)) {
@@ -5702,7 +5743,7 @@ function registerInboxTools(server, client) {
 			...params.cursor === void 0 ? { withTotal: true } : {}
 		});
 		return toolResult({
-			...folded(sameKeyOnce(pickFields(result.data, SETUP_TASK_FIELDS)), result.nextCursor, result.data.length),
+			...folded(sameKeyOnce(pickFields(result.data, SETUP_TASK_FIELDS)).map(setupTaskRow), result.nextCursor, result.data.length),
 			...totalOf(result)
 		});
 	}));
@@ -5955,42 +5996,31 @@ async function policiesPart(client) {
 		sections: Object.keys(sectionsOf(row["data"] ?? {}) ?? {}).length
 	}));
 }
-/** The statuses an item is open in; the API's filter takes one at a time. */
-const OPEN_BACKLOG_STATUSES = ["backlog", "in_progress"];
 /**
-* The items still open: one status-filtered read per open status (the API
-* leaves archived items out), each paged in full up to a cap the result
-* reports. The list is oldest first and the open items are the newest, so a
-* single page would miss exactly the ones that matter. Rows carrying a
-* retired status (readable for a rolling deploy) match neither filter;
-* the settled check below keeps the shape honest for whatever comes back.
+* The items still open, newest first (PRO-2843): one read of the open ones,
+* paged up to a cap the result reports. The API leaves archived items out.
 */
 async function backlogPart(client, productId) {
-	const open = /* @__PURE__ */ new Map();
+	const rows = [];
 	let truncated = false;
 	let pageCapped = false;
-	for (const status of OPEN_BACKLOG_STATUSES) {
-		let cursor;
-		for (let pageIndex = 0;; pageIndex += 1) {
-			if (pageIndex === BACKLOG_PAGE_LIMIT) {
-				truncated = true;
-				pageCapped = true;
-				break;
-			}
-			const result = await client.listBacklogItems(productId, {
-				status,
-				limit: 100,
-				cursor
-			});
-			for (const row of result.data) if (!isSettledOrArchived({
-				status: String(row.status),
-				archivedAt: row.archivedAt ?? null
-			})) open.set(String(row.id), row);
-			if (!result.nextCursor) break;
-			cursor = result.nextCursor;
+	let cursor;
+	for (let pageIndex = 0;; pageIndex += 1) {
+		if (pageIndex === BACKLOG_PAGE_LIMIT) {
+			truncated = true;
+			pageCapped = true;
+			break;
 		}
+		const result = await client.listBacklogItems(productId, {
+			open: true,
+			order: "newest",
+			limit: 100,
+			cursor
+		});
+		rows.push(...result.data);
+		if (!result.nextCursor) break;
+		cursor = result.nextCursor;
 	}
-	const rows = [...open.values()].sort((a, b) => String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0);
 	if (rows.length > BACKLOG_IN_CONTEXT) truncated = true;
 	const byColumn = {
 		backlog: 0,
@@ -6002,9 +6032,9 @@ async function backlogPart(client, productId) {
 	for (const row of rows) if (row.state) byColumn[row.state] = (byColumn[row.state] ?? 0) + 1;
 	return {
 		byColumn,
-		items: situatedRows(rows.slice(-50)),
+		items: situatedRows(rows.slice(0, BACKLOG_IN_CONTEXT)),
 		truncated,
-		...pageCapped ? { note: "More than 1000 open items in one status: only the oldest of them were read, so the newest may be missing here and byColumn counts only those read; taiga_list_initiatives pages the rest." } : {}
+		...pageCapped ? { note: "More than 1000 open items: byColumn counts the newest 1000; taiga_list_initiatives pages the rest." } : {}
 	};
 }
 /**
@@ -6029,7 +6059,7 @@ const CONTEXT_RUN_SAID = [
 	"runNumber",
 	"backlogItemId",
 	"targetTitle",
-	"disposition",
+	"status",
 	"outcome",
 	"failedReasonMeans",
 	"hardeningNote",
@@ -6124,15 +6154,15 @@ async function productContext(client, product, options) {
 		}), null, 2).length;
 	}
 	return toolResult({
-		...result,
-		characters
+		characters,
+		...result
 	});
 }
 function registerContextTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_product_context", {
 		title: "Get product context",
-		description: `Read where a product stands in one call; the first read for any product question. Name it by ID, slug or git remote URL. Returns product (in setup, readiness and next move), factory with its instructions, specification and architecture outlines (section ids, sizes), policies with section counts, open initiatives with a count per board column (byColumn; taiga_list_initiatives status: 'all' has the done and canceled), repositories, the latest five runs (taiga_list_runs has more), and counts for Action Required, open findings and policy violations. A part that failed is under unavailable, one the key cannot read under notGranted; neither shows as empty. documents: budget returns whole sections up to about ${DOCUMENT_BUDGET / 1e3}k characters each, full returns all.`,
+		description: `Read where a product stands in one call; the first read for any product question. Name it by ID, slug or git remote URL. Returns product (in setup, readiness and next move), factory with its instructions, specification and architecture outlines (section ids, sizes), policies with section counts, open initiatives with a count per board column (byColumn; taiga_list_initiatives column: 'all' has the done and canceled), repositories, the latest five runs (taiga_list_runs has more), and counts for Action Required, open findings and policy violations. A part that failed is under unavailable, one the key cannot read under notGranted; neither shows as empty. documents: budget returns whole sections up to about ${DOCUMENT_BUDGET / 1e3}k characters each, full returns all.`,
 		inputSchema: z.object({
 			productId: productId.optional(),
 			slug: slug.optional(),
@@ -22209,29 +22239,19 @@ function judgeItem(until, gate) {
 /** The initiative as a wait reports it: where it is, whose turn, its latest run and its criteria. */
 function itemReport(item) {
 	const run = latestBuildOf(item);
-	const situation = situationOf(item);
 	return {
-		...situation ? { situation } : {},
 		...pickFields([item], [
 			"id",
 			"title",
-			"state",
-			"planningStatus",
-			"needsHumanCause",
-			"needsHumanDetail",
 			"autoBuild"
 		])[0],
-		lifecycle: pickFields([lifecycleOf(item)], [
-			"turn",
-			"stage",
-			"cta",
-			"planFailureCause"
-		])[0],
-		latestBuild: run ? pickFields([run], [
+		...standing(item),
+		latestRun: run ? pickFields([run], [
 			"id",
 			"status",
 			"completedSteps",
 			"totalSteps",
+			"prNumber",
 			"prUrl",
 			"prState",
 			"prMerged",
@@ -22415,6 +22435,10 @@ function withRecoveryHints(tool, schema, inputs, isRead) {
 				message: `${withStop(issue.message)} ${pointers.join(" ")}`
 			};
 		}
+		if (issue.code === "invalid_value") return {
+			...issue,
+			message: `${withStop(issue.message)} Pass one of those values exactly.`
+		};
 		const argument = issue.path?.length === 1 ? String(issue.path[0]) : void 0;
 		const source = argument ? idSource(argument) : void 0;
 		if (source && /received undefined/.test(issue.message)) return {
@@ -22563,7 +22587,7 @@ function registerAllTools(server, client, options = {}) {
 function registerWhoami(server, client, registered) {
 	server.registerTool("taiga_whoami", {
 		title: "Who am I",
-		description: "Read who this API key acts as: the person's email and organization role, the key's scopes (null means every capability the person has), its capabilities, and its tools split into reads, writes, and ask-first writes (paid agent work, changes others see). A tool the key cannot use is not offered at all.",
+		description: "Read who this API key acts as: the API it talks to (api, which says the environment), the person's email and organization role, the key's scopes (null means every capability the person has), its capabilities, and its tools split into reads, writes, and ask-first writes (paid agent work, changes others see). A tool the key cannot use is not offered at all.",
 		inputSchema: z.object({}),
 		annotations: READ_ONLY
 	}, () => runTool(async () => {
@@ -22571,6 +22595,7 @@ function registerWhoami(server, client, registered) {
 		const tools = [...registered.entries()].filter(([name]) => name !== "taiga_whoami");
 		const named = (pick) => tools.filter(([, notes]) => pick(notes)).map(([name]) => name);
 		return toolResult({
+			api: client.apiHost,
 			email: me?.email ?? null,
 			role: me?.role ?? null,
 			scopes: me?.scopes ?? null,
@@ -22613,8 +22638,8 @@ const SERVER_INSTRUCTIONS = [
 	"conversation that specifies a new product. A factory owns products.",
 	"",
 	"**IDs** are UUIDs; the product, factory and initiative lists take query to find one by name. A NOT_FOUND names",
-	"the tool that lists the right ones. Lists page with nextCursor; taiga_list_initiatives lists open ones unless",
-	"status: 'all'. outcome, situation and nextStep are one-sentence summaries; setup writes return readiness.",
+	"the tool that lists the right ones. Lists page with nextCursor; taiga_list_initiatives lists open ones, newest",
+	"first. outcome, situation and nextStep are one-sentence summaries; setup writes return readiness.",
 	"Product documents have two timelines: plan (intent) and reality (from the code).",
 	"",
 	"**Writing.** A tool that writes opens with \"Writes.\", \"Ask first (paid agent work).\" or \"Ask first (others",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.26.0-dev.487",
+  "version": "0.26.0-dev.489",
   "description": "Taiga for AI coding assistants: read products, policies, initiatives and runs, and operate the line, over MCP",
   "mcpName": "ga.tai/mcp-server",
   "type": "module",