Commit fa86f3638388aaad1d4b2a3ff904ff4bc36cbe05

Authored by bboonnee
1 parent 043d6536

docs: move A/B/D/E/F/G/H's requirements+design docs into docs/done/

Per CLAUDE.md's docs/ role split (todo = pending, done = shipped into the
SDD/code): all seven Graph Engineering series items with a real
implementation (B, D, E, F, G, H -- A had no separate doc, resolved
directly in graphlemon_architecture.md; C is explicitly won't-do) now have
their requirements+design docs moved from docs/todo/ to docs/done/,
git mv'd to preserve history.

Every cross-reference to the 12 moved files -- across the other moved
docs themselves, graph-engineering-open-items.md, 2 Skill files, and 9
src/*.py docstrings/comments -- updated from docs/todo/<file> to
docs/done/<file>. Verified no stale docs/todo/ references to any of the
12 filenames remain anywhere in the repo.

graph-engineering-open-items.md itself stays in docs/todo/ (not moved) --
it's a living index that keeps gaining new entries from later
comparison-note/gap-analysis passes (H itself was added this way, and a
new item already appeared while this cleanup was in progress), not a
single finished conclusion. Its own header now reflects that all of
A/B/D/E/F/G/H are done and explains why it wasn't moved. Also fixed two
pre-existing stray path references (missing todo/done/ prefix entirely,
predating this cleanup) in its G section.

Full src suite (625 tests) passes -- this is a pure documentation/comment
change, no behavior touched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Showing 24 changed files with 26 additions and 26 deletions
docs/todo/dynamic-work-graph-design-skill-design.md renamed to docs/done/dynamic-work-graph-design-skill-design.md
1 1 # 跨 Org Agent 的动态 Work Graph 设计能力——详细设计(SDD)
2 2  
3 3 **日期**: 2026-08-06
4   -**性质**: 详细设计,对应需求文档 `docs/todo/dynamic-work-graph-design-skill-requirements.md`(条目 E,已确认)。回答该需求文档第 8 节的开放问题。
  4 +**性质**: 详细设计,对应需求文档 `docs/done/dynamic-work-graph-design-skill-requirements.md`(条目 E,已确认)。回答该需求文档第 8 节的开放问题。
5 5 **依赖**:条目 G(`docs/work-graph-parallel-execution-design.md`)已实现——`topological_layers()`/`run_graph()` 已经在生产代码里。
6 6 **状态**: 设计草案,待评审后实施。
7 7  
... ...
docs/todo/dynamic-work-graph-design-skill-requirements.md renamed to docs/done/dynamic-work-graph-design-skill-requirements.md
docs/todo/role-package-abstraction-design.md renamed to docs/done/role-package-abstraction-design.md
1 1 # 统一 Role Package 抽象层——详细设计(SDD)
2 2  
3 3 **日期**: 2026-08-06
4   -**性质**: 详细设计,对应需求文档 `docs/todo/role-package-abstraction-requirements.md`(条目 H,需求评审已通过,见 `docs/todo/graph-engineering-open-items.md` H 节的评审记录)。回答该需求文档第 8 节的开放问题。
  4 +**性质**: 详细设计,对应需求文档 `docs/done/role-package-abstraction-requirements.md`(条目 H,需求评审已通过,见 `docs/todo/graph-engineering-open-items.md` H 节的评审记录)。回答该需求文档第 8 节的开放问题。
5 5 **范围确认(用户 2026-08-06)**:FR-3 的 4 张 CHECK 约束表一次性全改,不分阶段。
6 6 **状态**: 设计草案,实施中。
7 7  
... ...
docs/todo/role-package-abstraction-requirements.md renamed to docs/done/role-package-abstraction-requirements.md
... ... @@ -16,7 +16,7 @@
16 16 | **context** | `memory: project` → `.claude/agent-memory/{role}/`,git 版本化;但 Work Node 执行时塞进 prompt 的内容是每个调用点临时拼的(`build_prompt(node, outputs)`),没有独立的"context 组装层"抽象 | 局部实现,无统一抽象 |
17 17 | **skills** | `skills/<name>/SKILL.md`,按名字挂进角色的 `skills:` frontmatter | 七项里最成熟、最像"可复用打包单元"的一个 |
18 18 | **applications** | 没有对应的一等概念。架构文档 §7.2 提到 `mcpServers` 字段可以挂专属 MCP server,但 `agent_profile.py::FRONTMATTER` 里三个角色**一个都没配** | 基本空白 |
19   -| **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,已确认待做) | 机制存在,不是每个角色都能复用的打包能力 |
  19 +| **workflows** | Claude Code 原生 Dynamic Workflows 机制在,但只有 Planner 真正用——`work_graph_plan.py::plan_work_graph()` 的提示词硬编码永远只生成 brd/prd/sdd/benchmark 四个节点,Coder/Validator 走的是更简化的单次 `trigger_org_node()` 调用,没有"先规划图再执行"这条路径(见 `docs/done/dynamic-work-graph-design-skill-requirements.md`,即条目 E,已确认待做) | 机制存在,不是每个角色都能复用的打包能力 |
20 20 | **permissions** | `tools`/`disallowedTools` per role(如 Validator `disallowedTools: [Edit, Write]`) | 有格式,但有记录在案的真实漏洞:`agent_profile.py` 注释明确写了"scoped Bash patterns(如 `Bash(git commit:*)`)会把 Bash 整个禁掉",Validator 的 git-mutation 限制实际上退化成了 SOUL.md 里的文字约定,不是工具层强制 |
21 21 | **acceptance criteria** | Benchmark、PASS/FAIL/INCONCLUSIVE、SDD REQ-01~15、`root_cause_trace` 根因归属 | 七项里最成熟的一环 |
22 22  
... ... @@ -32,7 +32,7 @@
32 32 ## 3. 非目标
33 33  
34 34 1. **不要求第一版就实现"运行时自主创建新角色"**。架构文档 §3"关键设计原则 1"明确 Org Graph 结构是人工定义、代码级固定,改动属于架构变更需要人工评审——这条决策不动。本需求要解决的是"人工新增一个角色时,需要改多少处代码/schema"这个摩擦,而不是让系统自己决定要不要新增角色。新增角色依然是人工发起的动作,只是发起方式从"改代码"变成"写一份声明式的 package"。
35   -2. **不在本文档里解决 workflows 维度的具体落地**——Coder/Validator 缺少动态 Work Graph 规划能力这件事,已经是条目 E(`docs/todo/dynamic-work-graph-design-skill-requirements.md`)的范围,本文档只要求"Role Package 里要有一个字段/引用指向这个角色的 workflow 规划能力",不重复设计 E 已经在做的事。
  35 +2. **不在本文档里解决 workflows 维度的具体落地**——Coder/Validator 缺少动态 Work Graph 规划能力这件事,已经是条目 E(`docs/done/dynamic-work-graph-design-skill-requirements.md`)的范围,本文档只要求"Role Package 里要有一个字段/引用指向这个角色的 workflow 规划能力",不重复设计 E 已经在做的事。
36 36 3. **不在本文档里重新解决 permissions 维度的已知漏洞**(scoped Bash disallowedTools 不生效)——这是 Claude Code 平台本身的行为限制,本文档只要求 Role Package 的 permissions 字段要能诚实反映"这条限制实际上是工具层强制还是仅靠文字约定",不假装这个漏洞已经修复。
37 37 4. **不要求一次性覆盖全部七个维度到同等成熟度**。applications 维度目前是空白,第一版只需要定义清楚"这个维度存在、字段长什么样、允许为空",不要求马上有真实的 MCP server 集成可用。
38 38 5. **不做通用的"角色市场/角色商店"之类的产品化能力**。这是纯粹的内部抽象层重构,不涉及把角色包装成可分发、可交易的产品单元。
... ...
docs/todo/validator-loop-until-dry-skill-design.md renamed to docs/done/validator-loop-until-dry-skill-design.md
1 1 # Validator "未知规模扫描收敛" Skill——详细设计(SDD)
2 2  
3 3 **日期**: 2026-08-06
4   -**性质**: 详细设计,对应需求文档 `docs/todo/validator-loop-until-dry-skill-requirements.md`(条目 B,已确认)。回答该需求文档第 8 节的开放问题。
  4 +**性质**: 详细设计,对应需求文档 `docs/done/validator-loop-until-dry-skill-requirements.md`(条目 B,已确认)。回答该需求文档第 8 节的开放问题。
5 5 **状态**: 设计草案,实施中。
6 6  
7 7 ## 1. 范围确认:纯 Skill,不动执行引擎
... ...
docs/todo/validator-loop-until-dry-skill-requirements.md renamed to docs/done/validator-loop-until-dry-skill-requirements.md
docs/todo/verifier-fan-out-jury-design.md renamed to docs/done/verifier-fan-out-jury-design.md
1 1 # 三视角评审团——Work Graph Fan-out 实现——详细设计(SDD)
2 2  
3 3 **日期**: 2026-08-06
4   -**性质**: 详细设计,对应需求文档 `docs/todo/verifier-fan-out-jury-requirements.md`(条目 F,已确认)。回答该需求文档第 8 节的开放问题。
  4 +**性质**: 详细设计,对应需求文档 `docs/done/verifier-fan-out-jury-requirements.md`(条目 F,已确认)。回答该需求文档第 8 节的开放问题。
5 5 **依赖代码**:`src/root_cause_trace.py`(`judge_root_cause`/`_PERSPECTIVE_FRAMINGS`)、`src/org_level_loop.py`(`run_fix_loop`,唯一真实生产调用方)、`src/work_graph_orchestrate.py`(G 已实现的 `run_graph()`/`topological_layers()`)。
6 6 **状态**: 设计草案,待评审后实施。
7 7  
... ...
docs/todo/verifier-fan-out-jury-requirements.md renamed to docs/done/verifier-fan-out-jury-requirements.md
docs/todo/work-graph-parallel-execution-design.md renamed to docs/done/work-graph-parallel-execution-design.md
docs/todo/work-graph-parallel-execution-requirements.md renamed to docs/done/work-graph-parallel-execution-requirements.md
docs/todo/work-graph-time-travel-debugging-design.md renamed to docs/done/work-graph-time-travel-debugging-design.md
1 1 # Work Graph 执行历史 Time-Travel 调试——详细设计(SDD)
2 2  
3 3 **日期**: 2026-08-06
4   -**性质**: 详细设计,对应需求文档 `docs/todo/work-graph-time-travel-debugging-requirements.md`(条目 D,已确认)。回答该需求文档第 8 节的开放问题。
  4 +**性质**: 详细设计,对应需求文档 `docs/done/work-graph-time-travel-debugging-requirements.md`(条目 D,已确认)。回答该需求文档第 8 节的开放问题。
5 5 **状态**: 设计草案,实施中,后端+控制台一起做(用户 2026-08-06 确认)。
6 6  
7 7 ## 1. `ux_work_graph_run_active` 比需求文档描述的风险更小
... ...
docs/todo/work-graph-time-travel-debugging-requirements.md renamed to docs/done/work-graph-time-travel-debugging-requirements.md
docs/todo/graph-engineering-open-items.md
1 1 # Graph Engineering 系列对照笔记——待确认事项清单
2 2  
3   -**日期**: 2026-08-04(2026-08-05 更新:A/B/D/E/F/G 已确认方向,C 已确认暂不做)
4   -**性质**: 从三份对照笔记里提取出的全部"待讨论的开放问题",去重合并后按主题整理,供逐条确认方案。每条确认后会展开成独立的需求文档(参考 `docs/work-graph-parallel-execution-requirements.md` 的产出方式),本文件本身只做索引和现状追踪,不写详细方案。
  3 +**日期**: 2026-08-04(2026-08-06 更新:A/B/D/E/F/G/H 全部已实现,C 已确认不做——全部条目均已resolve,本文件继续作为这条主线的活索引保留在 `docs/todo/`,不迁入 `docs/done/`,因为它会随新一批对照笔记/差距检查持续追加条目,见 H 的加入方式)
  4 +**性质**: 从三份对照笔记里提取出的全部"待讨论的开放问题",去重合并后按主题整理,供逐条确认方案。每条确认后会展开成独立的需求文档(参考 `docs/done/work-graph-parallel-execution-requirements.md` 的产出方式,条目落地后连同设计文档一并移入 `docs/done/`),本文件本身只做索引和现状追踪,不写详细方案。
5 5 **来源文档**:
6 6 - `docs/reference/graph-engineering-1000-agents-5-steps.diff-with-graphlemon.md`(简称"5 步版对照")
7 7 - `docs/reference/graph-engineering-vs-loop-engineering-overview.diff-with-graphlemon.md`(简称"综述版对照")
... ... @@ -36,7 +36,7 @@
36 36  
37 37 ## B. loop-until-dry 要不要在 Validator 落地
38 38  
39   -**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/todo/validator-loop-until-dry-skill-requirements.md` + 设计文档 `docs/todo/validator-loop-until-dry-skill-design.md`
  39 +**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/done/validator-loop-until-dry-skill-requirements.md` + 设计文档 `docs/done/validator-loop-until-dry-skill-design.md`
40 40  
41 41 **来源**:5 步版对照 §4 开放问题 1
42 42  
... ... @@ -62,7 +62,7 @@
62 62  
63 63 ## D. Time-travel 调试要不要立项
64 64  
65   -**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/todo/work-graph-time-travel-debugging-requirements.md` + 设计文档 `docs/todo/work-graph-time-travel-debugging-design.md`
  65 +**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/done/work-graph-time-travel-debugging-requirements.md` + 设计文档 `docs/done/work-graph-time-travel-debugging-design.md`
66 66  
67 67 **来源**:综述版对照 §6
68 68  
... ... @@ -78,7 +78,7 @@
78 78  
79 79 ## E. Planning Skill 提示词强化——识别可并行节点 + 通用 Work Graph 设计能力
80 80  
81   -**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/todo/dynamic-work-graph-design-skill-requirements.md` + 设计文档 `docs/todo/dynamic-work-graph-design-skill-design.md`
  81 +**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/done/dynamic-work-graph-design-skill-requirements.md` + 设计文档 `docs/done/dynamic-work-graph-design-skill-design.md`
82 82  
83 83 **来源**:综述版对照 §7 开放问题 3 + 14 步版对照 §3 开放问题 2(同一主题:让 Planning 阶段更早识别并行机会)
84 84  
... ... @@ -92,7 +92,7 @@
92 92  
93 93 ## F. 三视角评审团机制要不要推广到其他验证点
94 94  
95   -**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/todo/verifier-fan-out-jury-requirements.md` + 设计文档 `docs/todo/verifier-fan-out-jury-design.md`
  95 +**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/done/verifier-fan-out-jury-requirements.md` + 设计文档 `docs/done/verifier-fan-out-jury-design.md`
96 96  
97 97 **来源**:综述版对照 §7 开放问题 4 + 14 步版对照 §3 开放问题 4(同一主题)
98 98  
... ... @@ -106,7 +106,7 @@
106 106  
107 107 ## G. Work Graph 节点并行执行(Python 线程池方案)
108 108  
109   -**状态**:✅ 已实现(2026-08-06)→ 需求文档见 `docs/work-graph-parallel-execution-requirements.md`
  109 +**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/done/work-graph-parallel-execution-requirements.md` + 设计文档 `docs/done/work-graph-parallel-execution-design.md`
110 110  
111 111 **来源**:14 步版对照 §3 开放问题 1
112 112  
... ... @@ -120,7 +120,7 @@
120 120  
121 121 ## H. 统一 Role Package 抽象层
122 122  
123   -**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/todo/role-package-abstraction-requirements.md` + 设计文档 `docs/todo/role-package-abstraction-design.md`
  123 +**状态**:✅ 已实现(2026-08-06)→ 需求文档 `docs/done/role-package-abstraction-requirements.md` + 设计文档 `docs/done/role-package-abstraction-design.md`
124 124  
125 125 **来源**:不属于三份 Graph Engineering 对照笔记,是用户对照 Agentic Enterprise 产品目标("role + context + skills + applications + workflows + permissions + acceptance criteria;all essentially are context for intelligent computing")单独提出的差距检查,2026-08-06。
126 126  
... ...
skills/design-dynamic-work-graph/SKILL.md
... ... @@ -11,7 +11,7 @@ tags:
11 11 - orchestration
12 12 metadata:
13 13 origin: graphlemon-native
14   - related: [G(并行执行)docs/work-graph-parallel-execution-design.md, E docs/todo/dynamic-work-graph-design-skill-design.md]
  14 + related: [G(并行执行)docs/work-graph-parallel-execution-design.md, E docs/done/dynamic-work-graph-design-skill-design.md]
15 15 platforms: [linux, macos, windows]
16 16 ---
17 17  
... ...
skills/unknown-scope-defect-sweep/SKILL.md
... ... @@ -11,7 +11,7 @@ tags:
11 11 - sweep
12 12 metadata:
13 13 origin: graphlemon-native
14   - related: [qa-task-validation, docs/todo/validator-loop-until-dry-skill-design.md]
  14 + related: [qa-task-validation, docs/done/validator-loop-until-dry-skill-design.md]
15 15 platforms: [linux, macos, windows]
16 16 ---
17 17  
... ...
src/agent_profile.py
... ... @@ -33,7 +33,7 @@ read by this module&#39;s own Python code; `json.load` is the zero-risk choice,
33 33 no hand-rolled parser. role.json content is deliberately a REFERENCE
34 34 manifest, not a content copy: `identity.soul_md_path`/`agents_md_path` still
35 35 point at the same `agents/<org_node>/SOUL.md`/`AGENTS.md` files, unmoved --
36   -see docs/todo/role-package-abstraction-design.md §2 for why keeping the
  36 +see docs/done/role-package-abstraction-design.md §2 for why keeping the
37 37 existing identity files as the single source of prose content makes the
38 38 migration's "deployed output must stay byte-identical" requirement close to
39 39 automatic (only the frontmatter's data SOURCE changed, not the body-assembly
... ...
src/org_level_loop.py
... ... @@ -17,7 +17,7 @@ def run_fix_loop(conn, task_id, target_folder_path, bug_description, context, fi
17 17 function doesn't add its own fallback for that, matching 04-P's own
18 18 "升级人工" answer to disagreement).
19 19  
20   - **F (2026-08-06, docs/todo/verifier-fan-out-jury-design.md)**: root
  20 + **F (2026-08-06, docs/done/verifier-fan-out-jury-design.md)**: root
21 21 cause judgment now runs as a real Work Graph fan-out (each perspective
22 22 is its own Work Node with its own clean context) instead of three
23 23 sequential Python closures calling org_node_trigger.trigger_org_node --
... ...
src/root_cause_trace.py
... ... @@ -15,7 +15,7 @@ concrete question each perspective asks is a prompt-engineering concern for
15 15 the caller (see real_validator_perspective below for the real-call version),
16 16 not this module's.
17 17  
18   -**F (2026-08-06, docs/todo/verifier-fan-out-jury-design.md)**: judge_root_cause
  18 +**F (2026-08-06, docs/done/verifier-fan-out-jury-design.md)**: judge_root_cause
19 19 above is the closure-based implementation -- each perspective is a Python
20 20 function call, sequentially, in the SAME process/context. Kept as-is (not
21 21 replaced): it's the cheap path for scenarios that don't need worktree/Work
... ...
src/schema.py
... ... @@ -84,7 +84,7 @@ CREATE TABLE skill (
84 84 -- ('planner','coder','validator')) -- relaxed to a plain non-empty-string
85 85 -- check so a new role, added purely via roles/<role_id>/role.json (no
86 86 -- schema.py/agent_profile.py code change), isn't rejected by a stale
87   - -- hardcoded enum. See docs/todo/role-package-abstraction-design.md §4.
  87 + -- hardcoded enum. See docs/done/role-package-abstraction-design.md §4.
88 88 owner_org_node TEXT NOT NULL CHECK (owner_org_node != ''),
89 89 file_path TEXT NOT NULL,
90 90 current_git_commit_sha TEXT NOT NULL,
... ...
src/test_org_level_loop.py
... ... @@ -5,7 +5,7 @@ Testing constraint). Real coverage is in src/test_org_level_loop_e2e.py
5 5  
6 6 **F (2026-08-06)**: root-cause judgment now runs through
7 7 root_cause_trace.judge_root_cause_via_work_graph (a real Work Graph fan-out,
8   -see docs/todo/verifier-fan-out-jury-design.md), so the 3 perspective calls
  8 +see docs/done/verifier-fan-out-jury-design.md), so the 3 perspective calls
9 9 are mocked at work_graph_execute.write_workflow_script/execute_work_graph
10 10 (same boundary as test_work_graph_orchestrate.py), not at
11 11 org_node_trigger.trigger_org_node -- that mock is now only used for the
... ...
src/test_work_graph_fork.py
1 1 """D (2026-08-06) tests: work_graph_fork.py, mocked at the claude
2 2 subprocess boundary (CLAUDE.md Testing constraint) -- same pattern as
3 3 test_work_graph_orchestrate.py. Covers the requirements doc's acceptance
4   -standards 1-3 (docs/todo/work-graph-time-travel-debugging-requirements.md).
  4 +standards 1-3 (docs/done/work-graph-time-travel-debugging-requirements.md).
5 5  
6 6 Run: python3 -m unittest src.test_work_graph_fork -v
7 7 """
... ...
src/work_graph_fork.py
... ... @@ -3,7 +3,7 @@ work_graph_run from an already-&#39;done&#39; work_node_execution, substituting a
3 3 human-provided output for that node and re-executing everything strictly
4 4 downstream of it for real, while every other node reuses the original
5 5 run's persisted output_payload untouched. See
6   -docs/todo/work-graph-time-travel-debugging-design.md for the full design.
  6 +docs/done/work-graph-time-travel-debugging-design.md for the full design.
7 7  
8 8 **Output substitution, not re-prompting** (design doc §2, resolving the
9 9 requirements doc's FR-1 ambiguity): the fork point's own output_payload is
... ...
src/work_graph_orchestrate.py
... ... @@ -352,7 +352,7 @@ def run_graph(
352 352 independent work, no reason to throw away completed work), then raised
353 353 together as `WorkGraphLayerError` once the whole layer has settled.
354 354 One real limitation, accepted deliberately (see
355   - `docs/todo/work-graph-parallel-execution-design.md` §6): a node
  355 + `docs/done/work-graph-parallel-execution-design.md` §6): a node
356 356 waiting on a quota-backoff sleep inside `run_work_node` blocks the
357 357 thread pool worker running it, which in turn blocks the layer barrier
358 358 even after every sibling has finished -- Python threads have no clean
... ...
src/work_graph_plan.py
... ... @@ -80,7 +80,7 @@ _PROMPT_TEMPLATE = (
80 80 # E (2026-08-06): the generic, cross-Org-Agent path -- used for every
81 81 # org_node OTHER than 'planner'. Planner's own doc-writing chain stays on
82 82 # _PROMPT_TEMPLATE above unchanged (zero regression risk, see
83   -# docs/todo/dynamic-work-graph-design-skill-design.md §3): that chain is a
  83 +# docs/done/dynamic-work-graph-design-skill-design.md §3): that chain is a
84 84 # fixed architectural constant (brd->prd->sdd->benchmark->...), not
85 85 # something that should vary call to call, whereas Coder/Validator's
86 86 # sub-tasks have no such fixed small vocabulary of node types. Each node
... ...