ai-dev-requirements 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { dirname, resolve } from "node:path";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod/v4";
 import { McpServer } from "@modelcontextprotocol/server";
-import crypto from "node:crypto";
+import crypto, { createHash, randomBytes } from "node:crypto";
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 //#region ../../src/config/loader.ts
@@ -165,7 +165,7 @@ function loadConfig(startDir) {
 }
 //#endregion
 //#region package.json
-var version = "0.2.0";
+var version = "0.3.0";
 //#endregion
 //#region ../../src/utils/map-status.ts
 const ONES_STATUS_MAP = {
@@ -234,6 +234,39 @@ function workItemKindLabel(kind) {
 	}
 }
 //#endregion
+//#region ../../src/utils/requirement-decomposition.ts
+function canonicalize(value) {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, canonicalize(nested)]));
+	return value;
+}
+function stableHash(value) {
+	return createHash("sha256").update(JSON.stringify(canonicalize(value))).digest("hex");
+}
+function compareNullableDate$1(left, right) {
+	if (left === right) return 0;
+	if (left === null) return 1;
+	if (right === null) return -1;
+	return left.localeCompare(right);
+}
+function sortRequirementTasks(tasks) {
+	return [...tasks].sort((left, right) => compareNullableDate$1(left.planStartDate, right.planStartDate) || compareNullableDate$1(left.planEndDate, right.planEndDate) || left.displayId.localeCompare(right.displayId));
+}
+function buildRequirementDecompositionBaseline(requirement, tasks, metadata = {}) {
+	return {
+		requirementVersion: metadata.version ?? null,
+		requirementUpdatedAt: metadata.updatedAt ?? null,
+		requirementHash: stableHash(requirement),
+		relatedTasksHash: stableHash(tasks)
+	};
+}
+function buildRequirementDecompositionPlanHash(input) {
+	return stableHash(input);
+}
+function isSameRequirementBaseline(left, right) {
+	return left.requirementVersion === right.requirementVersion && left.requirementUpdatedAt === right.requirementUpdatedAt && left.requirementHash === right.requirementHash && left.relatedTasksHash === right.relatedTasksHash;
+}
+//#endregion
 //#region ../../src/adapters/base.ts
 /**
 * Abstract base class for source adapters.
@@ -274,8 +307,12 @@ const TASK_DETAIL_QUERY = `
       project { uuid name }
       parent { uuid number issueType { uuid name } }
       relatedTasks {
-        uuid number name
+        key uuid number name
+        description
+        descriptionText
+        desc_rich: description
         issueType { uuid name }
+        subIssueType { uuid name detailType }
         status { uuid name category }
         assign { uuid name }
       }
@@ -321,7 +358,8 @@ const SEARCH_TASKS_QUERY = `
         status { uuid name category }
         priority { value }
         assign { uuid name }
-        project { uuid name }
+        project { uuid name identifier }
+        parent { uuid number issueType { uuid name } }
       }
     }
   }
@@ -670,6 +708,135 @@ function htmlToPlainText(html) {
 function getTaskDetailText(task) {
 	return task.descriptionText?.trim() || htmlToPlainText(task.desc_rich ?? task.description ?? "");
 }
+function firstString(record, keys) {
+	for (const key of keys) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim()) return value.trim();
+		if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	}
+	return null;
+}
+function taskInfoFieldValue(record, fieldUuid) {
+	const direct = record[fieldUuid];
+	if (typeof direct === "string" && direct.trim()) return direct.trim();
+	const collections = [
+		record.field_values,
+		record.fieldValues,
+		record.fields
+	];
+	for (const collection of collections) if (Array.isArray(collection)) for (const entry of collection) {
+		if (!isRecord(entry)) continue;
+		if (firstString(entry, [
+			"field_uuid",
+			"fieldUuid",
+			"uuid"
+		]) !== fieldUuid) continue;
+		const value = firstString(entry, [
+			"date_value",
+			"dateValue",
+			"value",
+			"field_value",
+			"fieldValue"
+		]);
+		if (value) return value;
+	}
+	else if (isRecord(collection)) {
+		const entry = collection[fieldUuid];
+		if (typeof entry === "string" && entry.trim()) return entry.trim();
+		if (isRecord(entry)) {
+			const value = firstString(entry, [
+				"date_value",
+				"dateValue",
+				"value",
+				"field_value",
+				"fieldValue"
+			]);
+			if (value) return value;
+		}
+	}
+	return null;
+}
+function taskInfoDate(record, kind) {
+	let value;
+	if (kind === "start") value = firstString(record, [
+		"planStartDate",
+		"plan_start_date",
+		"plan_start"
+	]) ?? taskInfoFieldValue(record, "field027");
+	else value = firstString(record, [
+		"planEndDate",
+		"plan_end_date",
+		"plan_end"
+	]) ?? taskInfoFieldValue(record, "field028");
+	if (!value) return null;
+	if (isValidOnesDate(value)) return value;
+	const unixSeconds = Number(value);
+	if (!Number.isFinite(unixSeconds) || unixSeconds <= 0) return null;
+	return (/* @__PURE__ */ new Date(unixSeconds * 1e3)).toISOString().slice(0, 10);
+}
+const ONES_MANHOUR_UNITS_PER_HOUR = 1e5;
+function taskInfoHours(record, keys) {
+	for (const key of keys) {
+		const value = record[key];
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0) continue;
+		return value / ONES_MANHOUR_UNITS_PER_HOUR;
+	}
+	return null;
+}
+function inferredParentDisplayId(task, info) {
+	const explicit = firstString(info, ["parent_display_id", "parentDisplayId"]);
+	if (explicit) return explicit;
+	return task.name.trim().match(/^([A-Z][A-Z0-9]*-\d+)\b/i)?.[1]?.toUpperCase() ?? null;
+}
+function compareNullableDate(left, right) {
+	if (left === right) return 0;
+	if (left === null) return 1;
+	if (right === null) return -1;
+	return left.localeCompare(right);
+}
+async function mapWithConcurrency(items, concurrency, mapper) {
+	const results = [];
+	let cursor = 0;
+	const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+		while (cursor < items.length) {
+			const index = cursor;
+			cursor += 1;
+			results[index] = await mapper(items[index], index);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+function taskInfoDetail(record, fallback) {
+	const text = firstString(record, ["descriptionText", "description_text"]);
+	if (text) return text;
+	const rich = firstString(record, [
+		"desc_rich",
+		"description",
+		"desc"
+	]);
+	return rich ? htmlToPlainText(rich) : getTaskDetailText(fallback);
+}
+function taskDisplayId(info, task, fallbackIdentifier) {
+	const explicit = firstString(info, ["displayId", "display_id"]);
+	if (explicit) return explicit;
+	return fallbackIdentifier ? `${fallbackIdentifier}-${task.number}` : `#${task.number}`;
+}
+function extractHtmlImageReferences(html) {
+	return Array.from(html.matchAll(/<img\b[^>]*>/gi), (match) => {
+		const tag = match[0];
+		const srcMatch = tag.match(/\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
+		const resourceMatch = tag.match(/\bdata-uuid\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
+		return {
+			tag,
+			src: (srcMatch?.[1] ?? srcMatch?.[2] ?? "").replace(/&amp;/gi, "&").trim(),
+			resourceUuid: (resourceMatch?.[1] ?? resourceMatch?.[2] ?? "").trim()
+		};
+	});
+}
+function containsInlineTaskImages(task) {
+	return [task.description, task.desc_rich].some((value) => typeof value === "string" && /<img\b/i.test(value)) || /\[(?:image|图片)\]/i.test(task.descriptionText ?? "");
+}
 function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -1108,7 +1275,11 @@ var OnesAdapter = class extends BaseAdapter {
 		return response.json();
 	}
 	async fetchRelatedActivities(taskKey) {
-		return (await this.onesql(RELATED_ACTIVITIES_QUERY, { key: taskKey }, "Task")).data?.task?.relatedActivities ?? [];
+		try {
+			return (await this.onesql(RELATED_ACTIVITIES_QUERY, { key: taskKey }, "Task")).data?.task?.relatedActivities ?? [];
+		} catch {
+			return [];
+		}
 	}
 	async searchTaskByNumber(taskNumber) {
 		const session = await this.login();
@@ -1293,30 +1464,92 @@ var OnesAdapter = class extends BaseAdapter {
 			return null;
 		}
 	}
+	getAttachmentResourceUuid(image) {
+		if (image.src) try {
+			const source = new URL(image.src, this.config.apiBase);
+			if (source.origin === new URL(this.config.apiBase).origin) {
+				const match = source.pathname.match(/\/res\/attachment\/([^/]+)$/);
+				const resourceUuid = match?.[1] ? decodeOnesPathIdentifier(match[1]) : null;
+				if (resourceUuid) return resourceUuid;
+			}
+		} catch {}
+		return image.resourceUuid;
+	}
 	/**
 	* Replace stale image URLs in HTML with fresh signed URLs from the attachment API.
-	* Extracts data-uuid from <img> tags and resolves fresh URLs in parallel.
+	* Prefer the resource identifier from the attachment URL because ONES data-uuid
+	* can identify the editor node instead of the underlying attachment.
 	*/
-	async refreshImageUrls(html) {
+	async refreshImageUrls(html, freshUrlCache = /* @__PURE__ */ new Map()) {
 		if (!html) return html;
-		const matches = Array.from(html.matchAll(/<img\s[^>]*data-uuid="([^"]+)"[^>]*>/g));
-		if (matches.length === 0) return html;
-		const replacements = await Promise.all(matches.map(async (match) => {
-			const dataUuid = match[1];
-			const freshUrl = await this.getAttachmentUrl(dataUuid);
+		const images = extractHtmlImageReferences(html).flatMap((image) => {
+			const resourceUuid = this.getAttachmentResourceUuid(image);
+			return resourceUuid ? [{
+				image,
+				resourceUuid
+			}] : [];
+		});
+		if (images.length === 0) return html;
+		const replacements = await Promise.all(images.map(async ({ image, resourceUuid }) => {
+			let freshUrl = freshUrlCache.get(resourceUuid);
+			if (!freshUrl) {
+				freshUrl = this.getAttachmentUrl(resourceUuid);
+				freshUrlCache.set(resourceUuid, freshUrl);
+			}
 			return {
-				fullMatch: match[0],
-				dataUuid,
-				freshUrl
+				fullMatch: image.tag,
+				freshUrl: await freshUrl
 			};
 		}));
 		let result = html;
-		for (const { fullMatch, freshUrl } of replacements) if (freshUrl) {
-			const updatedImg = fullMatch.replace(/src="[^"]*"/, `src="${freshUrl}"`);
+		for (const { fullMatch, freshUrl } of replacements) {
+			if (!freshUrl) continue;
+			const updatedImg = /\bsrc\s*=/i.test(fullMatch) ? fullMatch.replace(/\bsrc\s*=\s*(?:"[^"]*"|'[^']*')/i, `src="${freshUrl}"`) : fullMatch.replace(/<img\b/i, `<img src="${freshUrl}"`);
 			result = result.replace(fullMatch, updatedImg);
 		}
 		return result;
 	}
+	async getFreshTaskDescriptions(task) {
+		const taskInfo = await this.fetchTaskInfo(task.uuid);
+		const rawDescription = typeof taskInfo.desc === "string" ? taskInfo.desc : task.description ?? "";
+		const rawDescriptionRich = typeof taskInfo.desc_rich === "string" ? taskInfo.desc_rich : task.desc_rich ?? task.description ?? "";
+		const freshUrlCache = /* @__PURE__ */ new Map();
+		const [description, descriptionRich] = await Promise.all([this.refreshImageUrls(rawDescription, freshUrlCache), this.refreshImageUrls(rawDescriptionRich, freshUrlCache)]);
+		return {
+			description,
+			descriptionRich
+		};
+	}
+	async getTaskImageAttachments(task) {
+		const { description, descriptionRich } = await this.getFreshTaskDescriptions(task);
+		const images = [...extractHtmlImageReferences(descriptionRich), ...extractHtmlImageReferences(description)];
+		const seen = /* @__PURE__ */ new Set();
+		const attachments = [];
+		for (const image of images) {
+			if (!image.src) continue;
+			let url;
+			try {
+				url = new URL(image.src, this.config.apiBase).toString();
+			} catch {
+				continue;
+			}
+			if (this.classifyRemoteImageUrl(url) === "untrusted") continue;
+			const identity = image.resourceUuid || url;
+			if (seen.has(identity)) continue;
+			seen.add(identity);
+			const pathname = new URL(url).pathname;
+			const pathName = attachmentNameFromPath(pathname);
+			const name = pathName && pathName !== "/" ? pathName : `image-${attachments.length + 1}.png`;
+			attachments.push({
+				id: image.resourceUuid || `${task.uuid}-image-${attachments.length + 1}`,
+				name,
+				url,
+				mimeType: mimeTypeFromFileName(pathname),
+				size: 0
+			});
+		}
+		return attachments;
+	}
 	/**
 	* Fetch wiki page content via REST API.
 	* Endpoint: /wiki/api/wiki/team/{teamUuid}/online_page/{wikiUuid}/content
@@ -1436,7 +1669,7 @@ var OnesAdapter = class extends BaseAdapter {
 			title: `Wiki ${wikiUuid}`,
 			uuid: wikiUuid
 		});
-		const wikiContents = await Promise.all([...wikiRefs.values()].map(async (wiki) => {
+		const [wikiContents, taskImageAttachments] = await Promise.all([Promise.all([...wikiRefs.values()].map(async (wiki) => {
 			const rendered = await this.fetchWikiContent(wiki.uuid);
 			return {
 				title: wiki.title,
@@ -1444,7 +1677,7 @@ var OnesAdapter = class extends BaseAdapter {
 				content: rendered.content,
 				attachments: rendered.attachments
 			};
-		}));
+		})), containsInlineTaskImages(task) ? this.getTaskImageAttachments(task) : Promise.resolve([])]);
 		const parts = [];
 		parts.push(`# #${task.number} ${task.name}`);
 		parts.push("");
@@ -1504,7 +1737,7 @@ var OnesAdapter = class extends BaseAdapter {
 			parts.push(detailText);
 		}
 		const wikiAttachments = wikiContents.flatMap((wiki) => wiki.attachments);
-		const req = toRequirement(task, parts.join("\n"), wikiAttachments);
+		const req = toRequirement(task, parts.join("\n"), [...wikiAttachments, ...taskImageAttachments]);
 		req.raw = {
 			...req.raw,
 			relatedActivities,
@@ -1597,13 +1830,13 @@ var OnesAdapter = class extends BaseAdapter {
 			filterGroup: [filter],
 			search: null,
 			pagination: {
-				limit: pageSize * page,
+				limit: intent === "all_tasks" ? 1e3 : pageSize * page,
 				preciseCount: false
 			},
 			limit: 1e3
 		}, "group-task-data")).data?.buckets?.flatMap((b) => b.tasks ?? []) ?? [];
 		if (intent === "all_bugs") tasks = tasks.filter((task) => classifyOnesWorkItem(task.issueType, task.subIssueType) === "defect").filter((task) => isOpenOrInProgressBug(task)).sort((a, b) => getBugStatusPriority(a) - getBugStatusPriority(b));
-		if (intent === "all_tasks") tasks = tasks.filter((task) => classifyOnesWorkItem(task.issueType, task.subIssueType) === "task");
+		if (intent === "all_tasks") tasks = tasks.filter((task) => classifyOnesWorkItem(task.issueType, task.subIssueType) === "task").filter((task) => task.status?.category === "to_do" || task.status?.category === "in_progress");
 		if (assigneeUuid) tasks = tasks.filter((task) => task.assign?.uuid === assigneeUuid);
 		if (intent === "keyword" && params.query) {
 			const keyword = params.query.trim();
@@ -1621,6 +1854,142 @@ var OnesAdapter = class extends BaseAdapter {
 			pageSize
 		};
 	}
+	async listPendingWorkItems() {
+		const items = await mapWithConcurrency(((await this.graphql(SEARCH_TASKS_QUERY, {
+			groupBy: { tasks: {} },
+			groupOrderBy: null,
+			orderBy: {
+				position: "ASC",
+				createTime: "DESC"
+			},
+			filterGroup: [{
+				assign_in: ["${currentUser}"],
+				status_notIn: DEFAULT_STATUS_NOT_IN
+			}],
+			search: null,
+			pagination: {
+				limit: 1e3,
+				preciseCount: false
+			},
+			limit: 1e3
+		}, "group-task-data")).data?.buckets?.flatMap((bucket) => bucket.tasks ?? []) ?? []).filter((task) => task.status?.category === "to_do" || task.status?.category === "in_progress").filter((task) => {
+			const kind = classifyOnesWorkItem(task.issueType, task.subIssueType);
+			return kind === "requirement" || kind === "task";
+		}), 6, async (task) => {
+			const info = await this.fetchTaskInfo(task.uuid);
+			const partial = Object.keys(info).length === 0;
+			const kind = classifyOnesWorkItem(task.issueType, task.subIssueType);
+			const statusCategory = task.status.category === "in_progress" ? "in_progress" : "to_do";
+			const fallbackIdentifier = task.project?.identifier?.toUpperCase() ?? null;
+			return {
+				uuid: task.uuid,
+				displayId: taskDisplayId(info, task, fallbackIdentifier),
+				kind: kind === "requirement" ? "requirement" : "task",
+				title: firstString(info, ["summary", "name"]) ?? task.name,
+				statusName: task.status.name,
+				statusCategory,
+				assigneeName: task.assign?.name ?? null,
+				projectName: task.project?.name ?? null,
+				parentUuid: firstString(info, ["parent_uuid", "parentUuid"]) ?? task.parent?.uuid ?? null,
+				parentDisplayId: kind === "task" ? inferredParentDisplayId(task, info) : null,
+				actualHours: taskInfoHours(info, [
+					"total_manhour",
+					"totalManhour",
+					"actual_manhour"
+				]),
+				remainingHours: taskInfoHours(info, ["remaining_manhour", "remainingManhour"]),
+				estimatedHours: taskInfoHours(info, [
+					"assess_manhour",
+					"assessManhour",
+					"estimated_manhour"
+				]),
+				planStartDate: taskInfoDate(info, "start"),
+				planEndDate: taskInfoDate(info, "end"),
+				partial,
+				warnings: partial ? ["ONES task detail GET returned no data"] : []
+			};
+		});
+		items.sort((left, right) => compareNullableDate(left.planStartDate, right.planStartDate) || compareNullableDate(left.planEndDate, right.planEndDate) || left.displayId.localeCompare(right.displayId));
+		return {
+			items,
+			total: items.length,
+			partialCount: items.filter((item) => item.partial).length,
+			fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	}
+	async getRequirementDecompositionContext(params) {
+		const workItem = await this.getRequirement({ id: params.requirementId });
+		if (workItem.raw.workItemKind !== "requirement") {
+			const kind = typeof workItem.raw.workItemKind === "string" ? workItem.raw.workItemKind : workItem.type;
+			throw new Error(`ONES: "${params.requirementId}" is ${kind}, not a requirement. Only requirements can be decomposed.`);
+		}
+		const raw = workItem.raw;
+		if (!Number.isInteger(raw.number)) throw new TypeError("ONES: Standalone wiki pages cannot be decomposed into requirement tasks");
+		const parsedDisplayId = parseDisplayId(params.requirementId);
+		const requirementInfo = await this.fetchTaskInfo(workItem.id);
+		const projectIdentifier = parsedDisplayId?.identifier.toUpperCase() ?? firstString(requirementInfo, ["projectIdentifier", "project_identifier"]);
+		const displayId = firstString(requirementInfo, ["displayId", "display_id"]) ?? (projectIdentifier ? `${projectIdentifier}-${raw.number}` : `#${raw.number}`);
+		const relatedTasks = (raw.relatedTasks ?? []).filter((task) => classifyOnesWorkItem(task.issueType, task.subIssueType) === "task");
+		const relatedInfos = await Promise.all(relatedTasks.map((task) => this.fetchTaskInfo(task.uuid)));
+		const tasks = sortRequirementTasks(relatedTasks.map((task, index) => {
+			const info = relatedInfos[index] ?? {};
+			const statusCategory = task.status?.category ?? "unknown";
+			return {
+				uuid: task.uuid,
+				displayId: taskDisplayId(info, task, projectIdentifier),
+				name: task.name,
+				detail: taskInfoDetail(info, task),
+				statusName: task.status?.name ?? "Unknown",
+				statusCategory,
+				pending: statusCategory === "to_do" || statusCategory === "in_progress",
+				assigneeName: task.assign?.name ?? null,
+				assigneeUuid: task.assign?.uuid ?? null,
+				planStartDate: taskInfoDate(info, "start"),
+				planEndDate: taskInfoDate(info, "end")
+			};
+		}));
+		const requirement = {
+			workItemKind: "requirement",
+			uuid: workItem.id,
+			displayId,
+			name: raw.name ?? workItem.title,
+			detail: typeof workItem.raw.sourceDescription === "string" ? workItem.raw.sourceDescription : workItem.description,
+			issueTypeName: raw.subIssueType?.name ?? raw.issueType?.name ?? "需求",
+			statusName: raw.status?.name ?? workItem.status,
+			statusCategory: raw.status?.category ?? workItem.status,
+			projectUuid: raw.project?.uuid ?? null,
+			projectName: raw.project?.name ?? null,
+			assigneeUuid: raw.assign?.uuid ?? null,
+			assigneeName: raw.assign?.name ?? workItem.assignee
+		};
+		const baseline = buildRequirementDecompositionBaseline(requirement, tasks, {
+			version: firstString(requirementInfo, [
+				"version",
+				"version_uuid",
+				"versionUuid"
+			]),
+			updatedAt: firstString(requirementInfo, [
+				"updatedAt",
+				"updated_at",
+				"updateTime",
+				"update_time"
+			])
+		});
+		return {
+			decompositionRelation: {
+				verified: false,
+				uuid: null,
+				name: null
+			},
+			requirement,
+			tasks,
+			pendingTasks: tasks.filter((task) => task.pending),
+			baseline
+		};
+	}
+	async createRequirementDecomposition(_params) {
+		throw new Error("ONES: Requirement task creation is unavailable because the production create/relationship API contract has not been confirmed. No write request was sent.");
+	}
 	async addManhour(params) {
 		const description = params.description.trim();
 		if (!description) throw new Error("ONES: description is required");
@@ -1712,35 +2081,13 @@ var OnesAdapter = class extends BaseAdapter {
 		}));
 	}
 	async getIssueDetail(params) {
-		let issueKey;
-		const numMatch = params.issueId.match(/^#?(\d+)$/);
-		if (numMatch) {
-			const taskNumber = Number.parseInt(numMatch[1], 10);
-			const found = ((await this.graphql(SEARCH_TASKS_QUERY, {
-				groupBy: { tasks: {} },
-				groupOrderBy: null,
-				orderBy: { createTime: "DESC" },
-				filterGroup: [{ number_in: [taskNumber] }],
-				search: null,
-				pagination: {
-					limit: 10,
-					preciseCount: false
-				},
-				limit: 10
-			}, "group-task-data")).data?.buckets?.flatMap((b) => b.tasks ?? []) ?? []).find((t) => t.number === taskNumber);
-			if (!found) throw new Error(`ONES: Issue #${taskNumber} not found in current team`);
-			issueKey = `task-${found.uuid}`;
-		} else issueKey = params.issueId.startsWith("task-") ? params.issueId : `task-${params.issueId}`;
+		const { key: issueKey } = await this.resolveTaskRef(params.issueId);
 		const task = (await this.graphql(ISSUE_DETAIL_QUERY, { key: issueKey }, "Task")).data?.task;
 		if (!task) throw new Error(`ONES: Issue "${issueKey}" not found`);
 		const kind = classifyOnesWorkItem(task.issueType, task.subIssueType);
 		if (kind === "unknown") throw new Error(`ONES: Unable to classify "${params.issueId}" before get_issue_detail`);
 		if (kind === "requirement" || kind === "task") throw unsupportedWorkItemToolError(params.issueId, kind, "get_issue_detail", "get_work_item");
-		const taskInfo = await this.fetchTaskInfo(task.uuid);
-		const rawDescription = taskInfo.desc ?? task.description ?? "";
-		const rawDescRich = taskInfo.desc_rich ?? task.desc_rich ?? "";
-		const freshDescription = await this.refreshImageUrls(rawDescription);
-		const freshDescRich = await this.refreshImageUrls(rawDescRich);
+		const { description: freshDescription, descriptionRich: freshDescRich } = await this.getFreshTaskDescriptions(task);
 		return {
 			key: task.key,
 			uuid: task.uuid,
@@ -2333,7 +2680,7 @@ async function downloadTrustedImages(urls, options) {
 //#endregion
 //#region ../../src/tools/get-issue-detail.ts
 const GetIssueDetailSchema = z.object({
-	issueId: z.string().describe("The issue task ID or key (e.g. \"mock-issue-uuid\" or \"task-mock-issue-uuid\")"),
+	issueId: z.string().describe("ONES defect UUID, task key, number, or display ID (for example \"DEMO-2001\")"),
 	source: z.string().optional().describe("Source to fetch from. If omitted, uses the default source.")
 });
 /**
@@ -2542,6 +2889,66 @@ function formatWorkItem(req) {
 	return lines.join("\n");
 }
 //#endregion
+//#region ../../src/tools/list-pending-work-items.ts
+const ListPendingWorkItemsSchema = z.object({ source: z.string().optional().describe("Source to read. If omitted, uses the default source.") });
+function resolveAdapter$1(source, adapters, defaultSource) {
+	const sourceType = source ?? defaultSource;
+	if (!sourceType) throw new Error("No source specified and no default source configured");
+	const adapter = adapters.get(sourceType);
+	if (!adapter) throw new Error(`Source "${sourceType}" is not configured. Available: ${[...adapters.keys()].join(", ")}`);
+	return adapter;
+}
+function sanitizeItem(item) {
+	return {
+		...item,
+		displayId: sanitizeExternalInline(item.displayId),
+		title: sanitizeExternalInline(item.title),
+		statusName: sanitizeExternalInline(item.statusName),
+		assigneeName: item.assigneeName ? sanitizeExternalInline(item.assigneeName) : null,
+		projectName: item.projectName ? sanitizeExternalInline(item.projectName) : null,
+		parentDisplayId: item.parentDisplayId ? sanitizeExternalInline(item.parentDisplayId) : null,
+		warnings: item.warnings.map(sanitizeExternalInline)
+	};
+}
+function formatHours(value) {
+	if (value === null) return "—";
+	return `${Number.isInteger(value) ? value : value.toFixed(1)}h`;
+}
+function escapeTable(value) {
+	return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function formatResult(result) {
+	const lines = [
+		"# Pending ONES Work Items",
+		"",
+		`- Total: ${result.total}`,
+		`- Partial rows: ${result.partialCount}`,
+		`- Fetched at: ${result.fetchedAt}`,
+		"- Scope: current assignee; requirements and tasks; status is not started or in progress; defects excluded.",
+		"",
+		UNTRUSTED_SOURCE_NOTICE,
+		"",
+		"| Display ID | Type | Title | Status | Actual | Remaining | Estimate | Plan Start | Plan End |",
+		"| --- | --- | --- | --- | ---: | ---: | ---: | --- | --- |"
+	];
+	for (const item of result.items) lines.push(`| ${escapeTable(item.displayId)} | ${item.kind} | ${escapeTable(item.title)} | ${escapeTable(item.statusName)} | ${formatHours(item.actualHours)} | ${formatHours(item.remainingHours)} | ${formatHours(item.estimatedHours)} | ${item.planStartDate ?? "—"} | ${item.planEndDate ?? "—"} |`);
+	return lines.join("\n");
+}
+async function handleListPendingWorkItems(input, adapters, defaultSource) {
+	const result = await resolveAdapter$1(input.source, adapters, defaultSource).listPendingWorkItems();
+	const safeResult = {
+		...result,
+		items: result.items.map(sanitizeItem)
+	};
+	return {
+		content: [{
+			type: "text",
+			text: formatResult(safeResult)
+		}],
+		structuredContent: safeResult
+	};
+}
+//#endregion
 //#region ../../src/tools/list-sources.ts
 async function handleListSources(adapters, config) {
 	const lines = ["# Configured Sources", ""];
@@ -2565,6 +2972,274 @@ async function handleListSources(adapters, config) {
 	}] };
 }
 //#endregion
+//#region ../../src/tools/requirement-decomposition.ts
+const APPROVAL_TTL_MS = 1800 * 1e3;
+const MAX_CREATE_OPERATIONS = 10;
+function isValidDate(value) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+	const [year, month, day] = value.split("-").map(Number);
+	const date = new Date(Date.UTC(year, month - 1, day));
+	return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+const DateSchema$1 = z.string().refine(isValidDate, "Expected a valid YYYY-MM-DD date");
+function unicodeLength(value) {
+	return Array.from(value).length;
+}
+const ShortContentSchema = z.string().trim().min(1).refine((value) => unicodeLength(value) <= 20, "shortContent must not exceed 20 Unicode characters");
+const RequirementTaskProposalSchema = z.object({
+	shortContent: ShortContentSchema.describe("Concise task content without the requirement display ID; at most 20 Unicode characters."),
+	detail: z.string().trim().min(1).describe("Concrete task detail and completion boundary."),
+	assigneeUuid: z.string().trim().min(1).optional(),
+	priorityUuid: z.string().trim().min(1).optional(),
+	complexityUuid: z.string().trim().min(1).optional(),
+	splitTypeUuid: z.string().trim().min(1).optional(),
+	productUuid: z.string().trim().min(1).optional(),
+	moduleUuid: z.string().trim().min(1).optional(),
+	estimatedHours: z.number().positive().finite().optional(),
+	planStartDate: DateSchema$1.optional(),
+	planEndDate: DateSchema$1.optional()
+}).refine((value) => !value.planStartDate || !value.planEndDate || value.planStartDate <= value.planEndDate, { message: "planEndDate must be the same as or later than planStartDate" });
+const InspectRequirementDecompositionSchema = z.object({
+	requirementId: z.string().trim().min(1).describe("ONES requirement UUID, number, or display ID."),
+	source: z.string().optional().describe("Source to inspect. If omitted, uses the default source.")
+});
+const PrepareRequirementDecompositionSchema = z.object({
+	requirementId: z.string().trim().min(1).describe("ONES requirement UUID, number, or display ID."),
+	tasks: z.array(RequirementTaskProposalSchema).min(1).max(MAX_CREATE_OPERATIONS),
+	source: z.string().optional().describe("Source to prepare against. If omitted, uses the default source.")
+});
+const ApplyRequirementDecompositionSchema = z.object({
+	approvalToken: z.string().trim().min(1),
+	planHash: z.string().regex(/^[a-f0-9]{64}$/),
+	confirmed: z.literal(true).describe("Must be true only after the user confirms the exact prepared operations."),
+	source: z.string().optional().describe("Source to write to. Must match the prepared plan source.")
+});
+var RequirementDecompositionApprovalStore = class {
+	approvals = /* @__PURE__ */ new Map();
+	now;
+	ttlMs;
+	constructor(options = {}) {
+		this.now = options.now ?? Date.now;
+		this.ttlMs = options.ttlMs ?? APPROVAL_TTL_MS;
+	}
+	create(record) {
+		const now = this.now();
+		for (const [token, approval] of this.approvals) {
+			const expired = approval.expiresAt <= now;
+			const superseded = approval.source === record.source && approval.requirementUuid === record.requirementUuid;
+			if (expired || superseded) this.approvals.delete(token);
+		}
+		const token = randomBytes(24).toString("hex");
+		const expiresAt = now + this.ttlMs;
+		this.approvals.set(token, {
+			...record,
+			expiresAt
+		});
+		return {
+			token,
+			expiresAt
+		};
+	}
+	/** Atomically remove and return an approval before any asynchronous work. */
+	take(token) {
+		const record = this.approvals.get(token);
+		if (!record) return null;
+		this.approvals.delete(token);
+		if (record.expiresAt <= this.now()) return null;
+		return record;
+	}
+};
+function resolveAdapter(source, adapters, defaultSource) {
+	const sourceType = source ?? defaultSource;
+	if (!sourceType) throw new Error("No source specified and no default source configured");
+	const adapter = adapters.get(sourceType);
+	if (!adapter) throw new Error(`Source "${sourceType}" is not configured. Available: ${[...adapters.keys()].join(", ")}`);
+	return {
+		sourceType,
+		adapter
+	};
+}
+function sanitizedContext(context) {
+	const requirement = {
+		...context.requirement,
+		displayId: sanitizeExternalInline(context.requirement.displayId),
+		name: sanitizeExternalInline(context.requirement.name),
+		detail: sanitizeExternalText(context.requirement.detail),
+		issueTypeName: sanitizeExternalInline(context.requirement.issueTypeName),
+		statusName: sanitizeExternalInline(context.requirement.statusName),
+		statusCategory: sanitizeExternalInline(context.requirement.statusCategory),
+		projectName: context.requirement.projectName ? sanitizeExternalInline(context.requirement.projectName) : null,
+		assigneeName: context.requirement.assigneeName ? sanitizeExternalInline(context.requirement.assigneeName) : null
+	};
+	const sanitizeTask = (task) => ({
+		...task,
+		displayId: sanitizeExternalInline(task.displayId),
+		name: sanitizeExternalInline(task.name),
+		detail: sanitizeExternalText(task.detail),
+		statusName: sanitizeExternalInline(task.statusName),
+		statusCategory: sanitizeExternalInline(task.statusCategory),
+		assigneeName: task.assigneeName ? sanitizeExternalInline(task.assigneeName) : null
+	});
+	const tasks = sortRequirementTasks(context.tasks.map(sanitizeTask));
+	const pendingUuids = new Set(context.pendingTasks.map((task) => task.uuid));
+	return {
+		decompositionRelation: context.decompositionRelation,
+		requirement,
+		tasks,
+		pendingTasks: tasks.filter((task) => pendingUuids.has(task.uuid)),
+		baseline: context.baseline
+	};
+}
+function formatInspection(context) {
+	const lines = [
+		`# ${context.requirement.displayId} ${context.requirement.name}`,
+		"",
+		`- **Type**: ${context.requirement.issueTypeName}`,
+		`- **Status**: ${context.requirement.statusName} (${context.requirement.statusCategory})`,
+		`- **Decomposition relation verified**: ${context.decompositionRelation.verified ? "yes" : "no"}`,
+		`- **Related task candidates**: ${context.tasks.length}`,
+		`- **Pending related task candidates**: ${context.pendingTasks.length}`,
+		"- **Implementation order**: use pending tasks only; they are sorted by planned start, planned end, then Display ID, with unset dates last.",
+		"- **Change safety**: compare requirement detail with every task name/detail before coding; warn on meaningful divergence and block affected work on a major mismatch.",
+		"",
+		"## Untrusted ONES Requirement Detail",
+		"",
+		UNTRUSTED_SOURCE_NOTICE,
+		"",
+		context.requirement.detail || "(No requirement detail)",
+		"",
+		context.decompositionRelation.verified ? "## Existing Requirement Decomposition" : "## Related Task Candidates (relationship unverified)",
+		""
+	];
+	if (context.tasks.length === 0) lines.push(context.decompositionRelation.verified ? "No existing requirement decomposition tasks." : "No related task candidates were returned; the decomposition relationship is still unverified.");
+	else for (const task of context.tasks) {
+		lines.push(`### ${task.displayId} ${task.name}`);
+		lines.push(`- Status: ${task.statusName} (${task.statusCategory})`);
+		lines.push(`- Plan: ${task.planStartDate ?? "unset"} → ${task.planEndDate ?? "unset"}`);
+		lines.push(`- Assignee: ${task.assigneeName ?? "Unassigned"}`);
+		lines.push("");
+		lines.push(task.detail || "(No task detail)");
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+function normalizedShortContent(value) {
+	return value.trim().replace(/\s+/g, " ");
+}
+function buildOperations(displayId, tasks) {
+	const seen = /* @__PURE__ */ new Set();
+	return tasks.map((task) => {
+		const shortContent = normalizedShortContent(task.shortContent);
+		if (new RegExp(`^${displayId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(shortContent)) throw new Error("shortContent must not repeat the requirement display ID");
+		const identity = shortContent.toLocaleLowerCase();
+		if (seen.has(identity)) throw new Error(`Duplicate decomposition task shortContent: "${shortContent}"`);
+		seen.add(identity);
+		return {
+			operation: "create",
+			title: `${displayId} ${shortContent}`,
+			shortContent,
+			detail: task.detail,
+			...task.assigneeUuid ? { assigneeUuid: task.assigneeUuid } : {},
+			...task.priorityUuid ? { priorityUuid: task.priorityUuid } : {},
+			...task.complexityUuid ? { complexityUuid: task.complexityUuid } : {},
+			...task.splitTypeUuid ? { splitTypeUuid: task.splitTypeUuid } : {},
+			...task.productUuid ? { productUuid: task.productUuid } : {},
+			...task.moduleUuid ? { moduleUuid: task.moduleUuid } : {},
+			...task.estimatedHours !== void 0 ? { estimatedHours: task.estimatedHours } : {},
+			...task.planStartDate ? { planStartDate: task.planStartDate } : {},
+			...task.planEndDate ? { planEndDate: task.planEndDate } : {}
+		};
+	});
+}
+async function handleInspectRequirementDecomposition(input, adapters, defaultSource) {
+	const { adapter } = resolveAdapter(input.source, adapters, defaultSource);
+	const context = sanitizedContext(await adapter.getRequirementDecompositionContext({ requirementId: input.requirementId }));
+	return {
+		content: [{
+			type: "text",
+			text: formatInspection(context)
+		}],
+		structuredContent: context
+	};
+}
+async function handlePrepareRequirementDecomposition(input, adapters, approvals, defaultSource) {
+	const { sourceType, adapter } = resolveAdapter(input.source, adapters, defaultSource);
+	const context = await adapter.getRequirementDecompositionContext({ requirementId: input.requirementId });
+	if (context.requirement.workItemKind !== "requirement") throw new Error("Only requirements can be decomposed");
+	if (!context.decompositionRelation.verified || !context.decompositionRelation.uuid) throw new Error("The \"requirement decomposition task\" relationship could not be verified from the read response. No plan or write was prepared.");
+	if (context.requirement.statusCategory !== "to_do" && context.requirement.statusCategory !== "in_progress") throw new Error(`Requirement ${context.requirement.displayId} is not pending (${context.requirement.statusName})`);
+	if (context.tasks.length > 0) throw new Error(`Requirement ${context.requirement.displayId} already has ${context.tasks.length} decomposition task(s). Inspect them; additions or edits require a separate explicit workflow.`);
+	const operations = buildOperations(context.requirement.displayId, input.tasks);
+	const planHash = buildRequirementDecompositionPlanHash({
+		requirementUuid: context.requirement.uuid,
+		decompositionRelation: context.decompositionRelation,
+		baseline: context.baseline,
+		operations
+	});
+	const approval = approvals.create({
+		source: sourceType,
+		requirementId: input.requirementId,
+		requirementUuid: context.requirement.uuid,
+		decompositionRelation: context.decompositionRelation,
+		baseline: context.baseline,
+		operations,
+		planHash
+	});
+	const plan = {
+		requirement: sanitizedContext(context).requirement,
+		decompositionRelation: context.decompositionRelation,
+		operations,
+		baseline: context.baseline,
+		planHash,
+		approvalToken: approval.token,
+		expiresAt: new Date(approval.expiresAt).toISOString()
+	};
+	return {
+		content: [{
+			type: "text",
+			text: [
+				`Prepared ${operations.length} create operation(s) for ${plan.requirement.displayId}.`,
+				"No ONES create or edit request was sent.",
+				"Show the exact operations to the user. Call apply_requirement_decomposition only after explicit confirmation."
+			].join("\n")
+		}],
+		structuredContent: plan
+	};
+}
+async function handleApplyRequirementDecomposition(input, adapters, approvals, options) {
+	if (input.confirmed !== true) throw new Error("Explicit confirmation is required before applying a decomposition");
+	if (!options.writesEnabled) throw new Error("Requirement decomposition writes are disabled. Enable both ONES_ENABLE_WRITES=true and the source requirementDecompositionWrites option only in an approved production deployment.");
+	const record = approvals.take(input.approvalToken);
+	if (!record) throw new Error("Approval token is invalid, expired, or already used. Prepare the decomposition again.");
+	if ((input.source ?? options.defaultSource) !== record.source) throw new Error("Approval token source does not match the requested source");
+	if (input.planHash !== record.planHash) throw new Error("Plan hash does not match the approved decomposition");
+	const { adapter } = resolveAdapter(record.source, adapters, options.defaultSource);
+	const current = await adapter.getRequirementDecompositionContext({ requirementId: record.requirementId });
+	if (current.requirement.uuid !== record.requirementUuid || !isSameRequirementBaseline(current.baseline, record.baseline)) throw new Error("Requirement or related tasks changed after preparation. Prepare and confirm a new decomposition.");
+	if (!current.decompositionRelation.verified || current.decompositionRelation.uuid !== record.decompositionRelation.uuid) throw new Error("The requirement decomposition relationship changed or is no longer verified. Prepare and confirm again.");
+	if (current.tasks.length > 0) throw new Error("Requirement now has decomposition tasks. No create request was sent.");
+	if (buildRequirementDecompositionPlanHash({
+		requirementUuid: record.requirementUuid,
+		decompositionRelation: record.decompositionRelation,
+		baseline: record.baseline,
+		operations: record.operations
+	}) !== record.planHash) throw new Error("Stored decomposition plan failed integrity validation");
+	const result = await adapter.createRequirementDecomposition({
+		requirementUuid: record.requirementUuid,
+		decompositionRelation: record.decompositionRelation,
+		baseline: record.baseline,
+		planHash: record.planHash,
+		operations: record.operations
+	});
+	return {
+		content: [{
+			type: "text",
+			text: `Created ${result.createdTasks.length} requirement decomposition task(s).`
+		}],
+		structuredContent: result
+	};
+}
+//#endregion
 //#region ../../src/tools/search-requirements.ts
 const SearchRequirementsSchema = z.object({
 	query: z.string().describe("Search keywords"),
@@ -2661,6 +3336,11 @@ function createRequirementsServer(config, adapterOverrides) {
 		adapters.set(source.type, adapter);
 	}
 	const defaultSource = config.config.defaultSource;
+	const decompositionApprovals = new RequirementDecompositionApprovalStore();
+	const decompositionWritesEnabled = (sourceType) => {
+		if (process.env.ONES_ENABLE_WRITES !== "true" || !sourceType) return false;
+		return config.sources.find((candidate) => candidate.type === sourceType)?.config.options?.requirementDecompositionWrites === true;
+	};
 	const server = new McpServer({
 		name: "ai-dev-requirements",
 		version
@@ -2709,6 +3389,21 @@ function createRequirementsServer(config, adapterOverrides) {
 			return toolError(err);
 		}
 	});
+	server.registerTool("list_pending_work_items", {
+		title: "List Pending Work Items",
+		description: "List the current assignee's not-started and in-progress ONES requirements and tasks with actual, remaining, and estimated hours plus planned dates. Defects are excluded. Read-only.",
+		inputSchema: ListPendingWorkItemsSchema,
+		annotations: {
+			readOnlyHint: true,
+			openWorldHint: true
+		}
+	}, async (params) => {
+		try {
+			return await handleListPendingWorkItems(params, adapters, defaultSource);
+		} catch (err) {
+			return toolError(err);
+		}
+	});
 	server.registerTool("get_related_issues", {
 		title: "Get Related Issues",
 		description: "Get pending defects related to a requirement or task. Rejects a defect ID; use get_issue_detail instead.",
@@ -2770,6 +3465,57 @@ function createRequirementsServer(config, adapterOverrides) {
 			return toolError(err);
 		}
 	});
+	server.registerTool("inspect_requirement_decomposition", {
+		title: "Inspect Requirement Decomposition",
+		description: "Read a requirement and related task candidates with task detail, status, sorted plan dates, and explicit decomposition-relation verification. When the relation is unverified, candidates are not claimed to be decomposition tasks. Rejects tasks and defects. Never creates or edits ONES data.",
+		inputSchema: InspectRequirementDecompositionSchema,
+		annotations: {
+			readOnlyHint: true,
+			openWorldHint: true
+		}
+	}, async (params) => {
+		try {
+			return await handleInspectRequirementDecomposition(params, adapters, defaultSource);
+		} catch (err) {
+			return toolError(err);
+		}
+	});
+	server.registerTool("prepare_requirement_decomposition", {
+		title: "Prepare Requirement Decomposition",
+		description: "Validate a structured decomposition for a pending requirement with no existing decomposition tasks, then return the exact create operations and a one-time approval token. Does not write to ONES.",
+		inputSchema: PrepareRequirementDecompositionSchema,
+		annotations: {
+			readOnlyHint: true,
+			openWorldHint: true
+		}
+	}, async (params) => {
+		try {
+			return await handlePrepareRequirementDecomposition(params, adapters, decompositionApprovals, defaultSource);
+		} catch (err) {
+			return toolError(err);
+		}
+	});
+	server.registerTool("apply_requirement_decomposition", {
+		title: "Apply Requirement Decomposition",
+		description: "Create the exact previously prepared requirement tasks only after explicit user confirmation. Rechecks requirement/task hashes and uses a one-time token. Disabled by default.",
+		inputSchema: ApplyRequirementDecompositionSchema,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: true
+		}
+	}, async (params) => {
+		try {
+			const sourceType = params.source ?? defaultSource;
+			return await handleApplyRequirementDecomposition(params, adapters, decompositionApprovals, {
+				defaultSource,
+				writesEnabled: decompositionWritesEnabled(sourceType)
+			});
+		} catch (err) {
+			return toolError(err);
+		}
+	});
 	server.registerTool("add_manhour", {
 		title: "Add Manhour",
 		description: "Add a work-hour record to a ONES task, bug, or requirement. Supports task key, uuid, number, or displayId.",