@ilikexiaoni/pi-task-list 0.4.0 → 0.4.2

package/lib/task-list-core.ts

@@ -49,6 +49,16 @@ export interface TaskState {
   tasks: Task[];
 }
 
+export interface TaskSummary {
+  total: number;
+  active: number;
+  blocked: number;
+  pending: number;
+  completed: number;
+  cancelled: number;
+  ready: number;
+}
+
 export interface TaskCommand {
   action: TaskAction;
   id?: number;
@@ -76,6 +86,13 @@ export interface TaskCommand {
   confirm?: boolean;
 }
 
+/** A mutation record that can be replayed after compaction or session restore. */
+export interface TaskOperation {
+  version: 1;
+  command: TaskCommand;
+  at: string;
+}
+
 export interface ApplyResult {
   action: TaskAction;
   state: TaskState;
@@ -96,15 +113,45 @@ export class TaskListError extends Error {
   }
 }
 
-const MAX_SUBJECT_LENGTH = 300;
-const MAX_FIELD_LENGTH = 4000;
-const MAX_LIST_ITEMS = 50;
-const MAX_NOTES = 100;
+export const MAX_TASKS = 200;
+export const MAX_TASK_ID = Number.MAX_SAFE_INTEGER;
+export const MAX_SUBJECT_LENGTH = 300;
+export const MAX_FIELD_LENGTH = 4000;
+export const MAX_LIST_ITEMS = 50;
+export const MAX_NOTES = 100;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
+/** Identify a persisted task snapshot without silently treating malformed data as an empty list. */
+export function isPersistedTaskState(value: unknown): value is { tasks: unknown[] } {
+  if (!isRecord(value) || !Array.isArray(value.tasks)) return false;
+  const seenIds = new Set<number>();
+  return value.tasks.every((task) => {
+    if (!isRecord(task)) return false;
+    const subject = typeof task.subject === "string" ? sanitizeTaskText(task.subject) : "";
+    if (!subject) return false;
+
+    const hasPersistedId = task.id !== undefined;
+    const id = positiveInteger(task.id);
+    // Missing IDs can be migrated by normalizeState; malformed explicit IDs cannot.
+    if (hasPersistedId && id === undefined) return false;
+    if (id !== undefined) {
+      if (seenIds.has(id)) return false;
+      seenIds.add(id);
+    }
+    return true;
+  });
+}
+
+export function isPersistedTaskOperation(value: unknown): value is TaskOperation {
+  if (!isRecord(value) || (value.version !== undefined && value.version !== 1)) return false;
+  if (typeof value.at !== "string" || !value.at.trim() || value.at.length > 64 || !isRecord(value.command)) return false;
+  const action = value.command.action;
+  return typeof action === "string" && ["create", "update", "clear"].includes(action);
+}
+
 function isTaskStatus(value: unknown): value is TaskStatus {
   return typeof value === "string" && (TASK_STATUSES as readonly string[]).includes(value);
 }
@@ -118,14 +165,21 @@ function isTaskBlockSource(value: unknown): value is TaskBlockSource {
 }
 
 function positiveInteger(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= MAX_TASK_ID ? value : undefined;
+}
+
+const ANSI_ESCAPE_PATTERN = /\u001b(?:\][^\u0007]*(?:\u0007|\u001b\\)|\[[0-?]*[ -/]*[@-~])/g;
+
+/** Keep task data safe for TUI rendering and compact enough for session context. */
+export function sanitizeTaskText(value: string): string {
+  return value.replace(ANSI_ESCAPE_PATTERN, "").replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
 }
 
 function boundedText(value: unknown, field: string, max = MAX_FIELD_LENGTH): string {
   if (typeof value !== "string") {
     throw new TaskListError("invalid_argument", `${field} 必须是字符串`);
   }
-  const text = value.trim();
+  const text = sanitizeTaskText(value);
   if (text.length > max) {
     throw new TaskListError("invalid_argument", `${field} 不能超过 ${max} 个字符`);
   }
@@ -177,7 +231,7 @@ function safeStringList(value: unknown): string[] {
   if (!Array.isArray(value)) return [];
   return value
     .filter((item): item is string => typeof item === "string")
-    .map((item) => item.trim().slice(0, MAX_FIELD_LENGTH))
+    .map((item) => sanitizeTaskText(item).slice(0, MAX_FIELD_LENGTH))
     .filter(Boolean)
     .filter((item, index, list) => list.indexOf(item) === index)
     .slice(0, MAX_LIST_ITEMS);
@@ -192,13 +246,43 @@ function safeIdList(value: unknown): number[] {
     .slice(0, MAX_LIST_ITEMS);
 }
 
+function nextTaskId(id: number): number {
+  return id === MAX_TASK_ID ? 1 : id + 1;
+}
+
+function findAvailableTaskId(preferred: number, reserved: ReadonlySet<number>): number {
+  let candidate = Math.min(Math.max(preferred, 1), MAX_TASK_ID);
+  for (let attempts = 0; attempts <= reserved.size; attempts += 1) {
+    if (!reserved.has(candidate)) return candidate;
+    candidate = nextTaskId(candidate);
+  }
+  throw new TaskListError("task_limit", "没有可用的安全任务 ID");
+}
+
+function reservedTaskIds(tasks: readonly Task[]): Set<number> {
+  const reserved = new Set<number>();
+  for (const task of tasks) {
+    reserved.add(task.id);
+    for (const dependency of task.blockedBy) reserved.add(dependency);
+  }
+  return reserved;
+}
+
+function allocateTaskId(state: TaskState): number {
+  const reserved = reservedTaskIds(state.tasks);
+  const id = findAvailableTaskId(state.nextId, reserved);
+  reserved.add(id);
+  state.nextId = findAvailableTaskId(nextTaskId(id), reserved);
+  return id;
+}
+
 function safeNotes(value: unknown): TaskNote[] {
   if (!Array.isArray(value)) return [];
   return value
     .filter(isRecord)
     .map((item) => ({
-      at: typeof item.at === "string" ? item.at : "",
-      text: typeof item.text === "string" ? item.text.trim().slice(0, MAX_FIELD_LENGTH) : "",
+      at: typeof item.at === "string" ? sanitizeTaskText(item.at).slice(0, 64) : "",
+      text: typeof item.text === "string" ? sanitizeTaskText(item.text).slice(0, MAX_FIELD_LENGTH) : "",
     }))
     .filter((item) => item.text.length > 0)
     .slice(-MAX_NOTES);
@@ -222,6 +306,41 @@ export function cloneState(state: TaskState): TaskState {
   };
 }
 
+export function cloneTaskCommand(command: TaskCommand): TaskCommand {
+  const cloned: TaskCommand = { action: command.action };
+  if (command.id !== undefined) cloned.id = command.id;
+  if (command.subject !== undefined) cloned.subject = command.subject;
+  if (command.description !== undefined) cloned.description = command.description;
+  if (command.activeForm !== undefined) cloned.activeForm = command.activeForm;
+  if (command.acceptanceCriteria !== undefined) cloned.acceptanceCriteria = [...command.acceptanceCriteria];
+  if (command.evidence !== undefined) cloned.evidence = [...command.evidence];
+  if (command.addEvidence !== undefined) cloned.addEvidence = [...command.addEvidence];
+  if (command.status !== undefined) cloned.status = command.status;
+  if (command.priority !== undefined) cloned.priority = command.priority;
+  if (command.blockedBy !== undefined) cloned.blockedBy = [...command.blockedBy];
+  if (command.addBlockedBy !== undefined) cloned.addBlockedBy = [...command.addBlockedBy];
+  if (command.removeBlockedBy !== undefined) cloned.removeBlockedBy = [...command.removeBlockedBy];
+  if (command.blockReason !== undefined) cloned.blockReason = command.blockReason;
+  if (command.tags !== undefined) cloned.tags = [...command.tags];
+  if (command.addTags !== undefined) cloned.addTags = [...command.addTags];
+  if (command.removeTags !== undefined) cloned.removeTags = [...command.removeTags];
+  if (command.owner !== undefined) cloned.owner = command.owner;
+  if (command.completionNote !== undefined) cloned.completionNote = command.completionNote;
+  if (command.note !== undefined) cloned.note = command.note;
+  if (command.query !== undefined) cloned.query = command.query;
+  if (command.includeCancelled !== undefined) cloned.includeCancelled = command.includeCancelled;
+  if (command.scope !== undefined) cloned.scope = command.scope;
+  if (command.confirm !== undefined) cloned.confirm = command.confirm;
+  return cloned;
+}
+
+export function createTaskOperation(command: TaskCommand, at: string): TaskOperation {
+  if (command.action !== "create" && command.action !== "update" && command.action !== "clear") {
+    throw new TaskListError("invalid_argument", "只有 create、update、clear 可以记录为任务 operation");
+  }
+  return { version: 1, command: cloneTaskCommand(command), at: sanitizeTaskText(at).slice(0, 64) };
+}
+
 export function createEmptyState(now = new Date().toISOString()): TaskState {
   return {
     version: TASK_LIST_VERSION,
@@ -236,32 +355,48 @@ export function createEmptyState(now = new Date().toISOString()): TaskState {
 export function normalizeState(value: unknown): TaskState {
   if (!isRecord(value)) return createEmptyState();
 
-  const rawTasks = Array.isArray(value.tasks) ? value.tasks : [];
+  const rawTasks = Array.isArray(value.tasks) ? value.tasks.slice(0, MAX_TASKS) : [];
   const tasks: Task[] = [];
   const seenIds = new Set<number>();
+  const reservedExplicitIds = new Set(
+    rawTasks
+      .filter(isRecord)
+      .map((rawTask) => positiveInteger(rawTask.id))
+      .filter((id): id is number => id !== undefined),
+  );
+  const reservedDependencyIds = new Set(
+    rawTasks.flatMap((rawTask) => (isRecord(rawTask) ? safeIdList(rawTask.blockedBy) : [])),
+  );
+  const reservedReferenceIds = new Set([...reservedExplicitIds, ...reservedDependencyIds]);
   let fallbackId = 1;
 
+  const nextAvailableId = (): number => {
+    const reserved = new Set([...reservedReferenceIds, ...seenIds]);
+    const id = findAvailableTaskId(fallbackId, reserved);
+    fallbackId = nextTaskId(id);
+    return id;
+  };
+
   for (const rawTask of rawTasks) {
     if (!isRecord(rawTask)) continue;
     const rawId = positiveInteger(rawTask.id);
-    const id = rawId ?? fallbackId;
-    fallbackId = Math.max(fallbackId, id + 1);
-    if (seenIds.has(id)) continue;
+    const id = rawId !== undefined && !seenIds.has(rawId) ? rawId : nextAvailableId();
     seenIds.add(id);
+    if (id < MAX_TASK_ID) fallbackId = Math.max(fallbackId, id + 1);
 
     const subject =
-      typeof rawTask.subject === "string" && rawTask.subject.trim()
-        ? rawTask.subject.trim().slice(0, MAX_SUBJECT_LENGTH)
+      typeof rawTask.subject === "string" && sanitizeTaskText(rawTask.subject)
+        ? sanitizeTaskText(rawTask.subject).slice(0, MAX_SUBJECT_LENGTH)
         : `Task #${id}`;
     const status = isTaskStatus(rawTask.status) ? rawTask.status : "pending";
     const priority = isTaskPriority(rawTask.priority) ? rawTask.priority : "medium";
-    const description = typeof rawTask.description === "string" ? rawTask.description.trim().slice(0, MAX_FIELD_LENGTH) : "";
+    const description = typeof rawTask.description === "string" ? sanitizeTaskText(rawTask.description).slice(0, MAX_FIELD_LENGTH) : "";
     const activeForm =
-      typeof rawTask.activeForm === "string" && rawTask.activeForm.trim()
-        ? rawTask.activeForm.trim().slice(0, MAX_SUBJECT_LENGTH)
+      typeof rawTask.activeForm === "string" && sanitizeTaskText(rawTask.activeForm)
+        ? sanitizeTaskText(rawTask.activeForm).slice(0, MAX_SUBJECT_LENGTH)
         : subject;
     const blockedBy = safeIdList(rawTask.blockedBy);
-    const blockReason = typeof rawTask.blockReason === "string" ? rawTask.blockReason.trim().slice(0, MAX_FIELD_LENGTH) : "";
+    const blockReason = typeof rawTask.blockReason === "string" ? sanitizeTaskText(rawTask.blockReason).slice(0, MAX_FIELD_LENGTH) : "";
     const inferredBlockSource: TaskBlockSource =
       status !== "blocked"
         ? ""
@@ -283,26 +418,46 @@ export function normalizeState(value: unknown): TaskState {
       blockReason,
       blockSource: status === "blocked" ? blockSource : "",
       tags: safeStringList(rawTask.tags),
-      owner: typeof rawTask.owner === "string" ? rawTask.owner.trim().slice(0, 200) : "",
+      owner: typeof rawTask.owner === "string" ? sanitizeTaskText(rawTask.owner).slice(0, 200) : "",
       completionNote:
-        typeof rawTask.completionNote === "string" ? rawTask.completionNote.trim().slice(0, MAX_FIELD_LENGTH) : "",
+        typeof rawTask.completionNote === "string" ? sanitizeTaskText(rawTask.completionNote).slice(0, MAX_FIELD_LENGTH) : "",
       notes: safeNotes(rawTask.notes),
-      createdAt: typeof rawTask.createdAt === "string" ? rawTask.createdAt : "",
-      updatedAt: typeof rawTask.updatedAt === "string" ? rawTask.updatedAt : "",
+      createdAt: typeof rawTask.createdAt === "string" ? sanitizeTaskText(rawTask.createdAt).slice(0, 64) : "",
+      updatedAt: typeof rawTask.updatedAt === "string" ? sanitizeTaskText(rawTask.updatedAt).slice(0, 64) : "",
     });
   }
 
   const rawNextId = positiveInteger(value.nextId) ?? 1;
   const rawRevision = typeof value.revision === "number" && Number.isInteger(value.revision) && value.revision >= 0 ? value.revision : 0;
-  const updatedAt = typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString();
+  const updatedAt =
+    typeof value.updatedAt === "string" && sanitizeTaskText(value.updatedAt)
+      ? sanitizeTaskText(value.updatedAt).slice(0, 64)
+      : new Date().toISOString();
 
   const state: TaskState = {
     version: TASK_LIST_VERSION,
     revision: rawRevision,
-    nextId: Math.max(rawNextId, fallbackId, ...tasks.map((task) => task.id + 1)),
+    nextId: findAvailableTaskId(Math.max(rawNextId, fallbackId), reservedTaskIds(tasks)),
     updatedAt,
     tasks,
   };
+
+  // Repair impossible persisted states before exposing them to the tool or UI.
+  for (const task of state.tasks) {
+    const unresolved = unresolvedDependencies(state, task);
+    if (task.status === "completed" && unresolved.length > 0) {
+      task.status = "blocked";
+      task.blockReason = dependencyReason(unresolved);
+      task.blockSource = "dependency";
+    } else if (task.status === "completed" && task.evidence.length < task.acceptanceCriteria.length) {
+      task.status = "pending";
+      task.blockReason = "";
+      task.blockSource = "";
+    } else if (task.status === "blocked" && !task.blockReason && unresolved.length === 0) {
+      task.status = "pending";
+      task.blockSource = "";
+    }
+  }
   reconcileDependencyBlocks(state, updatedAt, false);
   return state;
 }
@@ -334,33 +489,34 @@ function validateReferences(state: TaskState, ids: number[], selfId?: number): v
 function validateNoCycle(state: TaskState, taskId: number, dependencies: number[]): void {
   const graph = new Map(state.tasks.map((task) => [task.id, task.blockedBy]));
   graph.set(taskId, dependencies);
+  const visited = new Set<number>();
+  const stack = [...dependencies];
 
-  const reachesTask = (current: number, visited: Set<number>): boolean => {
-    if (current === taskId) return true;
-    if (visited.has(current)) return false;
-    visited.add(current);
-    for (const dependency of graph.get(current) ?? []) {
-      if (reachesTask(dependency, new Set(visited))) return true;
-    }
-    return false;
-  };
-
-  for (const dependency of dependencies) {
-    if (reachesTask(dependency, new Set())) {
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    if (current === taskId) {
       throw new TaskListError("dependency_cycle", `任务 #${taskId} 的依赖会形成循环`);
     }
+    if (visited.has(current)) continue;
+    visited.add(current);
+    stack.push(...(graph.get(current) ?? []));
   }
 }
 
-function unresolvedDependencies(state: TaskState, task: Task): Task[] {
-  const resolved = new Set(["completed", "cancelled"]);
+interface DependencyReference {
+  id: number;
+  status: TaskStatus;
+  missing?: boolean;
+}
+
+function unresolvedDependencies(state: TaskState, task: Task): DependencyReference[] {
   return task.blockedBy
-    .map((id) => state.tasks.find((candidate) => candidate.id === id))
-    .filter((candidate): candidate is Task => candidate !== undefined && !resolved.has(candidate.status));
+    .map((id) => state.tasks.find((candidate) => candidate.id === id) ?? { id, status: "blocked" as const, missing: true })
+    .filter((candidate) => candidate.status !== "completed");
 }
 
-function dependencyReason(tasks: Task[]): string {
-  return `等待任务 ${tasks.map((task) => `#${task.id}`).join(", ")} 完成`;
+function dependencyReason(tasks: DependencyReference[]): string {
+  return `等待任务 ${tasks.map((task) => `#${task.id}${task.missing ? "（不存在）" : ""}`).join(", ")} 完成`;
 }
 
 function normalizeStatus(value: unknown): TaskStatus {
@@ -382,12 +538,23 @@ function appendNote(task: Task, text: string, at: string): void {
   if (task.notes.length > MAX_NOTES) task.notes = task.notes.slice(-MAX_NOTES);
 }
 
+function appendUniqueBounded<T>(target: T[], additions: T[], field: string): void {
+  const uniqueAdditions = additions.filter((item) => !target.includes(item));
+  if (target.length + uniqueAdditions.length > MAX_LIST_ITEMS) {
+    throw new TaskListError("invalid_argument", `${field} 最多包含 ${MAX_LIST_ITEMS} 项`);
+  }
+  target.push(...uniqueAdditions);
+}
+
 function touch(state: TaskState, now: string): void {
   state.revision += 1;
   state.updatedAt = now;
 }
 
 function makeTask(state: TaskState, params: TaskCommand, now: string): Task {
+  if (state.tasks.length >= MAX_TASKS) {
+    throw new TaskListError("task_limit", `任务数量已达到上限 ${MAX_TASKS}，请先清理已完成任务`);
+  }
   const subject = requiredText(params.subject, "subject", MAX_SUBJECT_LENGTH);
   const requestedStatus = params.status === undefined ? "pending" : normalizeStatus(params.status);
   const priority = params.priority === undefined ? "medium" : normalizePriority(params.priority);
@@ -398,12 +565,15 @@ function makeTask(state: TaskState, params: TaskCommand, now: string): Task {
     throw new TaskListError("invalid_transition", "新任务只能从 pending、in_progress 或 blocked 开始");
   }
 
+  const id = allocateTaskId(state);
+  validateNoCycle(state, id, blockedBy);
+
   const task: Task = {
-    id: state.nextId++,
+    id,
     subject,
     description: params.description === undefined ? "" : boundedText(params.description, "description"),
     activeForm:
-      params.activeForm === undefined || !params.activeForm.trim()
+      params.activeForm === undefined || (typeof params.activeForm === "string" && !params.activeForm.trim())
         ? subject
         : boundedText(params.activeForm, "activeForm", MAX_SUBJECT_LENGTH),
     acceptanceCriteria: params.acceptanceCriteria === undefined ? [] : stringList(params.acceptanceCriteria, "acceptanceCriteria"),
@@ -467,16 +637,12 @@ function updateTask(state: TaskState, params: TaskCommand, now: string): { task:
   }
   if (params.evidence !== undefined) candidate.evidence = stringList(params.evidence, "evidence");
   if (params.addEvidence !== undefined) {
-    for (const item of stringList(params.addEvidence, "addEvidence")) {
-      if (!candidate.evidence.includes(item)) candidate.evidence.push(item);
-    }
+    appendUniqueBounded(candidate.evidence, stringList(params.addEvidence, "addEvidence"), "evidence");
   }
   if (params.priority !== undefined) candidate.priority = normalizePriority(params.priority);
   if (params.blockedBy !== undefined) candidate.blockedBy = idList(params.blockedBy, "blockedBy");
   if (params.addBlockedBy !== undefined) {
-    for (const id of idList(params.addBlockedBy, "addBlockedBy")) {
-      if (!candidate.blockedBy.includes(id)) candidate.blockedBy.push(id);
-    }
+    appendUniqueBounded(candidate.blockedBy, idList(params.addBlockedBy, "addBlockedBy"), "blockedBy");
   }
   if (params.removeBlockedBy !== undefined) {
     const remove = new Set(idList(params.removeBlockedBy, "removeBlockedBy"));
@@ -488,9 +654,7 @@ function updateTask(state: TaskState, params: TaskCommand, now: string): { task:
   }
   if (params.tags !== undefined) candidate.tags = stringList(params.tags, "tags");
   if (params.addTags !== undefined) {
-    for (const tag of stringList(params.addTags, "addTags")) {
-      if (!candidate.tags.includes(tag)) candidate.tags.push(tag);
-    }
+    appendUniqueBounded(candidate.tags, stringList(params.addTags, "addTags"), "tags");
   }
   if (params.removeTags !== undefined) {
     const remove = new Set(stringList(params.removeTags, "removeTags"));
@@ -561,49 +725,66 @@ function updateTask(state: TaskState, params: TaskCommand, now: string): { task:
 }
 
 function reconcileDependencyBlocks(state: TaskState, now: string, recordNotes = true): number[] {
-  const changedIds: number[] = [];
-
-  for (const task of state.tasks) {
-    if (task.status === "completed" || task.status === "cancelled") continue;
-    const before = cloneTask(task);
-    const unresolved = unresolvedDependencies(state, task);
-
-    if (unresolved.length > 0) {
-      if (task.status === "pending" || task.status === "in_progress" || task.blockSource === "dependency") {
-        task.status = "blocked";
-        task.blockReason = dependencyReason(unresolved);
-        task.blockSource = "dependency";
+  const changedIds = new Set<number>();
+  let passChanged = true;
+
+  // Reconcile to a fixed point so a reopened dependency cascades through the whole graph.
+  while (passChanged) {
+    passChanged = false;
+    for (const task of state.tasks) {
+      if (task.status === "cancelled" || task.blockSource === "manual") continue;
+      const before = cloneTask(task);
+      const unresolved = unresolvedDependencies(state, task);
+
+      if (unresolved.length > 0) {
+        if (task.status === "pending" || task.status === "in_progress" || task.status === "completed" || task.status === "blocked") {
+          task.status = "blocked";
+          task.blockReason = dependencyReason(unresolved);
+          task.blockSource = "dependency";
+        }
+      } else if (task.status === "blocked" && task.blockSource === "dependency") {
+        task.status = "pending";
+        task.blockReason = "";
+        task.blockSource = "";
       }
-    } else if (task.status === "blocked" && task.blockSource === "dependency") {
-      task.status = "pending";
-      task.blockReason = "";
-      task.blockSource = "";
-    }
 
-    if (JSON.stringify(task) === JSON.stringify(before)) continue;
-    if (recordNotes && task.status !== before.status) {
-      const note = task.status === "blocked" ? `依赖未完成，自动标记为 blocked：${task.blockReason}` : "依赖已完成，自动恢复为 pending";
-      appendNote(task, note, now);
+      if (JSON.stringify(task) === JSON.stringify(before)) continue;
+      if (recordNotes && task.status !== before.status) {
+        const note = task.status === "blocked" ? `依赖未完成，自动标记为 blocked：${task.blockReason}` : "依赖已完成，自动恢复为 pending";
+        appendNote(task, note, now);
+      }
+      task.updatedAt = now;
+      changedIds.add(task.id);
+      passChanged = true;
     }
-    task.updatedAt = now;
-    changedIds.push(task.id);
   }
 
-  return changedIds;
+  return [...changedIds];
 }
 
 export function filterTasks(state: TaskState, params: Pick<TaskCommand, "status" | "priority" | "query" | "includeCancelled"> = {}): Task[] {
   const status = params.status === undefined ? undefined : normalizeStatus(params.status);
   const priority = params.priority === undefined ? undefined : normalizePriority(params.priority);
-  const query = params.query?.trim().toLowerCase();
+  const query = params.query === undefined ? undefined : boundedText(params.query, "query", MAX_FIELD_LENGTH).toLowerCase();
 
   return state.tasks
-    .filter((task) => params.includeCancelled === true || task.status !== "cancelled")
+    .filter((task) => params.includeCancelled === true || status === "cancelled" || task.status !== "cancelled")
     .filter((task) => status === undefined || task.status === status)
     .filter((task) => priority === undefined || task.priority === priority)
     .filter((task) => {
       if (!query) return true;
-      return [task.subject, task.description, task.owner, ...task.tags].some((value) => value.toLowerCase().includes(query));
+      return [
+        task.subject,
+        task.description,
+        task.activeForm,
+        task.blockReason,
+        task.owner,
+        task.completionNote,
+        ...task.tags,
+        ...task.acceptanceCriteria,
+        ...task.evidence,
+        ...task.notes.map((note) => note.text),
+      ].some((value) => value.toLowerCase().includes(query));
     })
     .sort(compareTasks)
     .map(cloneTask);
@@ -719,17 +900,31 @@ export function applyTaskAction(current: TaskState, params: TaskCommand, now = n
         };
       }
       const removedIds = new Set(removed.map((task) => task.id));
+      const completedIds = new Set(removed.filter((task) => task.status === "completed").map((task) => task.id));
       state.tasks = scope === "all" ? [] : state.tasks.filter((task) => !removedIds.has(task.id));
+
+      const referenceChanges = new Set<number>();
       for (const task of state.tasks) {
-        task.blockedBy = task.blockedBy.filter((id) => !removedIds.has(id));
+        const removedCompletedDependencies = task.blockedBy.filter((id) => completedIds.has(id));
+        if (removedCompletedDependencies.length === 0) continue;
+        task.blockedBy = task.blockedBy.filter((id) => !completedIds.has(id));
+        task.updatedAt = now;
+        appendNote(task, `已清理完成的依赖任务 ${removedCompletedDependencies.map((id) => `#${id}`).join(", ")}，移除依赖引用`, now);
+        referenceChanges.add(task.id);
       }
+
+      // References to cancelled tasks remain dangling on purpose: cancellation is not completion.
+      // This keeps downstream work blocked and reserves the removed ID against accidental reuse.
+      const dependencyChanges = reconcileDependencyBlocks(state, now);
+      const affectedIds = new Set([...referenceChanges, ...dependencyChanges]);
+      const changedIds = [...removed.map((task) => task.id), ...affectedIds];
       touch(state, now);
       return {
         action: "clear",
         state,
-        changedIds: removed.map((task) => task.id),
-        visibleTasks: state.tasks.map(cloneTask),
-        message: `已清理 ${removed.length} 个任务（范围：${scope}）`,
+        changedIds,
+        visibleTasks: state.tasks.filter((task) => affectedIds.has(task.id)).map(cloneTask),
+        message: `已清理 ${removed.length} 个任务（范围：${scope}）${affectedIds.size > 0 ? `；同步更新 ${affectedIds.size} 个依赖任务` : ""}`,
         mutated: true,
       };
     }
@@ -753,9 +948,9 @@ export function priorityLabel(priority: TaskPriority): string {
   return { high: "高", medium: "中", low: "低" }[priority];
 }
 
-export function summarizeState(state: TaskState): { total: number; active: number; blocked: number; pending: number; completed: number; cancelled: number; ready: number } {
-  const summary = { total: 0, active: 0, blocked: 0, pending: 0, completed: 0, cancelled: 0, ready: 0 };
-  const statusById = new Map(state.tasks.map((task) => [task.id, task.status]));
+export function summarizeState(state: TaskState, dependencyState: TaskState = state): TaskSummary {
+  const summary: TaskSummary = { total: 0, active: 0, blocked: 0, pending: 0, completed: 0, cancelled: 0, ready: 0 };
+  const statusById = new Map(dependencyState.tasks.map((task) => [task.id, task.status]));
 
   for (const task of state.tasks) {
     if (task.status === "cancelled") {
@@ -768,10 +963,7 @@ export function summarizeState(state: TaskState): { total: number; active: numbe
     if (task.status === "completed") summary.completed++;
     if (task.status === "pending") {
       summary.pending++;
-      const dependenciesResolved = task.blockedBy.every((id) => {
-        const status = statusById.get(id);
-        return status === undefined || status === "completed" || status === "cancelled";
-      });
+      const dependenciesResolved = task.blockedBy.every((id) => statusById.get(id) === "completed");
       if (dependenciesResolved) summary.ready++;
     }
   }