@sleep2agi/commhub-server 0.9.0-preview.89 → 0.9.0-preview.91

package/src/requirements-status-participants-http.test.ts

@@ -0,0 +1,216 @@
+// #475(MCP 任务生命周期测试报告问题 6)—— Agent 写任务时两处常见的坑:
+//   - status 当 column 用(列表的筛选参数就叫 status):MCP 的 create / update / upsert 把 status 当 column 的别名,
+//     两个都给且不同 → 400 status_conflicts_with_column;REST 不变(仍是 empty_patch + 提示用 column)。
+//   - participants 是整体替换,Agent 想「加一个人」时把别人全删了:新增 participants_add / participants_remove,
+//     在当前列表上加减、同一次同步读改写里完成;加已有 = 不变,减不在的 = 不变。
+// 外加 #476 第 1 部分:项目工具的描述写明节点令牌只能读项目(行为本来就是 403 user_token_required)。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-status-part-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqStatusPartPassw0rd!xyz";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+async function rpc(token: string, method: string, params: Record<string, unknown>) {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const out = await rpc(token, "tools/call", { name, arguments: args });
+  const text = out.result?.content?.[0]?.text ?? "";
+  try { return JSON.parse(text); } catch { return { raw: out, text }; }
+}
+const keys = (refs: { kind: string; id: string }[]) => refs.map(r => `${r.kind}:${r.id}`).sort();
+const row = (id: string) => db.get<{ column_name: string; participants_json: string; updated_at: string }>("SELECT column_name, participants_json, updated_at FROM requirements WHERE requirement_id = ?1", id)!;
+const participantEvents = (id: string) => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events WHERE requirement_id = ?1 AND field = 'participants'", id)!.n;
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`sp_owner_${Date.now()}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const username = `sp_member_${Date.now()}`;
+  expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" })).status).toBe(200);
+  const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+  U.member = { token: login.body.token, id: login.body.user.user_id };
+  for (const [k, alias] of [["nodeA", "示例-甲"], ["nodeB", "示例-乙"], ["nodeC", "示例-丙"]] as const) {
+    const nodeId = `node_sp_${k}`;
+    U[k] = { token: createNetworkTokenForNode(U.owner.id, NET, alias, nodeId).token!, id: nodeId };
+  }
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("status is an alias of column (MCP)", () => {
+  test("create / update / upsert with status land exactly where column would", async () => {
+    const viaStatus = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:status 建", status: "doing" })).requirement;
+    const viaColumn = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:column 建", column: "doing" })).requirement;
+    expect(viaStatus.column).toBe("doing");
+    expect(viaStatus.column).toBe(viaColumn.column);
+
+    const done = await mcp(U.nodeA.token, "requirements_update", { id: `#${viaStatus.seq}`, status: "done" });
+    expect(done.requirement.column).toBe("done");
+    expect(done.requirement.completedAt).toBeTruthy(); // same side effects as column=done
+    expect(row(viaStatus.id).column_name).toBe("done");
+
+    const same = await mcp(U.nodeA.token, "requirements_update", { id: viaColumn.id, status: "pool", column: "pool" });
+    expect(same.requirement.column).toBe("pool");
+
+    const up = await mcp(U.nodeA.token, "requirements_upsert_by_external_ref", { external_ref: "demo:status-alias-1", name: "示例:upsert", status: "doing" });
+    expect(up.created).toBe(true);
+    expect(up.requirement.column).toBe("doing");
+  });
+
+  test("status and column both sent and different → 400 status_conflicts_with_column with a hint; nothing written", async () => {
+    const card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:冲突", column: "pool" })).requirement;
+    const before = row(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, status: "doing", column: "done" });
+    expect(r.ok).toBe(false);
+    expect(r.status).toBe(400);
+    expect(r.error).toBe("status_conflicts_with_column");
+    expect(r.field).toBe("status");
+    expect(r.hint).toContain("only one");
+    expect(row(card.id)).toEqual(before);
+    const c = await mcp(U.nodeA.token, "requirements_create", { name: "示例:冲突建", status: "doing", column: "done" });
+    expect(c.error).toBe("status_conflicts_with_column");
+  });
+
+  test("a bad status value is a schema error (-32602), like a bad column", async () => {
+    const out = await rpc(U.nodeA.token, "tools/call", { name: "requirements_update", arguments: { id: "#1", status: "finished" } });
+    expect(String(out.error?.code ?? out.result?.content?.[0]?.text)).toMatch(/-32602|invalid/i);
+  });
+
+  test("REST is unchanged: status on PATCH is still not a writable field", async () => {
+    const card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:REST", column: "pool" })).requirement;
+    const r = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { status: "doing" });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("empty_patch");
+    expect(row(card.id).column_name).toBe("pool");
+  });
+});
+
+describe("participants_add / participants_remove", () => {
+  let card = { id: "", seq: 0 };
+  const node = (k: string) => ({ kind: "node", id: U[k].id });
+  const user = (k: string) => ({ kind: "user", id: U[k].id });
+
+  test("add keeps the people already there", async () => {
+    card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:参与人", participants: [user("member"), node("nodeA")] })).requirement;
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: `#${card.seq}`, participants_add: [node("nodeB")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+  });
+
+  test("add is idempotent: someone already there → same list, no participants event", async () => {
+    const events = participantEvents(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeB"), node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+    expect(participantEvents(card.id)).toBe(events);
+  });
+
+  test("remove drops only those people; removing someone absent (or no longer in the network) is a no-op", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_remove: [user("member"), { kind: "user", id: "u_left_the_network" }] });
+    expect(r.ok).toBe(true);
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB")]));
+  });
+
+  test("add and remove in one call are applied together", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeC"), user("member")], participants_remove: [node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeB"), node("nodeC"), user("member")]));
+  });
+
+  test("concurrent adds from two Agents both stick (no lost update)", async () => {
+    const fresh = (await mcp(U.owner.token, "requirements_create", { name: "示例:并发", participants: [user("owner")], network_id: NET })).requirement;
+    await Promise.all([
+      mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeA")] }),
+      mcp(U.nodeB.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeB")] }),
+      mcp(U.nodeC.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeC")] }),
+    ]);
+    expect(keys(JSON.parse(row(fresh.id).participants_json))).toEqual(keys([user("owner"), node("nodeA"), node("nodeB"), node("nodeC")]));
+  });
+
+  test("name forms (#473): add by alias / username, remove by username", async () => {
+    const fresh = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:按名字", participants: [node("nodeA")] })).requirement;
+    const memberName = db.get<{ username: string }>("SELECT username FROM users WHERE user_id = ?1", U.member.id)!.username;
+    const added = await mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_add: [{ kind: "node", alias: "示例-乙" }, { kind: "user", username: memberName }] });
+    expect(keys(added.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB"), user("member")]));
+    const removed = await mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_remove: [{ kind: "user", username: memberName }] });
+    expect(keys(removed.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB")]));
+  });
+
+  test("participants is still a full replace", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants: [node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeA")]));
+  });
+
+  test("bad combinations → 400 with hints, nothing written", async () => {
+    const before = row(card.id);
+    const both = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants: [], participants_add: [node("nodeB")] });
+    expect(both.status).toBe(400);
+    expect(both.error).toBe("participants_conflict");
+    expect(both.hint).toContain("participants_add");
+    const overlap = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeB")], participants_remove: [node("nodeB")] });
+    expect(overlap.error).toBe("participants_add_remove_overlap");
+    const stranger = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [{ kind: "node", id: "node_not_here" }] });
+    expect(stranger.error).toBe("person_not_in_network");
+    expect(stranger.field).toBe("participants_add");
+    expect(row(card.id)).toEqual(before);
+  });
+
+  test("REST accepts the same keys (additive; old clients never send them)", async () => {
+    const r = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { participants_add: [user("member")] });
+    expect(r.status).toBe(200);
+    // the member has no grant on nodeA, so the response leaves it out — but the stored list keeps it
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([node("nodeA"), user("member")]));
+    expect(keys(r.body.requirement.participants)).toEqual(keys([user("member")]));
+    // …and the member cannot remove an Agent they cannot see (same error as a node that does not exist)
+    const hidden = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { participants_remove: [node("nodeA")] });
+    expect(hidden.status).toBe(400);
+    expect(hidden.body.error).toBe("person_not_in_network");
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([node("nodeA"), user("member")]));
+  });
+});
+
+describe("tool descriptions", () => {
+  test("participants says it replaces; projects tools say node tokens only read; node token project write → 403", async () => {
+    const tools = (await rpc(U.nodeA.token, "tools/list", {})).result.tools as any[];
+    const byName = new Map(tools.map(t => [t.name, t]));
+    const update = byName.get("requirements_update");
+    expect(update.description).toContain("REPLACES the whole list");
+    expect(update.inputSchema.properties.participants.description).toContain("REPLACES");
+    expect(Object.keys(update.inputSchema.properties)).toEqual(expect.arrayContaining(["status", "participants_add", "participants_remove"]));
+    for (const name of ["projects_list", "projects_create", "projects_update"]) expect(byName.get(name).description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    const denied = await mcp(U.nodeA.token, "projects_create", { name: "示例项目" });
+    expect(denied.status).toBe(403);
+    expect(denied.error).toBe("user_token_required");
+  });
+});

package/src/requirements.ts

@@ -2,6 +2,7 @@
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
 import { errorBody, errorFrom, RequirementFieldError, type ErrorContext } from "./requirements-errors.js";
 import { createHash } from "node:crypto";
+import { parsePeopleQuery, peopleDirectory, resolvePersonName } from "./requirements-people.js";
 import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
 import { db, logAudit } from "./db.js";
 import { markGzipReusable } from "./http-gzip.js";
@@ -10,10 +11,11 @@ import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-s
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
 import {
-  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
+  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, deletesAsHeadOnly, headOnlyEditScope, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
   isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
-import { notifyParticipantChange } from "./requirement-notify.js";
+import { notifyLeaderDeleted, notifyParticipantChange } from "./requirement-notify.js";
+import { departmentCardsFor, departmentSubtree } from "./department-heads.js";
 import { diffRequirement, ensureRequirementEvents, eventPublic, recordRequirementEvents, type EventRow } from "./requirement-events.js";
 import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
@@ -523,7 +525,15 @@ type PersonRef = { kind: 'user' | 'node'; id: string };
 function personRef(value: unknown, networkId: string, hidden: HiddenNode = null, field = 'owner'): PersonRef {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new RequirementFieldError('invalid_person', field);
   const row = value as Record<string, unknown>;
-  if ((row.kind !== 'user' && row.kind !== 'node') || typeof row.id !== 'string' || !row.id.trim()) throw new RequirementFieldError('invalid_person', field);
+  if (row.kind !== 'user' && row.kind !== 'node') throw new RequirementFieldError('invalid_person', field);
+  // #473 —— 没给 id 时可以按名字:人 {kind:'user', username},Agent {kind:'node', alias}。
+  // 只在 networkId(任务所在的网络)里找,绝不跨网络;存下来的仍是 {kind, id}。给了 id 就只看 id(与以前逐字相同)。
+  if (typeof row.id !== 'string' || !row.id.trim()) {
+    const name = row.kind === 'user' ? row.username : row.alias;
+    if (row.id !== undefined || typeof name !== 'string' || !name.trim()) throw new RequirementFieldError('invalid_person', field);
+    try { return { kind: row.kind, id: resolvePersonName(row.kind, name.trim(), networkId, hidden) }; }
+    catch (e) { throw new RequirementFieldError((e as Error).message, field); }
+  }
   const exists = row.kind === 'user'
     ? db.get("SELECT 1 FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 AND m.user_id=?2", networkId, row.id)
     : db.get("SELECT 1 FROM nodes WHERE network_id=?1 AND node_id=?2", networkId, row.id);
@@ -532,6 +542,18 @@ function personRef(value: unknown, networkId: string, hidden: HiddenNode = null,
   return { kind: row.kind, id: row.id };
 }
 
+// participants_remove 的一项 → "kind:id"。给了 id 就直接按 id 比(已经离开网络的人也能从列表里减掉,不查在不在网络里);
+// 没给 id 的形状交给 personRef 解析。受限成员看不见的节点与不存在同一个错误(不给他留探测差异)。
+function participantKey(value: unknown, networkId: string, hidden: HiddenNode, field: string): string {
+  const row = value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+  if (row && (row.kind === 'user' || row.kind === 'node') && typeof row.id === 'string' && row.id.trim()) {
+    if (row.kind === 'node' && hidden?.(row.id)) throw new RequirementFieldError('person_not_in_network', field);
+    return `${row.kind}:${row.id}`;
+  }
+  const ref = personRef(value, networkId, hidden, field);
+  return `${ref.kind}:${ref.id}`;
+}
+
 // 负责人只能是人类,负责 Agent 只能是节点;参与人两种都行。库里旧的节点负责人照样读出来(启动迁移会挪走),
 // 只有这次请求显式写了 owner / agent_owner 才校验种类。
 // 旧客户端兼容(App ≤ 0.2.142 只有一个「负责人」,可以选节点):请求里 owner 是节点、又**没带** agent_owner
@@ -544,7 +566,7 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
   // 受限成员看不见的负责 Agent,他也不能换掉或清空(他读到的是 null,写回 null 不该抹掉别人的指派)。
   const agentOwnerLocked = isHiddenRef(agentOwner, hidden);
   if ('owner' in body) {
-    owner = body.owner === null ? null : personRef(body.owner, networkId, hidden);
+    owner = body.owner === null ? null : personRef(body.owner, networkId, hidden, 'owner');
     if (owner && owner.kind !== 'user') {
       if (strictOwner || 'agent_owner' in body) throw new Error('owner_must_be_human');
       coerced = owner;
@@ -566,6 +588,26 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
     const keptHidden = hidden ? participants.filter((ref: unknown) => isHiddenRef(ref, hidden)) : [];
     participants = [...new Map([...keptHidden, ...refs].map((ref: PersonRef) => [`${ref.kind}:${ref.id}`, ref])).values()];
   }
+  // #475 —— 增量改参与人:participants_add / participants_remove 在当前列表上加 / 减(同步读改写,中间不让出,
+  // 并发的另一个请求插不进来),不碰别的参与人。加已有的人 = 不变;减不在列表里的人 = 不变。
+  // 和整体替换的 participants 不能同时用;同一个人既加又减 = 400,不猜先后。
+  if ('participants_add' in body || 'participants_remove' in body) {
+    if ('participants' in body) throw new RequirementFieldError('participants_conflict', 'participants');
+    const list = (key: string): unknown[] => {
+      const value = body[key];
+      if (value === undefined) return [];
+      if (!Array.isArray(value) || value.length > 100) throw new RequirementFieldError('invalid_participants_delta', key);
+      return value;
+    };
+    const add: PersonRef[] = list('participants_add').map(value => personRef(value, networkId, hidden, 'participants_add'));
+    const remove = new Set(list('participants_remove').map(value => participantKey(value, networkId, hidden, 'participants_remove')));
+    if (add.some(ref => remove.has(`${ref.kind}:${ref.id}`))) throw new RequirementFieldError('participants_add_remove_overlap', 'participants_remove');
+    const next = new Map<string, PersonRef>(participants.map((ref: PersonRef) => [`${ref.kind}:${ref.id}`, ref]));
+    for (const ref of add) if (!next.has(`${ref.kind}:${ref.id}`)) next.set(`${ref.kind}:${ref.id}`, ref);
+    for (const key of remove) next.delete(key);
+    if (next.size > 100) throw new RequirementFieldError('too_many_participants', 'participants_add');
+    participants = [...next.values()];
+  }
   return {
     coerced,
     ownerJson: owner === null ? null : JSON.stringify(owner),
@@ -578,12 +620,16 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
  * 节点令牌(Agent,比如把 GitHub issue 同步进任务的 TM 节点)可用的操作 —— 只在它自己的网络里
  * (令牌绑定的网络,范围由 resolveRestNetworkScope 强制)。删除卡片、管理项目仍然只给人。
  */
-const NODE_TOKEN_OPERATIONS: ReadonlySet<string> = new Set<string>(["read", "create", "patch", "checklist_item", "upsert", "projects_read"]);
+/** 一条评论最多这么多字(去掉首尾空白后);进展 / 结论写得下,又不至于让动态列表里一条撑爆。 */
+export const COMMENT_MAX_CHARS = 4000;
+
+const NODE_TOKEN_OPERATIONS: ReadonlySet<string> = new Set<string>(["read", "create", "patch", "checklist_item", "comment", "upsert", "projects_read"]);
 function operationOf(req: Request, url: URL): string {
   if (/^\/api\/requirements\/projects(\/|$)/.test(url.pathname)) return req.method === "GET" ? "projects_read" : "projects_write";
   if (url.pathname === "/api/requirements/tags/ops") return "tags_write";
   if (req.method === "GET") return "read";
   if (/^\/api\/requirements\/[^/]+\/checklist\/[^/]+$/.test(url.pathname)) return "checklist_item";
+  if (/^\/api\/requirements\/[^/]+\/comments$/.test(url.pathname)) return "comment";
   if (url.pathname === "/api/requirements/upsert") return "upsert";
   if (req.method === "DELETE") return "delete";
   if (req.method === "PATCH") return "patch";
@@ -811,7 +857,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
 }
 
 // ── 修改(省略的字段保留原值) ──
-const PATCH_FIELDS = ["column", "issues", "tags", "name", "priority", "due", "assignee", "owner", "agent_owner", "participants", "description", "checklist", "project_id", "external_ref", "external_url", "archived", "parent_id", "start"];
+const PATCH_FIELDS = ["column", "issues", "tags", "name", "priority", "due", "assignee", "owner", "agent_owner", "participants", "participants_add", "participants_remove", "description", "checklist", "project_id", "external_ref", "external_url", "archived", "parent_id", "start"];
 function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Record<string, unknown>): Response {
   if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400, { sent: Object.keys(body), writable: PATCH_FIELDS });
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
@@ -865,6 +911,15 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   }
   let people;
   try { people = assignments(body, row.network_id, row, hiddenNodeFilter(ctx, row.network_id), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
+  // RFC-040:只凭负责人身份改这张卡时,负责人 / 负责 Agent 只能交给本部门的人(或自己)/ 本部门成员的 Agent,
+  // 不能把卡推出本部门(推出去等于替别的部门派活)。清空(null)不限制。
+  const headOnly = (has("owner") || has("agent_owner")) ? headOnlyEditScope(caller, row) : null;
+  if (headOnly) {
+    const owner = people.ownerJson ? JSON.parse(people.ownerJson) as PersonRef : null;
+    const agent = people.agentOwnerJson ? JSON.parse(people.agentOwnerJson) as PersonRef : null;
+    if (has("owner") && owner && owner.id !== caller!.userId && !headOnly.users.has(owner.id)) return jsonError("department_scope_denied", 403, { field: "owner" });
+    if (has("agent_owner") && agent && !headOnly.nodes.has(agent.id)) return jsonError("department_scope_denied", 403, { field: "agent_owner" });
+  }
   let projectId = row.project_id;
   if (has("project_id")) {
     try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return errorFrom(e); }
@@ -998,6 +1053,23 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   if (ref !== null) sql += ` AND external_ref = ?${params.push(ref)}`;
   const parent = q.get("parent_id");
   if (parent !== null) sql += parent === "none" ? " AND parent_id IS NULL" : ` AND parent_id = ?${params.push(parent)}`;
+  // RFC-040:department_id= —— 负责人是这个部门(含下级)的成员、或负责 Agent 归这些成员所有的卡。可见范围照旧由上面的
+  // addTaskVisibilityScope 管,这里只再收窄。部门按调用者看得见的网络找(部门 id 只在网络内唯一)。
+  const dept = q.get("department_id");
+  if (dept !== null) {
+    if (!dept || !/^[A-Za-z0-9_-]{1,64}$/.test(dept)) return jsonError("department_not_found", 400);
+    const networks = ctx ? departmentNetworks(ctx, dept) : [];
+    if (!networks.length) return jsonError("department_not_found", 400);
+    const parts: string[] = [];
+    for (const networkId of networks) {
+      const cards = departmentCardsFor(networkId, departmentSubtree(networkId, dept));
+      const ors: string[] = [];
+      if (cards.users.size) ors.push(`owner_json IN (${[...cards.users].map((id) => `?${params.push(JSON.stringify({ kind: "user", id }))}`).join(", ")})`);
+      if (cards.nodes.size) ors.push(`agent_owner_json IN (${[...cards.nodes].map((id) => `?${params.push(JSON.stringify({ kind: "node", id }))}`).join(", ")})`);
+      if (ors.length) parts.push(`(network_id = ?${params.push(networkId)} AND (${ors.join(" OR ")}))`);
+    }
+    sql += parts.length ? ` AND (${parts.join(" OR ")})` : " AND 1=0";
+  }
   if (q.get("top_level") === "1") sql += " AND parent_id IS NULL";
   // Explicit archived-only wins over the legacy include-all switch.
   // changes=1 看得见「被归档」这一改动:默认连归档的一起回(行上 archived: true),客户端据此把它移出看板。
@@ -1006,6 +1078,13 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   return sql;
 }
 
+/** department_id 筛选:调用者作用域里有这个部门的网络。 */
+function departmentNetworks(ctx: RequirementsRequestContext, deptId: string): string[] {
+  const params: unknown[] = [deptId];
+  const sql = addHumanNetworkScope("SELECT DISTINCT network_id FROM network_departments WHERE department_id = ?1", params, ctx.scope);
+  return db.all<{ network_id: string }>(sql, ...params).map((r) => r.network_id);
+}
+
 const LIST_ORDER = " ORDER BY created_at DESC, requirement_id DESC";
 type LightRow = { requirement_id: string; seq?: number | null; network_id: string; created_at: string; title: string; description: string | null; assignee: string | null; tags_json: string | null; project_id: string | null; owner_json: string | null; agent_owner_json: string | null; participants_json: string | null };
 const parseRef = (json: string | null) => { try { return json ? JSON.parse(json) : null; } catch { return null; } };
@@ -1115,7 +1194,7 @@ function deletedSince(ctx: RequirementsRequestContext, sinceIso: string): string
 const EVENTS_PAGE_DEFAULT = 200;
 const EVENTS_PAGE_MAX = 500;
 const EVENTS_SCAN_MAX = 5000;
-type VisibilityRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null };
+type VisibilityRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null; agent_owner_json?: string | null };
 
 function listEvents(ctx: RequirementsRequestContext): Response {
   const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
@@ -1142,7 +1221,8 @@ function listEvents(ctx: RequirementsRequestContext): Response {
     let ok = seen.get(id);
     if (ok === undefined) {
       const cols = "network_id, owner_json, participants_json, created_by, created_by_json, project_id";
-      const row = db.get<VisibilityRow>(`SELECT ${cols} FROM requirements WHERE requirement_id = ?1`, id)
+      // agent_owner_json:负责人按「负责 Agent 归本部门成员」也认得这张卡(RFC-040);墓碑表没有这一列。
+      const row = db.get<VisibilityRow>(`SELECT ${cols}, agent_owner_json FROM requirements WHERE requirement_id = ?1`, id)
         ?? db.get<VisibilityRow>(`SELECT ${cols} FROM requirement_tombstones WHERE requirement_id = ?1`, id);
       seen.set(id, ok = !!row && row.network_id === networkId && canSeeTask(caller, row));
     }
@@ -1294,6 +1374,15 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
 
   if (url.pathname === "/api/requirements/events" && req.method === "GET") return listEvents(ctx);
 
+  // #473 —— MCP requirements_people:紧凑通讯录(用户名、角色、部门、名下 Agent),q / limit / offset。
+  if (url.pathname === '/api/requirements/people/directory' && req.method === 'GET') {
+    const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+    if (!networkId) return jsonError('network_id_required', 400);
+    const pq = parsePeopleQuery(url.searchParams);
+    if ('error' in pq) return jsonError(pq.error, 400);
+    return Response.json(peopleDirectory(networkId, hiddenNodeFilter(ctx, networkId), pq));
+  }
+
   if (url.pathname === '/api/requirements/people' && req.method === 'GET') {
     const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
     if (!networkId) return jsonError('network_id_required', 400);
@@ -1388,6 +1477,28 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     return Response.json({ ...data, created: false });
   }
 
+  // #474 评论 / 进展(MCP 任务生命周期测试报告问题 5):以前 Agent 只能读全文再整段改写 description,两次调用、
+  // 并发会覆盖别人刚写的。评论是一条只追加的动态(requirement_events kind=comment,正文存在 new.text),
+  // 不碰 requirements 表的任何一列;谁能看见这张卡谁就能读到,能写这个网络(非只读角色)又看得见它的人能发。
+  const commentMatch = url.pathname.match(/^\/api\/requirements\/([^/]+)\/comments$/);
+  if (commentMatch) {
+    if (req.method !== "POST") return jsonError("not_found", 404);
+    let body: Record<string, unknown>;
+    try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
+    const text = typeof body.text === "string" ? body.text.trim() : "";
+    if (!text) return jsonError("invalid_comment", 400);
+    if (text.length > COMMENT_MAX_CHARS) return jsonError("comment_too_long", 400);
+    const row = scopedRow(ctx, decodeURIComponent(commentMatch[1]));
+    if (row instanceof Response) return row;
+    if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    const at = new Date().toISOString();
+    const event = db.transaction(() => {
+      recordRequirementEvents(db, row, JSON.stringify(actorOf(ctx)), [{ kind: "comment", field: null, old: null, new: { text } }], at);
+      return db.get<EventRow>("SELECT id, network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at FROM requirement_events WHERE requirement_id = ?1 AND kind = 'comment' ORDER BY id DESC LIMIT 1", row.requirement_id)!;
+    });
+    return Response.json({ ok: true, event: eventPublic(event) }, { status: 201 });
+  }
+
   const itemMatch = url.pathname.match(/^\/api\/requirements\/([^/]+)\/checklist\/([^/]+)$/);
   if (itemMatch) {
     if (req.method !== "PATCH") return jsonError("not_found", 404);
@@ -1430,6 +1541,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
     if (!canDeleteTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_delete_denied");
+    const byLeader = deletesAsHeadOnly(taskCaller(ctx), row);
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
     const deletedAt = new Date().toISOString();
     db.transaction(() => {
@@ -1441,6 +1553,11 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     });
     // 硬删除以前不留痕(RFC-038 §9.1):记下是谁删了哪张(标题 + 短号),卡本身已经没了。
     if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_deleted", "requirement", row.requirement_id, JSON.stringify({ title: row.title, seq: row.seq ?? null }).slice(0, 1000), undefined, row.network_id);
+    // RFC-040 Q4:只凭部门负责人身份删的,另记一条并私信卡的负责人(人;没有就私信负责 Agent 的主人)。
+    if (byLeader && ctx.auth) {
+      const notified = notifyLeaderDeleted({ card: row, actorUserId: ctx.auth.userId });
+      logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_deleted_by_leader", "requirement", row.requirement_id, JSON.stringify({ title: row.title, seq: row.seq ?? null, owner: row.owner_json ? JSON.parse(row.owner_json) : null, agent_owner: row.agent_owner_json ? JSON.parse(row.agent_owner_json) : null, notified }).slice(0, 1000), undefined, row.network_id);
+    }
     return Response.json({ ok: true, deleted: row.requirement_id });
   }
   if (req.method !== "PATCH") return jsonError("not_found", 404);

package/src/rest-explicit-columns-http.test.ts

@@ -32,6 +32,8 @@ const GOLDEN_RESPONSE_KEYS = {
   authMeNetwork: [
     "network_id", "network_name", "owner_id", "description", "settings",
     "created_at", "updated_at", "visibility", "max_members", "member_role", "agent_access", "task_access",
+    // RFC-040(#455):不是列,是每次请求现算的「我负责的部门 + 全部下级」(department-heads.ts)。
+    "managed_department_ids",
   ],
   networkDetail: [
     "network_id", "network_name", "owner_id", "description", "settings",