graphlemon: auto-commit uncommitted changes for 33e0266c-d2ec-4982-9128-afd2d36a…

…ea4d-main-checkout-drift

graphlemon: auto-commit uncommitted changes for 33e0266c-d2ec-4982-9128-afd2d36a…
…ea4d-main-checkout-drift
graphlemon
1 parent 9eb4ef96
Showing 4 changed files with 88 additions and 25 deletions
.claude/agent-memory/validator/MEMORY.md
.claude/agent-memory/validator/feedback_fake_dom_escapehtml_harness.md
docs/todo/graph-engineering-open-items.md
docs/work-graph-parallel-execution-requirements.md
 - [Self-hosting loop_round probe](project_self_hosting_loop_round_probe.md) — task 14fd9ab6 was a deliberate no-bug probe; verified PASS, no code change is the correct outcome
 - [Zero-diff terminal state gap (2nd instance)](project_zero_diff_terminal_state_gap.md) — scheduler.py _BUSY_TIMEOUT_MS comment already present, PASS/no-change; same recurring pipeline gap as org_loop_route.py
 - [deploy_health_check comment resolved + stale-benchmark pattern](project_deploy_health_check_comment_resolved_stale_benchmark.md) — line 24 comment now PASS-verified; a task's benchmark.md can be superseded by that task's own later code_diff/test_report
+- [Fake-DOM escapeHtml harness gotcha](feedback_fake_dom_escapehtml_harness.md) — ad hoc app.js DOM harnesses need real textContent->innerHTML escaping or escapeHtml() falsely looks blank
+---
+name: feedback-fake-dom-escapehtml-harness
+description: When writing an ad hoc fake-DOM harness to independently verify frontend/app.js click/navigation flows, document.createElement's stub must implement real textContent->innerHTML entity-escaping, or escapeHtml() silently returns "" and looks like a content bug that isn't real.
+metadata:
+  type: feedback
+---
+
+`frontend/app.js`'s `escapeHtml(text)` (line ~20) works by setting a real DOM
+element's `.textContent` and reading `.innerHTML` back, relying on the browser
+to do entity-escaping as a side effect — it does not use string replace itself.
+
+**Why:** while independently verifying task 773a7a08 (Planner 产出总览 list
+click-through to `#/artifacts/:id`), I wrote a throwaway Node `vm` harness to
+simulate a real click -> hashchange -> render() -> mountArtifactBrowser ->
+showPreview flow (going beyond the repo's own `frontend/test_graph_console_smoke.js`,
+which only exercises pure render functions, not the full DOM/fetch mount flow).
+My first `document.createElement` stub had a naive `innerHTML` getter/setter
+pair that just stored/returned a string, with no `textContent` handling at
+all — so every `escapeHtml()` call inside app.js silently returned `""`, and
+the simulated artifact preview came back completely blank (type and content
+both empty) even though the fetched artifact object was 100% correct. This
+looked exactly like the real bug this task was fixing. Only after tracing
+`artifact.lineage`/`artifact.content` at every step and finding them intact
+right up until the final `escapeHtml()` call did the harness bug become
+obvious.
+
+**How to apply:** any time you build a fake DOM to validate `frontend/app.js`
+logic beyond what `frontend/test_graph_console_smoke.js`'s `makeFakeDiv()`
+already covers, either reuse that file's `makeFakeDiv()` verbatim or give your
+own stub a `textContent` setter that HTML-escapes (`&`, `<`, `>`, `"`) into
+the same backing store `innerHTML` reads from. If a simulated preview/content
+render comes back suspiciously blank while every value up to the last
+`escapeHtml()`/DOM-write call traces correctly, suspect the harness's fake DOM
+before suspecting app.js.
 # Graph Engineering 系列对照笔记——待确认事项清单
-**日期**: 2026-08-04
+**日期**: 2026-08-04（2026-08-05 更新：A/B/D/E/F/G 已确认方向，C 已确认暂不做）
 **性质**: 从三份对照笔记里提取出的全部"待讨论的开放问题"，去重合并后按主题整理，供逐条确认方案。每条确认后会展开成独立的需求文档（参考 `docs/work-graph-parallel-execution-requirements.md` 的产出方式），本文件本身只做索引和现状追踪，不写详细方案。
 **来源文档**：
 - `docs/reference/graph-engineering-1000-agents-5-steps.diff-with-graphlemon.md`（简称"5 步版对照"）
@@ -22,94 +22,122 @@
 ## A. 架构文档要不要正式采用"工作图 / 角色图"命名
-**状态**：🔲 待确认
+**状态**：✅ 已确认——两组术语等价，不是新概念
 **来源**：5 步版对照 §4 开放问题 3 + 综述版对照 §8 开放问题 1（同一件事，两份笔记从不同角度各自提出）
 **背景**：综述版文章提出一条治理红线——"工作图"（任务怎么拆怎么合，可以快变）vs "角色图"（谁有权改什么，必须慢变可审计）。这条边界跟 graphlemon 现有的 Org Graph（人工固定设计，架构变更需人工评审）/ Work Graph（每次任务动态生成）边界几乎是同一件事的两种命名。5 步版对照笔记是从"什么时候不该用 Graph"的角度独立推出同一条边界的。
-**需要确认的问题**：是否要把 `docs/graphlemon_architecture.md` 里"Org Graph 固定 / Work Graph 动态"的表述，正式替换或补强为综述版这套"工作图 / 角色图"命名？这是纯文档措辞层面的决策，不涉及代码改动。
+**确认结果（2026-08-05）**：`工作图` 是 `Work Graph` 的字面翻译，graphlemon 本来就这么叫；`角色图` 不是 `Org Graph` 的字面翻译，但语义完全对得上——Org Graph 本来就是"角色（Planner/Coder/Validator）之间固定的组织关系图"，`角色图` 是更准确的中文释义，不是新造的概念。两组术语直接画等号：**Work Graph ≡ 工作图，Org Graph ≡ 角色图**。
+
+**待办**：在 `docs/graphlemon_architecture.md` §2 术语表或 §3 整体架构处补一句显式对应说明（"Org Graph 即角色图、Work Graph 即工作图"），引用综述版文章的治理红线原文作为设计依据。纯文档改动，不涉及代码，可以随手做掉。
 ---
 ## B. loop-until-dry 要不要在 Validator 落地
-**状态**：🔲 待确认
+**状态**：✅ 已确认方向——做成 Validator 的一个 Skill
 **来源**：5 步版对照 §4 开放问题 1
 **背景**：Org-level Loop 目前固定 3 轮上限（`docs/sdd/04-P-流程与状态流转.md` 已标注这是"未来优化候选"）。14 步版对照进一步发现：这不只是优先级问题——`work_graph_orchestrate.py::topological_order` 对有环的 `graph_manifest` 直接报错，Work Graph 被设计成严格 DAG，图内根本不支持回路，要支持 loop-until-dry 需要动执行模型本身，不是加一个判断逻辑那么简单。
-**需要确认的问题**：这条要不要立项？如果要，是在 Org-level Loop 这个更粗的粒度上做（比如把"3 轮固定"换成"连续 K 轮无新 bug 才停"，不涉及 Work Graph 内部执行模型），还是真的要改到 Work Graph 内部支持图内回路（工作量大得多）？
+**确认结果（2026-08-05）**：不改 Work Graph 执行模型本身（不引入图内回路）。做成一个独立的 Skill（例如 `validate-until-dry` 之类），把"连续 K 轮无新发现才停止、去重比对全部见过的而非仅已确认的"这套收敛逻辑封装成 Validator 可调用的方法论/工具，并且要求 `.claude/agents/validator.md` 在跑到"未知规模缺陷扫描"这类场景时记得调用它——落地方式是 Skill + Agent 定义引用，不是改 Graph Engine 底层。
+
+**待办**：写需求文档，明确这个 Skill 的触发场景（哪些任务算"未知规模扫描"）、K 值默认多少、和现有 `root_cause_trace`/Org-level Loop 3 轮上限的关系（互不冲突：3 轮上限管的是 Org Graph 层 Validator→Planner 回退次数，这个 Skill 管的是 Validator 自己 Work Graph 内部一次验证过程要扫多少轮）。
 ---
 ## C. 按节点分层选模型——策略归属
-**状态**：🔲 待确认
+**状态**：⛔ 已确认暂不做
 **来源**：5 步版对照 §4 开放问题 2 + 14 步版对照 §1 表格第 12 行 / §3 开放问题 3
 **背景**：`agent_profile.py` 里 Planner/Coder/Validator 三个 Org Agent 目前全部固定 `claude-sonnet-5`。14 步版对照进一步发现：Work Graph 层的管线其实已经打通了一半——`_render_node_script` 支持往生成的单节点脚本里塞 `model` 参数，`run_fn(cwd, model=None)` 也留了口子，但没有任何调用方真正传入非 None 的值，`graph_manifest` 的节点结构里也没有 `model` 字段。基础设施就位，缺的是"谁来决定每个节点该用哪个模型"这层策略。
-**需要确认的问题**：
-1. Org Graph 三节点（Planner/Coder/Validator）要不要差异化选型？
-2. Work Graph 内部节点的模型策略该由谁定——Planning Skill 生成 `graph_manifest` 时就给每个节点标注推荐模型，还是在 `run_graph()` 里按 `org_node`/`artifact_type` 写一张静态映射表？
+**确认结果（2026-08-05）**：暂时不做。`_render_node_script` 的 `model` 参数保留现状（存在但不接线），Org Graph 三节点继续统一用 `claude-sonnet-5`。如果后续 G（并行执行）上线后节点数变多、成本变成真实痛点，再重新评估。
 ---
 ## D. Time-travel 调试要不要立项
-**状态**：🔲 待确认
+**状态**：✅ 已确认立项
 **来源**：综述版对照 §6
 **背景**：LangGraph 的 checkpointer 支持回到任意历史检查点重放/分叉。graphlemon 目前的容错（部分节点失败保留已成功节点输出）、人在回路（Start/Pause/Stop）、记忆（`.claude/agent-memory/`）都已具备，唯独"回到某个历史节点重新分叉执行"没有，现状是"用 git 历史 + 手动重跑"。
-**需要确认的问题**：这条要不要立项，还是维持现状，等真正遇到大规模 Work Graph 调试痛点（比如「Work Graph 节点并行执行」上线后图变复杂了）再评估？倾向于暂不立项，但需要你确认。
+**确认结果（2026-08-05）**：立项。
+
+**待办**：写需求文档。需要先定义清楚几个问题再展开：
+- "分叉重放"具体指什么粒度——回到某个 `work_node_execution` 之前，用新的输入/prompt 重新执行该节点及其下游，产出一条平行的执行分支？
+- 分叉出来的新分支和原分支在数据模型上怎么共存（`work_graph_run`/`work_node_execution` 现有 schema 需不需要扩展"parent_run_id"之类的字段）？
+- 和 G（并行执行）、控制台的关系——分叉调试大概率需要在控制台里可视化操作，属于第 13 节人机交互控制台的能力扩展，需要跟现有 v_task_detail 等页面的设计对齐。
 ---
-## E. Planning Skill 提示词强化——识别可并行节点
+## E. Planning Skill 提示词强化——识别可并行节点 + 通用 Work Graph 设计能力
-**状态**：🔲 待确认
+**状态**：✅ 已确认，且范围比原开放问题更大
 **来源**：综述版对照 §7 开放问题 3 + 14 步版对照 §3 开放问题 2（同一主题：让 Planning 阶段更早识别并行机会）
 **背景**：`work_graph_plan.py` 里 Planning Skill 的 prompt（约在 `work_graph_plan.py:67` 附近）目前只要求"一个 artifact_type 一个节点"，没有引导 Claude 识别哪些节点互不依赖。目前观察到的真实 `graph_manifest`（如 BRD→PRD→SDD→Benchmark）是纯串行链，架构文档 §6.1 设想的并行候选点从未真正被生成过。
-**需要确认的问题**：要不要把 14 步版"对每个箭头问是否真的有数据流动"的提问方式、以及 Anthropic 官方"并行可分解 / 单一上下文装不下 / 收益覆盖成本"这三条尺子，显式写进 Planning Skill 的 prompt，让它在生成 `graph_manifest` 阶段就标注可并行的节点组？
+**确认结果（2026-08-05）**：提示词强化肯定要做——把"对每个箭头问是否真的有数据流动"的提问方式、以及"并行可分解 / 单一上下文装不下 / 收益覆盖成本"这三条尺子写进 Planning 相关 prompt。**但范围比原开放问题更大**：不能只强化 Planner 自己写 BRD/PRD/SDD/Benchmark 那条链的 prompt——架构文档 §5 本来就说"每个 Org Agent 拥有一个 Planning Skill"（Coder 和 Validator 各自也要规划自己的 Work Graph），"如何识别 fan-out/fan-in、设计一张动态 Work Graph"这套方法论应该是**跨 Org Agent 通用**的能力，而不是分别在 Planner/Coder/Validator 三份 Planning Skill 里各写一遍。用户原话："planner agent 里面要有多个 skill，不仅仅是 brd prd sdd benchmark 还有给其他 org graph 的 node 节点的 agent 做各种动态 work graph 的设计"。
+
+**待办**：写需求文档，需要明确：
+- 这套"动态 Work Graph 设计方法论"要不要抽成一个独立的、三个 Org Agent 共用的 Skill（类似现在 `skills/` 目录下已有的 `write-brd`/`write-prd` 等，新增一个例如 `design-dynamic-work-graph`），还是分别内嵌进各自的 Planning 环节？
+- Planner 除了 BRD/PRD/SDD/Benchmark 这条主链的 skill 外，还需要哪些新 skill——用户提到"给其他 org graph 的 node 节点的 agent 做各种动态 work graph 的设计"，这暗示 Planner 可能要承担"帮 Coder/Validator 设计他们各自 Work Graph 结构"的角色，这跟架构文档 §5"每个 Org Agent 自己的 Planning Skill 各自生成自己的 Work Graph"的原有设计是否冲突，需要先对齐。
+- 和 F（三视角评审团做成 fan-out 图）、G（并行执行）的衔接——这个 Skill 生成的 graph_manifest 里，fan-out 的节点组要用什么标记方式，让 G 的执行引擎能识别出"这些节点可以并发"。
-**依赖关系**：这条和「G. Work Graph 节点并行执行」是互补的——G 解决"执行层能不能并发跑"，E 解决"规划层会不会生成值得并发的图"。E 做了但 G 没做，并行能力用不上；G 做了但 E 没做，`graph_manifest` 大概率还是纯串行链，G 的能力也没有实际发挥空间。建议两条一起排期，但可以先确认 G（已有需求文档），E 单独讨论。
+**依赖关系**：这条和「G. Work Graph 节点并行执行」是互补的——G 解决"执行层能不能并发跑"，E 解决"规划层会不会生成值得并发的图"。两条需要一起排期,建议先看 G 的需求文档,E 的需求文档要在 G 确认的数据结构（`graph_manifest` 里怎么表达"这组节点可并行"）基础上写,避免两边字段对不上。
 ---
 ## F. 三视角评审团机制要不要推广到其他验证点
-**状态**：🔲 待确认
+**状态**：✅ 已确认，且明确了实现方式
 **来源**：综述版对照 §7 开放问题 4 + 14 步版对照 §3 开放问题 4（同一主题）
 **背景**：`root_cause_trace.judge_root_cause`（正确性/需求完整性/Skill 缺陷三视角，≥2/3 一致才定案，否则升级人工）目前只服务于 Validator 的 `test_failed` 根因溯源场景。`run_graph()` 自身的 `verify_fn` 是单一验证器 + 失败重试一次，没有多视角/对抗式/评审团这类"重打法"。综述版文章把这类重仓验证归为"高风险场景才用"，暗示应该按风险分级选验证强度，而不是所有节点统一同一套。
-**需要确认的问题**：要不要把三视角评审团模式也下沉到 `verify_fn` 里，作为高风险节点（比如 SDD、代码变更）的可选验证强度？如果要，"高风险"的判定标准是什么（节点类型固定标注，还是运行时动态判断）？
+**确认结果（2026-08-05）**：要做，而且明确了实现方式——**不是**继续用现在 `root_cause_trace.judge_root_cause` 那种 Python 层直接顺序调用三个 `perspective_fn` 的写法，而是把三视角评审团**做成一张真正的 Work Graph fan-out/fan-in 菱形拓扑**：fan-out 出 N 个独立的验证节点（每个节点是一次独立的 `claude -p` 调用，带自己的视角提示词），fan-in 节点做投票/汇总。用户原话："三视角评审团可以做，做成 work graph 的 fan out 图来实现吧"。
+
+**待办**：写需求文档。这条**强依赖 G（并行执行）**——评审团的 fan-out 节点如果还是串行跑，就丢失了"多视角同时判断"的时间收益（现在 `judge_root_cause` 本来就是纯函数式顺序调用，改成 Work Graph fan-out 如果不配合并行执行，反而更慢）。需要确认：
+- 现有 `root_cause_trace.judge_root_cause` 要不要保留作为"轻量级/无需 worktree/纯 Python 场景"的备选实现，还是完全被 Work Graph fan-out 版本取代？
+- 哪些验证点要升级成这种 fan-out 评审团（SDD 审核？代码变更审核？）——"高风险"判定标准怎么定。
 ---
 ## G. Work Graph 节点并行执行（Python 线程池方案）
-**状态**：🟡 已产出需求文档，待评审 → 详见 `docs/work-graph-parallel-execution-requirements.md`
+**状态**：✅ 已确认，标记为核心优先级 → 需求文档见 `docs/work-graph-parallel-execution-requirements.md`
 **来源**：14 步版对照 §3 开放问题 1
-**背景**：`run_graph()` 目前严格串行执行所有节点，即使 `graph_manifest` 里的节点互不依赖。已经讨论过按拓扑层分批 + 线程池并发的方案，核心风险（SQLite 并发写入、worktree 创建竞态、配额错误处理）都已识别，且发现 `backend_server.py` 里已有可复用的"共享连接 + `threading.Lock()`"先例。已产出完整需求文档（目标/非目标/功能需求/验收标准/风险/开放问题），可以直接进入评审。
+**背景**：`run_graph()` 目前严格串行执行所有节点，即使 `graph_manifest` 里的节点互不依赖。已经讨论过按拓扑层分批 + 线程池并发的方案，核心风险（SQLite 并发写入、worktree 创建竞态、配额错误处理）都已识别，且发现 `backend_server.py` 里已有可复用的"共享连接 + `threading.Lock()`"先例。已产出完整需求文档（目标/非目标/功能需求/验收标准/风险/开放问题）。
+
+**确认结果（2026-08-05）**：确认要做，用户强调"这个很核心"。触发规则明确为：**只要 Work Graph 规划了 fan-out/fan-in 的并行节点，节点触发时就应该并行执行**——这跟需求文档 FR-1/FR-2 已经写的内容一致，不需要改需求文档的功能需求本身，只需要在文档里把这句话作为明确的验收口径固化下来。
-**需要确认的问题**：这份需求文档本身要不要按现在的范围继续往设计阶段走？还是需要先调整需求文档里的某些点？
+**待办**：进入详细设计阶段（`topological_layers()` 的具体实现、线程池调度器接口、锁的粒度），需求文档里第 8 节列的开放问题需要在设计阶段逐一敲定。这是 E、F 两条的前置依赖，建议优先推进。
 ---
-## 建议的确认顺序
+## 确认结果汇总（2026-08-05）
+
+| 项 | 结果 | 后续动作 |
+|---|---|---|
+| A | ✅ 确认，两组术语等价 | 待办：架构文档补一句对应说明（可直接做，无需求文档） |
+| B | ✅ 确认，做成 Validator 的 Skill | 待办：写需求文档 |
+| C | ⛔ 暂不做 | 无 |
+| D | ✅ 确认立项 | 待办：写需求文档 |
+| E | ✅ 确认，范围扩大为跨 Org Agent 的通用 Work Graph 设计能力 | 待办：写需求文档（依赖 G 的数据结构先定） |
+| F | ✅ 确认，用 Work Graph fan-out/fan-in 实现 | 待办：写需求文档（强依赖 G） |
+| G | ✅ 确认，核心优先级 | 需求文档已就绪，进入详细设计阶段，是 E/F 的前置依赖 |
-G 已经有现成的需求文档，最接近可以推进的状态，建议先确认。E 和 G 强相关（不改 Planning Skill，G 做出来的并行能力可能用不上真实的并行图），可以放在 G 之后一起看。A（纯文档命名）、B、C、D、F 相对独立，可以任意顺序讨论。
+**建议的推进顺序**：G 先进入详细设计（E、F 都依赖它的并行执行能力和数据结构），A 可以随手做掉（纯文档改动，不占用设计精力）。B、D 相对独立，可以在 G 设计的同时并行写需求文档。E、F 的需求文档建议等 G 的详细设计里"`graph_manifest` 怎么表达可并行节点组"这个数据结构定下来之后再写，避免字段对不上要返工。
-你想先确认哪一条？
+下一步要我先做哪一件——是把 G 推进到详细设计，还是先把 B/D 的需求文档写掉，或者先去把 A 的架构文档措辞补上？
 # Work Graph 节点并行执行——需求文档
-**日期**: 2026-08-04
+**日期**: 2026-08-04（2026-08-05 更新：已确认，标记为核心优先级，进入详细设计阶段）
 **性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。回应对 `docs/reference/Graph Engineering with Claude_ 14-Step roadmap from 0 to graph architect (Full Course).diff-with-graphlemon.md` 开放问题第 1 条的讨论——"现在的每节点独立子进程设计，断点续跑收益是否值得放弃 fan-out 并行？能否两者兼得？"。详细设计（SDD 层面：`topological_layers()` 的具体实现、线程池调度器接口、锁的粒度）留到需求确认后单独产出。
-**状态**: 草案，待评审。
+**状态**: ✅ 已确认。验收口径固化为一句话（2026-08-05 用户原话）："只要 Work Graph 规划了 fan-out、fan-in 的并行节点，就可以在节点触发的时候并行执行"——这与本文档 FR-1/FR-2 一致，无需改动功能需求本身。下一步进入详细设计阶段，见 `docs/todo/graph-engineering-open-items.md` 条目 G。
 ## 1. 背景