From acfca5bf8cce116802e3f86cc1b86010b278ed78 Mon Sep 17 00:00:00 2001
From: bboonnee <bboonnee@gmail.com>
Date: Thu, 6 Aug 2026 15:48:36 +0800
Subject: [PATCH] H: requirements review for the Role Package abstraction proposal

---
 docs/todo/graph-engineering-open-items.md          | 13 +++++++++----
 docs/todo/role-package-abstraction-requirements.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+), 4 deletions(-)
 create mode 100644 docs/todo/role-package-abstraction-requirements.md

diff --git a/docs/todo/graph-engineering-open-items.md b/docs/todo/graph-engineering-open-items.md
index ee64f6f..f4c384a 100644
--- a/docs/todo/graph-engineering-open-items.md
+++ b/docs/todo/graph-engineering-open-items.md
@@ -118,13 +118,18 @@
 
 ## H. 统一 Role Package 抽象层
 
-**状态**：🟡 需求文档已产出，待评审/排期
+**状态**：✅ 已确认（需求评审通过，2026-08-06）→ 需求文档 `docs/todo/role-package-abstraction-requirements.md`（注：文档正文里自己写的路径少了 `todo/` 一段，实际文件在这个路径下）
 
 **来源**：不属于三份 Graph Engineering 对照笔记，是用户对照 Agentic Enterprise 产品目标（"role + context + skills + applications + workflows + permissions + acceptance criteria；all essentially are context for intelligent computing"）单独提出的差距检查，2026-08-06。
 
 **背景**：逐维度核对代码发现，七个维度里六个都有对应实现（applications 是真空白），但没有被收敛成一个统一的"role package"格式——理解"Validator 这个角色完整定义是什么"现在得同时读 `agent_profile.py` + `skills/qa-task-validation/SKILL.md` + `.claude/agent-memory/validator/` + `docs/sdd/06-验收与测试锚点.md` 四个地方拼出来。更根本的问题：`role` 本身不是数据驱动的——`ORG_NODES = ("planner", "coder", "validator")` 硬编码元组，`schema.py` 四张表的 `CHECK (org_node IN ('planner','coder','validator'))` 约束——新增角色需要改代码和 schema，不是"包一个新角色进来"。
 
-**待办**：需求文档已产出 → `docs/role-package-abstraction-requirements.md`。核心可验证标准：能不能只靠"写一份新的 Role Package"、不改 `schema.py` 约束、不改 `agent_profile.py` 硬编码字典，就让系统认识一个新角色。已知这条改动面比 B/D/E/F/G 任何一条都大（4 张表的 CHECK 约束、`agent_profile.py` 被多处代码依赖），且 workflows 维度依赖 E 的产出。
+**需求评审结果（2026-08-06）**：方向确认，目标/非目标/FR-1~6 按原文通过，进入设计阶段。逐条核实过文档里对代码现状的描述后，发现两处需要修正/补充：
+
+1. **风险第 1 条的依赖清单不准确，且遗漏了真正的大头**。文档写"`ORG_NODES`/`FRONTMATTER` 被 `deploy_agent_definitions`、`org_node_trigger`、`work_graph_orchestrate` 等多处代码直接依赖"——实测 `work_graph_orchestrate.py` 根本不 `import agent_profile`，这条是误判；真正 `from src.agent_profile import ORG_NODES`/`from src import agent_profile` 的只有 `org_node_trigger.py`（校验 `org_node` 合法性）和 `project_scaffold.py`（调 `deploy_agent_definitions()` 这一个单一入口）——这部分实际依赖面比文档描述的**更小**，是个好消息。但文档完全没提到两处真正硬编码了三元组的地方：`src/work_graph_run_query.py::_VALID_ORG_NODES`，以及**分量最大的**——`frontend/app.js` 里四处独立硬编码（`ORG_NODE_DETAIL_RE` 路由正则、`ORG_NODE_ORDER` 排序数组、任务创建表单的 `<option value="planner">` 下拉硬编码列表、`byOrgNode` 查找对象字面量）。设计阶段的依赖梳理必须把这四处也纳入，不能只看 `schema.py`+`agent_profile.py`。
+2. **验收标准 1 的边界需要说清楚，不要造成"前端也覆盖了"的错觉**。标准 1 明确写了"这个新角色不需要真的接入 Org Graph 执行"（呼应非目标 #1），这意味着即使 FR-3/FR-4（schema + `agent_profile.py`）全部做完，**PH3 控制台依然认不出这个新角色**（上面第 1 点列的 4 处前端硬编码不在 FR-3/FR-4 范围内）——这不是要求本轮解决，而是要求设计文档明确写清楚"前端展示新角色是本轮已知不覆盖的范围"，不要让"新增角色不用改代码"这句话被误读成端到端成立。
+
+其余判断（`role` 表外键 vs 自由文本+应用层校验、applications 维度最小定义、迁移步骤、workflows 字段怎么接 E）维持文档第 8 节"留待详细设计阶段回答"不变，本次评审不抢先拍板。
 
 ---
 
@@ -135,8 +140,8 @@
 | **G** 并行执行 | Work Graph 层内并发、层间屏障 | ✅ **已实现**（`bc0eaa5`，575 测试全绿） | M | 已完成 | 无 |
 | **E** 动态 Work Graph 设计能力 | 让 Coder/Validator 也能规划自己的图，Planning 提示词识别可并行节点 | ✅ **已实现**（2026-08-06，580 测试全绿） | L | 已完成 | G（已满足） |
 | **F** 三视角评审团 fan-out | `judge_root_cause` 从 Python 函数改成 Work Graph 菱形拓扑 | ✅ **已实现**（2026-08-06，586 测试全绿） | M | 已完成 | 无（G 已满足） |
-| **B** loop-until-dry Skill | Validator 未知规模扫描收敛能力 | 仅需求 | S/M | P2 | 无 |
-| **H** Role Package 抽象层 | 统一 role/context/skills/applications/workflows/permissions/acceptance 打包格式 | 仅需求 | XL | P2（战略级，不阻塞其他项） | workflows 字段依赖 E 的产出 |
+| **B** loop-until-dry Skill | Validator 未知规模扫描收敛能力 | 实现中 | S/M | P0（正在推进） | 无 |
+| **H** Role Package 抽象层 | 统一 role/context/skills/applications/workflows/permissions/acceptance 打包格式 | ✅ 需求评审通过（2026-08-06），待设计 | XL | P2（战略级，不阻塞其他项） | workflows 字段依赖 E 的产出（已满足） |
 | **D** Time-travel 调试 | 回到历史节点分叉重跑 | 仅需求 | L | P3 | 无强依赖，但价值随图变复杂（E 落地后）才会显现 |
 | C 按节点选模型 | — | ⛔ 已确认不做 | — | — | — |
 | A 术语对照 | — | ✅ 已完成 | — | — | — |
diff --git a/docs/todo/role-package-abstraction-requirements.md b/docs/todo/role-package-abstraction-requirements.md
new file mode 100644
index 0000000..00ee4f0
--- /dev/null
+++ b/docs/todo/role-package-abstraction-requirements.md
@@ -0,0 +1,76 @@
+# 统一 Role Package 抽象层——需求文档
+
+**日期**: 2026-08-06
+**性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。回应用户对 Agentic Enterprise 产品"可复用打包单元"目标的对照检查——"role + context + skills + applications + workflows + permissions + acceptance criteria；all essentially are context for intelligent computing"。
+**状态**: 草案，待评审。
+
+## 1. 背景
+
+用户提出的目标判断是：Agentic Enterprise 产品的可复用打包单元，本质上应该是 role / context / skills / applications / workflows / permissions / acceptance criteria 这七个维度，而且这七个维度**本质上是同一种东西**——喂给智能计算的 context，应该被统一表达成一个可序列化、可实例化、可复制的对象。
+
+对照 graphlemon 现状（逐维度核对代码得出）：
+
+| 维度 | 现状 | 成熟度 |
+|---|---|---|
+| **role** | `.claude/agents/{planner,coder,validator}.md` + `agents/*/SOUL.md`，`src/agent_profile.py::FRONTMATTER` 是权威定义 | 有清晰打包格式，但**不可重复实例化**——见第 2 节 |
+| **context** | `memory: project` → `.claude/agent-memory/{role}/`，git 版本化；但 Work Node 执行时塞进 prompt 的内容是每个调用点临时拼的（`build_prompt(node, outputs)`），没有独立的"context 组装层"抽象 | 局部实现，无统一抽象 |
+| **skills** | `skills/<name>/SKILL.md`，按名字挂进角色的 `skills:` frontmatter | 七项里最成熟、最像"可复用打包单元"的一个 |
+| **applications** | 没有对应的一等概念。架构文档 §7.2 提到 `mcpServers` 字段可以挂专属 MCP server，但 `agent_profile.py::FRONTMATTER` 里三个角色**一个都没配** | 基本空白 |
+| **workflows** | Claude Code 原生 Dynamic Workflows 机制在，但只有 Planner 真正用——`work_graph_plan.py::plan_work_graph()` 的提示词硬编码永远只生成 brd/prd/sdd/benchmark 四个节点，Coder/Validator 走的是更简化的单次 `trigger_org_node()` 调用，没有"先规划图再执行"这条路径（见 `docs/todo/dynamic-work-graph-design-skill-requirements.md`，即条目 E，已确认待做） | 机制存在，不是每个角色都能复用的打包能力 |
+| **permissions** | `tools`/`disallowedTools` per role（如 Validator `disallowedTools: [Edit, Write]`） | 有格式，但有记录在案的真实漏洞：`agent_profile.py` 注释明确写了"scoped Bash patterns（如 `Bash(git commit:*)`）会把 Bash 整个禁掉"，Validator 的 git-mutation 限制实际上退化成了 SOUL.md 里的文字约定，不是工具层强制 |
+| **acceptance criteria** | Benchmark、PASS/FAIL/INCONCLUSIVE、SDD REQ-01~15、`root_cause_trace` 根因归属 | 七项里最成熟的一环 |
+
+**核心判断**：这不是功能缺口，是抽象层缺口。七个维度里六个都有对应实现（applications 是真空白），但没有被收敛成一个统一的"role package"格式——要理解"Validator 这个角色完整定义是什么"，现在得同时读 `agent_profile.py` + `skills/qa-task-validation/SKILL.md` + `.claude/agent-memory/validator/` + `docs/sdd/06-验收与测试锚点.md` 四个地方拼出来。而且 role 本身不是数据驱动的——`src/agent_profile.py::ORG_NODES = ("planner", "coder", "validator")` 是硬编码元组，`src/schema.py` 里四张表（`skill.owner_org_node`、`task.assigned_org_node`、`work_graph_run.org_node`、`agent_profile.org_node`）全部是 `CHECK (... IN ('planner', 'coder', 'validator'))` 的枚举约束——新增一个角色需要改代码和 schema，不是"包一个新角色进来"。
+
+## 2. 目标
+
+1. 定义一个统一的、可序列化的"Role Package"抽象——把 role/context/skills/applications/workflows/permissions/acceptance criteria 这七个维度表达成同一种对象的不同字段/引用，而不是分散在 frontmatter、独立目录、运行时生成脚本、SDD 文档四个不相关的地方。
+2. 让"角色"从硬编码的 3 个枚举值变成数据驱动的、可新增的对象——**具体的可验证标准**：能不能不改 `schema.py` 的 CHECK 约束、不改 `agent_profile.py` 的硬编码字典，只靠"写一份新的 role package"就让系统认识一个新角色。
+3. 把 applications 这个目前空白的维度定义清楚——至少要回答"一个角色能调用哪些外部工具/集成/MCP server"这件事该怎么表达，不要求第一版就有完整实现。
+4. 现有 Planner/Coder/Validator 三个角色要能**用新格式重新表达**（迁移，不是重写行为），验证这套抽象本身是自洽的，不是只停留在文档设计层面。
+
+## 3. 非目标
+
+1. **不要求第一版就实现"运行时自主创建新角色"**。架构文档 §3"关键设计原则 1"明确 Org Graph 结构是人工定义、代码级固定，改动属于架构变更需要人工评审——这条决策不动。本需求要解决的是"人工新增一个角色时，需要改多少处代码/schema"这个摩擦，而不是让系统自己决定要不要新增角色。新增角色依然是人工发起的动作，只是发起方式从"改代码"变成"写一份声明式的 package"。
+2. **不在本文档里解决 workflows 维度的具体落地**——Coder/Validator 缺少动态 Work Graph 规划能力这件事，已经是条目 E（`docs/todo/dynamic-work-graph-design-skill-requirements.md`）的范围，本文档只要求"Role Package 里要有一个字段/引用指向这个角色的 workflow 规划能力"，不重复设计 E 已经在做的事。
+3. **不在本文档里重新解决 permissions 维度的已知漏洞**（scoped Bash disallowedTools 不生效）——这是 Claude Code 平台本身的行为限制，本文档只要求 Role Package 的 permissions 字段要能诚实反映"这条限制实际上是工具层强制还是仅靠文字约定"，不假装这个漏洞已经修复。
+4. **不要求一次性覆盖全部七个维度到同等成熟度**。applications 维度目前是空白，第一版只需要定义清楚"这个维度存在、字段长什么样、允许为空"，不要求马上有真实的 MCP server 集成可用。
+5. **不做通用的"角色市场/角色商店"之类的产品化能力**。这是纯粹的内部抽象层重构，不涉及把角色包装成可分发、可交易的产品单元。
+
+## 4. 功能需求
+
+| # | 需求描述 | 优先级 |
+|---|---|---|
+| FR-1 | 定义 Role Package 的字段结构，覆盖七个维度：role（身份/人设，对应现有 SOUL.md 正文）、context（memory 配置 + 运行时 context 组装规则的引用）、skills（技能列表，对应现有 `skills:` frontmatter）、applications（可调用的外部工具/集成/MCP server 列表，当前允许为空）、workflows（该角色的 Work Graph 规划能力引用，对接条目 E 的产出）、permissions（tools/disallowedTools，并诚实标注每条限制是工具层强制还是仅文字约定）、acceptance criteria（该角色产出的验收标准引用，比如 Validator 对接 SDD REQ 锚点）。 | 必须 |
+| FR-2 | Role Package 需要是**声明式**的（数据，不是代码）——具体载体形式（单个 YAML/JSON 文件、还是延续现在"一个目录 + 几个子文件"的约定）留待设计阶段决定，但判断标准是"新增一个角色不需要写 Python 代码"。 | 必须 |
+| FR-3 | `src/schema.py` 里 `org_node` 相关的四处 `CHECK (org_node IN ('planner','coder','validator'))` 约束需要改造成不再硬编码这三个值——具体改造方式（改成引用一张新的 `role` 表做外键约束，还是放开成自由文本 + 应用层校验）留待设计阶段决定。 | 必须 |
+| FR-4 | `src/agent_profile.py::ORG_NODES`/`FRONTMATTER` 这两个硬编码常量需要改造成从 Role Package 读取，而不是 Python 字典里硬写三个角色的定义——但 `deploy_agent_definitions()` 对外的部署行为（生成 `.claude/agents/*.md`）保持不变，只是数据来源变了。 | 必须 |
+| FR-5 | 现有 Planner/Coder/Validator 三个角色需要各自被表达成一份 Role Package，作为这套抽象的第一批真实用例，且迁移后系统对外行为（部署出的 `.claude/agents/*.md` 内容、实际执行结果）不应该有可观察的变化——这是一次纯粹的内部表达方式重构，不是功能变更。 | 必须 |
+| FR-6 | applications 维度需要有一个明确的最小定义（哪怕第一版只是"MCP server 列表，允许为空"），不能继续保持"架构文档提过但从未真正定义"的状态。 | 应该 |
+
+## 5. 验收标准
+
+1. **核心验收（对应目标 2 的可验证标准）**：能够只通过"新增一份 Role Package"（不改 `schema.py`、不改 `agent_profile.py` 的硬编码逻辑）让系统认识一个新角色，并成功为它部署出一份 `.claude/agents/<新角色>.md`。这个新角色不需要真的接入 Org Graph 执行（Org Graph 本身仍是人工评审后才能改的架构决策，见非目标第 1 条），只需要验证"定义一个角色"这件事本身不再需要写 Python 代码或改 schema 约束。
+2. 迁移后，现有 Planner/Coder/Validator 三个角色部署出的 `.claude/agents/*.md` 内容（frontmatter 字段、正文）跟迁移前逐字节一致（或差异只是格式规范化，不影响语义），既有测试套件（`src/test_agent_profile.py` 一类）全部通过，不需要修改断言。
+3. 给定一份 Role Package，能够看清楚它在七个维度上分别声明了什么——不需要再像现状一样，为了理解"这个角色能干什么"而去翻四个不同的地方。
+4. permissions 维度里，Validator 的 git-mutation 限制在新格式里被诚实标注为"仅文字约定，非工具层强制"（不是假装它已经被强制执行）。
+
+## 6. 约束与假设
+
+- 这次重构不改变 Org Graph 本身"人工设计、变更需人工评审"的既定原则（架构文档 §3 决策 1），只改变"定义一个角色的具体成本"。
+- Role Package 的 workflows 字段依赖条目 E 的产出（跨 Org Agent 通用的动态 Work Graph 设计能力）——如果 E 还没落地，Role Package 的 workflows 字段可以先指向"占位/尚未实现"，不阻塞本需求其余六个维度的推进。
+- 复用现有的 Skill 目录约定（`skills/<name>/SKILL.md`）和 memory 约定（`memory: project` → `.claude/agent-memory/{role}/`），不重新发明这两块已经工作良好的机制，只是让 Role Package 引用它们，而不是重新定义。
+
+## 7. 风险
+
+- **改动面比 B/D/E/F/G 任何一条都大**：`org_node` 的 CHECK 约束出现在 4 张表上，`ORG_NODES`/`FRONTMATTER` 被 `deploy_agent_definitions`、`org_node_trigger`、`work_graph_orchestrate` 等多处代码直接依赖，改造前需要在设计阶段完整梳理所有依赖点，不能只看 schema 定义本身。
+- **applications 维度定义不清可能导致设计阶段卡壳**——这是七个维度里唯一"从零开始"的，没有现成机制可以对齐（不像 skills/permissions/acceptance criteria 那样已经有半成品可以收编），需要额外的探索性设计工作，不能假设跟其他六个维度一样容易定义。
+- **"声明式、不用写代码就能新增角色"这个目标可能跟 Claude Code 本身的能力边界冲突**——`.claude/agents/*.md` 的部署机制、`skills:`/`tools:` frontmatter 本身已经是 Claude Code 原生支持的声明式格式，Role Package 更多是在这之上再包一层统一抽象，需要在设计阶段验证这层抽象不会变成"重新发明 Claude Code 已经提供的能力"的冗余包装。
+
+## 8. 开放问题（留给详细设计阶段回答）
+
+- [ ] Role Package 的具体载体格式（单文件 vs 目录约定）。
+- [ ] `org_node` CHECK 约束的改造方式——新增 `role` 表做外键，还是放开成自由文本 + 应用层校验。
+- [ ] applications 维度的最小可行定义——只是 MCP server 列表，还是要覆盖更广的"角色能操作哪些外部系统"。
+- [ ] 迁移 Planner/Coder/Validator 三个现有角色到新格式的具体步骤和验证方式。
+- [ ] 这套抽象跟条目 E（动态 Work Graph 设计能力）的接口——Role Package 的 workflows 字段具体怎么引用 E 的产出。
--
libgit2 0.21.4